Actual source code: lmeopts.c
slepc-3.18.0 2022-10-01
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: LME routines related to options that can be set via the command-line
12: or procedurally
13: */
15: #include <slepc/private/lmeimpl.h>
16: #include <petscdraw.h>
18: /*@C
19: LMEMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
20: indicated by the user.
22: Collective on lme
24: Input Parameters:
25: + lme - the linear matrix equation context
26: . opt - the command line option for this monitor
27: . name - the monitor type one is seeking
28: - ctx - an optional user context for the monitor, or NULL
30: Level: developer
32: .seealso: LMEMonitorSet()
33: @*/
34: PetscErrorCode LMEMonitorSetFromOptions(LME lme,const char opt[],const char name[],void *ctx)
35: {
36: PetscErrorCode (*mfunc)(LME,PetscInt,PetscReal,void*);
37: PetscErrorCode (*cfunc)(PetscViewer,PetscViewerFormat,void*,PetscViewerAndFormat**);
38: PetscErrorCode (*dfunc)(PetscViewerAndFormat**);
39: PetscViewerAndFormat *vf;
40: PetscViewer viewer;
41: PetscViewerFormat format;
42: PetscViewerType vtype;
43: char key[PETSC_MAX_PATH_LEN];
44: PetscBool flg;
46: PetscOptionsGetViewer(PetscObjectComm((PetscObject)lme),((PetscObject)lme)->options,((PetscObject)lme)->prefix,opt,&viewer,&format,&flg);
47: if (!flg) return 0;
49: PetscViewerGetType(viewer,&vtype);
50: SlepcMonitorMakeKey_Internal(name,vtype,format,key);
51: PetscFunctionListFind(LMEMonitorList,key,&mfunc);
53: PetscFunctionListFind(LMEMonitorCreateList,key,&cfunc);
54: PetscFunctionListFind(LMEMonitorDestroyList,key,&dfunc);
55: if (!cfunc) cfunc = PetscViewerAndFormatCreate_Internal;
56: if (!dfunc) dfunc = PetscViewerAndFormatDestroy;
58: (*cfunc)(viewer,format,ctx,&vf);
59: PetscObjectDereference((PetscObject)viewer);
60: LMEMonitorSet(lme,mfunc,vf,(PetscErrorCode(*)(void **))dfunc);
61: return 0;
62: }
64: /*@
65: LMESetFromOptions - Sets LME options from the options database.
66: This routine must be called before LMESetUp() if the user is to be
67: allowed to set the solver type.
69: Collective on lme
71: Input Parameters:
72: . lme - the linear matrix equation solver context
74: Notes:
75: To see all options, run your program with the -help option.
77: Level: beginner
79: .seealso: LMESetOptionsPrefix()
80: @*/
81: PetscErrorCode LMESetFromOptions(LME lme)
82: {
83: char type[256];
84: PetscBool set,flg,flg1,flg2;
85: PetscReal r;
86: PetscInt i;
89: LMERegisterAll();
90: PetscObjectOptionsBegin((PetscObject)lme);
91: PetscOptionsFList("-lme_type","Linear matrix equation","LMESetType",LMEList,(char*)(((PetscObject)lme)->type_name?((PetscObject)lme)->type_name:LMEKRYLOV),type,sizeof(type),&flg);
92: if (flg) LMESetType(lme,type);
93: else if (!((PetscObject)lme)->type_name) LMESetType(lme,LMEKRYLOV);
95: PetscOptionsBoolGroupBegin("-lme_lyapunov","Continuous-time Lyapunov equation","LMESetProblemType",&flg);
96: if (flg) LMESetProblemType(lme,LME_LYAPUNOV);
97: PetscOptionsBoolGroup("-lme_sylvester","Continuous-time Sylvester equation","LMESetProblemType",&flg);
98: if (flg) LMESetProblemType(lme,LME_SYLVESTER);
99: PetscOptionsBoolGroup("-lme_gen_lyapunov","Generalized Lyapunov equation","LMESetProblemType",&flg);
100: if (flg) LMESetProblemType(lme,LME_GEN_LYAPUNOV);
101: PetscOptionsBoolGroup("-lme_gen_sylvester","Generalized Sylvester equation","LMESetProblemType",&flg);
102: if (flg) LMESetProblemType(lme,LME_GEN_SYLVESTER);
103: PetscOptionsBoolGroup("-lme_dt_lyapunov","Discrete-time Lyapunov equation","LMESetProblemType",&flg);
104: if (flg) LMESetProblemType(lme,LME_DT_LYAPUNOV);
105: PetscOptionsBoolGroupEnd("-lme_stein","Stein equation","LMESetProblemType",&flg);
106: if (flg) LMESetProblemType(lme,LME_STEIN);
108: i = lme->max_it;
109: PetscOptionsInt("-lme_max_it","Maximum number of iterations","LMESetTolerances",lme->max_it,&i,&flg1);
110: if (!flg1) i = PETSC_DEFAULT;
111: r = lme->tol;
112: PetscOptionsReal("-lme_tol","Tolerance","LMESetTolerances",SlepcDefaultTol(lme->tol),&r,&flg2);
113: if (flg1 || flg2) LMESetTolerances(lme,r,i);
115: PetscOptionsInt("-lme_ncv","Number of basis vectors","LMESetDimensions",lme->ncv,&i,&flg);
116: if (flg) LMESetDimensions(lme,i);
118: PetscOptionsBool("-lme_error_if_not_converged","Generate error if solver does not converge","LMESetErrorIfNotConverged",lme->errorifnotconverged,&lme->errorifnotconverged,NULL);
120: /* -----------------------------------------------------------------------*/
121: /*
122: Cancels all monitors hardwired into code before call to LMESetFromOptions()
123: */
124: PetscOptionsBool("-lme_monitor_cancel","Remove any hardwired monitor routines","LMEMonitorCancel",PETSC_FALSE,&flg,&set);
125: if (set && flg) LMEMonitorCancel(lme);
126: LMEMonitorSetFromOptions(lme,"-lme_monitor","error_estimate",NULL);
128: /* -----------------------------------------------------------------------*/
129: PetscOptionsName("-lme_view","Print detailed information on solver used","LMEView",NULL);
131: PetscTryTypeMethod(lme,setfromoptions,PetscOptionsObject);
132: PetscObjectProcessOptionsHandlers((PetscObject)lme,PetscOptionsObject);
133: PetscOptionsEnd();
135: if (!lme->V) LMEGetBV(lme,&lme->V);
136: BVSetFromOptions(lme->V);
137: return 0;
138: }
140: /*@
141: LMESetProblemType - Specifies the type of matrix equation to be solved.
143: Logically Collective on lme
145: Input Parameters:
146: + lme - the linear matrix equation solver context
147: - type - a known type of matrix equation
149: Options Database Keys:
150: + -lme_lyapunov - continuous-time Lyapunov equation A*X+X*A'=-C
151: . -lme_sylvester - continuous-time Sylvester equation A*X+X*B=C
152: . -lme_gen_lyapunov - generalized Lyapunov equation A*X*D'+D*X*A'=-C
153: . -lme_gen_sylvester - generalized Sylvester equation A*X*E+D*X*B=C
154: . -lme_dt_lyapunov - discrete-time Lyapunov equation A*X*A'-X=-C
155: - -lme_stein - Stein equation A*X*E+X=C
157: Notes:
158: The coefficient matrices A, B, D, E must be provided via LMESetCoefficients(),
159: but some of them are optional depending on the matrix equation.
161: .vb
162: equation A B D E
163: ----------------- --- --- --- ---
164: LME_LYAPUNOV A*X+X*A'=-C yes (A-t) - -
165: LME_SYLVESTER A*X+X*B=C yes yes - -
166: LME_GEN_LYAPUNOV A*X*D'+D*X*A'=-C yes (A-t) yes (D-t)
167: LME_GEN_SYLVESTER A*X*E+D*X*B=C yes yes yes yes
168: LME_DT_LYAPUNOV A*X*A'-X=-C yes - - (A-t)
169: LME_STEIN A*X*E+X=C yes - - yes
170: .ve
172: In the above table, the notation (A-t) means that this matrix need
173: not be passed, but the user may choose to pass an explicit transpose
174: of matrix A (for improved efficiency).
176: Also note that some of the equation types impose restrictions on the
177: properties of the coefficient matrices and possibly on the right-hand
178: side C.
180: Level: beginner
182: .seealso: LMESetCoefficients(), LMESetType(), LMEGetProblemType(), LMEProblemType
183: @*/
184: PetscErrorCode LMESetProblemType(LME lme,LMEProblemType type)
185: {
188: if (type == lme->problem_type) return 0;
189: switch (type) {
190: case LME_LYAPUNOV:
191: case LME_SYLVESTER:
192: case LME_GEN_LYAPUNOV:
193: case LME_GEN_SYLVESTER:
194: case LME_DT_LYAPUNOV:
195: case LME_STEIN:
196: break;
197: default:
198: SETERRQ(PetscObjectComm((PetscObject)lme),PETSC_ERR_ARG_WRONG,"Unknown matrix equation type");
199: }
200: lme->problem_type = type;
201: lme->setupcalled = PETSC_FALSE;
202: return 0;
203: }
205: /*@
206: LMEGetProblemType - Gets the matrix equation type from the LME object.
208: Not Collective
210: Input Parameter:
211: . lme - the linear matrix equation solver context
213: Output Parameter:
214: . type - name of LME problem type
216: Level: intermediate
218: .seealso: LMESetProblemType(), LMEProblemType
219: @*/
220: PetscErrorCode LMEGetProblemType(LME lme,LMEProblemType *type)
221: {
224: *type = lme->problem_type;
225: return 0;
226: }
228: /*@C
229: LMEGetTolerances - Gets the tolerance and maximum iteration count used
230: by the LME convergence tests.
232: Not Collective
234: Input Parameter:
235: . lme - the linear matrix equation solver context
237: Output Parameters:
238: + tol - the convergence tolerance
239: - maxits - maximum number of iterations
241: Notes:
242: The user can specify NULL for any parameter that is not needed.
244: Level: intermediate
246: .seealso: LMESetTolerances()
247: @*/
248: PetscErrorCode LMEGetTolerances(LME lme,PetscReal *tol,PetscInt *maxits)
249: {
251: if (tol) *tol = lme->tol;
252: if (maxits) *maxits = lme->max_it;
253: return 0;
254: }
256: /*@
257: LMESetTolerances - Sets the tolerance and maximum iteration count used
258: by the LME convergence tests.
260: Logically Collective on lme
262: Input Parameters:
263: + lme - the linear matrix equation solver context
264: . tol - the convergence tolerance
265: - maxits - maximum number of iterations to use
267: Options Database Keys:
268: + -lme_tol <tol> - Sets the convergence tolerance
269: - -lme_max_it <maxits> - Sets the maximum number of iterations allowed
271: Notes:
272: Use PETSC_DEFAULT for either argument to assign a reasonably good value.
274: Level: intermediate
276: .seealso: LMEGetTolerances()
277: @*/
278: PetscErrorCode LMESetTolerances(LME lme,PetscReal tol,PetscInt maxits)
279: {
283: if (tol == PETSC_DEFAULT) {
284: lme->tol = PETSC_DEFAULT;
285: lme->setupcalled = 0;
286: } else {
288: lme->tol = tol;
289: }
290: if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
291: lme->max_it = PETSC_DEFAULT;
292: lme->setupcalled = 0;
293: } else {
295: lme->max_it = maxits;
296: }
297: return 0;
298: }
300: /*@
301: LMEGetDimensions - Gets the dimension of the subspace used by the solver.
303: Not Collective
305: Input Parameter:
306: . lme - the linear matrix equation solver context
308: Output Parameter:
309: . ncv - the maximum dimension of the subspace to be used by the solver
311: Level: intermediate
313: .seealso: LMESetDimensions()
314: @*/
315: PetscErrorCode LMEGetDimensions(LME lme,PetscInt *ncv)
316: {
319: *ncv = lme->ncv;
320: return 0;
321: }
323: /*@
324: LMESetDimensions - Sets the dimension of the subspace to be used by the solver.
326: Logically Collective on lme
328: Input Parameters:
329: + lme - the linear matrix equation solver context
330: - ncv - the maximum dimension of the subspace to be used by the solver
332: Options Database Keys:
333: . -lme_ncv <ncv> - Sets the dimension of the subspace
335: Notes:
336: Use PETSC_DEFAULT for ncv to assign a reasonably good value, which is
337: dependent on the solution method.
339: Level: intermediate
341: .seealso: LMEGetDimensions()
342: @*/
343: PetscErrorCode LMESetDimensions(LME lme,PetscInt ncv)
344: {
347: if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
348: lme->ncv = PETSC_DEFAULT;
349: } else {
351: lme->ncv = ncv;
352: }
353: lme->setupcalled = 0;
354: return 0;
355: }
357: /*@
358: LMESetErrorIfNotConverged - Causes LMESolve() to generate an error if the
359: solver has not converged.
361: Logically Collective on lme
363: Input Parameters:
364: + lme - the linear matrix equation solver context
365: - flg - PETSC_TRUE indicates you want the error generated
367: Options Database Keys:
368: . -lme_error_if_not_converged - this takes an optional truth value (0/1/no/yes/true/false)
370: Level: intermediate
372: Note:
373: Normally SLEPc continues if the solver fails to converge, you can call
374: LMEGetConvergedReason() after a LMESolve() to determine if it has converged.
376: .seealso: LMEGetErrorIfNotConverged()
377: @*/
378: PetscErrorCode LMESetErrorIfNotConverged(LME lme,PetscBool flg)
379: {
382: lme->errorifnotconverged = flg;
383: return 0;
384: }
386: /*@
387: LMEGetErrorIfNotConverged - Return a flag indicating whether LMESolve() will
388: generate an error if the solver does not converge.
390: Not Collective
392: Input Parameter:
393: . lme - the linear matrix equation solver context
395: Output Parameter:
396: . flag - PETSC_TRUE if it will generate an error, else PETSC_FALSE
398: Level: intermediate
400: .seealso: LMESetErrorIfNotConverged()
401: @*/
402: PetscErrorCode LMEGetErrorIfNotConverged(LME lme,PetscBool *flag)
403: {
406: *flag = lme->errorifnotconverged;
407: return 0;
408: }
410: /*@C
411: LMESetOptionsPrefix - Sets the prefix used for searching for all
412: LME options in the database.
414: Logically Collective on lme
416: Input Parameters:
417: + lme - the linear matrix equation solver context
418: - prefix - the prefix string to prepend to all LME option requests
420: Notes:
421: A hyphen (-) must NOT be given at the beginning of the prefix name.
422: The first character of all runtime options is AUTOMATICALLY the
423: hyphen.
425: For example, to distinguish between the runtime options for two
426: different LME contexts, one could call
427: .vb
428: LMESetOptionsPrefix(lme1,"fun1_")
429: LMESetOptionsPrefix(lme2,"fun2_")
430: .ve
432: Level: advanced
434: .seealso: LMEAppendOptionsPrefix(), LMEGetOptionsPrefix()
435: @*/
436: PetscErrorCode LMESetOptionsPrefix(LME lme,const char *prefix)
437: {
439: if (!lme->V) LMEGetBV(lme,&lme->V);
440: BVSetOptionsPrefix(lme->V,prefix);
441: PetscObjectSetOptionsPrefix((PetscObject)lme,prefix);
442: return 0;
443: }
445: /*@C
446: LMEAppendOptionsPrefix - Appends to the prefix used for searching for all
447: LME options in the database.
449: Logically Collective on lme
451: Input Parameters:
452: + lme - the linear matrix equation solver context
453: - prefix - the prefix string to prepend to all LME option requests
455: Notes:
456: A hyphen (-) must NOT be given at the beginning of the prefix name.
457: The first character of all runtime options is AUTOMATICALLY the hyphen.
459: Level: advanced
461: .seealso: LMESetOptionsPrefix(), LMEGetOptionsPrefix()
462: @*/
463: PetscErrorCode LMEAppendOptionsPrefix(LME lme,const char *prefix)
464: {
466: if (!lme->V) LMEGetBV(lme,&lme->V);
467: BVAppendOptionsPrefix(lme->V,prefix);
468: PetscObjectAppendOptionsPrefix((PetscObject)lme,prefix);
469: return 0;
470: }
472: /*@C
473: LMEGetOptionsPrefix - Gets the prefix used for searching for all
474: LME options in the database.
476: Not Collective
478: Input Parameters:
479: . lme - the linear matrix equation solver context
481: Output Parameters:
482: . prefix - pointer to the prefix string used is returned
484: Note:
485: On the Fortran side, the user should pass in a string 'prefix' of
486: sufficient length to hold the prefix.
488: Level: advanced
490: .seealso: LMESetOptionsPrefix(), LMEAppendOptionsPrefix()
491: @*/
492: PetscErrorCode LMEGetOptionsPrefix(LME lme,const char *prefix[])
493: {
496: PetscObjectGetOptionsPrefix((PetscObject)lme,prefix);
497: return 0;
498: }