1 /*$Id: tsreg.c,v 1.71 2001/08/06 21:18:08 bsmith Exp $*/ 2 3 #include "src/ts/tsimpl.h" /*I "petscts.h" I*/ 4 5 PetscFList TSList = PETSC_NULL; 6 PetscTruth TSRegisterAllCalled = PETSC_FALSE; 7 PetscFList TSSerializeList = PETSC_NULL; 8 PetscTruth TSSerializeRegisterAllCalled = PETSC_FALSE; 9 10 #undef __FUNCT__ 11 #define __FUNCT__ "TSSetType" 12 /*@C 13 TSSetType - Sets the method for the timestepping solver. 14 15 Collective on TS 16 17 Input Parameters: 18 + ts - The TS context 19 - type - A known method 20 21 Options Database Command: 22 . -ts_type <type> - Sets the method; use -help for a list of available methods (for instance, euler) 23 24 Notes: 25 See "petsc/include/petscts.h" for available methods (for instance) 26 + TS_EULER - Euler 27 . TS_PVODE - PVODE interface 28 . TS_BEULER - Backward Euler 29 - TS_PSEUDO - Pseudo-timestepping 30 31 Normally, it is best to use the TSSetFromOptions() command and 32 then set the TS type from the options database rather than by using 33 this routine. Using the options database provides the user with 34 maximum flexibility in evaluating the many different solvers. 35 The TSSetType() routine is provided for those situations where it 36 is necessary to set the timestepping solver independently of the 37 command line or options database. This might be the case, for example, 38 when the choice of solver changes during the execution of the 39 program, and the user's application is taking responsibility for 40 choosing the appropriate method. In other words, this routine is 41 not for beginners. 42 43 Level: intermediate 44 45 .keywords: TS, set, type 46 .seealso TSSetSerializeType() 47 @*/ 48 int TSSetType(TS ts, TSType type) 49 { 50 int (*r)(TS); 51 PetscTruth match; 52 int ierr; 53 54 PetscFunctionBegin; 55 PetscValidHeaderSpecific(ts, TS_COOKIE); 56 ierr = PetscTypeCompare((PetscObject) ts, type, &match); CHKERRQ(ierr); 57 if (match == PETSC_TRUE) PetscFunctionReturn(0); 58 59 /* Get the function pointers for the method requested */ 60 if (TSRegisterAllCalled == PETSC_FALSE) { 61 ierr = TSRegisterAll(PETSC_NULL); CHKERRQ(ierr); 62 } 63 ierr = PetscFListFind(ts->comm, TSList, type, (void (**)(void)) &r); CHKERRQ(ierr); 64 if (!r) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE, "Unknown TS type: %s", type); 65 66 if (ts->sles != PETSC_NULL) { 67 ierr = SLESDestroy(ts->sles); CHKERRQ(ierr); 68 ts->sles = PETSC_NULL; 69 } 70 if (ts->snes != PETSC_NULL) { 71 ierr = SNESDestroy(ts->snes); CHKERRQ(ierr); 72 ts->snes = PETSC_NULL; 73 } 74 if (ts->ops->destroy != PETSC_NULL) { 75 ierr = (*(ts)->ops->destroy)(ts); CHKERRQ(ierr); 76 } 77 ierr = (*r)(ts); CHKERRQ(ierr); 78 79 ierr = PetscObjectChangeTypeName((PetscObject)ts, type); CHKERRQ(ierr); 80 PetscFunctionReturn(0); 81 } 82 83 #undef __FUNCT__ 84 #define __FUNCT__ "TSGetType" 85 /*@C 86 TSGetType - Gets the TS method type (as a string). 87 88 Not Collective 89 90 Input Parameter: 91 . ts - The TS 92 93 Output Parameter: 94 . type - The name of TS method 95 96 Level: intermediate 97 98 .keywords: TS, timestepper, get, type, name 99 .seealso TSSetType() 100 @*/ 101 int TSGetType(TS ts, TSType *type) 102 { 103 int ierr; 104 105 PetscFunctionBegin; 106 PetscValidHeaderSpecific(ts, TS_COOKIE); 107 PetscValidPointer(type); 108 if (TSRegisterAllCalled == PETSC_FALSE) { 109 ierr = TSRegisterAll(PETSC_NULL); CHKERRQ(ierr); 110 } 111 *type = ts->type_name; 112 PetscFunctionReturn(0); 113 } 114 115 #undef __FUNCT__ 116 #define __FUNCT__ "TSSetSerializeType" 117 /*@C 118 TSSetSerializeType - Sets the serialization method for the ts. 119 120 Collective on TS 121 122 Input Parameters: 123 + ts - The TS context 124 - method - A known method 125 126 Options Database Command: 127 . -ts_serialize_type <method> - Sets the method; use -help for a list 128 of available methods (for instance, gbeuler_binary) 129 130 Notes: 131 See "petsc/include/ts.h" for available methods (for instance) 132 . GTS_SER_BEULER_BINARY - Grid Backwards Euler TS to binary file 133 134 Normally, it is best to use the TSSetFromOptions() command and 135 then set the TS type from the options database rather than by using 136 this routine. Using the options database provides the user with 137 maximum flexibility in evaluating the many different solvers. 138 The TSSetSerializeType() routine is provided for those situations 139 where it is necessary to set the application ordering independently of the 140 command line or options database. This might be the case, for example, 141 when the choice of solver changes during the execution of the 142 program, and the user's application is taking responsibility for 143 choosing the appropriate method. In other words, this routine is 144 not for beginners. 145 146 Level: intermediate 147 148 .keywords: TS, set, type, serialization 149 .seealso TSSetType() 150 @*/ 151 int TSSetSerializeType(TS ts, TSSerializeType method) 152 { 153 int (*r)(MPI_Comm, TS *, PetscViewer, PetscTruth); 154 PetscTruth match; 155 int ierr; 156 157 PetscFunctionBegin; 158 PetscValidHeaderSpecific(ts, TS_COOKIE); 159 ierr = PetscSerializeCompare((PetscObject) ts, method, &match); CHKERRQ(ierr); 160 if (match == PETSC_TRUE) PetscFunctionReturn(0); 161 162 /* Get the function pointers for the method requested but do not call */ 163 if (TSSerializeRegisterAllCalled == PETSC_FALSE) { 164 ierr = TSSerializeRegisterAll(PETSC_NULL); CHKERRQ(ierr); 165 } 166 ierr = PetscFListFind(ts->comm, TSSerializeList, method, (void (**)(void)) &r); CHKERRQ(ierr); 167 if (!r) SETERRQ1(PETSC_ERR_ARG_WRONG, "Unknown ts serialization type: %s", method); 168 169 ierr = PetscObjectChangeSerializeName((PetscObject) ts, method); CHKERRQ(ierr); 170 PetscFunctionReturn(0); 171 } 172 173 #undef __FUNCT__ 174 #define __FUNCT__ "TSGetSerializeType" 175 /*@C 176 TSGetSerializeType - Gets the TS serialization method (as a string). 177 178 Not collective 179 180 Input Parameter: 181 . ts - The ts 182 183 Output Parameter: 184 . type - The name of TS serialization method 185 186 Level: intermediate 187 188 .keywords: TS, get, serialize, type, name 189 .seealso TSSetType() 190 @*/ 191 int TSGetSerializeType(TS ts, TSSerializeType *type) 192 { 193 int ierr; 194 195 PetscFunctionBegin; 196 PetscValidHeaderSpecific(ts, TS_COOKIE); 197 PetscValidPointer(type); 198 if (TSSerializeRegisterAllCalled == PETSC_FALSE) { 199 ierr = TSSerializeRegisterAll(PETSC_NULL); CHKERRQ(ierr); 200 } 201 *type = ts->serialize_name; 202 PetscFunctionReturn(0); 203 } 204 205 /*--------------------------------------------------------------------------------------------------------------------*/ 206 /*@C 207 TSRegister - Adds a creation method to the TS package. 208 209 Synopsis: 210 211 TSRegister(char *name, char *path, char *func_name, int (*create_func)(TS)) 212 213 Not Collective 214 215 Input Parameters: 216 + name - The name of a new user-defined creation routine 217 . path - The path (either absolute or relative) of the library containing this routine 218 . func_name - The name of the creation routine 219 - create_func - The creation routine itself 220 221 Notes: 222 TSRegister() may be called multiple times to add several user-defined tses. 223 224 If dynamic libraries are used, then the fourth input argument (create_func) is ignored. 225 226 Sample usage: 227 .vb 228 TSRegisterDynamic("my_ts", "/home/username/my_lib/lib/libO/solaris/libmy.a", "MyTSCreate", MyTSCreate); 229 .ve 230 231 Then, your ts type can be chosen with the procedural interface via 232 .vb 233 TSCreate(MPI_Comm, TS *); 234 TSSetType(vec, "my_ts") 235 .ve 236 or at runtime via the option 237 .vb 238 -ts_type my_ts 239 .ve 240 241 Note: $PETSC_ARCH and $BOPT occuring in pathname will be replaced with appropriate values. 242 243 Level: advanced 244 245 .keywords: TS, register 246 .seealso: TSRegisterAll(), TSRegisterDestroy() 247 @*/ 248 #undef __FUNCT__ 249 #define __FUNCT__ "TSRegister" 250 int TSRegister(const char sname[], const char path[], const char name[], int (*function)(TS)) 251 { 252 char fullname[256]; 253 int ierr; 254 255 PetscFunctionBegin; 256 ierr = PetscStrcpy(fullname, path); CHKERRQ(ierr); 257 ierr = PetscStrcat(fullname, ":"); CHKERRQ(ierr); 258 ierr = PetscStrcat(fullname, name); CHKERRQ(ierr); 259 ierr = PetscFListAdd(&TSList, sname, fullname, (void (*)(void)) function); CHKERRQ(ierr); 260 PetscFunctionReturn(0); 261 } 262 263 /*@C 264 TSSerializeRegister - Adds a serialization method to the ts package. 265 266 Synopsis: 267 268 TSSerializeRegister(char *name, char *path, char *func_name, 269 int (*serialize_func)(MPI_Comm, TS *, PetscViewer, PetscTruth)) 270 271 Not Collective 272 273 Input Parameters: 274 + name - The name of a new user-defined serialization routine 275 . path - The path (either absolute or relative) of the library containing this routine 276 . func_name - The name of the serialization routine 277 - serialize_func - The serialization routine itself 278 279 Notes: 280 TSSerializeRegister() may be called multiple times to add several user-defined serializers. 281 282 If dynamic libraries are used, then the fourth input argument (serialize_func) is ignored. 283 284 Sample usage: 285 .vb 286 TSSerializeRegisterDynamic("my_store", "/home/username/my_lib/lib/libO/solaris/libmy.a", "MyStoreFunc", MyStoreFunc); 287 .ve 288 289 Then, your serialization can be chosen with the procedural interface via 290 .vb 291 TSSetSerializeType(ts, "my_store") 292 .ve 293 or at runtime via the option 294 .vb 295 -ts_serialize_type my_store 296 .ve 297 298 Note: $PETSC_ARCH and $BOPT occuring in pathname will be replaced with appropriate values. 299 300 Level: advanced 301 302 .keywords: ts, register 303 .seealso: TSSerializeRegisterAll(), TSSerializeRegisterDestroy() 304 M*/ 305 #undef __FUNCT__ 306 #define __FUNCT__ "TSSerializeRegister" 307 int TSSerializeRegister(const char sname[], const char path[], const char name[], 308 int (*function)(MPI_Comm, TS *, PetscViewer, PetscTruth)) 309 { 310 char fullname[256]; 311 int ierr; 312 313 PetscFunctionBegin; 314 ierr = PetscStrcpy(fullname, path); CHKERRQ(ierr); 315 ierr = PetscStrcat(fullname, ":"); CHKERRQ(ierr); 316 ierr = PetscStrcat(fullname, name); CHKERRQ(ierr); 317 ierr = PetscFListAdd(&TSSerializeList, sname, fullname, (void (*)(void)) function); CHKERRQ(ierr); 318 PetscFunctionReturn(0); 319 } 320 321 /*-------------------------------------------------------------------------------------------------------------------*/ 322 #undef __FUNCT__ 323 #define __FUNCT__ "TSRegisterDestroy" 324 /*@C 325 TSRegisterDestroy - Frees the list of timestepping routines that were registered by TSREgister(). 326 327 Not Collective 328 329 Level: advanced 330 331 .keywords: TS, timestepper, register, destroy 332 .seealso: TSRegister(), TSRegisterAll(), TSSerializeRegisterDestroy() 333 @*/ 334 int TSRegisterDestroy(void) 335 { 336 int ierr; 337 338 PetscFunctionBegin; 339 if (TSList != PETSC_NULL) { 340 ierr = PetscFListDestroy(&TSList); CHKERRQ(ierr); 341 TSList = PETSC_NULL; 342 } 343 TSRegisterAllCalled = PETSC_FALSE; 344 PetscFunctionReturn(0); 345 } 346 347 #undef __FUNCT__ 348 #define __FUNCT__ "TSSerializeRegisterDestroy" 349 /*@C 350 TSSerializeRegisterDestroy - Frees the list of serialization routines for 351 timesteppers that were registered by FListAdd(). 352 353 Not collective 354 355 Level: advanced 356 357 .keywords: ts, serialization, register, destroy 358 .seealso: TSSerializeRegisterAll(), TSRegisterDestroy() 359 @*/ 360 int TSSerializeRegisterDestroy() 361 { 362 int ierr; 363 364 PetscFunctionBegin; 365 if (TSSerializeList != PETSC_NULL) { 366 ierr = PetscFListDestroy(&TSSerializeList); CHKERRQ(ierr); 367 TSSerializeList = PETSC_NULL; 368 } 369 TSSerializeRegisterAllCalled = PETSC_FALSE; 370 PetscFunctionReturn(0); 371 } 372