Thyra Base interface for implicit time steppers. More...

#include <Tempus_StepperImplicit_decl.hpp>

Inheritance diagram for Tempus::StepperImplicit< Scalar >:

Overridden from Teuchos::Describable
Teuchos::RCP< WrapperModelEvaluator< Scalar > >	wrapperModel_

Teuchos::RCP< Thyra::NonlinearSolverBase< Scalar > >	solver_

Teuchos::RCP< const Thyra::VectorBase< Scalar > >	initialGuess_

bool	zeroInitialGuess_

std::string	solverName_

virtual void	describe (Teuchos::FancyOStream &out, const Teuchos::EVerbosityLevel verbLevel) const override

virtual bool	isValidSetup (Teuchos::FancyOStream &out) const override

virtual Teuchos::RCP< const Teuchos::ParameterList >	getValidParameters () const override

Teuchos::RCP< Teuchos::ParameterList >	getValidParametersBasicImplicit () const

void	setStepperImplicitValues (Teuchos::RCP< Teuchos::ParameterList > pl)
	Set StepperImplicit member data from the ParameterList.

void	setStepperSolverValues (Teuchos::RCP< Teuchos::ParameterList > pl)
	Set solver from ParameterList.

void	setSolverName (std::string i)
	Set the Solver Name.

std::string	getSolverName () const
	Get the Solver Name.

Basic implicit stepper methods
virtual void	setModel (const Teuchos::RCP< const Thyra::ModelEvaluator< Scalar > > &appModel) override
	Set the model.

virtual Teuchos::RCP< const Thyra::ModelEvaluator< Scalar > >	getModel () const override

virtual Teuchos::RCP< const WrapperModelEvaluator< Scalar > >	getWrapperModel ()

virtual void	setDefaultSolver ()

virtual void	setSolver (Teuchos::RCP< Thyra::NonlinearSolverBase< Scalar > > solver) override
	Set solver.

virtual Teuchos::RCP< Thyra::NonlinearSolverBase< Scalar > >	getSolver () const override
	Get solver.

virtual void	setInitialConditions (const Teuchos::RCP< SolutionHistory< Scalar > > &solutionHistory) override
	Set the initial conditions and make them consistent.

virtual Scalar	getAlpha (const Scalar dt) const =0
	Return alpha = d(xDot)/dx.

virtual Scalar	getBeta (const Scalar dt) const =0
	Return beta = d(x)/dx.

const Thyra::SolveStatus< Scalar >	solveImplicitODE (const Teuchos::RCP< Thyra::VectorBase< Scalar > > &x, const Teuchos::RCP< Thyra::VectorBase< Scalar > > &xDot, const Scalar time, const Teuchos::RCP< ImplicitODEParameters< Scalar > > &p, const Teuchos::RCP< Thyra::VectorBase< Scalar > > &y=Teuchos::null, const int index=-1)
	Solve implicit ODE, f(x, xDot, t, p) = 0.

void	evaluateImplicitODE (Teuchos::RCP< Thyra::VectorBase< Scalar > > &f, const Teuchos::RCP< Thyra::VectorBase< Scalar > > &x, const Teuchos::RCP< Thyra::VectorBase< Scalar > > &xDot, const Scalar time, const Teuchos::RCP< ImplicitODEParameters< Scalar > > &p)
	Evaluate implicit ODE residual, f(x, xDot, t, p).

virtual void	setInitialGuess (Teuchos::RCP< const Thyra::VectorBase< Scalar > > initialGuess) override
	Pass initial guess to Newton solver (only relevant for implicit solvers)

virtual void	setZeroInitialGuess (bool zIG)

virtual bool	getZeroInitialGuess () const

virtual Scalar	getInitTimeStep (const Teuchos::RCP< SolutionHistory< Scalar > > &) const override

Additional Inherited Members
Public Member Functions inherited from Tempus::Stepper< Scalar >
virtual std::string	description () const

void	setStepperValues (const Teuchos::RCP< Teuchos::ParameterList > pl)
	Set Stepper member data from ParameterList.

Teuchos::RCP< Teuchos::ParameterList >	getValidParametersBasic () const
	Add basic parameters to Steppers ParameterList.

virtual void	initialize ()
	Initialize after construction and changing input parameters.

virtual bool	isInitialized ()
	True if stepper's member data is initialized.

virtual void	checkInitialized ()
	Check initialization, and error out on failure.

virtual void	takeStep (const Teuchos::RCP< SolutionHistory< Scalar > > &solutionHistory)=0
	Take the specified timestep, dt, and return true if successful.

virtual Teuchos::RCP< Tempus::StepperState< Scalar > >	getDefaultStepperState ()=0

virtual Scalar	getOrder () const =0

virtual Scalar	getOrderMin () const =0

virtual Scalar	getOrderMax () const =0

virtual bool	isExplicit () const =0

virtual bool	isImplicit () const =0

virtual bool	isExplicitImplicit () const =0

virtual bool	isOneStepMethod () const =0

virtual bool	isMultiStepMethod () const =0

void	setStepperName (std::string s)
	Set the stepper name.

std::string	getStepperName () const
	Get the stepper name.

std::string	getStepperType () const
	Get the stepper type. The stepper type is used as an identifier for the stepper, and can only be set by the derived Stepper class.

virtual void	setUseFSAL (bool a)

void	setUseFSALTrueOnly (bool a)

void	setUseFSALFalseOnly (bool a)

bool	getUseFSAL () const

void	setICConsistency (std::string s)

std::string	getICConsistency () const

void	setICConsistencyCheck (bool c)

bool	getICConsistencyCheck () const

virtual OrderODE	getOrderODE () const =0

virtual Teuchos::RCP< Thyra::VectorBase< Scalar > >	getStepperX ()
	Get Stepper x.

virtual Teuchos::RCP< Thyra::VectorBase< Scalar > >	getStepperXDot ()
	Get Stepper xDot.

virtual Teuchos::RCP< Thyra::VectorBase< Scalar > >	getStepperXDotDot ()
	Get Stepper xDotDot.

virtual Teuchos::RCP< Thyra::VectorBase< Scalar > >	getStepperXDotDot (Teuchos::RCP< SolutionState< Scalar > > state)
	Get xDotDot from SolutionState or Stepper storage.

Protected Member Functions inherited from Tempus::Stepper< Scalar >
virtual void	setStepperX (Teuchos::RCP< Thyra::VectorBase< Scalar > > x)
	Set x for Stepper storage.

virtual void	setStepperXDot (Teuchos::RCP< Thyra::VectorBase< Scalar > > xDot)
	Set xDot for Stepper storage.

virtual void	setStepperXDotDot (Teuchos::RCP< Thyra::VectorBase< Scalar > > xDotDot)
	Set x for Stepper storage.

void	setStepperType (std::string s)
	Set the stepper type.

Protected Attributes inherited from Tempus::Stepper< Scalar >
bool	useFSAL_ = false
	Use First-Same-As-Last (FSAL) principle.

bool	isInitialized_
	True if stepper's member data is initialized.

Detailed Description

template<class Scalar>
class Tempus::StepperImplicit< Scalar >

Thyra Base interface for implicit time steppers.

For first-order ODEs, we can write the implicit ODE as

$\mathcal{F}(\dot{x}_n,x_n,t_n) = 0$

where is the solution vector, $\dot{x}$ is the time derivative, is the time and indicates the $n^{th}$ time level. Note that $\dot{x}_n$ is different for each time stepper and is a function of other solution states, e.g., for Backward Euler,

$\dot{x}_n(x_n) = \frac{x_n - x_{n-1}}{\Delta t}$

Defining the Iteration Matrix

Often we use Newton's method or one of its variations to solve for , such as

$\left[ \frac{\partial}{\partial x_n} \left( \mathcal{F}(\dot{x}_n,x_n,t_n) \right) \right] \Delta x_n^\nu = - \mathcal{F}(\dot{x}_n^\nu,x_n^\nu,t_n)$

where $\Delta x_n^\nu = x_n^{\nu+1} - x_n^\nu$ and $\nu$ is the iteration index. Using the chain rule for a function with multiple variables, we can write

$\left[ \frac{\partial \dot{x}_n(x_n) }{\partial x_n} \frac{\partial}{\partial \dot{x}_n} \left( \mathcal{F}(\dot{x}_n,x_n,t_n) \right) + \frac{\partial x_n}{\partial x_n} \frac{\partial}{\partial x_n} \left( \mathcal{F}(\dot{x}_n,x_n,t_n) \right) \right] \Delta x_n^\nu = - \mathcal{F}(\dot{x}_n^\nu,x_n^\nu,t_n)$

Defining the iteration matrix, , we have

$W \Delta x_n^\nu = - \mathcal{F}(\dot{x}_n^\nu,x_n^\nu,t_n)$

using $\mathcal{F}_n = \mathcal{F}(\dot{x}_n,x_n,t_n)$ , where

$W = \alpha \frac{\partial \mathcal{F}_n}{\partial \dot{x}_n} + \beta \frac{\partial \mathcal{F}_n}{\partial x_n}$

and

$W = \alpha M + \beta J$

where

$\alpha \equiv \frac{\partial \dot{x}_n(x_n) }{\partial x_n}, \quad \quad \beta \equiv \frac{\partial x_n}{\partial x_n} = 1, \quad \quad M = \frac{\partial \mathcal{F}_n}{\partial \dot{x}_n}, \quad \quad J = \frac{\partial \mathcal{F}_n}{\partial x_n}$

and is the mass matrix and is the Jacobian.

Note that sometimes it is helpful to set $\alpha=0$ and $\beta = 1$ to obtain the Jacobian, , from the iteration matrix (i.e., ModelEvaluator), or set $\alpha=1$ and $\beta = 0$ to obtain the mass matrix, , from the iteration matrix (i.e., the ModelEvaluator).

As a concrete example, the time derivative for Backward Euler is

$\dot{x}_n(x_n) = \frac{x_n - x_{n-1}}{\Delta t}$

thus

$\alpha \equiv \frac{\partial \dot{x}_n(x_n) }{\partial x_n} = \frac{1}{\Delta t} \quad \quad \beta \equiv \frac{\partial x_n}{\partial x_n} = 1$

and the iteration matrix for Backward Euler is

$W = \frac{1}{\Delta t} \frac{\partial \mathcal{F}_n}{\partial \dot{x}_n} + \frac{\partial \mathcal{F}_n}{\partial x_n}$

Dangers of multiplying through by $\Delta t$ . In some time-integration schemes, the application might want to multiply the governing equations by the time-step size, $\Delta t$ , for scaling or other reasons. Here we illustrate what that means and the complications that follow from it.

Starting with a simple implicit ODE and multiplying through by $\Delta t$ , we have

$\mathcal{F}_n = \Delta t \dot{x}_n - \Delta t \bar{f}(x_n,t_n) = 0$

For the Backward Euler stepper, we recall from above that

$\dot{x}_n(x_n) = \frac{x_n - x_{n-1}}{\Delta t} \quad\quad \alpha \equiv \frac{\partial \dot{x}_n(x_n) }{\partial x_n} = \frac{1}{\Delta t} \quad \quad \beta \equiv \frac{\partial x_n}{\partial x_n} = 1$

and we can find for our simple implicit ODE, $\mathcal{F}_n$ ,

$M = \frac{\partial \mathcal{F}_n}{\partial \dot{x}_n} = \Delta t, \quad \quad J = \frac{\partial \mathcal{F}_n}{\partial x_n} = -\Delta t \frac{\partial \bar{f}_n}{\partial x_n}$

Thus this iteration matrix, $W^\ast$ , is

$W^\ast = \alpha \frac{\partial \mathcal{F}_n}{\partial \dot{x}_n} + \beta \frac{\partial \mathcal{F}_n}{\partial x_n} = \frac{1}{\Delta t} \Delta t + (1) \left( - \Delta t \frac{\partial \bar{f}_n}{\partial x_n} \right)$

or simply

$W^\ast = 1 - \Delta t \frac{\partial \bar{f}_n}{\partial x_n}$

Note that $W^\ast$ is not the same as from above (i.e., $W = \frac{1}{\Delta t} - \frac{\partial \bar{f}_n}{\partial x_n}$ ). But we should not infer from this is that $\alpha = 1$ or $\beta = -\Delta t$ , as those definitions are unchanged (i.e., $\alpha \equiv \frac{\partial \dot{x}_n(x_n)} {\partial x_n} = \frac{1}{\Delta t}$ and $\beta \equiv \frac{\partial x_n}{\partial x_n} = 1$ ). However, the mass matrix, , the Jacobian, and the residual, $-\mathcal{F}_n$ , all need to include $\Delta t$ in their evaluations (i.e., be included in the ModelEvaluator return values for these terms).

Dangers of explicitly including time-derivative definition. If we explicitly include the time-derivative defintion for Backward Euler, we find for our simple implicit ODE,

$\mathcal{F}_n = \frac{x_n - x_{n-1}}{\Delta t} - \bar{f}(x_n,t_n) = 0$

that the iteration matrix is

$W^{\ast\ast} = \alpha \frac{\partial \mathcal{F}_n}{\partial \dot{x}_n} + \beta \frac{\partial \mathcal{F}_n}{\partial x_n} = \frac{1}{\Delta t} (0) + (1) \left(\frac{1}{\Delta t} - \frac{\partial \bar{f}_n}{\partial x_n} \right)$

or simply

$W^{\ast\ast} = \frac{1}{\Delta t} - \frac{\partial \bar{f}_n}{\partial x_n}$

which is the same as from above for Backward Euler, but again we should not infer that $\alpha = \frac{1}{\Delta t}$ or $\beta = -1$ . However the major drawback is the mass matrix, , the Jacobian, , and the residual, $-\mathcal{F}_n$ (i.e., the ModelEvaluator) are explicitly written only for Backward Euler. The application would need to write separate ModelEvaluators for each stepper, thus destroying the ability to re-use the ModelEvaluator with any stepper.

Definition at line 197 of file Tempus_StepperImplicit_decl.hpp.

Member Function Documentation

◆ setModel()

template<class Scalar >

void Tempus::StepperImplicit< Scalar >::setModel ( const Teuchos::RCP< const Thyra::ModelEvaluator< Scalar > > & appModel )

overridevirtual

Set the model.

Reimplemented from Tempus::Stepper< Scalar >.

Reimplemented in Tempus::StepperBDF2< Scalar >, Tempus::StepperHHTAlpha< Scalar >, Tempus::StepperIMEX_RK< Scalar >, Tempus::StepperIMEX_RK_Partition< Scalar >, Tempus::StepperNewmarkImplicitAForm< Scalar >, Tempus::StepperNewmarkImplicitDForm< Scalar >, Tempus::StepperBackwardEuler< Scalar >, and Tempus::StepperDIRK< Scalar >.

Definition at line 19 of file Tempus_StepperImplicit_impl.hpp.

◆ getModel()

template<class Scalar >

virtual Teuchos::RCP< const Thyra::ModelEvaluator< Scalar > > Tempus::StepperImplicit< Scalar >::getModel ( ) const

inlineoverridevirtual

Reimplemented from Tempus::Stepper< Scalar >.

Reimplemented in Tempus::StepperIMEX_RK< Scalar >, and Tempus::StepperIMEX_RK_Partition< Scalar >.

Definition at line 206 of file Tempus_StepperImplicit_decl.hpp.

◆ getWrapperModel()

template<class Scalar >

virtual Teuchos::RCP< const WrapperModelEvaluator< Scalar > > Tempus::StepperImplicit< Scalar >::getWrapperModel ( )

inlinevirtual

template<class Scalar >

void Tempus::StepperImplicit< Scalar >::setInitialConditions ( const Teuchos::RCP< SolutionHistory< Scalar > > & solutionHistory )

overridevirtual

Set the initial conditions and make them consistent.

Implements Tempus::Stepper< Scalar >.

Reimplemented in Tempus::StepperHHTAlpha< Scalar >, Tempus::StepperNewmarkImplicitDForm< Scalar >, Tempus::StepperBDF2< Scalar >, Tempus::StepperIMEX_RK< Scalar >, Tempus::StepperIMEX_RK_Partition< Scalar >, Tempus::StepperNewmarkImplicitAForm< Scalar >, Tempus::StepperTrapezoidal< Scalar >, Tempus::StepperBackwardEuler< Scalar >, and Tempus::StepperDIRK< Scalar >.

Definition at line 34 of file Tempus_StepperImplicit_impl.hpp.

◆ getAlpha()

template<class Scalar >

virtual Scalar Tempus::StepperImplicit< Scalar >::getAlpha ( const Scalar dt ) const

pure virtual

Return alpha = d(xDot)/dx.

Implemented in Tempus::StepperBDF2< Scalar >, Tempus::StepperHHTAlpha< Scalar >, Tempus::StepperIMEX_RK< Scalar >, Tempus::StepperIMEX_RK_Partition< Scalar >, Tempus::StepperNewmarkImplicitAForm< Scalar >, Tempus::StepperNewmarkImplicitDForm< Scalar >, Tempus::StepperTrapezoidal< Scalar >, Tempus::StepperBackwardEuler< Scalar >, and Tempus::StepperDIRK< Scalar >.

◆ getBeta()

template<class Scalar >

virtual Scalar Tempus::StepperImplicit< Scalar >::getBeta ( const Scalar dt ) const

pure virtual

Return beta = d(x)/dx.

Implemented in Tempus::StepperNewmarkImplicitAForm< Scalar >, Tempus::StepperBDF2< Scalar >, Tempus::StepperHHTAlpha< Scalar >, Tempus::StepperIMEX_RK< Scalar >, Tempus::StepperIMEX_RK_Partition< Scalar >, Tempus::StepperNewmarkImplicitDForm< Scalar >, Tempus::StepperTrapezoidal< Scalar >, Tempus::StepperBackwardEuler< Scalar >, and Tempus::StepperDIRK< Scalar >.

◆ solveImplicitODE()

template<class Scalar >

const Thyra::SolveStatus< Scalar > Tempus::StepperImplicit< Scalar >::solveImplicitODE	(	const Teuchos::RCP< Thyra::VectorBase< Scalar > > &	x,
		const Teuchos::RCP< Thyra::VectorBase< Scalar > > &	xDot,
		const Scalar	time,
		const Teuchos::RCP< ImplicitODEParameters< Scalar > > &	p,
		const Teuchos::RCP< Thyra::VectorBase< Scalar > > &	y = `Teuchos::null`,
		const int	index = `-1`
	)

Solve implicit ODE, f(x, xDot, t, p) = 0.

Definition at line 252 of file Tempus_StepperImplicit_impl.hpp.

◆ evaluateImplicitODE()

template<class Scalar >

void Tempus::StepperImplicit< Scalar >::evaluateImplicitODE	(	Teuchos::RCP< Thyra::VectorBase< Scalar > > &	f,
		const Teuchos::RCP< Thyra::VectorBase< Scalar > > &	x,
		const Teuchos::RCP< Thyra::VectorBase< Scalar > > &	xDot,
		const Scalar	time,
		const Teuchos::RCP< ImplicitODEParameters< Scalar > > &	p
	)