Actual source code: pcset.c
petsc-3.10.5 2019-03-28
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 KSP routines
12: */
13: PetscFunctionList PCList = 0;
15: /*@C
16: PCSetType - Builds PC for a particular preconditioner type
18: Collective on PC
20: Input Parameter:
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: .keywords: PC, set, method, type
53: .seealso: KSPSetType(), PCType, PCRegister(), PCCreate(), KSPGetPC()
55: @*/
56: PetscErrorCode PCSetType(PC pc,PCType type)
57: {
58: PetscErrorCode ierr,(*r)(PC);
59: PetscBool match;
65: PetscObjectTypeCompare((PetscObject)pc,type,&match);
66: if (match) return(0);
68: PetscFunctionListFind(PCList,type,&r);
69: if (!r) SETERRQ1(PetscObjectComm((PetscObject)pc),PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested PC type %s",type);
70: /* Destroy the previous private PC context */
71: if (pc->ops->destroy) {
72: (*pc->ops->destroy)(pc);
73: pc->ops->destroy = NULL;
74: pc->data = 0;
75: }
76: PetscFunctionListDestroy(&((PetscObject)pc)->qlist);
77: /* Reinitialize function pointers in PCOps structure */
78: PetscMemzero(pc->ops,sizeof(struct _PCOps));
79: /* XXX Is this OK?? */
80: pc->modifysubmatrices = 0;
81: pc->modifysubmatricesP = 0;
82: /* Call the PCCreate_XXX routine for this particular preconditioner */
83: pc->setupcalled = 0;
85: PetscObjectChangeTypeName((PetscObject)pc,type);
86: (*r)(pc);
87: return(0);
88: }
90: /*@C
91: PCGetType - Gets the PC method type and name (as a string) from the PC
92: context.
94: Not Collective
96: Input Parameter:
97: . pc - the preconditioner context
99: Output Parameter:
100: . type - name of preconditioner method
102: Level: intermediate
104: .keywords: PC, get, method, name, type
106: .seealso: PCSetType()
108: @*/
109: PetscErrorCode PCGetType(PC pc,PCType *type)
110: {
114: *type = ((PetscObject)pc)->type_name;
115: return(0);
116: }
118: extern PetscErrorCode PCGetDefaultType_Private(PC,const char*[]);
120: /*@
121: PCSetFromOptions - Sets PC options from the options database.
122: This routine must be called before PCSetUp() if the user is to be
123: allowed to set the preconditioner method.
125: Collective on PC
127: Input Parameter:
128: . pc - the preconditioner context
130: Options Database:
131: . -pc_use_amat true,false see PCSetUseAmat()
133: Level: developer
135: .keywords: PC, set, from, options, database
137: .seealso: PCSetUseAmat()
139: @*/
140: PetscErrorCode PCSetFromOptions(PC pc)
141: {
143: char type[256];
144: const char *def;
145: PetscBool flg;
150: PCRegisterAll();
151: PetscObjectOptionsBegin((PetscObject)pc);
152: if (!((PetscObject)pc)->type_name) {
153: PCGetDefaultType_Private(pc,&def);
154: } else {
155: def = ((PetscObject)pc)->type_name;
156: }
158: PetscOptionsFList("-pc_type","Preconditioner","PCSetType",PCList,def,type,256,&flg);
159: if (flg) {
160: PCSetType(pc,type);
161: } else if (!((PetscObject)pc)->type_name) {
162: PCSetType(pc,def);
163: }
165: PetscObjectTypeCompare((PetscObject)pc,PCNONE,&flg);
166: if (flg) goto skipoptions;
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)(PetscOptionsObject,pc);
172: }
174: skipoptions:
175: /* process any options handlers added with PetscObjectAddOptionsHandler() */
176: PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)pc);
177: PetscOptionsEnd();
178: pc->setfromoptionscalled++;
179: return(0);
180: }
182: /*@
183: PCSetDM - Sets the DM that may be used by some preconditioners
185: Logically Collective on PC
187: Input Parameters:
188: + pc - the preconditioner context
189: - dm - the dm, can be NULL
191: Level: intermediate
193: Developer Notes:
194: The routines KSP/SNES/TSSetDM() require the dm to be non-NULL, but this one can be NULL since all it does is
195: replace the current DM
197: .seealso: PCGetDM(), KSPSetDM(), KSPGetDM()
198: @*/
199: PetscErrorCode PCSetDM(PC pc,DM dm)
200: {
205: if (dm) {PetscObjectReference((PetscObject)dm);}
206: DMDestroy(&pc->dm);
207: pc->dm = dm;
208: return(0);
209: }
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: }
235: /*@
236: PCSetApplicationContext - Sets the optional user-defined context for the linear solver.
238: Logically Collective on PC
240: Input Parameters:
241: + pc - the PC context
242: - usrP - optional user context
244: Level: intermediate
246: .keywords: PC, set, application, context
248: .seealso: PCGetApplicationContext()
249: @*/
250: PetscErrorCode PCSetApplicationContext(PC pc,void *usrP)
251: {
254: pc->user = usrP;
255: return(0);
256: }
258: /*@
259: PCGetApplicationContext - Gets the user-defined context for the linear solver.
261: Not Collective
263: Input Parameter:
264: . pc - PC context
266: Output Parameter:
267: . usrP - user context
269: Level: intermediate
271: .keywords: PC, get, application, context
273: .seealso: PCSetApplicationContext()
274: @*/
275: PetscErrorCode PCGetApplicationContext(PC pc,void *usrP)
276: {
279: *(void**)usrP = pc->user;
280: return(0);
281: }