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: }