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