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