Actual source code: traj.c
petsc-3.13.6 2020-09-29
Report Typos and Errors

      1:  #include <petsc/private/tsimpl.h>
      2:  #include <petsc/private/tshistoryimpl.h>
      3:  #include <petscdm.h>

      5: PetscFunctionList TSTrajectoryList              = NULL;
      6: PetscBool         TSTrajectoryRegisterAllCalled = PETSC_FALSE;
      7: PetscClassId      TSTRAJECTORY_CLASSID;
      8: PetscLogEvent     TSTrajectory_Set, TSTrajectory_Get, TSTrajectory_GetVecs;

     10: /*@C
     11:   TSTrajectoryRegister - Adds a way of storing trajectories to the TS package

     13:   Not Collective

     15:   Input Parameters:
     16: + name        - the name of a new user-defined creation routine
     17: - create_func - the creation routine itself

     19:   Notes:
     20:   TSTrajectoryRegister() may be called multiple times to add several user-defined tses.

     22:   Level: developer

     24: .seealso: TSTrajectoryRegisterAll()
     25: @*/
     26: PetscErrorCode TSTrajectoryRegister(const char sname[],PetscErrorCode (*function)(TSTrajectory,TS))
     27: {

     31:   PetscFunctionListAdd(&TSTrajectoryList,sname,function);
     32:   return(0);
     33: }

     35: /*@
     36:   TSTrajectorySet - Sets a vector of state in the trajectory object

     38:   Collective on TSTrajectory

     40:   Input Parameters:
     41: + tj      - the trajectory object
     42: . ts      - the time stepper object (optional)
     43: . stepnum - the step number
     44: . time    - the current time
     45: - X       - the current solution

     47:   Level: developer

     49:   Notes: Usually one does not call this routine, it is called automatically during TSSolve()

     51: .seealso: TSTrajectorySetUp(), TSTrajectoryDestroy(), TSTrajectorySetType(), TSTrajectorySetVariableNames(), TSGetTrajectory(), TSTrajectoryGet(), TSTrajectoryGetVecs()
     52: @*/
     53: PetscErrorCode TSTrajectorySet(TSTrajectory tj,TS ts,PetscInt stepnum,PetscReal time,Vec X)
     54: {

     58:   if (!tj) return(0);
     64:   if (!tj->ops->set) SETERRQ1(PetscObjectComm((PetscObject)tj),PETSC_ERR_SUP,"TSTrajectory type %s",((PetscObject)tj)->type_name);
     65:   if (!tj->setupcalled) SETERRQ(PetscObjectComm((PetscObject)tj),PETSC_ERR_ORDER,"TSTrajectorySetUp should be called first");
     66:   if (tj->monitor) {
     67:     PetscViewerASCIIPrintf(tj->monitor,"TSTrajectorySet: stepnum %D, time %g (stages %D)\n",stepnum,(double)time,(PetscInt)!tj->solution_only);
     68:   }
     69:   PetscLogEventBegin(TSTrajectory_Set,tj,ts,0,0);
     70:   (*tj->ops->set)(tj,ts,stepnum,time,X);
     71:   PetscLogEventEnd(TSTrajectory_Set,tj,ts,0,0);
     72:   if (tj->usehistory) {
     73:     TSHistoryUpdate(tj->tsh,stepnum,time);
     74:   }
     75:   if (tj->lag.caching) tj->lag.Udotcached.time = PETSC_MIN_REAL;
     76:   return(0);
     77: }

     79: /*@
     80:   TSTrajectoryGetNumSteps - Return the number of steps registered in the TSTrajectory via TSTrajectorySet().

     82:   Not collective.

     84:   Input Parameters:
     85: . tj - the trajectory object

     87:   Output Parameter:
     88: . steps - the number of steps

     90:   Level: developer

     92: .seealso: TSTrajectorySet()
     93: @*/
     94: PetscErrorCode TSTrajectoryGetNumSteps(TSTrajectory tj, PetscInt *steps)
     95: {

    101:   TSHistoryGetNumSteps(tj->tsh,steps);
    102:   return(0);
    103: }

    105: /*@
    106:   TSTrajectoryGet - Updates the solution vector of a time stepper object by inquiring the TSTrajectory

    108:   Collective on TS

    110:   Input Parameters:
    111: + tj      - the trajectory object
    112: . ts      - the time stepper object
    113: - stepnum - the step number

    115:   Output Parameter:
    116: . time    - the time associated with the step number

    118:   Level: developer

    120:   Notes: Usually one does not call this routine, it is called automatically during TSSolve()

    122: .seealso: TSTrajectorySetUp(), TSTrajectoryDestroy(), TSTrajectorySetType(), TSTrajectorySetVariableNames(), TSGetTrajectory(), TSTrajectorySet(), TSTrajectoryGetVecs(), TSGetSolution()
    123: @*/
    124: PetscErrorCode TSTrajectoryGet(TSTrajectory tj,TS ts,PetscInt stepnum,PetscReal *time)
    125: {

    129:   if (!tj) SETERRQ(PetscObjectComm((PetscObject)ts),PETSC_ERR_ARG_WRONGSTATE,"TS solver did not save trajectory");
    134:   if (!tj->ops->get) SETERRQ1(PetscObjectComm((PetscObject)tj),PETSC_ERR_SUP,"TSTrajectory type %s",((PetscObject)tj)->type_name);
    135:   if (!tj->setupcalled) SETERRQ(PetscObjectComm((PetscObject)tj),PETSC_ERR_ORDER,"TSTrajectorySetUp should be called first");
    136:   if (stepnum < 0) SETERRQ(PetscObjectComm((PetscObject)tj),PETSC_ERR_PLIB,"Requesting negative step number");
    137:   if (tj->monitor) {
    138:     PetscViewerASCIIPrintf(tj->monitor,"TSTrajectoryGet: stepnum %D, stages %D\n",stepnum,(PetscInt)!tj->solution_only);
    139:     PetscViewerFlush(tj->monitor);
    140:   }
    141:   PetscLogEventBegin(TSTrajectory_Get,tj,ts,0,0);
    142:   (*tj->ops->get)(tj,ts,stepnum,time);
    143:   PetscLogEventEnd(TSTrajectory_Get,tj,ts,0,0);
    144:   return(0);
    145: }

    147: /*@
    148:   TSTrajectoryGetVecs - Reconstructs the vector of state and its time derivative using information from the TSTrajectory and, possibly, from the TS

    150:   Collective on TS

    152:   Input Parameters:
    153: + tj      - the trajectory object
    154: . ts      - the time stepper object (optional)
    155: - stepnum - the requested step number

    157:   Input/Output Parameters:
    158: . time - the time associated with the step number

    160:   Output Parameters:
    161: + U       - state vector (can be NULL)
    162: - Udot    - time derivative of state vector (can be NULL)

    164:   Level: developer

    166:   Notes: If the step number is PETSC_DECIDE, the time argument is used to inquire the trajectory.
    167:          If the requested time does not match any in the trajectory, Lagrangian interpolations are returned.

    169: .seealso: TSTrajectorySetUp(), TSTrajectoryDestroy(), TSTrajectorySetType(), TSTrajectorySetVariableNames(), TSGetTrajectory(), TSTrajectorySet(), TSTrajectoryGet()
    170: @*/
    171: PetscErrorCode TSTrajectoryGetVecs(TSTrajectory tj,TS ts,PetscInt stepnum,PetscReal *time,Vec U,Vec Udot)
    172: {

    176:   if (!tj) SETERRQ(PetscObjectComm((PetscObject)ts),PETSC_ERR_ARG_WRONGSTATE,"TS solver did not save trajectory");
    183:   if (!U && !Udot) return(0);
    184:   if (!tj->setupcalled) SETERRQ(PetscObjectComm((PetscObject)tj),PETSC_ERR_ORDER,"TSTrajectorySetUp should be called first");
    185:   PetscLogEventBegin(TSTrajectory_GetVecs,tj,ts,0,0);
    186:   if (tj->monitor) {
    187:     PetscInt pU,pUdot;
    188:     pU    = U ? 1 : 0;
    189:     pUdot = Udot ? 1 : 0;
    190:     PetscViewerASCIIPrintf(tj->monitor,"Requested by GetVecs %D %D: stepnum %D, time %g\n",pU,pUdot,stepnum,(double)*time);
    191:     PetscViewerFlush(tj->monitor);
    192:   }
    193:   if (U && tj->lag.caching) {
    194:     PetscObjectId    id;
    195:     PetscObjectState state;

    197:     PetscObjectStateGet((PetscObject)U,&state);
    198:     PetscObjectGetId((PetscObject)U,&id);
    199:     if (stepnum == PETSC_DECIDE) {
    200:       if (id == tj->lag.Ucached.id && *time == tj->lag.Ucached.time && state == tj->lag.Ucached.state) U = NULL;
    201:     } else {
    202:       if (id == tj->lag.Ucached.id && stepnum == tj->lag.Ucached.step && state == tj->lag.Ucached.state) U = NULL;
    203:     }
    204:     if (tj->monitor && !U) {
    205:       PetscViewerASCIIPushTab(tj->monitor);
    206:       PetscViewerASCIIPrintf(tj->monitor,"State vector cached\n");
    207:       PetscViewerASCIIPopTab(tj->monitor);
    208:       PetscViewerFlush(tj->monitor);
    209:     }
    210:   }
    211:   if (Udot && tj->lag.caching) {
    212:     PetscObjectId    id;
    213:     PetscObjectState state;

    215:     PetscObjectStateGet((PetscObject)Udot,&state);
    216:     PetscObjectGetId((PetscObject)Udot,&id);
    217:     if (stepnum == PETSC_DECIDE) {
    218:       if (id == tj->lag.Udotcached.id && *time == tj->lag.Udotcached.time && state == tj->lag.Udotcached.state) Udot = NULL;
    219:     } else {
    220:       if (id == tj->lag.Udotcached.id && stepnum == tj->lag.Udotcached.step && state == tj->lag.Udotcached.state) Udot = NULL;
    221:     }
    222:     if (tj->monitor && !Udot) {
    223:       PetscViewerASCIIPushTab(tj->monitor);
    224:       PetscViewerASCIIPrintf(tj->monitor,"Derivative vector cached\n");
    225:       PetscViewerASCIIPopTab(tj->monitor);
    226:       PetscViewerFlush(tj->monitor);
    227:     }
    228:   }
    229:   if (!U && !Udot) {
    230:     PetscLogEventEnd(TSTrajectory_GetVecs,tj,ts,0,0);
    231:     return(0);
    232:   }

    234:   if (stepnum == PETSC_DECIDE || Udot) { /* reverse search for requested time in TSHistory */
    235:     if (tj->monitor) {
    236:       PetscViewerASCIIPushTab(tj->monitor);
    237:     }
    238:     /* cached states will be updated in the function */
    239:     TSTrajectoryReconstruct_Private(tj,ts,*time,U,Udot);
    240:     if (tj->monitor) {
    241:       PetscViewerASCIIPopTab(tj->monitor);
    242:       PetscViewerFlush(tj->monitor);
    243:     }
    244:   } else if (U) { /* we were asked to load from stepnum, use TSTrajectoryGet */
    245:     TS  fakets = ts;
    246:     Vec U2;

    248:     /* use a fake TS if ts is missing */
    249:     if (!ts) {
    250:       PetscObjectQuery((PetscObject)tj,"__fake_ts",(PetscObject*)&fakets);
    251:       if (!fakets) {
    252:         TSCreate(PetscObjectComm((PetscObject)tj),&fakets);
    253:         PetscObjectCompose((PetscObject)tj,"__fake_ts",(PetscObject)fakets);
    254:         PetscObjectDereference((PetscObject)fakets);
    255:         VecDuplicate(U,&U2);
    256:         TSSetSolution(fakets,U2);
    257:         PetscObjectDereference((PetscObject)U2);
    258:       }
    259:     }
    260:     TSTrajectoryGet(tj,fakets,stepnum,time);
    261:     TSGetSolution(fakets,&U2);
    262:     VecCopy(U2,U);
    263:     PetscObjectStateGet((PetscObject)U,&tj->lag.Ucached.state);
    264:     PetscObjectGetId((PetscObject)U,&tj->lag.Ucached.id);
    265:     tj->lag.Ucached.time = *time;
    266:     tj->lag.Ucached.step = stepnum;
    267:   }
    268:   PetscLogEventEnd(TSTrajectory_GetVecs,tj,ts,0,0);
    269:   return(0);
    270: }

    272: /*@C
    273:    TSTrajectoryViewFromOptions - View from Options

    275:    Collective on TSTrajectory

    277:    Input Parameters:
    278: +  A - the TSTrajectory context
    279: .  obj - Optional object
    280: -  name - command line option

    282:    Level: intermediate
    283: .seealso:  TSTrajectory, TSTrajectoryView, PetscObjectViewFromOptions(), TSTrajectoryCreate()
    284: @*/
    285: PetscErrorCode  TSTrajectoryViewFromOptions(TSTrajectory A,PetscObject obj,const char name[])
    286: {

    291:   PetscObjectViewFromOptions((PetscObject)A,obj,name);
    292:   return(0);
    293: }

    295: /*@C
    296:     TSTrajectoryView - Prints information about the trajectory object

    298:     Collective on TSTrajectory

    300:     Input Parameters:
    301: +   tj - the TSTrajectory context obtained from TSTrajectoryCreate()
    302: -   viewer - visualization context

    304:     Options Database Key:
    305: .   -ts_trajectory_view - calls TSTrajectoryView() at end of TSAdjointStep()

    307:     Notes:
    308:     The available visualization contexts include
    309: +     PETSC_VIEWER_STDOUT_SELF - standard output (default)
    310: -     PETSC_VIEWER_STDOUT_WORLD - synchronized standard
    311:          output where only the first processor opens
    312:          the file.  All other processors send their
    313:          data to the first processor to print.

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

    318:     Level: developer

    320: .seealso: PetscViewerASCIIOpen()
    321: @*/
    322: PetscErrorCode  TSTrajectoryView(TSTrajectory tj,PetscViewer viewer)
    323: {
    325:   PetscBool      iascii;

    329:   if (!viewer) {
    330:     PetscViewerASCIIGetStdout(PetscObjectComm((PetscObject)tj),&viewer);
    331:   }

    335:   PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&iascii);
    336:   if (iascii) {
    337:     PetscObjectPrintClassNamePrefixType((PetscObject)tj,viewer);
    338:     PetscViewerASCIIPrintf(viewer,"  total number of recomputations for adjoint calculation = %D\n",tj->recomps);
    339:     PetscViewerASCIIPrintf(viewer,"  disk checkpoint reads = %D\n",tj->diskreads);
    340:     PetscViewerASCIIPrintf(viewer,"  disk checkpoint writes = %D\n",tj->diskwrites);
    341:     if (tj->ops->view) {
    342:       PetscViewerASCIIPushTab(viewer);
    343:       (*tj->ops->view)(tj,viewer);
    344:       PetscViewerASCIIPopTab(viewer);
    345:     }
    346:   }
    347:   return(0);
    348: }

    350: /*@C
    351:    TSTrajectorySetVariableNames - Sets the name of each component in the solution vector so that it may be saved with the trajectory

    353:    Collective on TSTrajectory

    355:    Input Parameters:
    356: +  tr - the trajectory context
    357: -  names - the names of the components, final string must be NULL

    359:    Level: intermediate

    361:    Note: Fortran interface is not possible because of the string array argument

    363: .seealso: TSTrajectory, TSGetTrajectory()
    364: @*/
    365: PetscErrorCode  TSTrajectorySetVariableNames(TSTrajectory ctx,const char * const *names)
    366: {
    367:   PetscErrorCode    ierr;

    372:   PetscStrArrayDestroy(&ctx->names);
    373:   PetscStrArrayallocpy(names,&ctx->names);
    374:   return(0);
    375: }

    377: /*@C
    378:    TSTrajectorySetTransform - Solution vector will be transformed by provided function before being saved to disk

    380:    Collective on TSLGCtx

    382:    Input Parameters:
    383: +  tj - the TSTrajectory context
    384: .  transform - the transform function
    385: .  destroy - function to destroy the optional context
    386: -  ctx - optional context used by transform function

    388:    Level: intermediate

    390: .seealso:  TSTrajectorySetVariableNames(), TSTrajectory, TSMonitorLGSetTransform()
    391: @*/
    392: PetscErrorCode  TSTrajectorySetTransform(TSTrajectory tj,PetscErrorCode (*transform)(void*,Vec,Vec*),PetscErrorCode (*destroy)(void*),void *tctx)
    393: {
    396:   tj->transform        = transform;
    397:   tj->transformdestroy = destroy;
    398:   tj->transformctx     = tctx;
    399:   return(0);
    400: }

    402: /*@
    403:   TSTrajectoryCreate - This function creates an empty trajectory object used to store the time dependent solution of an ODE/DAE

    405:   Collective

    407:   Input Parameter:
    408: . comm - the communicator

    410:   Output Parameter:
    411: . tj   - the trajectory object

    413:   Level: developer

    415:   Notes:
    416:     Usually one does not call this routine, it is called automatically when one calls TSSetSaveTrajectory().

    418: .seealso: TSTrajectorySetUp(), TSTrajectoryDestroy(), TSTrajectorySetType(), TSTrajectorySetVariableNames(), TSGetTrajectory(), TSTrajectorySetKeepFiles()
    419: @*/
    420: PetscErrorCode  TSTrajectoryCreate(MPI_Comm comm,TSTrajectory *tj)
    421: {
    422:   TSTrajectory   t;

    427:   *tj = NULL;
    428:   TSInitializePackage();

    430:   PetscHeaderCreate(t,TSTRAJECTORY_CLASSID,"TSTrajectory","Time stepping","TS",comm,TSTrajectoryDestroy,TSTrajectoryView);
    431:   t->setupcalled = PETSC_FALSE;
    432:   TSHistoryCreate(comm,&t->tsh);

    434:   t->lag.order            = 1;
    435:   t->lag.L                = NULL;
    436:   t->lag.T                = NULL;
    437:   t->lag.W                = NULL;
    438:   t->lag.WW               = NULL;
    439:   t->lag.TW               = NULL;
    440:   t->lag.TT               = NULL;
    441:   t->lag.caching          = PETSC_TRUE;
    442:   t->lag.Ucached.id       = 0;
    443:   t->lag.Ucached.state    = -1;
    444:   t->lag.Ucached.time     = PETSC_MIN_REAL;
    445:   t->lag.Ucached.step     = PETSC_MAX_INT;
    446:   t->lag.Udotcached.id    = 0;
    447:   t->lag.Udotcached.state = -1;
    448:   t->lag.Udotcached.time  = PETSC_MIN_REAL;
    449:   t->lag.Udotcached.step  = PETSC_MAX_INT;
    450:   t->adjoint_solve_mode   = PETSC_TRUE;
    451:   t->solution_only        = PETSC_FALSE;
    452:   t->keepfiles            = PETSC_FALSE;
    453:   t->usehistory           = PETSC_TRUE;
    454:   *tj  = t;
    455:   TSTrajectorySetFiletemplate(t,"TS-%06D.bin");
    456:   return(0);
    457: }

    459: /*@C
    460:   TSTrajectorySetType - Sets the storage method to be used as in a trajectory

    462:   Collective on TS

    464:   Input Parameters:
    465: + tj   - the TSTrajectory context
    466: . ts   - the TS context
    467: - type - a known method

    469:   Options Database Command:
    470: . -ts_trajectory_type <type> - Sets the method; use -help for a list of available methods (for instance, basic)

    472:    Level: developer

    474: .seealso: TS, TSTrajectoryCreate(), TSTrajectorySetFromOptions(), TSTrajectoryDestroy(), TSTrajectoryGetType()

    476: @*/
    477: PetscErrorCode  TSTrajectorySetType(TSTrajectory tj,TS ts,TSTrajectoryType type)
    478: {
    479:   PetscErrorCode (*r)(TSTrajectory,TS);
    480:   PetscBool      match;

    485:   PetscObjectTypeCompare((PetscObject)tj,type,&match);
    486:   if (match) return(0);

    488:   PetscFunctionListFind(TSTrajectoryList,type,&r);
    489:   if (!r) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_UNKNOWN_TYPE,"Unknown TSTrajectory type: %s",type);
    490:   if (tj->ops->destroy) {
    491:     (*(tj)->ops->destroy)(tj);

    493:     tj->ops->destroy = NULL;
    494:   }
    495:   PetscMemzero(tj->ops,sizeof(*tj->ops));

    497:   PetscObjectChangeTypeName((PetscObject)tj,type);
    498:   (*r)(tj,ts);
    499:   return(0);
    500: }

    502: /*@C
    503:   TSTrajectoryGetType - Gets the trajectory type

    505:   Collective on TS

    507:   Input Parameters:
    508: + tj   - the TSTrajectory context
    509: - ts   - the TS context

    511:   Output Parameters:
    512: . type - a known method

    514:   Level: developer

    516: .seealso: TS, TSTrajectoryCreate(), TSTrajectorySetFromOptions(), TSTrajectoryDestroy(), TSTrajectorySetType()

    518: @*/
    519: PetscErrorCode TSTrajectoryGetType(TSTrajectory tj,TS ts,TSTrajectoryType *type)
    520: {
    523:   if (type) *type = ((PetscObject)tj)->type_name;
    524:   return(0);
    525: }

    527: PETSC_EXTERN PetscErrorCode TSTrajectoryCreate_Basic(TSTrajectory,TS);
    528: PETSC_EXTERN PetscErrorCode TSTrajectoryCreate_Singlefile(TSTrajectory,TS);
    529: PETSC_EXTERN PetscErrorCode TSTrajectoryCreate_Memory(TSTrajectory,TS);
    530: PETSC_EXTERN PetscErrorCode TSTrajectoryCreate_Visualization(TSTrajectory,TS);

    532: /*@C
    533:   TSTrajectoryRegisterAll - Registers all of the trajectory storage schecmes in the TS package.

    535:   Not Collective

    537:   Level: developer

    539: .seealso: TSTrajectoryRegister()
    540: @*/
    541: PetscErrorCode  TSTrajectoryRegisterAll(void)
    542: {

    546:   if (TSTrajectoryRegisterAllCalled) return(0);
    547:   TSTrajectoryRegisterAllCalled = PETSC_TRUE;

    549:   TSTrajectoryRegister(TSTRAJECTORYBASIC,TSTrajectoryCreate_Basic);
    550:   TSTrajectoryRegister(TSTRAJECTORYSINGLEFILE,TSTrajectoryCreate_Singlefile);
    551:   TSTrajectoryRegister(TSTRAJECTORYMEMORY,TSTrajectoryCreate_Memory);
    552:   TSTrajectoryRegister(TSTRAJECTORYVISUALIZATION,TSTrajectoryCreate_Visualization);
    553:   return(0);
    554: }

    556: /*@
    557:    TSTrajectoryReset - Resets a trajectory context

    559:    Collective on TSTrajectory

    561:    Input Parameter:
    562: .  tj - the TSTrajectory context obtained from TSTrajectoryCreate()

    564:    Level: developer

    566: .seealso: TSTrajectoryCreate(), TSTrajectorySetUp()
    567: @*/
    568: PetscErrorCode TSTrajectoryReset(TSTrajectory tj)
    569: {

    573:   if (!tj) return(0);
    575:   if (tj->ops->reset) {
    576:     (*tj->ops->reset)(tj);
    577:   }
    578:   PetscFree(tj->dirfiletemplate);
    579:   TSHistoryDestroy(&tj->tsh);
    580:   TSHistoryCreate(PetscObjectComm((PetscObject)tj),&tj->tsh);
    581:   tj->setupcalled = PETSC_FALSE;
    582:   return(0);
    583: }

    585: /*@
    586:    TSTrajectoryDestroy - Destroys a trajectory context

    588:    Collective on TSTrajectory

    590:    Input Parameter:
    591: .  tj - the TSTrajectory context obtained from TSTrajectoryCreate()

    593:    Level: developer

    595: .seealso: TSTrajectoryCreate(), TSTrajectorySetUp()
    596: @*/
    597: PetscErrorCode TSTrajectoryDestroy(TSTrajectory *tj)
    598: {

    602:   if (!*tj) return(0);
    604:   if (--((PetscObject)(*tj))->refct > 0) {*tj = 0; return(0);}

    606:   TSTrajectoryReset(*tj);
    607:   TSHistoryDestroy(&(*tj)->tsh);
    608:   VecDestroyVecs((*tj)->lag.order+1,&(*tj)->lag.W);
    609:   PetscFree5((*tj)->lag.L,(*tj)->lag.T,(*tj)->lag.WW,(*tj)->lag.TT,(*tj)->lag.TW);
    610:   VecDestroy(&(*tj)->U);
    611:   VecDestroy(&(*tj)->Udot);

    613:   if ((*tj)->transformdestroy) {(*(*tj)->transformdestroy)((*tj)->transformctx);}
    614:   if ((*tj)->ops->destroy) {(*(*tj)->ops->destroy)((*tj));}
    615:   if (!((*tj)->keepfiles)) {
    616:     PetscMPIInt rank;
    617:     MPI_Comm    comm;

    619:     PetscObjectGetComm((PetscObject)(*tj),&comm);
    620:     MPI_Comm_rank(comm,&rank);
    621:     if (!rank && (*tj)->dirname) { /* we own the directory, so we run PetscRMTree on it */
    622:       PetscRMTree((*tj)->dirname);
    623:     }
    624:   }
    625:   PetscStrArrayDestroy(&(*tj)->names);
    626:   PetscFree((*tj)->dirname);
    627:   PetscFree((*tj)->filetemplate);
    628:   PetscHeaderDestroy(tj);
    629:   return(0);
    630: }

    632: /*
    633:   TSTrajectorySetTypeFromOptions_Private - Sets the type of ts from user options.

    635:   Collective on TSTrajectory

    637:   Input Parameter:
    638: + tj - the TSTrajectory context
    639: - ts - the TS context

    641:   Options Database Keys:
    642: . -ts_trajectory_type <type> - TSTRAJECTORYBASIC, TSTRAJECTORYMEMORY, TSTRAJECTORYSINGLEFILE, TSTRAJECTORYVISUALIZATION

    644:   Level: developer

    646: .seealso: TSTrajectorySetFromOptions(), TSTrajectorySetType()
    647: */
    648: static PetscErrorCode TSTrajectorySetTypeFromOptions_Private(PetscOptionItems *PetscOptionsObject,TSTrajectory tj,TS ts)
    649: {
    650:   PetscBool      opt;
    651:   const char     *defaultType;
    652:   char           typeName[256];

    656:   if (((PetscObject)tj)->type_name) defaultType = ((PetscObject)tj)->type_name;
    657:   else defaultType = TSTRAJECTORYBASIC;

    659:   TSTrajectoryRegisterAll();
    660:   PetscOptionsFList("-ts_trajectory_type","TSTrajectory method","TSTrajectorySetType",TSTrajectoryList,defaultType,typeName,256,&opt);
    661:   if (opt) {
    662:     TSTrajectorySetType(tj,ts,typeName);
    663:   } else {
    664:     TSTrajectorySetType(tj,ts,defaultType);
    665:   }
    666:   return(0);
    667: }

    669: /*@
    670:    TSTrajectorySetUseHistory - Use TSHistory in TSTrajectory

    672:    Collective on TSTrajectory

    674:    Input Arguments:
    675: +  tj - the TSTrajectory context
    676: -  flg - PETSC_TRUE to save, PETSC_FALSE to disable

    678:    Options Database Keys:
    679: .  -ts_trajectory_use_history - have it use TSHistory

    681:    Level: advanced

    683: .seealso: TSTrajectoryCreate(), TSTrajectoryDestroy(), TSTrajectorySetUp()
    684: @*/
    685: PetscErrorCode TSTrajectorySetUseHistory(TSTrajectory tj,PetscBool flg)
    686: {
    690:   tj->usehistory = flg;
    691:   return(0);
    692: }

    694: /*@
    695:    TSTrajectorySetMonitor - Monitor the schedules generated by the checkpointing controller

    697:    Collective on TSTrajectory

    699:    Input Arguments:
    700: +  tj - the TSTrajectory context
    701: -  flg - PETSC_TRUE to active a monitor, PETSC_FALSE to disable

    703:    Options Database Keys:
    704: .  -ts_trajectory_monitor - print TSTrajectory information

    706:    Level: developer

    708: .seealso: TSTrajectoryCreate(), TSTrajectoryDestroy(), TSTrajectorySetUp()
    709: @*/
    710: PetscErrorCode TSTrajectorySetMonitor(TSTrajectory tj,PetscBool flg)
    711: {
    715:   if (flg) tj->monitor = PETSC_VIEWER_STDOUT_(PetscObjectComm((PetscObject)tj));
    716:   else tj->monitor = NULL;
    717:   return(0);
    718: }

    720: /*@
    721:    TSTrajectorySetKeepFiles - Keep the files generated by the TSTrajectory

    723:    Collective on TSTrajectory

    725:    Input Arguments:
    726: +  tj - the TSTrajectory context
    727: -  flg - PETSC_TRUE to save, PETSC_FALSE to disable

    729:    Options Database Keys:
    730: .  -ts_trajectory_keep_files - have it keep the files

    732:    Notes:
    733:     By default the TSTrajectory used for adjoint computations, TSTRAJECTORYBASIC, removes the files it generates at the end of the run. This causes the files to be kept.

    735:    Level: advanced

    737: .seealso: TSTrajectoryCreate(), TSTrajectoryDestroy(), TSTrajectorySetUp(), TSTrajectorySetMonitor()
    738: @*/
    739: PetscErrorCode TSTrajectorySetKeepFiles(TSTrajectory tj,PetscBool flg)
    740: {
    744:   tj->keepfiles = flg;
    745:   return(0);
    746: }

    748: /*@C
    749:    TSTrajectorySetDirname - Specify the name of the directory where disk checkpoints are stored.

    751:    Collective on TSTrajectory

    753:    Input Arguments:
    754: +  tj      - the TSTrajectory context
    755: -  dirname - the directory name

    757:    Options Database Keys:
    758: .  -ts_trajectory_dirname - set the directory name

    760:    Notes:
    761:     The final location of the files is determined by dirname/filetemplate where filetemplate was provided by TSTrajectorySetFiletemplate()

    763:    Level: developer

    765: .seealso: TSTrajectorySetFiletemplate(),TSTrajectorySetUp()
    766: @*/
    767: PetscErrorCode TSTrajectorySetDirname(TSTrajectory tj,const char dirname[])
    768: {
    770:   PetscBool      flg;

    774:   PetscStrcmp(tj->dirname,dirname,&flg);
    775:   if (!flg && tj->dirfiletemplate) {
    776:     SETERRQ(PetscObjectComm((PetscObject)tj),PETSC_ERR_ARG_WRONGSTATE,"Cannot set directoryname after TSTrajectory has been setup");
    777:   }
    778:   PetscFree(tj->dirname);
    779:   PetscStrallocpy(dirname,&tj->dirname);
    780:   return(0);
    781: }

    783: /*@C
    784:    TSTrajectorySetFiletemplate - Specify the name template for the files storing checkpoints.

    786:    Collective on TSTrajectory

    788:    Input Arguments:
    789: +  tj      - the TSTrajectory context
    790: -  filetemplate - the template

    792:    Options Database Keys:
    793: .  -ts_trajectory_file_template - set the file name template

    795:    Notes:
    796:     The name template should be of the form, for example filename-%06D.bin It should not begin with a leading /

    798:    The final location of the files is determined by dirname/filetemplate where dirname was provided by TSTrajectorySetDirname(). The %06D is replaced by the
    799:    timestep counter

    801:    Level: developer

    803: .seealso: TSTrajectorySetDirname(),TSTrajectorySetUp()
    804: @*/
    805: PetscErrorCode TSTrajectorySetFiletemplate(TSTrajectory tj,const char filetemplate[])
    806: {
    808:   const char     *ptr,*ptr2;

    812:   if (tj->dirfiletemplate) SETERRQ(PetscObjectComm((PetscObject)tj),PETSC_ERR_ARG_WRONGSTATE,"Cannot set filetemplate after TSTrajectory has been setup");

    814:   if (!filetemplate[0]) SETERRQ(PetscObjectComm((PetscObject)tj),PETSC_ERR_USER,"-ts_trajectory_file_template requires a file name template, e.g. filename-%%06D.bin");
    815:   /* Do some cursory validation of the input. */
    816:   PetscStrstr(filetemplate,"%",(char**)&ptr);
    817:   if (!ptr) SETERRQ(PetscObjectComm((PetscObject)tj),PETSC_ERR_USER,"-ts_trajectory_file_template requires a file name template, e.g. filename-%%06D.bin");
    818:   for (ptr++; ptr && *ptr; ptr++) {
    819:     PetscStrchr("DdiouxX",*ptr,(char**)&ptr2);
    820:     if (!ptr2 && (*ptr < '0' || '9' < *ptr)) SETERRQ(PetscObjectComm((PetscObject)tj),PETSC_ERR_USER,"Invalid file template argument to -ts_trajectory_file_template, should look like filename-%%06D.bin");
    821:     if (ptr2) break;
    822:   }
    823:   PetscFree(tj->filetemplate);
    824:   PetscStrallocpy(filetemplate,&tj->filetemplate);
    825:   return(0);
    826: }

    828: /*@
    829:    TSTrajectorySetFromOptions - Sets various TSTrajectory parameters from user options.

    831:    Collective on TSTrajectory

    833:    Input Parameter:
    834: +  tj - the TSTrajectory context obtained from TSTrajectoryCreate()
    835: -  ts - the TS context

    837:    Options Database Keys:
    838: +  -ts_trajectory_type <type> - TSTRAJECTORYBASIC, TSTRAJECTORYMEMORY, TSTRAJECTORYSINGLEFILE, TSTRAJECTORYVISUALIZATION
    839: .  -ts_trajectory_keep_files <true,false> - keep the files generated by the code after the program ends. This is true by default for TSTRAJECTORYSINGLEFILE, TSTRAJECTORYVISUALIZATION
    840: -  -ts_trajectory_monitor - print TSTrajectory information

    842:    Level: developer

    844:    Notes:
    845:     This is not normally called directly by users

    847: .seealso: TSSetSaveTrajectory(), TSTrajectorySetUp()
    848: @*/
    849: PetscErrorCode  TSTrajectorySetFromOptions(TSTrajectory tj,TS ts)
    850: {
    851:   PetscBool      set,flg;
    852:   char           dirname[PETSC_MAX_PATH_LEN],filetemplate[PETSC_MAX_PATH_LEN];

    858:   PetscObjectOptionsBegin((PetscObject)tj);
    859:   TSTrajectorySetTypeFromOptions_Private(PetscOptionsObject,tj,ts);
    860:   PetscOptionsBool("-ts_trajectory_use_history","Turn on/off usage of TSHistory",NULL,tj->usehistory,&tj->usehistory,NULL);
    861:   PetscOptionsBool("-ts_trajectory_monitor","Print checkpointing schedules","TSTrajectorySetMonitor",tj->monitor ? PETSC_TRUE:PETSC_FALSE,&flg,&set);
    862:   if (set) {TSTrajectorySetMonitor(tj,flg);}
    863:   PetscOptionsInt("-ts_trajectory_reconstruction_order","Interpolation order for reconstruction",NULL,tj->lag.order,&tj->lag.order,NULL);
    864:   PetscOptionsBool("-ts_trajectory_reconstruction_caching","Turn on/off caching of TSTrajectoryGetVecs input",NULL,tj->lag.caching,&tj->lag.caching,NULL);
    865:   PetscOptionsBool("-ts_trajectory_adjointmode","Instruct the trajectory that will be used in a TSAdjointSolve()",NULL,tj->adjoint_solve_mode,&tj->adjoint_solve_mode,NULL);
    866:   PetscOptionsBool("-ts_trajectory_solution_only","Checkpoint solution only","TSTrajectorySetSolutionOnly",tj->solution_only,&tj->solution_only,NULL);
    867:   PetscOptionsBool("-ts_trajectory_keep_files","Keep any trajectory files generated during the run","TSTrajectorySetKeepFiles",tj->keepfiles,&flg,&set);
    868:   if (set) {TSTrajectorySetKeepFiles(tj,flg);}

    870:   PetscOptionsString("-ts_trajectory_dirname","Directory name for TSTrajectory file","TSTrajectorySetDirname",0,dirname,PETSC_MAX_PATH_LEN-14,&set);
    871:   if (set) {
    872:     TSTrajectorySetDirname(tj,dirname);
    873:   }

    875:   PetscOptionsString("-ts_trajectory_file_template","Template for TSTrajectory file name, use filename-%06D.bin","TSTrajectorySetFiletemplate",0,filetemplate,PETSC_MAX_PATH_LEN,&set);
    876:   if (set) {
    877:     TSTrajectorySetFiletemplate(tj,filetemplate);
    878:   }

    880:   /* Handle specific TSTrajectory options */
    881:   if (tj->ops->setfromoptions) {
    882:     (*tj->ops->setfromoptions)(PetscOptionsObject,tj);
    883:   }
    884:   PetscOptionsEnd();
    885:   return(0);
    886: }

    888: /*@
    889:    TSTrajectorySetUp - Sets up the internal data structures, e.g. stacks, for the later use
    890:    of a TS trajectory.

    892:    Collective on TS

    894:    Input Parameter:
    895: +  ts - the TS context obtained from TSCreate()
    896: -  tj - the TS trajectory context

    898:    Level: developer

    900: .seealso: TSSetSaveTrajectory(), TSTrajectoryCreate(), TSTrajectoryDestroy()
    901: @*/
    902: PetscErrorCode  TSTrajectorySetUp(TSTrajectory tj,TS ts)
    903: {
    905:   size_t         s1,s2;

    908:   if (!tj) return(0);
    911:   if (tj->setupcalled) return(0);

    913:   if (!((PetscObject)tj)->type_name) {
    914:     TSTrajectorySetType(tj,ts,TSTRAJECTORYBASIC);
    915:   }
    916:   if (tj->ops->setup) {
    917:     (*tj->ops->setup)(tj,ts);
    918:   }

    920:   tj->setupcalled = PETSC_TRUE;

    922:   /* Set the counters to zero */
    923:   tj->recomps    = 0;
    924:   tj->diskreads  = 0;
    925:   tj->diskwrites = 0;
    926:   PetscStrlen(tj->dirname,&s1);
    927:   PetscStrlen(tj->filetemplate,&s2);
    928:   PetscFree(tj->dirfiletemplate);
    929:   PetscMalloc((s1 + s2 + 10)*sizeof(char),&tj->dirfiletemplate);
    930:   PetscSNPrintf(tj->dirfiletemplate,s1+s2+10,"%s/%s",tj->dirname,tj->filetemplate);
    931:   return(0);
    932: }

    934: /*@
    935:    TSTrajectorySetSolutionOnly - Tells the trajectory to store just the solution, and not any intermediate stage also.

    937:    Collective on TSTrajectory

    939:    Input Parameter:
    940: +  tj  - the TS trajectory context
    941: -  flg - the boolean flag

    943:    Level: developer

    945: .seealso: TSSetSaveTrajectory(), TSTrajectoryCreate(), TSTrajectoryDestroy(), TSTrajectoryGetSolutionOnly()
    946: @*/
    947: PetscErrorCode TSTrajectorySetSolutionOnly(TSTrajectory tj,PetscBool solution_only)
    948: {
    952:   tj->solution_only = solution_only;
    953:   return(0);
    954: }

    956: /*@
    957:    TSTrajectoryGetSolutionOnly - Gets the value set with TSTrajectorySetSolutionOnly.

    959:    Logically collective on TSTrajectory

    961:    Input Parameter:
    962: .  tj  - the TS trajectory context

    964:    Output Parameter:
    965: -  flg - the boolean flag

    967:    Level: developer

    969: .seealso: TSSetSaveTrajectory(), TSTrajectoryCreate(), TSTrajectoryDestroy(), TSTrajectorySetSolutionOnly()
    970: @*/
    971: PetscErrorCode TSTrajectoryGetSolutionOnly(TSTrajectory tj,PetscBool *solution_only)
    972: {
    976:   *solution_only = tj->solution_only;
    977:   return(0);
    978: }

    980: /*@
    981:    TSTrajectoryGetUpdatedHistoryVecs - Get updated state and time-derivative history vectors.

    983:    Collective on TSTrajectory

    985:    Input Parameter:
    986: +  tj   - the TS trajectory context
    987: .  ts   - the TS solver context
    988: -  time - the requested time

    990:    Output Parameter:
    991: +  U    - state vector at given time (can be interpolated)
    992: -  Udot - time-derivative vector at given time (can be interpolated)

    994:    Level: developer

    996:    Notes: The vectors are interpolated if time does not match any time step stored in the TSTrajectory(). Pass NULL to not request a vector.
    997:           This function differs from TSTrajectoryGetVecs since the vectors obtained cannot be modified, and they need to be returned by
    998:           calling TSTrajectoryRestoreUpdatedHistoryVecs().

    1000: .seealso: TSSetSaveTrajectory(), TSTrajectoryCreate(), TSTrajectoryDestroy(), TSTrajectoryRestoreUpdatedHistoryVecs(), TSTrajectoryGetVecs()
    1001: @*/
    1002: PetscErrorCode TSTrajectoryGetUpdatedHistoryVecs(TSTrajectory tj, TS ts, PetscReal time, Vec *U, Vec *Udot)
    1003: {

    1012:   if (U && !tj->U) {
    1013:     DM dm;

    1015:     TSGetDM(ts,&dm);
    1016:     DMCreateGlobalVector(dm,&tj->U);
    1017:   }
    1018:   if (Udot && !tj->Udot) {
    1019:     DM dm;

    1021:     TSGetDM(ts,&dm);
    1022:     DMCreateGlobalVector(dm,&tj->Udot);
    1023:   }
    1024:   TSTrajectoryGetVecs(tj,ts,PETSC_DECIDE,&time,U ? tj->U : NULL,Udot ? tj->Udot : NULL);
    1025:   if (U) {
    1026:     VecLockReadPush(tj->U);
    1027:     *U   = tj->U;
    1028:   }
    1029:   if (Udot) {
    1030:     VecLockReadPush(tj->Udot);
    1031:     *Udot = tj->Udot;
    1032:   }
    1033:   return(0);
    1034: }

    1036: /*@
    1037:    TSTrajectoryRestoreUpdatedHistoryVecs - Restores updated state and time-derivative history vectors obtained with TSTrajectoryGetUpdatedHistoryVecs().

    1039:    Collective on TSTrajectory

    1041:    Input Parameter:
    1042: +  tj   - the TS trajectory context
    1043: .  U    - state vector at given time (can be interpolated)
    1044: -  Udot - time-derivative vector at given time (can be interpolated)

    1046:    Level: developer

    1048: .seealso: TSTrajectoryGetUpdatedHistoryVecs()
    1049: @*/
    1050: PetscErrorCode TSTrajectoryRestoreUpdatedHistoryVecs(TSTrajectory tj, Vec *U, Vec *Udot)
    1051: {

    1058:   if (U && *U != tj->U) SETERRQ(PetscObjectComm((PetscObject)*U),PETSC_ERR_USER,"U was not obtained from TSTrajectoryGetUpdatedHistoryVecs()");
    1059:   if (Udot && *Udot != tj->Udot) SETERRQ(PetscObjectComm((PetscObject)*Udot),PETSC_ERR_USER,"Udot was not obtained from TSTrajectoryGetUpdatedHistoryVecs()");
    1060:   if (U) {
    1061:     VecLockReadPop(tj->U);
    1062:     *U   = NULL;
    1063:   }
    1064:   if (Udot) {
    1065:     VecLockReadPop(tj->Udot);
    1066:     *Udot = NULL;
    1067:   }
    1068:   return(0);
    1069: }