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: PetscErrorCode ierr,(*r)(PC);
57: PetscBool match;
63: PetscObjectTypeCompare((PetscObject)pc,type,&match);
64: if (match) return(0);
66: PetscFunctionListFind(PCList,type,&r);
67: if (!r) SETERRQ1(PetscObjectComm((PetscObject)pc),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) {
70: (*pc->ops->destroy)(pc);
71: pc->ops->destroy = NULL;
72: pc->data = NULL;
73: }
74: PetscFunctionListDestroy(&((PetscObject)pc)->qlist);
75: /* Reinitialize function pointers in PCOps structure */
76: PetscMemzero(pc->ops,sizeof(struct _PCOps));
77: /* XXX Is this OK?? */
78: pc->modifysubmatrices = NULL;
79: pc->modifysubmatricesP = NULL;
80: /* Call the PCCreate_XXX routine for this particular preconditioner */
81: pc->setupcalled = 0;
83: PetscObjectChangeTypeName((PetscObject)pc,type);
84: (*r)(pc);
85: return(0);
86: }
88: /*@C
89: PCGetType - Gets the PC method type and name (as a string) from the PC
90: context.
92: Not Collective
94: Input Parameter:
95: . pc - the preconditioner context
97: Output Parameter:
98: . type - name of preconditioner method
100: Level: intermediate
102: .seealso: PCSetType()
104: @*/
105: PetscErrorCode PCGetType(PC pc,PCType *type)
106: {
110: *type = ((PetscObject)pc)->type_name;
111: return(0);
112: }
114: extern PetscErrorCode PCGetDefaultType_Private(PC,const char*[]);
116: /*@
117: PCSetFromOptions - Sets PC options from the options database.
118: This routine must be called before PCSetUp() if the user is to be
119: allowed to set the preconditioner method.
121: Collective on PC
123: Input Parameter:
124: . pc - the preconditioner context
126: Options Database:
127: . -pc_use_amat true,false see PCSetUseAmat()
129: Level: developer
131: .seealso: PCSetUseAmat()
133: @*/
134: PetscErrorCode PCSetFromOptions(PC pc)
135: {
137: char type[256];
138: const char *def;
139: PetscBool flg;
144: PCRegisterAll();
145: PetscObjectOptionsBegin((PetscObject)pc);
146: if (!((PetscObject)pc)->type_name) {
147: PCGetDefaultType_Private(pc,&def);
148: } else {
149: def = ((PetscObject)pc)->type_name;
150: }
152: PetscOptionsFList("-pc_type","Preconditioner","PCSetType",PCList,def,type,256,&flg);
153: if (flg) {
154: PCSetType(pc,type);
155: } else if (!((PetscObject)pc)->type_name) {
156: PCSetType(pc,def);
157: }
159: PetscObjectTypeCompare((PetscObject)pc,PCNONE,&flg);
160: if (flg) goto skipoptions;
162: PetscOptionsBool("-pc_use_amat","use Amat (instead of Pmat) to define preconditioner in nested inner solves","PCSetUseAmat",pc->useAmat,&pc->useAmat,NULL);
164: if (pc->ops->setfromoptions) {
165: (*pc->ops->setfromoptions)(PetscOptionsObject,pc);
166: }
168: skipoptions:
169: /* process any options handlers added with PetscObjectAddOptionsHandler() */
170: PetscObjectProcessOptionsHandlers(PetscOptionsObject,(PetscObject)pc);
171: PetscOptionsEnd();
172: pc->setfromoptionscalled++;
173: return(0);
174: }
176: /*@
177: PCSetDM - Sets the DM that may be used by some preconditioners
179: Logically Collective on PC
181: Input Parameters:
182: + pc - the preconditioner context
183: - dm - the dm, can be NULL
185: Level: intermediate
187: Developer Notes:
188: The routines KSP/SNES/TSSetDM() require the dm to be non-NULL, but this one can be NULL since all it does is
189: replace the current DM
191: .seealso: PCGetDM(), KSPSetDM(), KSPGetDM()
192: @*/
193: PetscErrorCode PCSetDM(PC pc,DM dm)
194: {
199: if (dm) {PetscObjectReference((PetscObject)dm);}
200: DMDestroy(&pc->dm);
201: pc->dm = dm;
202: return(0);
203: }
205: /*@
206: PCGetDM - Gets the DM that may be used by some preconditioners
208: Not Collective
210: Input Parameter:
211: . pc - the preconditioner context
213: Output Parameter:
214: . dm - the dm
216: Level: intermediate
218: .seealso: PCSetDM(), KSPSetDM(), KSPGetDM()
219: @*/
220: PetscErrorCode PCGetDM(PC pc,DM *dm)
221: {
224: *dm = pc->dm;
225: return(0);
226: }
228: /*@
229: PCSetApplicationContext - Sets the optional user-defined context for the linear solver.
231: Logically Collective on PC
233: Input Parameters:
234: + pc - the PC context
235: - usrP - optional user context
237: Level: intermediate
239: .seealso: PCGetApplicationContext()
240: @*/
241: PetscErrorCode PCSetApplicationContext(PC pc,void *usrP)
242: {
245: pc->user = usrP;
246: return(0);
247: }
249: /*@
250: PCGetApplicationContext - Gets the user-defined context for the linear solver.
252: Not Collective
254: Input Parameter:
255: . pc - PC context
257: Output Parameter:
258: . usrP - user context
260: Level: intermediate
262: .seealso: PCSetApplicationContext()
263: @*/
264: PetscErrorCode PCGetApplicationContext(PC pc,void *usrP)
265: {
268: *(void**)usrP = pc->user;
269: return(0);
270: }