Actual source code: mfnbasic.c

slepc-3.5.2 2014-10-10
Report Typos and Errors
  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(), MFN
126: @*/
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 MFN

175:    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: MFNType
198: @*/
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 MFN

294:    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 MFN

320:    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 MFN

353:    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 MFN

420:    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: }