Actual source code: pcset.c
2: /*
3: Routines to set PC methods and options.
4: */
6: #include <petsc/private/pcimpl.h>
7: #include <petscdm.h>
9: PetscBool PCRegisterAllCalled = PETSC_FALSE;
10: /*
11: Contains the list of registered PC routines
12: */
13: PetscFunctionList PCList = NULL;
15: /*@C
16: PCSetType - Builds PC for a particular preconditioner type
18: Collective on PC
20: Input Parameters:
21: + pc - the preconditioner context.
22: - type - a known method
24: Options Database Key:
25: . -pc_type <type> - Sets PC type
27: Use -help for a list of available methods (for instance,
28: jacobi or bjacobi)
30: Notes:
31: See "petsc/include/petscpc.h" for available methods (for instance,
32: PCJACOBI, PCILU, or PCBJACOBI).
34: Normally, it is best to use the KSPSetFromOptions() command and
35: then set the PC type from the options database rather than by using
36: this routine. Using the options database provides the user with
37: maximum flexibility in evaluating the many different preconditioners.
38: The PCSetType() routine is provided for those situations where it
39: is necessary to set the preconditioner independently of the command
40: line or options database. This might be the case, for example, when
41: the choice of preconditioner changes during the execution of the
42: program, and the user's application is taking responsibility for
43: choosing the appropriate preconditioner. In other words, this
44: routine is not for beginners.
46: Level: intermediate
48: Developer Note: PCRegister() is used to add preconditioner types to PCList from which they
49: are accessed by PCSetType().
51: .seealso: KSPSetType(), PCType, PCRegister(), PCCreate(), KSPGetPC()
53: @*/
54: PetscErrorCode PCSetType(PC pc,PCType type)
55: {
56: PetscBool match;
57: PetscErrorCode (*r)(PC);
62: PetscObjectTypeCompare((PetscObject)pc,type,&match);
63: if (match) return 0;
65: PetscFunctionListFind(PCList,type,&r);
67: /* Destroy the previous private PC context */
68: if (pc->ops->destroy) {
69: (*pc->ops->destroy)(pc);
70: pc->ops->destroy = NULL;
71: pc->data = NULL;
72: }
73: PetscFunctionListDestroy(&((PetscObject)pc)->qlist);
74: /* Reinitialize function pointers in PCOps structure */
75: PetscMemzero(pc->ops,sizeof(struct _PCOps));
76: /* XXX Is this OK?? */
77: pc->modifysubmatrices = NULL;
78: pc->modifysubmatricesP = NULL;
79: /* Call the PCCreate_XXX routine for this particular preconditioner */
80: pc->setupcalled = 0;
82: PetscObjectChangeTypeName((PetscObject)pc,type);
83: (*r)(pc);
84: return 0;
85: }
87: /*@C
88: PCGetType - Gets the PC method type and name (as a string) from the PC
89: context.
91: Not Collective
93: Input Parameter:
94: . pc - the preconditioner context
96: Output Parameter:
97: . type - name of preconditioner method
99: Level: intermediate
101: .seealso: PCSetType()
103: @*/
104: PetscErrorCode PCGetType(PC pc,PCType *type)
105: {
108: *type = ((PetscObject)pc)->type_name;
109: return 0;
110: }
112: extern PetscErrorCode PCGetDefaultType_Private(PC,const char*[]);
114: /*@
115: PCSetFromOptions - Sets PC options from the options database.
116: This routine must be called before PCSetUp() if the user is to be
117: allowed to set the preconditioner method.
119: Collective on PC
121: Input Parameter:
122: . pc - the preconditioner context
124: Options Database:
125: . -pc_use_amat true,false - see PCSetUseAmat()
127: Level: developer
129: .seealso: PCSetUseAmat()
131: @*/
132: PetscErrorCode PCSetFromOptions(PC pc)
133: {
135: char type[256];
136: const char *def;
137: PetscBool flg;
141: PCRegisterAll();
142: PetscObjectOptionsBegin((PetscObject)pc);
143: if (!((PetscObject)pc)->type_name) {
144: PCGetDefaultType_Private(pc,&def);
145: } else {
146: def = ((PetscObject)pc)->type_name;
147: }
149: PetscOptionsFList("-pc_type","Preconditioner","PCSetType",PCList,def,type,256,&flg);
150: if (flg) {
151: PCSetType(pc,type);
152: } else if (!((PetscObject)pc)->type_name) {
153: PCSetType(pc,def);
154: }
156: PetscObjectTypeCompare((PetscObject)pc,PCNONE,&flg);
157: if (flg) goto skipoptions;
159: PetscOptionsBool("-pc_use_amat","use Amat (instead of Pmat) to define preconditioner in nested inner solves","PCSetUseAmat",pc->useAmat,&pc->useAmat,NULL);
161: if (pc->ops->setfromoptions) {
162: (*pc->ops->setfromoptions)(PetscOptionsObject,pc);
163: }
165: skipoptions:
166: /* process any options handlers added with PetscObjectAddOptionsHandler() */
167: PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)pc);
168: PetscOptionsEnd();
169: pc->setfromoptionscalled++;
170: return 0;
171: }
173: /*@
174: PCSetDM - Sets the DM that may be used by some preconditioners
176: Logically Collective on PC
178: Input Parameters:
179: + pc - the preconditioner context
180: - dm - the dm, can be NULL
182: Level: intermediate
184: Developer Notes:
185: The routines KSP/SNES/TSSetDM() require the dm to be non-NULL, but this one can be NULL since all it does is
186: replace the current DM
188: .seealso: PCGetDM(), KSPSetDM(), KSPGetDM()
189: @*/
190: PetscErrorCode PCSetDM(PC pc,DM dm)
191: {
193: if (dm) PetscObjectReference((PetscObject)dm);
194: DMDestroy(&pc->dm);
195: pc->dm = dm;
196: return 0;
197: }
199: /*@
200: PCGetDM - Gets the DM that may be used by some preconditioners
202: Not Collective
204: Input Parameter:
205: . pc - the preconditioner context
207: Output Parameter:
208: . dm - the dm
210: Level: intermediate
212: .seealso: PCSetDM(), KSPSetDM(), KSPGetDM()
213: @*/
214: PetscErrorCode PCGetDM(PC pc,DM *dm)
215: {
217: *dm = pc->dm;
218: return 0;
219: }
221: /*@
222: PCSetApplicationContext - Sets the optional user-defined context for the linear solver.
224: Logically Collective on PC
226: Input Parameters:
227: + pc - the PC context
228: - usrP - optional user context
230: Level: intermediate
232: .seealso: PCGetApplicationContext()
233: @*/
234: PetscErrorCode PCSetApplicationContext(PC pc,void *usrP)
235: {
237: pc->user = usrP;
238: return 0;
239: }
241: /*@
242: PCGetApplicationContext - Gets the user-defined context for the linear solver.
244: Not Collective
246: Input Parameter:
247: . pc - PC context
249: Output Parameter:
250: . usrP - user context
252: Level: intermediate
254: .seealso: PCSetApplicationContext()
255: @*/
256: PetscErrorCode PCGetApplicationContext(PC pc,void *usrP)
257: {
259: *(void**)usrP = pc->user;
260: return 0;
261: }