Actual source code: pcset.c
 
   petsc-3.7.7 2017-09-25
   
  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: }