Actual source code: pcset.c
2: /*
3: Routines to set PC methods and options.
4: */
6: #include <private/pcimpl.h> /*I "petscpc.h" I*/
8: PetscBool 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: PetscBool match;
63: PetscTypeCompare((PetscObject)pc,type,&match);
64: if (match) return(0);
66: PetscFListFind(PCList,((PetscObject)pc)->comm,type,PETSC_TRUE,(void (**)(void)) &r);
67: if (!r) SETERRQ1(((PetscObject)pc)->comm,PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested PC type %s",type);
68: /* Destroy the previous private PC context */
69: if (pc->ops->destroy) { (*pc->ops->destroy)(pc); pc->data = 0;}
70: PetscFListDestroy(&((PetscObject)pc)->qlist);
71: /* Reinitialize function pointers in PCOps structure */
72: PetscMemzero(pc->ops,sizeof(struct _PCOps));
73: /* XXX Is this OK?? */
74: pc->modifysubmatrices = 0;
75: pc->modifysubmatricesP = 0;
76: /* Call the PCCreate_XXX routine for this particular preconditioner */
77: pc->setupcalled = 0;
78: PetscObjectChangeTypeName((PetscObject)pc,type);
79: (*r)(pc);
80: #if defined(PETSC_HAVE_AMS)
81: if (PetscAMSPublishAll) {
82: PetscObjectAMSPublish((PetscObject)pc);
83: }
84: #endif
85: return(0);
86: }
90: /*@
91: PCRegisterDestroy - Frees the list of preconditioners that were
92: registered by PCRegisterDynamic().
94: Not Collective
96: Level: advanced
98: .keywords: PC, register, destroy
100: .seealso: PCRegisterAll(), PCRegisterAll()
102: @*/
103: PetscErrorCode PCRegisterDestroy(void)
104: {
108: PetscFListDestroy(&PCList);
109: PCRegisterAllCalled = PETSC_FALSE;
110: return(0);
111: }
115: /*@C
116: PCGetType - Gets the PC method type and name (as a string) from the PC
117: context.
119: Not Collective
121: Input Parameter:
122: . pc - the preconditioner context
124: Output Parameter:
125: . type - name of preconditioner method
127: Level: intermediate
129: .keywords: PC, get, method, name, type
131: .seealso: PCSetType()
133: @*/
134: PetscErrorCode PCGetType(PC pc,const PCType *type)
135: {
139: *type = ((PetscObject)pc)->type_name;
140: return(0);
141: }
147: /*@
148: PCSetFromOptions - Sets PC options from the options database.
149: This routine must be called before PCSetUp() if the user is to be
150: allowed to set the preconditioner method.
152: Collective on PC
154: Input Parameter:
155: . pc - the preconditioner context
157: Level: developer
159: .keywords: PC, set, from, options, database
161: .seealso:
163: @*/
164: PetscErrorCode PCSetFromOptions(PC pc)
165: {
167: char type[256];
168: const char *def;
169: PetscBool flg;
174: if (!PCRegisterAllCalled) {PCRegisterAll(PETSC_NULL);}
175: PetscObjectOptionsBegin((PetscObject)pc);
176: if (!((PetscObject)pc)->type_name) {
177: PCGetDefaultType_Private(pc,&def);
178: } else {
179: def = ((PetscObject)pc)->type_name;
180: }
181:
182: PetscOptionsList("-pc_type","Preconditioner","PCSetType",PCList,def,type,256,&flg);
183: if (flg) {
184: PCSetType(pc,type);
185: } else if (!((PetscObject)pc)->type_name){
186: PCSetType(pc,def);
187: }
188:
189: PetscOptionsGetInt(((PetscObject)pc)->prefix,"-pc_reuse",&pc->reuse,PETSC_NULL);
190:
191: if (pc->ops->setfromoptions) {
192: (*pc->ops->setfromoptions)(pc);
193: }
194:
195: /* process any options handlers added with PetscObjectAddOptionsHandler() */
196: PetscObjectProcessOptionsHandlers((PetscObject)pc);
197: PetscOptionsEnd();
198: pc->setfromoptionscalled++;
199: return(0);
200: }
204: /*@
205: PCSetDM - Sets the DM that may be used by some preconditioners
207: Logically Collective on PC
209: Input Parameters:
210: + pc - the preconditioner context
211: - dm - the dm
213: Level: intermediate
216: .seealso: PCGetDM(), KSPSetDM(), KSPGetDM()
217: @*/
218: PetscErrorCode PCSetDM(PC pc,DM dm)
219: {
224: if (dm) {PetscObjectReference((PetscObject)dm);}
225: DMDestroy(&pc->dm);
226: pc->dm = dm;
227: return(0);
228: }
232: /*@
233: PCGetDM - Gets the DM that may be used by some preconditioners
235: Not Collective
237: Input Parameter:
238: . pc - the preconditioner context
240: Output Parameter:
241: . dm - the dm
243: Level: intermediate
246: .seealso: PCSetDM(), KSPSetDM(), KSPGetDM()
247: @*/
248: PetscErrorCode PCGetDM(PC pc,DM *dm)
249: {
252: *dm = pc->dm;
253: return(0);
254: }
258: /*@
259: PCSetApplicationContext - Sets the optional user-defined context for the linear solver.
261: Logically Collective on PC
263: Input Parameters:
264: + pc - the PC context
265: - usrP - optional user context
267: Level: intermediate
269: .keywords: PC, set, application, context
271: .seealso: PCGetApplicationContext()
272: @*/
273: PetscErrorCode PCSetApplicationContext(PC pc,void *usrP)
274: {
277: pc->user = usrP;
278: return(0);
279: }
283: /*@
284: PCGetApplicationContext - Gets the user-defined context for the linear solver.
286: Not Collective
288: Input Parameter:
289: . pc - PC context
291: Output Parameter:
292: . usrP - user context
294: Level: intermediate
296: .keywords: PC, get, application, context
298: .seealso: PCSetApplicationContext()
299: @*/
300: PetscErrorCode PCGetApplicationContext(PC pc,void *usrP)
301: {
304: *(void**)usrP = pc->user;
305: return(0);
306: }