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 /*MC 207 TSRegisterDynamic - Adds a creation method to the TS package. 208 209 Synopsis: 210 211 TSRegisterDynamic(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 TSRegisterDynamic() 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 Notes: $PETSC_ARCH and $BOPT occuring in pathname will be replaced with appropriate values. 242 If your function is not being put into a shared library then use TSRegister() instead 243 244 Level: advanced 245 246 .keywords: TS, register 247 .seealso: TSRegisterAll(), TSRegisterDestroy() 248 M*/ 249 250 #undef __FUNCT__ 251 #define __FUNCT__ "TSRegister" 252 /*@C 253 TSRegister - See TSRegisterDynamic() 254 255 Level: advanced 256 @*/ 257 int TSRegister(const char sname[], const char path[], const char name[], int (*function)(TS)) 258 { 259 char fullname[256]; 260 int ierr; 261 262 PetscFunctionBegin; 263 ierr = PetscStrcpy(fullname, path); CHKERRQ(ierr); 264 ierr = PetscStrcat(fullname, ":"); CHKERRQ(ierr); 265 ierr = PetscStrcat(fullname, name); CHKERRQ(ierr); 266 ierr = PetscFListAdd(&TSList, sname, fullname, (void (*)(void)) function); CHKERRQ(ierr); 267 PetscFunctionReturn(0); 268 } 269 270 /*@C 271 TSSerializeRegister - Adds a serialization method to the ts package. 272 273 Synopsis: 274 275 TSSerializeRegister(char *name, char *path, char *func_name, 276 int (*serialize_func)(MPI_Comm, TS *, PetscViewer, PetscTruth)) 277 278 Not Collective 279 280 Input Parameters: 281 + name - The name of a new user-defined serialization routine 282 . path - The path (either absolute or relative) of the library containing this routine 283 . func_name - The name of the serialization routine 284 - serialize_func - The serialization routine itself 285 286 Notes: 287 TSSerializeRegister() may be called multiple times to add several user-defined serializers. 288 289 If dynamic libraries are used, then the fourth input argument (serialize_func) is ignored. 290 291 Sample usage: 292 .vb 293 TSSerializeRegisterDynamic("my_store", "/home/username/my_lib/lib/libO/solaris/libmy.a", "MyStoreFunc", MyStoreFunc); 294 .ve 295 296 Then, your serialization can be chosen with the procedural interface via 297 .vb 298 TSSetSerializeType(ts, "my_store") 299 .ve 300 or at runtime via the option 301 .vb 302 -ts_serialize_type my_store 303 .ve 304 305 Note: $PETSC_ARCH and $BOPT occuring in pathname will be replaced with appropriate values. 306 307 Level: advanced 308 309 .keywords: ts, register 310 .seealso: TSSerializeRegisterAll(), TSSerializeRegisterDestroy() 311 M*/ 312 #undef __FUNCT__ 313 #define __FUNCT__ "TSSerializeRegister" 314 int TSSerializeRegister(const char sname[], const char path[], const char name[], 315 int (*function)(MPI_Comm, TS *, PetscViewer, PetscTruth)) 316 { 317 char fullname[256]; 318 int ierr; 319 320 PetscFunctionBegin; 321 ierr = PetscStrcpy(fullname, path); CHKERRQ(ierr); 322 ierr = PetscStrcat(fullname, ":"); CHKERRQ(ierr); 323 ierr = PetscStrcat(fullname, name); CHKERRQ(ierr); 324 ierr = PetscFListAdd(&TSSerializeList, sname, fullname, (void (*)(void)) function); CHKERRQ(ierr); 325 PetscFunctionReturn(0); 326 } 327 328 /*-------------------------------------------------------------------------------------------------------------------*/ 329 #undef __FUNCT__ 330 #define __FUNCT__ "TSRegisterDestroy" 331 /*@C 332 TSRegisterDestroy - Frees the list of timestepping routines that were registered by TSRegister()/TSRegisterDynamic(). 333 334 Not Collective 335 336 Level: advanced 337 338 .keywords: TS, timestepper, register, destroy 339 .seealso: TSRegister(), TSRegisterAll(), TSSerializeRegisterDestroy(), TSRegisterDynamic() 340 @*/ 341 int TSRegisterDestroy(void) 342 { 343 int ierr; 344 345 PetscFunctionBegin; 346 if (TSList != PETSC_NULL) { 347 ierr = PetscFListDestroy(&TSList); CHKERRQ(ierr); 348 TSList = PETSC_NULL; 349 } 350 TSRegisterAllCalled = PETSC_FALSE; 351 PetscFunctionReturn(0); 352 } 353 354 #undef __FUNCT__ 355 #define __FUNCT__ "TSSerializeRegisterDestroy" 356 /*@C 357 TSSerializeRegisterDestroy - Frees the list of serialization routines for 358 timesteppers that were registered by FListAdd(). 359 360 Not collective 361 362 Level: advanced 363 364 .keywords: ts, serialization, register, destroy 365 .seealso: TSSerializeRegisterAll(), TSRegisterDestroy() 366 @*/ 367 int TSSerializeRegisterDestroy() 368 { 369 int ierr; 370 371 PetscFunctionBegin; 372 if (TSSerializeList != PETSC_NULL) { 373 ierr = PetscFListDestroy(&TSSerializeList); CHKERRQ(ierr); 374 TSSerializeList = PETSC_NULL; 375 } 376 TSSerializeRegisterAllCalled = PETSC_FALSE; 377 PetscFunctionReturn(0); 378 } 379