Actual source code: theta.c
1: /*
2: Code for timestepping with implicit Theta method
3: */
4: #include <private/tsimpl.h> /*I "petscts.h" I*/
6: typedef struct {
7: Vec X,Xdot; /* Storage for one stage */
8: Vec affine; /* Affine vector needed for residual at beginning of step */
9: PetscBool extrapolate;
10: PetscBool endpoint;
11: PetscReal Theta;
12: PetscReal shift;
13: PetscReal stage_time;
14: } TS_Theta;
18: static PetscErrorCode TSStep_Theta(TS ts)
19: {
20: TS_Theta *th = (TS_Theta*)ts->data;
21: PetscInt its,lits;
22: PetscReal next_time_step;
26: next_time_step = ts->time_step;
27: th->stage_time = ts->ptime + (th->endpoint ? 1. : th->Theta)*ts->time_step;
28: th->shift = 1./(th->Theta*ts->time_step);
30: if (th->endpoint) { /* This formulation assumes linear time-independent mass matrix */
31: VecZeroEntries(th->Xdot);
32: if (!th->affine) {VecDuplicate(ts->vec_sol,&th->affine);}
33: TSComputeIFunction(ts,ts->ptime,ts->vec_sol,th->Xdot,th->affine,PETSC_FALSE);
34: VecScale(th->affine,(th->Theta-1.)/th->Theta);
35: }
36: if (th->extrapolate) {
37: VecWAXPY(th->X,1./th->shift,th->Xdot,ts->vec_sol);
38: } else {
39: VecCopy(ts->vec_sol,th->X);
40: }
41: SNESSolve(ts->snes,th->affine,th->X);
42: SNESGetIterationNumber(ts->snes,&its);
43: SNESGetLinearSolveIterations(ts->snes,&lits);
44: ts->nonlinear_its += its; ts->linear_its += lits;
46: if (th->endpoint) {
47: VecCopy(th->X,ts->vec_sol);
48: } else {
49: VecAXPBYPCZ(th->Xdot,-th->shift,th->shift,0,ts->vec_sol,th->X);
50: VecAXPY(ts->vec_sol,ts->time_step,th->Xdot);
51: }
52: ts->ptime += ts->time_step;
53: ts->time_step = next_time_step;
54: ts->steps++;
55: return(0);
56: }
60: static PetscErrorCode TSInterpolate_Theta(TS ts,PetscReal t,Vec X)
61: {
62: TS_Theta *th = (TS_Theta*)ts->data;
63: PetscReal alpha = t - ts->ptime;
67: VecCopy(ts->vec_sol,th->X);
68: if (th->endpoint) alpha *= th->Theta;
69: VecWAXPY(X,alpha,th->Xdot,th->X);
70: return(0);
71: }
73: /*------------------------------------------------------------*/
76: static PetscErrorCode TSReset_Theta(TS ts)
77: {
78: TS_Theta *th = (TS_Theta*)ts->data;
79: PetscErrorCode ierr;
82: VecDestroy(&th->X);
83: VecDestroy(&th->Xdot);
84: VecDestroy(&th->affine);
85: return(0);
86: }
90: static PetscErrorCode TSDestroy_Theta(TS ts)
91: {
92: PetscErrorCode ierr;
95: TSReset_Theta(ts);
96: PetscFree(ts->data);
97: PetscObjectComposeFunctionDynamic((PetscObject)ts,"TSThetaGetTheta_C","",PETSC_NULL);
98: PetscObjectComposeFunctionDynamic((PetscObject)ts,"TSThetaSetTheta_C","",PETSC_NULL);
99: PetscObjectComposeFunctionDynamic((PetscObject)ts,"TSThetaGetEndpoint_C","",PETSC_NULL);
100: PetscObjectComposeFunctionDynamic((PetscObject)ts,"TSThetaSetEndpoint_C","",PETSC_NULL);
101: return(0);
102: }
104: /*
105: This defines the nonlinear equation that is to be solved with SNES
106: G(U) = F[t0+Theta*dt, U, (U-U0)*shift] = 0
107: */
110: static PetscErrorCode SNESTSFormFunction_Theta(SNES snes,Vec x,Vec y,TS ts)
111: {
112: TS_Theta *th = (TS_Theta*)ts->data;
116: /* When using the endpoint variant, this is actually 1/Theta * Xdot */
117: VecAXPBYPCZ(th->Xdot,-th->shift,th->shift,0,ts->vec_sol,x);
118: TSComputeIFunction(ts,th->stage_time,x,th->Xdot,y,PETSC_FALSE);
119: return(0);
120: }
124: static PetscErrorCode SNESTSFormJacobian_Theta(SNES snes,Vec x,Mat *A,Mat *B,MatStructure *str,TS ts)
125: {
126: TS_Theta *th = (TS_Theta*)ts->data;
130: /* th->Xdot has already been computed in SNESTSFormFunction_Theta (SNES guarantees this) */
131: TSComputeIJacobian(ts,th->stage_time,x,th->Xdot,th->shift,A,B,str,PETSC_FALSE);
132: return(0);
133: }
138: static PetscErrorCode TSSetUp_Theta(TS ts)
139: {
140: TS_Theta *th = (TS_Theta*)ts->data;
144: VecDuplicate(ts->vec_sol,&th->X);
145: VecDuplicate(ts->vec_sol,&th->Xdot);
146: return(0);
147: }
148: /*------------------------------------------------------------*/
152: static PetscErrorCode TSSetFromOptions_Theta(TS ts)
153: {
154: TS_Theta *th = (TS_Theta*)ts->data;
158: PetscOptionsHead("Theta ODE solver options");
159: {
160: PetscOptionsReal("-ts_theta_theta","Location of stage (0<Theta<=1)","TSThetaSetTheta",th->Theta,&th->Theta,PETSC_NULL);
161: PetscOptionsBool("-ts_theta_extrapolate","Extrapolate stage solution from previous solution (sometimes unstable)","TSThetaSetExtrapolate",th->extrapolate,&th->extrapolate,PETSC_NULL);
162: PetscOptionsBool("-ts_theta_endpoint","Use the endpoint instead of midpoint form of the Theta method","TSThetaSetEndpoint",th->endpoint,&th->endpoint,PETSC_NULL);
163: SNESSetFromOptions(ts->snes);
164: }
165: PetscOptionsTail();
166: return(0);
167: }
171: static PetscErrorCode TSView_Theta(TS ts,PetscViewer viewer)
172: {
173: TS_Theta *th = (TS_Theta*)ts->data;
174: PetscBool iascii;
175: PetscErrorCode ierr;
178: PetscTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
179: if (iascii) {
180: PetscViewerASCIIPrintf(viewer," Theta=%G\n",th->Theta);
181: PetscViewerASCIIPrintf(viewer," Extrapolation=%s\n",th->extrapolate?"yes":"no");
182: }
183: SNESView(ts->snes,viewer);
184: return(0);
185: }
190: PetscErrorCode TSThetaGetTheta_Theta(TS ts,PetscReal *theta)
191: {
192: TS_Theta *th = (TS_Theta*)ts->data;
195: *theta = th->Theta;
196: return(0);
197: }
201: PetscErrorCode TSThetaSetTheta_Theta(TS ts,PetscReal theta)
202: {
203: TS_Theta *th = (TS_Theta*)ts->data;
206: if (theta <= 0 || 1 < theta) SETERRQ1(((PetscObject)ts)->comm,PETSC_ERR_ARG_OUTOFRANGE,"Theta %G not in range (0,1]",theta);
207: th->Theta = theta;
208: return(0);
209: }
213: PetscErrorCode TSThetaGetEndpoint_Theta(TS ts,PetscBool *endpoint)
214: {
215: TS_Theta *th = (TS_Theta*)ts->data;
218: *endpoint = th->endpoint;
219: return(0);
220: }
224: PetscErrorCode TSThetaSetEndpoint_Theta(TS ts,PetscBool flg)
225: {
226: TS_Theta *th = (TS_Theta*)ts->data;
229: th->endpoint = flg;
230: return(0);
231: }
234: /* ------------------------------------------------------------ */
235: /*MC
236: TSTHETA - DAE solver using the implicit Theta method
238: Level: beginner
240: Notes:
241: This method can be applied to DAE.
243: This method is cast as a 1-stage implicit Runge-Kutta method.
245: .vb
246: Theta | Theta
247: -------------
248: | 1
249: .ve
251: For the default Theta=0.5, this is also known as the implicit midpoint rule.
253: When the endpoint variant is chosen, the method becomes a 2-stage method with first stage explicit:
255: .vb
256: 0 | 0 0
257: 1 | 1-Theta Theta
258: -------------------
259: | 1-Theta Theta
260: .ve
262: For the default Theta=0.5, this is the trapezoid rule (also known as Crank-Nicolson, see TSCN).
264: To apply a diagonally implicit RK method to DAE, the stage formula
266: $ Y_i = X + h sum_j a_ij Y'_j
268: is interpreted as a formula for Y'_i in terms of Y_i and known stuff (Y'_j, j<i)
270: .seealso: TSCreate(), TS, TSSetType(), TSCN, TSBEULER, TSThetaSetTheta(), TSThetaSetEndpoint()
272: M*/
276: PetscErrorCode TSCreate_Theta(TS ts)
277: {
278: TS_Theta *th;
282: ts->ops->reset = TSReset_Theta;
283: ts->ops->destroy = TSDestroy_Theta;
284: ts->ops->view = TSView_Theta;
285: ts->ops->setup = TSSetUp_Theta;
286: ts->ops->step = TSStep_Theta;
287: ts->ops->interpolate = TSInterpolate_Theta;
288: ts->ops->setfromoptions = TSSetFromOptions_Theta;
289: ts->ops->snesfunction = SNESTSFormFunction_Theta;
290: ts->ops->snesjacobian = SNESTSFormJacobian_Theta;
292: PetscNewLog(ts,TS_Theta,&th);
293: ts->data = (void*)th;
295: th->extrapolate = PETSC_FALSE;
296: th->Theta = 0.5;
298: PetscObjectComposeFunctionDynamic((PetscObject)ts,"TSThetaGetTheta_C","TSThetaGetTheta_Theta",TSThetaGetTheta_Theta);
299: PetscObjectComposeFunctionDynamic((PetscObject)ts,"TSThetaSetTheta_C","TSThetaSetTheta_Theta",TSThetaSetTheta_Theta);
300: PetscObjectComposeFunctionDynamic((PetscObject)ts,"TSThetaGetEndpoint_C","TSThetaGetEndpoint_Theta",TSThetaGetEndpoint_Theta);
301: PetscObjectComposeFunctionDynamic((PetscObject)ts,"TSThetaSetEndpoint_C","TSThetaSetEndpoint_Theta",TSThetaSetEndpoint_Theta);
302: return(0);
303: }
308: /*@
309: TSThetaGetTheta - Get the abscissa of the stage in (0,1].
311: Not Collective
313: Input Parameter:
314: . ts - timestepping context
316: Output Parameter:
317: . theta - stage abscissa
319: Note:
320: Use of this function is normally only required to hack TSTHETA to use a modified integration scheme.
322: Level: Advanced
324: .seealso: TSThetaSetTheta()
325: @*/
326: PetscErrorCode TSThetaGetTheta(TS ts,PetscReal *theta)
327: {
333: PetscUseMethod(ts,"TSThetaGetTheta_C",(TS,PetscReal*),(ts,theta));
334: return(0);
335: }
339: /*@
340: TSThetaSetTheta - Set the abscissa of the stage in (0,1].
342: Not Collective
344: Input Parameter:
345: + ts - timestepping context
346: - theta - stage abscissa
348: Options Database:
349: . -ts_theta_theta <theta>
351: Level: Intermediate
353: .seealso: TSThetaGetTheta()
354: @*/
355: PetscErrorCode TSThetaSetTheta(TS ts,PetscReal theta)
356: {
361: PetscTryMethod(ts,"TSThetaSetTheta_C",(TS,PetscReal),(ts,theta));
362: return(0);
363: }
367: /*@
368: TSThetaGetEndpoint - Gets whether to use the endpoint variant of the method (e.g. trapezoid/Crank-Nicolson instead of midpoint rule).
370: Not Collective
372: Input Parameter:
373: . ts - timestepping context
375: Output Parameter:
376: . endpoint - PETSC_TRUE when using the endpoint variant
378: Level: Advanced
380: .seealso: TSThetaSetEndpoint(), TSTHETA, TSCN
381: @*/
382: PetscErrorCode TSThetaGetEndpoint(TS ts,PetscBool *endpoint)
383: {
389: PetscTryMethod(ts,"TSThetaGetEndpoint_C",(TS,PetscBool*),(ts,endpoint));
390: return(0);
391: }
395: /*@
396: TSThetaSetEndpoint - Sets whether to use the endpoint variant of the method (e.g. trapezoid/Crank-Nicolson instead of midpoint rule).
398: Not Collective
400: Input Parameter:
401: + ts - timestepping context
402: - flg - PETSC_TRUE to use the endpoint variant
404: Options Database:
405: . -ts_theta_endpoint <flg>
407: Level: Intermediate
409: .seealso: TSTHETA, TSCN
410: @*/
411: PetscErrorCode TSThetaSetEndpoint(TS ts,PetscBool flg)
412: {
417: PetscTryMethod(ts,"TSThetaSetEndpoint_C",(TS,PetscBool),(ts,flg));
418: return(0);
419: }
421: /*
422: * TSBEULER and TSCN are straightforward specializations of TSTHETA.
423: * The creation functions for these specializations are below.
424: */
428: static PetscErrorCode TSView_BEuler(TS ts,PetscViewer viewer)
429: {
433: SNESView(ts->snes,viewer);
434: return(0);
435: }
437: /*MC
438: TSBEULER - ODE solver using the implicit backward Euler method
440: Level: beginner
442: .seealso: TSCreate(), TS, TSSetType(), TSEULER, TSCN, TSTHETA
444: M*/
448: PetscErrorCode TSCreate_BEuler(TS ts)
449: {
453: TSCreate_Theta(ts);
454: TSThetaSetTheta(ts,1.0);
455: ts->ops->view = TSView_BEuler;
456: return(0);
457: }
462: static PetscErrorCode TSView_CN(TS ts,PetscViewer viewer)
463: {
467: SNESView(ts->snes,viewer);
468: return(0);
469: }
471: /*MC
472: TSCN - ODE solver using the implicit Crank-Nicolson method.
474: Level: beginner
476: Notes:
477: TSCN is equivalent to TSTHETA with Theta=0.5 and the "endpoint" option set. I.e.
479: $ -ts_type theta -ts_theta_theta 0.5 -ts_theta_endpoint
481: .seealso: TSCreate(), TS, TSSetType(), TSBEULER, TSTHETA
483: M*/
487: PetscErrorCode TSCreate_CN(TS ts)
488: {
492: TSCreate_Theta(ts);
493: TSThetaSetTheta(ts,0.5);
494: TSThetaSetEndpoint(ts,PETSC_TRUE);
495: ts->ops->view = TSView_CN;
496: return(0);
497: }