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: #undef __FUNCT__  
 12: /*@C
 13:   TSSetType - Sets the method for the timestepping solver.  

 15:   Collective on TS

 17:   Input Parameters:
 18: + ts   - The TS context
 19: - type - A known method

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

 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

 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.

 43:    Level: intermediate

 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;

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

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

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

 79:   PetscObjectChangeTypeName((PetscObject)ts, type);
 80:   return(0);
 81: }

 83: #undef __FUNCT__  
 85: /*@C
 86:   TSGetType - Gets the TS method type (as a string).

 88:   Not Collective

 90:   Input Parameter:
 91: . ts - The TS

 93:   Output Parameter:
 94: . type - The name of TS method

 96:   Level: intermediate

 98: .keywords: TS, timestepper, get, type, name
 99: .seealso TSSetType()
100: @*/
101: int TSGetType(TS ts, TSType *type)
102: {

108:   if (TSRegisterAllCalled == PETSC_FALSE) {
109:     TSRegisterAll(PETSC_NULL);
110:   }
111:   *type = ts->type_name;
112:   return(0);
113: }

115: #undef __FUNCT__  
117: /*@C
118:   TSSetSerializeType - Sets the serialization method for the ts.

120:   Collective on TS

122:   Input Parameters:
123: + ts     - The TS context
124: - method - A known method

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)

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

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.

146:   Level: intermediate

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;

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

162:   /* Get the function pointers for the method requested but do not call */
163:   if (TSSerializeRegisterAllCalled == PETSC_FALSE) {
164:     TSSerializeRegisterAll(PETSC_NULL);
165:   }
166:   PetscFListFind(ts->comm, TSSerializeList, method, (void (**)(void)) &r);
167:   if (!r) SETERRQ1(PETSC_ERR_ARG_WRONG, "Unknown ts serialization type: %s", method);

169:   PetscObjectChangeSerializeName((PetscObject) ts, method);
170:   return(0);
171: }

173: #undef __FUNCT__
175: /*@C
176:   TSGetSerializeType - Gets the TS serialization method (as a string).

178:   Not collective

180:   Input Parameter:
181: . ts   - The ts

183:   Output Parameter:
184: . type - The name of TS serialization method

186:   Level: intermediate

188: .keywords: TS, get, serialize, type, name
189: .seealso TSSetType()
190: @*/
191: int TSGetSerializeType(TS ts, TSSerializeType *type)
192: {

198:   if (TSSerializeRegisterAllCalled == PETSC_FALSE) {
199:     TSSerializeRegisterAll(PETSC_NULL);
200:   }
201:   *type = ts->serialize_name;
202:   return(0);
203: }

205: /*--------------------------------------------------------------------------------------------------------------------*/
206: /*MC
207:   TSRegisterDynamic - Adds a creation method to the TS package.

209:   Synopsis:

211:   TSRegisterDynamic(char *name, char *path, char *func_name, int (*create_func)(TS))

213:   Not Collective

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

221:   Notes:
222:   TSRegisterDynamic() may be called multiple times to add several user-defined tses.

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

226:   Sample usage:
227: .vb
228:   TSRegisterDynamic("my_ts", "/home/username/my_lib/lib/libO/solaris/libmy.a", "MyTSCreate", MyTSCreate);
229: .ve

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

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

244:   Level: advanced

246: .keywords: TS, register
247: .seealso: TSRegisterAll(), TSRegisterDestroy()
248: M*/

250: #undef __FUNCT__  
252: /*@C
253:   TSRegister - See TSRegisterDynamic()

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;

263:   PetscStrcpy(fullname, path);
264:   PetscStrcat(fullname, ":");
265:   PetscStrcat(fullname, name);
266:   PetscFListAdd(&TSList, sname, fullname, (void (*)(void)) function);
267:   return(0);
268: }

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

273:   Synopsis:

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

278:   Not Collective

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

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

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

291:   Sample usage:
292: .vb
293:   TSSerializeRegisterDynamic("my_store", "/home/username/my_lib/lib/libO/solaris/libmy.a", "MyStoreFunc", MyStoreFunc);
294: .ve

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

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

307:   Level: advanced

309: .keywords: ts, register
310: .seealso: TSSerializeRegisterAll(), TSSerializeRegisterDestroy()
311: M*/
312: #undef __FUNCT__  
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;

321:   PetscStrcpy(fullname, path);
322:   PetscStrcat(fullname, ":");
323:   PetscStrcat(fullname, name);
324:   PetscFListAdd(&TSSerializeList, sname, fullname, (void (*)(void)) function);
325:   return(0);
326: }

328: /*-------------------------------------------------------------------------------------------------------------------*/
329: #undef __FUNCT__  
331: /*@C
332:    TSRegisterDestroy - Frees the list of timestepping routines that were registered by TSRegister()/TSRegisterDynamic().

334:    Not Collective

336:    Level: advanced

338: .keywords: TS, timestepper, register, destroy
339: .seealso: TSRegister(), TSRegisterAll(), TSSerializeRegisterDestroy(), TSRegisterDynamic()
340: @*/
341: int TSRegisterDestroy(void)
342: {

346:   if (TSList != PETSC_NULL) {
347:     PetscFListDestroy(&TSList);
348:     TSList = PETSC_NULL;
349:   }
350:   TSRegisterAllCalled = PETSC_FALSE;
351:   return(0);
352: }

354: #undef __FUNCT__  
356: /*@C
357:   TSSerializeRegisterDestroy - Frees the list of serialization routines for
358:   timesteppers that were registered by FListAdd().

360:   Not collective

362:   Level: advanced

364: .keywords: ts, serialization, register, destroy
365: .seealso: TSSerializeRegisterAll(), TSRegisterDestroy()
366: @*/
367: int TSSerializeRegisterDestroy()
368: {

372:   if (TSSerializeList != PETSC_NULL) {
373:     PetscFListDestroy(&TSSerializeList);
374:     TSSerializeList = PETSC_NULL;
375:   }
376:   TSSerializeRegisterAllCalled = PETSC_FALSE;
377:   return(0);
378: }