1: /*
2: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3: SLEPc - Scalable Library for Eigenvalue Problem Computations
4: Copyright (c) 2002-2019, 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: MFN routines related to options that can be set via the command-line
12: or procedurally
13: */
15: #include <slepc/private/mfnimpl.h> /*I "slepcmfn.h" I*/
16: #include <petscdraw.h>
18: /*@C
19: MFNMonitorSetFromOptions - Sets a monitor function and viewer appropriate for the type
20: indicated by the user.
22: Collective on MFN 24: Input Parameters:
25: + mfn - the eigensolver context
26: . name - the monitor option name
27: . help - message indicating what monitoring is done
28: . manual - manual page for the monitor
29: - monitor - the monitor function, whose context is a PetscViewerAndFormat
31: Level: developer
33: .seealso: MFNMonitorSet()
34: @*/
35: PetscErrorCode MFNMonitorSetFromOptions(MFN mfn,const char name[],const char help[],const char manual[],PetscErrorCode (*monitor)(MFN,PetscInt,PetscReal,PetscViewerAndFormat*)) 36: {
37: PetscErrorCode ierr;
38: PetscBool flg;
39: PetscViewer viewer;
40: PetscViewerFormat format;
41: PetscViewerAndFormat *vf;
44: PetscOptionsGetViewer(PetscObjectComm((PetscObject)mfn),((PetscObject)mfn)->options,((PetscObject)mfn)->prefix,name,&viewer,&format,&flg);
45: if (flg) {
46: PetscViewerAndFormatCreate(viewer,format,&vf);
47: PetscObjectDereference((PetscObject)viewer);
48: MFNMonitorSet(mfn,(PetscErrorCode (*)(MFN,PetscInt,PetscReal,void*))monitor,vf,(PetscErrorCode (*)(void**))PetscViewerAndFormatDestroy);
49: }
50: return(0);
51: }
53: /*@
54: MFNSetFromOptions - Sets MFN options from the options database.
55: This routine must be called before MFNSetUp() if the user is to be
56: allowed to set the solver type.
58: Collective on MFN 60: Input Parameters:
61: . mfn - the matrix function context
63: Notes:
64: To see all options, run your program with the -help option.
66: Level: beginner
67: @*/
68: PetscErrorCode MFNSetFromOptions(MFN mfn) 69: {
71: char type[256];
72: PetscBool set,flg,flg1,flg2;
73: PetscReal r;
74: PetscInt i;
75: PetscDrawLG lg;
79: MFNRegisterAll();
80: PetscObjectOptionsBegin((PetscObject)mfn);
81: PetscOptionsFList("-mfn_type","Matrix Function method","MFNSetType",MFNList,(char*)(((PetscObject)mfn)->type_name?((PetscObject)mfn)->type_name:MFNKRYLOV),type,256,&flg);
82: if (flg) {
83: MFNSetType(mfn,type);
84: } else if (!((PetscObject)mfn)->type_name) {
85: MFNSetType(mfn,MFNKRYLOV);
86: }
88: i = mfn->max_it;
89: PetscOptionsInt("-mfn_max_it","Maximum number of iterations","MFNSetTolerances",mfn->max_it,&i,&flg1);
90: if (!flg1) i = PETSC_DEFAULT;
91: r = mfn->tol;
92: PetscOptionsReal("-mfn_tol","Tolerance","MFNSetTolerances",mfn->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:mfn->tol,&r,&flg2);
93: if (flg1 || flg2) { MFNSetTolerances(mfn,r,i); }
95: PetscOptionsInt("-mfn_ncv","Number of basis vectors","MFNSetDimensions",mfn->ncv,&i,&flg);
96: if (flg) { MFNSetDimensions(mfn,i); }
98: PetscOptionsBool("-mfn_error_if_not_converged","Generate error if solver does not converge","MFNSetErrorIfNotConverged",mfn->errorifnotconverged,&mfn->errorifnotconverged,NULL);
100: /* -----------------------------------------------------------------------*/
101: /*
102: Cancels all monitors hardwired into code before call to MFNSetFromOptions()
103: */
104: PetscOptionsBool("-mfn_monitor_cancel","Remove any hardwired monitor routines","MFNMonitorCancel",PETSC_FALSE,&flg,&set);
105: if (set && flg) {
106: MFNMonitorCancel(mfn);
107: }
108: /*
109: Text monitors
110: */
111: MFNMonitorSetFromOptions(mfn,"-mfn_monitor","Monitor error estimate","MFNMonitorDefault",MFNMonitorDefault);
112: /*
113: Line graph monitors
114: */
115: PetscOptionsBool("-mfn_monitor_lg","Monitor error estimate graphically","MFNMonitorSet",PETSC_FALSE,&flg,&set);
116: if (set && flg) {
117: MFNMonitorLGCreate(PetscObjectComm((PetscObject)mfn),NULL,"Error estimate",PETSC_DECIDE,PETSC_DECIDE,300,300,&lg);
118: MFNMonitorSet(mfn,MFNMonitorLG,lg,(PetscErrorCode (*)(void**))PetscDrawLGDestroy);
119: }
121: /* -----------------------------------------------------------------------*/
122: PetscOptionsName("-mfn_view","Print detailed information on solver used","MFNView",NULL);
124: if (mfn->ops->setfromoptions) {
125: (*mfn->ops->setfromoptions)(PetscOptionsObject,mfn);
126: }
127: PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)mfn);
128: PetscOptionsEnd();
130: if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
131: BVSetFromOptions(mfn->V);
132: if (!mfn->fn) { MFNGetFN(mfn,&mfn->fn); }
133: FNSetFromOptions(mfn->fn);
134: return(0);
135: }
137: /*@C
138: MFNGetTolerances - Gets the tolerance and maximum iteration count used
139: by the MFN convergence tests.
141: Not Collective
143: Input Parameter:
144: . mfn - the matrix function context
146: Output Parameters:
147: + tol - the convergence tolerance
148: - maxits - maximum number of iterations
150: Notes:
151: The user can specify NULL for any parameter that is not needed.
153: Level: intermediate
155: .seealso: MFNSetTolerances()
156: @*/
157: PetscErrorCode MFNGetTolerances(MFN mfn,PetscReal *tol,PetscInt *maxits)158: {
161: if (tol) *tol = mfn->tol;
162: if (maxits) *maxits = mfn->max_it;
163: return(0);
164: }
166: /*@
167: MFNSetTolerances - Sets the tolerance and maximum iteration count used
168: by the MFN convergence tests.
170: Logically Collective on MFN172: Input Parameters:
173: + mfn - the matrix function context
174: . tol - the convergence tolerance
175: - maxits - maximum number of iterations to use
177: Options Database Keys:
178: + -mfn_tol <tol> - Sets the convergence tolerance
179: - -mfn_max_it <maxits> - Sets the maximum number of iterations allowed
181: Notes:
182: Use PETSC_DEFAULT for either argument to assign a reasonably good value.
184: Level: intermediate
186: .seealso: MFNGetTolerances()
187: @*/
188: PetscErrorCode MFNSetTolerances(MFN mfn,PetscReal tol,PetscInt maxits)189: {
194: if (tol == PETSC_DEFAULT) {
195: mfn->tol = PETSC_DEFAULT;
196: mfn->setupcalled = 0;
197: } else {
198: if (tol <= 0.0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
199: mfn->tol = tol;
200: }
201: if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
202: mfn->max_it = 0;
203: mfn->setupcalled = 0;
204: } else {
205: if (maxits <= 0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
206: mfn->max_it = maxits;
207: }
208: return(0);
209: }
211: /*@
212: MFNGetDimensions - Gets the dimension of the subspace used by the solver.
214: Not Collective
216: Input Parameter:
217: . mfn - the matrix function context
219: Output Parameter:
220: . ncv - the maximum dimension of the subspace to be used by the solver
222: Level: intermediate
224: .seealso: MFNSetDimensions()
225: @*/
226: PetscErrorCode MFNGetDimensions(MFN mfn,PetscInt *ncv)227: {
231: *ncv = mfn->ncv;
232: return(0);
233: }
235: /*@
236: MFNSetDimensions - Sets the dimension of the subspace to be used by the solver.
238: Logically Collective on MFN240: Input Parameters:
241: + mfn - the matrix function context
242: - ncv - the maximum dimension of the subspace to be used by the solver
244: Options Database Keys:
245: . -mfn_ncv <ncv> - Sets the dimension of the subspace
247: Notes:
248: Use PETSC_DEFAULT for ncv to assign a reasonably good value, which is
249: dependent on the solution method.
251: Level: intermediate
253: .seealso: MFNGetDimensions()
254: @*/
255: PetscErrorCode MFNSetDimensions(MFN mfn,PetscInt ncv)256: {
260: if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
261: mfn->ncv = 0;
262: } else {
263: if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
264: mfn->ncv = ncv;
265: }
266: mfn->setupcalled = 0;
267: return(0);
268: }
270: /*@
271: MFNSetErrorIfNotConverged - Causes MFNSolve() to generate an error if the
272: solver has not converged.
274: Logically Collective on MFN276: Input Parameters:
277: + mfn - the matrix function context
278: - flg - PETSC_TRUE indicates you want the error generated
280: Options Database Keys:
281: . -mfn_error_if_not_converged - this takes an optional truth value (0/1/no/yes/true/false)
283: Level: intermediate
285: Note:
286: Normally SLEPc continues if the solver fails to converge, you can call
287: MFNGetConvergedReason() after a MFNSolve() to determine if it has converged.
289: .seealso: MFNGetErrorIfNotConverged()
290: @*/
291: PetscErrorCode MFNSetErrorIfNotConverged(MFN mfn,PetscBool flg)292: {
296: mfn->errorifnotconverged = flg;
297: return(0);
298: }
300: /*@
301: MFNGetErrorIfNotConverged - Return a flag indicating whether MFNSolve() will
302: generate an error if the solver does not converge.
304: Not Collective
306: Input Parameter:
307: . mfn - the matrix function context
309: Output Parameter:
310: . flag - PETSC_TRUE if it will generate an error, else PETSC_FALSE
312: Level: intermediate
314: .seealso: MFNSetErrorIfNotConverged()
315: @*/
316: PetscErrorCode MFNGetErrorIfNotConverged(MFN mfn,PetscBool *flag)317: {
321: *flag = mfn->errorifnotconverged;
322: return(0);
323: }
325: /*@C
326: MFNSetOptionsPrefix - Sets the prefix used for searching for all
327: MFN options in the database.
329: Logically Collective on MFN331: Input Parameters:
332: + mfn - the matrix function context
333: - prefix - the prefix string to prepend to all MFN option requests
335: Notes:
336: A hyphen (-) must NOT be given at the beginning of the prefix name.
337: The first character of all runtime options is AUTOMATICALLY the
338: hyphen.
340: For example, to distinguish between the runtime options for two
341: different MFN contexts, one could call
342: .vb
343: MFNSetOptionsPrefix(mfn1,"fun1_")
344: MFNSetOptionsPrefix(mfn2,"fun2_")
345: .ve
347: Level: advanced
349: .seealso: MFNAppendOptionsPrefix(), MFNGetOptionsPrefix()
350: @*/
351: PetscErrorCode MFNSetOptionsPrefix(MFN mfn,const char *prefix)352: {
357: if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
358: BVSetOptionsPrefix(mfn->V,prefix);
359: if (!mfn->fn) { MFNGetFN(mfn,&mfn->fn); }
360: FNSetOptionsPrefix(mfn->fn,prefix);
361: PetscObjectSetOptionsPrefix((PetscObject)mfn,prefix);
362: return(0);
363: }
365: /*@C
366: MFNAppendOptionsPrefix - Appends to the prefix used for searching for all
367: MFN options in the database.
369: Logically Collective on MFN371: Input Parameters:
372: + mfn - the matrix function context
373: - prefix - the prefix string to prepend to all MFN option requests
375: Notes:
376: A hyphen (-) must NOT be given at the beginning of the prefix name.
377: The first character of all runtime options is AUTOMATICALLY the hyphen.
379: Level: advanced
381: .seealso: MFNSetOptionsPrefix(), MFNGetOptionsPrefix()
382: @*/
383: PetscErrorCode MFNAppendOptionsPrefix(MFN mfn,const char *prefix)384: {
389: if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
390: BVAppendOptionsPrefix(mfn->V,prefix);
391: if (!mfn->fn) { MFNGetFN(mfn,&mfn->fn); }
392: FNAppendOptionsPrefix(mfn->fn,prefix);
393: PetscObjectAppendOptionsPrefix((PetscObject)mfn,prefix);
394: return(0);
395: }
397: /*@C
398: MFNGetOptionsPrefix - Gets the prefix used for searching for all
399: MFN options in the database.
401: Not Collective
403: Input Parameters:
404: . mfn - the matrix function context
406: Output Parameters:
407: . prefix - pointer to the prefix string used is returned
409: Note:
410: On the Fortran side, the user should pass in a string 'prefix' of
411: sufficient length to hold the prefix.
413: Level: advanced
415: .seealso: MFNSetOptionsPrefix(), MFNAppendOptionsPrefix()
416: @*/
417: PetscErrorCode MFNGetOptionsPrefix(MFN mfn,const char *prefix[])418: {
424: PetscObjectGetOptionsPrefix((PetscObject)mfn,prefix);
425: return(0);
426: }