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