Goal

The primary goal of Example 4: Add SolutionHistory is to move from a single Tempus::SolutionState to a Tempus::SolutionHistory while preserving the same Thyra::ModelEvaluator-based model, the same explicit Forward Euler update, the same simple tabular output, and the same regression-testing workflow used in Example 3: Introduce SolutionState.

New concepts introduced are:

Tempus::SolutionHistory
- stores and manages multiple Tempus::SolutionState objects during time integration
Tempus::createSolutionHistoryState()
- creates a solution history initialized with an initial solution state
initWorkingState()
- initializes a working state for the next tentative time step
getCurrentState()
- returns the current accepted solution state
getWorkingState()
- returns the tentative working solution state
getCurrentTime()
- returns the time of the current accepted solution state
getCurrentIndex()
- returns the index of the current accepted solution state
promoteWorkingState()
- promotes the accepted working state to become the new current state

This is the first step in moving from state-based solution management to history-based solution management. That transition is important because many time integration algorithms require access to multiple states, including the current solution, tentative working states, and previously accepted states.

What stays the same

The van der Pol model is still provided by a Thyra::ModelEvaluator.
The timestepper is still Forward Euler.
The application still controls the time loop directly.
The output table still reports the step index, time, , and .
The regression check remains a separate final comparison.

Selected code excerpts

The code excerpts below highlight the main changes needed to move from a single Tempus::SolutionState to a Tempus::SolutionHistory.

Create the solution history

Create a SolutionHistory. The initial condition is still stored in a Tempus::SolutionState, but that state is now inserted into a Tempus::SolutionHistory.

Before

auto solState = Tempus::createSolutionStateX(
                  model->getNominalValues().get_x()->clone_v());
solState->setIndex   (0);
solState->setTime    (0.0);
solState->setTimeStep(0.0);
solState->setSolutionStatus(Tempus::Status::PASSED);

After

auto solState = Tempus::createSolutionStateX(
                  model->getNominalValues().get_x()->clone_v());
solState->setIndex   (0);
solState->setTime    (0.0);
solState->setTimeStep(0.0);
solState->setSolutionStatus(Tempus::Status::PASSED);
 
auto solHistory = Tempus::createSolutionHistoryState<double>(solState);

The initial condition remains the same, but it is now managed through a Tempus::SolutionHistory.

Access current and working states

Use SolutionHistory to access states. Instead of working directly with a single solution state, the application now asks the history object for the current and working states.

Before

while (solState->getSolutionStatus() == Tempus::Status::PASSED &&
       solState->getTime() < finalTime &&
       solState->getIndex() < nTimeSteps) {
 
  RCP<Thyra::VectorBase<double> > x_n   = solState->getX();
  RCP<Thyra::VectorBase<double> > x_np1 = solState->getX()->clone_v();
  solState->setSolutionStatus(Tempus::Status::WORKING);

After

while (solHistory->getCurrentState()->getSolutionStatus() ==
         Tempus::Status::PASSED &&
       solHistory->getCurrentTime() < finalTime &&
       solHistory->getCurrentIndex() < nTimeSteps) {
 
  solHistory->initWorkingState();
  auto currentState = solHistory->getCurrentState();
  auto workingState = solHistory->getWorkingState();
  RCP<Thyra::VectorBase<double> > x_n   = currentState->getX();
  RCP<Thyra::VectorBase<double> > x_np1 = workingState->getX();

The current and tentative states are now obtained through the history object rather than being managed manually.

Update metadata on the working state

Assign metadata to the working state. The timestep index, time, and timestep size are associated with the working state created by the history object.

Before

int index = solState->getIndex()+1;
double dt = constDT;
double time = index*dt;

After

int index = workingState->getIndex();
double dt = constDT;
double time = index*dt;
workingState->setTime(time);
workingState->setTimeStep(dt);

The working state is initialized by the history object and then updated with the time information for the tentative step.

Record and promote the working state

Promote the accepted working state. The step outcome is recorded on the working state, and the history object promotes it when the step completes.

Before

if ( std::isnan(Thyra::norm(*x_np1)) ) {
  solState->setSolutionStatus(Tempus::Status::FAILED);
} else {
  Thyra::V_V(x_n.ptr(), *x_np1);
  solState->setIndex   (index);
  solState->setTime    (time);
  solState->setTimeStep(constDT);
  solState->setSolutionStatus(Tempus::Status::PASSED);
}

After

if ( std::isnan(Thyra::norm(*x_np1)) ) {
  workingState->setSolutionStatus(Tempus::Status::FAILED);
} else {
  workingState->setSolutionStatus(Tempus::Status::PASSED);
}
solHistory->promoteWorkingState();

The new solution is written into the working state, the step result is associated with that state, and the history object manages promotion of that state to become the new current state.

As in the updated examples, the regression comparison remains separate from step status. Final tutorial success is determined after the loop by combining the final state status with the result of the regression test.

How to compare the examples

A more detailed comparison can be made by diffing:

From the packages/tempus directory, a focused comparison of the main time-integration logic between these two examples can be generated locally in bash or zsh with:

git diff --no-index \
  <(sed -n '83,184p' examples/03_Intro_SolutionState/03_Intro_SolutionState.cpp) \
  <(sed -n '88,195p' examples/04_Adding_SolutionHistory/04_Adding_SolutionHistory.cpp)

This ignores leading header lines (e.g., #include statements and Doxygen comments) and trailing regression-testing lines.

← Previous Example | Current Example | Next Example →