Tempus  Version of the Day
Time Integration
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Tempus_IntegratorForwardSensitivity_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_IntegratorForwardSensitivity_decl_hpp
10 #define Tempus_IntegratorForwardSensitivity_decl_hpp
11 
12 // Tempus
13 #include "Tempus_IntegratorBasic.hpp"
15 #include "Tempus_StepperStaggeredForwardSensitivity.hpp"
16 
17 namespace Tempus {
18 
19 
20 /** \brief Time integrator implementing forward sensitivity analysis */
21 /**
22  * This integrator implements forward parameter sensitivity analysis by
23  * propagating the derivative of the solution with respect to model parameters
24  * alongside the solution. It supports sensitivity propagation methods:
25  * <ul>
26  * <li> "Combined" where the sensitivity and state equations are solved
27  * simultaneously. This is most appropriate for explicit time
28  * integration methods or implicit methods where a very-lightweight
29  * nonlinear solution strategy is used.
30  * <li> "Staggered" where the sensitivity equations are solved at each time
31  * step immediately after the state equations are solved. This is
32  * useful for implicit methods since it saves the cost of solving the
33  * sensitivity equations while the state equations are being solved. It
34  * generally does not work for explicit methods (and wouldn't be more
35  * efficient than the combined method even if it did).
36  * </ul>
37  *
38  * Note that this integrator implements all of the same functions as the
39  * IntegratorBasic, but is not derived from IntegratorBasic. It also provides
40  * functions for setting the sensitivity initial conditions and extracting the
41  * sensitivity at the final time. Also the vectors stored in the solution
42  * history store product vectors of the state and sensitivities using
43  * Thyra;:DefaultMultiVectorProductVector.
44  */
45 template<class Scalar>
46 class IntegratorForwardSensitivity : virtual public Tempus::Integrator<Scalar>
47 {
48 public:
49 
50  /** \brief Constructor with ParameterList and model, and will be fully
51  * initialized. */
52  /*!
53  * In addition to all of the regular integrator options, the supplied
54  * parameter list supports the following options contained within a sublist
55  * "Sensitivities" from the top-level parameter list:
56  * <ul>
57  * <li> "Sensitivity Method" (default: "Combined") The sensitivity
58  * analysis method as described above.
59  * <li> "Reuse State Linear Solver" (default: false) For the staggered
60  * method, whether to reuse the model's W matrix, solver, and
61  * preconditioner when solving the sensitivity equations. If they
62  * can be reused, substantial savings in compute time are possible.
63  * <li> "Use DfDp as Tangent" (default: false) Reinterpret the df/dp
64  * out-arg as the tangent vector (df/dx)(x,p) * dx/dp + df/dp(x,p)
65  * as described in the Tempus::CombinedForwardSensitivityModelEvaluator
66  * documentation.
67  * <li> "Sensitivity Parameter Index" (default: 0) Model evaluator
68  * parameter index for which sensitivities will be computed.
69  * <li> "Sensitivity X Tangent Index" (default: 1) If "Use DfDp as Tangent"
70  * is true, the model evaluator parameter index for passing dx/dp
71  * as a Thyra::DefaultMultiVectorProductVector.
72  * <li> "Sensitivity X-Dot Tangent Index" (default: 2) If
73  * "Use DfDp as Tangent" is true, the model evaluator parameter index
74  * for passing dx_dot/dp as a Thyra::DefaultMultiVectorProductVector.
75  * <li> "Sensitivity X-Dot-Dot Tangent Index" (default: 3) If
76  * "Use DfDp as Tangent" is true, the model evaluator parameter index
77  * for passing dx_dot_dot/dp as a
78  * Thyra::DefaultMultiVectorProductVector (if the model supports
79  * x_dot_dot).
80  * </ul>
81  */
83  Teuchos::RCP<Teuchos::ParameterList> pList,
84  const Teuchos::RCP<Thyra::ModelEvaluator<Scalar> >& model);
85 
86  /** \brief Constructor with model and "Stepper Type" and is fully initialized with default settings. */
88  const Teuchos::RCP<Thyra::ModelEvaluator<Scalar> >& model,
89  std::string stepperType);
90 
91  /// Destructor
92  /** \brief Constructor that requires a subsequent setParameterList, setStepper, and initialize calls. */
94 
95  /// Destructor
97 
98  /// \name Basic integrator methods
99  //@{
100  /// Advance the solution to timeMax, and return true if successful.
101  virtual bool advanceTime()
102  { return integrator_->advanceTime(); }
103  /// Advance the solution to timeFinal, and return true if successful.
104  virtual bool advanceTime(const Scalar timeFinal) override
105  { return integrator_->advanceTime(timeFinal); }
106  /// Perform tasks before start of integrator.
107  virtual void startIntegrator()
108  { integrator_->startIntegrator(); }
109  /// Start time step.
110  virtual void startTimeStep()
111  { integrator_->startTimeStep(); }
112  /// Check if time step has passed or failed.
113  virtual void checkTimeStep()
114  { integrator_->checkTimeStep(); }
115  /// Perform tasks after end of integrator.
116  virtual void endIntegrator()
117  { integrator_->endIntegrator(); }
118  /// Return a copy of the Tempus ParameterList
119  virtual Teuchos::RCP<Teuchos::ParameterList> getTempusParameterList() override
120  { return integrator_->getTempusParameterList(); }
121  virtual void setTempusParameterList(Teuchos::RCP<Teuchos::ParameterList> pl) override
122  { integrator_->setTempusParameterList(pl); }
123  //@}
124 
125  /// \name Accessor methods
126  //@{
127  /// Get current time
128  virtual Scalar getTime() const override
129  { return integrator_->getTime(); }
130  /// Get current index
131  virtual Scalar getIndex() const override
132  { return integrator_->getIndex(); }
133  /// Get Status
134  virtual Status getStatus() const override
135  { return integrator_->getStatus(); }
136  /// Get the Stepper
137  virtual Teuchos::RCP<Stepper<Scalar> > getStepper() const override
138  { return integrator_->getStepper(); }
139 
140  /// Set the Stepper
141  virtual void setStepper(Teuchos::RCP<Thyra::ModelEvaluator<Scalar> > model);
142 
143  /// Set the Stepper
144  virtual void setStepperWStepper(Teuchos::RCP<Stepper<Scalar> > stepper)
145  { integrator_->setStepperWStepper(stepper); }
146  /// Set the initial state which has the initial conditions
148  Teuchos::RCP<SolutionState<Scalar> > state = Teuchos::null)
149  { integrator_->initializeSolutionHistory(state); }
150 
151  /// Set the initial state from Thyra::VectorBase(s)
152  virtual void initializeSolutionHistory(
153  Scalar t0,
154  Teuchos::RCP<const Thyra::VectorBase<Scalar> > x0,
155  Teuchos::RCP<const Thyra::VectorBase<Scalar> > xdot0 = Teuchos::null,
156  Teuchos::RCP<const Thyra::VectorBase<Scalar> > xdotdot0 = Teuchos::null,
157  Teuchos::RCP<const Thyra::MultiVectorBase<Scalar> > DxDp0 = Teuchos::null,
158  Teuchos::RCP<const Thyra::MultiVectorBase<Scalar> > DxdotDp0 = Teuchos::null,
159  Teuchos::RCP<const Thyra::MultiVectorBase<Scalar> > DxdotdotDp0 = Teuchos::null);
160 
161  /// Get the SolutionHistory
162  virtual Teuchos::RCP<const SolutionHistory<Scalar> > getSolutionHistory() const override
163  { return integrator_->getSolutionHistory(); }
164  /// Set the SolutionHistory
165  virtual void setSolutionHistory(
166  Teuchos::RCP<SolutionHistory<Scalar> > sh = Teuchos::null)
167  { integrator_->setSolutionHistory(sh); }
168  /// Get the TimeStepControl
169  virtual Teuchos::RCP<const TimeStepControl<Scalar> > getTimeStepControl() const override
170  { return integrator_->getTimeStepControl(); }
171  /// Set the TimeStepControl
172  virtual void setTimeStepControl(
173  Teuchos::RCP<TimeStepControl<Scalar> > tsc = Teuchos::null)
174  { integrator_->setTimeStepControl(tsc); }
175  /// Get the Observer
176  virtual Teuchos::RCP<IntegratorObserver<Scalar> > getObserver()
177  { return integrator_->getObserver(); }
178  /// Set the Observer
179  virtual void setObserver(
180  Teuchos::RCP<IntegratorObserver<Scalar> > obs = Teuchos::null)
181  { integrator_->setObserver(obs); }
182  /// Initializes the Integrator after set* function calls
183  virtual void initialize()
184  { integrator_->initialize(); }
185  virtual Teuchos::RCP<Teuchos::Time> getIntegratorTimer() const override
186  { return integrator_->getIntegratorTimer(); }
187  virtual Teuchos::RCP<Teuchos::Time> getStepperTimer() const override
188  { return integrator_->getStepperTimer(); }
189 
190  /// Get current the solution, x
191  virtual Teuchos::RCP<const Thyra::VectorBase<Scalar> > getX() const;
192  virtual Teuchos::RCP<const Thyra::MultiVectorBase<Scalar> > getDxDp() const;
193  /// Get current the time derivative of the solution, xdot
194  virtual Teuchos::RCP<const Thyra::VectorBase<Scalar> > getXdot() const;
195  virtual Teuchos::RCP<const Thyra::MultiVectorBase<Scalar> > getDxdotDp() const;
196  /// Get current the second time derivative of the solution, xdotdot
197  virtual Teuchos::RCP<const Thyra::VectorBase<Scalar> > getXdotdot() const;
198  virtual Teuchos::RCP<const Thyra::MultiVectorBase<Scalar> > getDxdotdotDp() const;
199 
200  /// Get current state
201  virtual Teuchos::RCP<SolutionState<Scalar> > getCurrentState()
202  {return integrator_->getCurrentState();}
203  //@}
204 
205  /// Parse when screen output should be executed
206  void parseScreenOutput() { integrator_->parseScreenOutput(); }
207 
208  /// \name Overridden from Teuchos::ParameterListAcceptor
209  //@{
210  void setParameterList(const Teuchos::RCP<Teuchos::ParameterList> & pl)
211  override;
212  Teuchos::RCP<Teuchos::ParameterList> getNonconstParameterList() override
213  { return tempus_pl_; }
214  Teuchos::RCP<Teuchos::ParameterList> unsetParameterList() override;
215 
216  Teuchos::RCP<const Teuchos::ParameterList> getValidParameters()
217  const override;
218  //@}
219 
220  /// \name Overridden from Teuchos::Describable
221  //@{
222  std::string description() const override;
223  void describe(Teuchos::FancyOStream & out,
224  const Teuchos::EVerbosityLevel verbLevel) const override;
225  //@}
226 
227 protected:
228 
229  // Create sensitivity model evaluator from application model
230  void
232  const Teuchos::RCP<Thyra::ModelEvaluator<Scalar> >& model);
233 
234  Teuchos::RCP<Thyra::ModelEvaluator<Scalar> > model_;
235  Teuchos::RCP<SensitivityModelEvaluatorBase<Scalar> > sens_model_;
236  Teuchos::RCP<StepperStaggeredForwardSensitivity<Scalar> > sens_stepper_;
237  Teuchos::RCP<IntegratorBasic<Scalar> > integrator_;
238  Teuchos::RCP<Teuchos::ParameterList> tempus_pl_;
239  Teuchos::RCP<Teuchos::ParameterList> sens_pl_;
240  Teuchos::RCP<Teuchos::ParameterList> stepper_pl_;
242 };
243 
244 /// Non-member constructor
245 template<class Scalar>
246 Teuchos::RCP<Tempus::IntegratorForwardSensitivity<Scalar> >
248  Teuchos::RCP<Teuchos::ParameterList> pList,
249  const Teuchos::RCP<Thyra::ModelEvaluator<Scalar> >& model);
250 
251 /// Non-member constructor
252 template<class Scalar>
253 Teuchos::RCP<Tempus::IntegratorForwardSensitivity<Scalar> >
255  const Teuchos::RCP<Thyra::ModelEvaluator<Scalar> >& model,
256  std::string stepperType);
257 
258 /// Non-member constructor
259 template<class Scalar>
260 Teuchos::RCP<Tempus::IntegratorForwardSensitivity<Scalar> >
262 
263 } // namespace Tempus
264 
265 #endif // Tempus_IntegratorForwardSensitivity_decl_hpp
virtual Teuchos::RCP< const SolutionHistory< Scalar > > getSolutionHistory() const override
Get the SolutionHistory.
Teuchos::RCP< IntegratorBasic< Scalar > > integrator_
virtual Teuchos::RCP< Teuchos::Time > getIntegratorTimer() const override
Returns the IntegratorTimer_ for this Integrator.
virtual bool advanceTime()
Advance the solution to timeMax, and return true if successful.
virtual Teuchos::RCP< const Thyra::VectorBase< Scalar > > getXdot() const
Get current the time derivative of the solution, xdot.
virtual void initializeSolutionHistory(Teuchos::RCP< SolutionState< Scalar > > state=Teuchos::null)
Set the initial state which has the initial conditions.
virtual Scalar getIndex() const override
Get current index.
virtual void setTimeStepControl(Teuchos::RCP< TimeStepControl< Scalar > > tsc=Teuchos::null)
Set the TimeStepControl.
virtual Teuchos::RCP< IntegratorObserver< Scalar > > getObserver()
Get the Observer.
virtual Teuchos::RCP< const TimeStepControl< Scalar > > getTimeStepControl() const override
Get the TimeStepControl.
virtual void endIntegrator()
Perform tasks after end of integrator.
virtual void setSolutionHistory(Teuchos::RCP< SolutionHistory< Scalar > > sh=Teuchos::null)
Set the SolutionHistory.
virtual Teuchos::RCP< const Thyra::MultiVectorBase< Scalar > > getDxdotDp() const
Teuchos::RCP< StepperStaggeredForwardSensitivity< Scalar > > sens_stepper_
virtual void setStepper(Teuchos::RCP< Thyra::ModelEvaluator< Scalar > > model)
Set the Stepper.
Teuchos::RCP< Teuchos::ParameterList > unsetParameterList() override
virtual Teuchos::RCP< const Thyra::MultiVectorBase< Scalar > > getDxdotdotDp() const
virtual Teuchos::RCP< const Thyra::VectorBase< Scalar > > getXdotdot() const
Get current the second time derivative of the solution, xdotdot.
virtual Teuchos::RCP< SolutionState< Scalar > > getCurrentState()
Get current state.
virtual Status getStatus() const override
Get Status.
virtual Teuchos::RCP< Teuchos::ParameterList > getTempusParameterList() override
Return a copy of the Tempus ParameterList.
Thyra Base interface for time steppers.
void createSensitivityModelAndStepper(const Teuchos::RCP< Thyra::ModelEvaluator< Scalar > > &model)
virtual void startIntegrator()
Perform tasks before start of integrator.
virtual void checkTimeStep()
Check if time step has passed or failed.
virtual Teuchos::RCP< Teuchos::Time > getStepperTimer() const override
virtual Teuchos::RCP< const Thyra::MultiVectorBase< Scalar > > getDxDp() const
virtual void initialize()
Initializes the Integrator after set* function calls.
virtual Teuchos::RCP< Stepper< Scalar > > getStepper() const override
Get the Stepper.
void setParameterList(const Teuchos::RCP< Teuchos::ParameterList > &pl) override
Teuchos::RCP< Thyra::ModelEvaluator< Scalar > > model_
Status
Status for the Integrator, the Stepper and the SolutionState.
IntegratorObserver class for time integrators.
TimeStepControl manages the time step size. There several mechanicisms that effect the time step size...
SolutionHistory is basically a container of SolutionStates. SolutionHistory maintains a collection of...
void parseScreenOutput()
Parse when screen output should be executed.
virtual Scalar getTime() const override
Get current time.
void describe(Teuchos::FancyOStream &out, const Teuchos::EVerbosityLevel verbLevel) const override
Teuchos::RCP< Tempus::IntegratorForwardSensitivity< Scalar > > integratorForwardSensitivity(Teuchos::RCP< Teuchos::ParameterList > pList, const Teuchos::RCP< Thyra::ModelEvaluator< Scalar > > &model)
Non-member constructor.
virtual Teuchos::RCP< const Thyra::VectorBase< Scalar > > getX() const
Get current the solution, x.
Thyra Base interface for time integrators. Time integrators are designed to advance the solution from...
virtual void setStepperWStepper(Teuchos::RCP< Stepper< Scalar > > stepper)
Set the Stepper.
virtual void setTempusParameterList(Teuchos::RCP< Teuchos::ParameterList > pl) override
virtual void setObserver(Teuchos::RCP< IntegratorObserver< Scalar > > obs=Teuchos::null)
Set the Observer.
Teuchos::RCP< SensitivityModelEvaluatorBase< Scalar > > sens_model_
Time integrator implementing forward sensitivity analysis.
virtual bool advanceTime(const Scalar timeFinal) override
Advance the solution to timeFinal, and return true if successful.
Solution state for integrators and steppers. SolutionState contains the metadata for solutions and th...
Teuchos::RCP< const Teuchos::ParameterList > getValidParameters() const override
Teuchos::RCP< Teuchos::ParameterList > getNonconstParameterList() override