Actual source code: petscts.h

  1: /*
  2:    User interface for the timestepping package. This package
  3:    is for use in solving time-dependent PDEs.
  4: */
 7:  #include petscsnes.h

 10: /*S
 11:      TS - Abstract PETSc object that manages all time-steppers (ODE integrators)

 13:    Level: beginner

 15:   Concepts: ODE solvers

 17: .seealso:  TSCreate(), TSSetType(), TSType, SNES, KSP, PC
 18: S*/
 19: typedef struct _p_TS* TS;

 21: /*E
 22:     TSType - String with the name of a PETSc TS method or the creation function
 23:        with an optional dynamic library name, for example
 24:        http://www.mcs.anl.gov/petsc/lib.a:mytscreate()

 26:    Level: beginner

 28: .seealso: TSSetType(), TS
 29: E*/
 30: #define TSType char*
 31: #define TSEULER           "euler"
 32: #define TSBEULER          "beuler"
 33: #define TSPSEUDO          "pseudo"
 34: #define TSCN              "cn"
 35: #define TSSUNDIALS        "sundials"
 36: #define TSRK              "rk"
 37: #define TSPYTHON          "python"
 38: #define TSTHETA           "theta"
 39: #define TSALPHA           "alpha"
 40: #define TSGL              "gl"
 41: #define TSSSP             "ssp"
 42: #define TSARKIMEX         "arkimex"

 44: /*E
 45:     TSProblemType - Determines the type of problem this TS object is to be used to solve

 47:    Level: beginner

 49: .seealso: TSCreate()
 50: E*/
 51: typedef enum {TS_LINEAR,TS_NONLINEAR} TSProblemType;

 53: typedef enum {
 54:   TS_CONVERGED_ITERATING      = 0,
 55:   TS_CONVERGED_TIME           = 1,
 56:   TS_CONVERGED_ITS            = 2,
 57:   TS_DIVERGED_NONLINEAR_SOLVE = -1,
 58:   TS_DIVERGED_STEP_REJECTED   = -2
 59: } TSConvergedReason;

 62: /* Logging support */









104: typedef PetscErrorCode (*TSRHSFunction)(TS,PetscReal,Vec,Vec,void*);
105: typedef PetscErrorCode (*TSRHSJacobian)(TS,PetscReal,Vec,Mat*,Mat*,MatStructure*,void*);

111: typedef PetscErrorCode (*TSIFunction)(TS,PetscReal,Vec,Vec,Vec,void*);
112: typedef PetscErrorCode (*TSIJacobian)(TS,PetscReal,Vec,Vec,PetscReal,Mat*,Mat*,MatStructure*,void*);








151: /* Dynamic creation and loading functions */

160: /*MC
161:   TSRegisterDynamic - Adds a creation method to the TS package.

163:   Synopsis:
164:   PetscErrorCode TSRegisterDynamic(const char *name, const char *path, const char *func_name, PetscErrorCode (*create_func)(TS))

166:   Not Collective

168:   Input Parameters:
169: + name        - The name of a new user-defined creation routine
170: . path        - The path (either absolute or relative) of the library containing this routine
171: . func_name   - The name of the creation routine
172: - create_func - The creation routine itself

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

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

179:   Sample usage:
180: .vb
181:   TSRegisterDynamic("my_ts", "/home/username/my_lib/lib/libO/solaris/libmy.a", "MyTSCreate", MyTSCreate);
182: .ve

184:   Then, your ts type can be chosen with the procedural interface via
185: .vb
186:     TS ts;
187:     TSCreate(MPI_Comm, &ts);
188:     TSSetType(ts, "my_ts")
189: .ve
190:   or at runtime via the option
191: .vb
192:     -ts_type my_ts
193: .ve

195:   Notes: $PETSC_ARCH occuring in pathname will be replaced with appropriate values.
196:         If your function is not being put into a shared library then use TSRegister() instead

198:   Level: advanced

200: .keywords: TS, register
201: .seealso: TSRegisterAll(), TSRegisterDestroy()
202: M*/
203: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
204: #define TSRegisterDynamic(a,b,c,d) TSRegister(a,b,c,0)
205: #else
206: #define TSRegisterDynamic(a,b,c,d) TSRegister(a,b,c,d)
207: #endif





221: /*S
222:    TSGLAdapt - Abstract object that manages time-step adaptivity

224:    Level: beginner

226: .seealso: TSGL, TSGLAdaptCreate(), TSGLAdaptType
227: S*/
228: typedef struct _p_TSGLAdapt *TSGLAdapt;

230: /*E
231:     TSGLAdaptType - String with the name of TSGLAdapt scheme or the creation function
232:        with an optional dynamic library name, for example
233:        http://www.mcs.anl.gov/petsc/lib.a:mytsgladaptcreate()

235:    Level: beginner

237: .seealso: TSGLAdaptSetType(), TS
238: E*/
239: #define TSGLAdaptType  char*
240: #define TSGLADAPT_NONE "none"
241: #define TSGLADAPT_SIZE "size"
242: #define TSGLADAPT_BOTH "both"

244: /*MC
245:    TSGLAdaptRegisterDynamic - adds a TSGLAdapt implementation

247:    Synopsis:
248:    PetscErrorCode TSGLAdaptRegisterDynamic(const char *name_scheme,const char *path,const char *name_create,PetscErrorCode (*routine_create)(TS))

250:    Not Collective

252:    Input Parameters:
253: +  name_scheme - name of user-defined adaptivity scheme
254: .  path - path (either absolute or relative) the library containing this scheme
255: .  name_create - name of routine to create method context
256: -  routine_create - routine to create method context

258:    Notes:
259:    TSGLAdaptRegisterDynamic() may be called multiple times to add several user-defined families.

261:    If dynamic libraries are used, then the fourth input argument (routine_create)
262:    is ignored.

264:    Sample usage:
265: .vb
266:    TSGLAdaptRegisterDynamic("my_scheme",/home/username/my_lib/lib/libO/solaris/mylib.a,
267:                             "MySchemeCreate",MySchemeCreate);
268: .ve

270:    Then, your scheme can be chosen with the procedural interface via
271: $     TSGLAdaptSetType(ts,"my_scheme")
272:    or at runtime via the option
273: $     -ts_adapt_type my_scheme

275:    Level: advanced

277:    Notes: Environmental variables such as ${PETSC_ARCH}, ${PETSC_DIR}, ${PETSC_LIB_DIR},
278:           and others of the form ${any_environmental_variable} occuring in pathname will be 
279:           replaced with appropriate values.

281: .keywords: TSGLAdapt, register

283: .seealso: TSGLAdaptRegisterAll()
284: M*/
285: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
286: #  define TSGLAdaptRegisterDynamic(a,b,c,d)  TSGLAdaptRegister(a,b,c,0)
287: #else
288: #  define TSGLAdaptRegisterDynamic(a,b,c,d)  TSGLAdaptRegister(a,b,c,d)
289: #endif


304: /*E
305:     TSGLAcceptType - String with the name of TSGLAccept scheme or the function
306:        with an optional dynamic library name, for example
307:        http://www.mcs.anl.gov/petsc/lib.a:mytsglaccept()

309:    Level: beginner

311: .seealso: TSGLSetAcceptType(), TS
312: E*/
313: #define TSGLAcceptType  char*
314: #define TSGLACCEPT_ALWAYS "always"

316: typedef PetscErrorCode (*TSGLAcceptFunction)(TS,PetscReal,PetscReal,const PetscReal[],PetscBool *);

319: /*MC
320:    TSGLAcceptRegisterDynamic - adds a TSGL acceptance scheme

322:    Synopsis:
323:    PetscErrorCode TSGLAcceptRegisterDynamic(const char *name_scheme,const char *path,const char *name_create,PetscErrorCode (*routine_create)(TS))

325:    Not Collective

327:    Input Parameters:
328: +  name_scheme - name of user-defined acceptance scheme
329: .  path - path (either absolute or relative) the library containing this scheme
330: .  name_create - name of routine to create method context
331: -  routine_create - routine to create method context

333:    Notes:
334:    TSGLAcceptRegisterDynamic() may be called multiple times to add several user-defined families.

336:    If dynamic libraries are used, then the fourth input argument (routine_create)
337:    is ignored.

339:    Sample usage:
340: .vb
341:    TSGLAcceptRegisterDynamic("my_scheme",/home/username/my_lib/lib/libO/solaris/mylib.a,
342:                              "MySchemeCreate",MySchemeCreate);
343: .ve

345:    Then, your scheme can be chosen with the procedural interface via
346: $     TSGLSetAcceptType(ts,"my_scheme")
347:    or at runtime via the option
348: $     -ts_gl_accept_type my_scheme

350:    Level: advanced

352:    Notes: Environmental variables such as ${PETSC_ARCH}, ${PETSC_DIR}, ${PETSC_LIB_DIR},
353:           and others of the form ${any_environmental_variable} occuring in pathname will be 
354:           replaced with appropriate values.

356: .keywords: TSGL, TSGLAcceptType, register

358: .seealso: TSGLRegisterAll()
359: M*/
360: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
361: #  define TSGLAcceptRegisterDynamic(a,b,c,d) TSGLAcceptRegister(a,b,c,0)
362: #else
363: #  define TSGLAcceptRegisterDynamic(a,b,c,d) TSGLAcceptRegister(a,b,c,d)
364: #endif

366: /*E
367:   TSGLType - family of time integration method within the General Linear class

369:   Level: beginner

371: .seealso: TSGLSetType(), TSGLRegister()
372: E*/
373: #define TSGLType char*
374: #define TSGL_IRKS   "irks"

376: /*MC
377:    TSGLRegisterDynamic - adds a TSGL implementation

379:    Synopsis:
380:    PetscErrorCode TSGLRegisterDynamic(const char *name_scheme,const char *path,const char *name_create,PetscErrorCode (*routine_create)(TS))

382:    Not Collective

384:    Input Parameters:
385: +  name_scheme - name of user-defined general linear scheme
386: .  path - path (either absolute or relative) the library containing this scheme
387: .  name_create - name of routine to create method context
388: -  routine_create - routine to create method context

390:    Notes:
391:    TSGLRegisterDynamic() may be called multiple times to add several user-defined families.

393:    If dynamic libraries are used, then the fourth input argument (routine_create)
394:    is ignored.

396:    Sample usage:
397: .vb
398:    TSGLRegisterDynamic("my_scheme",/home/username/my_lib/lib/libO/solaris/mylib.a,
399:                        "MySchemeCreate",MySchemeCreate);
400: .ve

402:    Then, your scheme can be chosen with the procedural interface via
403: $     TSGLSetType(ts,"my_scheme")
404:    or at runtime via the option
405: $     -ts_gl_type my_scheme

407:    Level: advanced

409:    Notes: Environmental variables such as ${PETSC_ARCH}, ${PETSC_DIR}, ${PETSC_LIB_DIR},
410:           and others of the form ${any_environmental_variable} occuring in pathname will be 
411:           replaced with appropriate values.

413: .keywords: TSGL, register

415: .seealso: TSGLRegisterAll()
416: M*/
417: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
418: #  define TSGLRegisterDynamic(a,b,c,d)       TSGLRegister(a,b,c,0)
419: #else
420: #  define TSGLRegisterDynamic(a,b,c,d)       TSGLRegister(a,b,c,d)
421: #endif


432: #define TSARKIMEXType char*
433: #define TSARKIMEX2D "2d"
434: #define TSARKIMEX2E "2e"
435: #define TSARKIMEX3  "3"
436: #define TSARKIMEX4  "4"
437: #define TSARKIMEX5  "5"

447: /*
448:        PETSc interface to Sundials
449: */
450: #ifdef PETSC_HAVE_SUNDIALS
451: typedef enum { SUNDIALS_ADAMS=1,SUNDIALS_BDF=2} TSSundialsLmmType;
453: typedef enum { SUNDIALS_MODIFIED_GS = 1,SUNDIALS_CLASSICAL_GS = 2 } TSSundialsGramSchmidtType;
467: #endif






489: #endif