Transition from Example 2 to Example 3

Goal

The primary goal of Example 3: Introduce SolutionState is to move the evolving solution and selected time-integration metadata into Tempus::SolutionState 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 2: Use ModelEvaluator.

New concepts introduced are:

• Tempus::SolutionState
  • stores the solution together with metadata describing its role in the time integration process
• Tempus::SolutionStateMetaData
  • stores quantities such as time, index, timestep size, and status
• Tempus::Status
  • represents whether a solution is working, passed, or failed
• Tempus::createSolutionStateX()
  • creates a solution state containing the primary solution vector

This is the first step in moving from application-local scalar bookkeeping to a Tempus-managed representation of the evolving solution state. That organization becomes increasingly important in later examples that introduce solution histories, steppers, and integrators.

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 is still a separate final comparison against gold values.

Selected code excerpts

The code excerpts below highlight the main changes needed to move from separate scalar bookkeeping variables to a Tempus::SolutionState.

---

Create the solution state

Create a SolutionState. The current solution is now stored in a Tempus::SolutionState together with selected metadata.

Before

int n = 0;
double time = 0.0;
bool passed = true;
RCP<Thyra::VectorBase<double> > x_n =
  model->getNominalValues().get_x()->clone_v();

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);

This replaces several scalar bookkeeping variables with a single Tempus::SolutionState object.

---

Use solution-state metadata

Use metadata from the solution state. The loop condition is now expressed in terms of the solution state's index, time, and status.

Before

while (passed && time < finalTime && n < nTimeSteps) {

After

while (solState->getSolutionStatus() == Tempus::Status::PASSED &&
       solState->getTime() < finalTime &&
       solState->getIndex() < nTimeSteps) {

---

Record step outcome

Record step success or failure through the solution state. Step acceptance and failure are now reflected in the solution status and metadata.

Before

if ( std::isnan(Thyra::norm(*x_np1)) ) {
  passed = false;
} else {
  Thyra::V_V(x_n.ptr(), *x_np1);
  n++;
}

After

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);
}

In the updated example, the final tutorial success condition is formed after the time loop by combining:

• whether the final SolutionState has status PASSED, and
• whether the final solution satisfies the regression test.

---

How to compare the examples

A more detailed comparison can be made by diffing:

• examples/02_Use_ModelEvaluator/02_Use_ModelEvaluator.cpp
• examples/03_Intro_SolutionState/03_Intro_SolutionState.cpp

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 '76,164p' examples/02_Use_ModelEvaluator/02_Use_ModelEvaluator.cpp) \
  <(sed -n '83,184p' examples/03_Intro_SolutionState/03_Intro_SolutionState.cpp)

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

---

← Previous Example | Current Example | Next Example →