Actual source code: mfnbasic.c
slepc-3.8.0 2017-10-20
1: /*
2: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
3: SLEPc - Scalable Library for Eigenvalue Problem Computations
4: Copyright (c) 2002-2017, 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: Basic MFN routines
12: */
14: #include <slepc/private/mfnimpl.h> /*I "slepcmfn.h" I*/
16: PetscFunctionList MFNList = 0;
17: PetscBool MFNRegisterAllCalled = PETSC_FALSE;
18: PetscClassId MFN_CLASSID = 0;
19: PetscLogEvent MFN_SetUp = 0,MFN_Solve = 0;
21: /*@C
22: MFNView - Prints the MFN data structure.
24: Collective on MFN
26: Input Parameters:
27: + mfn - the matrix function solver context
28: - viewer - optional visualization context
30: Options Database Key:
31: . -mfn_view - Calls MFNView() at end of MFNSolve()
33: Note:
34: The available visualization contexts include
35: + PETSC_VIEWER_STDOUT_SELF - standard output (default)
36: - PETSC_VIEWER_STDOUT_WORLD - synchronized standard
37: output where only the first processor opens
38: the file. All other processors send their
39: data to the first processor to print.
41: The user can open an alternative visualization context with
42: PetscViewerASCIIOpen() - output to a specified file.
44: Level: beginner
46: .seealso: PetscViewerASCIIOpen()
47: @*/
48: PetscErrorCode MFNView(MFN mfn,PetscViewer viewer)
49: {
51: PetscBool isascii;
55: if (!viewer) viewer = PETSC_VIEWER_STDOUT_(PetscObjectComm((PetscObject)mfn));
59: PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
60: if (isascii) {
61: PetscObjectPrintClassNamePrefixType((PetscObject)mfn,viewer);
62: if (mfn->ops->view) {
63: PetscViewerASCIIPushTab(viewer);
64: (*mfn->ops->view)(mfn,viewer);
65: PetscViewerASCIIPopTab(viewer);
66: }
67: PetscViewerASCIIPrintf(viewer," number of column vectors (ncv): %D\n",mfn->ncv);
68: PetscViewerASCIIPrintf(viewer," maximum number of iterations: %D\n",mfn->max_it);
69: PetscViewerASCIIPrintf(viewer," tolerance: %g\n",(double)mfn->tol);
70: } else {
71: if (mfn->ops->view) {
72: (*mfn->ops->view)(mfn,viewer);
73: }
74: }
75: PetscViewerPushFormat(viewer,PETSC_VIEWER_ASCII_INFO);
76: if (!mfn->V) { MFNGetFN(mfn,&mfn->fn); }
77: FNView(mfn->fn,viewer);
78: if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
79: BVView(mfn->V,viewer);
80: PetscViewerPopFormat(viewer);
81: return(0);
82: }
84: /*@C
85: MFNReasonView - Displays the reason an MFN solve converged or diverged.
87: Collective on MFN
89: Parameter:
90: + mfn - the matrix function context
91: - viewer - the viewer to display the reason
93: Options Database Keys:
94: . -mfn_converged_reason - print reason for convergence, and number of iterations
96: Level: intermediate
98: .seealso: MFNSetTolerances(), MFNGetIterationNumber()
99: @*/
100: PetscErrorCode MFNReasonView(MFN mfn,PetscViewer viewer)
101: {
103: PetscBool isAscii;
106: PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isAscii);
107: if (isAscii) {
108: PetscViewerASCIIAddTab(viewer,((PetscObject)mfn)->tablevel);
109: if (mfn->reason > 0) {
110: PetscViewerASCIIPrintf(viewer,"%s Matrix function solve converged due to %s; iterations %D\n",((PetscObject)mfn)->prefix?((PetscObject)mfn)->prefix:"",MFNConvergedReasons[mfn->reason],mfn->its);
111: } else {
112: PetscViewerASCIIPrintf(viewer,"%s Matrix function solve did not converge due to %s; iterations %D\n",((PetscObject)mfn)->prefix?((PetscObject)mfn)->prefix:"",MFNConvergedReasons[mfn->reason],mfn->its);
113: }
114: PetscViewerASCIISubtractTab(viewer,((PetscObject)mfn)->tablevel);
115: }
116: return(0);
117: }
119: /*@
120: MFNReasonViewFromOptions - Processes command line options to determine if/how
121: the MFN converged reason is to be viewed.
123: Collective on MFN
125: Input Parameters:
126: . mfn - the matrix function context
128: Level: developer
129: @*/
130: PetscErrorCode MFNReasonViewFromOptions(MFN mfn)
131: {
132: PetscErrorCode ierr;
133: PetscViewer viewer;
134: PetscBool flg;
135: static PetscBool incall = PETSC_FALSE;
136: PetscViewerFormat format;
139: if (incall) return(0);
140: incall = PETSC_TRUE;
141: PetscOptionsGetViewer(PetscObjectComm((PetscObject)mfn),((PetscObject)mfn)->prefix,"-mfn_converged_reason",&viewer,&format,&flg);
142: if (flg) {
143: PetscViewerPushFormat(viewer,format);
144: MFNReasonView(mfn,viewer);
145: PetscViewerPopFormat(viewer);
146: PetscViewerDestroy(&viewer);
147: }
148: incall = PETSC_FALSE;
149: return(0);
150: }
152: /*@
153: MFNCreate - Creates the default MFN context.
155: Collective on MPI_Comm
157: Input Parameter:
158: . comm - MPI communicator
160: Output Parameter:
161: . mfn - location to put the MFN context
163: Note:
164: The default MFN type is MFNKRYLOV
166: Level: beginner
168: .seealso: MFNSetUp(), MFNSolve(), MFNDestroy(), MFN
169: @*/
170: PetscErrorCode MFNCreate(MPI_Comm comm,MFN *outmfn)
171: {
173: MFN mfn;
177: *outmfn = 0;
178: MFNInitializePackage();
179: SlepcHeaderCreate(mfn,MFN_CLASSID,"MFN","Matrix Function","MFN",comm,MFNDestroy,MFNView);
181: mfn->A = NULL;
182: mfn->fn = NULL;
183: mfn->max_it = 0;
184: mfn->ncv = 0;
185: mfn->tol = PETSC_DEFAULT;
186: mfn->errorifnotconverged = PETSC_FALSE;
188: mfn->numbermonitors = 0;
190: mfn->V = NULL;
191: mfn->nwork = 0;
192: mfn->work = NULL;
193: mfn->data = NULL;
195: mfn->its = 0;
196: mfn->nv = 0;
197: mfn->errest = 0;
198: mfn->setupcalled = 0;
199: mfn->reason = MFN_CONVERGED_ITERATING;
201: *outmfn = mfn;
202: return(0);
203: }
205: /*@C
206: MFNSetType - Selects the particular solver to be used in the MFN object.
208: Logically Collective on MFN
210: Input Parameters:
211: + mfn - the matrix function context
212: - type - a known method
214: Options Database Key:
215: . -mfn_type <method> - Sets the method; use -help for a list
216: of available methods
218: Notes:
219: See "slepc/include/slepcmfn.h" for available methods. The default
220: is MFNKRYLOV
222: Normally, it is best to use the MFNSetFromOptions() command and
223: then set the MFN type from the options database rather than by using
224: this routine. Using the options database provides the user with
225: maximum flexibility in evaluating the different available methods.
226: The MFNSetType() routine is provided for those situations where it
227: is necessary to set the iterative solver independently of the command
228: line or options database.
230: Level: intermediate
232: .seealso: MFNType
233: @*/
234: PetscErrorCode MFNSetType(MFN mfn,MFNType type)
235: {
236: PetscErrorCode ierr,(*r)(MFN);
237: PetscBool match;
243: PetscObjectTypeCompare((PetscObject)mfn,type,&match);
244: if (match) return(0);
246: PetscFunctionListFind(MFNList,type,&r);
247: if (!r) SETERRQ1(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_UNKNOWN_TYPE,"Unknown MFN type given: %s",type);
249: if (mfn->ops->destroy) { (*mfn->ops->destroy)(mfn); }
250: PetscMemzero(mfn->ops,sizeof(struct _MFNOps));
252: mfn->setupcalled = 0;
253: PetscObjectChangeTypeName((PetscObject)mfn,type);
254: (*r)(mfn);
255: return(0);
256: }
258: /*@C
259: MFNGetType - Gets the MFN type as a string from the MFN object.
261: Not Collective
263: Input Parameter:
264: . mfn - the matrix function context
266: Output Parameter:
267: . name - name of MFN method
269: Level: intermediate
271: .seealso: MFNSetType()
272: @*/
273: PetscErrorCode MFNGetType(MFN mfn,MFNType *type)
274: {
278: *type = ((PetscObject)mfn)->type_name;
279: return(0);
280: }
282: /*@C
283: MFNRegister - Adds a method to the matrix function solver package.
285: Not Collective
287: Input Parameters:
288: + name - name of a new user-defined solver
289: - function - routine to create the solver context
291: Notes:
292: MFNRegister() may be called multiple times to add several user-defined solvers.
294: Sample usage:
295: .vb
296: MFNRegister("my_solver",MySolverCreate);
297: .ve
299: Then, your solver can be chosen with the procedural interface via
300: $ MFNSetType(mfn,"my_solver")
301: or at runtime via the option
302: $ -mfn_type my_solver
304: Level: advanced
306: .seealso: MFNRegisterAll()
307: @*/
308: PetscErrorCode MFNRegister(const char *name,PetscErrorCode (*function)(MFN))
309: {
313: PetscFunctionListAdd(&MFNList,name,function);
314: return(0);
315: }
317: /*@
318: MFNReset - Resets the MFN context to the initial state (prior to setup)
319: and destroys any allocated Vecs and Mats.
321: Collective on MFN
323: Input Parameter:
324: . mfn - matrix function context obtained from MFNCreate()
326: Level: advanced
328: .seealso: MFNDestroy()
329: @*/
330: PetscErrorCode MFNReset(MFN mfn)
331: {
336: if (!mfn) return(0);
337: if (mfn->ops->reset) { (mfn->ops->reset)(mfn); }
338: MatDestroy(&mfn->A);
339: BVDestroy(&mfn->V);
340: VecDestroyVecs(mfn->nwork,&mfn->work);
341: mfn->nwork = 0;
342: mfn->setupcalled = 0;
343: return(0);
344: }
346: /*@
347: MFNDestroy - Destroys the MFN context.
349: Collective on MFN
351: Input Parameter:
352: . mfn - matrix function context obtained from MFNCreate()
354: Level: beginner
356: .seealso: MFNCreate(), MFNSetUp(), MFNSolve()
357: @*/
358: PetscErrorCode MFNDestroy(MFN *mfn)
359: {
363: if (!*mfn) return(0);
365: if (--((PetscObject)(*mfn))->refct > 0) { *mfn = 0; return(0); }
366: MFNReset(*mfn);
367: if ((*mfn)->ops->destroy) { (*(*mfn)->ops->destroy)(*mfn); }
368: FNDestroy(&(*mfn)->fn);
369: MFNMonitorCancel(*mfn);
370: PetscHeaderDestroy(mfn);
371: return(0);
372: }
374: /*@
375: MFNSetBV - Associates a basis vectors object to the matrix function solver.
377: Collective on MFN
379: Input Parameters:
380: + mfn - matrix function context obtained from MFNCreate()
381: - bv - the basis vectors object
383: Note:
384: Use MFNGetBV() to retrieve the basis vectors context (for example,
385: to free it at the end of the computations).
387: Level: advanced
389: .seealso: MFNGetBV()
390: @*/
391: PetscErrorCode MFNSetBV(MFN mfn,BV bv)
392: {
399: PetscObjectReference((PetscObject)bv);
400: BVDestroy(&mfn->V);
401: mfn->V = bv;
402: PetscLogObjectParent((PetscObject)mfn,(PetscObject)mfn->V);
403: return(0);
404: }
406: /*@
407: MFNGetBV - Obtain the basis vectors object associated to the matrix
408: function solver.
410: Not Collective
412: Input Parameters:
413: . mfn - matrix function context obtained from MFNCreate()
415: Output Parameter:
416: . bv - basis vectors context
418: Level: advanced
420: .seealso: MFNSetBV()
421: @*/
422: PetscErrorCode MFNGetBV(MFN mfn,BV *bv)
423: {
429: if (!mfn->V) {
430: BVCreate(PetscObjectComm((PetscObject)mfn),&mfn->V);
431: PetscLogObjectParent((PetscObject)mfn,(PetscObject)mfn->V);
432: }
433: *bv = mfn->V;
434: return(0);
435: }
437: /*@
438: MFNSetFN - Specifies the function to be computed.
440: Collective on MFN
442: Input Parameters:
443: + mfn - matrix function context obtained from MFNCreate()
444: - fn - the math function object
446: Note:
447: Use MFNGetFN() to retrieve the math function context (for example,
448: to free it at the end of the computations).
450: Level: beginner
452: .seealso: MFNGetFN()
453: @*/
454: PetscErrorCode MFNSetFN(MFN mfn,FN fn)
455: {
462: PetscObjectReference((PetscObject)fn);
463: FNDestroy(&mfn->fn);
464: mfn->fn = fn;
465: PetscLogObjectParent((PetscObject)mfn,(PetscObject)mfn->fn);
466: return(0);
467: }
469: /*@
470: MFNGetFN - Obtain the math function object associated to the MFN object.
472: Not Collective
474: Input Parameters:
475: . mfn - matrix function context obtained from MFNCreate()
477: Output Parameter:
478: . fn - math function context
480: Level: beginner
482: .seealso: MFNSetFN()
483: @*/
484: PetscErrorCode MFNGetFN(MFN mfn,FN *fn)
485: {
491: if (!mfn->fn) {
492: FNCreate(PetscObjectComm((PetscObject)mfn),&mfn->fn);
493: PetscLogObjectParent((PetscObject)mfn,(PetscObject)mfn->fn);
494: }
495: *fn = mfn->fn;
496: return(0);
497: }