Actual source code: pcset.c

petsc-3.4.0 2013-05-13
  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.

 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: .keywords: PC, set, method, type

 52: .seealso: KSPSetType(), PCType

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


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

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

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

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

 95:    Not Collective

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

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

103:    Level: intermediate

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

107: .seealso: PCSetType()

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

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

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

128:    Collective on PC

130:    Input Parameter:
131: .  pc - the preconditioner context

133:    Options Database:
134: .   -pc_use_amat true,false see PCSetUseAmat()

136:    Level: developer

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

140: .seealso: PCSetUseAmat()

142: @*/
143: PetscErrorCode  PCSetFromOptions(PC pc)
144: {
146:   char           type[256];
147:   const char     *def;
148:   PetscBool      flg;


153:   if (!PCRegisterAllCalled) {PCRegisterAll();}
154:   PetscObjectOptionsBegin((PetscObject)pc);
155:   if (!((PetscObject)pc)->type_name) {
156:     PCGetDefaultType_Private(pc,&def);
157:   } else {
158:     def = ((PetscObject)pc)->type_name;
159:   }

161:   PetscOptionsList("-pc_type","Preconditioner","PCSetType",PCList,def,type,256,&flg);
162:   if (flg) {
163:     PCSetType(pc,type);
164:   } else if (!((PetscObject)pc)->type_name) {
165:     PCSetType(pc,def);
166:   }

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)(pc);
172:   }

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

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

186:    Logically Collective on PC

188:    Input Parameters:
189: +  pc - the preconditioner context
190: -  dm - the dm

192:    Level: intermediate


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

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

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

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

240:    Logically Collective on PC

242:    Input Parameters:
243: +  pc - the PC context
244: -  usrP - optional user context

246:    Level: intermediate

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

250: .seealso: PCGetApplicationContext()
251: @*/
252: PetscErrorCode  PCSetApplicationContext(PC pc,void *usrP)
253: {
256:   pc->user = usrP;
257:   return(0);
258: }

262: /*@
263:    PCGetApplicationContext - Gets the user-defined context for the linear solver.

265:    Not Collective

267:    Input Parameter:
268: .  pc - PC context

270:    Output Parameter:
271: .  usrP - user context

273:    Level: intermediate

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

277: .seealso: PCSetApplicationContext()
278: @*/
279: PetscErrorCode  PCGetApplicationContext(PC pc,void *usrP)
280: {
283:   *(void**)usrP = pc->user;
284:   return(0);
285: }