1: /*
2: The basic MFN routines, Create, View, etc. are here.
4: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
5: SLEPc - Scalable Library for Eigenvalue Problem Computations
6: Copyright (c) 2002-2014, Universitat Politecnica de Valencia, Spain
8: This file is part of SLEPc.
10: SLEPc is free software: you can redistribute it and/or modify it under the
11: terms of version 3 of the GNU Lesser General Public License as published by
12: the Free Software Foundation.
14: SLEPc is distributed in the hope that it will be useful, but WITHOUT ANY
15: WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
16: FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
17: more details.
19: You should have received a copy of the GNU Lesser General Public License
20: along with SLEPc. If not, see <http://www.gnu.org/licenses/>.
21: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
22: */
24: #include <slepc-private/mfnimpl.h> /*I "slepcmfn.h" I*/
26: PetscFunctionList MFNList = 0;
27: PetscBool MFNRegisterAllCalled = PETSC_FALSE;
28: PetscClassId MFN_CLASSID = 0;
29: PetscLogEvent MFN_SetUp = 0,MFN_Solve = 0;
33: /*@C
34: MFNView - Prints the MFN data structure.
36: Collective on MFN 38: Input Parameters:
39: + mfn - the matrix function solver context
40: - viewer - optional visualization context
42: Options Database Key:
43: . -mfn_view - Calls MFNView() at end of MFNSolve()
45: Note:
46: The available visualization contexts include
47: + PETSC_VIEWER_STDOUT_SELF - standard output (default)
48: - PETSC_VIEWER_STDOUT_WORLD - synchronized standard
49: output where only the first processor opens
50: the file. All other processors send their
51: data to the first processor to print.
53: The user can open an alternative visualization context with
54: PetscViewerASCIIOpen() - output to a specified file.
56: Level: beginner
58: .seealso: PetscViewerASCIIOpen()
59: @*/
60: PetscErrorCode MFNView(MFN mfn,PetscViewer viewer) 61: {
63: const char *fun;
64: char str[50];
65: PetscBool isascii;
69: if (!viewer) viewer = PETSC_VIEWER_STDOUT_(PetscObjectComm((PetscObject)mfn));
73: PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
74: if (isascii) {
75: PetscObjectPrintClassNamePrefixType((PetscObject)mfn,viewer);
76: if (mfn->ops->view) {
77: PetscViewerASCIIPushTab(viewer);
78: (*mfn->ops->view)(mfn,viewer);
79: PetscViewerASCIIPopTab(viewer);
80: }
81: if (mfn->function) {
82: switch (mfn->function) {
83: case SLEPC_FUNCTION_EXP: fun = "exponential"; break;
84: default: SETERRQ(PetscObjectComm((PetscObject)mfn),1,"Wrong value of mfn->function");
85: }
86: } else fun = "not yet set";
87: PetscViewerASCIIPrintf(viewer," function: %s\n",fun);
88: PetscViewerASCIIPrintf(viewer," number of column vectors (ncv): %D\n",mfn->ncv);
89: PetscViewerASCIIPrintf(viewer," maximum number of iterations: %D\n",mfn->max_it);
90: PetscViewerASCIIPrintf(viewer," tolerance: %g\n",(double)mfn->tol);
91: SlepcSNPrintfScalar(str,50,mfn->sfactor,PETSC_FALSE);
92: PetscViewerASCIIPrintf(viewer," scaling factor: %s\n",str);
93: } else {
94: if (mfn->ops->view) {
95: (*mfn->ops->view)(mfn,viewer);
96: }
97: }
98: PetscViewerPushFormat(viewer,PETSC_VIEWER_ASCII_INFO);
99: if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
100: BVView(mfn->V,viewer);
101: if (!mfn->ds) { MFNGetDS(mfn,&mfn->ds); }
102: DSView(mfn->ds,viewer);
103: PetscViewerPopFormat(viewer);
104: return(0);
105: }
109: /*@C
110: MFNCreate - Creates the default MFN context.
112: Collective on MPI_Comm
114: Input Parameter:
115: . comm - MPI communicator
117: Output Parameter:
118: . mfn - location to put the MFN context
120: Note:
121: The default MFN type is MFNKRYLOV
123: Level: beginner
125: .seealso: MFNSetUp(), MFNSolve(), MFNDestroy(), MFN126: @*/
127: PetscErrorCode MFNCreate(MPI_Comm comm,MFN *outmfn)128: {
130: MFN mfn;
134: *outmfn = 0;
135: MFNInitializePackage();
136: SlepcHeaderCreate(mfn,_p_MFN,struct _MFNOps,MFN_CLASSID,"MFN","Matrix Function","MFN",comm,MFNDestroy,MFNView);
138: mfn->A = NULL;
139: mfn->max_it = 0;
140: mfn->ncv = 0;
141: mfn->tol = PETSC_DEFAULT;
142: mfn->function = (SlepcFunction)0;
143: mfn->sfactor = 1.0;
144: mfn->errorifnotconverged = PETSC_FALSE;
146: mfn->numbermonitors = 0;
148: mfn->ds = NULL;
149: mfn->V = NULL;
150: mfn->rand = NULL;
151: mfn->nwork = 0;
152: mfn->work = NULL;
153: mfn->data = NULL;
155: mfn->its = 0;
156: mfn->nv = 0;
157: mfn->errest = 0;
158: mfn->setupcalled = 0;
159: mfn->reason = MFN_CONVERGED_ITERATING;
161: PetscRandomCreate(comm,&mfn->rand);
162: PetscRandomSetSeed(mfn->rand,0x12345678);
163: PetscLogObjectParent((PetscObject)mfn,(PetscObject)mfn->rand);
164: *outmfn = mfn;
165: return(0);
166: }
170: /*@C
171: MFNSetType - Selects the particular solver to be used in the MFN object.
173: Logically Collective on MFN175: Input Parameters:
176: + mfn - the matrix function context
177: - type - a known method
179: Options Database Key:
180: . -mfn_type <method> - Sets the method; use -help for a list
181: of available methods
183: Notes:
184: See "slepc/include/slepcmfn.h" for available methods. The default
185: is MFNKRYLOV
187: Normally, it is best to use the MFNSetFromOptions() command and
188: then set the MFN type from the options database rather than by using
189: this routine. Using the options database provides the user with
190: maximum flexibility in evaluating the different available methods.
191: The MFNSetType() routine is provided for those situations where it
192: is necessary to set the iterative solver independently of the command
193: line or options database.
195: Level: intermediate
197: .seealso: MFNType198: @*/
199: PetscErrorCode MFNSetType(MFN mfn,MFNType type)200: {
201: PetscErrorCode ierr,(*r)(MFN);
202: PetscBool match;
208: PetscObjectTypeCompare((PetscObject)mfn,type,&match);
209: if (match) return(0);
211: PetscFunctionListFind(MFNList,type,&r);
212: if (!r) SETERRQ1(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_UNKNOWN_TYPE,"Unknown MFN type given: %s",type);
214: if (mfn->ops->destroy) { (*mfn->ops->destroy)(mfn); }
215: PetscMemzero(mfn->ops,sizeof(struct _MFNOps));
217: mfn->setupcalled = 0;
218: PetscObjectChangeTypeName((PetscObject)mfn,type);
219: (*r)(mfn);
220: return(0);
221: }
225: /*@C
226: MFNGetType - Gets the MFN type as a string from the MFN object.
228: Not Collective
230: Input Parameter:
231: . mfn - the matrix function context
233: Output Parameter:
234: . name - name of MFN method
236: Level: intermediate
238: .seealso: MFNSetType()
239: @*/
240: PetscErrorCode MFNGetType(MFN mfn,MFNType *type)241: {
245: *type = ((PetscObject)mfn)->type_name;
246: return(0);
247: }
251: /*@C
252: MFNRegister - Adds a method to the matrix function solver package.
254: Not Collective
256: Input Parameters:
257: + name - name of a new user-defined solver
258: - function - routine to create the solver context
260: Notes:
261: MFNRegister() may be called multiple times to add several user-defined solvers.
263: Sample usage:
264: .vb
265: MFNRegister("my_solver",MySolverCreate);
266: .ve
268: Then, your solver can be chosen with the procedural interface via
269: $ MFNSetType(mfn,"my_solver")
270: or at runtime via the option
271: $ -mfn_type my_solver
273: Level: advanced
275: .seealso: MFNRegisterAll()
276: @*/
277: PetscErrorCode MFNRegister(const char *name,PetscErrorCode (*function)(MFN))278: {
282: PetscFunctionListAdd(&MFNList,name,function);
283: return(0);
284: }
288: /*@
289: MFNReset - Resets the MFN context to the setupcalled=0 state and removes any
290: allocated objects.
292: Collective on MFN294: Input Parameter:
295: . mfn - matrix function context obtained from MFNCreate()
297: Level: advanced
299: .seealso: MFNDestroy()
300: @*/
301: PetscErrorCode MFNReset(MFN mfn)302: {
307: if (mfn->ops->reset) { (mfn->ops->reset)(mfn); }
308: if (mfn->ds) { DSReset(mfn->ds); }
309: mfn->setupcalled = 0;
310: return(0);
311: }
315: /*@C
316: MFNDestroy - Destroys the MFN context.
318: Collective on MFN320: Input Parameter:
321: . mfn - matrix function context obtained from MFNCreate()
323: Level: beginner
325: .seealso: MFNCreate(), MFNSetUp(), MFNSolve()
326: @*/
327: PetscErrorCode MFNDestroy(MFN *mfn)328: {
332: if (!*mfn) return(0);
334: if (--((PetscObject)(*mfn))->refct > 0) { *mfn = 0; return(0); }
335: MFNReset(*mfn);
336: if ((*mfn)->ops->destroy) { (*(*mfn)->ops->destroy)(*mfn); }
337: MatDestroy(&(*mfn)->A);
338: BVDestroy(&(*mfn)->V);
339: DSDestroy(&(*mfn)->ds);
340: PetscRandomDestroy(&(*mfn)->rand);
341: MFNMonitorCancel(*mfn);
342: PetscHeaderDestroy(mfn);
343: return(0);
344: }
348: /*@
349: MFNSetBV - Associates a basis vectors object to the matrix function solver.
351: Collective on MFN353: Input Parameters:
354: + mfn - matrix function context obtained from MFNCreate()
355: - bv - the basis vectors object
357: Note:
358: Use MFNGetBV() to retrieve the basis vectors context (for example,
359: to free it at the end of the computations).
361: Level: advanced
363: .seealso: MFNGetBV()
364: @*/
365: PetscErrorCode MFNSetBV(MFN mfn,BV bv)366: {
373: PetscObjectReference((PetscObject)bv);
374: BVDestroy(&mfn->V);
375: mfn->V = bv;
376: PetscLogObjectParent((PetscObject)mfn,(PetscObject)mfn->V);
377: return(0);
378: }
382: /*@C
383: MFNGetBV - Obtain the basis vectors object associated to the matrix
384: function solver.
386: Not Collective
388: Input Parameters:
389: . mfn - matrix function context obtained from MFNCreate()
391: Output Parameter:
392: . bv - basis vectors context
394: Level: advanced
396: .seealso: MFNSetBV()
397: @*/
398: PetscErrorCode MFNGetBV(MFN mfn,BV *bv)399: {
405: if (!mfn->V) {
406: BVCreate(PetscObjectComm((PetscObject)mfn),&mfn->V);
407: PetscLogObjectParent((PetscObject)mfn,(PetscObject)mfn->V);
408: }
409: *bv = mfn->V;
410: return(0);
411: }
415: /*@
416: MFNSetDS - Associates a direct solver object to the matrix function solver.
418: Collective on MFN420: Input Parameters:
421: + mfn - matrix function context obtained from MFNCreate()
422: - ds - the direct solver object
424: Note:
425: Use MFNGetDS() to retrieve the direct solver context (for example,
426: to free it at the end of the computations).
428: Level: advanced
430: .seealso: MFNGetDS()
431: @*/
432: PetscErrorCode MFNSetDS(MFN mfn,DS ds)433: {
440: PetscObjectReference((PetscObject)ds);
441: DSDestroy(&mfn->ds);
442: mfn->ds = ds;
443: PetscLogObjectParent((PetscObject)mfn,(PetscObject)mfn->ds);
444: return(0);
445: }
449: /*@C
450: MFNGetDS - Obtain the direct solver object associated to the matrix function object.
452: Not Collective
454: Input Parameters:
455: . mfn - matrix function context obtained from MFNCreate()
457: Output Parameter:
458: . ds - direct solver context
460: Level: advanced
462: .seealso: MFNSetDS()
463: @*/
464: PetscErrorCode MFNGetDS(MFN mfn,DS *ds)465: {
471: if (!mfn->ds) {
472: DSCreate(PetscObjectComm((PetscObject)mfn),&mfn->ds);
473: PetscLogObjectParent((PetscObject)mfn,(PetscObject)mfn->ds);
474: }
475: *ds = mfn->ds;
476: return(0);
477: }