Actual source code: slepclme.h

  1: /*
  2:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  3:    SLEPc - Scalable Library for Eigenvalue Problem Computations
  4:    Copyright (c) 2002-, Universitat Politecnica de Valencia, Spain

  6:    This file is part of SLEPc.
  7:    SLEPc is distributed under a 2-clause BSD license (see LICENSE).
  8:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  9: */
 10: /*
 11:    User interface for the SLEPc object for solving linear matrix equations
 12: */

 14: #pragma once

 16: #include <slepcbv.h>

 18: /* SUBMANSEC = LME */

 20: SLEPC_EXTERN PetscErrorCode LMEInitializePackage(void);
 21: SLEPC_EXTERN PetscErrorCode LMEFinalizePackage(void);

 23: /*S
 24:    LME - SLEPc object that encapsulates functionality for linear matrix equations.

 26:    Level: beginner

 28: .seealso: [](ch:lme), `LMECreate()`
 29: S*/
 30: typedef struct _p_LME* LME;

 32: /*J
 33:    LMEType - String with the name of a method for solving linear matrix equations.

 35:    Level: beginner

 37: .seealso: [](ch:lme), `LMESetType()`, `LME`
 38: J*/
 39: typedef const char *LMEType;
 40: #define LMEKRYLOV   "krylov"

 42: /* Logging support */
 43: SLEPC_EXTERN PetscClassId LME_CLASSID;

 45: /*E
 46:    LMEProblemType - Determines the type of linear matrix equation.

 48:    Values:
 49: +  `LME_LYAPUNOV`      - continuous-time Lyapunov equation
 50: .  `LME_SYLVESTER`     - Sylvester equation
 51: .  `LME_GEN_LYAPUNOV`  - generalized Lyapunov equation
 52: .  `LME_GEN_SYLVESTER` - generalized Sylvester equation
 53: .  `LME_DT_LYAPUNOV`   - discrete-time Lyapunov equation
 54: -  `LME_STEIN`         - Stein equation

 56:    Level: beginner

 58: .seealso: [](ch:lme), `LMESetProblemType()`, `LMEGetProblemType()`
 59: E*/
 60: typedef enum { LME_LYAPUNOV,
 61:                LME_SYLVESTER,
 62:                LME_GEN_LYAPUNOV,
 63:                LME_GEN_SYLVESTER,
 64:                LME_DT_LYAPUNOV ,
 65:                LME_STEIN} LMEProblemType;
 66: SLEPC_EXTERN const char *LMEProblemTypes[];

 68: /*MC
 69:    LME_LYAPUNOV - The continuous-time Lyapunov equation, $AX+XA^*=-C$.

 71:    Level: beginner

 73: .seealso: [](ch:lme), `LMEProblemType`, `LMESetProblemType()`, `LME_SYLVESTER`, `LME_GEN_LYAPUNOV`, `LME_GEN_SYLVESTER`, `LME_DT_LYAPUNOV`, `LME_STEIN`
 74: M*/

 76: /*MC
 77:    LME_SYLVESTER - The Sylvester equation, $AX+XB=C$.

 79:    Level: beginner

 81: .seealso: [](ch:lme), `LMEProblemType`, `LMESetProblemType()`, `LME_LYAPUNOV`, `LME_GEN_LYAPUNOV`, `LME_GEN_SYLVESTER`, `LME_DT_LYAPUNOV`, `LME_STEIN`
 82: M*/

 84: /*MC
 85:    LME_GEN_LYAPUNOV - The generalized Lyapunov equation, $AXD^*+DXA^*=-C$.

 87:    Level: beginner

 89: .seealso: [](ch:lme), `LMEProblemType`, `LMESetProblemType()`, `LME_LYAPUNOV`, `LME_GEN_SYLVESTER`, `LME_SYLVESTER`, `LME_DT_LYAPUNOV`, `LME_STEIN`
 90: M*/

 92: /*MC
 93:    LME_GEN_SYLVESTER - The generalized Sylvester equation, $AXE+DXB=C$.

 95:    Level: beginner

 97: .seealso: [](ch:lme), `LMEProblemType`, `LMESetProblemType()`, `LME_LYAPUNOV`, `LME_DT_LYAPUNOV`, `LME_SYLVESTER`, `LME_GEN_LYAPUNOV`, `LME_STEIN`
 98: M*/

100: /*MC
101:    LME_DT_LYAPUNOV - The discrete-time Lyapunov equation, $AXA^*-X=-C$.

103:    Level: beginner

105: .seealso: [](ch:lme), `LMEProblemType`, `LMESetProblemType()`, `LME_LYAPUNOV`, `LME_SYLVESTER`, `LME_GEN_LYAPUNOV`, `LME_GEN_SYLVESTER`, `LME_STEIN`
106: M*/

108: /*MC
109:    LME_STEIN - The Stein equation, $AXE-X=-C$.

111:    Level: beginner

113: .seealso: [](ch:lme), `LMEProblemType`, `LMESetProblemType()`, `LME_LYAPUNOV`, `LME_SYLVESTER`, `LME_GEN_LYAPUNOV`, `LME_GEN_SYLVESTER`, `LME_DT_LYAPUNOV`
114: M*/

116: SLEPC_EXTERN PetscErrorCode LMECreate(MPI_Comm,LME*);
117: SLEPC_EXTERN PetscErrorCode LMEDestroy(LME*);
118: SLEPC_EXTERN PetscErrorCode LMEReset(LME);
119: SLEPC_EXTERN PetscErrorCode LMESetType(LME,LMEType);
120: SLEPC_EXTERN PetscErrorCode LMEGetType(LME,LMEType*);
121: SLEPC_EXTERN PetscErrorCode LMESetProblemType(LME,LMEProblemType);
122: SLEPC_EXTERN PetscErrorCode LMEGetProblemType(LME,LMEProblemType*);
123: SLEPC_EXTERN PetscErrorCode LMESetCoefficients(LME,Mat,Mat,Mat,Mat);
124: SLEPC_EXTERN PetscErrorCode LMEGetCoefficients(LME,Mat*,Mat*,Mat*,Mat*);
125: SLEPC_EXTERN PetscErrorCode LMESetRHS(LME,Mat);
126: SLEPC_EXTERN PetscErrorCode LMEGetRHS(LME,Mat*);
127: SLEPC_EXTERN PetscErrorCode LMESetSolution(LME,Mat);
128: SLEPC_EXTERN PetscErrorCode LMEGetSolution(LME,Mat*);
129: SLEPC_EXTERN PetscErrorCode LMESetFromOptions(LME);
130: SLEPC_EXTERN PetscErrorCode LMESetUp(LME);
131: SLEPC_EXTERN PetscErrorCode LMESolve(LME);
132: SLEPC_EXTERN PetscErrorCode LMEView(LME,PetscViewer);
133: SLEPC_EXTERN PetscErrorCode LMEViewFromOptions(LME,PetscObject,const char[]);
134: SLEPC_EXTERN PetscErrorCode LMEConvergedReasonView(LME,PetscViewer);
135: SLEPC_EXTERN PetscErrorCode LMEConvergedReasonViewFromOptions(LME);
136: PETSC_DEPRECATED_FUNCTION(3, 14, 0, "LMEConvergedReasonView()", ) static inline PetscErrorCode LMEReasonView(LME lme,PetscViewer v) {return LMEConvergedReasonView(lme,v);}
137: PETSC_DEPRECATED_FUNCTION(3, 14, 0, "LMEConvergedReasonViewFromOptions()", ) static inline PetscErrorCode LMEReasonViewFromOptions(LME lme) {return LMEConvergedReasonViewFromOptions(lme);}

139: SLEPC_EXTERN PetscErrorCode LMESetBV(LME,BV);
140: SLEPC_EXTERN PetscErrorCode LMEGetBV(LME,BV*);
141: SLEPC_EXTERN PetscErrorCode LMESetTolerances(LME,PetscReal,PetscInt);
142: SLEPC_EXTERN PetscErrorCode LMEGetTolerances(LME,PetscReal*,PetscInt*);
143: SLEPC_EXTERN PetscErrorCode LMESetDimensions(LME,PetscInt);
144: SLEPC_EXTERN PetscErrorCode LMEGetDimensions(LME,PetscInt*);
145: SLEPC_EXTERN PetscErrorCode LMEGetIterationNumber(LME,PetscInt*);

147: SLEPC_EXTERN PetscErrorCode LMEGetErrorEstimate(LME,PetscReal*);
148: SLEPC_EXTERN PetscErrorCode LMEComputeError(LME,PetscReal*);
149: SLEPC_EXTERN PetscErrorCode LMESetErrorIfNotConverged(LME,PetscBool);
150: SLEPC_EXTERN PetscErrorCode LMEGetErrorIfNotConverged(LME,PetscBool*);

152: SLEPC_EXTERN PetscErrorCode LMEDenseLyapunov(LME,PetscInt,PetscScalar[],PetscInt,PetscScalar[],PetscInt,PetscScalar[],PetscInt);
153: SLEPC_EXTERN PetscErrorCode LMEDenseHessLyapunovChol(LME,PetscInt,PetscScalar[],PetscInt,PetscInt,PetscScalar[],PetscInt,PetscScalar[],PetscInt,PetscReal*);
154: PETSC_DEPRECATED_FUNCTION(3, 8, 0, "LMEDenseHessLyapunovChol()", ) static inline PetscErrorCode LMEDenseLyapunovChol(LME lme,PetscScalar *H,PetscInt m,PetscInt ldh,PetscScalar *r,PetscScalar *L,PetscInt ldl,PetscReal *res) {return LMEDenseHessLyapunovChol(lme,m,H,ldh,1,r,m,L,ldl,res);}

156: /*S
157:    LMEMonitorFn - A function prototype for functions provided to `LMEMonitorSet()`.

159:    Calling Sequence:
160: +  lme    - the linear matrix equation solver context
161: .  its    - iteration number
162: .  errest - error estimate
163: -  ctx    - optional monitoring context, as provided with `LMEMonitorSet()`

165:    Level: intermediate

167: .seealso: [](ch:lme), `LMEMonitorSet()`
168: S*/
169: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode LMEMonitorFn(LME lme,PetscInt its,PetscReal errest,void *ctx);

171: /*S
172:    LMEMonitorRegisterFn - A function prototype for functions provided to `LMEMonitorRegister()`.

174:    Calling Sequence:
175: +  lme    - the linear matrix equation solver context
176: .  its    - iteration number
177: .  errest - error estimate
178: -  ctx    - `PetscViewerAndFormat` object

180:    Level: advanced

182:    Note:
183:    This is an `LMEMonitorFn` specialized for a context of `PetscViewerAndFormat`.

185: .seealso: [](ch:lme), `LMEMonitorSet()`, `LMEMonitorRegister()`, `LMEMonitorFn`, `LMEMonitorRegisterCreateFn`, `LMEMonitorRegisterDestroyFn`
186: S*/
187: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode LMEMonitorRegisterFn(LME lme,PetscInt its,PetscReal errest,PetscViewerAndFormat *ctx);

189: /*S
190:    LMEMonitorRegisterCreateFn - A function prototype for functions that do the
191:    creation when provided to `LMEMonitorRegister()`.

193:    Calling Sequence:
194: +  viewer - the viewer to be used with the `LMEMonitorRegisterFn`
195: .  format - the format of the viewer
196: .  ctx    - a context for the monitor
197: -  result - a `PetscViewerAndFormat` object

199:    Level: advanced

201: .seealso: [](ch:lme), `LMEMonitorRegisterFn`, `LMEMonitorSet()`, `LMEMonitorRegister()`, `LMEMonitorFn`, `LMEMonitorRegisterDestroyFn`
202: S*/
203: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode LMEMonitorRegisterCreateFn(PetscViewer viewer,PetscViewerFormat format,void *ctx,PetscViewerAndFormat **result);

205: /*S
206:    LMEMonitorRegisterDestroyFn - A function prototype for functions that do the after
207:    use destruction when provided to `LMEMonitorRegister()`.

209:    Calling Sequence:
210: .  vf - a `PetscViewerAndFormat` object to be destroyed, including any context

212:    Level: advanced

214: .seealso: [](ch:lme), `LMEMonitorRegisterFn`, `LMEMonitorSet()`, `LMEMonitorRegister()`, `LMEMonitorFn`, `LMEMonitorRegisterCreateFn`
215: S*/
216: PETSC_EXTERN_TYPEDEF typedef PetscErrorCode LMEMonitorRegisterDestroyFn(PetscViewerAndFormat **result);

218: SLEPC_EXTERN PetscErrorCode LMEMonitor(LME,PetscInt,PetscReal);
219: SLEPC_EXTERN PetscErrorCode LMEMonitorSet(LME,LMEMonitorFn,void*,PetscCtxDestroyFn*);
220: SLEPC_EXTERN PetscErrorCode LMEMonitorCancel(LME);
221: SLEPC_EXTERN PetscErrorCode LMEGetMonitorContext(LME,void*);

223: SLEPC_EXTERN PetscErrorCode LMEMonitorSetFromOptions(LME,const char[],const char[],void*);
224: SLEPC_EXTERN LMEMonitorRegisterFn       LMEMonitorDefault;
225: SLEPC_EXTERN LMEMonitorRegisterFn       LMEMonitorDefaultDrawLG;
226: SLEPC_EXTERN LMEMonitorRegisterCreateFn LMEMonitorDefaultDrawLGCreate;

228: SLEPC_EXTERN PetscErrorCode LMESetOptionsPrefix(LME,const char[]);
229: SLEPC_EXTERN PetscErrorCode LMEAppendOptionsPrefix(LME,const char[]);
230: SLEPC_EXTERN PetscErrorCode LMEGetOptionsPrefix(LME,const char*[]);

232: /*E
233:    LMEConvergedReason - Reason a matrix function iteration was determined to
234:    have converged or diverged.

236:    Values:
237: +  `LME_CONVERGED_TOL`       - requested decrease in the residual
238: .  `LME_DIVERGED_ITS`        - requested number of iterations
239: .  `LME_DIVERGED_BREAKDOWN`  - breakdown in the solver
240: -  `LME_CONVERGED_ITERATING` - the solver is still running

242:    Level: intermediate

244: .seealso: [](ch:lme), `LMESolve()`, `LMEGetConvergedReason()`, `LMESetTolerances()`
245: E*/
246: typedef enum {/* converged */
247:               LME_CONVERGED_TOL                =  1,
248:               /* diverged */
249:               LME_DIVERGED_ITS                 = -1,
250:               LME_DIVERGED_BREAKDOWN           = -2,
251:               LME_CONVERGED_ITERATING          =  0} LMEConvergedReason;
252: SLEPC_EXTERN const char *const*LMEConvergedReasons;

254: /*MC
255:    LME_CONVERGED_TOL - The computed residual of the matrix equation is below the
256:    tolerance.

258:    Level: intermediate

260: .seealso: [](ch:lme), `LMESolve()`, `LMEGetConvergedReason()`, `LMEConvergedReason`
261: M*/

263: /*MC
264:    LME_DIVERGED_ITS - Ran out of iterations before the convergence criterion was
265:    reached.

267:    Level: intermediate

269: .seealso: [](ch:lme), `LMESolve()`, `LMEGetConvergedReason()`, `LMEConvergedReason`
270: M*/

272: /*MC
273:    LME_DIVERGED_BREAKDOWN - A breakdown in the solver was detected so the
274:    method could not continue.

276:    Level: intermediate

278: .seealso: [](ch:lme), `LMESolve()`, `LMEGetConvergedReason()`, `LMEConvergedReason`
279: M*/

281: /*MC
282:    LME_CONVERGED_ITERATING - This flag is returned if `LMEGetConvergedReason()` is called
283:    while `LMESolve()` is still running..

285:    Level: intermediate

287: .seealso: [](ch:lme), `LMESolve()`, `LMEGetConvergedReason()`, `LMEConvergedReason`
288: M*/

290: SLEPC_EXTERN PetscErrorCode LMEGetConvergedReason(LME,LMEConvergedReason*);

292: SLEPC_EXTERN PetscFunctionList LMEList;
293: SLEPC_EXTERN PetscFunctionList LMEMonitorList;
294: SLEPC_EXTERN PetscFunctionList LMEMonitorCreateList;
295: SLEPC_EXTERN PetscFunctionList LMEMonitorDestroyList;
296: SLEPC_EXTERN PetscErrorCode LMERegister(const char[],PetscErrorCode(*)(LME));
297: SLEPC_EXTERN PetscErrorCode LMEMonitorRegister(const char[],PetscViewerType,PetscViewerFormat,LMEMonitorRegisterFn*,LMEMonitorRegisterCreateFn*,LMEMonitorRegisterDestroyFn*);

299: SLEPC_EXTERN PetscErrorCode LMEAllocateSolution(LME,PetscInt);