Actual source code: ts.c

  1: #define PETSCTS_DLL

 3:  #include src/ts/tsimpl.h

  5: /* Logging support */
  6: PetscCookie PETSCTS_DLLEXPORT TS_COOKIE = 0;
  7: PetscEvent  TS_Step = 0, TS_PseudoComputeTimeStep = 0, TS_FunctionEval = 0, TS_JacobianEval = 0;

 11: /*
 12:   TSSetTypeFromOptions - Sets the type of ts from user options.

 14:   Collective on TS

 16:   Input Parameter:
 17: . ts - The ts

 19:   Level: intermediate

 21: .keywords: TS, set, options, database, type
 22: .seealso: TSSetFromOptions(), TSSetType()
 23: */
 24: static PetscErrorCode TSSetTypeFromOptions(TS ts)
 25: {
 26:   PetscTruth     opt;
 27:   const char     *defaultType;
 28:   char           typeName[256];

 32:   if (ts->type_name) {
 33:     defaultType = ts->type_name;
 34:   } else {
 35:     defaultType = TS_EULER;
 36:   }

 38:   if (!TSRegisterAllCalled) {
 39:     TSRegisterAll(PETSC_NULL);
 40:   }
 41:   PetscOptionsList("-ts_type", "TS method"," TSSetType", TSList, defaultType, typeName, 256, &opt);
 42:   if (opt) {
 43:     TSSetType(ts, typeName);
 44:   } else {
 45:     TSSetType(ts, defaultType);
 46:   }
 47:   return(0);
 48: }

 52: /*@
 53:    TSSetFromOptions - Sets various TS parameters from user options.

 55:    Collective on TS

 57:    Input Parameter:
 58: .  ts - the TS context obtained from TSCreate()

 60:    Options Database Keys:
 61: +  -ts_type <type> - TS_EULER, TS_BEULER, TS_PVODE, TS_PSEUDO, TS_CRANK_NICHOLSON
 62: .  -ts_max_steps maxsteps - maximum number of time-steps to take
 63: .  -ts_max_time time - maximum time to compute to
 64: .  -ts_dt dt - initial time step
 65: .  -ts_monitor - print information at each timestep
 66: -  -ts_xmonitor - plot information at each timestep

 68:    Level: beginner

 70: .keywords: TS, timestep, set, options, database

 72: .seealso: TSGetType
 73: @*/
 74: PetscErrorCode PETSCTS_DLLEXPORT TSSetFromOptions(TS ts)
 75: {
 76:   PetscReal      dt;
 77:   PetscTruth     opt;

 82:   PetscOptionsBegin(ts->comm, ts->prefix, "Time step options", "TS");

 84:   /* Handle generic TS options */
 85:   PetscOptionsInt("-ts_max_steps","Maximum number of time steps","TSSetDuration",ts->max_steps,&ts->max_steps,PETSC_NULL);
 86:   PetscOptionsReal("-ts_max_time","Time to run to","TSSetDuration",ts->max_time,&ts->max_time,PETSC_NULL);
 87:   PetscOptionsReal("-ts_init_time","Initial time","TSSetInitialTime", ts->ptime, &ts->ptime, PETSC_NULL);
 88:   PetscOptionsReal("-ts_dt","Initial time step","TSSetInitialTimeStep",ts->initial_time_step,&dt,&opt);
 89:   if (opt) {
 90:     ts->initial_time_step = ts->time_step = dt;
 91:   }

 93:   /* Monitor options */
 94:     PetscOptionsName("-ts_monitor","Monitor timestep size","TSDefaultMonitor",&opt);
 95:     if (opt) {
 96:       TSSetMonitor(ts,TSDefaultMonitor,PETSC_NULL,PETSC_NULL);
 97:     }
 98:     PetscOptionsName("-ts_xmonitor","Monitor timestep size graphically","TSLGMonitor",&opt);
 99:     if (opt) {
100:       TSSetMonitor(ts,TSLGMonitor,PETSC_NULL,PETSC_NULL);
101:     }
102:     PetscOptionsName("-ts_vecmonitor","Monitor solution graphically","TSVecViewMonitor",&opt);
103:     if (opt) {
104:       TSSetMonitor(ts,TSVecViewMonitor,PETSC_NULL,PETSC_NULL);
105:     }

107:   /* Handle TS type options */
108:   TSSetTypeFromOptions(ts);

110:   /* Handle specific TS options */
111:   if (ts->ops->setfromoptions) {
112:     (*ts->ops->setfromoptions)(ts);
113:   }
114:   PetscOptionsEnd();

116:   /* Handle subobject options */
117:   switch(ts->problem_type) {
118:     /* Should check for implicit/explicit */
119:   case TS_LINEAR:
120:     if (ts->ksp) {
121:       KSPSetOperators(ts->ksp,ts->A,ts->B,DIFFERENT_NONZERO_PATTERN);
122:       KSPSetFromOptions(ts->ksp);
123:     }
124:     break;
125:   case TS_NONLINEAR:
126:     if (ts->snes) {
127:       /* this is a bit of a hack, but it gets the matrix information into SNES earlier
128:          so that SNES and KSP have more information to pick reasonable defaults
129:          before they allow users to set options */
130:       SNESSetJacobian(ts->snes,ts->A,ts->B,0,ts);
131:       SNESSetFromOptions(ts->snes);
132:     }
133:     break;
134:   default:
135:     SETERRQ1(PETSC_ERR_ARG_WRONG, "Invalid problem type: %d", (int)ts->problem_type);
136:   }

138:   return(0);
139: }

141: #undef  __FUNCT__
143: /*@
144:   TSViewFromOptions - This function visualizes the ts based upon user options.

146:   Collective on TS

148:   Input Parameter:
149: . ts - The ts

151:   Level: intermediate

153: .keywords: TS, view, options, database
154: .seealso: TSSetFromOptions(), TSView()
155: @*/
156: PetscErrorCode PETSCTS_DLLEXPORT TSViewFromOptions(TS ts,const char title[])
157: {
158:   PetscViewer    viewer;
159:   PetscDraw      draw;
160:   PetscTruth     opt;
161:   char           typeName[1024];
162:   char           fileName[PETSC_MAX_PATH_LEN];
163:   size_t         len;

167:   PetscOptionsHasName(ts->prefix, "-ts_view", &opt);
168:   if (opt) {
169:     PetscOptionsGetString(ts->prefix, "-ts_view", typeName, 1024, &opt);
170:     PetscStrlen(typeName, &len);
171:     if (len > 0) {
172:       PetscViewerCreate(ts->comm, &viewer);
173:       PetscViewerSetType(viewer, typeName);
174:       PetscOptionsGetString(ts->prefix, "-ts_view_file", fileName, 1024, &opt);
175:       if (opt) {
176:         PetscViewerSetFilename(viewer, fileName);
177:       } else {
178:         PetscViewerSetFilename(viewer, ts->name);
179:       }
180:       TSView(ts, viewer);
181:       PetscViewerFlush(viewer);
182:       PetscViewerDestroy(viewer);
183:     } else {
184:       TSView(ts, PETSC_NULL);
185:     }
186:   }
187:   PetscOptionsHasName(ts->prefix, "-ts_view_draw", &opt);
188:   if (opt) {
189:     PetscViewerDrawOpen(ts->comm, 0, 0, 0, 0, 300, 300, &viewer);
190:     PetscViewerDrawGetDraw(viewer, 0, &draw);
191:     if (title) {
192:       PetscDrawSetTitle(draw, (char *)title);
193:     } else {
194:       PetscObjectName((PetscObject) ts);
195:       PetscDrawSetTitle(draw, ts->name);
196:     }
197:     TSView(ts, viewer);
198:     PetscViewerFlush(viewer);
199:     PetscDrawPause(draw);
200:     PetscViewerDestroy(viewer);
201:   }
202:   return(0);
203: }

207: /*@
208:    TSComputeRHSJacobian - Computes the Jacobian matrix that has been
209:       set with TSSetRHSJacobian().

211:    Collective on TS and Vec

213:    Input Parameters:
214: +  ts - the SNES context
215: .  t - current timestep
216: -  x - input vector

218:    Output Parameters:
219: +  A - Jacobian matrix
220: .  B - optional preconditioning matrix
221: -  flag - flag indicating matrix structure

223:    Notes: 
224:    Most users should not need to explicitly call this routine, as it 
225:    is used internally within the nonlinear solvers. 

227:    See KSPSetOperators() for important information about setting the
228:    flag parameter.

230:    TSComputeJacobian() is valid only for TS_NONLINEAR

232:    Level: developer

234: .keywords: SNES, compute, Jacobian, matrix

236: .seealso:  TSSetRHSJacobian(), KSPSetOperators()
237: @*/
238: PetscErrorCode PETSCTS_DLLEXPORT TSComputeRHSJacobian(TS ts,PetscReal t,Vec X,Mat *A,Mat *B,MatStructure *flg)
239: {

246:   if (ts->problem_type != TS_NONLINEAR) {
247:     SETERRQ(PETSC_ERR_ARG_WRONG,"For TS_NONLINEAR only");
248:   }
249:   if (ts->ops->rhsjacobian) {
250:     PetscLogEventBegin(TS_JacobianEval,ts,X,*A,*B);
251:     *flg = DIFFERENT_NONZERO_PATTERN;
252:     PetscStackPush("TS user Jacobian function");
253:     (*ts->ops->rhsjacobian)(ts,t,X,A,B,flg,ts->jacP);
254:     PetscStackPop;
255:     PetscLogEventEnd(TS_JacobianEval,ts,X,*A,*B);
256:     /* make sure user returned a correct Jacobian and preconditioner */
259:   } else {
260:     MatAssemblyBegin(*A,MAT_FINAL_ASSEMBLY);
261:     MatAssemblyEnd(*A,MAT_FINAL_ASSEMBLY);
262:     if (*A != *B) {
263:       MatAssemblyBegin(*B,MAT_FINAL_ASSEMBLY);
264:       MatAssemblyEnd(*B,MAT_FINAL_ASSEMBLY);
265:     }
266:   }
267:   return(0);
268: }

272: /*
273:    TSComputeRHSFunction - Evaluates the right-hand-side function. 

275:    Note: If the user did not provide a function but merely a matrix,
276:    this routine applies the matrix.
277: */
278: PetscErrorCode TSComputeRHSFunction(TS ts,PetscReal t,Vec x,Vec y)
279: {


287:   PetscLogEventBegin(TS_FunctionEval,ts,x,y,0);
288:   if (ts->ops->rhsfunction) {
289:     PetscStackPush("TS user right-hand-side function");
290:     (*ts->ops->rhsfunction)(ts,t,x,y,ts->funP);
291:     PetscStackPop;
292:   } else {
293:     if (ts->ops->rhsmatrix) { /* assemble matrix for this timestep */
294:       MatStructure flg;
295:       PetscStackPush("TS user right-hand-side matrix function");
296:       (*ts->ops->rhsmatrix)(ts,t,&ts->A,&ts->B,&flg,ts->jacP);
297:       PetscStackPop;
298:     }
299:     MatMult(ts->A,x,y);
300:   }

302:   /* apply user-provided boundary conditions (only needed if these are time dependent) */
303:   TSComputeRHSBoundaryConditions(ts,t,y);
304:   PetscLogEventEnd(TS_FunctionEval,ts,x,y,0);

306:   return(0);
307: }

311: /*@C
312:     TSSetRHSFunction - Sets the routine for evaluating the function,
313:     F(t,u), where U_t = F(t,u).

315:     Collective on TS

317:     Input Parameters:
318: +   ts - the TS context obtained from TSCreate()
319: .   f - routine for evaluating the right-hand-side function
320: -   ctx - [optional] user-defined context for private data for the 
321:           function evaluation routine (may be PETSC_NULL)

323:     Calling sequence of func:
324: $     func (TS ts,PetscReal t,Vec u,Vec F,void *ctx);

326: +   t - current timestep
327: .   u - input vector
328: .   F - function vector
329: -   ctx - [optional] user-defined function context 

331:     Important: 
332:     The user MUST call either this routine or TSSetRHSMatrix().

334:     Level: beginner

336: .keywords: TS, timestep, set, right-hand-side, function

338: .seealso: TSSetRHSMatrix()
339: @*/
340: PetscErrorCode PETSCTS_DLLEXPORT TSSetRHSFunction(TS ts,PetscErrorCode (*f)(TS,PetscReal,Vec,Vec,void*),void *ctx)
341: {

345:   if (ts->problem_type == TS_LINEAR) {
346:     SETERRQ(PETSC_ERR_ARG_WRONG,"Cannot set function for linear problem");
347:   }
348:   ts->ops->rhsfunction = f;
349:   ts->funP             = ctx;
350:   return(0);
351: }

355: /*@C
356:    TSSetRHSMatrix - Sets the function to compute the matrix A, where U_t = A(t) U.
357:    Also sets the location to store A.

359:    Collective on TS

361:    Input Parameters:
362: +  ts  - the TS context obtained from TSCreate()
363: .  A   - matrix
364: .  B   - preconditioner matrix (usually same as A)
365: .  f   - the matrix evaluation routine; use PETSC_NULL (PETSC_NULL_FUNCTION in fortran)
366:          if A is not a function of t.
367: -  ctx - [optional] user-defined context for private data for the 
368:           matrix evaluation routine (may be PETSC_NULL)

370:    Calling sequence of func:
371: $     func (TS ts,PetscReal t,Mat *A,Mat *B,PetscInt *flag,void *ctx);

373: +  t - current timestep
374: .  A - matrix A, where U_t = A(t) U
375: .  B - preconditioner matrix, usually the same as A
376: .  flag - flag indicating information about the preconditioner matrix
377:           structure (same as flag in KSPSetOperators())
378: -  ctx - [optional] user-defined context for matrix evaluation routine

380:    Notes: 
381:    See KSPSetOperators() for important information about setting the flag
382:    output parameter in the routine func().  Be sure to read this information!

384:    The routine func() takes Mat * as the matrix arguments rather than Mat.  
385:    This allows the matrix evaluation routine to replace A and/or B with a 
386:    completely new new matrix structure (not just different matrix elements)
387:    when appropriate, for instance, if the nonzero structure is changing
388:    throughout the global iterations.

390:    Important: 
391:    The user MUST call either this routine or TSSetRHSFunction().

393:    Level: beginner

395: .keywords: TS, timestep, set, right-hand-side, matrix

397: .seealso: TSSetRHSFunction()
398: @*/
399: PetscErrorCode PETSCTS_DLLEXPORT TSSetRHSMatrix(TS ts,Mat A,Mat B,PetscErrorCode (*f)(TS,PetscReal,Mat*,Mat*,MatStructure*,void*),void *ctx)
400: {
407:   if (ts->problem_type == TS_NONLINEAR) {
408:     SETERRQ(PETSC_ERR_ARG_WRONG,"Not for nonlinear problems; use TSSetRHSJacobian()");
409:   }

411:   ts->ops->rhsmatrix = f;
412:   ts->jacP           = ctx;
413:   ts->A              = A;
414:   ts->B              = B;

416:   return(0);
417: }

421: /*@C
422:    TSSetRHSJacobian - Sets the function to compute the Jacobian of F,
423:    where U_t = F(U,t), as well as the location to store the matrix.
424:    Use TSSetRHSMatrix() for linear problems.

426:    Collective on TS

428:    Input Parameters:
429: +  ts  - the TS context obtained from TSCreate()
430: .  A   - Jacobian matrix
431: .  B   - preconditioner matrix (usually same as A)
432: .  f   - the Jacobian evaluation routine
433: -  ctx - [optional] user-defined context for private data for the 
434:          Jacobian evaluation routine (may be PETSC_NULL)

436:    Calling sequence of func:
437: $     func (TS ts,PetscReal t,Vec u,Mat *A,Mat *B,MatStructure *flag,void *ctx);

439: +  t - current timestep
440: .  u - input vector
441: .  A - matrix A, where U_t = A(t)u
442: .  B - preconditioner matrix, usually the same as A
443: .  flag - flag indicating information about the preconditioner matrix
444:           structure (same as flag in KSPSetOperators())
445: -  ctx - [optional] user-defined context for matrix evaluation routine

447:    Notes: 
448:    See KSPSetOperators() for important information about setting the flag
449:    output parameter in the routine func().  Be sure to read this information!

451:    The routine func() takes Mat * as the matrix arguments rather than Mat.  
452:    This allows the matrix evaluation routine to replace A and/or B with a 
453:    completely new new matrix structure (not just different matrix elements)
454:    when appropriate, for instance, if the nonzero structure is changing
455:    throughout the global iterations.

457:    Level: beginner
458:    
459: .keywords: TS, timestep, set, right-hand-side, Jacobian

461: .seealso: TSDefaultComputeJacobianColor(),
462:           SNESDefaultComputeJacobianColor(), TSSetRHSFunction(), TSSetRHSMatrix()

464: @*/
465: PetscErrorCode PETSCTS_DLLEXPORT TSSetRHSJacobian(TS ts,Mat A,Mat B,PetscErrorCode (*f)(TS,PetscReal,Vec,Mat*,Mat*,MatStructure*,void*),void *ctx)
466: {
473:   if (ts->problem_type != TS_NONLINEAR) {
474:     SETERRQ(PETSC_ERR_ARG_WRONG,"Not for linear problems; use TSSetRHSMatrix()");
475:   }

477:   ts->ops->rhsjacobian = f;
478:   ts->jacP             = ctx;
479:   ts->A                = A;
480:   ts->B                = B;
481:   return(0);
482: }

486: /*
487:    TSComputeRHSBoundaryConditions - Evaluates the boundary condition function. 

489:    Note: If the user did not provide a function but merely a matrix,
490:    this routine applies the matrix.
491: */
492: PetscErrorCode TSComputeRHSBoundaryConditions(TS ts,PetscReal t,Vec x)
493: {


501:   if (ts->ops->rhsbc) {
502:     PetscStackPush("TS user boundary condition function");
503:     (*ts->ops->rhsbc)(ts,t,x,ts->bcP);
504:     PetscStackPop;
505:     return(0);
506:   }

508:   return(0);
509: }

513: /*@C
514:     TSSetRHSBoundaryConditions - Sets the routine for evaluating the function,
515:     boundary conditions for the function F.

517:     Collective on TS

519:     Input Parameters:
520: +   ts - the TS context obtained from TSCreate()
521: .   f - routine for evaluating the boundary condition function
522: -   ctx - [optional] user-defined context for private data for the 
523:           function evaluation routine (may be PETSC_NULL)

525:     Calling sequence of func:
526: $     func (TS ts,PetscReal t,Vec F,void *ctx);

528: +   t - current timestep
529: .   F - function vector
530: -   ctx - [optional] user-defined function context 

532:     Level: intermediate

534: .keywords: TS, timestep, set, boundary conditions, function
535: @*/
536: PetscErrorCode PETSCTS_DLLEXPORT TSSetRHSBoundaryConditions(TS ts,PetscErrorCode (*f)(TS,PetscReal,Vec,void*),void *ctx)
537: {

541:   if (ts->problem_type != TS_LINEAR) {
542:     SETERRQ(PETSC_ERR_ARG_WRONG,"For linear problems only");
543:   }
544:   ts->ops->rhsbc = f;
545:   ts->bcP        = ctx;
546:   return(0);
547: }

551: /*@C
552:     TSView - Prints the TS data structure.

554:     Collective on TS

556:     Input Parameters:
557: +   ts - the TS context obtained from TSCreate()
558: -   viewer - visualization context

560:     Options Database Key:
561: .   -ts_view - calls TSView() at end of TSStep()

563:     Notes:
564:     The available visualization contexts include
565: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
566: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
567:          output where only the first processor opens
568:          the file.  All other processors send their 
569:          data to the first processor to print. 

571:     The user can open an alternative visualization context with
572:     PetscViewerASCIIOpen() - output to a specified file.

574:     Level: beginner

576: .keywords: TS, timestep, view

578: .seealso: PetscViewerASCIIOpen()
579: @*/
580: PetscErrorCode PETSCTS_DLLEXPORT TSView(TS ts,PetscViewer viewer)
581: {
583:   char           *type;
584:   PetscTruth     iascii,isstring;

588:   if (!viewer) viewer = PETSC_VIEWER_STDOUT_(ts->comm);

592:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_ASCII,&iascii);
593:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_STRING,&isstring);
594:   if (iascii) {
595:     PetscViewerASCIIPrintf(viewer,"TS Object:\n");
596:     TSGetType(ts,(TSType *)&type);
597:     if (type) {
598:       PetscViewerASCIIPrintf(viewer,"  type: %s\n",type);
599:     } else {
600:       PetscViewerASCIIPrintf(viewer,"  type: not yet set\n");
601:     }
602:     if (ts->ops->view) {
603:       PetscViewerASCIIPushTab(viewer);
604:       (*ts->ops->view)(ts,viewer);
605:       PetscViewerASCIIPopTab(viewer);
606:     }
607:     PetscViewerASCIIPrintf(viewer,"  maximum steps=%D\n",ts->max_steps);
608:     PetscViewerASCIIPrintf(viewer,"  maximum time=%g\n",ts->max_time);
609:     if (ts->problem_type == TS_NONLINEAR) {
610:       PetscViewerASCIIPrintf(viewer,"  total number of nonlinear solver iterations=%D\n",ts->nonlinear_its);
611:     }
612:     PetscViewerASCIIPrintf(viewer,"  total number of linear solver iterations=%D\n",ts->linear_its);
613:   } else if (isstring) {
614:     TSGetType(ts,(TSType *)&type);
615:     PetscViewerStringSPrintf(viewer," %-7.7s",type);
616:   }
617:   PetscViewerASCIIPushTab(viewer);
618:   if (ts->ksp) {KSPView(ts->ksp,viewer);}
619:   if (ts->snes) {SNESView(ts->snes,viewer);}
620:   PetscViewerASCIIPopTab(viewer);
621:   return(0);
622: }


627: /*@C
628:    TSSetApplicationContext - Sets an optional user-defined context for 
629:    the timesteppers.

631:    Collective on TS

633:    Input Parameters:
634: +  ts - the TS context obtained from TSCreate()
635: -  usrP - optional user context

637:    Level: intermediate

639: .keywords: TS, timestep, set, application, context

641: .seealso: TSGetApplicationContext()
642: @*/
643: PetscErrorCode PETSCTS_DLLEXPORT TSSetApplicationContext(TS ts,void *usrP)
644: {
647:   ts->user = usrP;
648:   return(0);
649: }

653: /*@C
654:     TSGetApplicationContext - Gets the user-defined context for the 
655:     timestepper.

657:     Not Collective

659:     Input Parameter:
660: .   ts - the TS context obtained from TSCreate()

662:     Output Parameter:
663: .   usrP - user context

665:     Level: intermediate

667: .keywords: TS, timestep, get, application, context

669: .seealso: TSSetApplicationContext()
670: @*/
671: PetscErrorCode PETSCTS_DLLEXPORT TSGetApplicationContext(TS ts,void **usrP)
672: {
675:   *usrP = ts->user;
676:   return(0);
677: }

681: /*@
682:    TSGetTimeStepNumber - Gets the current number of timesteps.

684:    Not Collective

686:    Input Parameter:
687: .  ts - the TS context obtained from TSCreate()

689:    Output Parameter:
690: .  iter - number steps so far

692:    Level: intermediate

694: .keywords: TS, timestep, get, iteration, number
695: @*/
696: PetscErrorCode PETSCTS_DLLEXPORT TSGetTimeStepNumber(TS ts,PetscInt* iter)
697: {
701:   *iter = ts->steps;
702:   return(0);
703: }

707: /*@
708:    TSSetInitialTimeStep - Sets the initial timestep to be used, 
709:    as well as the initial time.

711:    Collective on TS

713:    Input Parameters:
714: +  ts - the TS context obtained from TSCreate()
715: .  initial_time - the initial time
716: -  time_step - the size of the timestep

718:    Level: intermediate

720: .seealso: TSSetTimeStep(), TSGetTimeStep()

722: .keywords: TS, set, initial, timestep
723: @*/
724: PetscErrorCode PETSCTS_DLLEXPORT TSSetInitialTimeStep(TS ts,PetscReal initial_time,PetscReal time_step)
725: {
728:   ts->time_step         = time_step;
729:   ts->initial_time_step = time_step;
730:   ts->ptime             = initial_time;
731:   return(0);
732: }

736: /*@
737:    TSSetTimeStep - Allows one to reset the timestep at any time,
738:    useful for simple pseudo-timestepping codes.

740:    Collective on TS

742:    Input Parameters:
743: +  ts - the TS context obtained from TSCreate()
744: -  time_step - the size of the timestep

746:    Level: intermediate

748: .seealso: TSSetInitialTimeStep(), TSGetTimeStep()

750: .keywords: TS, set, timestep
751: @*/
752: PetscErrorCode PETSCTS_DLLEXPORT TSSetTimeStep(TS ts,PetscReal time_step)
753: {
756:   ts->time_step = time_step;
757:   return(0);
758: }

762: /*@
763:    TSGetTimeStep - Gets the current timestep size.

765:    Not Collective

767:    Input Parameter:
768: .  ts - the TS context obtained from TSCreate()

770:    Output Parameter:
771: .  dt - the current timestep size

773:    Level: intermediate

775: .seealso: TSSetInitialTimeStep(), TSGetTimeStep()

777: .keywords: TS, get, timestep
778: @*/
779: PetscErrorCode PETSCTS_DLLEXPORT TSGetTimeStep(TS ts,PetscReal* dt)
780: {
784:   *dt = ts->time_step;
785:   return(0);
786: }

790: /*@C
791:    TSGetSolution - Returns the solution at the present timestep. It
792:    is valid to call this routine inside the function that you are evaluating
793:    in order to move to the new timestep. This vector not changed until
794:    the solution at the next timestep has been calculated.

796:    Not Collective, but Vec returned is parallel if TS is parallel

798:    Input Parameter:
799: .  ts - the TS context obtained from TSCreate()

801:    Output Parameter:
802: .  v - the vector containing the solution

804:    Level: intermediate

806: .seealso: TSGetTimeStep()

808: .keywords: TS, timestep, get, solution
809: @*/
810: PetscErrorCode PETSCTS_DLLEXPORT TSGetSolution(TS ts,Vec *v)
811: {
815:   *v = ts->vec_sol_always;
816:   return(0);
817: }

819: /* ----- Routines to initialize and destroy a timestepper ---- */
822: /*@C
823:   TSSetProblemType - Sets the type of problem to be solved.

825:   Not collective

827:   Input Parameters:
828: + ts   - The TS
829: - type - One of TS_LINEAR, TS_NONLINEAR where these types refer to problems of the forms
830: .vb
831:          U_t = A U    
832:          U_t = A(t) U 
833:          U_t = F(t,U) 
834: .ve

836:    Level: beginner

838: .keywords: TS, problem type
839: .seealso: TSSetUp(), TSProblemType, TS
840: @*/
841: PetscErrorCode PETSCTS_DLLEXPORT TSSetProblemType(TS ts, TSProblemType type)
842: {
845:   ts->problem_type = type;
846:   return(0);
847: }

851: /*@C
852:   TSGetProblemType - Gets the type of problem to be solved.

854:   Not collective

856:   Input Parameter:
857: . ts   - The TS

859:   Output Parameter:
860: . type - One of TS_LINEAR, TS_NONLINEAR where these types refer to problems of the forms
861: .vb
862:          U_t = A U    
863:          U_t = A(t) U 
864:          U_t = F(t,U) 
865: .ve

867:    Level: beginner

869: .keywords: TS, problem type
870: .seealso: TSSetUp(), TSProblemType, TS
871: @*/
872: PetscErrorCode PETSCTS_DLLEXPORT TSGetProblemType(TS ts, TSProblemType *type)
873: {
877:   *type = ts->problem_type;
878:   return(0);
879: }

883: /*@
884:    TSSetUp - Sets up the internal data structures for the later use
885:    of a timestepper.  

887:    Collective on TS

889:    Input Parameter:
890: .  ts - the TS context obtained from TSCreate()

892:    Notes:
893:    For basic use of the TS solvers the user need not explicitly call
894:    TSSetUp(), since these actions will automatically occur during
895:    the call to TSStep().  However, if one wishes to control this
896:    phase separately, TSSetUp() should be called after TSCreate()
897:    and optional routines of the form TSSetXXX(), but before TSStep().  

899:    Level: advanced

901: .keywords: TS, timestep, setup

903: .seealso: TSCreate(), TSStep(), TSDestroy()
904: @*/
905: PetscErrorCode PETSCTS_DLLEXPORT TSSetUp(TS ts)
906: {

911:   if (!ts->vec_sol) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call TSSetSolution() first");
912:   if (!ts->type_name) {
913:     TSSetType(ts,TS_EULER);
914:   }
915:   (*ts->ops->setup)(ts);
916:   ts->setupcalled = 1;
917:   return(0);
918: }

922: /*@C
923:    TSDestroy - Destroys the timestepper context that was created
924:    with TSCreate().

926:    Collective on TS

928:    Input Parameter:
929: .  ts - the TS context obtained from TSCreate()

931:    Level: beginner

933: .keywords: TS, timestepper, destroy

935: .seealso: TSCreate(), TSSetUp(), TSSolve()
936: @*/
937: PetscErrorCode PETSCTS_DLLEXPORT TSDestroy(TS ts)
938: {
940:   PetscInt       i;

944:   if (--ts->refct > 0) return(0);

946:   /* if memory was published with AMS then destroy it */
947:   PetscObjectDepublish(ts);

949:   if (ts->ksp) {KSPDestroy(ts->ksp);}
950:   if (ts->snes) {SNESDestroy(ts->snes);}
951:   (*(ts)->ops->destroy)(ts);
952:   for (i=0; i<ts->numbermonitors; i++) {
953:     if (ts->mdestroy[i]) {
954:       (*ts->mdestroy[i])(ts->monitorcontext[i]);
955:     }
956:   }
957:   PetscHeaderDestroy(ts);
958:   return(0);
959: }

963: /*@C
964:    TSGetSNES - Returns the SNES (nonlinear solver) associated with 
965:    a TS (timestepper) context. Valid only for nonlinear problems.

967:    Not Collective, but SNES is parallel if TS is parallel

969:    Input Parameter:
970: .  ts - the TS context obtained from TSCreate()

972:    Output Parameter:
973: .  snes - the nonlinear solver context

975:    Notes:
976:    The user can then directly manipulate the SNES context to set various
977:    options, etc.  Likewise, the user can then extract and manipulate the 
978:    KSP, KSP, and PC contexts as well.

980:    TSGetSNES() does not work for integrators that do not use SNES; in
981:    this case TSGetSNES() returns PETSC_NULL in snes.

983:    Level: beginner

985: .keywords: timestep, get, SNES
986: @*/
987: PetscErrorCode PETSCTS_DLLEXPORT TSGetSNES(TS ts,SNES *snes)
988: {
992:   if (ts->problem_type == TS_LINEAR) SETERRQ(PETSC_ERR_ARG_WRONG,"Nonlinear only; use TSGetKSP()");
993:   *snes = ts->snes;
994:   return(0);
995: }

999: /*@C
1000:    TSGetKSP - Returns the KSP (linear solver) associated with 
1001:    a TS (timestepper) context.

1003:    Not Collective, but KSP is parallel if TS is parallel

1005:    Input Parameter:
1006: .  ts - the TS context obtained from TSCreate()

1008:    Output Parameter:
1009: .  ksp - the nonlinear solver context

1011:    Notes:
1012:    The user can then directly manipulate the KSP context to set various
1013:    options, etc.  Likewise, the user can then extract and manipulate the 
1014:    KSP and PC contexts as well.

1016:    TSGetKSP() does not work for integrators that do not use KSP;
1017:    in this case TSGetKSP() returns PETSC_NULL in ksp.

1019:    Level: beginner

1021: .keywords: timestep, get, KSP
1022: @*/
1023: PetscErrorCode PETSCTS_DLLEXPORT TSGetKSP(TS ts,KSP *ksp)
1024: {
1028:   if (ts->problem_type != TS_LINEAR) SETERRQ(PETSC_ERR_ARG_WRONG,"Linear only; use TSGetSNES()");
1029:   *ksp = ts->ksp;
1030:   return(0);
1031: }

1033: /* ----------- Routines to set solver parameters ---------- */

1037: /*@
1038:    TSGetDuration - Gets the maximum number of timesteps to use and 
1039:    maximum time for iteration.

1041:    Collective on TS

1043:    Input Parameters:
1044: +  ts       - the TS context obtained from TSCreate()
1045: .  maxsteps - maximum number of iterations to use, or PETSC_NULL
1046: -  maxtime  - final time to iterate to, or PETSC_NULL

1048:    Level: intermediate

1050: .keywords: TS, timestep, get, maximum, iterations, time
1051: @*/
1052: PetscErrorCode PETSCTS_DLLEXPORT TSGetDuration(TS ts, PetscInt *maxsteps, PetscReal *maxtime)
1053: {
1056:   if (maxsteps) {
1058:     *maxsteps = ts->max_steps;
1059:   }
1060:   if (maxtime ) {
1062:     *maxtime  = ts->max_time;
1063:   }
1064:   return(0);
1065: }

1069: /*@
1070:    TSSetDuration - Sets the maximum number of timesteps to use and 
1071:    maximum time for iteration.

1073:    Collective on TS

1075:    Input Parameters:
1076: +  ts - the TS context obtained from TSCreate()
1077: .  maxsteps - maximum number of iterations to use
1078: -  maxtime - final time to iterate to

1080:    Options Database Keys:
1081: .  -ts_max_steps <maxsteps> - Sets maxsteps
1082: .  -ts_max_time <maxtime> - Sets maxtime

1084:    Notes:
1085:    The default maximum number of iterations is 5000. Default time is 5.0

1087:    Level: intermediate

1089: .keywords: TS, timestep, set, maximum, iterations
1090: @*/
1091: PetscErrorCode PETSCTS_DLLEXPORT TSSetDuration(TS ts,PetscInt maxsteps,PetscReal maxtime)
1092: {
1095:   ts->max_steps = maxsteps;
1096:   ts->max_time  = maxtime;
1097:   return(0);
1098: }

1102: /*@
1103:    TSSetSolution - Sets the initial solution vector
1104:    for use by the TS routines.

1106:    Collective on TS and Vec

1108:    Input Parameters:
1109: +  ts - the TS context obtained from TSCreate()
1110: -  x - the solution vector

1112:    Level: beginner

1114: .keywords: TS, timestep, set, solution, initial conditions
1115: @*/
1116: PetscErrorCode PETSCTS_DLLEXPORT TSSetSolution(TS ts,Vec x)
1117: {
1121:   ts->vec_sol        = ts->vec_sol_always = x;
1122:   return(0);
1123: }

1127: /*@
1128:   TSDefaultRhsBC - The default boundary condition function which does nothing.

1130:   Collective on TS

1132:   Input Parameters:
1133: + ts  - The TS context obtained from TSCreate()
1134: . rhs - The Rhs
1135: - ctx - The user-context

1137:   Level: developer

1139: .keywords: TS, Rhs, boundary conditions
1140: @*/
1141: PetscErrorCode PETSCTS_DLLEXPORT TSDefaultRhsBC(TS ts,  Vec rhs, void *ctx)
1142: {
1144:   return(0);
1145: }

1149: /*@C
1150:   TSSetSystemMatrixBC - Sets the function which applies boundary conditions
1151:   to the system matrix and preconditioner of each system.

1153:   Collective on TS

1155:   Input Parameters:
1156: + ts   - The TS context obtained from TSCreate()
1157: - func - The function

1159:   Calling sequence of func:
1160: . func (TS ts, Mat A, Mat B, void *ctx);

1162: + A   - The current system matrix
1163: . B   - The current preconditioner
1164: - ctx - The user-context

1166:   Level: intermediate

1168: .keywords: TS, System matrix, boundary conditions
1169: @*/
1170: PetscErrorCode PETSCTS_DLLEXPORT TSSetSystemMatrixBC(TS ts, PetscErrorCode (*func)(TS, Mat, Mat, void *))
1171: {
1174:   ts->ops->applymatrixbc = func;
1175:   return(0);
1176: }

1180: /*@
1181:   TSDefaultSystemMatrixBC - The default boundary condition function which
1182:   does nothing.

1184:   Collective on TS

1186:   Input Parameters:
1187: + ts  - The TS context obtained from TSCreate()
1188: . A   - The system matrix
1189: . B   - The preconditioner
1190: - ctx - The user-context

1192:   Level: developer

1194: .keywords: TS, System matrix, boundary conditions
1195: @*/
1196: PetscErrorCode PETSCTS_DLLEXPORT TSDefaultSystemMatrixBC(TS ts, Mat A, Mat B, void *ctx)
1197: {
1199:   return(0);
1200: }

1204: /*@C
1205:   TSSetSolutionBC - Sets the function which applies boundary conditions
1206:   to the solution of each system. This is necessary in nonlinear systems
1207:   which time dependent boundary conditions.

1209:   Collective on TS

1211:   Input Parameters:
1212: + ts   - The TS context obtained from TSCreate()
1213: - func - The function

1215:   Calling sequence of func:
1216: . func (TS ts, Vec rsol, void *ctx);

1218: + sol - The current solution vector
1219: - ctx - The user-context

1221:   Level: intermediate

1223: .keywords: TS, solution, boundary conditions
1224: @*/
1225: PetscErrorCode PETSCTS_DLLEXPORT TSSetSolutionBC(TS ts, PetscErrorCode (*func)(TS, Vec, void *))
1226: {
1229:   ts->ops->applysolbc = func;
1230:   return(0);
1231: }

1235: /*@
1236:   TSDefaultSolutionBC - The default boundary condition function which
1237:   does nothing.

1239:   Collective on TS

1241:   Input Parameters:
1242: + ts  - The TS context obtained from TSCreate()
1243: . sol - The solution
1244: - ctx - The user-context

1246:   Level: developer

1248: .keywords: TS, solution, boundary conditions
1249: @*/
1250: PetscErrorCode PETSCTS_DLLEXPORT TSDefaultSolutionBC(TS ts, Vec sol, void *ctx)
1251: {
1253:   return(0);
1254: }

1258: /*@C
1259:   TSSetPreStep - Sets the general-purpose function
1260:   called once at the beginning of time stepping.

1262:   Collective on TS

1264:   Input Parameters:
1265: + ts   - The TS context obtained from TSCreate()
1266: - func - The function

1268:   Calling sequence of func:
1269: . func (TS ts);

1271:   Level: intermediate

1273: .keywords: TS, timestep
1274: @*/
1275: PetscErrorCode PETSCTS_DLLEXPORT TSSetPreStep(TS ts, PetscErrorCode (*func)(TS))
1276: {
1279:   ts->ops->prestep = func;
1280:   return(0);
1281: }

1285: /*@
1286:   TSDefaultPreStep - The default pre-stepping function which does nothing.

1288:   Collective on TS

1290:   Input Parameters:
1291: . ts  - The TS context obtained from TSCreate()

1293:   Level: developer

1295: .keywords: TS, timestep
1296: @*/
1297: PetscErrorCode PETSCTS_DLLEXPORT TSDefaultPreStep(TS ts)
1298: {
1300:   return(0);
1301: }

1305: /*@C
1306:   TSSetUpdate - Sets the general-purpose update function called
1307:   at the beginning of every time step. This function can change
1308:   the time step.

1310:   Collective on TS

1312:   Input Parameters:
1313: + ts   - The TS context obtained from TSCreate()
1314: - func - The function

1316:   Calling sequence of func:
1317: . func (TS ts, double t, double *dt);

1319: + t   - The current time
1320: - dt  - The current time step

1322:   Level: intermediate

1324: .keywords: TS, update, timestep
1325: @*/
1326: PetscErrorCode PETSCTS_DLLEXPORT TSSetUpdate(TS ts, PetscErrorCode (*func)(TS, PetscReal, PetscReal *))
1327: {
1330:   ts->ops->update = func;
1331:   return(0);
1332: }

1336: /*@
1337:   TSDefaultUpdate - The default update function which does nothing.

1339:   Collective on TS

1341:   Input Parameters:
1342: + ts  - The TS context obtained from TSCreate()
1343: - t   - The current time

1345:   Output Parameters:
1346: . dt  - The current time step

1348:   Level: developer

1350: .keywords: TS, update, timestep
1351: @*/
1352: PetscErrorCode PETSCTS_DLLEXPORT TSDefaultUpdate(TS ts, PetscReal t, PetscReal *dt)
1353: {
1355:   return(0);
1356: }

1360: /*@C
1361:   TSSetPostStep - Sets the general-purpose function
1362:   called once at the end of time stepping.

1364:   Collective on TS

1366:   Input Parameters:
1367: + ts   - The TS context obtained from TSCreate()
1368: - func - The function

1370:   Calling sequence of func:
1371: . func (TS ts);

1373:   Level: intermediate

1375: .keywords: TS, timestep
1376: @*/
1377: PetscErrorCode PETSCTS_DLLEXPORT TSSetPostStep(TS ts, PetscErrorCode (*func)(TS))
1378: {
1381:   ts->ops->poststep = func;
1382:   return(0);
1383: }

1387: /*@
1388:   TSDefaultPostStep - The default post-stepping function which does nothing.

1390:   Collective on TS

1392:   Input Parameters:
1393: . ts  - The TS context obtained from TSCreate()

1395:   Level: developer

1397: .keywords: TS, timestep
1398: @*/
1399: PetscErrorCode PETSCTS_DLLEXPORT TSDefaultPostStep(TS ts)
1400: {
1402:   return(0);
1403: }

1405: /* ------------ Routines to set performance monitoring options ----------- */

1409: /*@C
1410:    TSSetMonitor - Sets an ADDITIONAL function that is to be used at every
1411:    timestep to display the iteration's  progress.   

1413:    Collective on TS

1415:    Input Parameters:
1416: +  ts - the TS context obtained from TSCreate()
1417: .  func - monitoring routine
1418: .  mctx - [optional] user-defined context for private data for the 
1419:              monitor routine (use PETSC_NULL if no context is desired)
1420: -  monitordestroy - [optional] routine that frees monitor context
1421:           (may be PETSC_NULL)

1423:    Calling sequence of func:
1424: $    int func(TS ts,PetscInt steps,PetscReal time,Vec x,void *mctx)

1426: +    ts - the TS context
1427: .    steps - iteration number
1428: .    time - current time
1429: .    x - current iterate
1430: -    mctx - [optional] monitoring context

1432:    Notes:
1433:    This routine adds an additional monitor to the list of monitors that 
1434:    already has been loaded.

1436:    Level: intermediate

1438: .keywords: TS, timestep, set, monitor

1440: .seealso: TSDefaultMonitor(), TSClearMonitor()
1441: @*/
1442: PetscErrorCode PETSCTS_DLLEXPORT TSSetMonitor(TS ts,PetscErrorCode (*monitor)(TS,PetscInt,PetscReal,Vec,void*),void *mctx,PetscErrorCode (*mdestroy)(void*))
1443: {
1446:   if (ts->numbermonitors >= MAXTSMONITORS) {
1447:     SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many monitors set");
1448:   }
1449:   ts->monitor[ts->numbermonitors]           = monitor;
1450:   ts->mdestroy[ts->numbermonitors]          = mdestroy;
1451:   ts->monitorcontext[ts->numbermonitors++]  = (void*)mctx;
1452:   return(0);
1453: }

1457: /*@C
1458:    TSClearMonitor - Clears all the monitors that have been set on a time-step object.   

1460:    Collective on TS

1462:    Input Parameters:
1463: .  ts - the TS context obtained from TSCreate()

1465:    Notes:
1466:    There is no way to remove a single, specific monitor.

1468:    Level: intermediate

1470: .keywords: TS, timestep, set, monitor

1472: .seealso: TSDefaultMonitor(), TSSetMonitor()
1473: @*/
1474: PetscErrorCode PETSCTS_DLLEXPORT TSClearMonitor(TS ts)
1475: {
1478:   ts->numbermonitors = 0;
1479:   return(0);
1480: }

1484: PetscErrorCode TSDefaultMonitor(TS ts,PetscInt step,PetscReal ptime,Vec v,void *ctx)
1485: {

1489:   PetscPrintf(ts->comm,"timestep %D dt %g time %g\n",step,ts->time_step,ptime);
1490:   return(0);
1491: }

1495: /*@
1496:    TSStep - Steps the requested number of timesteps.

1498:    Collective on TS

1500:    Input Parameter:
1501: .  ts - the TS context obtained from TSCreate()

1503:    Output Parameters:
1504: +  steps - number of iterations until termination
1505: -  ptime - time until termination

1507:    Level: beginner

1509: .keywords: TS, timestep, solve

1511: .seealso: TSCreate(), TSSetUp(), TSDestroy()
1512: @*/
1513: PetscErrorCode PETSCTS_DLLEXPORT TSStep(TS ts,PetscInt *steps,PetscReal *ptime)
1514: {

1519:   if (!ts->setupcalled) {
1520:     TSSetUp(ts);
1521:   }

1523:   PetscLogEventBegin(TS_Step, ts, 0, 0, 0);
1524:   (*ts->ops->prestep)(ts);
1525:   (*ts->ops->step)(ts, steps, ptime);
1526:   (*ts->ops->poststep)(ts);
1527:   PetscLogEventEnd(TS_Step, ts, 0, 0, 0);

1529:   if (!PetscPreLoadingOn) {
1530:     TSViewFromOptions(ts,ts->name);
1531:   }
1532:   return(0);
1533: }

1537: /*
1538:      Runs the user provided monitor routines, if they exists.
1539: */
1540: PetscErrorCode TSMonitor(TS ts,PetscInt step,PetscReal ptime,Vec x)
1541: {
1543:   PetscInt i,n = ts->numbermonitors;

1546:   for (i=0; i<n; i++) {
1547:     (*ts->monitor[i])(ts,step,ptime,x,ts->monitorcontext[i]);
1548:   }
1549:   return(0);
1550: }

1552: /* ------------------------------------------------------------------------*/

1556: /*@C
1557:    TSLGMonitorCreate - Creates a line graph context for use with 
1558:    TS to monitor convergence of preconditioned residual norms.

1560:    Collective on TS

1562:    Input Parameters:
1563: +  host - the X display to open, or null for the local machine
1564: .  label - the title to put in the title bar
1565: .  x, y - the screen coordinates of the upper left coordinate of the window
1566: -  m, n - the screen width and height in pixels

1568:    Output Parameter:
1569: .  draw - the drawing context

1571:    Options Database Key:
1572: .  -ts_xmonitor - automatically sets line graph monitor

1574:    Notes: 
1575:    Use TSLGMonitorDestroy() to destroy this line graph, not PetscDrawLGDestroy().

1577:    Level: intermediate

1579: .keywords: TS, monitor, line graph, residual, seealso

1581: .seealso: TSLGMonitorDestroy(), TSSetMonitor()

1583: @*/
1584: PetscErrorCode PETSCTS_DLLEXPORT TSLGMonitorCreate(const char host[],const char label[],int x,int y,int m,int n,PetscDrawLG *draw)
1585: {
1586:   PetscDraw      win;

1590:   PetscDrawCreate(PETSC_COMM_SELF,host,label,x,y,m,n,&win);
1591:   PetscDrawSetType(win,PETSC_DRAW_X);
1592:   PetscDrawLGCreate(win,1,draw);
1593:   PetscDrawLGIndicateDataPoints(*draw);

1595:   PetscLogObjectParent(*draw,win);
1596:   return(0);
1597: }

1601: PetscErrorCode TSLGMonitor(TS ts,PetscInt n,PetscReal ptime,Vec v,void *monctx)
1602: {
1603:   PetscDrawLG    lg = (PetscDrawLG) monctx;
1604:   PetscReal      x,y = ptime;

1608:   if (!monctx) {
1609:     MPI_Comm    comm;
1610:     PetscViewer viewer;

1612:     PetscObjectGetComm((PetscObject)ts,&comm);
1613:     viewer = PETSC_VIEWER_DRAW_(comm);
1614:     PetscViewerDrawGetDrawLG(viewer,0,&lg);
1615:   }

1617:   if (!n) {PetscDrawLGReset(lg);}
1618:   x = (PetscReal)n;
1619:   PetscDrawLGAddPoint(lg,&x,&y);
1620:   if (n < 20 || (n % 5)) {
1621:     PetscDrawLGDraw(lg);
1622:   }
1623:   return(0);
1624: }

1628: /*@C
1629:    TSLGMonitorDestroy - Destroys a line graph context that was created 
1630:    with TSLGMonitorCreate().

1632:    Collective on PetscDrawLG

1634:    Input Parameter:
1635: .  draw - the drawing context

1637:    Level: intermediate

1639: .keywords: TS, monitor, line graph, destroy

1641: .seealso: TSLGMonitorCreate(),  TSSetMonitor(), TSLGMonitor();
1642: @*/
1643: PetscErrorCode PETSCTS_DLLEXPORT TSLGMonitorDestroy(PetscDrawLG drawlg)
1644: {
1645:   PetscDraw      draw;

1649:   PetscDrawLGGetDraw(drawlg,&draw);
1650:   PetscDrawDestroy(draw);
1651:   PetscDrawLGDestroy(drawlg);
1652:   return(0);
1653: }

1657: /*@
1658:    TSGetTime - Gets the current time.

1660:    Not Collective

1662:    Input Parameter:
1663: .  ts - the TS context obtained from TSCreate()

1665:    Output Parameter:
1666: .  t  - the current time

1668:    Contributed by: Matthew Knepley

1670:    Level: beginner

1672: .seealso: TSSetInitialTimeStep(), TSGetTimeStep()

1674: .keywords: TS, get, time
1675: @*/
1676: PetscErrorCode PETSCTS_DLLEXPORT TSGetTime(TS ts,PetscReal* t)
1677: {
1681:   *t = ts->ptime;
1682:   return(0);
1683: }

1687: /*@C
1688:    TSSetOptionsPrefix - Sets the prefix used for searching for all
1689:    TS options in the database.

1691:    Collective on TS

1693:    Input Parameter:
1694: +  ts     - The TS context
1695: -  prefix - The prefix to prepend to all option names

1697:    Notes:
1698:    A hyphen (-) must NOT be given at the beginning of the prefix name.
1699:    The first character of all runtime options is AUTOMATICALLY the
1700:    hyphen.

1702:    Contributed by: Matthew Knepley

1704:    Level: advanced

1706: .keywords: TS, set, options, prefix, database

1708: .seealso: TSSetFromOptions()

1710: @*/
1711: PetscErrorCode PETSCTS_DLLEXPORT TSSetOptionsPrefix(TS ts,const char prefix[])
1712: {

1717:   PetscObjectSetOptionsPrefix((PetscObject)ts,prefix);
1718:   switch(ts->problem_type) {
1719:     case TS_NONLINEAR:
1720:       SNESSetOptionsPrefix(ts->snes,prefix);
1721:       break;
1722:     case TS_LINEAR:
1723:       KSPSetOptionsPrefix(ts->ksp,prefix);
1724:       break;
1725:   }
1726:   return(0);
1727: }


1732: /*@C
1733:    TSAppendOptionsPrefix - Appends to the prefix used for searching for all
1734:    TS options in the database.

1736:    Collective on TS

1738:    Input Parameter:
1739: +  ts     - The TS context
1740: -  prefix - The prefix to prepend to all option names

1742:    Notes:
1743:    A hyphen (-) must NOT be given at the beginning of the prefix name.
1744:    The first character of all runtime options is AUTOMATICALLY the
1745:    hyphen.

1747:    Contributed by: Matthew Knepley

1749:    Level: advanced

1751: .keywords: TS, append, options, prefix, database

1753: .seealso: TSGetOptionsPrefix()

1755: @*/
1756: PetscErrorCode PETSCTS_DLLEXPORT TSAppendOptionsPrefix(TS ts,const char prefix[])
1757: {

1762:   PetscObjectAppendOptionsPrefix((PetscObject)ts,prefix);
1763:   switch(ts->problem_type) {
1764:     case TS_NONLINEAR:
1765:       SNESAppendOptionsPrefix(ts->snes,prefix);
1766:       break;
1767:     case TS_LINEAR:
1768:       KSPAppendOptionsPrefix(ts->ksp,prefix);
1769:       break;
1770:   }
1771:   return(0);
1772: }

1776: /*@C
1777:    TSGetOptionsPrefix - Sets the prefix used for searching for all
1778:    TS options in the database.

1780:    Not Collective

1782:    Input Parameter:
1783: .  ts - The TS context

1785:    Output Parameter:
1786: .  prefix - A pointer to the prefix string used

1788:    Contributed by: Matthew Knepley

1790:    Notes: On the fortran side, the user should pass in a string 'prifix' of
1791:    sufficient length to hold the prefix.

1793:    Level: intermediate

1795: .keywords: TS, get, options, prefix, database

1797: .seealso: TSAppendOptionsPrefix()
1798: @*/
1799: PetscErrorCode PETSCTS_DLLEXPORT TSGetOptionsPrefix(TS ts,const char *prefix[])
1800: {

1806:   PetscObjectGetOptionsPrefix((PetscObject)ts,prefix);
1807:   return(0);
1808: }

1812: /*@C
1813:    TSGetRHSMatrix - Returns the matrix A at the present timestep.

1815:    Not Collective, but parallel objects are returned if TS is parallel

1817:    Input Parameter:
1818: .  ts  - The TS context obtained from TSCreate()

1820:    Output Parameters:
1821: +  A   - The matrix A, where U_t = A(t) U
1822: .  M   - The preconditioner matrix, usually the same as A
1823: -  ctx - User-defined context for matrix evaluation routine

1825:    Notes: You can pass in PETSC_NULL for any return argument you do not need.

1827:    Contributed by: Matthew Knepley

1829:    Level: intermediate

1831: .seealso: TSGetTimeStep(), TSGetTime(), TSGetTimeStepNumber(), TSGetRHSJacobian()

1833: .keywords: TS, timestep, get, matrix

1835: @*/
1836: PetscErrorCode PETSCTS_DLLEXPORT TSGetRHSMatrix(TS ts,Mat *A,Mat *M,void **ctx)
1837: {
1840:   if (A)   *A = ts->A;
1841:   if (M)   *M = ts->B;
1842:   if (ctx) *ctx = ts->jacP;
1843:   return(0);
1844: }

1848: /*@C
1849:    TSGetRHSJacobian - Returns the Jacobian J at the present timestep.

1851:    Not Collective, but parallel objects are returned if TS is parallel

1853:    Input Parameter:
1854: .  ts  - The TS context obtained from TSCreate()

1856:    Output Parameters:
1857: +  J   - The Jacobian J of F, where U_t = F(U,t)
1858: .  M   - The preconditioner matrix, usually the same as J
1859: - ctx - User-defined context for Jacobian evaluation routine

1861:    Notes: You can pass in PETSC_NULL for any return argument you do not need.

1863:    Contributed by: Matthew Knepley

1865:    Level: intermediate

1867: .seealso: TSGetTimeStep(), TSGetRHSMatrix(), TSGetTime(), TSGetTimeStepNumber()

1869: .keywords: TS, timestep, get, matrix, Jacobian
1870: @*/
1871: PetscErrorCode PETSCTS_DLLEXPORT TSGetRHSJacobian(TS ts,Mat *J,Mat *M,void **ctx)
1872: {

1876:   TSGetRHSMatrix(ts,J,M,ctx);
1877:   return(0);
1878: }

1882: /*@C
1883:    TSVecViewMonitor - Monitors progress of the TS solvers by calling 
1884:    VecView() for the solution at each timestep

1886:    Collective on TS

1888:    Input Parameters:
1889: +  ts - the TS context
1890: .  step - current time-step
1891: .  ptime - current time
1892: -  dummy - either a viewer or PETSC_NULL

1894:    Level: intermediate

1896: .keywords: TS,  vector, monitor, view

1898: .seealso: TSSetMonitor(), TSDefaultMonitor(), VecView()
1899: @*/
1900: PetscErrorCode PETSCTS_DLLEXPORT TSVecViewMonitor(TS ts,PetscInt step,PetscReal ptime,Vec x,void *dummy)
1901: {
1903:   PetscViewer    viewer = (PetscViewer) dummy;

1906:   if (!viewer) {
1907:     MPI_Comm comm;
1908:     PetscObjectGetComm((PetscObject)ts,&comm);
1909:     viewer = PETSC_VIEWER_DRAW_(comm);
1910:   }
1911:   VecView(x,viewer);
1912:   return(0);
1913: }