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