Actual source code: tsimpl.h

petsc-3.7.0 2016-04-25
Report Typos and Errors
  1: #ifndef __TSIMPL_H

  4: #include <petscts.h>
  5: #include <petsc/private/petscimpl.h>

  7: /*
  8:     Timesteping context.
  9:       General DAE: F(t,U,U_t) = 0, required Jacobian is G'(U) where G(U) = F(t,U,U0+a*U)
 10:       General ODE: U_t = F(t,U) <-- the right-hand-side function
 11:       Linear  ODE: U_t = A(t) U <-- the right-hand-side matrix
 12:       Linear (no time) ODE: U_t = A U <-- the right-hand-side matrix
 13: */

 15: /*
 16:      Maximum number of monitors you can run with a single TS
 17: */
 18: #define MAXTSMONITORS 10

 20: PETSC_EXTERN PetscBool TSRegisterAllCalled;
 21: PETSC_EXTERN PetscErrorCode TSRegisterAll(void);
 22: PETSC_EXTERN PetscErrorCode TSAdaptRegisterAll(void);

 24: PETSC_EXTERN PetscErrorCode TSRKRegisterAll(void);
 25: PETSC_EXTERN PetscErrorCode TSARKIMEXRegisterAll(void);
 26: PETSC_EXTERN PetscErrorCode TSRosWRegisterAll(void);
 27: PETSC_EXTERN PetscErrorCode TSGLRegisterAll(void);
 28: PETSC_EXTERN PetscErrorCode TSGLAdaptRegisterAll(void);

 30: typedef struct _TSOps *TSOps;

 32: struct _TSOps {
 33:   PetscErrorCode (*snesfunction)(SNES,Vec,Vec,TS);
 34:   PetscErrorCode (*snesjacobian)(SNES,Vec,Mat,Mat,TS);
 35:   PetscErrorCode (*setup)(TS);
 36:   PetscErrorCode (*step)(TS);
 37:   PetscErrorCode (*solve)(TS);
 38:   PetscErrorCode (*interpolate)(TS,PetscReal,Vec);
 39:   PetscErrorCode (*evaluatewlte)(TS,NormType,PetscInt*,PetscReal*);
 40:   PetscErrorCode (*evaluatestep)(TS,PetscInt,Vec,PetscBool*);
 41:   PetscErrorCode (*setfromoptions)(PetscOptionItems*,TS);
 42:   PetscErrorCode (*destroy)(TS);
 43:   PetscErrorCode (*view)(TS,PetscViewer);
 44:   PetscErrorCode (*reset)(TS);
 45:   PetscErrorCode (*linearstability)(TS,PetscReal,PetscReal,PetscReal*,PetscReal*);
 46:   PetscErrorCode (*load)(TS,PetscViewer);
 47:   PetscErrorCode (*rollback)(TS);
 48:   PetscErrorCode (*getstages)(TS,PetscInt*,Vec**);
 49:   PetscErrorCode (*adjointstep)(TS);
 50:   PetscErrorCode (*adjointsetup)(TS);
 51:   PetscErrorCode (*adjointintegral)(TS);
 52:   PetscErrorCode (*forwardintegral)(TS);
 53: };

 55: /*
 56:    TSEvent - Abstract object to handle event monitoring
 57: */
 58: typedef struct _n_TSEvent *TSEvent;

 60: typedef struct _TSTrajectoryOps *TSTrajectoryOps;

 62: struct _TSTrajectoryOps {
 63:   PetscErrorCode (*view)(TSTrajectory,PetscViewer);
 64:   PetscErrorCode (*destroy)(TSTrajectory);
 65:   PetscErrorCode (*set)(TSTrajectory,TS,PetscInt,PetscReal,Vec);
 66:   PetscErrorCode (*get)(TSTrajectory,TS,PetscInt,PetscReal*);
 67:   PetscErrorCode (*setfromoptions)(PetscOptionItems*,TSTrajectory);
 68:   PetscErrorCode (*setup)(TSTrajectory,TS);
 69: };

 71: struct _p_TSTrajectory {
 72:   PETSCHEADER(struct _TSTrajectoryOps);
 73:   PetscInt setupcalled;             /* true if setup has been called */
 74:   PetscInt recomps;                 /* counter for recomputations in the adjoint run */
 75:   PetscInt diskreads,diskwrites;    /* counters for disk checkpoint reads and writes */
 76:   void *data;
 77: };

 79: struct _p_TS {
 80:   PETSCHEADER(struct _TSOps);
 81:   TSProblemType  problem_type;
 82:   TSEquationType equation_type;

 84:   DM             dm;
 85:   Vec            vec_sol; /* solution vector in first and second order equations */
 86:   Vec            vec_dot; /* time derivative vector in second order equations */
 87:   TSAdapt        adapt;
 88:   TSEvent        event;

 90:   /* ---------------- User (or PETSc) Provided stuff ---------------------*/
 91:   PetscErrorCode (*monitor[MAXTSMONITORS])(TS,PetscInt,PetscReal,Vec,void*);
 92:   PetscErrorCode (*monitordestroy[MAXTSMONITORS])(void**);
 93:   void *monitorcontext[MAXTSMONITORS];
 94:   PetscInt  numbermonitors;
 95:   PetscErrorCode (*adjointmonitor[MAXTSMONITORS])(TS,PetscInt,PetscReal,Vec,PetscInt,Vec*,Vec*,void*);
 96:   PetscErrorCode (*adjointmonitordestroy[MAXTSMONITORS])(void**);
 97:   void *adjointmonitorcontext[MAXTSMONITORS];
 98:   PetscInt  numberadjointmonitors;

100:   PetscErrorCode (*prestep)(TS);
101:   PetscErrorCode (*prestage)(TS,PetscReal);
102:   PetscErrorCode (*poststage)(TS,PetscReal,PetscInt,Vec*);
103:   PetscErrorCode (*poststep)(TS);
104:   PetscErrorCode (*functiondomainerror)(TS,PetscReal,Vec,PetscBool*);

106:   /* ---------------------- Sensitivity Analysis support -----------------*/
107:   TSTrajectory trajectory;          /* All solutions are kept here for the entire time integration process */
108:   Vec       *vecs_sensi;            /* one vector for each cost function */
109:   Vec       *vecs_sensip;
110:   PetscInt  numcost;                /* number of cost functions */
111:   Vec       vec_costintegral;
112:   PetscInt  adjointsetupcalled;
113:   PetscInt  adjoint_max_steps;
114:   PetscBool adjoint_solve;          /* immediately call TSAdjointSolve() after TSSolve() is complete */
115:   PetscBool costintegralfwd;        /* cost integral is evaluated in the forward run if true */
116:   Vec       vec_costintegrand;      /* workspace for Adjoint computations */
117:   Mat       Jacp;
118:   void      *rhsjacobianpctx;
119:   void      *costintegrandctx;
120:   Vec       *vecs_drdy;
121:   Vec       *vecs_drdp;

123:   PetscErrorCode (*rhsjacobianp)(TS,PetscReal,Vec,Mat,void*);
124:   PetscErrorCode (*costintegrand)(TS,PetscReal,Vec,Vec,void*);
125:   PetscErrorCode (*drdyfunction)(TS,PetscReal,Vec,Vec*,void*);
126:   PetscErrorCode (*drdpfunction)(TS,PetscReal,Vec,Vec*,void*);

128:   /* ---------------------- IMEX support ---------------------------------*/
129:   /* These extra slots are only used when the user provides both Implicit and RHS */
130:   Mat Arhs;     /* Right hand side matrix */
131:   Mat Brhs;     /* Right hand side preconditioning matrix */
132:   Vec Frhs;     /* Right hand side function value */

134:   /* This is a general caching scheme to avoid recomputing the Jacobian at a place that has been previously been evaluated.
135:    * The present use case is that TSComputeRHSFunctionLinear() evaluates the Jacobian once and we don't want it to be immeditely re-evaluated.
136:    */
137:   struct {
138:     PetscReal time;             /* The time at which the matrices were last evaluated */
139:     Vec X;                      /* Solution vector at which the Jacobian was last evaluated */
140:     PetscObjectState Xstate;    /* State of the solution vector */
141:     MatStructure mstructure;    /* The structure returned */
142:     /* Flag to unshift Jacobian before calling the IJacobian or RHSJacobian functions.  This is useful
143:      * if the user would like to reuse (part of) the Jacobian from the last evaluation. */
144:     PetscBool reuse;
145:     PetscReal scale,shift;
146:   } rhsjacobian;

148:   struct {
149:     PetscReal shift;            /* The derivative of the lhs wrt to Xdot */
150:   } ijacobian;

152:   /* --------------------Nonlinear Iteration------------------------------*/
153:   SNES     snes;
154:   PetscInt ksp_its;                /* total number of linear solver iterations */
155:   PetscInt snes_its;               /* total number of nonlinear solver iterations */
156:   PetscInt num_snes_failures;
157:   PetscInt max_snes_failures;

159:   /* --- Data that is unique to each particular solver --- */
160:   PetscInt setupcalled;             /* true if setup has been called */
161:   void     *data;                   /* implementationspecific data */
162:   void     *user;                   /* user context */

164:   /* ------------------  Parameters -------------------------------------- */
165:   PetscInt  max_steps;              /* max number of steps */
166:   PetscReal max_time;               /* max time allowed */

168:   /* --------------------------------------------------------------------- */

170:   PetscBool steprollback;           /* flag to indicate that the step was rolled back */
171:   PetscBool steprestart;            /* flag to indicate that the timestepper has to discard any history and restart */
172:   PetscInt  steps;                  /* steps taken so far in latest call to TSSolve() */
173:   PetscInt  total_steps;            /* steps taken in all calls to TSSolve() since the TS was created or since TSSetUp() was called */
174:   PetscReal ptime;                  /* time at the start of the current step (stage time is internal if it exists) */
175:   PetscReal time_step;              /* current time increment */
176:   PetscReal ptime_prev;             /* time at the start of the previous step */
177:   PetscReal ptime_prev_rollback;    /* time at the start of the 2nd previous step to recover from rollback */
178:   PetscReal solvetime;              /* time at the conclusion of TSSolve() */

180:   TSConvergedReason reason;
181:   PetscBool errorifstepfailed;
182:   PetscInt  reject,max_reject;
183:   TSExactFinalTimeOption exact_final_time;

185:   PetscReal atol,rtol;              /* Relative and absolute tolerance for local truncation error */
186:   Vec       vatol,vrtol;            /* Relative and absolute tolerance in vector form */
187:   PetscReal cfltime,cfltime_local;

189:   /* ------------------- Default work-area management ------------------ */
190:   PetscInt nwork;
191:   Vec      *work;
192: };

194: struct _TSAdaptOps {
195:   PetscErrorCode (*choose)(TSAdapt,TS,PetscReal,PetscInt*,PetscReal*,PetscBool*,PetscReal*);
196:   PetscErrorCode (*destroy)(TSAdapt);
197:   PetscErrorCode (*reset)(TSAdapt);
198:   PetscErrorCode (*view)(TSAdapt,PetscViewer);
199:   PetscErrorCode (*setfromoptions)(PetscOptionItems*,TSAdapt);
200:   PetscErrorCode (*load)(TSAdapt,PetscViewer);
201: };

203: struct _p_TSAdapt {
204:   PETSCHEADER(struct _TSAdaptOps);
205:   void *data;
206:   PetscErrorCode (*checkstage)(TSAdapt,TS,PetscReal,Vec,PetscBool*);
207:   struct {
208:     PetscInt   n;                /* number of candidate schemes, including the one currently in use */
209:     PetscBool  inuse_set;        /* the current scheme has been set */
210:     const char *name[16];        /* name of the scheme */
211:     PetscInt   order[16];        /* classical order of each scheme */
212:     PetscInt   stageorder[16];   /* stage order of each scheme */
213:     PetscReal  ccfl[16];         /* stability limit relative to explicit Euler */
214:     PetscReal  cost[16];         /* relative measure of the amount of work required for each scheme */
215:   } candidates;
216:   PetscReal   dt_min,dt_max;
217:   PetscReal   scale_solve_failed; /* Scale step by this factor if solver (linear or nonlinear) fails. */
218:   PetscViewer monitor;
219:   NormType    wnormtype;
220: };

222: typedef struct _p_DMTS *DMTS;
223: typedef struct _DMTSOps *DMTSOps;
224: struct _DMTSOps {
225:   TSRHSFunction rhsfunction;
226:   TSRHSJacobian rhsjacobian;

228:   TSIFunction ifunction;
229:   PetscErrorCode (*ifunctionview)(void*,PetscViewer);
230:   PetscErrorCode (*ifunctionload)(void**,PetscViewer);

232:   TSIJacobian ijacobian;
233:   PetscErrorCode (*ijacobianview)(void*,PetscViewer);
234:   PetscErrorCode (*ijacobianload)(void**,PetscViewer);

236:   TSI2Function i2function;
237:   TSI2Jacobian i2jacobian;

239:   TSSolutionFunction solution;
240:   TSForcingFunction  forcing;

242:   PetscErrorCode (*destroy)(DMTS);
243:   PetscErrorCode (*duplicate)(DMTS,DMTS);
244: };

246: struct _p_DMTS {
247:   PETSCHEADER(struct _DMTSOps);
248:   void *rhsfunctionctx;
249:   void *rhsjacobianctx;

251:   void *ifunctionctx;
252:   void *ijacobianctx;

254:   void *i2functionctx;
255:   void *i2jacobianctx;

257:   void *solutionctx;
258:   void *forcingctx;

260:   void *data;

262:   /* This is NOT reference counted. The DM on which this context was first created is cached here to implement one-way
263:    * copy-on-write. When DMGetDMTSWrite() sees a request using a different DM, it makes a copy. Thus, if a user
264:    * only interacts directly with one level, e.g., using TSSetIFunction(), then coarse levels of a multilevel item
265:    * integrator are built, then the user changes the routine with another call to TSSetIFunction(), it automatically
266:    * propagates to all the levels. If instead, they get out a specific level and set the function on that level,
267:    * subsequent changes to the original level will no longer propagate to that level.
268:    */
269:   DM originaldm;
270: };

272: PETSC_EXTERN PetscErrorCode DMGetDMTS(DM,DMTS*);
273: PETSC_EXTERN PetscErrorCode DMGetDMTSWrite(DM,DMTS*);
274: PETSC_EXTERN PetscErrorCode DMCopyDMTS(DM,DM);
275: PETSC_EXTERN PetscErrorCode DMTSView(DMTS,PetscViewer);
276: PETSC_EXTERN PetscErrorCode DMTSLoad(DMTS,PetscViewer);
277: PETSC_EXTERN PetscErrorCode DMTSCopy(DMTS,DMTS);

279: typedef enum {TSEVENT_NONE,TSEVENT_LOCATED_INTERVAL,TSEVENT_PROCESSING,TSEVENT_ZERO,TSEVENT_RESET_NEXTSTEP} TSEventStatus;

281: struct _n_TSEvent {
282:   PetscScalar    *fvalue;          /* value of event function at the end of the step*/
283:   PetscScalar    *fvalue_prev;     /* value of event function at start of the step (left end-point of event interval) */
284:   PetscReal       ptime_prev;      /* time at step start (left end-point of event interval) */
285:   PetscReal       ptime_end;       /* end time of step (when an event interval is detected, ptime_end is fixed to the time at step end during event processing) */
286:   PetscReal       ptime_right;     /* time on the right end-point of the event interval */
287:   PetscScalar    *fvalue_right;    /* value of event function at the right end-point of the event interval */
288:   PetscInt       *side;            /* Used for detecting repetition of end-point, -1 => left, +1 => right */
289:   PetscReal       timestep_prev;   /* previous time step */
290:   PetscReal       timestep_orig;   /* initial time step */
291:   PetscBool      *zerocrossing;    /* Flag to signal zero crossing detection */
292:   PetscErrorCode  (*eventhandler)(TS,PetscReal,Vec,PetscScalar*,void*); /* User event handler function */
293:   PetscErrorCode  (*postevent)(TS,PetscInt,PetscInt[],PetscReal,Vec,PetscBool,void*); /* User post event function */
294:   void           *ctx;              /* User context for event handler and post even functions */
295:   PetscInt       *direction;        /* Zero crossing direction: 1 -> Going positive, -1 -> Going negative, 0 -> Any */
296:   PetscBool      *terminate;        /* 1 -> Terminate time stepping, 0 -> continue */
297:   PetscInt        nevents;          /* Number of events to handle */
298:   PetscInt        nevents_zero;     /* Number of event zero detected */
299:   PetscInt       *events_zero;      /* List of events that have reached zero */
300:   PetscReal      *vtol;             /* Vector tolerances for event zero check */
301:   TSEventStatus   status;           /* Event status */
302:   PetscInt        iterctr;          /* Iteration counter */
303:   PetscViewer     monitor;
304:   /* Struct to record the events */
305:   struct {
306:     PetscInt  ctr;        /* recorder counter */
307:     PetscReal *time;      /* Event times */
308:     PetscInt  *stepnum;   /* Step numbers */
309:     PetscInt  *nevents;   /* Number of events occuring at the event times */
310:     PetscInt  **eventidx; /* Local indices of the events in the event list */
311:   } recorder;
312:   PetscInt  recsize; /* Size of recorder stack */
313: };

315: PETSC_EXTERN PetscErrorCode TSEventInitialize(TSEvent,TS,PetscReal,Vec);
316: PETSC_EXTERN PetscErrorCode TSEventDestroy(TSEvent*);
317: PETSC_EXTERN PetscErrorCode TSEventHandler(TS);
318: PETSC_EXTERN PetscErrorCode TSAdjointEventHandler(TS);

320: PETSC_EXTERN PetscLogEvent TS_AdjointStep, TS_Step, TS_PseudoComputeTimeStep, TS_FunctionEval, TS_JacobianEval;

322: typedef enum {TS_STEP_INCOMPLETE, /* vec_sol, ptime, etc point to beginning of step */
323:               TS_STEP_PENDING,    /* vec_sol advanced, but step has not been accepted yet */
324:               TS_STEP_COMPLETE    /* step accepted and ptime, steps, etc have been advanced */
325: } TSStepStatus;

327: struct _n_TSMonitorLGCtx {
328:   PetscDrawLG    lg;
329:   PetscInt       howoften;  /* when > 0 uses step % howoften, when negative only final solution plotted */
330:   PetscInt       ksp_its,snes_its;
331:   char           **names;
332:   char           **displaynames;
333:   PetscInt       ndisplayvariables;
334:   PetscInt       *displayvariables;
335:   PetscReal      *displayvalues;
336:   PetscErrorCode (*transform)(void*,Vec,Vec*);
337:   PetscErrorCode (*transformdestroy)(void*);
338:   void           *transformctx;
339: };

341: struct _n_TSMonitorEnvelopeCtx {
342:   Vec max,min;
343: };

345: PETSC_EXTERN PetscLogEvent TSTrajectory_Set, TSTrajectory_Get, TSTrajectory_DiskWrite, TSTrajectory_DiskRead;

347: #endif