Date: 2016-03-29T14:59:33+00:00

Actual source code: slepcpep.h
slepc-3.6.3 2016-03-29
Report Typos and Errors

      1: /*
      2:    User interface for SLEPc's polynomial eigenvalue solvers.

      4:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      5:    SLEPc - Scalable Library for Eigenvalue Problem Computations
      6:    Copyright (c) 2002-2015, Universitat Politecnica de Valencia, Spain

      8:    This file is part of SLEPc.

     10:    SLEPc is free software: you can redistribute it and/or modify it under  the
     11:    terms of version 3 of the GNU Lesser General Public License as published by
     12:    the Free Software Foundation.

     14:    SLEPc  is  distributed in the hope that it will be useful, but WITHOUT  ANY
     15:    WARRANTY;  without even the implied warranty of MERCHANTABILITY or  FITNESS
     16:    FOR  A  PARTICULAR PURPOSE. See the GNU Lesser General Public  License  for
     17:    more details.

     19:    You  should have received a copy of the GNU Lesser General  Public  License
     20:    along with SLEPc. If not, see <http://www.gnu.org/licenses/>.
     21:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
     22: */

     26: #include <slepceps.h>

     28: PETSC_EXTERN PetscErrorCode PEPInitializePackage(void);

     30: /*S
     31:      PEP - Abstract SLEPc object that manages all the polynomial eigenvalue
     32:      problem solvers.

     34:    Level: beginner

     36: .seealso:  PEPCreate()
     37: S*/
     38: typedef struct _p_PEP* PEP;

     40: /*J
     41:     PEPType - String with the name of a polynomial eigensolver

     43:    Level: beginner

     45: .seealso: PEPSetType(), PEP
     46: J*/
     47: typedef const char* PEPType;
     48: #define PEPLINEAR    "linear"
     49: #define PEPQARNOLDI  "qarnoldi"
     50: #define PEPTOAR      "toar"
     51: #define PEPSTOAR     "stoar"
     52: #define PEPJD        "jd"

     54: /* Logging support */
     55: PETSC_EXTERN PetscClassId PEP_CLASSID;

     57: /*E
     58:     PEPProblemType - Determines the type of the polynomial eigenproblem

     60:     Level: intermediate

     62: .seealso: PEPSetProblemType(), PEPGetProblemType()
     63: E*/
     64: typedef enum { PEP_GENERAL=1,
     65:                PEP_HERMITIAN,   /* All A_i  Hermitian */
     66:                PEP_GYROSCOPIC   /* QEP with M, K  Hermitian, M>0, C skew-Hermitian */
     67:              } PEPProblemType;

     69: /*E
     70:     PEPWhich - Determines which part of the spectrum is requested

     72:     Level: intermediate

     74: .seealso: PEPSetWhichEigenpairs(), PEPGetWhichEigenpairs()
     75: E*/
     76: typedef enum { PEP_LARGEST_MAGNITUDE=1,
     77:                PEP_SMALLEST_MAGNITUDE,
     78:                PEP_LARGEST_REAL,
     79:                PEP_SMALLEST_REAL,
     80:                PEP_LARGEST_IMAGINARY,
     81:                PEP_SMALLEST_IMAGINARY,
     82:                PEP_TARGET_MAGNITUDE,
     83:                PEP_TARGET_REAL,
     84:                PEP_TARGET_IMAGINARY,
     85:                PEP_WHICH_USER } PEPWhich;

     87: /*E
     88:     PEPBasis - The type of polynomial basis used to represent the polynomial
     89:     eigenproblem

     91:     Level: intermediate

     93: .seealso: PEPSetBasis()
     94: E*/
     95: typedef enum { PEP_BASIS_MONOMIAL,
     96:                PEP_BASIS_CHEBYSHEV1,
     97:                PEP_BASIS_CHEBYSHEV2,
     98:                PEP_BASIS_LEGENDRE,
     99:                PEP_BASIS_LAGUERRE,
    100:                PEP_BASIS_HERMITE } PEPBasis;
    101: PETSC_EXTERN const char *PEPBasisTypes[];

    103: /*E
    104:     PEPScale - The scaling strategy

    106:     Level: intermediate

    108: .seealso: PEPSetScale()
    109: E*/
    110: typedef enum { PEP_SCALE_NONE,
    111:                PEP_SCALE_SCALAR,
    112:                PEP_SCALE_DIAGONAL,
    113:                PEP_SCALE_BOTH } PEPScale;
    114: PETSC_EXTERN const char *PEPScaleTypes[];

    116: /*E
    117:     PEPRefine - The refinement type

    119:     Level: intermediate

    121: .seealso: PEPSetRefine()
    122: E*/
    123: typedef enum { PEP_REFINE_NONE,
    124:                PEP_REFINE_SIMPLE,
    125:                PEP_REFINE_MULTIPLE } PEPRefine;
    126: PETSC_EXTERN const char *PEPRefineTypes[];

    128: /*E
    129:     PEPExtract - The extraction type

    131:     Level: intermediate

    133: .seealso: PEPSetExtract()
    134: E*/
    135: typedef enum { PEP_EXTRACT_NONE=1,
    136:                PEP_EXTRACT_NORM,
    137:                PEP_EXTRACT_RESIDUAL,
    138:                PEP_EXTRACT_STRUCTURED } PEPExtract;
    139: PETSC_EXTERN const char *PEPExtractTypes[];

    141: /*E
    142:     PEPErrorType - The error type used to assess accuracy of computed solutions

    144:     Level: intermediate

    146: .seealso: PEPComputeError()
    147: E*/
    148: typedef enum { PEP_ERROR_ABSOLUTE,
    149:                PEP_ERROR_RELATIVE,
    150:                PEP_ERROR_BACKWARD } PEPErrorType;
    151: PETSC_EXTERN const char *PEPErrorTypes[];

    153: /*E
    154:     PEPConv - Determines the convergence test

    156:     Level: intermediate

    158: .seealso: PEPSetConvergenceTest(), PEPSetConvergenceTestFunction()
    159: E*/
    160: typedef enum { PEP_CONV_ABS,
    161:                PEP_CONV_EIG,
    162:                PEP_CONV_LINEAR,
    163:                PEP_CONV_NORM,
    164:                PEP_CONV_USER } PEPConv;

    166: PETSC_EXTERN PetscErrorCode PEPCreate(MPI_Comm,PEP*);
    167: PETSC_EXTERN PetscErrorCode PEPDestroy(PEP*);
    168: PETSC_EXTERN PetscErrorCode PEPReset(PEP);
    169: PETSC_EXTERN PetscErrorCode PEPSetType(PEP,PEPType);
    170: PETSC_EXTERN PetscErrorCode PEPGetType(PEP,PEPType*);
    171: PETSC_EXTERN PetscErrorCode PEPSetProblemType(PEP,PEPProblemType);
    172: PETSC_EXTERN PetscErrorCode PEPGetProblemType(PEP,PEPProblemType*);
    173: PETSC_EXTERN PetscErrorCode PEPSetOperators(PEP,PetscInt,Mat[]);
    174: PETSC_EXTERN PetscErrorCode PEPGetOperators(PEP,PetscInt,Mat*);
    175: PETSC_EXTERN PetscErrorCode PEPGetNumMatrices(PEP,PetscInt*);
    176: PETSC_EXTERN PetscErrorCode PEPSetTarget(PEP,PetscScalar);
    177: PETSC_EXTERN PetscErrorCode PEPGetTarget(PEP,PetscScalar*);
    178: PETSC_EXTERN PetscErrorCode PEPSetFromOptions(PEP);
    179: PETSC_EXTERN PetscErrorCode PEPSetUp(PEP);
    180: PETSC_EXTERN PetscErrorCode PEPSolve(PEP);
    181: PETSC_EXTERN PetscErrorCode PEPView(PEP,PetscViewer);
    182: PETSC_STATIC_INLINE PetscErrorCode PEPViewFromOptions(PEP pep,PetscObject obj,const char name[]) {return PetscObjectViewFromOptions((PetscObject)pep,obj,name);}
    183: PETSC_EXTERN PetscErrorCode PEPErrorView(PEP,PEPErrorType,PetscViewer);
    184: PETSC_DEPRECATED("Use PEPErrorView()") PETSC_STATIC_INLINE PetscErrorCode PEPPrintSolution(PEP pep,PetscViewer v) {return PEPErrorView(pep,PEP_ERROR_BACKWARD,v);}
    185: PETSC_EXTERN PetscErrorCode PEPErrorViewFromOptions(PEP);
    186: PETSC_EXTERN PetscErrorCode PEPReasonView(PEP,PetscViewer);
    187: PETSC_EXTERN PetscErrorCode PEPReasonViewFromOptions(PEP);
    188: PETSC_EXTERN PetscErrorCode PEPValuesView(PEP,PetscViewer);
    189: PETSC_EXTERN PetscErrorCode PEPValuesViewFromOptions(PEP);
    190: PETSC_EXTERN PetscErrorCode PEPVectorsView(PEP,PetscViewer);
    191: PETSC_EXTERN PetscErrorCode PEPVectorsViewFromOptions(PEP);
    192: PETSC_EXTERN PetscErrorCode PEPSetBV(PEP,BV);
    193: PETSC_EXTERN PetscErrorCode PEPGetBV(PEP,BV*);
    194: PETSC_EXTERN PetscErrorCode PEPSetRG(PEP,RG);
    195: PETSC_EXTERN PetscErrorCode PEPGetRG(PEP,RG*);
    196: PETSC_EXTERN PetscErrorCode PEPSetDS(PEP,DS);
    197: PETSC_EXTERN PetscErrorCode PEPGetDS(PEP,DS*);
    198: PETSC_EXTERN PetscErrorCode PEPSetST(PEP,ST);
    199: PETSC_EXTERN PetscErrorCode PEPGetST(PEP,ST*);
    200: PETSC_EXTERN PetscErrorCode PEPRefineGetKSP(PEP,KSP*);

    202: PETSC_EXTERN PetscErrorCode PEPSetTolerances(PEP,PetscReal,PetscInt);
    203: PETSC_EXTERN PetscErrorCode PEPGetTolerances(PEP,PetscReal*,PetscInt*);
    204: PETSC_EXTERN PetscErrorCode PEPSetConvergenceTestFunction(PEP,PetscErrorCode (*)(PEP,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*),void*,PetscErrorCode (*)(void*));
    205: PETSC_EXTERN PetscErrorCode PEPSetConvergenceTest(PEP,PEPConv);
    206: PETSC_EXTERN PetscErrorCode PEPGetConvergenceTest(PEP,PEPConv*);
    207: PETSC_EXTERN PetscErrorCode PEPConvergedEigRelative(PEP,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);
    208: PETSC_EXTERN PetscErrorCode PEPConvergedLinear(PEP,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);
    209: PETSC_EXTERN PetscErrorCode PEPConvergedNorm(PEP,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);
    210: PETSC_EXTERN PetscErrorCode PEPConvergedAbsolute(PEP,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);
    211: PETSC_EXTERN PetscErrorCode PEPSetDimensions(PEP,PetscInt,PetscInt,PetscInt);
    212: PETSC_EXTERN PetscErrorCode PEPGetDimensions(PEP,PetscInt*,PetscInt*,PetscInt*);
    213: PETSC_EXTERN PetscErrorCode PEPSetScale(PEP,PEPScale,PetscReal,Vec,Vec,PetscInt,PetscReal);
    214: PETSC_EXTERN PetscErrorCode PEPGetScale(PEP,PEPScale*,PetscReal*,Vec*,Vec*,PetscInt*,PetscReal*);
    215: PETSC_EXTERN PetscErrorCode PEPSetRefine(PEP,PEPRefine,PetscInt,PetscReal,PetscInt,PetscBool);
    216: PETSC_EXTERN PetscErrorCode PEPGetRefine(PEP,PEPRefine*,PetscInt*,PetscReal*,PetscInt*,PetscBool*);
    217: PETSC_EXTERN PetscErrorCode PEPSetExtract(PEP,PEPExtract);
    218: PETSC_EXTERN PetscErrorCode PEPGetExtract(PEP,PEPExtract*);
    219: PETSC_EXTERN PetscErrorCode PEPSetBasis(PEP,PEPBasis);
    220: PETSC_EXTERN PetscErrorCode PEPGetBasis(PEP,PEPBasis*);

    222: PETSC_EXTERN PetscErrorCode PEPGetConverged(PEP,PetscInt*);
    223: PETSC_EXTERN PetscErrorCode PEPGetEigenpair(PEP,PetscInt,PetscScalar*,PetscScalar*,Vec,Vec);
    224: PETSC_EXTERN PetscErrorCode PEPComputeError(PEP,PetscInt,PEPErrorType,PetscReal*);
    225: PETSC_DEPRECATED("Use PEPComputeError()") PETSC_STATIC_INLINE PetscErrorCode PEPComputeRelativeError(PEP pep,PetscInt i,PetscReal *r) {return PEPComputeError(pep,i,PEP_ERROR_BACKWARD,r);}
    226: PETSC_DEPRECATED("Use PEPComputeError() with PEP_ERROR_ABSOLUTE") PETSC_STATIC_INLINE PetscErrorCode PEPComputeResidualNorm(PEP pep,PetscInt i,PetscReal *r) {return PEPComputeError(pep,i,PEP_ERROR_ABSOLUTE,r);}
    227: PETSC_EXTERN PetscErrorCode PEPGetErrorEstimate(PEP,PetscInt,PetscReal*);

    229: PETSC_EXTERN PetscErrorCode PEPMonitor(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt);
    230: PETSC_EXTERN PetscErrorCode PEPMonitorSet(PEP,PetscErrorCode (*)(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*),void*,PetscErrorCode (*)(void**));
    231: PETSC_EXTERN PetscErrorCode PEPMonitorCancel(PEP);
    232: PETSC_EXTERN PetscErrorCode PEPGetMonitorContext(PEP,void **);
    233: PETSC_EXTERN PetscErrorCode PEPGetIterationNumber(PEP,PetscInt*);

    235: PETSC_EXTERN PetscErrorCode PEPSetInitialSpace(PEP,PetscInt,Vec*);
    236: PETSC_EXTERN PetscErrorCode PEPSetWhichEigenpairs(PEP,PEPWhich);
    237: PETSC_EXTERN PetscErrorCode PEPGetWhichEigenpairs(PEP,PEPWhich*);
    238: PETSC_EXTERN PetscErrorCode PEPSetEigenvalueComparison(PEP,PetscErrorCode (*func)(PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*),void*);

    240: PETSC_EXTERN PetscErrorCode PEPMonitorAll(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
    241: PETSC_EXTERN PetscErrorCode PEPMonitorFirst(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
    242: PETSC_EXTERN PetscErrorCode PEPMonitorConverged(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
    243: PETSC_EXTERN PetscErrorCode PEPMonitorLG(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);
    244: PETSC_EXTERN PetscErrorCode PEPMonitorLGAll(PEP,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);

    246: PETSC_EXTERN PetscErrorCode PEPSetTrackAll(PEP,PetscBool);
    247: PETSC_EXTERN PetscErrorCode PEPGetTrackAll(PEP,PetscBool*);

    249: PETSC_EXTERN PetscErrorCode PEPSetOptionsPrefix(PEP,const char*);
    250: PETSC_EXTERN PetscErrorCode PEPAppendOptionsPrefix(PEP,const char*);
    251: PETSC_EXTERN PetscErrorCode PEPGetOptionsPrefix(PEP,const char*[]);

    253: /*E
    254:     PEPConvergedReason - Reason an eigensolver was said to
    255:          have converged or diverged

    257:     Level: intermediate

    259: .seealso: PEPSolve(), PEPGetConvergedReason(), PEPSetTolerances()
    260: E*/
    261: typedef enum {/* converged */
    262:               PEP_CONVERGED_TOL                =  2,
    263:               /* diverged */
    264:               PEP_DIVERGED_ITS                 = -3,
    265:               PEP_DIVERGED_BREAKDOWN           = -4,
    266:               PEP_DIVERGED_SYMMETRY_LOST       = -5,
    267:               PEP_CONVERGED_ITERATING          =  0} PEPConvergedReason;
    268: PETSC_EXTERN const char *const*PEPConvergedReasons;

    270: PETSC_EXTERN PetscErrorCode PEPGetConvergedReason(PEP,PEPConvergedReason *);

    272: PETSC_EXTERN PetscFunctionList PEPList;
    273: PETSC_EXTERN PetscErrorCode PEPRegister(const char[],PetscErrorCode(*)(PEP));

    275: PETSC_EXTERN PetscErrorCode PEPSetWorkVecs(PEP,PetscInt);
    276: PETSC_EXTERN PetscErrorCode PEPAllocateSolution(PEP,PetscInt);

    278: /* --------- options specific to particular eigensolvers -------- */

    280: PETSC_EXTERN PetscErrorCode PEPLinearSetCompanionForm(PEP,PetscInt);
    281: PETSC_EXTERN PetscErrorCode PEPLinearGetCompanionForm(PEP,PetscInt*);
    282: PETSC_EXTERN PetscErrorCode PEPLinearSetExplicitMatrix(PEP,PetscBool);
    283: PETSC_EXTERN PetscErrorCode PEPLinearGetExplicitMatrix(PEP,PetscBool*);
    284: PETSC_EXTERN PetscErrorCode PEPLinearSetEPS(PEP,EPS);
    285: PETSC_EXTERN PetscErrorCode PEPLinearGetEPS(PEP,EPS*);

    287: PETSC_EXTERN PetscErrorCode PEPQArnoldiSetRestart(PEP,PetscReal);
    288: PETSC_EXTERN PetscErrorCode PEPQArnoldiGetRestart(PEP,PetscReal*);
    289: PETSC_EXTERN PetscErrorCode PEPQArnoldiSetLocking(PEP,PetscBool);
    290: PETSC_EXTERN PetscErrorCode PEPQArnoldiGetLocking(PEP,PetscBool*);

    292: PETSC_EXTERN PetscErrorCode PEPTOARSetRestart(PEP,PetscReal);
    293: PETSC_EXTERN PetscErrorCode PEPTOARGetRestart(PEP,PetscReal*);
    294: PETSC_EXTERN PetscErrorCode PEPTOARSetLocking(PEP,PetscBool);
    295: PETSC_EXTERN PetscErrorCode PEPTOARGetLocking(PEP,PetscBool*);

    297: PETSC_EXTERN PetscErrorCode PEPSTOARSetLocking(PEP,PetscBool);
    298: PETSC_EXTERN PetscErrorCode PEPSTOARGetLocking(PEP,PetscBool*);

    300: PETSC_EXTERN PetscErrorCode PEPJDSetRestart(PEP,PetscReal);
    301: PETSC_EXTERN PetscErrorCode PEPJDGetRestart(PEP,PetscReal*);
    302: PETSC_EXTERN PetscErrorCode PEPJDSetTolerances(PEP,PetscReal,PetscReal,PetscReal);
    303: PETSC_EXTERN PetscErrorCode PEPJDGetTolerances(PEP,PetscReal*,PetscReal*,PetscReal*);

    305: #endif