Actual source code: mfnbasic.c

  1: /*
  2:      The basic MFN routines, Create, View, etc. are here.

  4:    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  5:    SLEPc - Scalable Library for Eigenvalue Problem Computations
  6:    Copyright (c) 2002-2013, 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;
 30: static PetscBool  MFNPackageInitialized = PETSC_FALSE;

 34: /*@C
 35:   MFNFinalizePackage - This function destroys everything in the SLEPc interface
 36:   to the MFN package. It is called from SlepcFinalize().

 38:   Level: developer

 40: .seealso: SlepcFinalize()
 41: @*/
 42: PetscErrorCode MFNFinalizePackage(void)
 43: {

 47:   PetscFunctionListDestroy(&MFNList);
 48:   MFNPackageInitialized = PETSC_FALSE;
 49:   MFNRegisterAllCalled  = PETSC_FALSE;
 50:   return(0);
 51: }

 55: /*@C
 56:   MFNInitializePackage - This function initializes everything in the MFN package.
 57:   It is called from PetscDLLibraryRegister() when using dynamic libraries, and
 58:   on the first call to MFNCreate() when using static libraries.

 60:   Level: developer

 62: .seealso: SlepcInitialize()
 63: @*/
 64: PetscErrorCode MFNInitializePackage(void)
 65: {
 66:   char           logList[256];
 67:   char           *className;
 68:   PetscBool      opt;

 72:   if (MFNPackageInitialized) return(0);
 73:   MFNPackageInitialized = PETSC_TRUE;
 74:   /* Register Classes */
 75:   PetscClassIdRegister("Matrix Function",&MFN_CLASSID);
 76:   /* Register Constructors */
 77:   MFNRegisterAll();
 78:   /* Register Events */
 79:   PetscLogEventRegister("MFNSetUp",MFN_CLASSID,&MFN_SetUp);
 80:   PetscLogEventRegister("MFNSolve",MFN_CLASSID,&MFN_Solve);
 81:   /* Process info exclusions */
 82:   PetscOptionsGetString(NULL,"-info_exclude",logList,256,&opt);
 83:   if (opt) {
 84:     PetscStrstr(logList,"mfn",&className);
 85:     if (className) {
 86:       PetscInfoDeactivateClass(MFN_CLASSID);
 87:     }
 88:   }
 89:   /* Process summary exclusions */
 90:   PetscOptionsGetString(NULL,"-log_summary_exclude",logList,256,&opt);
 91:   if (opt) {
 92:     PetscStrstr(logList,"mfn",&className);
 93:     if (className) {
 94:       PetscLogEventDeactivateClass(MFN_CLASSID);
 95:     }
 96:   }
 97:   PetscRegisterFinalize(MFNFinalizePackage);
 98:   return(0);
 99: }

103: /*@C
104:    MFNView - Prints the MFN data structure.

106:    Collective on MFN

108:    Input Parameters:
109: +  mfn - the matrix function solver context
110: -  viewer - optional visualization context

112:    Options Database Key:
113: .  -mfn_view -  Calls MFNView() at end of MFNSolve()

115:    Note:
116:    The available visualization contexts include
117: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
118: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
119:          output where only the first processor opens
120:          the file.  All other processors send their
121:          data to the first processor to print.

123:    The user can open an alternative visualization context with
124:    PetscViewerASCIIOpen() - output to a specified file.

126:    Level: beginner

128: .seealso: PetscViewerASCIIOpen()
129: @*/
130: PetscErrorCode MFNView(MFN mfn,PetscViewer viewer)
131: {
133:   const char     *fun;
134:   char           str[50];
135:   PetscBool      isascii;

139:   if (!viewer) viewer = PETSC_VIEWER_STDOUT_(PetscObjectComm((PetscObject)mfn));

143:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
144:   if (isascii) {
145:     PetscObjectPrintClassNamePrefixType((PetscObject)mfn,viewer,"MFN Object");
146:     if (mfn->ops->view) {
147:       PetscViewerASCIIPushTab(viewer);
148:       (*mfn->ops->view)(mfn,viewer);
149:       PetscViewerASCIIPopTab(viewer);
150:     }
151:     if (mfn->function) {
152:       switch (mfn->function) {
153:         case SLEPC_FUNCTION_EXP: fun = "exponential"; break;
154:         default: SETERRQ(PetscObjectComm((PetscObject)mfn),1,"Wrong value of mfn->function");
155:       }
156:     } else fun = "not yet set";
157:     PetscViewerASCIIPrintf(viewer,"  function: %s\n",fun);
158:     PetscViewerASCIIPrintf(viewer,"  number of column vectors (ncv): %D\n",mfn->ncv);
159:     PetscViewerASCIIPrintf(viewer,"  maximum number of iterations: %D\n",mfn->max_it);
160:     PetscViewerASCIIPrintf(viewer,"  tolerance: %G\n",mfn->tol);
161:     SlepcSNPrintfScalar(str,50,mfn->sfactor,PETSC_FALSE);
162:     PetscViewerASCIIPrintf(viewer,"  scaling factor: %s\n",str);
163:   } else {
164:     if (mfn->ops->view) {
165:       (*mfn->ops->view)(mfn,viewer);
166:     }
167:   }
168:   if (!mfn->ip) { MFNGetIP(mfn,&mfn->ip); }
169:   IPView(mfn->ip,viewer);
170:   if (!mfn->ds) { MFNGetDS(mfn,&mfn->ds); }
171:   PetscViewerPushFormat(viewer,PETSC_VIEWER_ASCII_INFO);
172:   DSView(mfn->ds,viewer);
173:   PetscViewerPopFormat(viewer);
174:   return(0);
175: }

179: /*@C
180:    MFNCreate - Creates the default MFN context.

182:    Collective on MPI_Comm

184:    Input Parameter:
185: .  comm - MPI communicator

187:    Output Parameter:
188: .  mfn - location to put the MFN context

190:    Note:
191:    The default MFN type is MFNKRYLOV

193:    Level: beginner

195: .seealso: MFNSetUp(), MFNSolve(), MFNDestroy(), MFN
196: @*/
197: PetscErrorCode MFNCreate(MPI_Comm comm,MFN *outmfn)
198: {
200:   MFN            mfn;

204:   *outmfn = 0;
205: #if !defined(PETSC_USE_DYNAMIC_LIBRARIES)
206:   MFNInitializePackage();
207: #endif

209:   SlepcHeaderCreate(mfn,_p_MFN,struct _MFNOps,MFN_CLASSID,"MFN","Matrix Function","MFN",comm,MFNDestroy,MFNView);

211:   mfn->max_it          = 0;
212:   mfn->ncv             = 0;
213:   mfn->allocated_ncv   = 0;
214:   mfn->tol             = PETSC_DEFAULT;
215:   mfn->function        = (SlepcFunction)0;
216:   mfn->sfactor         = 1.0;

218:   mfn->A               = 0;
219:   mfn->V               = 0;
220:   mfn->t               = 0;
221:   mfn->errest          = 0;
222:   mfn->ip              = 0;
223:   mfn->ds              = 0;
224:   mfn->rand            = 0;
225:   mfn->data            = 0;
226:   mfn->its             = 0;

228:   mfn->nwork           = 0;
229:   mfn->work            = 0;
230:   mfn->setupcalled     = 0;
231:   mfn->reason          = MFN_CONVERGED_ITERATING;
232:   mfn->numbermonitors  = 0;

234:   PetscRandomCreate(comm,&mfn->rand);
235:   PetscRandomSetSeed(mfn->rand,0x12345678);
236:   PetscLogObjectParent(mfn,mfn->rand);
237:   *outmfn = mfn;
238:   return(0);
239: }

243: /*@C
244:    MFNSetType - Selects the particular solver to be used in the MFN object.

246:    Logically Collective on MFN

248:    Input Parameters:
249: +  mfn  - the matrix function context
250: -  type - a known method

252:    Options Database Key:
253: .  -mfn_type <method> - Sets the method; use -help for a list
254:     of available methods

256:    Notes:
257:    See "slepc/include/slepcmfn.h" for available methods. The default
258:    is MFNKRYLOV

260:    Normally, it is best to use the MFNSetFromOptions() command and
261:    then set the MFN type from the options database rather than by using
262:    this routine.  Using the options database provides the user with
263:    maximum flexibility in evaluating the different available methods.
264:    The MFNSetType() routine is provided for those situations where it
265:    is necessary to set the iterative solver independently of the command
266:    line or options database.

268:    Level: intermediate

270: .seealso: MFNType
271: @*/
272: PetscErrorCode MFNSetType(MFN mfn,MFNType type)
273: {
274:   PetscErrorCode ierr,(*r)(MFN);
275:   PetscBool      match;


281:   PetscObjectTypeCompare((PetscObject)mfn,type,&match);
282:   if (match) return(0);

284:   PetscFunctionListFind(MFNList,type,&r);
285:   if (!r) SETERRQ1(PetscObjectComm((PetscObject)mfn),PETSC_ERR_ARG_UNKNOWN_TYPE,"Unknown MFN type given: %s",type);

287:   if (mfn->ops->destroy) { (*mfn->ops->destroy)(mfn); }
288:   PetscMemzero(mfn->ops,sizeof(struct _MFNOps));

290:   mfn->setupcalled = 0;
291:   PetscObjectChangeTypeName((PetscObject)mfn,type);
292:   (*r)(mfn);
293:   return(0);
294: }

298: /*@C
299:    MFNGetType - Gets the MFN type as a string from the MFN object.

301:    Not Collective

303:    Input Parameter:
304: .  mfn - the matrix function context

306:    Output Parameter:
307: .  name - name of MFN method

309:    Level: intermediate

311: .seealso: MFNSetType()
312: @*/
313: PetscErrorCode MFNGetType(MFN mfn,MFNType *type)
314: {
318:   *type = ((PetscObject)mfn)->type_name;
319:   return(0);
320: }

324: /*@C
325:    MFNRegister - Adds a method to the matrix function solver package.

327:    Not Collective

329:    Input Parameters:
330: +  name - name of a new user-defined solver
331: -  function - routine to create the solver context

333:    Notes:
334:    MFNRegister() may be called multiple times to add several user-defined solvers.

336:    Sample usage:
337: .vb
338:    MFNRegister("my_solver",MySolverCreate);
339: .ve

341:    Then, your solver can be chosen with the procedural interface via
342: $     MFNSetType(mfn,"my_solver")
343:    or at runtime via the option
344: $     -mfn_type my_solver

346:    Level: advanced

348: .seealso: MFNRegisterAll()
349: @*/
350: PetscErrorCode MFNRegister(const char *name,PetscErrorCode (*function)(MFN))
351: {

355:   PetscFunctionListAdd(&MFNList,name,function);
356:   return(0);
357: }

361: /*@
362:    MFNReset - Resets the MFN context to the setupcalled=0 state and removes any
363:    allocated objects.

365:    Collective on MFN

367:    Input Parameter:
368: .  mfn - matrix function context obtained from MFNCreate()

370:    Level: advanced

372: .seealso: MFNDestroy()
373: @*/
374: PetscErrorCode MFNReset(MFN mfn)
375: {

380:   if (mfn->ops->reset) { (mfn->ops->reset)(mfn); }
381:   if (mfn->ip) { IPReset(mfn->ip); }
382:   if (mfn->ds) { DSReset(mfn->ds); }
383:   VecDestroy(&mfn->t);
384:   mfn->setupcalled = 0;
385:   return(0);
386: }

390: /*@C
391:    MFNDestroy - Destroys the MFN context.

393:    Collective on MFN

395:    Input Parameter:
396: .  mfn - matrix function context obtained from MFNCreate()

398:    Level: beginner

400: .seealso: MFNCreate(), MFNSetUp(), MFNSolve()
401: @*/
402: PetscErrorCode MFNDestroy(MFN *mfn)
403: {

407:   if (!*mfn) return(0);
409:   if (--((PetscObject)(*mfn))->refct > 0) { *mfn = 0; return(0); }
410:   MFNReset(*mfn);
411:   if ((*mfn)->ops->destroy) { (*(*mfn)->ops->destroy)(*mfn); }
412:   MatDestroy(&(*mfn)->A);
413:   IPDestroy(&(*mfn)->ip);
414:   DSDestroy(&(*mfn)->ds);
415:   PetscRandomDestroy(&(*mfn)->rand);
416:   MFNMonitorCancel(*mfn);
417:   PetscHeaderDestroy(mfn);
418:   return(0);
419: }

423: /*@
424:    MFNSetIP - Associates an inner product object to the matrix function solver.

426:    Collective on MFN

428:    Input Parameters:
429: +  mfn - matrix function context obtained from MFNCreate()
430: -  ip  - the inner product object

432:    Note:
433:    Use MFNGetIP() to retrieve the inner product context (for example,
434:    to free it at the end of the computations).

436:    Level: advanced

438: .seealso: MFNGetIP()
439: @*/
440: PetscErrorCode MFNSetIP(MFN mfn,IP ip)
441: {

448:   PetscObjectReference((PetscObject)ip);
449:   IPDestroy(&mfn->ip);
450:   mfn->ip = ip;
451:   PetscLogObjectParent(mfn,mfn->ip);
452:   return(0);
453: }

457: /*@C
458:    MFNGetIP - Obtain the inner product object associated to the eigensolver object.

460:    Not Collective

462:    Input Parameters:
463: .  mfn - matrix function context obtained from MFNCreate()

465:    Output Parameter:
466: .  ip - inner product context

468:    Level: advanced

470: .seealso: MFNSetIP()
471: @*/
472: PetscErrorCode MFNGetIP(MFN mfn,IP *ip)
473: {

479:   if (!mfn->ip) {
480:     IPCreate(PetscObjectComm((PetscObject)mfn),&mfn->ip);
481:     PetscLogObjectParent(mfn,mfn->ip);
482:   }
483:   *ip = mfn->ip;
484:   return(0);
485: }

489: /*@
490:    MFNSetDS - Associates a direct solver object to the matrix function solver.

492:    Collective on MFN

494:    Input Parameters:
495: +  mfn - matrix function context obtained from MFNCreate()
496: -  ds  - the direct solver object

498:    Note:
499:    Use MFNGetDS() to retrieve the direct solver context (for example,
500:    to free it at the end of the computations).

502:    Level: advanced

504: .seealso: MFNGetDS()
505: @*/
506: PetscErrorCode MFNSetDS(MFN mfn,DS ds)
507: {

514:   PetscObjectReference((PetscObject)ds);
515:   DSDestroy(&mfn->ds);
516:   mfn->ds = ds;
517:   PetscLogObjectParent(mfn,mfn->ds);
518:   return(0);
519: }

523: /*@C
524:    MFNGetDS - Obtain the direct solver object associated to the matrix function object.

526:    Not Collective

528:    Input Parameters:
529: .  mfn - matrix function context obtained from MFNCreate()

531:    Output Parameter:
532: .  ds - direct solver context

534:    Level: advanced

536: .seealso: MFNSetDS()
537: @*/
538: PetscErrorCode MFNGetDS(MFN mfn,DS *ds)
539: {

545:   if (!mfn->ds) {
546:     DSCreate(PetscObjectComm((PetscObject)mfn),&mfn->ds);
547:     PetscLogObjectParent(mfn,mfn->ds);
548:   }
549:   *ds = mfn->ds;
550:   return(0);
551: }