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

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

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

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

 19:    Collective on PC

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

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

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

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

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

 47:   Level: intermediate

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

 51: .seealso: KSPSetType(), PCType

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


 63:   PetscObjectTypeCompare((PetscObject)pc,type,&match);
 64:   if (match) return(0);

 66:    PetscFListFind(PCList,((PetscObject)pc)->comm,type,PETSC_TRUE,(void (**)(void)) &r);
 67:   if (!r) SETERRQ1(((PetscObject)pc)->comm,PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested PC type %s",type);
 68:   /* Destroy the previous private PC context */
 69:   if (pc->ops->destroy) {
 70:      (*pc->ops->destroy)(pc);
 71:     pc->ops->destroy = PETSC_NULL;
 72:     pc->data = 0;
 73:   }
 74:   PetscFListDestroy(&((PetscObject)pc)->qlist);
 75:   /* Reinitialize function pointers in PCOps structure */
 76:   PetscMemzero(pc->ops,sizeof(struct _PCOps));
 77:   /* XXX Is this OK?? */
 78:   pc->modifysubmatrices        = 0;
 79:   pc->modifysubmatricesP       = 0;
 80:   /* Call the PCCreate_XXX routine for this particular preconditioner */
 81:   pc->setupcalled = 0;
 82:   PetscObjectChangeTypeName((PetscObject)pc,type);
 83:   (*r)(pc);
 84: #if defined(PETSC_HAVE_AMS)
 85:   if (PetscAMSPublishAll) {
 86:     PetscObjectAMSPublish((PetscObject)pc);
 87:   }
 88: #endif
 89:   return(0);
 90: }

 94: /*@
 95:    PCRegisterDestroy - Frees the list of preconditioners that were
 96:    registered by PCRegisterDynamic().

 98:    Not Collective

100:    Level: advanced

102: .keywords: PC, register, destroy

104: .seealso: PCRegisterAll(), PCRegisterAll()

106: @*/
107: PetscErrorCode  PCRegisterDestroy(void)
108: {

112:   PetscFListDestroy(&PCList);
113:   PCRegisterAllCalled = PETSC_FALSE;
114:   return(0);
115: }

119: /*@C
120:    PCGetType - Gets the PC method type and name (as a string) from the PC
121:    context.

123:    Not Collective

125:    Input Parameter:
126: .  pc - the preconditioner context

128:    Output Parameter:
129: .  type - name of preconditioner method

131:    Level: intermediate

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

135: .seealso: PCSetType()

137: @*/
138: PetscErrorCode  PCGetType(PC pc,const PCType *type)
139: {
143:   *type = ((PetscObject)pc)->type_name;
144:   return(0);
145: }

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

151: /*@
152:    PCSetFromOptions - Sets PC options from the options database.
153:    This routine must be called before PCSetUp() if the user is to be
154:    allowed to set the preconditioner method. 

156:    Collective on PC

158:    Input Parameter:
159: .  pc - the preconditioner context

161:    Level: developer

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

165: .seealso: 

167: @*/
168: PetscErrorCode  PCSetFromOptions(PC pc)
169: {
171:   char           type[256];
172:   const char     *def;
173:   PetscBool      flg;


178:   if (!PCRegisterAllCalled) {PCRegisterAll(PETSC_NULL);}
179:   PetscObjectOptionsBegin((PetscObject)pc);
180:   if (!((PetscObject)pc)->type_name) {
181:     PCGetDefaultType_Private(pc,&def);
182:   } else {
183:     def = ((PetscObject)pc)->type_name;
184:   }
185: 
186:   PetscOptionsList("-pc_type","Preconditioner","PCSetType",PCList,def,type,256,&flg);
187:   if (flg) {
188:     PCSetType(pc,type);
189:   } else if (!((PetscObject)pc)->type_name){
190:     PCSetType(pc,def);
191:   }
192: 
193:   PetscOptionsGetInt(((PetscObject)pc)->prefix,"-pc_reuse",&pc->reuse,PETSC_NULL);
194: 
195:   if (pc->ops->setfromoptions) {
196:     (*pc->ops->setfromoptions)(pc);
197:   }
198: 
199:   /* process any options handlers added with PetscObjectAddOptionsHandler() */
200:   PetscObjectProcessOptionsHandlers((PetscObject)pc);
201:   PetscOptionsEnd();
202:   pc->setfromoptionscalled++;
203:   return(0);
204: }

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

211:    Logically Collective on PC

213:    Input Parameters:
214: +  pc - the preconditioner context
215: -  dm - the dm

217:    Level: intermediate


220: .seealso: PCGetDM(), KSPSetDM(), KSPGetDM()
221: @*/
222: PetscErrorCode  PCSetDM(PC pc,DM dm)
223: {

228:   if (dm) {PetscObjectReference((PetscObject)dm);}
229:   DMDestroy(&pc->dm);
230:   pc->dm = dm;
231:   return(0);
232: }

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

239:    Not Collective

241:    Input Parameter:
242: . pc - the preconditioner context

244:    Output Parameter:
245: .  dm - the dm

247:    Level: intermediate


250: .seealso: PCSetDM(), KSPSetDM(), KSPGetDM()
251: @*/
252: PetscErrorCode  PCGetDM(PC pc,DM *dm)
253: {
256:   *dm = pc->dm;
257:   return(0);
258: }

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

265:    Logically Collective on PC

267:    Input Parameters:
268: +  pc - the PC context
269: -  usrP - optional user context

271:    Level: intermediate

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

275: .seealso: PCGetApplicationContext()
276: @*/
277: PetscErrorCode  PCSetApplicationContext(PC pc,void *usrP)
278: {
281:   pc->user = usrP;
282:   return(0);
283: }

287: /*@
288:    PCGetApplicationContext - Gets the user-defined context for the linear solver.

290:    Not Collective

292:    Input Parameter:
293: .  pc - PC context

295:    Output Parameter:
296: .  usrP - user context

298:    Level: intermediate

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

302: .seealso: PCSetApplicationContext()
303: @*/
304: PetscErrorCode  PCGetApplicationContext(PC pc,void *usrP)
305: {
308:   *(void**)usrP = pc->user;
309:   return(0);
310: }