Actual source code: pcset.c

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

 5:  #include src/ksp/pc/pcimpl.h
 6:  #include petscsys.h

  8: PetscTruth 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:   PetscTruth     match;


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

 66:   if (pc->ops->destroy) { (*pc->ops->destroy)(pc);}
 67:   PetscFListDestroy(&pc->qlist);
 68:   pc->data        = 0;
 69:   pc->setupcalled = 0;

 71:   /* Get the function pointers for the method requested */
 72:   if (!PCRegisterAllCalled) {PCRegisterAll(0);}

 74:   /* Determine the PCCreateXXX routine for a particular preconditioner */
 75:    PetscFListFind(pc->comm,PCList,type,(void (**)(void)) &r);
 76:   if (!r) SETERRQ1(PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested PC type %s",type);
 77:   if (pc->data) {PetscFree(pc->data);}

 79:   pc->ops->setup               = (PetscErrorCode (*)(PC)) 0;
 80:   pc->ops->apply               = (PetscErrorCode (*)(PC,Vec,Vec)) 0;
 81:   pc->ops->applyrichardson     = (PetscErrorCode (*)(PC,Vec,Vec,Vec,PetscReal,PetscReal,PetscReal,PetscInt)) 0;
 82:   pc->ops->applyBA             = (PetscErrorCode (*)(PC,PetscInt,Vec,Vec,Vec)) 0;
 83:   pc->ops->applytranspose      = (PetscErrorCode (*)(PC,Vec,Vec)) 0;
 84:   pc->ops->applyBAtranspose    = (PetscErrorCode (*)(PC,PetscInt,Vec,Vec,Vec)) 0;
 85:   pc->ops->setfromoptions      = (PetscErrorCode (*)(PC)) 0;
 86:   pc->ops->presolve            = (PetscErrorCode (*)(PC,KSP,Vec,Vec)) 0;
 87:   pc->ops->postsolve           = (PetscErrorCode (*)(PC,KSP,Vec,Vec)) 0;
 88:   pc->ops->getfactoredmatrix   = (PetscErrorCode (*)(PC,Mat*)) 0;
 89:   pc->ops->applysymmetricleft  = (PetscErrorCode (*)(PC,Vec,Vec)) 0;
 90:   pc->ops->applysymmetricright = (PetscErrorCode (*)(PC,Vec,Vec)) 0;
 91:   pc->ops->setuponblocks       = (PetscErrorCode (*)(PC)) 0;
 92:   pc->ops->destroy             = (PetscErrorCode (*)(PC)) 0;
 93:   pc->ops->view                = (PetscErrorCode (*)(PC,PetscViewer)) 0;
 94:   pc->modifysubmatrices        = (PetscErrorCode (*)(PC,PetscInt,const IS[],const IS[],Mat[],void*)) 0;

 96:   /* Call the PCCreateXXX routine for this particular preconditioner */
 97:   (*r)(pc);

 99:   PetscObjectChangeTypeName((PetscObject)pc,type);
100:   return(0);
101: }

105: /*@C
106:    PCRegisterDestroy - Frees the list of preconditioners that were
107:    registered by PCRegisterDynamic().

109:    Not Collective

111:    Level: advanced

113: .keywords: PC, register, destroy

115: .seealso: PCRegisterAll(), PCRegisterAll()

117: @*/
118: PetscErrorCode PCRegisterDestroy(void)
119: {

123:   if (PCList) {
124:     PetscFListDestroy(&PCList);
125:     PCList = 0;
126:   }
127:   PCRegisterAllCalled = PETSC_FALSE;
128:   return(0);
129: }

133: /*@C
134:    PCGetType - Gets the PC method type and name (as a string) from the PC
135:    context.

137:    Not Collective

139:    Input Parameter:
140: .  pc - the preconditioner context

142:    Output Parameter:
143: .  name - name of preconditioner 

145:    Level: intermediate

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

149: .seealso: PCSetType()

151: @*/
152: PetscErrorCode PCGetType(PC pc,PCType *meth)
153: {
155:   *meth = (PCType) pc->type_name;
156:   return(0);
157: }

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

163: /*@
164:    PCSetFromOptions - Sets PC options from the options database.
165:    This routine must be called before PCSetUp() if the user is to be
166:    allowed to set the preconditioner method. 

168:    Collective on PC

170:    Input Parameter:
171: .  pc - the preconditioner context

173:    Level: developer

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

177: .seealso: 

179: @*/
180: PetscErrorCode PCSetFromOptions(PC pc)
181: {
183:   char           type[256];
184:   const char     *def;
185:   PetscTruth     flg;


190:   if (!PCRegisterAllCalled) {PCRegisterAll(PETSC_NULL);}
191:   PetscOptionsBegin(pc->comm,pc->prefix,"Preconditioner (PC) Options","PC");
192:     if (!pc->type_name) {
193:       PCGetDefaultType_Private(pc,&def);
194:     } else {
195:       def = pc->type_name;
196:     }

198:     PetscOptionsList("-pc_type","Preconditioner","PCSetType",PCList,def,type,256,&flg);
199:     if (flg) {
200:       PCSetType(pc,type);
201:     } else if (!pc->type_name){
202:       PCSetType(pc,def);
203:     }

205:     if (pc->ops->setfromoptions) {
206:       (*pc->ops->setfromoptions)(pc);
207:     }
208:   PetscOptionsEnd();
209:   return(0);
210: }