Date: 2015-09-03T15:06:05+00:00

Actual source code: mfnbasic.c
slepc-3.6.1 2015-09-03
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-2015, 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:   PetscBool      isascii;

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

     71:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
     72:   if (isascii) {
     73:     PetscObjectPrintClassNamePrefixType((PetscObject)mfn,viewer);
     74:     if (mfn->ops->view) {
     75:       PetscViewerASCIIPushTab(viewer);
     76:       (*mfn->ops->view)(mfn,viewer);
     77:       PetscViewerASCIIPopTab(viewer);
     78:     }
     79:     PetscViewerASCIIPrintf(viewer,"  number of column vectors (ncv): %D\n",mfn->ncv);
     80:     PetscViewerASCIIPrintf(viewer,"  maximum number of iterations: %D\n",mfn->max_it);
     81:     PetscViewerASCIIPrintf(viewer,"  tolerance: %g\n",(double)mfn->tol);
     82:   } else {
     83:     if (mfn->ops->view) {
     84:       (*mfn->ops->view)(mfn,viewer);
     85:     }
     86:   }
     87:   PetscViewerPushFormat(viewer,PETSC_VIEWER_ASCII_INFO);
     88:   if (!mfn->V) { MFNGetFN(mfn,&mfn->fn); }
     89:   FNView(mfn->fn,viewer);
     90:   if (!mfn->V) { MFNGetBV(mfn,&mfn->V); }
     91:   BVView(mfn->V,viewer);
     92:   PetscViewerPopFormat(viewer);
     93:   return(0);
     94: }

     98: /*@C
     99:    MFNReasonView - Displays the reason an MFN solve converged or diverged.

    101:    Collective on MFN

    103:    Parameter:
    104: +  mfn - the matrix function context
    105: -  viewer - the viewer to display the reason

    107:    Options Database Keys:
    108: .  -mfn_converged_reason - print reason for convergence, and number of iterations

    110:    Level: intermediate

    112: .seealso: MFNSetTolerances(), MFNGetIterationNumber()
    113: @*/
    114: PetscErrorCode MFNReasonView(MFN mfn,PetscViewer viewer)
    115: {
    117:   PetscBool      isAscii;

    120:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isAscii);
    121:   if (isAscii) {
    122:     PetscViewerASCIIAddTab(viewer,((PetscObject)mfn)->tablevel);
    123:     if (mfn->reason > 0) {
    124:       PetscViewerASCIIPrintf(viewer,"%s Matrix function solve converged due to %s; iterations %D\n",((PetscObject)mfn)->prefix?((PetscObject)mfn)->prefix:"",MFNConvergedReasons[mfn->reason],mfn->its);
    125:     } else {
    126:       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);
    127:     }
    128:     PetscViewerASCIISubtractTab(viewer,((PetscObject)mfn)->tablevel);
    129:   }
    130:   return(0);
    131: }

    135: /*@
    136:    MFNReasonViewFromOptions - Processes command line options to determine if/how
    137:    the MFN converged reason is to be viewed.

    139:    Collective on MFN

    141:    Input Parameters:
    142: .  mfn - the matrix function context

    144:    Level: developer
    145: @*/
    146: PetscErrorCode MFNReasonViewFromOptions(MFN mfn)
    147: {
    148:   PetscErrorCode    ierr;
    149:   PetscViewer       viewer;
    150:   PetscBool         flg;
    151:   static PetscBool  incall = PETSC_FALSE;
    152:   PetscViewerFormat format;

    155:   if (incall) return(0);
    156:   incall = PETSC_TRUE;
    157:   PetscOptionsGetViewer(PetscObjectComm((PetscObject)mfn),((PetscObject)mfn)->prefix,"-mfn_converged_reason",&viewer,&format,&flg);
    158:   if (flg) {
    159:     PetscViewerPushFormat(viewer,format);
    160:     MFNReasonView(mfn,viewer);
    161:     PetscViewerPopFormat(viewer);
    162:     PetscViewerDestroy(&viewer);
    163:   }
    164:   incall = PETSC_FALSE;
    165:   return(0);
    166: }

    170: /*@
    171:    MFNCreate - Creates the default MFN context.

    173:    Collective on MPI_Comm

    175:    Input Parameter:
    176: .  comm - MPI communicator

    178:    Output Parameter:
    179: .  mfn - location to put the MFN context

    181:    Note:
    182:    The default MFN type is MFNKRYLOV

    184:    Level: beginner

    186: .seealso: MFNSetUp(), MFNSolve(), MFNDestroy(), MFN
    187: @*/
    188: PetscErrorCode MFNCreate(MPI_Comm comm,MFN *outmfn)
    189: {
    191:   MFN            mfn;

    195:   *outmfn = 0;
    196:   MFNInitializePackage();
    197:   SlepcHeaderCreate(mfn,MFN_CLASSID,"MFN","Matrix Function","MFN",comm,MFNDestroy,MFNView);

    199:   mfn->A               = NULL;
    200:   mfn->fn              = NULL;
    201:   mfn->max_it          = 0;
    202:   mfn->ncv             = 0;
    203:   mfn->tol             = PETSC_DEFAULT;
    204:   mfn->sfactor         = 1.0;
    205:   mfn->errorifnotconverged = PETSC_FALSE;

    207:   mfn->numbermonitors  = 0;

    209:   mfn->V               = NULL;
    210:   mfn->rand            = NULL;
    211:   mfn->nwork           = 0;
    212:   mfn->work            = NULL;
    213:   mfn->data            = NULL;

    215:   mfn->its             = 0;
    216:   mfn->nv              = 0;
    217:   mfn->errest          = 0;
    218:   mfn->setupcalled     = 0;
    219:   mfn->reason          = MFN_CONVERGED_ITERATING;

    221:   PetscRandomCreate(comm,&mfn->rand);
    222:   PetscRandomSetSeed(mfn->rand,0x12345678);
    223:   PetscLogObjectParent((PetscObject)mfn,(PetscObject)mfn->rand);
    224:   *outmfn = mfn;
    225:   return(0);
    226: }

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

    233:    Logically Collective on MFN

    235:    Input Parameters:
    236: +  mfn  - the matrix function context
    237: -  type - a known method

    239:    Options Database Key:
    240: .  -mfn_type <method> - Sets the method; use -help for a list
    241:     of available methods

    243:    Notes:
    244:    See "slepc/include/slepcmfn.h" for available methods. The default
    245:    is MFNKRYLOV

    247:    Normally, it is best to use the MFNSetFromOptions() command and
    248:    then set the MFN type from the options database rather than by using
    249:    this routine.  Using the options database provides the user with
    250:    maximum flexibility in evaluating the different available methods.
    251:    The MFNSetType() routine is provided for those situations where it
    252:    is necessary to set the iterative solver independently of the command
    253:    line or options database.

    255:    Level: intermediate

    257: .seealso: MFNType
    258: @*/
    259: PetscErrorCode MFNSetType(MFN mfn,MFNType type)
    260: {
    261:   PetscErrorCode ierr,(*r)(MFN);
    262:   PetscBool      match;

    268:   PetscObjectTypeCompare((PetscObject)mfn,type,&match);
    269:   if (match) return(0);

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

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

    277:   mfn->setupcalled = 0;
    278:   PetscObjectChangeTypeName((PetscObject)mfn,type);
    279:   (*r)(mfn);
    280:   return(0);
    281: }

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

    288:    Not Collective

    290:    Input Parameter:
    291: .  mfn - the matrix function context

    293:    Output Parameter:
    294: .  name - name of MFN method

    296:    Level: intermediate

    298: .seealso: MFNSetType()
    299: @*/
    300: PetscErrorCode MFNGetType(MFN mfn,MFNType *type)
    301: {
    305:   *type = ((PetscObject)mfn)->type_name;
    306:   return(0);
    307: }

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

    314:    Not Collective

    316:    Input Parameters:
    317: +  name - name of a new user-defined solver
    318: -  function - routine to create the solver context

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

    323:    Sample usage:
    324: .vb
    325:    MFNRegister("my_solver",MySolverCreate);
    326: .ve

    328:    Then, your solver can be chosen with the procedural interface via
    329: $     MFNSetType(mfn,"my_solver")
    330:    or at runtime via the option
    331: $     -mfn_type my_solver

    333:    Level: advanced

    335: .seealso: MFNRegisterAll()
    336: @*/
    337: PetscErrorCode MFNRegister(const char *name,PetscErrorCode (*function)(MFN))
    338: {

    342:   PetscFunctionListAdd(&MFNList,name,function);
    343:   return(0);
    344: }

    348: /*@
    349:    MFNReset - Resets the MFN context to the setupcalled=0 state and removes any
    350:    allocated objects.

    352:    Collective on MFN

    354:    Input Parameter:
    355: .  mfn - matrix function context obtained from MFNCreate()

    357:    Level: advanced

    359: .seealso: MFNDestroy()
    360: @*/
    361: PetscErrorCode MFNReset(MFN mfn)
    362: {

    367:   if (mfn->ops->reset) { (mfn->ops->reset)(mfn); }
    368:   mfn->setupcalled = 0;
    369:   return(0);
    370: }

    374: /*@
    375:    MFNDestroy - Destroys the MFN context.

    377:    Collective on MFN

    379:    Input Parameter:
    380: .  mfn - matrix function context obtained from MFNCreate()

    382:    Level: beginner

    384: .seealso: MFNCreate(), MFNSetUp(), MFNSolve()
    385: @*/
    386: PetscErrorCode MFNDestroy(MFN *mfn)
    387: {

    391:   if (!*mfn) return(0);
    393:   if (--((PetscObject)(*mfn))->refct > 0) { *mfn = 0; return(0); }
    394:   MFNReset(*mfn);
    395:   if ((*mfn)->ops->destroy) { (*(*mfn)->ops->destroy)(*mfn); }
    396:   MatDestroy(&(*mfn)->A);
    397:   BVDestroy(&(*mfn)->V);
    398:   FNDestroy(&(*mfn)->fn);
    399:   PetscRandomDestroy(&(*mfn)->rand);
    400:   MFNMonitorCancel(*mfn);
    401:   PetscHeaderDestroy(mfn);
    402:   return(0);
    403: }

    407: /*@
    408:    MFNSetBV - Associates a basis vectors object to the matrix function solver.

    410:    Collective on MFN

    412:    Input Parameters:
    413: +  mfn - matrix function context obtained from MFNCreate()
    414: -  bv  - the basis vectors object

    416:    Note:
    417:    Use MFNGetBV() to retrieve the basis vectors context (for example,
    418:    to free it at the end of the computations).

    420:    Level: advanced

    422: .seealso: MFNGetBV()
    423: @*/
    424: PetscErrorCode MFNSetBV(MFN mfn,BV bv)
    425: {

    432:   PetscObjectReference((PetscObject)bv);
    433:   BVDestroy(&mfn->V);
    434:   mfn->V = bv;
    435:   PetscLogObjectParent((PetscObject)mfn,(PetscObject)mfn->V);
    436:   return(0);
    437: }

    441: /*@
    442:    MFNGetBV - Obtain the basis vectors object associated to the matrix
    443:    function solver.

    445:    Not Collective

    447:    Input Parameters:
    448: .  mfn - matrix function context obtained from MFNCreate()

    450:    Output Parameter:
    451: .  bv - basis vectors context

    453:    Level: advanced

    455: .seealso: MFNSetBV()
    456: @*/
    457: PetscErrorCode MFNGetBV(MFN mfn,BV *bv)
    458: {

    464:   if (!mfn->V) {
    465:     BVCreate(PetscObjectComm((PetscObject)mfn),&mfn->V);
    466:     PetscLogObjectParent((PetscObject)mfn,(PetscObject)mfn->V);
    467:   }
    468:   *bv = mfn->V;
    469:   return(0);
    470: }

    474: /*@
    475:    MFNSetFN - Specifies the function to be computed.

    477:    Collective on MFN

    479:    Input Parameters:
    480: +  mfn - matrix function context obtained from MFNCreate()
    481: -  fn  - the math function object

    483:    Note:
    484:    Use MFNGetFN() to retrieve the math function context (for example,
    485:    to free it at the end of the computations).

    487:    Level: beginner

    489: .seealso: MFNGetFN()
    490: @*/
    491: PetscErrorCode MFNSetFN(MFN mfn,FN fn)
    492: {

    499:   PetscObjectReference((PetscObject)fn);
    500:   FNDestroy(&mfn->fn);
    501:   mfn->fn = fn;
    502:   PetscLogObjectParent((PetscObject)mfn,(PetscObject)mfn->fn);
    503:   return(0);
    504: }

    508: /*@
    509:    MFNGetFN - Obtain the math function object associated to the MFN object.

    511:    Not Collective

    513:    Input Parameters:
    514: .  mfn - matrix function context obtained from MFNCreate()

    516:    Output Parameter:
    517: .  fn - math function context

    519:    Level: intermediate

    521: .seealso: MFNSetFN()
    522: @*/
    523: PetscErrorCode MFNGetFN(MFN mfn,FN *fn)
    524: {

    530:   if (!mfn->fn) {
    531:     FNCreate(PetscObjectComm((PetscObject)mfn),&mfn->fn);
    532:     PetscLogObjectParent((PetscObject)mfn,(PetscObject)mfn->fn);
    533:   }
    534:   *fn = mfn->fn;
    535:   return(0);
    536: }