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

#include <Tempus_StepperImplicit_decl.hpp>

Inheritance diagram for Tempus::StepperImplicit< Scalar >:

Public Member Functions
virtual bool	isValidSetup (Teuchos::FancyOStream &out) const

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

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

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

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

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

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

Public Member Functions inherited from Tempus::Stepper< Scalar >
void	setStepperValues (const Teuchos::RCP< Teuchos::ParameterList > pl)
	Set Stepper member data from ParameterList. More...

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

virtual void	setNonConstModel (const Teuchos::RCP< Thyra::ModelEvaluator< Scalar > > &)

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

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

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

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

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. More...

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

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. More...

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. More...

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

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

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

virtual std::string	description () const

Public Member Functions inherited from Teuchos::Describable
void	describe (std::ostream &out, const EVerbosityLevel verbLevel=verbLevel_default) const

virtual	~Describable ()

	LabeledObject ()

virtual	~LabeledObject ()

virtual void	setObjectLabel (const std::string &objectLabel)

virtual std::string	getObjectLabel () const

DescribableStreamManipulatorState	describe (const Describable &describable, const EVerbosityLevel verbLevel=Describable::verbLevel_default)

std::ostream &	operator<< (std::ostream &os, const DescribableStreamManipulatorState &d)

Public Member Functions inherited from Teuchos::VerboseObject< Stepper< Scalar > >
	VerboseObject (const EVerbosityLevel verbLevel=VERB_DEFAULT, const RCP< FancyOStream > &oStream=Teuchos::null)

virtual const VerboseObject &	setVerbLevel (const EVerbosityLevel verbLevel) const

virtual const VerboseObject &	setOverridingVerbLevel (const EVerbosityLevel verbLevel) const

virtual EVerbosityLevel	getVerbLevel () const

TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT RCP< const ParameterList >	getValidVerboseObjectSublist ()

TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT void	setupVerboseObjectSublist (ParameterList *paramList)

TEUCHOSPARAMETERLIST_LIB_DLL_EXPORT void	readVerboseObjectSublist (ParameterList paramList, RCP< FancyOStream > oStream, EVerbosityLevel *verbLevel)

void	readVerboseObjectSublist (ParameterList paramList, VerboseObject< ObjectType > verboseObject)

Public Member Functions inherited from Teuchos::VerboseObjectBase
virtual	~VerboseObjectBase ()

	VerboseObjectBase (const RCP< FancyOStream > &oStream=Teuchos::null)

virtual const VerboseObjectBase &	setOStream (const RCP< FancyOStream > &oStream) const

virtual const VerboseObjectBase &	setOverridingOStream (const RCP< FancyOStream > &oStream) const

virtual VerboseObjectBase &	setLinePrefix (const std::string &linePrefix)

virtual RCP< FancyOStream >	getOStream () const

virtual RCP< FancyOStream >	getOverridingOStream () const

virtual std::string	getLinePrefix () const

virtual OSTab	getOSTab (const int tabs=1, const std::string &linePrefix="") const

Protected Attributes
Teuchos::RCP < WrapperModelEvaluator < Scalar > >	wrapperModel_

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

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

bool	zeroInitialGuess_

std::string	solverName_

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

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

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

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

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

virtual void	setDefaultSolver ()

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

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

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

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

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

const Thyra::SolveStatus< Scalar >	solveImplicitODE (const Teuchos::RCP< Thyra::VectorBase< Scalar > > &x)
	Solve problem using x in-place. (Needs to be deprecated!) More...

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)
	Solve implicit ODE, f(x, xDot, t, p) = 0. More...

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). More...

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

virtual void	setZeroInitialGuess (bool zIG)
	Set parameter so that the initial guess is set to zero (=True) or use last timestep (=False). More...

virtual bool	getZeroInitialGuess () const

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

Overridden from Teuchos::Describable
virtual void	describe (Teuchos::FancyOStream &out, const Teuchos::EVerbosityLevel verbLevel) const

Additional Inherited Members
Static Public Member Functions inherited from Teuchos::VerboseObject< Stepper< Scalar > >
static void	setDefaultVerbLevel (const EVerbosityLevel defaultVerbLevel)

static EVerbosityLevel	getDefaultVerbLevel ()

Static Public Member Functions inherited from Teuchos::VerboseObjectBase
static void	setDefaultOStream (const RCP< FancyOStream > &defaultOStream)

static RCP< FancyOStream >	getDefaultOStream ()

Static Public Attributes inherited from Teuchos::Describable
static const EVerbosityLevel	verbLevel_default

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

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

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

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

Protected Member Functions inherited from Teuchos::VerboseObject< Stepper< Scalar > >
void	initializeVerboseObject (const EVerbosityLevel verbLevel=VERB_DEFAULT, const RCP< FancyOStream > &oStream=Teuchos::null)

Protected Member Functions inherited from Teuchos::VerboseObjectBase
void	initializeVerboseObjectBase (const RCP< FancyOStream > &oStream=Teuchos::null)

virtual void	informUpdatedVerbosityState () const

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 $x_n$ is the solution vector, $\dot{x}$ is the time derivative, $t_n$ is the time and $n$ 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 $x_n$ , 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, $W$ , 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 $M$ is the mass matrix and $J$ is the Jacobian.

Note that sometimes it is helpful to set $\alpha=0$ and $\beta = 1$ to obtain the Jacobian, $J$ , from the iteration matrix (i.e., ModelEvaluator), or set $\alpha=1$ and $\beta = 0$ to obtain the mass matrix, $M$ , 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 $W$ 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, $M$ , the Jacobian, $J$ 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 $W$ 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, $M$ , the Jacobian, $J$ , 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 228 of file Tempus_StepperImplicit_decl.hpp.

Member Function Documentation

template<class Scalar >

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

virtual

Reimplemented from Tempus::Stepper< Scalar >.

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

Definition at line 20 of file Tempus_StepperImplicit_impl.hpp.

template<class Scalar >

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

inlinevirtual

Reimplemented from Tempus::Stepper< Scalar >.

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

Definition at line 237 of file Tempus_StepperImplicit_decl.hpp.

template<class Scalar >

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

inlinevirtual

Definition at line 245 of file Tempus_StepperImplicit_decl.hpp.

template<class Scalar >

void Tempus::StepperImplicit< Scalar >::setDefaultSolver ( )

virtual

Definition at line 212 of file Tempus_StepperImplicit_impl.hpp.

template<class Scalar >

void Tempus::StepperImplicit< Scalar >::setSolver ( Teuchos::RCP< Thyra::NonlinearSolverBase< Scalar > > solver )

virtual

Set solver.

Reimplemented from Tempus::Stepper< Scalar >.

Definition at line 227 of file Tempus_StepperImplicit_impl.hpp.

template<class Scalar >

virtual Teuchos::RCP<Thyra::NonlinearSolverBase<Scalar> > Tempus::StepperImplicit< Scalar >::getSolver ( ) const

inlinevirtual

Get solver.

Reimplemented from Tempus::Stepper< Scalar >.

Definition at line 253 of file Tempus_StepperImplicit_decl.hpp.

template<class Scalar >

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

virtual

Set the initial conditions and make them consistent.

Implements Tempus::Stepper< Scalar >.

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

Definition at line 36 of file Tempus_StepperImplicit_impl.hpp.

template<class Scalar >

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

pure virtual

Return alpha = d(xDot)/dx.

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

template<class Scalar >

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

pure virtual

Return beta = d(x)/dx.

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

template<class Scalar >

const Thyra::SolveStatus< Scalar > Tempus::StepperImplicit< Scalar >::solveImplicitODE ( const Teuchos::RCP< Thyra::VectorBase< Scalar > > & x )

Solve problem using x in-place. (Needs to be deprecated!)

Definition at line 242 of file Tempus_StepperImplicit_impl.hpp.

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
	)

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

Definition at line 256 of file Tempus_StepperImplicit_impl.hpp.

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
	)