Actual source code: tsreg.c

  1: /*$Id: tsreg.c,v 1.71 2001/08/06 21:18:08 bsmith Exp $*/

 3:  #include src/ts/tsimpl.h

  5: PetscFList TSList                       = PETSC_NULL;
  6: PetscTruth TSRegisterAllCalled          = PETSC_FALSE;
  7: PetscFList TSSerializeList              = PETSC_NULL;
  8: PetscTruth TSSerializeRegisterAllCalled = PETSC_FALSE;

 10: /*@C
 11:   TSSetType - Sets the method for the timestepping solver.  

 13:   Collective on TS

 15:   Input Parameters:
 16: + ts   - The TS context
 17: - type - A known method

 19:   Options Database Command:
 20: . -ts_type <type> - Sets the method; use -help for a list of available methods (for instance, euler)

 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

 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.

 41:    Level: intermediate

 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;

 54:   PetscTypeCompare((PetscObject) ts, type, &match);
 55:   if (match == PETSC_TRUE) return(0);

 57:   /* Get the function pointers for the method requested */
 58:   if (TSRegisterAllCalled == PETSC_FALSE) {
 59:     TSRegisterAll(PETSC_NULL);
 60:   }
 61:   PetscFListFind(ts->comm, TSList, type, (void (**)(void)) &r);
 62:   if (!r) SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE, "Unknown TS type: %s", type);

 64:   if (ts->sles != PETSC_NULL) {
 65:     SLESDestroy(ts->sles);
 66:     ts->sles = PETSC_NULL;
 67:   }
 68:   if (ts->snes != PETSC_NULL) {
 69:     SNESDestroy(ts->snes);
 70:     ts->snes = PETSC_NULL;
 71:   }
 72:   if (ts->ops->destroy != PETSC_NULL) {
 73:     (*(ts)->ops->destroy)(ts);
 74:   }
 75:   (*r)(ts);

 77:   PetscObjectChangeTypeName((PetscObject)ts, type);
 78:   return(0);
 79: }

 81: /*@C
 82:   TSGetType - Gets the TS method type (as a string).

 84:   Not Collective

 86:   Input Parameter:
 87: . ts - The TS

 89:   Output Parameter:
 90: . type - The name of TS method

 92:   Level: intermediate

 94: .keywords: TS, timestepper, get, type, name
 95: .seealso TSSetType()
 96: @*/
 97: int TSGetType(TS ts, TSType *type)
 98: {

104:   if (TSRegisterAllCalled == PETSC_FALSE) {
105:     TSRegisterAll(PETSC_NULL);
106:   }
107:   *type = ts->type_name;
108:   return(0);
109: }

111: /*@C
112:   TSSetSerializeType - Sets the serialization method for the ts.

114:   Collective on TS

116:   Input Parameters:
117: + ts     - The TS context
118: - method - A known method

120:   Options Database Command:
121: . -ts_serialize_type <method> - Sets the method; use -help for a list
122:                                 of available methods (for instance, gbeuler_binary)

124:   Notes:
125:   See "petsc/include/ts.h" for available methods (for instance)
126: . GTS_SER_BEULER_BINARY - Grid Backwards Euler TS to binary file

128:   Normally, it is best to use the TSSetFromOptions() command and
129:   then set the TS type from the options database rather than by using
130:   this routine.  Using the options database provides the user with
131:   maximum flexibility in evaluating the many different solvers.
132:   The TSSetSerializeType() routine is provided for those situations
133:   where it is necessary to set the application ordering independently of the
134:   command line or options database.  This might be the case, for example,
135:   when the choice of solver changes during the execution of the
136:   program, and the user's application is taking responsibility for
137:   choosing the appropriate method.  In other words, this routine is
138:   not for beginners.

140:   Level: intermediate

142: .keywords: TS, set, type, serialization
143: .seealso TSSetType()
144: @*/
145: int TSSetSerializeType(TS ts, TSSerializeType method)
146: {
147:   int      (*r)(MPI_Comm, TS *, PetscViewer, PetscTruth);
148:   PetscTruth match;
149:   int        ierr;

153:   PetscSerializeCompare((PetscObject) ts, method, &match);
154:   if (match == PETSC_TRUE) return(0);

156:   /* Get the function pointers for the method requested but do not call */
157:   if (TSSerializeRegisterAllCalled == PETSC_FALSE) {
158:     TSSerializeRegisterAll(PETSC_NULL);
159:   }
160:   PetscFListFind(ts->comm, TSSerializeList, method, (void (**)(void)) &r);
161:   if (!r) SETERRQ1(PETSC_ERR_ARG_WRONG, "Unknown ts serialization type: %s", method);

163:   PetscObjectChangeSerializeName((PetscObject) ts, method);
164:   return(0);
165: }

167: /*@C
168:   TSGetSerializeType - Gets the TS serialization method (as a string).

170:   Not collective

172:   Input Parameter:
173: . ts   - The ts

175:   Output Parameter:
176: . type - The name of TS serialization method

178:   Level: intermediate

180: .keywords: TS, get, serialize, type, name
181: .seealso TSSetType()
182: @*/
183: int TSGetSerializeType(TS ts, TSSerializeType *type)
184: {

190:   if (TSSerializeRegisterAllCalled == PETSC_FALSE) {
191:     TSSerializeRegisterAll(PETSC_NULL);
192:   }
193:   *type = ts->serialize_name;
194:   return(0);
195: }

197: /*--------------------------------------------------------------------------------------------------------------------*/
198: /*@C
199:   TSRegister - Adds a creation method to the TS package.

201:   Synopsis:

203:   TSRegister(char *name, char *path, char *func_name, int (*create_func)(TS))

205:   Not Collective

207:   Input Parameters:
208: + name        - The name of a new user-defined creation routine
209: . path        - The path (either absolute or relative) of the library containing this routine
210: . func_name   - The name of the creation routine
211: - create_func - The creation routine itself

213:   Notes:
214:   TSRegister() may be called multiple times to add several user-defined tses.

216:   If dynamic libraries are used, then the fourth input argument (create_func) is ignored.

218:   Sample usage:
219: .vb
220:   TSRegisterDynamic("my_ts", "/home/username/my_lib/lib/libO/solaris/libmy.a", "MyTSCreate", MyTSCreate);
221: .ve

223:   Then, your ts type can be chosen with the procedural interface via
224: .vb
225:     TSCreate(MPI_Comm, TS *);
226:     TSSetType(vec, "my_ts")
227: .ve
228:   or at runtime via the option
229: .vb
230:     -ts_type my_ts
231: .ve

233:   Note: $PETSC_ARCH and $BOPT occuring in pathname will be replaced with appropriate values.

235:   Level: advanced

237: .keywords: TS, register
238: .seealso: TSRegisterAll(), TSRegisterDestroy()
239: @*/
240: int TSRegister(const char sname[], const char path[], const char name[], int (*function)(TS))
241: {
242:   char fullname[256];
243:   int  ierr;

246:   PetscStrcpy(fullname, path);
247:   PetscStrcat(fullname, ":");
248:   PetscStrcat(fullname, name);
249:   PetscFListAdd(&TSList, sname, fullname, (void (*)(void)) function);
250:   return(0);
251: }

253: /*@C
254:   TSSerializeRegister - Adds a serialization method to the ts package.

256:   Synopsis:

258:   TSSerializeRegister(char *name, char *path, char *func_name,
259:                         int (*serialize_func)(MPI_Comm, TS *, PetscViewer, PetscTruth))

261:   Not Collective

263:   Input Parameters:
264: + name           - The name of a new user-defined serialization routine
265: . path           - The path (either absolute or relative) of the library containing this routine
266: . func_name      - The name of the serialization routine
267: - serialize_func - The serialization routine itself

269:   Notes:
270:   TSSerializeRegister() may be called multiple times to add several user-defined serializers.

272:   If dynamic libraries are used, then the fourth input argument (serialize_func) is ignored.

274:   Sample usage:
275: .vb
276:   TSSerializeRegisterDynamic("my_store", "/home/username/my_lib/lib/libO/solaris/libmy.a", "MyStoreFunc", MyStoreFunc);
277: .ve

279:   Then, your serialization can be chosen with the procedural interface via
280: .vb
281:     TSSetSerializeType(ts, "my_store")
282: .ve
283:   or at runtime via the option
284: .vb
285:     -ts_serialize_type my_store
286: .ve

288:   Note: $PETSC_ARCH and $BOPT occuring in pathname will be replaced with appropriate values.

290:   Level: advanced

292: .keywords: ts, register
293: .seealso: TSSerializeRegisterAll(), TSSerializeRegisterDestroy()
294: M*/
295: int TSSerializeRegister(const char sname[], const char path[], const char name[],
296:                           int (*function)(MPI_Comm, TS *, PetscViewer, PetscTruth))
297: {
298:   char fullname[256];
299:   int  ierr;

302:   PetscStrcpy(fullname, path);
303:   PetscStrcat(fullname, ":");
304:   PetscStrcat(fullname, name);
305:   PetscFListAdd(&TSSerializeList, sname, fullname, (void (*)(void)) function);
306:   return(0);
307: }

309: /*-------------------------------------------------------------------------------------------------------------------*/
310: /*@C
311:    TSRegisterDestroy - Frees the list of timestepping routines that were registered by TSREgister().

313:    Not Collective

315:    Level: advanced

317: .keywords: TS, timestepper, register, destroy
318: .seealso: TSRegister(), TSRegisterAll(), TSSerializeRegisterDestroy()
319: @*/
320: int TSRegisterDestroy(void)
321: {

325:   if (TSList != PETSC_NULL) {
326:     PetscFListDestroy(&TSList);
327:     TSList = PETSC_NULL;
328:   }
329:   TSRegisterAllCalled = PETSC_FALSE;
330:   return(0);
331: }

333: /*@C
334:   TSSerializeRegisterDestroy - Frees the list of serialization routines for
335:   timesteppers that were registered by FListAdd().

337:   Not collective

339:   Level: advanced

341: .keywords: ts, serialization, register, destroy
342: .seealso: TSSerializeRegisterAll(), TSRegisterDestroy()
343: @*/
344: int TSSerializeRegisterDestroy()
345: {

349:   if (TSSerializeList != PETSC_NULL) {
350:     PetscFListDestroy(&TSSerializeList);
351:     TSSerializeList = PETSC_NULL;
352:   }
353:   TSSerializeRegisterAllCalled = PETSC_FALSE;
354:   return(0);
355: }