Actual source code: pcset.c
petsc-3.7.1 2016-05-15
Report Typos and Errors

      2: /*
      3:     Routines to set PC methods and options.
      4: */

      6: #include <petsc/private/pcimpl.h>      /*I "petscpc.h" I*/
      7: #include <petscdm.h>

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

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

     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:   Developer Note: PCRegister() is used to add preconditioner types to PCList from which they
     51:   are accessed by PCSetType().

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

     55: .seealso: KSPSetType(), PCType, PCRegister(), PCCreate(), KSPGetPC()

     57: @*/
     58: PetscErrorCode  PCSetType(PC pc,PCType type)
     59: {
     60:   PetscErrorCode ierr,(*r)(PC);
     61:   PetscBool      match;

     67:   PetscObjectTypeCompare((PetscObject)pc,type,&match);
     68:   if (match) return(0);

     70:    PetscFunctionListFind(PCList,type,&r);
     71:   if (!r) SETERRQ1(PetscObjectComm((PetscObject)pc),PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested PC type %s",type);
     72:   /* Destroy the previous private PC context */
     73:   if (pc->ops->destroy) {
     74:      (*pc->ops->destroy)(pc);
     75:     pc->ops->destroy = NULL;
     76:     pc->data         = 0;
     77:   }
     78:   PetscFunctionListDestroy(&((PetscObject)pc)->qlist);
     79:   /* Reinitialize function pointers in PCOps structure */
     80:   PetscMemzero(pc->ops,sizeof(struct _PCOps));
     81:   /* XXX Is this OK?? */
     82:   pc->modifysubmatrices  = 0;
     83:   pc->modifysubmatricesP = 0;
     84:   /* Call the PCCreate_XXX routine for this particular preconditioner */
     85:   pc->setupcalled = 0;

     87:   PetscObjectChangeTypeName((PetscObject)pc,type);
     88:   (*r)(pc);
     89:   return(0);
     90: }

     94: /*@C
     95:    PCGetType - Gets the PC method type and name (as a string) from the PC
     96:    context.

     98:    Not Collective

    100:    Input Parameter:
    101: .  pc - the preconditioner context

    103:    Output Parameter:
    104: .  type - name of preconditioner method

    106:    Level: intermediate

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

    110: .seealso: PCSetType()

    112: @*/
    113: PetscErrorCode  PCGetType(PC pc,PCType *type)
    114: {
    118:   *type = ((PetscObject)pc)->type_name;
    119:   return(0);
    120: }

    122: extern PetscErrorCode PCGetDefaultType_Private(PC,const char*[]);

    126: /*@
    127:    PCSetFromOptions - Sets PC options from the options database.
    128:    This routine must be called before PCSetUp() if the user is to be
    129:    allowed to set the preconditioner method.

    131:    Collective on PC

    133:    Input Parameter:
    134: .  pc - the preconditioner context

    136:    Options Database:
    137: .   -pc_use_amat true,false see PCSetUseAmat()

    139:    Level: developer

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

    143: .seealso: PCSetUseAmat()

    145: @*/
    146: PetscErrorCode  PCSetFromOptions(PC pc)
    147: {
    149:   char           type[256];
    150:   const char     *def;
    151:   PetscBool      flg;

    156:   PCRegisterAll();
    157:   PetscObjectOptionsBegin((PetscObject)pc);
    158:   if (!((PetscObject)pc)->type_name) {
    159:     PCGetDefaultType_Private(pc,&def);
    160:   } else {
    161:     def = ((PetscObject)pc)->type_name;
    162:   }

    164:   PetscOptionsFList("-pc_type","Preconditioner","PCSetType",PCList,def,type,256,&flg);
    165:   if (flg) {
    166:     PCSetType(pc,type);
    167:   } else if (!((PetscObject)pc)->type_name) {
    168:     PCSetType(pc,def);
    169:   }

    171:   PetscObjectTypeCompare((PetscObject)pc,PCNONE,&flg);
    172:   if (flg) goto skipoptions;

    174:   PetscOptionsBool("-pc_use_amat","use Amat (instead of Pmat) to define preconditioner in nested inner solves","PCSetUseAmat",pc->useAmat,&pc->useAmat,NULL);

    176:   if (pc->ops->setfromoptions) {
    177:     (*pc->ops->setfromoptions)(PetscOptionsObject,pc);
    178:   }

    180:   skipoptions:
    181:   /* process any options handlers added with PetscObjectAddOptionsHandler() */
    182:   PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)pc);
    183:   PetscOptionsEnd();
    184:   pc->setfromoptionscalled++;
    185:   return(0);
    186: }

    190: /*@
    191:    PCSetDM - Sets the DM that may be used by some preconditioners

    193:    Logically Collective on PC

    195:    Input Parameters:
    196: +  pc - the preconditioner context
    197: -  dm - the dm

    199:    Level: intermediate

    202: .seealso: PCGetDM(), KSPSetDM(), KSPGetDM()
    203: @*/
    204: PetscErrorCode  PCSetDM(PC pc,DM dm)
    205: {

    210:   if (dm) {PetscObjectReference((PetscObject)dm);}
    211:   DMDestroy(&pc->dm);
    212:   pc->dm = dm;
    213:   return(0);
    214: }

    218: /*@
    219:    PCGetDM - Gets the DM that may be used by some preconditioners

    221:    Not Collective

    223:    Input Parameter:
    224: . pc - the preconditioner context

    226:    Output Parameter:
    227: .  dm - the dm

    229:    Level: intermediate

    232: .seealso: PCSetDM(), KSPSetDM(), KSPGetDM()
    233: @*/
    234: PetscErrorCode  PCGetDM(PC pc,DM *dm)
    235: {
    238:   *dm = pc->dm;
    239:   return(0);
    240: }

    244: /*@
    245:    PCSetApplicationContext - Sets the optional user-defined context for the linear solver.

    247:    Logically Collective on PC

    249:    Input Parameters:
    250: +  pc - the PC context
    251: -  usrP - optional user context

    253:    Level: intermediate

    255: .keywords: PC, set, application, context

    257: .seealso: PCGetApplicationContext()
    258: @*/
    259: PetscErrorCode  PCSetApplicationContext(PC pc,void *usrP)
    260: {
    263:   pc->user = usrP;
    264:   return(0);
    265: }

    269: /*@
    270:    PCGetApplicationContext - Gets the user-defined context for the linear solver.

    272:    Not Collective

    274:    Input Parameter:
    275: .  pc - PC context

    277:    Output Parameter:
    278: .  usrP - user context

    280:    Level: intermediate

    282: .keywords: PC, get, application, context

    284: .seealso: PCSetApplicationContext()
    285: @*/
    286: PetscErrorCode  PCGetApplicationContext(PC pc,void *usrP)
    287: {
    290:   *(void**)usrP = pc->user;
    291:   return(0);
    292: }