Actual source code: pcset.c
petsc-3.10.5 2019-03-28
Report Typos and Errors

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

      6:  #include <petsc/private/pcimpl.h>
      7:  #include <petscdm.h>

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

     15: /*@C
     16:    PCSetType - Builds PC for a particular preconditioner type

     18:    Collective on PC

     20:    Input Parameter:
     21: +  pc - the preconditioner context.
     22: -  type - a known method

     24:    Options Database Key:
     25: .  -pc_type <type> - Sets PC type

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

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

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

     46:   Level: intermediate

     48:   Developer Note: PCRegister() is used to add preconditioner types to PCList from which they
     49:   are accessed by PCSetType().

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

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

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

     65:   PetscObjectTypeCompare((PetscObject)pc,type,&match);
     66:   if (match) return(0);

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

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

     90: /*@C
     91:    PCGetType - Gets the PC method type and name (as a string) from the PC
     92:    context.

     94:    Not Collective

     96:    Input Parameter:
     97: .  pc - the preconditioner context

     99:    Output Parameter:
    100: .  type - name of preconditioner method

    102:    Level: intermediate

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

    106: .seealso: PCSetType()

    108: @*/
    109: PetscErrorCode  PCGetType(PC pc,PCType *type)
    110: {
    114:   *type = ((PetscObject)pc)->type_name;
    115:   return(0);
    116: }

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

    120: /*@
    121:    PCSetFromOptions - Sets PC options from the options database.
    122:    This routine must be called before PCSetUp() if the user is to be
    123:    allowed to set the preconditioner method.

    125:    Collective on PC

    127:    Input Parameter:
    128: .  pc - the preconditioner context

    130:    Options Database:
    131: .   -pc_use_amat true,false see PCSetUseAmat()

    133:    Level: developer

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

    137: .seealso: PCSetUseAmat()

    139: @*/
    140: PetscErrorCode  PCSetFromOptions(PC pc)
    141: {
    143:   char           type[256];
    144:   const char     *def;
    145:   PetscBool      flg;

    150:   PCRegisterAll();
    151:   PetscObjectOptionsBegin((PetscObject)pc);
    152:   if (!((PetscObject)pc)->type_name) {
    153:     PCGetDefaultType_Private(pc,&def);
    154:   } else {
    155:     def = ((PetscObject)pc)->type_name;
    156:   }

    158:   PetscOptionsFList("-pc_type","Preconditioner","PCSetType",PCList,def,type,256,&flg);
    159:   if (flg) {
    160:     PCSetType(pc,type);
    161:   } else if (!((PetscObject)pc)->type_name) {
    162:     PCSetType(pc,def);
    163:   }

    165:   PetscObjectTypeCompare((PetscObject)pc,PCNONE,&flg);
    166:   if (flg) goto skipoptions;

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

    170:   if (pc->ops->setfromoptions) {
    171:     (*pc->ops->setfromoptions)(PetscOptionsObject,pc);
    172:   }

    174:   skipoptions:
    175:   /* process any options handlers added with PetscObjectAddOptionsHandler() */
    176:   PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)pc);
    177:   PetscOptionsEnd();
    178:   pc->setfromoptionscalled++;
    179:   return(0);
    180: }

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

    185:    Logically Collective on PC

    187:    Input Parameters:
    188: +  pc - the preconditioner context
    189: -  dm - the dm, can be NULL

    191:    Level: intermediate

    193:    Developer Notes:
    194:     The routines KSP/SNES/TSSetDM() require the dm to be non-NULL, but this one can be NULL since all it does is
    195:     replace the current DM

    197: .seealso: PCGetDM(), KSPSetDM(), KSPGetDM()
    198: @*/
    199: PetscErrorCode  PCSetDM(PC pc,DM dm)
    200: {

    205:   if (dm) {PetscObjectReference((PetscObject)dm);}
    206:   DMDestroy(&pc->dm);
    207:   pc->dm = dm;
    208:   return(0);
    209: }

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

    214:    Not Collective

    216:    Input Parameter:
    217: . pc - the preconditioner context

    219:    Output Parameter:
    220: .  dm - the dm

    222:    Level: intermediate

    225: .seealso: PCSetDM(), KSPSetDM(), KSPGetDM()
    226: @*/
    227: PetscErrorCode  PCGetDM(PC pc,DM *dm)
    228: {
    231:   *dm = pc->dm;
    232:   return(0);
    233: }

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

    238:    Logically Collective on PC

    240:    Input Parameters:
    241: +  pc - the PC context
    242: -  usrP - optional user context

    244:    Level: intermediate

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

    248: .seealso: PCGetApplicationContext()
    249: @*/
    250: PetscErrorCode  PCSetApplicationContext(PC pc,void *usrP)
    251: {
    254:   pc->user = usrP;
    255:   return(0);
    256: }

    258: /*@
    259:    PCGetApplicationContext - Gets the user-defined context for the linear solver.

    261:    Not Collective

    263:    Input Parameter:
    264: .  pc - PC context

    266:    Output Parameter:
    267: .  usrP - user context

    269:    Level: intermediate

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

    273: .seealso: PCSetApplicationContext()
    274: @*/
    275: PetscErrorCode  PCGetApplicationContext(PC pc,void *usrP)
    276: {
    279:   *(void**)usrP = pc->user;
    280:   return(0);
    281: }