Tempus  Version of the Day
Time Integration
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Tempus_StepperBackwardEuler_decl.hpp
Go to the documentation of this file.
1 // @HEADER
2 // ****************************************************************************
3 // Tempus: Copyright (2017) Sandia Corporation
4 //
5 // Distributed under BSD 3-clause license (See accompanying file Copyright.txt)
6 // ****************************************************************************
7 // @HEADER
8 
9 #ifndef Tempus_StepperBackwardEuler_decl_hpp
10 #define Tempus_StepperBackwardEuler_decl_hpp
11 
12 #include "Tempus_StepperImplicit.hpp"
14 #ifndef TEMPUS_HIDE_DEPRECATED_CODE
16 #endif
19 
20 
21 namespace Tempus {
22 
23 /** \brief Backward Euler time stepper.
24  *
25  * For the implicit ODE system, \f$\mathcal{F}(\dot{x},x,t) = 0\f$,
26  * the solution, \f$\dot{x}\f$ and \f$x\f$, is determined using a
27  * solver (e.g., a non-linear solver, like NOX).
28  *
29  * <b> Algorithm </b>
30  * The single-timestep algorithm for Backward Euler is
31  *
32  * \f{algorithm}{
33  * \renewcommand{\thealgorithm}{}
34  * \caption{Backward Euler}
35  * \begin{algorithmic}[1]
36  * \State {\it appAction.execute(solutionHistory, stepper, BEGIN\_STEP)}
37  * \State Compute the predictor (e.g., apply stepper to $x_n$).
38  * \State {\it appAction.execute(solutionHistory, stepper, BEFORE\_SOLVE)}
39  * \State Solve $\mathcal{F}_n(\dot{x}=(x_n-x_{n-1})/\Delta t_n, x_n, t_n)=0$ for $x_n$
40  * \State {\it appAction.execute(solutionHistory, stepper, AFTER\_SOLVE)}
41  * \State $\dot{x}_n \leftarrow (x_n-x_{n-1})/\Delta t_n$
42  * \State {\it appAction.execute(solutionHistory, stepper, END\_STEP)}
43  * \end{algorithmic}
44  * \f}
45  *
46  * The First-Step-As-Last (FSAL) principle is not needed with Backward Euler.
47  * The default is to set useFSAL=false, however useFSAL=true will also work
48  * but have no affect (i.e., no-op).
49  *
50  * <b> Iteration Matrix, \f$W\f$.</b>
51  * Recalling that the definition of the iteration matrix, \f$W\f$, is
52  * \f[
53  * W = \alpha \frac{\partial \mathcal{F}_n}{\partial \dot{x}_n}
54  * + \beta \frac{\partial \mathcal{F}_n}{\partial x_n},
55  * \f]
56  * where \f$ \alpha \equiv \frac{\partial \dot{x}_n(x_n) }{\partial x_n}, \f$
57  * and \f$ \beta \equiv \frac{\partial x_n}{\partial x_n} = 1\f$, and
58  * the time derivative for Backward Euler is
59  * \f[
60  * \dot{x}_n(x_n) = \frac{x_n - x_{n-1}}{\Delta t},
61  * \f]
62  * we can determine that
63  * \f$ \alpha = \frac{1}{\Delta t} \f$
64  * and \f$ \beta = 1 \f$, and therefore write
65  * \f[
66  * W = \frac{1}{\Delta t}
67  * \frac{\partial \mathcal{F}_n}{\partial \dot{x}_n}
68  * + \frac{\partial \mathcal{F}_n}{\partial x_n}.
69  * \f]
70  */
71 template<class Scalar>
73  virtual public Tempus::StepperImplicit<Scalar>,
74  virtual public Tempus::StepperOptimizationInterface<Scalar>
75 {
76 public:
77 
78  /** \brief Default constructor.
79  *
80  * Requires subsequent setModel(), setSolver() and initialize()
81  * calls before calling takeStep().
82  */
84 
85 #ifndef TEMPUS_HIDE_DEPRECATED_CODE
86  /// Constructor
88  const Teuchos::RCP<const Thyra::ModelEvaluator<Scalar> >& appModel,
89  const Teuchos::RCP<StepperObserver<Scalar> >& obs,
90  const Teuchos::RCP<Thyra::NonlinearSolverBase<Scalar> >& solver,
91  const Teuchos::RCP<Stepper<Scalar> >& predictorStepper,
92  bool useFSAL,
93  std::string ICConsistency,
94  bool ICConsistencyCheck,
95  bool zeroInitialGuess);
96 #endif
97 
98  /// Constructor
100  const Teuchos::RCP<const Thyra::ModelEvaluator<Scalar> >& appModel,
101  const Teuchos::RCP<Thyra::NonlinearSolverBase<Scalar> >& solver,
102  const Teuchos::RCP<Stepper<Scalar> >& predictorStepper,
103  bool useFSAL,
104  std::string ICConsistency,
105  bool ICConsistencyCheck,
106  bool zeroInitialGuess,
107  const Teuchos::RCP<StepperBackwardEulerAppAction<Scalar> >& stepperBEAppAction);
108 
109  /// \name Basic stepper methods
110  //@{
111 #ifndef TEMPUS_HIDE_DEPRECATED_CODE
112  virtual void setObserver(
113  Teuchos::RCP<StepperObserver<Scalar> > obs = Teuchos::null);
114 
115  virtual Teuchos::RCP<StepperObserver<Scalar> > getObserver() const
116  { return stepperBEObserver_; }
117 #endif
118 
119  virtual void setAppAction(
120  Teuchos::RCP<StepperBackwardEulerAppAction<Scalar> > appAction);
121 
122  virtual Teuchos::RCP<StepperBackwardEulerAppAction<Scalar> > getAppAction() const
123  { return stepperBEAppAction_; }
124 
125  /// Set the predictor
126  void setPredictor(std::string predictorType = "None");
127  void setPredictor(Teuchos::RCP<Stepper<Scalar> > predictorStepper);
128 
129  /// Set the initial conditions and make them consistent.
130  virtual void setInitialConditions (
131  const Teuchos::RCP<SolutionHistory<Scalar> >& solutionHistory);
132 
133  /// Take the specified timestep, dt, and return true if successful.
134  virtual void takeStep(
135  const Teuchos::RCP<SolutionHistory<Scalar> >& solutionHistory);
136 
137  /// Get a default (initial) StepperState
138  virtual Teuchos::RCP<Tempus::StepperState<Scalar> > getDefaultStepperState();
139  virtual Scalar getOrder() const {return 1.0;}
140  virtual Scalar getOrderMin() const {return 1.0;}
141  virtual Scalar getOrderMax() const {return 1.0;}
142 
143  virtual bool isExplicit() const {return false;}
144  virtual bool isImplicit() const {return true;}
145  virtual bool isExplicitImplicit() const
146  {return isExplicit() and isImplicit();}
147  virtual bool isOneStepMethod() const {return true;}
148  virtual bool isMultiStepMethod() const {return !isOneStepMethod();}
149 
150  virtual OrderODE getOrderODE() const {return FIRST_ORDER_ODE;}
151  //@}
152 
153  /// Return alpha = d(xDot)/dx.
154  virtual Scalar getAlpha(const Scalar dt) const { return Scalar(1.0)/dt; }
155  /// Return beta = d(x)/dx.
156  virtual Scalar getBeta (const Scalar ) const { return Scalar(1.0); }
157 
158  /// Compute predictor given the supplied stepper
159  virtual void computePredictor(
160  const Teuchos::RCP<SolutionHistory<Scalar> >& solutionHistory);
161 
162  Teuchos::RCP<const Teuchos::ParameterList> getValidParameters() const;
163 
164  /// \name Overridden from Teuchos::Describable
165  //@{
166  virtual void describe(Teuchos::FancyOStream & out,
167  const Teuchos::EVerbosityLevel verbLevel) const;
168  //@}
169 
170  virtual bool isValidSetup(Teuchos::FancyOStream & out) const;
171 
172  /// \name Implementation of StepperOptimizationInterface
173  //@{
174  virtual int stencilLength() const;
175  virtual void computeStepResidual(
176  Thyra::VectorBase<Scalar>& residual,
177  const Teuchos::Array< Teuchos::RCP<const Thyra::VectorBase<Scalar> > >& x,
178  const Teuchos::Array<Scalar>& t,
179  const Thyra::VectorBase<Scalar>& p,
180  const int param_index) const;
181  virtual void computeStepJacobian(
182  Thyra::LinearOpBase<Scalar>& jacobian,
183  const Teuchos::Array< Teuchos::RCP<const Thyra::VectorBase<Scalar> > >& x,
184  const Teuchos::Array<Scalar>& t,
185  const Thyra::VectorBase<Scalar>& p,
186  const int param_index,
187  const int deriv_index) const;
188  virtual void computeStepParamDeriv(
189  Thyra::LinearOpBase<Scalar>& deriv,
190  const Teuchos::Array< Teuchos::RCP<const Thyra::VectorBase<Scalar> > >& x,
191  const Teuchos::Array<Scalar>& t,
192  const Thyra::VectorBase<Scalar>& p,
193  const int param_index) const;
194  virtual void computeStepSolver(
195  Thyra::LinearOpWithSolveBase<Scalar>& jacobian_solver,
196  const Teuchos::Array< Teuchos::RCP<const Thyra::VectorBase<Scalar> > >& x,
197  const Teuchos::Array<Scalar>& t,
198  const Thyra::VectorBase<Scalar>& p,
199  const int param_index) const;
200  //@}
201 
202 private:
203 
204  /// Implementation of computeStep*() methods
206  const Thyra::ModelEvaluatorBase::OutArgs<Scalar>& outArgs,
207  const Teuchos::Array< Teuchos::RCP<const Thyra::VectorBase<Scalar> > >& x,
208  const Teuchos::Array<Scalar>& t,
209  const Thyra::VectorBase<Scalar>& p,
210  const int param_index,
211  const int deriv_index = 0) const;
212 
213 private:
214 
215  Teuchos::RCP<Stepper<Scalar> > predictorStepper_;
216 #ifndef TEMPUS_HIDE_DEPRECATED_CODE
217  Teuchos::RCP<StepperBackwardEulerObserver<Scalar> > stepperBEObserver_;
218 #endif
219  Teuchos::RCP<StepperBackwardEulerAppAction<Scalar> > stepperBEAppAction_;
220 
221 };
222 
223 /** \brief Time-derivative interface for Backward Euler.
224  *
225  * Given the state \f$x\f$, compute the Backward Euler time-derivative,
226  * \f[
227  * \dot{x}_{n} = \frac{(x_{n} - x_{n-1})}{\Delta t_{n}}.
228  * \f]
229  * \f$\ddot{x}\f$ is not used and set to null.
230  */
231 template <typename Scalar>
233  : virtual public Tempus::TimeDerivative<Scalar>
234 {
235 public:
236 
237  /// Constructor
239  Scalar s, Teuchos::RCP<const Thyra::VectorBase<Scalar> > xOld)
240  { initialize(s, xOld); }
241 
242  /// Destructor
244 
245  /// Compute the time derivative.
246  virtual void compute(
247  Teuchos::RCP<const Thyra::VectorBase<Scalar> > x,
248  Teuchos::RCP< Thyra::VectorBase<Scalar> > xDot,
249  Teuchos::RCP< Thyra::VectorBase<Scalar> > xDotDot = Teuchos::null)
250  {
251  xDotDot = Teuchos::null;
252  // Calculate the Backward Euler x dot vector
253  Thyra::V_StVpStV(xDot.ptr(),s_,*x,-s_,*xOld_);
254  }
255 
256  virtual void initialize(Scalar s,
257  Teuchos::RCP<const Thyra::VectorBase<Scalar> > xOld)
258  { s_ = s; xOld_ = xOld; }
259 
260 private:
261 
262  Teuchos::RCP<const Thyra::VectorBase<Scalar> > xOld_;
263  Scalar s_; // = 1.0/dt
264 };
265 
266 
267 } // namespace Tempus
268 
269 #endif // Tempus_StepperBackwardEuler_decl_hpp
Teuchos::RCP< const Thyra::VectorBase< Scalar > > xOld_
Teuchos::RCP< const Teuchos::ParameterList > getValidParameters() const
Teuchos::RCP< StepperBackwardEulerAppAction< Scalar > > stepperBEAppAction_
void computeStepResidDerivImpl(const Thyra::ModelEvaluatorBase::OutArgs< Scalar > &outArgs, const Teuchos::Array< Teuchos::RCP< const Thyra::VectorBase< Scalar > > > &x, const Teuchos::Array< Scalar > &t, const Thyra::VectorBase< Scalar > &p, const int param_index, const int deriv_index=0) const
Implementation of computeStep*() methods.
virtual void computeStepResidual(Thyra::VectorBase< Scalar > &residual, const Teuchos::Array< Teuchos::RCP< const Thyra::VectorBase< Scalar > > > &x, const Teuchos::Array< Scalar > &t, const Thyra::VectorBase< Scalar > &p, const int param_index) const
Compute time step residual.
virtual void compute(Teuchos::RCP< const Thyra::VectorBase< Scalar > > x, Teuchos::RCP< Thyra::VectorBase< Scalar > > xDot, Teuchos::RCP< Thyra::VectorBase< Scalar > > xDotDot=Teuchos::null)
Compute the time derivative.
virtual void takeStep(const Teuchos::RCP< SolutionHistory< Scalar > > &solutionHistory)
Take the specified timestep, dt, and return true if successful.
virtual void computePredictor(const Teuchos::RCP< SolutionHistory< Scalar > > &solutionHistory)
Compute predictor given the supplied stepper.
virtual int stencilLength() const
Return the number of solution vectors in the time step stencil.
virtual Scalar getBeta(const Scalar) const
Return beta = d(x)/dx.
virtual Teuchos::RCP< Tempus::StepperState< Scalar > > getDefaultStepperState()
Get a default (initial) StepperState.
Application Action for StepperBackwardEuler.
virtual void setObserver(Teuchos::RCP< StepperObserver< Scalar > > obs=Teuchos::null)
Set Observer.
Thyra Base interface for time steppers.
virtual void computeStepSolver(Thyra::LinearOpWithSolveBase< Scalar > &jacobian_solver, const Teuchos::Array< Teuchos::RCP< const Thyra::VectorBase< Scalar > > > &x, const Teuchos::Array< Scalar > &t, const Thyra::VectorBase< Scalar > &p, const int param_index) const
Compute time step Jacobian solver.
Thyra Base interface for implicit time steppers.
virtual void computeStepJacobian(Thyra::LinearOpBase< Scalar > &jacobian, const Teuchos::Array< Teuchos::RCP< const Thyra::VectorBase< Scalar > > > &x, const Teuchos::Array< Scalar > &t, const Thyra::VectorBase< Scalar > &p, const int param_index, const int deriv_index) const
Compute time step Jacobian.
virtual void computeStepParamDeriv(Thyra::LinearOpBase< Scalar > &deriv, const Teuchos::Array< Teuchos::RCP< const Thyra::VectorBase< Scalar > > > &x, const Teuchos::Array< Scalar > &t, const Thyra::VectorBase< Scalar > &p, const int param_index) const
Compute time step derivative w.r.t. model parameters.
void setPredictor(std::string predictorType="None")
Set the predictor.
StepperObserver class for Stepper class.
virtual Scalar getAlpha(const Scalar dt) const
Return alpha = d(xDot)/dx.
SolutionHistory is basically a container of SolutionStates. SolutionHistory maintains a collection of...
virtual Teuchos::RCP< StepperObserver< Scalar > > getObserver() const
Get Observer.
Teuchos::RCP< Stepper< Scalar > > predictorStepper_
virtual void setAppAction(Teuchos::RCP< StepperBackwardEulerAppAction< Scalar > > appAction)
Stepper integrates first-order ODEs.
StepperBackwardEulerTimeDerivative(Scalar s, Teuchos::RCP< const Thyra::VectorBase< Scalar > > xOld)
Constructor.
virtual bool isValidSetup(Teuchos::FancyOStream &out) const
virtual Teuchos::RCP< StepperBackwardEulerAppAction< Scalar > > getAppAction() const
This interface defines the time derivative connection between an implicit Stepper and WrapperModelEva...
virtual void setInitialConditions(const Teuchos::RCP< SolutionHistory< Scalar > > &solutionHistory)
Set the initial conditions and make them consistent.
virtual void describe(Teuchos::FancyOStream &out, const Teuchos::EVerbosityLevel verbLevel) const
Teuchos::RCP< StepperBackwardEulerObserver< Scalar > > stepperBEObserver_
virtual void initialize(Scalar s, Teuchos::RCP< const Thyra::VectorBase< Scalar > > xOld)
Stepper interface to support full-space optimization.
Time-derivative interface for Backward Euler.