Tempus Version of the Day
Time Integration
Loading...
Searching...
No Matches
List of all members
Tempus::StepperImplicit< Scalar > Class Template Referenceabstract

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

#include <Tempus_StepperImplicit_decl.hpp>

Inheritance diagram for Tempus::StepperImplicit< Scalar >:
Tempus::Stepper< Scalar > Tempus::StepperBDF2< Scalar > Tempus::StepperBackwardEuler< Scalar > Tempus::StepperDIRK< Scalar > Tempus::StepperHHTAlpha< Scalar > Tempus::StepperIMEX_RK< Scalar > Tempus::StepperIMEX_RK_Partition< Scalar > Tempus::StepperNewmarkImplicitAForm< Scalar > Tempus::StepperNewmarkImplicitDForm< Scalar > Tempus::StepperTrapezoidal< 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=0)
 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)
 Set parameter so that the initial guess is set to zero (=True) or use last timestep (=False).
 
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_ = false
 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 $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 226 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

◆ getModel()

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

◆ getWrapperModel()

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

Definition at line 244 of file Tempus_StepperImplicit_decl.hpp.

◆ setDefaultSolver()

template<class Scalar >
void Tempus::StepperImplicit< Scalar >::setDefaultSolver
virtual

Definition at line 212 of file Tempus_StepperImplicit_impl.hpp.

◆ setSolver()

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

Set solver.

Reimplemented from Tempus::Stepper< Scalar >.

Definition at line 227 of file Tempus_StepperImplicit_impl.hpp.

◆ getSolver()

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

Get solver.

Reimplemented from Tempus::Stepper< Scalar >.

Definition at line 252 of file Tempus_StepperImplicit_decl.hpp.

◆ setInitialConditions()

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

◆ getAlpha()

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

◆ getBeta()

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

◆ 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 = 0 
)

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

Definition at line 242 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 
)

Evaluate implicit ODE residual, f(x, xDot, t, p).

Definition at line 291 of file Tempus_StepperImplicit_impl.hpp.

◆ setInitialGuess()

template<class Scalar >
virtual void Tempus::StepperImplicit< Scalar >::setInitialGuess ( Teuchos::RCP< const Thyra::VectorBase< Scalar > >  initialGuess)
inlineoverridevirtual

Pass initial guess to Newton solver (only relevant for implicit solvers)

Implements Tempus::Stepper< Scalar >.

Definition at line 283 of file Tempus_StepperImplicit_decl.hpp.

◆ setZeroInitialGuess()

template<class Scalar >
virtual void Tempus::StepperImplicit< Scalar >::setZeroInitialGuess ( bool  zIG)
inlinevirtual

Set parameter so that the initial guess is set to zero (=True) or use last timestep (=False).

Definition at line 291 of file Tempus_StepperImplicit_decl.hpp.

◆ getZeroInitialGuess()

template<class Scalar >
virtual bool Tempus::StepperImplicit< Scalar >::getZeroInitialGuess ( ) const
inlinevirtual

Definition at line 296 of file Tempus_StepperImplicit_decl.hpp.

◆ getInitTimeStep()

template<class Scalar >
virtual Scalar Tempus::StepperImplicit< Scalar >::getInitTimeStep ( const Teuchos::RCP< SolutionHistory< Scalar > > &  ) const
inlineoverridevirtual

Implements Tempus::Stepper< Scalar >.

Definition at line 298 of file Tempus_StepperImplicit_decl.hpp.

◆ describe()

template<class Scalar >
void Tempus::StepperImplicit< Scalar >::describe ( Teuchos::FancyOStream &  out,
const Teuchos::EVerbosityLevel  verbLevel 
) const
overridevirtual

◆ isValidSetup()

template<class Scalar >
bool Tempus::StepperImplicit< Scalar >::isValidSetup ( Teuchos::FancyOStream &  out) const
overridevirtual

◆ getValidParameters()

template<class Scalar >
Teuchos::RCP< const Teuchos::ParameterList > Tempus::StepperImplicit< Scalar >::getValidParameters
overridevirtual

◆ getValidParametersBasicImplicit()

template<class Scalar >
Teuchos::RCP< Teuchos::ParameterList > Tempus::StepperImplicit< Scalar >::getValidParametersBasicImplicit

Definition at line 372 of file Tempus_StepperImplicit_impl.hpp.

◆ setStepperImplicitValues()

template<class Scalar >
void Tempus::StepperImplicit< Scalar >::setStepperImplicitValues ( Teuchos::RCP< Teuchos::ParameterList >  pl)

Set StepperImplicit member data from the ParameterList.

Definition at line 387 of file Tempus_StepperImplicit_impl.hpp.

◆ setStepperSolverValues()

template<class Scalar >
void Tempus::StepperImplicit< Scalar >::setStepperSolverValues ( Teuchos::RCP< Teuchos::ParameterList >  pl)

Set solver from ParameterList.

Definition at line 402 of file Tempus_StepperImplicit_impl.hpp.

◆ setSolverName()

template<class Scalar >
void Tempus::StepperImplicit< Scalar >::setSolverName ( std::string  i)
inline

Set the Solver Name.

Definition at line 322 of file Tempus_StepperImplicit_decl.hpp.

◆ getSolverName()

template<class Scalar >
std::string Tempus::StepperImplicit< Scalar >::getSolverName ( ) const
inline

Get the Solver Name.

Definition at line 324 of file Tempus_StepperImplicit_decl.hpp.

Member Data Documentation

◆ wrapperModel_

template<class Scalar >
Teuchos::RCP<WrapperModelEvaluator<Scalar> > Tempus::StepperImplicit< Scalar >::wrapperModel_
protected

Definition at line 328 of file Tempus_StepperImplicit_decl.hpp.

◆ solver_

template<class Scalar >
Teuchos::RCP<Thyra::NonlinearSolverBase<Scalar> > Tempus::StepperImplicit< Scalar >::solver_
protected

Definition at line 329 of file Tempus_StepperImplicit_decl.hpp.

◆ initialGuess_

template<class Scalar >
Teuchos::RCP<const Thyra::VectorBase<Scalar> > Tempus::StepperImplicit< Scalar >::initialGuess_
protected

Definition at line 330 of file Tempus_StepperImplicit_decl.hpp.

◆ zeroInitialGuess_

template<class Scalar >
bool Tempus::StepperImplicit< Scalar >::zeroInitialGuess_
protected

Definition at line 331 of file Tempus_StepperImplicit_decl.hpp.

◆ solverName_

template<class Scalar >
std::string Tempus::StepperImplicit< Scalar >::solverName_
protected

Definition at line 332 of file Tempus_StepperImplicit_decl.hpp.


The documentation for this class was generated from the following files: