Actual source code: pcset.c

  1: #define PETSCKSP_DLL
  2: /*
  3:     Routines to set PC methods and options.
  4: */

 6:  #include private/pcimpl.h
 7:  #include petscsys.h

  9: PetscTruth PCRegisterAllCalled = PETSC_FALSE;
 10: /*
 11:    Contains the list of registered KSP routines
 12: */
 13: PetscFList 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,const PCType type)
 56: {
 57:   PetscErrorCode ierr,(*r)(PC);
 58:   PetscTruth     match;


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

 67:    PetscFListFind(PCList,((PetscObject)pc)->comm,type,(void (**)(void)) &r);
 68:   if (!r) SETERRQ1(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) {  (*pc->ops->destroy)(pc); pc->data = 0;}
 71:   PetscFListDestroy(&((PetscObject)pc)->qlist);
 72:   /* Reinitialize function pointers in PCOps structure */
 73:   PetscMemzero(pc->ops,sizeof(struct _PCOps));
 74:   /* XXX Is this OK?? */
 75:   pc->modifysubmatrices        = 0;
 76:   pc->modifysubmatricesP       = 0;
 77:   /* Call the PCCreate_XXX routine for this particular preconditioner */
 78:   pc->setupcalled = 0;
 79:   (*r)(pc);
 80:   PetscObjectChangeTypeName((PetscObject)pc,type);
 81:   return(0);
 82: }

 86: /*@
 87:    PCRegisterDestroy - Frees the list of preconditioners that were
 88:    registered by PCRegisterDynamic().

 90:    Not Collective

 92:    Level: advanced

 94: .keywords: PC, register, destroy

 96: .seealso: PCRegisterAll(), PCRegisterAll()

 98: @*/
 99: PetscErrorCode  PCRegisterDestroy(void)
100: {

104:   PetscFListDestroy(&PCList);
105:   PCRegisterAllCalled = PETSC_FALSE;
106:   return(0);
107: }

111: /*@C
112:    PCGetType - Gets the PC method type and name (as a string) from the PC
113:    context.

115:    Not Collective

117:    Input Parameter:
118: .  pc - the preconditioner context

120:    Output Parameter:
121: .  type - name of preconditioner method

123:    Level: intermediate

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

127: .seealso: PCSetType()

129: @*/
130: PetscErrorCode  PCGetType(PC pc,const PCType *type)
131: {
135:   *type = ((PetscObject)pc)->type_name;
136:   return(0);
137: }

139: EXTERN PetscErrorCode PCGetDefaultType_Private(PC,const char*[]);

143: /*@
144:    PCSetFromOptions - Sets PC options from the options database.
145:    This routine must be called before PCSetUp() if the user is to be
146:    allowed to set the preconditioner method. 

148:    Collective on PC

150:    Input Parameter:
151: .  pc - the preconditioner context

153:    Level: developer

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

157: .seealso: 

159: @*/
160: PetscErrorCode  PCSetFromOptions(PC pc)
161: {
163:   char           type[256];
164:   const char     *def;
165:   PetscTruth     flg;


170:   if (!PCRegisterAllCalled) {PCRegisterAll(PETSC_NULL);}
171:   PetscOptionsBegin(((PetscObject)pc)->comm,((PetscObject)pc)->prefix,"Preconditioner (PC) Options","PC");
172:     if (!((PetscObject)pc)->type_name) {
173:       PCGetDefaultType_Private(pc,&def);
174:     } else {
175:       def = ((PetscObject)pc)->type_name;
176:     }

178:     PetscOptionsList("-pc_type","Preconditioner","PCSetType",PCList,def,type,256,&flg);
179:     if (flg) {
180:       PCSetType(pc,type);
181:     } else if (!((PetscObject)pc)->type_name){
182:       PCSetType(pc,def);
183:     }

185:     if (pc->ops->setfromoptions) {
186:       (*pc->ops->setfromoptions)(pc);
187:     }
188:   PetscOptionsEnd();
189:   pc->setfromoptionscalled++;
190:   return(0);
191: }