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 TSCRANK_NICHOLSON "crank-nicholson"
 35: #define TSSUNDIALS        "sundials"
 36: #define TSRUNGE_KUTTA     "runge-kutta"
 37: #define TSPYTHON          "python"
 38: #define TSTHETA           "theta"
 39: #define TSGL              "gl"
 40: #define TSSSP             "ssp"

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

 45:    Level: beginner

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

 51: /* Logging support */

 54: EXTERN PetscErrorCode   TSInitializePackage(const char[]);

 56: EXTERN PetscErrorCode   TSCreate(MPI_Comm,TS*);
 57: EXTERN PetscErrorCode   TSDestroy(TS);

 59: EXTERN PetscErrorCode   TSSetProblemType(TS,TSProblemType);
 60: EXTERN PetscErrorCode   TSGetProblemType(TS,TSProblemType*);
 61: EXTERN PetscErrorCode   TSMonitorSet(TS,PetscErrorCode(*)(TS,PetscInt,PetscReal,Vec,void*),void *,PetscErrorCode (*)(void*));
 62: EXTERN PetscErrorCode   TSMonitorCancel(TS);

 64: EXTERN PetscErrorCode   TSSetOptionsPrefix(TS,const char[]);
 65: EXTERN PetscErrorCode   TSAppendOptionsPrefix(TS,const char[]);
 66: EXTERN PetscErrorCode   TSGetOptionsPrefix(TS,const char *[]);
 67: EXTERN PetscErrorCode   TSSetFromOptions(TS);
 68: EXTERN PetscErrorCode   TSSetUp(TS);

 70: EXTERN PetscErrorCode   TSSetSolution(TS,Vec);
 71: EXTERN PetscErrorCode   TSGetSolution(TS,Vec*);

 73: EXTERN PetscErrorCode   TSSetDuration(TS,PetscInt,PetscReal);
 74: EXTERN PetscErrorCode   TSGetDuration(TS,PetscInt*,PetscReal*);

 76: EXTERN PetscErrorCode   TSMonitorDefault(TS,PetscInt,PetscReal,Vec,void*);
 77: EXTERN PetscErrorCode   TSMonitorSolution(TS,PetscInt,PetscReal,Vec,void*);
 78: EXTERN PetscErrorCode   TSStep(TS,PetscInt *,PetscReal*);
 79: EXTERN PetscErrorCode   TSSolve(TS,Vec);


 82: EXTERN PetscErrorCode   TSSetInitialTimeStep(TS,PetscReal,PetscReal);
 83: EXTERN PetscErrorCode   TSGetTimeStep(TS,PetscReal*);
 84: EXTERN PetscErrorCode   TSGetTime(TS,PetscReal*);
 85: EXTERN PetscErrorCode   TSSetTime(TS,PetscReal);
 86: EXTERN PetscErrorCode   TSGetTimeStepNumber(TS,PetscInt*);
 87: EXTERN PetscErrorCode   TSSetTimeStep(TS,PetscReal);

 89: EXTERN PetscErrorCode   TSSetRHSFunction(TS,PetscErrorCode (*)(TS,PetscReal,Vec,Vec,void*),void*);
 90: EXTERN PetscErrorCode   TSSetMatrices(TS,Mat,PetscErrorCode (*)(TS,PetscReal,Mat*,Mat*,MatStructure*,void*),Mat,PetscErrorCode (*)(TS,PetscReal,Mat*,Mat*,MatStructure*,void*),MatStructure,void*);
 91: EXTERN PetscErrorCode   TSGetMatrices(TS,Mat*,Mat*,void**);
 92: EXTERN PetscErrorCode   TSSetRHSJacobian(TS,Mat,Mat,PetscErrorCode (*)(TS,PetscReal,Vec,Mat*,Mat*,MatStructure*,void*),void*);
 93: EXTERN PetscErrorCode   TSGetRHSJacobian(TS,Mat*,Mat*,void**);

 95: typedef PetscErrorCode (*TSIFunction)(TS,PetscReal,Vec,Vec,Vec,void*);
 96: typedef PetscErrorCode (*TSIJacobian)(TS,PetscReal,Vec,Vec,PetscReal,Mat*,Mat*,MatStructure*,void*);
 97: EXTERN PetscErrorCode   TSSetIFunction(TS,TSIFunction,void*);
 98: EXTERN PetscErrorCode   TSSetIJacobian(TS,Mat,Mat,TSIJacobian,void*);
 99: EXTERN PetscErrorCode   TSGetIJacobian(TS,Mat*,Mat*,TSIJacobian*,void**);

101: EXTERN PetscErrorCode   TSDefaultComputeJacobianColor(TS,PetscReal,Vec,Mat*,Mat*,MatStructure*,void*);
102: EXTERN PetscErrorCode   TSDefaultComputeJacobian(TS,PetscReal,Vec,Mat*,Mat*,MatStructure*,void*);

104: EXTERN PetscErrorCode   TSSetPreStep(TS, PetscErrorCode (*)(TS));
105: EXTERN PetscErrorCode   TSSetPostStep(TS, PetscErrorCode (*)(TS));
106: EXTERN PetscErrorCode   TSDefaultPreStep(TS);
107: EXTERN PetscErrorCode   TSDefaultPostStep(TS);
108: EXTERN PetscErrorCode   TSPreStep(TS);
109: EXTERN PetscErrorCode   TSPostStep(TS);

111: EXTERN PetscErrorCode   TSPseudoSetTimeStep(TS,PetscErrorCode(*)(TS,PetscReal*,void*),void*);
112: EXTERN PetscErrorCode   TSPseudoDefaultTimeStep(TS,PetscReal*,void*);
113: EXTERN PetscErrorCode   TSPseudoComputeTimeStep(TS,PetscReal *);

115: EXTERN PetscErrorCode   TSPseudoSetVerifyTimeStep(TS,PetscErrorCode(*)(TS,Vec,void*,PetscReal*,PetscTruth*),void*);
116: EXTERN PetscErrorCode   TSPseudoDefaultVerifyTimeStep(TS,Vec,void*,PetscReal*,PetscTruth*);
117: EXTERN PetscErrorCode   TSPseudoVerifyTimeStep(TS,Vec,PetscReal*,PetscTruth*);
118: EXTERN PetscErrorCode   TSPseudoSetTimeStepIncrement(TS,PetscReal);
119: EXTERN PetscErrorCode   TSPseudoIncrementDtFromInitialDt(TS);

121: EXTERN PetscErrorCode   TSPythonSetType(TS,const char[]);

123: EXTERN PetscErrorCode   TSComputeRHSFunction(TS,PetscReal,Vec,Vec);
124: EXTERN PetscErrorCode   TSComputeRHSJacobian(TS,PetscReal,Vec,Mat*,Mat*,MatStructure*);
125: EXTERN PetscErrorCode   TSComputeIFunction(TS,PetscReal,Vec,Vec,Vec);
126: EXTERN PetscErrorCode   TSComputeIJacobian(TS,PetscReal,Vec,Vec,PetscReal,Mat*,Mat*,MatStructure*);

128: /* Dynamic creation and loading functions */
131: EXTERN PetscErrorCode   TSGetType(TS,const TSType*);
132: EXTERN PetscErrorCode   TSSetType(TS,const TSType);
133: EXTERN PetscErrorCode   TSRegister(const char[], const char[], const char[], PetscErrorCode (*)(TS));
134: EXTERN PetscErrorCode   TSRegisterAll(const char[]);
135: EXTERN PetscErrorCode   TSRegisterDestroy(void);

137: /*MC
138:   TSRegisterDynamic - Adds a creation method to the TS package.

140:   Synopsis:
141:   PetscErrorCode TSRegisterDynamic(const char *name, const char *path, const char *func_name, PetscErrorCode (*create_func)(TS))

143:   Not Collective

145:   Input Parameters:
146: + name        - The name of a new user-defined creation routine
147: . path        - The path (either absolute or relative) of the library containing this routine
148: . func_name   - The name of the creation routine
149: - create_func - The creation routine itself

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

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

156:   Sample usage:
157: .vb
158:   TSRegisterDynamic("my_ts", "/home/username/my_lib/lib/libO/solaris/libmy.a", "MyTSCreate", MyTSCreate);
159: .ve

161:   Then, your ts type can be chosen with the procedural interface via
162: .vb
163:     TS ts;
164:     TSCreate(MPI_Comm, &ts);
165:     TSSetType(ts, "my_ts")
166: .ve
167:   or at runtime via the option
168: .vb
169:     -ts_type my_ts
170: .ve

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

175:   Level: advanced

177: .keywords: TS, register
178: .seealso: TSRegisterAll(), TSRegisterDestroy()
179: M*/
180: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
181: #define TSRegisterDynamic(a,b,c,d) TSRegister(a,b,c,0)
182: #else
183: #define TSRegisterDynamic(a,b,c,d) TSRegister(a,b,c,d)
184: #endif

186: EXTERN PetscErrorCode   TSGetSNES(TS,SNES*);
187: EXTERN PetscErrorCode   TSGetKSP(TS,KSP*);

189: EXTERN PetscErrorCode   TSView(TS,PetscViewer);
190: EXTERN PetscErrorCode   TSViewFromOptions(TS,const char[]);

192: EXTERN PetscErrorCode   TSSetApplicationContext(TS,void *);
193: EXTERN PetscErrorCode   TSGetApplicationContext(TS,void **);

195: EXTERN PetscErrorCode   TSMonitorLGCreate(const char[],const char[],int,int,int,int,PetscDrawLG *);
196: EXTERN PetscErrorCode   TSMonitorLG(TS,PetscInt,PetscReal,Vec,void *);
197: EXTERN PetscErrorCode   TSMonitorLGDestroy(PetscDrawLG);

199: /*S
200:    TSGLAdapt - Abstract object that manages time-step adaptivity

202:    Level: beginner

204: .seealso: TSGL, TSGLAdaptCreate(), TSGLAdaptType
205: S*/
206: typedef struct _p_TSGLAdapt *TSGLAdapt;

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

213:    Level: beginner

215: .seealso: TSGLAdaptSetType(), TS
216: E*/
217: #define TSGLAdaptType  char*
218: #define TSGLADAPT_NONE "none"
219: #define TSGLADAPT_SIZE "size"
220: #define TSGLADAPT_BOTH "both"

222: /*MC
223:    TSGLAdaptRegisterDynamic - adds a TSGLAdapt implementation

225:    Synopsis:
226:    PetscErrorCode TSGLAdaptRegisterDynamic(const char *name_scheme,const char *path,const char *name_create,PetscErrorCode (*routine_create)(TS))

228:    Not Collective

230:    Input Parameters:
231: +  name_scheme - name of user-defined adaptivity scheme
232: .  path - path (either absolute or relative) the library containing this scheme
233: .  name_create - name of routine to create method context
234: -  routine_create - routine to create method context

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

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

242:    Sample usage:
243: .vb
244:    TSGLAdaptRegisterDynamic("my_scheme",/home/username/my_lib/lib/libO/solaris/mylib.a,
245:                             "MySchemeCreate",MySchemeCreate);
246: .ve

248:    Then, your scheme can be chosen with the procedural interface via
249: $     TSGLAdaptSetType(ts,"my_scheme")
250:    or at runtime via the option
251: $     -ts_adapt_type my_scheme

253:    Level: advanced

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

259: .keywords: TSGLAdapt, register

261: .seealso: TSGLAdaptRegisterAll()
262: M*/
263: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
264: #  define TSGLAdaptRegisterDynamic(a,b,c,d)  TSGLAdaptRegister(a,b,c,0)
265: #else
266: #  define TSGLAdaptRegisterDynamic(a,b,c,d)  TSGLAdaptRegister(a,b,c,d)
267: #endif

269: EXTERN PetscErrorCode  TSGLAdaptRegister(const char[],const char[],const char[],PetscErrorCode (*)(TSGLAdapt));
270: EXTERN PetscErrorCode  TSGLAdaptRegisterAll(const char[]);
271: EXTERN PetscErrorCode  TSGLAdaptRegisterDestroy(void);
272: EXTERN PetscErrorCode  TSGLAdaptInitializePackage(const char[]);
273: EXTERN PetscErrorCode  TSGLAdaptFinalizePackage(void);
274: EXTERN PetscErrorCode  TSGLAdaptCreate(MPI_Comm,TSGLAdapt*);
275: EXTERN PetscErrorCode  TSGLAdaptSetType(TSGLAdapt,const TSGLAdaptType);
276: EXTERN PetscErrorCode  TSGLAdaptSetOptionsPrefix(TSGLAdapt,const char[]);
277: EXTERN PetscErrorCode  TSGLAdaptChoose(TSGLAdapt,PetscInt,const PetscInt[],const PetscReal[],const PetscReal[],PetscInt,PetscReal,PetscReal,PetscInt*,PetscReal*,PetscTruth*);
278: EXTERN PetscErrorCode  TSGLAdaptView(TSGLAdapt,PetscViewer);
279: EXTERN PetscErrorCode  TSGLAdaptSetFromOptions(TSGLAdapt);
280: EXTERN PetscErrorCode  TSGLAdaptDestroy(TSGLAdapt);

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

287:    Level: beginner

289: .seealso: TSGLSetAcceptType(), TS
290: E*/
291: #define TSGLAcceptType  char*
292: #define TSGLACCEPT_ALWAYS "always"

294: typedef PetscErrorCode (*TSGLAcceptFunction)(TS,PetscReal,PetscReal,const PetscReal[],PetscTruth*);
295: EXTERN PetscErrorCode  TSGLAcceptRegister(const char[],const char[],const char[],TSGLAcceptFunction);

297: /*MC
298:    TSGLAcceptRegisterDynamic - adds a TSGL acceptance scheme

300:    Synopsis:
301:    PetscErrorCode TSGLAcceptRegisterDynamic(const char *name_scheme,const char *path,const char *name_create,PetscErrorCode (*routine_create)(TS))

303:    Not Collective

305:    Input Parameters:
306: +  name_scheme - name of user-defined acceptance scheme
307: .  path - path (either absolute or relative) the library containing this scheme
308: .  name_create - name of routine to create method context
309: -  routine_create - routine to create method context

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

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

317:    Sample usage:
318: .vb
319:    TSGLAcceptRegisterDynamic("my_scheme",/home/username/my_lib/lib/libO/solaris/mylib.a,
320:                              "MySchemeCreate",MySchemeCreate);
321: .ve

323:    Then, your scheme can be chosen with the procedural interface via
324: $     TSGLSetAcceptType(ts,"my_scheme")
325:    or at runtime via the option
326: $     -ts_gl_accept_type my_scheme

328:    Level: advanced

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

334: .keywords: TSGL, TSGLAcceptType, register

336: .seealso: TSGLRegisterAll()
337: M*/
338: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
339: #  define TSGLAcceptRegisterDynamic(a,b,c,d) TSGLAcceptRegister(a,b,c,0)
340: #else
341: #  define TSGLAcceptRegisterDynamic(a,b,c,d) TSGLAcceptRegister(a,b,c,d)
342: #endif

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

347:   Level: beginner

349: .seealso: TSGLSetType(), TSGLRegister()
350: E*/
351: #define TSGLType char*
352: #define TSGL_IRKS   "irks"

354: /*MC
355:    TSGLRegisterDynamic - adds a TSGL implementation

357:    Synopsis:
358:    PetscErrorCode TSGLRegisterDynamic(const char *name_scheme,const char *path,const char *name_create,PetscErrorCode (*routine_create)(TS))

360:    Not Collective

362:    Input Parameters:
363: +  name_scheme - name of user-defined general linear scheme
364: .  path - path (either absolute or relative) the library containing this scheme
365: .  name_create - name of routine to create method context
366: -  routine_create - routine to create method context

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

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

374:    Sample usage:
375: .vb
376:    TSGLRegisterDynamic("my_scheme",/home/username/my_lib/lib/libO/solaris/mylib.a,
377:                        "MySchemeCreate",MySchemeCreate);
378: .ve

380:    Then, your scheme can be chosen with the procedural interface via
381: $     TSGLSetType(ts,"my_scheme")
382:    or at runtime via the option
383: $     -ts_gl_type my_scheme

385:    Level: advanced

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

391: .keywords: TSGL, register

393: .seealso: TSGLRegisterAll()
394: M*/
395: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
396: #  define TSGLRegisterDynamic(a,b,c,d)       TSGLRegister(a,b,c,0)
397: #else
398: #  define TSGLRegisterDynamic(a,b,c,d)       TSGLRegister(a,b,c,d)
399: #endif

401: EXTERN PetscErrorCode   TSGLRegister(const char[],const char[],const char[],PetscErrorCode(*)(TS));
402: EXTERN PetscErrorCode  TSGLRegisterAll(const char[]);
403: EXTERN PetscErrorCode  TSGLRegisterDestroy(void);
404: EXTERN PetscErrorCode  TSGLInitializePackage(const char[]);
405: EXTERN PetscErrorCode  TSGLFinalizePackage(void);
406: EXTERN PetscErrorCode  TSGLSetType(TS,const TSGLType);
407: EXTERN PetscErrorCode  TSGLGetAdapt(TS,TSGLAdapt*);
408: EXTERN PetscErrorCode  TSGLSetAcceptType(TS,const TSGLAcceptType);

410: /*
411:        PETSc interface to Sundials
412: */
413: #ifdef PETSC_HAVE_SUNDIALS
414: typedef enum { SUNDIALS_ADAMS=1,SUNDIALS_BDF=2} TSSundialsLmmType;
416: typedef enum { SUNDIALS_MODIFIED_GS = 1,SUNDIALS_CLASSICAL_GS = 2 } TSSundialsGramSchmidtType;
418: EXTERN PetscErrorCode   TSSundialsSetType(TS,TSSundialsLmmType);
419: EXTERN PetscErrorCode   TSSundialsGetPC(TS,PC*);
420: EXTERN PetscErrorCode   TSSundialsSetTolerance(TS,PetscReal,PetscReal);
421: EXTERN PetscErrorCode   TSSundialsGetIterations(TS,PetscInt *,PetscInt *);
422: EXTERN PetscErrorCode   TSSundialsSetGramSchmidtType(TS,TSSundialsGramSchmidtType);
423: EXTERN PetscErrorCode   TSSundialsSetGMRESRestart(TS,PetscInt);
424: EXTERN PetscErrorCode   TSSundialsSetLinearTolerance(TS,PetscReal);
425: EXTERN PetscErrorCode   TSSundialsSetExactFinalTime(TS,PetscTruth);
426: EXTERN PetscErrorCode   TSSundialsMonitorInternalSteps(TS,PetscTruth);
427: EXTERN PetscErrorCode   TSSundialsGetParameters(TS,PetscInt *,long*[],double*[]);
428: #endif

430: EXTERN PetscErrorCode   TSRKSetTolerance(TS,PetscReal);

432: EXTERN PetscErrorCode  TSThetaSetTheta(TS,PetscReal);
433: EXTERN PetscErrorCode  TSThetaGetTheta(TS,PetscReal*);

436: #endif