Tutorial_Regression_Tester.hpp File Reference

Regression utilities for the Tempus progression tutorials. More...

#include <iostream>
#include <cmath>
#include "Teuchos_RCP.hpp"
#include "Teuchos_as.hpp"
#include "Thyra_VectorBase.hpp"
#include "Thyra_VectorStdOps.hpp"
#include "Thyra_DefaultSpmdVectorSpace.hpp"
#include "Thyra_DetachedVectorView.hpp"
#include "Tempus_SolutionState.hpp"

Go to the source code of this file.

Functions
bool	tutorialRegressionTest (const Teuchos::RCP< Thyra::VectorBase< double > > &x_n, std::ostream &out=std::cout, const double relTol=Teuchos::as< double >(1.0e-8))
	Regression check for the Tempus tutorial van der Pol examples.
bool	tutorialRegressionTest (const Teuchos::RCP< Tempus::SolutionState< double > > &solState, std::ostream &out=std::cout, const double relTol=Teuchos::as< double >(1.0e-8))
	Overload for Tempus::SolutionState.
template<int N>
bool	tutorialRegressionTest (const double(&x_n)[N], std::ostream &out=std::cout, const double relTol=Teuchos::as< double >(1.0e-8))
	Overload for the raw-array representation used in Example 0.

Detailed Description

Regression utilities for the Tempus progression tutorials.

This file defines tutorialRegressionTest, which performs the common final-solution regression comparison used by the van der Pol tutorial examples.

Definition in file Tutorial_Regression_Tester.hpp.

Function Documentation

tutorialRegressionTest() [1/3]

bool tutorialRegressionTest ( const Teuchos::RCP< Thyra::VectorBase< double > > &  x_n, std::ostream &  out = std::cout, const double  relTol = Teuchos::as<double>(1.0e-8)  )

inline

Regression check for the Tempus tutorial van der Pol examples.

This helper compares a computed solution against a fixed "gold" reference solution for the van der Pol tutorial problem at final time using 2000 Forward Euler steps.

The purpose of this check is not to validate the physical model against an analytic solution, since no closed-form analytic solution is available for the van der Pol problem. Rather, it is a regression check intended to ensure that the tutorial examples continue to reproduce the same numerical result to approximately 8 digits of relative accuracy for the fixed timestep size .

The current gold values are:

In practice, this tutorial example often reproduces the gold values much more accurately than the required 8 digits, but the acceptance threshold is intentionally looser in order to keep the regression check robust.

Replacing this regression test with a comparison to an analytic solution would answer a different question: it would primarily measure temporal discretization error at this timestep size. That error would be much larger than the regression tolerance used here, and would make it harder to detect simple coding mistakes that this tutorial regression check is meant to catch, such as taking one too many timesteps or changing the update logic.

How to update the gold values

If the gold values ever need to be updated, use the Tempus Forward Euler verification test, test/ForwardEuler/Tempus_ForwardEulerTest.cpp, which performs a temporal refinement study to verify first-order accuracy. A typical update workflow is:

• rerun a temporal refinement study for the same problem to verify that the Forward Euler implementation still exhibits the expected first-order convergence behavior and that no first-order bugs have been introduced
• once satisfied that the implementation is correct, record the final solution for the tutorial configuration:
  • van der Pol problem
  • final time
  • 2000 Forward Euler steps
• replace the hardcoded gold values in this helper with the new reference values

Parameters

[in]	x_n	Computed final solution vector.
[in]	out	Output stream used for reporting.
[in]	relTol	Relative error tolerance. The default is 1.0e-8.

Returns

true if the regression comparison passes; otherwise false.

Definition at line 83 of file Tutorial_Regression_Tester.hpp.

tutorialRegressionTest() [2/3]

bool tutorialRegressionTest ( const Teuchos::RCP< Tempus::SolutionState< double > > &  solState, std::ostream &  out = std::cout, const double  relTol = Teuchos::as<double>(1.0e-8)  )

inline

Overload for Tempus::SolutionState.

Extracts the solution vector from the supplied Tempus::SolutionState and applies tutorialRegressionTest().

Parameters

[in]	solState	Final solution state.
[in]	out	Output stream used for reporting.
[in]	relTol	Relative error tolerance. The default is 1.0e-8.

Returns

true if the regression comparison passes, else false.

Definition at line 125 of file Tutorial_Regression_Tester.hpp.

tutorialRegressionTest() [3/3]

template<int N>

bool tutorialRegressionTest ( const double(&)  x_n[N], std::ostream &  out = std::cout, const double  relTol = Teuchos::as<double>(1.0e-8)  )

inline

Overload for the raw-array representation used in Example 0.

This overload converts the raw array into a Thyra::VectorBase and then applies the common regression check implemented by the Thyra-vector overload of tutorialRegressionTest().

For the vander Pol problem tutorial, N is expected to be an array of length 2.

Parameters

[in]	x_n	Computed final solution stored as an array.
[in]	out	Output stream used for reporting.
[in]	relTol	Relative error tolerance. The default is 1.0e-8.

Returns

true if the regression comparison passes; otherwise false.

Definition at line 149 of file Tutorial_Regression_Tester.hpp.