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