Actual source code: pcset.c

      1: #define PETSCKSP_DLL
      2: /*
      3:     Routines to set PC methods and options.
      4: */

     6:  #include src/ksp/pc/pcimpl.h
     7:  #include petscsys.h

      9: PetscTruth PCRegisterAllCalled = PETSC_FALSE;
     10: /*
     11:    Contains the list of registered KSP routines
     12: */
     13: PetscFList PCList = 0;

     17: /*@C
     18:    PCSetType - Builds PC for a particular preconditioner.

     20:    Collective on PC

     22:    Input Parameter:
     23: +  pc - the preconditioner context.
     24: -  type - a known method

     26:    Options Database Key:
     27: .  -pc_type <type> - Sets PC type

     29:    Use -help for a list of available methods (for instance,
     30:    jacobi or bjacobi)

     32:   Notes:
     33:   See "petsc/include/petscpc.h" for available methods (for instance,
     34:   PCJACOBI, PCILU, or PCBJACOBI).

     36:   Normally, it is best to use the KSPSetFromOptions() command and
     37:   then set the PC type from the options database rather than by using
     38:   this routine.  Using the options database provides the user with
     39:   maximum flexibility in evaluating the many different preconditioners.
     40:   The PCSetType() routine is provided for those situations where it
     41:   is necessary to set the preconditioner independently of the command
     42:   line or options database.  This might be the case, for example, when
     43:   the choice of preconditioner changes during the execution of the
     44:   program, and the user's application is taking responsibility for
     45:   choosing the appropriate preconditioner.  In other words, this
     46:   routine is not for beginners.

     48:   Level: intermediate

     50: .keywords: PC, set, method, type

     52: .seealso: KSPSetType(), PCType

     54: @*/
     55: PetscErrorCode PETSCKSP_DLLEXPORT PCSetType(PC pc, PCType type)
     56: {
     57:   PetscErrorCode ierr,(*r)(PC);
     58:   PetscTruth     match;

     64:   PetscTypeCompare((PetscObject)pc,type,&match);
     65:   if (match) return(0);

     67:   if (pc->ops->destroy) { (*pc->ops->destroy)(pc);}
     68:   PetscFListDestroy(&pc->qlist);
     69:   pc->data        = 0;
     70:   pc->setupcalled = 0;

     72:   /* Get the function pointers for the method requested */
     73:   if (!PCRegisterAllCalled) {PCRegisterAll(0);}

     75:   /* Determine the PCCreateXXX routine for a particular preconditioner */
     76:    PetscFListFind(pc->comm,PCList,type,(void (**)(void)) &r);
     77:   if (!r) SETERRQ1(PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested PC type %s",type);
     78:   if (pc->data) {PetscFree(pc->data);}

     80:   pc->ops->setup               = (PetscErrorCode (*)(PC)) 0;
     81:   pc->ops->apply               = (PetscErrorCode (*)(PC,Vec,Vec)) 0;
     82:   pc->ops->applyrichardson     = (PetscErrorCode (*)(PC,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal,PetscInt)) 0;
     83:   pc->ops->applyBA             = (PetscErrorCode (*)(PC,PetscInt,Vec,Vec,Vec)) 0;
     84:   pc->ops->applytranspose      = (PetscErrorCode (*)(PC,Vec,Vec)) 0;
     85:   pc->ops->applyBAtranspose    = (PetscErrorCode (*)(PC,PetscInt,Vec,Vec,Vec)) 0;
     86:   pc->ops->setfromoptions      = (PetscErrorCode (*)(PC)) 0;
     87:   pc->ops->presolve            = (PetscErrorCode (*)(PC,KSP,Vec,Vec)) 0;
     88:   pc->ops->postsolve           = (PetscErrorCode (*)(PC,KSP,Vec,Vec)) 0;
     89:   pc->ops->getfactoredmatrix   = (PetscErrorCode (*)(PC,Mat*)) 0;
     90:   pc->ops->applysymmetricleft  = (PetscErrorCode (*)(PC,Vec,Vec)) 0;
     91:   pc->ops->applysymmetricright = (PetscErrorCode (*)(PC,Vec,Vec)) 0;
     92:   pc->ops->setuponblocks       = (PetscErrorCode (*)(PC)) 0;
     93:   pc->ops->destroy             = (PetscErrorCode (*)(PC)) 0;
     94:   pc->ops->view                = (PetscErrorCode (*)(PC,PetscViewer)) 0;
     95:   pc->modifysubmatrices        = (PetscErrorCode (*)(PC,PetscInt,const IS[],const IS[],Mat[],void*)) 0;

     97:   /* Call the PCCreateXXX routine for this particular preconditioner */
     98:   (*r)(pc);

    100:   PetscObjectChangeTypeName((PetscObject)pc,type);
    101:   return(0);
    102: }

    106: /*@C
    107:    PCRegisterDestroy - Frees the list of preconditioners that were
    108:    registered by PCRegisterDynamic().

    110:    Not Collective

    112:    Level: advanced

    114: .keywords: PC, register, destroy

    116: .seealso: PCRegisterAll(), PCRegisterAll()

    118: @*/
    119: PetscErrorCode PETSCKSP_DLLEXPORT PCRegisterDestroy(void)
    120: {

    124:   if (PCList) {
    125:     PetscFListDestroy(&PCList);
    126:     PCList = 0;
    127:   }
    128:   PCRegisterAllCalled = PETSC_FALSE;
    129:   return(0);
    130: }

    134: /*@C
    135:    PCGetType - Gets the PC method type and name (as a string) from the PC
    136:    context.

    138:    Not Collective

    140:    Input Parameter:
    141: .  pc - the preconditioner context

    143:    Output Parameter:
    144: .  name - name of preconditioner

    146:    Level: intermediate

    148: .keywords: PC, get, method, name, type

    150: .seealso: PCSetType()

    152: @*/
    153: PetscErrorCode PETSCKSP_DLLEXPORT PCGetType(PC pc,PCType *meth)
    154: {
    156:   *meth = (PCType) pc->type_name;
    157:   return(0);
    158: }

    160: EXTERN PetscErrorCode PCGetDefaultType_Private(PC,const char*[]);

    164: /*@
    165:    PCSetFromOptions - Sets PC options from the options database.
    166:    This routine must be called before PCSetUp() if the user is to be
    167:    allowed to set the preconditioner method.

    169:    Collective on PC

    171:    Input Parameter:
    172: .  pc - the preconditioner context

    174:    Level: developer

    176: .keywords: PC, set, from, options, database

    178: .seealso:

    180: @*/
    181: PetscErrorCode PETSCKSP_DLLEXPORT PCSetFromOptions(PC pc)
    182: {
    184:   char           type[256];
    185:   const char     *def;
    186:   PetscTruth     flg;

    191:   if (!PCRegisterAllCalled) {PCRegisterAll(PETSC_NULL);}
    192:   PetscOptionsBegin(pc->comm,pc->prefix,"Preconditioner (PC) Options","PC");
    193:     if (!pc->type_name) {
    194:       PCGetDefaultType_Private(pc,&def);
    195:     } else {
    196:       def = pc->type_name;
    197:     }

    199:     PetscOptionsList("-pc_type","Preconditioner","PCSetType",PCList,def,type,256,&flg);
    200:     if (flg) {
    201:       PCSetType(pc,type);
    202:     } else if (!pc->type_name){
    203:       PCSetType(pc,def);
    204:     }

    206:     if (pc->ops->setfromoptions) {
    207:       (*pc->ops->setfromoptions)(pc);
    208:     }
    209:   PetscOptionsEnd();
    210:   return(0);
    211: }