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

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

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

    948:   if (ts->ksp) {KSPDestroy(ts->ksp);}
    949:   if (ts->snes) {SNESDestroy(ts->snes);}
    950:   (*(ts)->ops->destroy)(ts);
    951:   TSClearMonitor(ts);
    952:   PetscHeaderDestroy(ts);
    953:   return(0);
    954: }

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

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

    964:    Input Parameter:
    965: .  ts - the TS context obtained from TSCreate()

    967:    Output Parameter:
    968: .  snes - the nonlinear solver context

    970:    Notes:
    971:    The user can then directly manipulate the SNES context to set various
    972:    options, etc.  Likewise, the user can then extract and manipulate the
    973:    KSP, KSP, and PC contexts as well.

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

    978:    Level: beginner

    980: .keywords: timestep, get, SNES
    981: @*/
    982: PetscErrorCode PETSCTS_DLLEXPORT TSGetSNES(TS ts,SNES *snes)
    983: {
    987:   if (ts->problem_type == TS_LINEAR) SETERRQ(PETSC_ERR_ARG_WRONG,"Nonlinear only; use TSGetKSP()");
    988:   *snes = ts->snes;
    989:   return(0);
    990: }

    994: /*@C
    995:    TSGetKSP - Returns the KSP (linear solver) associated with
    996:    a TS (timestepper) context.

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

    1000:    Input Parameter:
    1001: .  ts - the TS context obtained from TSCreate()

    1003:    Output Parameter:
    1004: .  ksp - the nonlinear solver context

    1006:    Notes:
    1007:    The user can then directly manipulate the KSP context to set various
    1008:    options, etc.  Likewise, the user can then extract and manipulate the
    1009:    KSP and PC contexts as well.

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

    1014:    Level: beginner

    1016: .keywords: timestep, get, KSP
    1017: @*/
    1018: PetscErrorCode PETSCTS_DLLEXPORT TSGetKSP(TS ts,KSP *ksp)
    1019: {
    1023:   if (ts->problem_type != TS_LINEAR) SETERRQ(PETSC_ERR_ARG_WRONG,"Linear only; use TSGetSNES()");
    1024:   *ksp = ts->ksp;
    1025:   return(0);
    1026: }

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

    1032: /*@
    1033:    TSGetDuration - Gets the maximum number of timesteps to use and
    1034:    maximum time for iteration.

    1036:    Collective on TS

    1038:    Input Parameters:
    1039: +  ts       - the TS context obtained from TSCreate()
    1040: .  maxsteps - maximum number of iterations to use, or PETSC_NULL
    1041: -  maxtime  - final time to iterate to, or PETSC_NULL

    1043:    Level: intermediate

    1045: .keywords: TS, timestep, get, maximum, iterations, time
    1046: @*/
    1047: PetscErrorCode PETSCTS_DLLEXPORT TSGetDuration(TS ts, PetscInt *maxsteps, PetscReal *maxtime)
    1048: {
    1051:   if (maxsteps) {
    1053:     *maxsteps = ts->max_steps;
    1054:   }
    1055:   if (maxtime ) {
    1057:     *maxtime  = ts->max_time;
    1058:   }
    1059:   return(0);
    1060: }

    1064: /*@
    1065:    TSSetDuration - Sets the maximum number of timesteps to use and
    1066:    maximum time for iteration.

    1068:    Collective on TS

    1070:    Input Parameters:
    1071: +  ts - the TS context obtained from TSCreate()
    1072: .  maxsteps - maximum number of iterations to use
    1073: -  maxtime - final time to iterate to

    1075:    Options Database Keys:
    1076: .  -ts_max_steps <maxsteps> - Sets maxsteps
    1077: .  -ts_max_time <maxtime> - Sets maxtime

    1079:    Notes:
    1080:    The default maximum number of iterations is 5000. Default time is 5.0

    1082:    Level: intermediate

    1084: .keywords: TS, timestep, set, maximum, iterations
    1085: @*/
    1086: PetscErrorCode PETSCTS_DLLEXPORT TSSetDuration(TS ts,PetscInt maxsteps,PetscReal maxtime)
    1087: {
    1090:   ts->max_steps = maxsteps;
    1091:   ts->max_time  = maxtime;
    1092:   return(0);
    1093: }

    1097: /*@
    1098:    TSSetSolution - Sets the initial solution vector
    1099:    for use by the TS routines.

    1101:    Collective on TS and Vec

    1103:    Input Parameters:
    1104: +  ts - the TS context obtained from TSCreate()
    1105: -  x - the solution vector

    1107:    Level: beginner

    1109: .keywords: TS, timestep, set, solution, initial conditions
    1110: @*/
    1111: PetscErrorCode PETSCTS_DLLEXPORT TSSetSolution(TS ts,Vec x)
    1112: {
    1116:   ts->vec_sol        = ts->vec_sol_always = x;
    1117:   return(0);
    1118: }

    1122: /*@
    1123:   TSDefaultRhsBC - The default boundary condition function which does nothing.

    1125:   Collective on TS

    1127:   Input Parameters:
    1128: + ts  - The TS context obtained from TSCreate()
    1129: . rhs - The Rhs
    1130: - ctx - The user-context

    1132:   Level: developer

    1134: .keywords: TS, Rhs, boundary conditions
    1135: @*/
    1136: PetscErrorCode PETSCTS_DLLEXPORT TSDefaultRhsBC(TS ts,  Vec rhs, void *ctx)
    1137: {
    1139:   return(0);
    1140: }

    1144: /*@C
    1145:   TSSetSystemMatrixBC - Sets the function which applies boundary conditions
    1146:   to the system matrix and preconditioner of each system.

    1148:   Collective on TS

    1150:   Input Parameters:
    1151: + ts   - The TS context obtained from TSCreate()
    1152: - func - The function

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

    1157: + A   - The current system matrix
    1158: . B   - The current preconditioner
    1159: - ctx - The user-context

    1161:   Level: intermediate

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

    1175: /*@
    1176:   TSDefaultSystemMatrixBC - The default boundary condition function which
    1177:   does nothing.

    1179:   Collective on TS

    1181:   Input Parameters:
    1182: + ts  - The TS context obtained from TSCreate()
    1183: . A   - The system matrix
    1184: . B   - The preconditioner
    1185: - ctx - The user-context

    1187:   Level: developer

    1189: .keywords: TS, System matrix, boundary conditions
    1190: @*/
    1191: PetscErrorCode PETSCTS_DLLEXPORT TSDefaultSystemMatrixBC(TS ts, Mat A, Mat B, void *ctx)
    1192: {
    1194:   return(0);
    1195: }

    1199: /*@C
    1200:   TSSetSolutionBC - Sets the function which applies boundary conditions
    1201:   to the solution of each system. This is necessary in nonlinear systems
    1202:   which time dependent boundary conditions.

    1204:   Collective on TS

    1206:   Input Parameters:
    1207: + ts   - The TS context obtained from TSCreate()
    1208: - func - The function

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

    1213: + sol - The current solution vector
    1214: - ctx - The user-context

    1216:   Level: intermediate

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

    1230: /*@
    1231:   TSDefaultSolutionBC - The default boundary condition function which
    1232:   does nothing.

    1234:   Collective on TS

    1236:   Input Parameters:
    1237: + ts  - The TS context obtained from TSCreate()
    1238: . sol - The solution
    1239: - ctx - The user-context

    1241:   Level: developer

    1243: .keywords: TS, solution, boundary conditions
    1244: @*/
    1245: PetscErrorCode PETSCTS_DLLEXPORT TSDefaultSolutionBC(TS ts, Vec sol, void *ctx)
    1246: {
    1248:   return(0);
    1249: }

    1253: /*@C
    1254:   TSSetPreStep - Sets the general-purpose function
    1255:   called once at the beginning of time stepping.

    1257:   Collective on TS

    1259:   Input Parameters:
    1260: + ts   - The TS context obtained from TSCreate()
    1261: - func - The function

    1263:   Calling sequence of func:
    1264: . func (TS ts);

    1266:   Level: intermediate

    1268: .keywords: TS, timestep
    1269: @*/
    1270: PetscErrorCode PETSCTS_DLLEXPORT TSSetPreStep(TS ts, PetscErrorCode (*func)(TS))
    1271: {
    1274:   ts->ops->prestep = func;
    1275:   return(0);
    1276: }

    1280: /*@
    1281:   TSDefaultPreStep - The default pre-stepping function which does nothing.

    1283:   Collective on TS

    1285:   Input Parameters:
    1286: . ts  - The TS context obtained from TSCreate()

    1288:   Level: developer

    1290: .keywords: TS, timestep
    1291: @*/
    1292: PetscErrorCode PETSCTS_DLLEXPORT TSDefaultPreStep(TS ts)
    1293: {
    1295:   return(0);
    1296: }

    1300: /*@C
    1301:   TSSetUpdate - Sets the general-purpose update function called
    1302:   at the beginning of every time step. This function can change
    1303:   the time step.

    1305:   Collective on TS

    1307:   Input Parameters:
    1308: + ts   - The TS context obtained from TSCreate()
    1309: - func - The function

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

    1314: + t   - The current time
    1315: - dt  - The current time step

    1317:   Level: intermediate

    1319: .keywords: TS, update, timestep
    1320: @*/
    1321: PetscErrorCode PETSCTS_DLLEXPORT TSSetUpdate(TS ts, PetscErrorCode (*func)(TS, PetscReal, PetscReal *))
    1322: {
    1325:   ts->ops->update = func;
    1326:   return(0);
    1327: }

    1331: /*@
    1332:   TSDefaultUpdate - The default update function which does nothing.

    1334:   Collective on TS

    1336:   Input Parameters:
    1337: + ts  - The TS context obtained from TSCreate()
    1338: - t   - The current time

    1340:   Output Parameters:
    1341: . dt  - The current time step

    1343:   Level: developer

    1345: .keywords: TS, update, timestep
    1346: @*/
    1347: PetscErrorCode PETSCTS_DLLEXPORT TSDefaultUpdate(TS ts, PetscReal t, PetscReal *dt)
    1348: {
    1350:   return(0);
    1351: }

    1355: /*@C
    1356:   TSSetPostStep - Sets the general-purpose function
    1357:   called once at the end of time stepping.

    1359:   Collective on TS

    1361:   Input Parameters:
    1362: + ts   - The TS context obtained from TSCreate()
    1363: - func - The function

    1365:   Calling sequence of func:
    1366: . func (TS ts);

    1368:   Level: intermediate

    1370: .keywords: TS, timestep
    1371: @*/
    1372: PetscErrorCode PETSCTS_DLLEXPORT TSSetPostStep(TS ts, PetscErrorCode (*func)(TS))
    1373: {
    1376:   ts->ops->poststep = func;
    1377:   return(0);
    1378: }

    1382: /*@
    1383:   TSDefaultPostStep - The default post-stepping function which does nothing.

    1385:   Collective on TS

    1387:   Input Parameters:
    1388: . ts  - The TS context obtained from TSCreate()

    1390:   Level: developer

    1392: .keywords: TS, timestep
    1393: @*/
    1394: PetscErrorCode PETSCTS_DLLEXPORT TSDefaultPostStep(TS ts)
    1395: {
    1397:   return(0);
    1398: }

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

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

    1408:    Collective on TS

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

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

    1421: +    ts - the TS context
    1422: .    steps - iteration number
    1423: .    time - current time
    1424: .    x - current iterate
    1425: -    mctx - [optional] monitoring context

    1427:    Notes:
    1428:    This routine adds an additional monitor to the list of monitors that
    1429:    already has been loaded.

    1431:    Level: intermediate

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

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

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

    1455:    Collective on TS

    1457:    Input Parameters:
    1458: .  ts - the TS context obtained from TSCreate()

    1460:    Notes:
    1461:    There is no way to remove a single, specific monitor.

    1463:    Level: intermediate

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

    1467: .seealso: TSDefaultMonitor(), TSSetMonitor()
    1468: @*/
    1469: PetscErrorCode PETSCTS_DLLEXPORT TSClearMonitor(TS ts)
    1470: {
    1472:   PetscInt       i;

    1476:   for (i=0; i<ts->numbermonitors; i++) {
    1477:     if (ts->mdestroy[i]) {
    1478:       (*ts->mdestroy[i])(ts->monitorcontext[i]);
    1479:     }
    1480:   }
    1481:   ts->numbermonitors = 0;
    1482:   return(0);
    1483: }

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

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

    1498: /*@
    1499:    TSStep - Steps the requested number of timesteps.

    1501:    Collective on TS

    1503:    Input Parameter:
    1504: .  ts - the TS context obtained from TSCreate()

    1506:    Output Parameters:
    1507: +  steps - number of iterations until termination
    1508: -  ptime - time until termination

    1510:    Level: beginner

    1512: .keywords: TS, timestep, solve

    1514: .seealso: TSCreate(), TSSetUp(), TSDestroy()
    1515: @*/
    1516: PetscErrorCode PETSCTS_DLLEXPORT TSStep(TS ts,PetscInt *steps,PetscReal *ptime)
    1517: {

    1522:   if (!ts->setupcalled) {
    1523:     TSSetUp(ts);
    1524:   }

    1526:   PetscLogEventBegin(TS_Step, ts, 0, 0, 0);
    1527:   (*ts->ops->prestep)(ts);
    1528:   (*ts->ops->step)(ts, steps, ptime);
    1529:   (*ts->ops->poststep)(ts);
    1530:   PetscLogEventEnd(TS_Step, ts, 0, 0, 0);

    1532:   if (!PetscPreLoadingOn) {
    1533:     TSViewFromOptions(ts,ts->name);
    1534:   }
    1535:   return(0);
    1536: }

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

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

    1555: /* ------------------------------------------------------------------------*/

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

    1563:    Collective on TS

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

    1571:    Output Parameter:
    1572: .  draw - the drawing context

    1574:    Options Database Key:
    1575: .  -ts_xmonitor - automatically sets line graph monitor

    1577:    Notes:
    1578:    Use TSLGMonitorDestroy() to destroy this line graph, not PetscDrawLGDestroy().

    1580:    Level: intermediate

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

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

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

    1593:   PetscDrawCreate(PETSC_COMM_SELF,host,label,x,y,m,n,&win);
    1594:   PetscDrawSetType(win,PETSC_DRAW_X);
    1595:   PetscDrawLGCreate(win,1,draw);
    1596:   PetscDrawLGIndicateDataPoints(*draw);

    1598:   PetscLogObjectParent(*draw,win);
    1599:   return(0);
    1600: }

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

    1611:   if (!monctx) {
    1612:     MPI_Comm    comm;
    1613:     PetscViewer viewer;

    1615:     PetscObjectGetComm((PetscObject)ts,&comm);
    1616:     viewer = PETSC_VIEWER_DRAW_(comm);
    1617:     PetscViewerDrawGetDrawLG(viewer,0,&lg);
    1618:   }

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

    1631: /*@C
    1632:    TSLGMonitorDestroy - Destroys a line graph context that was created
    1633:    with TSLGMonitorCreate().

    1635:    Collective on PetscDrawLG

    1637:    Input Parameter:
    1638: .  draw - the drawing context

    1640:    Level: intermediate

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

    1644: .seealso: TSLGMonitorCreate(),  TSSetMonitor(), TSLGMonitor();
    1645: @*/
    1646: PetscErrorCode PETSCTS_DLLEXPORT TSLGMonitorDestroy(PetscDrawLG drawlg)
    1647: {
    1648:   PetscDraw      draw;

    1652:   PetscDrawLGGetDraw(drawlg,&draw);
    1653:   PetscDrawDestroy(draw);
    1654:   PetscDrawLGDestroy(drawlg);
    1655:   return(0);
    1656: }

    1660: /*@
    1661:    TSGetTime - Gets the current time.

    1663:    Not Collective

    1665:    Input Parameter:
    1666: .  ts - the TS context obtained from TSCreate()

    1668:    Output Parameter:
    1669: .  t  - the current time

    1671:    Contributed by: Matthew Knepley

    1673:    Level: beginner

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

    1677: .keywords: TS, get, time
    1678: @*/
    1679: PetscErrorCode PETSCTS_DLLEXPORT TSGetTime(TS ts,PetscReal* t)
    1680: {
    1684:   *t = ts->ptime;
    1685:   return(0);
    1686: }

    1690: /*@C
    1691:    TSSetOptionsPrefix - Sets the prefix used for searching for all
    1692:    TS options in the database.

    1694:    Collective on TS

    1696:    Input Parameter:
    1697: +  ts     - The TS context
    1698: -  prefix - The prefix to prepend to all option names

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

    1705:    Contributed by: Matthew Knepley

    1707:    Level: advanced

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

    1711: .seealso: TSSetFromOptions()

    1713: @*/
    1714: PetscErrorCode PETSCTS_DLLEXPORT TSSetOptionsPrefix(TS ts,const char prefix[])
    1715: {

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

    1735: /*@C
    1736:    TSAppendOptionsPrefix - Appends to the prefix used for searching for all
    1737:    TS options in the database.

    1739:    Collective on TS

    1741:    Input Parameter:
    1742: +  ts     - The TS context
    1743: -  prefix - The prefix to prepend to all option names

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

    1750:    Contributed by: Matthew Knepley

    1752:    Level: advanced

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

    1756: .seealso: TSGetOptionsPrefix()

    1758: @*/
    1759: PetscErrorCode PETSCTS_DLLEXPORT TSAppendOptionsPrefix(TS ts,const char prefix[])
    1760: {

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

    1779: /*@C
    1780:    TSGetOptionsPrefix - Sets the prefix used for searching for all
    1781:    TS options in the database.

    1783:    Not Collective

    1785:    Input Parameter:
    1786: .  ts - The TS context

    1788:    Output Parameter:
    1789: .  prefix - A pointer to the prefix string used

    1791:    Contributed by: Matthew Knepley

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

    1796:    Level: intermediate

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

    1800: .seealso: TSAppendOptionsPrefix()
    1801: @*/
    1802: PetscErrorCode PETSCTS_DLLEXPORT TSGetOptionsPrefix(TS ts,const char *prefix[])
    1803: {

    1809:   PetscObjectGetOptionsPrefix((PetscObject)ts,prefix);
    1810:   return(0);
    1811: }

    1815: /*@C
    1816:    TSGetRHSMatrix - Returns the matrix A at the present timestep.

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

    1820:    Input Parameter:
    1821: .  ts  - The TS context obtained from TSCreate()

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

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

    1830:    Contributed by: Matthew Knepley

    1832:    Level: intermediate

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

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

    1838: @*/
    1839: PetscErrorCode PETSCTS_DLLEXPORT TSGetRHSMatrix(TS ts,Mat *A,Mat *M,void **ctx)
    1840: {
    1843:   if (A)   *A = ts->A;
    1844:   if (M)   *M = ts->B;
    1845:   if (ctx) *ctx = ts->jacP;
    1846:   return(0);
    1847: }

    1851: /*@C
    1852:    TSGetRHSJacobian - Returns the Jacobian J at the present timestep.

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

    1856:    Input Parameter:
    1857: .  ts  - The TS context obtained from TSCreate()

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

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

    1866:    Contributed by: Matthew Knepley

    1868:    Level: intermediate

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

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

    1879:   TSGetRHSMatrix(ts,J,M,ctx);
    1880:   return(0);
    1881: }

    1885: /*@C
    1886:    TSVecViewMonitor - Monitors progress of the TS solvers by calling
    1887:    VecView() for the solution at each timestep

    1889:    Collective on TS

    1891:    Input Parameters:
    1892: +  ts - the TS context
    1893: .  step - current time-step
    1894: .  ptime - current time
    1895: -  dummy - either a viewer or PETSC_NULL

    1897:    Level: intermediate

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

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

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