Actual source code: mfnbasic.c

slepc-3.8.0 2017-10-20
Report Typos and Errors
  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: }