Actual source code: mfnopts.c
1: /*
2: MFN routines related to options that can be set via the command-line
3: or procedurally.
5: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
6: SLEPc - Scalable Library for Eigenvalue Problem Computations
7: Copyright (c) 2002-2013, Universitat Politecnica de Valencia, Spain
9: This file is part of SLEPc.
11: SLEPc is free software: you can redistribute it and/or modify it under the
12: terms of version 3 of the GNU Lesser General Public License as published by
13: the Free Software Foundation.
15: SLEPc is distributed in the hope that it will be useful, but WITHOUT ANY
16: WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17: FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
18: more details.
20: You should have received a copy of the GNU Lesser General Public License
21: along with SLEPc. If not, see <http://www.gnu.org/licenses/>.
22: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
23: */
25: #include <slepc-private/mfnimpl.h> /*I "slepcmfn.h" I*/
29: /*@
30: MFNSetFromOptions - Sets MFN options from the options database.
31: This routine must be called before MFNSetUp() if the user is to be
32: allowed to set the solver type.
34: Collective on MFN
36: Input Parameters:
37: . mfn - the matrix function context
39: Notes:
40: To see all options, run your program with the -help option.
42: Level: beginner
43: @*/
44: PetscErrorCode MFNSetFromOptions(MFN mfn)
45: {
46: PetscErrorCode ierr;
47: char type[256],monfilename[PETSC_MAX_PATH_LEN];
48: PetscBool flg;
49: PetscReal r;
50: PetscInt i;
51: PetscViewer monviewer;
55: if (!MFNRegisterAllCalled) { MFNRegisterAll(); }
56: PetscObjectOptionsBegin((PetscObject)mfn);
57: PetscOptionsList("-mfn_type","Matrix Function method","MFNSetType",MFNList,(char*)(((PetscObject)mfn)->type_name?((PetscObject)mfn)->type_name:MFNKRYLOV),type,256,&flg);
58: if (flg) {
59: MFNSetType(mfn,type);
60: }
61: /*
62: Set the type if it was never set.
63: */
64: if (!((PetscObject)mfn)->type_name) {
65: MFNSetType(mfn,MFNKRYLOV);
66: }
68: PetscOptionsBoolGroupBegin("-mfn_exp","matrix exponential","MFNSetFunction",&flg);
69: if (flg) {
70: MFNSetFunction(mfn,SLEPC_FUNCTION_EXP);
71: }
73: PetscOptionsScalar("-mfn_scale","Scale factor","MFNSetScaleFactor",mfn->sfactor,&mfn->sfactor,NULL);
75: r = i = 0;
76: PetscOptionsInt("-mfn_max_it","Maximum number of iterations","MFNSetTolerances",mfn->max_it,&i,NULL);
77: PetscOptionsReal("-mfn_tol","Tolerance","MFNSetTolerances",mfn->tol==PETSC_DEFAULT?SLEPC_DEFAULT_TOL:mfn->tol,&r,NULL);
78: MFNSetTolerances(mfn,r,i);
80: i = 0;
81: PetscOptionsInt("-mfn_ncv","Number of basis vectors","MFNSetDimensions",mfn->ncv,&i,NULL);
82: MFNSetDimensions(mfn,i);
84: PetscOptionsBool("-mfn_error_if_not_converged","Generate error if solver does not converge","MFNSetErrorIfNotConverged",mfn->errorifnotconverged,&mfn->errorifnotconverged,NULL);
86: /* -----------------------------------------------------------------------*/
87: /*
88: Cancels all monitors hardwired into code before call to MFNSetFromOptions()
89: */
90: flg = PETSC_FALSE;
91: PetscOptionsBool("-mfn_monitor_cancel","Remove any hardwired monitor routines","MFNMonitorCancel",flg,&flg,NULL);
92: if (flg) {
93: MFNMonitorCancel(mfn);
94: }
95: /*
96: Prints error estimate at each iteration
97: */
98: PetscOptionsString("-mfn_monitor","Monitor error estimate","MFNMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
99: if (flg) {
100: PetscViewerASCIIOpen(PetscObjectComm((PetscObject)mfn),monfilename,&monviewer);
101: MFNMonitorSet(mfn,MFNMonitorDefault,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
102: }
103: flg = PETSC_FALSE;
104: PetscOptionsBool("-mfn_monitor_lg","Monitor error estimate graphically","MFNMonitorSet",flg,&flg,NULL);
105: if (flg) {
106: MFNMonitorSet(mfn,MFNMonitorLG,NULL,NULL);
107: }
108: /* -----------------------------------------------------------------------*/
110: PetscOptionsName("-mfn_view","Print detailed information on solver used","MFNView",0);
112: if (mfn->ops->setfromoptions) {
113: (*mfn->ops->setfromoptions)(mfn);
114: }
115: PetscObjectProcessOptionsHandlers((PetscObject)mfn);
116: PetscOptionsEnd();
118: if (!mfn->ip) { MFNGetIP(mfn,&mfn->ip); }
119: IPSetFromOptions(mfn->ip);
120: if (!mfn->ds) { MFNGetDS(mfn,&mfn->ds); }
121: DSSetFromOptions(mfn->ds);
122: PetscRandomSetFromOptions(mfn->rand);
123: return(0);
124: }
128: /*@
129: MFNGetTolerances - Gets the tolerance and maximum iteration count used
130: by the MFN convergence tests.
132: Not Collective
134: Input Parameter:
135: . mfn - the matrix function context
137: Output Parameters:
138: + tol - the convergence tolerance
139: - maxits - maximum number of iterations
141: Notes:
142: The user can specify NULL for any parameter that is not needed.
144: Level: intermediate
146: .seealso: MFNSetTolerances()
147: @*/
148: PetscErrorCode MFNGetTolerances(MFN mfn,PetscReal *tol,PetscInt *maxits)
149: {
152: if (tol) *tol = mfn->tol;
153: if (maxits) *maxits = mfn->max_it;
154: return(0);
155: }
159: /*@
160: MFNSetTolerances - Sets the tolerance and maximum iteration count used
161: by the MFN convergence tests.
163: Logically Collective on MFN
165: Input Parameters:
166: + mfn - the matrix function context
167: . tol - the convergence tolerance
168: - maxits - maximum number of iterations to use
170: Options Database Keys:
171: + -mfn_tol <tol> - Sets the convergence tolerance
172: - -mfn_max_it <maxits> - Sets the maximum number of iterations allowed
174: Notes:
175: Pass 0 for an argument that need not be changed.
177: Use PETSC_DECIDE for maxits to assign a reasonably good value, which is
178: dependent on the solution method.
180: Level: intermediate
182: .seealso: MFNGetTolerances()
183: @*/
184: PetscErrorCode MFNSetTolerances(MFN mfn,PetscReal tol,PetscInt maxits)
185: {
190: if (tol) {
191: if (tol == PETSC_DEFAULT) {
192: mfn->tol = PETSC_DEFAULT;
193: } else {
194: if (tol < 0.0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of tol. Must be > 0");
195: mfn->tol = tol;
196: }
197: }
198: if (maxits) {
199: if (maxits == PETSC_DEFAULT || maxits == PETSC_DECIDE) {
200: mfn->max_it = 0;
201: mfn->setupcalled = 0;
202: } else {
203: if (maxits < 0) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of maxits. Must be > 0");
204: mfn->max_it = maxits;
205: }
206: }
207: return(0);
208: }
212: /*@
213: MFNGetDimensions - Gets the dimension of the subspace used by the solver.
215: Not Collective
217: Input Parameter:
218: . mfn - the matrix function context
220: Output Parameter:
221: . ncv - the maximum dimension of the subspace to be used by the solver
223: Level: intermediate
225: .seealso: MFNSetDimensions()
226: @*/
227: PetscErrorCode MFNGetDimensions(MFN mfn,PetscInt *ncv)
228: {
232: *ncv = mfn->ncv;
233: return(0);
234: }
238: /*@
239: MFNSetDimensions - Sets the dimension of the subspace to be used by the solver.
241: Logically Collective on MFN
243: Input Parameters:
244: + mfn - the matrix function context
245: - ncv - the maximum dimension of the subspace to be used by the solver
247: Options Database Keys:
248: . -mfn_ncv <ncv> - Sets the dimension of the subspace
250: Notes:
251: Use PETSC_DECIDE for ncv to assign a reasonably good value, which is
252: dependent on the solution method.
254: Level: intermediate
256: .seealso: MFNGetDimensions()
257: @*/
258: PetscErrorCode MFNSetDimensions(MFN mfn,PetscInt ncv)
259: {
263: if (ncv) {
264: if (ncv == PETSC_DECIDE || ncv == PETSC_DEFAULT) {
265: mfn->ncv = 0;
266: } else {
267: if (ncv<1) SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_OUTOFRANGE,"Illegal value of ncv. Must be > 0");
268: mfn->ncv = ncv;
269: }
270: mfn->setupcalled = 0;
271: }
272: return(0);
273: }
277: /*@
278: MFNSetFunction - Specifies the function to be computed.
280: Logically Collective on MFN
282: Input Parameters:
283: + mfn - the matrix function context
284: - fun - a known function
286: Options Database Keys:
287: . -mfn_exp - matrix exponential
289: Level: beginner
291: .seealso: MFNSetOperator(), MFNSetType(), MFNGetFunction(), SlepcFunction
292: @*/
293: PetscErrorCode MFNSetFunction(MFN mfn,SlepcFunction fun)
294: {
298: switch (fun) {
299: case SLEPC_FUNCTION_EXP:
300: break;
301: default:
302: SETERRQ(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_WRONG,"Unknown function");
303: }
304: mfn->function = fun;
305: return(0);
306: }
310: /*@C
311: MFNGetFunction - Gets the function from the MFN object.
313: Not Collective
315: Input Parameter:
316: . mfn - the matrix function context
318: Output Parameter:
319: . fun - function
321: Level: intermediate
323: .seealso: MFNSetFunction(), SlepcFunction
324: @*/
325: PetscErrorCode MFNGetFunction(MFN mfn,SlepcFunction *fun)
326: {
330: *fun = mfn->function;
331: return(0);
332: }
336: /*@
337: MFNSetScaleFactor - Sets the scale factor to multiply the matrix (the
338: argument of the function).
340: Logically Collective on MFN
342: Input Parameters:
343: + mfn - the matrix function context
344: - alpha - the scaling factor
346: Options Database Keys:
347: . -mfn_scale <alpha> - Sets the scaling factor
349: Notes:
350: The computed result is f(alpha*A)*b. The default is alpha=1.0.
352: Level: intermediate
354: .seealso: MFNGetScaleFactor(), MFNSolve()
355: @*/
356: PetscErrorCode MFNSetScaleFactor(MFN mfn,PetscScalar alpha)
357: {
361: mfn->sfactor = alpha;
362: return(0);
363: }
367: /*@
368: MFNGetScaleFactor - Gets the factor used for scaling the matrix.
370: Not Collective
372: Input Parameter:
373: . mfn - the matrix function context
375: Output Parameters:
376: . alpha - the scaling factor
378: Level: intermediate
380: .seealso: MFNSetScaleFactor(), MFNSolve()
381: @*/
382: PetscErrorCode MFNGetScaleFactor(MFN mfn,PetscScalar *alpha)
383: {
387: *alpha = mfn->sfactor;
388: return(0);
389: }
393: /*@
394: MFNSetErrorIfNotConverged - Causes MFNSolve() to generate an error if the
395: solver has not converged.
397: Logically Collective on MFN
399: Input Parameters:
400: + mfn - the matrix function context
401: - flg - PETSC_TRUE indicates you want the error generated
403: Options Database Keys:
404: . -mfn_error_if_not_converged - this takes an optional truth value (0/1/no/yes/true/false)
406: Level: intermediate
408: Note:
409: Normally SLEPc continues if the solver fails to converge, you can call
410: MFNGetConvergedReason() after a MFNSolve() to determine if it has converged.
412: .seealso: MFNGetErrorIfNotConverged()
413: @*/
414: PetscErrorCode MFNSetErrorIfNotConverged(MFN mfn,PetscBool flg)
415: {
419: mfn->errorifnotconverged = flg;
420: return(0);
421: }
425: /*@
426: MFNGetErrorIfNotConverged - Return a flag indicating whether MFNSolve() will
427: generate an error if the solver does not converge.
429: Not Collective
431: Input Parameter:
432: . mfn - the matrix function context
434: Output Parameter:
435: . flag - PETSC_TRUE if it will generate an error, else PETSC_FALSE
437: Level: intermediate
439: .seealso: MFNSetErrorIfNotConverged()
440: @*/
441: PetscErrorCode MFNGetErrorIfNotConverged(MFN mfn,PetscBool *flag)
442: {
446: *flag = mfn->errorifnotconverged;
447: return(0);
448: }
452: /*@C
453: MFNSetOptionsPrefix - Sets the prefix used for searching for all
454: MFN options in the database.
456: Logically Collective on MFN
458: Input Parameters:
459: + mfn - the matrix function context
460: - prefix - the prefix string to prepend to all MFN option requests
462: Notes:
463: A hyphen (-) must NOT be given at the beginning of the prefix name.
464: The first character of all runtime options is AUTOMATICALLY the
465: hyphen.
467: For example, to distinguish between the runtime options for two
468: different MFN contexts, one could call
469: .vb
470: MFNSetOptionsPrefix(mfn1,"fun1_")
471: MFNSetOptionsPrefix(mfn2,"fun2_")
472: .ve
474: Level: advanced
476: .seealso: MFNAppendOptionsPrefix(), MFNGetOptionsPrefix()
477: @*/
478: PetscErrorCode MFNSetOptionsPrefix(MFN mfn,const char *prefix)
479: {
484: if (!mfn->ip) { MFNGetIP(mfn,&mfn->ip); }
485: IPSetOptionsPrefix(mfn->ip,prefix);
486: if (!mfn->ds) { MFNGetDS(mfn,&mfn->ds); }
487: DSSetOptionsPrefix(mfn->ds,prefix);
488: PetscObjectSetOptionsPrefix((PetscObject)mfn,prefix);
489: return(0);
490: }
494: /*@C
495: MFNAppendOptionsPrefix - Appends to the prefix used for searching for all
496: MFN options in the database.
498: Logically Collective on MFN
500: Input Parameters:
501: + mfn - the matrix function context
502: - prefix - the prefix string to prepend to all MFN option requests
504: Notes:
505: A hyphen (-) must NOT be given at the beginning of the prefix name.
506: The first character of all runtime options is AUTOMATICALLY the hyphen.
508: Level: advanced
510: .seealso: MFNSetOptionsPrefix(), MFNGetOptionsPrefix()
511: @*/
512: PetscErrorCode MFNAppendOptionsPrefix(MFN mfn,const char *prefix)
513: {
518: if (!mfn->ip) { MFNGetIP(mfn,&mfn->ip); }
519: IPSetOptionsPrefix(mfn->ip,prefix);
520: if (!mfn->ds) { MFNGetDS(mfn,&mfn->ds); }
521: DSSetOptionsPrefix(mfn->ds,prefix);
522: PetscObjectAppendOptionsPrefix((PetscObject)mfn,prefix);
523: return(0);
524: }
528: /*@C
529: MFNGetOptionsPrefix - Gets the prefix used for searching for all
530: MFN options in the database.
532: Not Collective
534: Input Parameters:
535: . mfn - the matrix function context
537: Output Parameters:
538: . prefix - pointer to the prefix string used is returned
540: Notes: On the fortran side, the user should pass in a string 'prefix' of
541: sufficient length to hold the prefix.
543: Level: advanced
545: .seealso: MFNSetOptionsPrefix(), MFNAppendOptionsPrefix()
546: @*/
547: PetscErrorCode MFNGetOptionsPrefix(MFN mfn,const char *prefix[])
548: {
554: PetscObjectGetOptionsPrefix((PetscObject)mfn,prefix);
555: return(0);
556: }