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