Subversion Repositories slepc-dev

/*

   User interface for the SLEPC eigenproblem solvers.

   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

   SLEPc - Scalable Library for Eigenvalue Problem Computations

   Copyright (c) 2002-2010, Universidad Politecnica de Valencia, Spain

   This file is part of SLEPc.

   SLEPc is free software: you can redistribute it and/or modify it under  the

   terms of version 3 of the GNU Lesser General Public License as published by

   the Free Software Foundation.

   SLEPc  is  distributed in the hope that it will be useful, but WITHOUT  ANY

   WARRANTY;  without even the implied warranty of MERCHANTABILITY or  FITNESS

   FOR  A  PARTICULAR PURPOSE. See the GNU Lesser General Public  License  for

   more details.

   You  should have received a copy of the GNU Lesser General  Public  License

   along with SLEPc. If not, see <http://www.gnu.org/licenses/>.

   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

*/

#if !defined(__SLEPCEPS_H)

#define __SLEPCEPS_H

#include "slepcsys.h"

#include "slepcst.h"

#include "slepcip.h"

PETSC_EXTERN_CXX_BEGIN

extern PetscErrorCode EPSInitializePackage(const char[]);

/*S

    EPS - Abstract SLEPc object that manages all the eigenvalue

    problem solvers.

    Level: beginner

.seealso:  EPSCreate(), ST

S*/

typedef struct _p_EPS* EPS;

/*E

    EPSType - String with the name of a SLEPc eigensolver

    Level: beginner

.seealso: EPSSetType(), EPS

E*/

#define EPSType      char*

#define EPSPOWER     "power"

#define EPSSUBSPACE  "subspace"

#define EPSARNOLDI   "arnoldi"

#define EPSLANCZOS   "lanczos"

#define EPSKRYLOVSCHUR "krylovschur"

#define EPSDSITRLANCZOS "dsitrlanczos"

#define EPSGD        "gd"

#define EPSJD        "jd"

#define EPSLAPACK    "lapack"

/* the next ones are interfaces to external libraries */

#define EPSARPACK    "arpack"

#define EPSBLZPACK   "blzpack"

#define EPSTRLAN     "trlan"

#define EPSBLOPEX    "blopex"

#define EPSPRIMME    "primme"

/* Logging support */

extern PetscClassId EPS_CLASSID;

/*E

    EPSProblemType - determines the type of eigenvalue problem

    Level: beginner

.seealso: EPSSetProblemType(), EPSGetProblemType()

E*/

typedef enum { EPS_HEP=1,

               EPS_GHEP,

               EPS_NHEP,

               EPS_GNHEP,

               EPS_PGNHEP,

               EPS_GHIEP } EPSProblemType;

/*E

    EPSExtraction - determines the type of extraction technique employed

    by the eigensolver

    Level: beginner

.seealso: EPSSetExtraction(), EPSGetExtraction()

E*/

typedef enum { EPS_RITZ=1,

               EPS_HARMONIC,

               EPS_HARMONIC_RELATIVE,

               EPS_HARMONIC_RIGHT,

               EPS_HARMONIC_LARGEST,

               EPS_REFINED,

               EPS_REFINED_HARMONIC } EPSExtraction;

/*E

    EPSWhich - determines which part of the spectrum is requested

    Level: intermediate

.seealso: EPSSetWhichEigenpairs(), EPSGetWhichEigenpairs()

E*/

typedef enum { EPS_LARGEST_MAGNITUDE=1,

               EPS_SMALLEST_MAGNITUDE,

               EPS_LARGEST_REAL,

               EPS_SMALLEST_REAL,

               EPS_LARGEST_IMAGINARY,

               EPS_SMALLEST_IMAGINARY,

               EPS_TARGET_MAGNITUDE,

               EPS_TARGET_REAL,

               EPS_TARGET_IMAGINARY,

               EPS_ALL,

               EPS_WHICH_USER } EPSWhich;

/*E

    EPSBalance - the type of balancing used for non-Hermitian problems

    Level: intermediate

.seealso: EPSSetBalance()

E*/

typedef enum { EPS_BALANCE_NONE=1,

               EPS_BALANCE_ONESIDE,

               EPS_BALANCE_TWOSIDE,

               EPS_BALANCE_USER } EPSBalance;

/*E

    EPSConv - determines the convergence test

    Level: intermediate

.seealso: EPSSetConvergenceTest(), EPSSetConvergenceTestFunction()

E*/

typedef enum { EPS_CONV_ABS=1,

               EPS_CONV_EIG,

               EPS_CONV_NORM,

               EPS_CONV_USER } EPSConv;

extern PetscErrorCode EPSCreate(MPI_Comm,EPS *);

extern PetscErrorCode EPSDestroy(EPS*);

extern PetscErrorCode EPSReset(EPS);

extern PetscErrorCode EPSSetType(EPS,const EPSType);

extern PetscErrorCode EPSGetType(EPS,const EPSType*);

extern PetscErrorCode EPSSetProblemType(EPS,EPSProblemType);

extern PetscErrorCode EPSGetProblemType(EPS,EPSProblemType*);

extern PetscErrorCode EPSSetExtraction(EPS,EPSExtraction);

extern PetscErrorCode EPSGetExtraction(EPS,EPSExtraction*);

extern PetscErrorCode EPSSetBalance(EPS,EPSBalance,PetscInt,PetscReal);

extern PetscErrorCode EPSGetBalance(EPS,EPSBalance*,PetscInt*,PetscReal*);

extern PetscErrorCode EPSSetOperators(EPS,Mat,Mat);

extern PetscErrorCode EPSGetOperators(EPS,Mat*,Mat*);

extern PetscErrorCode EPSSetFromOptions(EPS);

extern PetscErrorCode EPSSetUp(EPS);

extern PetscErrorCode EPSSolve(EPS);

extern PetscErrorCode EPSView(EPS,PetscViewer);

extern PetscErrorCode EPSSetTarget(EPS,PetscScalar);

extern PetscErrorCode EPSGetTarget(EPS,PetscScalar*);

extern PetscErrorCode EPSSetInterval(EPS,PetscReal,PetscReal);

extern PetscErrorCode EPSGetInterval(EPS,PetscReal*,PetscReal*);

extern PetscErrorCode EPSSetST(EPS,ST);

extern PetscErrorCode EPSGetST(EPS,ST*);

extern PetscErrorCode EPSSetIP(EPS,IP);

extern PetscErrorCode EPSGetIP(EPS,IP*);

extern PetscErrorCode EPSSetTolerances(EPS,PetscReal,PetscInt);

extern PetscErrorCode EPSGetTolerances(EPS,PetscReal*,PetscInt*);

extern PetscErrorCode EPSSetConvergenceTestFunction(EPS,PetscErrorCode (*)(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*),void*);

extern PetscErrorCode EPSSetConvergenceTest(EPS eps,EPSConv conv);

extern PetscErrorCode EPSGetConvergenceTest(EPS eps,EPSConv *conv);

extern PetscErrorCode EPSEigRelativeConverged(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);

extern PetscErrorCode EPSAbsoluteConverged(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);

extern PetscErrorCode EPSNormRelativeConverged(EPS,PetscScalar,PetscScalar,PetscReal,PetscReal*,void*);

extern PetscErrorCode EPSSetDimensions(EPS,PetscInt,PetscInt,PetscInt);

extern PetscErrorCode EPSGetDimensions(EPS,PetscInt*,PetscInt*,PetscInt*);

extern PetscErrorCode EPSGetConverged(EPS,PetscInt*);

extern PetscErrorCode EPSGetEigenpair(EPS,PetscInt,PetscScalar*,PetscScalar*,Vec,Vec);

extern PetscErrorCode EPSGetEigenvalue(EPS,PetscInt,PetscScalar*,PetscScalar*);

extern PetscErrorCode EPSGetEigenvector(EPS,PetscInt,Vec,Vec);

extern PetscErrorCode EPSGetEigenvectorLeft(EPS,PetscInt,Vec,Vec);

extern PetscErrorCode EPSComputeRelativeError(EPS,PetscInt,PetscReal*);

extern PetscErrorCode EPSComputeRelativeErrorLeft(EPS,PetscInt,PetscReal*);

extern PetscErrorCode EPSComputeResidualNorm(EPS,PetscInt,PetscReal*);

extern PetscErrorCode EPSComputeResidualNormLeft(EPS,PetscInt,PetscReal*);

extern PetscErrorCode EPSGetInvariantSubspace(EPS,Vec*);

extern PetscErrorCode EPSGetInvariantSubspaceLeft(EPS,Vec*);

extern PetscErrorCode EPSGetErrorEstimate(EPS,PetscInt,PetscReal*);

extern PetscErrorCode EPSGetErrorEstimateLeft(EPS,PetscInt,PetscReal*);

extern PetscErrorCode EPSMonitorSet(EPS,PetscErrorCode (*)(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*),void*,PetscErrorCode (*)(void**));

extern PetscErrorCode EPSMonitorCancel(EPS);

extern PetscErrorCode EPSGetMonitorContext(EPS,void **);

extern PetscErrorCode EPSGetIterationNumber(EPS,PetscInt*);

extern PetscErrorCode EPSGetOperationCounters(EPS,PetscInt*,PetscInt*,PetscInt*);

extern PetscErrorCode EPSSetWhichEigenpairs(EPS,EPSWhich);

extern PetscErrorCode EPSGetWhichEigenpairs(EPS,EPSWhich*);

extern PetscErrorCode EPSSetLeftVectorsWanted(EPS,PetscBool);

extern PetscErrorCode EPSGetLeftVectorsWanted(EPS,PetscBool*);

extern PetscErrorCode EPSSetMatrixNorms(EPS,PetscReal,PetscReal,PetscBool);

extern PetscErrorCode EPSGetMatrixNorms(EPS,PetscReal*,PetscReal*,PetscBool*);

extern PetscErrorCode EPSSetTrueResidual(EPS,PetscBool);

extern PetscErrorCode EPSGetTrueResidual(EPS,PetscBool*);

extern PetscErrorCode EPSSetEigenvalueComparison(EPS,PetscErrorCode (*func)(EPS,PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*,void*),void*);

extern PetscErrorCode EPSIsGeneralized(EPS,PetscBool*);

extern PetscErrorCode EPSIsHermitian(EPS,PetscBool*);

extern PetscErrorCode EPSMonitorFirst(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);

extern PetscErrorCode EPSMonitorAll(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);

extern PetscErrorCode EPSMonitorConverged(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);

extern PetscErrorCode EPSMonitorLG(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);

extern PetscErrorCode EPSMonitorLGAll(EPS,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscInt,void*);

extern PetscErrorCode EPSSetTrackAll(EPS,PetscBool);

extern PetscErrorCode EPSGetTrackAll(EPS,PetscBool*);

extern PetscErrorCode EPSSetDeflationSpace(EPS,PetscInt,Vec*);

extern PetscErrorCode EPSRemoveDeflationSpace(EPS);

extern PetscErrorCode EPSSetInitialSpace(EPS,PetscInt,Vec*);

extern PetscErrorCode EPSSetInitialSpaceLeft(EPS,PetscInt,Vec*);

extern PetscErrorCode EPSSetOptionsPrefix(EPS,const char*);

extern PetscErrorCode EPSAppendOptionsPrefix(EPS,const char*);

extern PetscErrorCode EPSGetOptionsPrefix(EPS,const char*[]);

/*E

    EPSConvergedReason - reason an eigensolver was said to

         have converged or diverged

    Level: beginner

.seealso: EPSSolve(), EPSGetConvergedReason(), EPSSetTolerances()

E*/

typedef enum {/* converged */

              EPS_CONVERGED_TOL                =  2,

              /* diverged */

              EPS_DIVERGED_ITS                 = -3,

              EPS_DIVERGED_BREAKDOWN           = -4,

              EPS_CONVERGED_ITERATING          =  0} EPSConvergedReason;

extern PetscErrorCode EPSGetConvergedReason(EPS,EPSConvergedReason *);

extern PetscErrorCode EPSSortEigenvalues(EPS,PetscInt,PetscScalar*,PetscScalar*,PetscInt*);

extern PetscErrorCode EPSSortEigenvaluesReal(EPS,PetscInt,PetscReal*,PetscInt*);

extern PetscErrorCode EPSCompareEigenvalues(EPS,PetscScalar,PetscScalar,PetscScalar,PetscScalar,PetscInt*);

extern PetscErrorCode EPSDenseNHEP(PetscInt,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*);

extern PetscErrorCode EPSDenseGNHEP(PetscInt,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*);

extern PetscErrorCode EPSDenseHEP(PetscInt,PetscScalar*,PetscInt,PetscReal*,PetscScalar*);

extern PetscErrorCode EPSDenseGHEP(PetscInt,PetscScalar*,PetscScalar*,PetscReal*,PetscScalar*);

extern PetscErrorCode EPSDenseHessenberg(PetscInt,PetscInt,PetscScalar*,PetscInt,PetscScalar*);

extern PetscErrorCode EPSDenseSchur(PetscInt,PetscInt,PetscScalar*,PetscInt,PetscScalar*,PetscScalar*,PetscScalar*);

extern PetscErrorCode EPSSortDenseSchur(EPS,PetscInt,PetscInt,PetscScalar*,PetscInt,PetscScalar*,PetscScalar*,PetscScalar*);

extern PetscErrorCode EPSSortDenseSchurGeneralized(EPS,PetscInt,PetscInt,PetscInt,PetscScalar*,PetscScalar*,PetscInt,PetscScalar*,PetscScalar*,PetscScalar*,PetscScalar*);

extern PetscErrorCode EPSDenseTridiagonal(PetscInt,PetscReal*,PetscReal*,PetscReal*,PetscScalar*);

extern PetscErrorCode EPSGetStartVector(EPS,PetscInt,Vec,PetscBool*);

extern PetscErrorCode EPSGetStartVectorLeft(EPS,PetscInt,Vec,PetscBool*);

extern PetscFList EPSList;

extern PetscBool  EPSRegisterAllCalled;

extern PetscErrorCode EPSRegisterAll(const char[]);

extern PetscErrorCode EPSRegisterDestroy(void);

extern PetscErrorCode EPSRegister(const char[],const char[],const char[],PetscErrorCode(*)(EPS));

/*MC

   EPSRegisterDynamic - Adds a method to the eigenproblem solver package.

   Synopsis:

   PetscErrorCode EPSRegisterDynamic(const char *name_solver,const char *path,const char *name_create,PetscErrorCode (*routine_create)(EPS))

   Not Collective

   Input Parameters:

+  name_solver - name of a new user-defined solver

.  path - path (either absolute or relative) the library containing this solver

.  name_create - name of routine to create the solver context

-  routine_create - routine to create the solver context

   Notes:

   EPSRegisterDynamic() may be called multiple times to add several user-defined solvers.

   If dynamic libraries are used, then the fourth input argument (routine_create)

   is ignored.

   Sample usage:

.vb

   EPSRegisterDynamic("my_solver",/home/username/my_lib/lib/libO/solaris/mylib.a,

               "MySolverCreate",MySolverCreate);

.ve

   Then, your solver can be chosen with the procedural interface via

$     EPSSetType(eps,"my_solver")

   or at runtime via the option

$     -eps_type my_solver

   Level: advanced

.seealso: EPSRegisterDestroy(), EPSRegisterAll()

M*/

#if defined(PETSC_USE_DYNAMIC_LIBRARIES)

#define EPSRegisterDynamic(a,b,c,d) EPSRegister(a,b,c,0)

#else

#define EPSRegisterDynamic(a,b,c,d) EPSRegister(a,b,c,d)

#endif

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

/*E

    EPSPowerShiftType - determines the type of shift used in the Power iteration

    Level: advanced

.seealso: EPSPowerSetShiftType(), EPSPowerGetShiftType()

E*/

typedef enum { EPS_POWER_SHIFT_CONSTANT,

               EPS_POWER_SHIFT_RAYLEIGH,

               EPS_POWER_SHIFT_WILKINSON } EPSPowerShiftType;

extern const char *EPSPowerShiftTypes[];

extern PetscErrorCode EPSPowerSetShiftType(EPS,EPSPowerShiftType);

extern PetscErrorCode EPSPowerGetShiftType(EPS,EPSPowerShiftType*);

extern PetscErrorCode EPSArnoldiSetDelayed(EPS,PetscBool);

extern PetscErrorCode EPSArnoldiGetDelayed(EPS,PetscBool*);

/*E

    EPSLanczosReorthogType - determines the type of reorthogonalization

    used in the Lanczos method

    Level: advanced

.seealso: EPSLanczosSetReorthog(), EPSLanczosGetReorthog()

E*/

typedef enum { EPS_LANCZOS_REORTHOG_LOCAL,

               EPS_LANCZOS_REORTHOG_FULL,

               EPS_LANCZOS_REORTHOG_SELECTIVE,

               EPS_LANCZOS_REORTHOG_PERIODIC,

               EPS_LANCZOS_REORTHOG_PARTIAL,

               EPS_LANCZOS_REORTHOG_DELAYED } EPSLanczosReorthogType;

extern const char *EPSLanczosReorthogTypes[];

extern PetscErrorCode EPSLanczosSetReorthog(EPS,EPSLanczosReorthogType);

extern PetscErrorCode EPSLanczosGetReorthog(EPS,EPSLanczosReorthogType*);

extern PetscErrorCode EPSBlzpackSetBlockSize(EPS,PetscInt);

extern PetscErrorCode EPSBlzpackSetInterval(EPS,PetscReal,PetscReal);

extern PetscErrorCode EPSBlzpackSetNSteps(EPS,PetscInt);

/*E

    EPSPRIMMEMethod - determines the method selected in the PRIMME library

    Level: advanced

.seealso: EPSPRIMMESetMethod(), EPSPRIMMEGetMethod()

E*/

typedef enum { EPS_PRIMME_DYNAMIC,

               EPS_PRIMME_DEFAULT_MIN_TIME,

               EPS_PRIMME_DEFAULT_MIN_MATVECS,

               EPS_PRIMME_ARNOLDI,

               EPS_PRIMME_GD,

               EPS_PRIMME_GD_PLUSK,

               EPS_PRIMME_GD_OLSEN_PLUSK,

               EPS_PRIMME_JD_OLSEN_PLUSK,

               EPS_PRIMME_RQI,

               EPS_PRIMME_JDQR,

               EPS_PRIMME_JDQMR,

               EPS_PRIMME_JDQMR_ETOL,

               EPS_PRIMME_SUBSPACE_ITERATION,

               EPS_PRIMME_LOBPCG_ORTHOBASIS,

               EPS_PRIMME_LOBPCG_ORTHOBASISW } EPSPRIMMEMethod;

extern const char *EPSPRIMMEMethods[];

extern PetscErrorCode EPSPRIMMESetBlockSize(EPS eps,PetscInt bs);

extern PetscErrorCode EPSPRIMMESetMethod(EPS eps, EPSPRIMMEMethod method);

extern PetscErrorCode EPSPRIMMEGetBlockSize(EPS eps,PetscInt *bs);

extern PetscErrorCode EPSPRIMMEGetMethod(EPS eps, EPSPRIMMEMethod *method);

extern PetscErrorCode EPSGDSetKrylovStart(EPS eps,PetscBool krylovstart);

extern PetscErrorCode EPSGDGetKrylovStart(EPS eps,PetscBool *krylovstart);

extern PetscErrorCode EPSGDSetBlockSize(EPS eps,PetscInt blocksize);

extern PetscErrorCode EPSGDGetBlockSize(EPS eps,PetscInt *blocksize);

extern PetscErrorCode EPSGDSetRestart(EPS eps,PetscInt minv,PetscInt plusk);

extern PetscErrorCode EPSGDGetRestart(EPS eps,PetscInt *minv,PetscInt *plusk);

extern PetscErrorCode EPSGDSetInitialSize(EPS eps,PetscInt initialsize);

extern PetscErrorCode EPSGDGetInitialSize(EPS eps,PetscInt *initialsize);

extern PetscErrorCode EPSJDSetKrylovStart(EPS eps,PetscBool krylovstart);

extern PetscErrorCode EPSJDGetKrylovStart(EPS eps,PetscBool *krylovstart);

extern PetscErrorCode EPSJDSetBlockSize(EPS eps,PetscInt blocksize);

extern PetscErrorCode EPSJDGetBlockSize(EPS eps,PetscInt *blocksize);

extern PetscErrorCode EPSJDSetRestart(EPS eps,PetscInt minv,PetscInt plusk);

extern PetscErrorCode EPSJDGetRestart(EPS eps,PetscInt *minv,PetscInt *plusk);

extern PetscErrorCode EPSJDSetInitialSize(EPS eps,PetscInt initialsize);

extern PetscErrorCode EPSJDGetInitialSize(EPS eps,PetscInt *initialsize);

extern PetscErrorCode EPSJDSetFix(EPS eps,PetscReal fix);

extern PetscErrorCode EPSJDGetFix(EPS eps,PetscReal *fix);

PETSC_EXTERN_CXX_END

#endif