1 2 /* 3 Routines to set PC methods and options. 4 */ 5 6 #include <petsc/private/pcimpl.h> /*I "petscpc.h" I*/ 7 #include <petscdm.h> 8 9 PetscBool PCRegisterAllCalled = PETSC_FALSE; 10 /* 11 Contains the list of registered KSP routines 12 */ 13 PetscFunctionList PCList = 0; 14 15 #undef __FUNCT__ 16 #define __FUNCT__ "PCSetType" 17 /*@C 18 PCSetType - Builds PC for a particular preconditioner type 19 20 Collective on PC 21 22 Input Parameter: 23 + pc - the preconditioner context. 24 - type - a known method 25 26 Options Database Key: 27 . -pc_type <type> - Sets PC type 28 29 Use -help for a list of available methods (for instance, 30 jacobi or bjacobi) 31 32 Notes: 33 See "petsc/include/petscpc.h" for available methods (for instance, 34 PCJACOBI, PCILU, or PCBJACOBI). 35 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. 47 48 Level: intermediate 49 50 Developer Note: PCRegister() is used to add preconditioner types to PCList from which they 51 are accessed by PCSetType(). 52 53 .keywords: PC, set, method, type 54 55 .seealso: KSPSetType(), PCType, PCRegister(), PCCreate(), KSPGetPC() 56 57 @*/ 58 PetscErrorCode PCSetType(PC pc,PCType type) 59 { 60 PetscErrorCode ierr,(*r)(PC); 61 PetscBool match; 62 63 PetscFunctionBegin; 64 PetscValidHeaderSpecific(pc,PC_CLASSID,1); 65 PetscValidCharPointer(type,2); 66 67 ierr = PetscObjectTypeCompare((PetscObject)pc,type,&match);CHKERRQ(ierr); 68 if (match) PetscFunctionReturn(0); 69 70 ierr = PetscFunctionListFind(PCList,type,&r);CHKERRQ(ierr); 71 if (!r) SETERRQ1(PetscObjectComm((PetscObject)pc),PETSC_ERR_ARG_UNKNOWN_TYPE,"Unable to find requested PC type %s",type); 72 /* Destroy the previous private PC context */ 73 if (pc->ops->destroy) { 74 ierr = (*pc->ops->destroy)(pc);CHKERRQ(ierr); 75 pc->ops->destroy = NULL; 76 pc->data = 0; 77 } 78 ierr = PetscFunctionListDestroy(&((PetscObject)pc)->qlist);CHKERRQ(ierr); 79 /* Reinitialize function pointers in PCOps structure */ 80 ierr = PetscMemzero(pc->ops,sizeof(struct _PCOps));CHKERRQ(ierr); 81 /* XXX Is this OK?? */ 82 pc->modifysubmatrices = 0; 83 pc->modifysubmatricesP = 0; 84 /* Call the PCCreate_XXX routine for this particular preconditioner */ 85 pc->setupcalled = 0; 86 87 ierr = PetscObjectChangeTypeName((PetscObject)pc,type);CHKERRQ(ierr); 88 ierr = (*r)(pc);CHKERRQ(ierr); 89 PetscFunctionReturn(0); 90 } 91 92 #undef __FUNCT__ 93 #define __FUNCT__ "PCGetType" 94 /*@C 95 PCGetType - Gets the PC method type and name (as a string) from the PC 96 context. 97 98 Not Collective 99 100 Input Parameter: 101 . pc - the preconditioner context 102 103 Output Parameter: 104 . type - name of preconditioner method 105 106 Level: intermediate 107 108 .keywords: PC, get, method, name, type 109 110 .seealso: PCSetType() 111 112 @*/ 113 PetscErrorCode PCGetType(PC pc,PCType *type) 114 { 115 PetscFunctionBegin; 116 PetscValidHeaderSpecific(pc,PC_CLASSID,1); 117 PetscValidPointer(type,2); 118 *type = ((PetscObject)pc)->type_name; 119 PetscFunctionReturn(0); 120 } 121 122 extern PetscErrorCode PCGetDefaultType_Private(PC,const char*[]); 123 124 #undef __FUNCT__ 125 #define __FUNCT__ "PCSetFromOptions" 126 /*@ 127 PCSetFromOptions - Sets PC options from the options database. 128 This routine must be called before PCSetUp() if the user is to be 129 allowed to set the preconditioner method. 130 131 Collective on PC 132 133 Input Parameter: 134 . pc - the preconditioner context 135 136 Options Database: 137 . -pc_use_amat true,false see PCSetUseAmat() 138 139 Level: developer 140 141 .keywords: PC, set, from, options, database 142 143 .seealso: PCSetUseAmat() 144 145 @*/ 146 PetscErrorCode PCSetFromOptions(PC pc) 147 { 148 PetscErrorCode ierr; 149 char type[256]; 150 const char *def; 151 PetscBool flg; 152 153 PetscFunctionBegin; 154 PetscValidHeaderSpecific(pc,PC_CLASSID,1); 155 156 ierr = PCRegisterAll();CHKERRQ(ierr); 157 ierr = PetscObjectOptionsBegin((PetscObject)pc);CHKERRQ(ierr); 158 if (!((PetscObject)pc)->type_name) { 159 ierr = PCGetDefaultType_Private(pc,&def);CHKERRQ(ierr); 160 } else { 161 def = ((PetscObject)pc)->type_name; 162 } 163 164 ierr = PetscOptionsFList("-pc_type","Preconditioner","PCSetType",PCList,def,type,256,&flg);CHKERRQ(ierr); 165 if (flg) { 166 ierr = PCSetType(pc,type);CHKERRQ(ierr); 167 } else if (!((PetscObject)pc)->type_name) { 168 ierr = PCSetType(pc,def);CHKERRQ(ierr); 169 } 170 171 ierr = PetscObjectTypeCompare((PetscObject)pc,PCNONE,&flg);CHKERRQ(ierr); 172 if (flg) goto skipoptions; 173 174 ierr = PetscOptionsBool("-pc_use_amat","use Amat (instead of Pmat) to define preconditioner in nested inner solves","PCSetUseAmat",pc->useAmat,&pc->useAmat,NULL);CHKERRQ(ierr); 175 176 if (pc->ops->setfromoptions) { 177 ierr = (*pc->ops->setfromoptions)(PetscOptionsObject,pc);CHKERRQ(ierr); 178 } 179 180 skipoptions: 181 /* process any options handlers added with PetscObjectAddOptionsHandler() */ 182 ierr = PetscObjectProcessOptionsHandlers((PetscObject)pc);CHKERRQ(ierr); 183 ierr = PetscOptionsEnd();CHKERRQ(ierr); 184 pc->setfromoptionscalled++; 185 PetscFunctionReturn(0); 186 } 187 188 #undef __FUNCT__ 189 #define __FUNCT__ "PCSetDM" 190 /*@ 191 PCSetDM - Sets the DM that may be used by some preconditioners 192 193 Logically Collective on PC 194 195 Input Parameters: 196 + pc - the preconditioner context 197 - dm - the dm 198 199 Level: intermediate 200 201 202 .seealso: PCGetDM(), KSPSetDM(), KSPGetDM() 203 @*/ 204 PetscErrorCode PCSetDM(PC pc,DM dm) 205 { 206 PetscErrorCode ierr; 207 208 PetscFunctionBegin; 209 PetscValidHeaderSpecific(pc,PC_CLASSID,1); 210 if (dm) {ierr = PetscObjectReference((PetscObject)dm);CHKERRQ(ierr);} 211 ierr = DMDestroy(&pc->dm);CHKERRQ(ierr); 212 pc->dm = dm; 213 PetscFunctionReturn(0); 214 } 215 216 #undef __FUNCT__ 217 #define __FUNCT__ "PCGetDM" 218 /*@ 219 PCGetDM - Gets the DM that may be used by some preconditioners 220 221 Not Collective 222 223 Input Parameter: 224 . pc - the preconditioner context 225 226 Output Parameter: 227 . dm - the dm 228 229 Level: intermediate 230 231 232 .seealso: PCSetDM(), KSPSetDM(), KSPGetDM() 233 @*/ 234 PetscErrorCode PCGetDM(PC pc,DM *dm) 235 { 236 PetscFunctionBegin; 237 PetscValidHeaderSpecific(pc,PC_CLASSID,1); 238 *dm = pc->dm; 239 PetscFunctionReturn(0); 240 } 241 242 #undef __FUNCT__ 243 #define __FUNCT__ "PCSetApplicationContext" 244 /*@ 245 PCSetApplicationContext - Sets the optional user-defined context for the linear solver. 246 247 Logically Collective on PC 248 249 Input Parameters: 250 + pc - the PC context 251 - usrP - optional user context 252 253 Level: intermediate 254 255 .keywords: PC, set, application, context 256 257 .seealso: PCGetApplicationContext() 258 @*/ 259 PetscErrorCode PCSetApplicationContext(PC pc,void *usrP) 260 { 261 PetscFunctionBegin; 262 PetscValidHeaderSpecific(pc,PC_CLASSID,1); 263 pc->user = usrP; 264 PetscFunctionReturn(0); 265 } 266 267 #undef __FUNCT__ 268 #define __FUNCT__ "PCGetApplicationContext" 269 /*@ 270 PCGetApplicationContext - Gets the user-defined context for the linear solver. 271 272 Not Collective 273 274 Input Parameter: 275 . pc - PC context 276 277 Output Parameter: 278 . usrP - user context 279 280 Level: intermediate 281 282 .keywords: PC, get, application, context 283 284 .seealso: PCSetApplicationContext() 285 @*/ 286 PetscErrorCode PCGetApplicationContext(PC pc,void *usrP) 287 { 288 PetscFunctionBegin; 289 PetscValidHeaderSpecific(pc,PC_CLASSID,1); 290 *(void**)usrP = pc->user; 291 PetscFunctionReturn(0); 292 } 293 294