Tempus  Version of the Day
Time Integration
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Tempus_Stepper_impl.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_Stepper_impl_hpp
10 #define Tempus_Stepper_impl_hpp
11 
12 
13 namespace Tempus {
14 
15 
16 template<class Scalar>
17 void Stepper<Scalar>::getValidParametersBasic(
18  Teuchos::RCP<Teuchos::ParameterList> pl) const
19 {
20  pl->set<bool>("Use FSAL", false,
21  "The First-Step-As-Last (FSAL) principle is the situation where the\n"
22  "last function evaluation, f(x^{n-1},t^{n-1}) [a.k.a. xDot^{n-1}],\n"
23  "can be used for the first function evaluation, f(x^n,t^n)\n"
24  "[a.k.a. xDot^n]. For RK methods, this applies to the stages.\n"
25  "\n"
26  "Often the FSAL priniciple can be used to save an evaluation.\n"
27  "However there are cases when it cannot be used, e.g., operator\n"
28  "splitting where other steppers/operators have modified the solution,\n"
29  "x^*, and thus require the function evaluation, f(x^*, t^{n-1}).\n"
30  "\n"
31  "It should be noted that when the FSAL priniciple can be used\n"
32  "(can set useFSAL=true), setting useFSAL=false will give the\n"
33  "same solution but at additional expense. However, the reverse\n"
34  "is not true. When the FSAL priniciple can not be used\n"
35  "(need to set useFSAL=false), setting useFSAL=true will produce\n"
36  "incorrect solutions.\n"
37  "\n"
38  "Default in general for explicit and implicit steppers is false,\n"
39  "but individual steppers can override this default.\n");
40 
41  pl->set<std::string>("Initial Condition Consistency", "None",
42  "This indicates which type of consistency should be applied to\n"
43  "the initial conditions (ICs):\n"
44  "\n"
45  " 'None' - Do nothing to the ICs provided in the SolutionHistory.\n"
46  " 'Zero' - Set the derivative of the SolutionState to zero in the\n"
47  " SolutionHistory provided, e.g., xDot^0 = 0, or \n"
48  " xDotDot^0 = 0.\n"
49  " 'App' - Use the application's ICs, e.g., getNominalValues().\n"
50  " 'Consistent' - Make the initial conditions for x and xDot\n"
51  " consistent with the governing equations, e.g.,\n"
52  " xDot = f(x,t), and f(x, xDot, t) = 0. For implicit\n"
53  " ODEs, this requires a solve of f(x, xDot, t) = 0 for\n"
54  " xDot, and another Jacobian and residual may be\n"
55  " needed, e.g., boundary conditions on xDot may need\n"
56  " to replace boundary conditions on x.\n"
57  "\n"
58  "In general for explicit steppers, the default is 'Consistent',\n"
59  "because it is fairly cheap with just one residual evaluation.\n"
60  "In general for implicit steppers, the default is 'None', because\n"
61  "the application often knows its IC and can set it the initial\n"
62  "SolutionState. Also, as noted above, 'Consistent' may require\n"
63  "another Jacobian from the application. Individual steppers may\n"
64  "override these defaults.\n");
65 
66  pl->set<bool>("Initial Condition Consistency Check", true,
67  "Check if the initial condition, x and xDot, is consistent with the\n"
68  "governing equations, xDot = f(x,t), or f(x, xDot, t) = 0.\n"
69  "\n"
70  "In general for explicit and implicit steppers, the default is true,\n"
71  "because it is fairly cheap with just one residual evaluation.\n"
72  "Individual steppers may override this default.\n");
73 }
74 
75 
76 template<class Scalar>
77 void Stepper<Scalar>::modelWarning() const
78 {
79  Teuchos::RCP<Teuchos::FancyOStream> out = this->getOStream();
80  Teuchos::OSTab ostab(out,1,this->description());
81  *out << "Warning -- Constructing " << this->description()
82  << " without ModelEvaluator!\n"
83  << " - Can reset ParameterList with setParameterList().\n"
84  << " - Requires subsequent setModel() and initialize() calls\n"
85  << " before calling takeStep().\n" << std::endl;
86 }
87 
88 
89 template<class Scalar>
90 void Stepper<Scalar>::validExplicitODE(
91  const Teuchos::RCP<const Thyra::ModelEvaluator<Scalar> >& model) const
92 {
93  TEUCHOS_TEST_FOR_EXCEPT( is_null(model) );
94  typedef Thyra::ModelEvaluatorBase MEB;
95  const MEB::InArgs<Scalar> inArgs = model->createInArgs();
96  const MEB::OutArgs<Scalar> outArgs = model->createOutArgs();
97  const bool supports = inArgs.supports(MEB::IN_ARG_x) and
98  outArgs.supports(MEB::OUT_ARG_f);
99 
100  TEUCHOS_TEST_FOR_EXCEPTION( supports == false, std::logic_error,
101  model->description() << "can not support an explicit ODE with\n"
102  << " IN_ARG_x = " << inArgs.supports(MEB::IN_ARG_x) << "\n"
103  << " OUT_ARG_f = " << outArgs.supports(MEB::OUT_ARG_f) << "\n"
104  << "Explicit ODE requires:\n"
105  << " IN_ARG_x = true\n"
106  << " OUT_ARG_f = true\n"
107  << "\n"
108  << "NOTE: Currently the convention to evaluate f(x,t) is to set\n"
109  << "xdot=null! There is no InArgs support to test if xdot is null,\n"
110  << "so we set xdot=null and hope the ModelEvaluator can handle it.\n");
111 
112  return;
113 }
114 
115 
116 template<class Scalar>
117 void Stepper<Scalar>::validSecondOrderExplicitODE(
118  const Teuchos::RCP<const Thyra::ModelEvaluator<Scalar> >& model) const
119 {
120  TEUCHOS_TEST_FOR_EXCEPT( is_null(model) );
121  typedef Thyra::ModelEvaluatorBase MEB;
122  const MEB::InArgs<Scalar> inArgs = model->createInArgs();
123  const MEB::OutArgs<Scalar> outArgs = model->createOutArgs();
124  const bool supports = inArgs.supports(MEB::IN_ARG_x) and
125  inArgs.supports(MEB::IN_ARG_x_dot) and
126  outArgs.supports(MEB::OUT_ARG_f);
127 
128  TEUCHOS_TEST_FOR_EXCEPTION( supports == false, std::logic_error,
129  model->description() << "can not support an explicit ODE with\n"
130  << " IN_ARG_x = " << inArgs.supports(MEB::IN_ARG_x) << "\n"
131  << " IN_ARG_x_dot = " << inArgs.supports(MEB::IN_ARG_x_dot) << "\n"
132  << " OUT_ARG_f = " << outArgs.supports(MEB::OUT_ARG_f) << "\n"
133  << "Explicit ODE requires:\n"
134  << " IN_ARG_x = true\n"
135  << " IN_ARG_x_dot = true\n"
136  << " OUT_ARG_f = true\n"
137  << "\n"
138  << "NOTE: Currently the convention to evaluate f(x, xdot, t) is to\n"
139  << "set xdotdot=null! There is no InArgs support to test if xdotdot\n"
140  << "is null, so we set xdotdot=null and hope the ModelEvaluator can\n"
141  << "handle it.\n");
142 
143  return;
144 }
145 
146 
147 template<class Scalar>
148 void Stepper<Scalar>::validImplicitODE_DAE(
149  const Teuchos::RCP<const Thyra::ModelEvaluator<Scalar> >& model) const
150 {
151  TEUCHOS_TEST_FOR_EXCEPT( is_null(model) );
152  typedef Thyra::ModelEvaluatorBase MEB;
153  const MEB::InArgs<Scalar> inArgs = model->createInArgs();
154  const MEB::OutArgs<Scalar> outArgs = model->createOutArgs();
155  const bool supports = inArgs.supports(MEB::IN_ARG_x) and
156  inArgs.supports(MEB::IN_ARG_x_dot) and
157  inArgs.supports(MEB::IN_ARG_alpha) and
158  inArgs.supports(MEB::IN_ARG_beta) and
159  !inArgs.supports(MEB::IN_ARG_W_x_dot_dot_coeff) and
160  outArgs.supports(MEB::OUT_ARG_f) and
161  outArgs.supports(MEB::OUT_ARG_W);
162 
163  TEUCHOS_TEST_FOR_EXCEPTION( supports == false, std::logic_error,
164  model->description() << " can not support an implicit ODE with\n"
165  << " IN_ARG_x = "
166  << inArgs.supports(MEB::IN_ARG_x) << "\n"
167  << " IN_ARG_x_dot = "
168  << inArgs.supports(MEB::IN_ARG_x_dot) << "\n"
169  << " IN_ARG_alpha = "
170  << inArgs.supports(MEB::IN_ARG_alpha) << "\n"
171  << " IN_ARG_beta = "
172  << inArgs.supports(MEB::IN_ARG_beta) << "\n"
173  << " IN_ARG_W_x_dot_dot_coeff = "
174  << inArgs.supports(MEB::IN_ARG_W_x_dot_dot_coeff) << "\n"
175  << " OUT_ARG_f = "
176  << outArgs.supports(MEB::OUT_ARG_f) << "\n"
177  << " OUT_ARG_W = "
178  << outArgs.supports(MEB::OUT_ARG_W) << "\n"
179  << "Implicit ODE requires:\n"
180  << " IN_ARG_x = true\n"
181  << " IN_ARG_x_dot = true\n"
182  << " IN_ARG_alpha = true\n"
183  << " IN_ARG_beta = true\n"
184  << " IN_ARG_W_x_dot_dot_coeff = false\n"
185  << " OUT_ARG_f = true\n"
186  << " OUT_ARG_W = true\n");
187 
188  return;
189 }
190 
191 
192 template<class Scalar>
193 void Stepper<Scalar>::validSecondOrderODE_DAE(
194  const Teuchos::RCP<const Thyra::ModelEvaluator<Scalar> >& model) const
195 {
196  TEUCHOS_TEST_FOR_EXCEPT( is_null(model) );
197  typedef Thyra::ModelEvaluatorBase MEB;
198  const MEB::InArgs<Scalar> inArgs = model->createInArgs();
199  const MEB::OutArgs<Scalar> outArgs = model->createOutArgs();
200  const bool supports = inArgs.supports(MEB::IN_ARG_x) and
201  inArgs.supports(MEB::IN_ARG_x_dot) and
202  inArgs.supports(MEB::IN_ARG_x_dot_dot) and
203  inArgs.supports(MEB::IN_ARG_alpha) and
204  inArgs.supports(MEB::IN_ARG_beta) and
205  inArgs.supports(MEB::IN_ARG_W_x_dot_dot_coeff) and
206  outArgs.supports(MEB::OUT_ARG_f) and
207  outArgs.supports(MEB::OUT_ARG_W);
208 
209  TEUCHOS_TEST_FOR_EXCEPTION( supports == false, std::logic_error,
210  model->description() << " can not support an implicit ODE with\n"
211  << " IN_ARG_x = "
212  << inArgs.supports(MEB::IN_ARG_x) << "\n"
213  << " IN_ARG_x_dot = "
214  << inArgs.supports(MEB::IN_ARG_x_dot) << "\n"
215  << " IN_ARG_x_dot_dot = "
216  << inArgs.supports(MEB::IN_ARG_x_dot_dot) << "\n"
217  << " IN_ARG_alpha = "
218  << inArgs.supports(MEB::IN_ARG_alpha) << "\n"
219  << " IN_ARG_beta = "
220  << inArgs.supports(MEB::IN_ARG_beta) << "\n"
221  << " IN_ARG_W_x_dot_dot_coeff = "
222  << inArgs.supports(MEB::IN_ARG_W_x_dot_dot_coeff) << "\n"
223  << " OUT_ARG_f = "
224  << outArgs.supports(MEB::OUT_ARG_f) << "\n"
225  << " OUT_ARG_W = "
226  << outArgs.supports(MEB::OUT_ARG_W) << "\n"
227  << "Implicit Second Order ODE requires:\n"
228  << " IN_ARG_x = true\n"
229  << " IN_ARG_x_dot = true\n"
230  << " IN_ARG_x_dot_dot = true\n"
231  << " IN_ARG_alpha = true\n"
232  << " IN_ARG_beta = true\n"
233  << " IN_ARG_W_x_dot_dot_coeff = true\n"
234  << " OUT_ARG_f = true\n"
235  << " OUT_ARG_W = true\n");
236 
237  return;
238 }
239 
240 
241 template<class Scalar>
242 Teuchos::RCP<Teuchos::ParameterList>
243 Stepper<Scalar>::defaultSolverParameters() const
244 {
245  using Teuchos::RCP;
246  using Teuchos::ParameterList;
247 
248  // NOX Solver ParameterList
249  RCP<ParameterList> noxPL = Teuchos::parameterList();
250 
251  // Direction ParameterList
252  RCP<ParameterList> directionPL = Teuchos::parameterList();
253  directionPL->set<std::string>("Method", "Newton");
254  RCP<ParameterList> newtonPL = Teuchos::parameterList();
255  newtonPL->set<std::string>("Forcing Term Method", "Constant");
256  newtonPL->set<bool> ("Rescue Bad Newton Solve", 1);
257  directionPL->set("Newton", *newtonPL);
258  noxPL->set("Direction", *directionPL);
259 
260  // Line Search ParameterList
261  RCP<ParameterList> lineSearchPL = Teuchos::parameterList();
262  lineSearchPL->set<std::string>("Method", "Full Step");
263  RCP<ParameterList> fullStepPL = Teuchos::parameterList();
264  fullStepPL->set<double>("Full Step", 1);
265  lineSearchPL->set("Full Step", *fullStepPL);
266  noxPL->set("Line Search", *lineSearchPL);
267 
268  noxPL->set<std::string>("Nonlinear Solver", "Line Search Based");
269 
270  // Printing ParameterList
271  RCP<ParameterList> printingPL = Teuchos::parameterList();
272  printingPL->set<int>("Output Precision", 3);
273  printingPL->set<int>("Output Processor", 0);
274  RCP<ParameterList> outputPL = Teuchos::parameterList();
275  outputPL->set<bool>("Error", 1);
276  outputPL->set<bool>("Warning", 1);
277  outputPL->set<bool>("Outer Iteration", 0);
278  outputPL->set<bool>("Parameters", 0);
279  outputPL->set<bool>("Details", 0);
280  outputPL->set<bool>("Linear Solver Details", 1);
281  outputPL->set<bool>("Stepper Iteration", 1);
282  outputPL->set<bool>("Stepper Details", 1);
283  outputPL->set<bool>("Stepper Parameters", 1);
284  printingPL->set("Output Information", *outputPL);
285  noxPL->set("Printing", *printingPL);
286 
287  // Solver Options ParameterList
288  RCP<ParameterList> solverOptionsPL = Teuchos::parameterList();
289  solverOptionsPL->set<std::string>("Status Test Check Type", "Minimal");
290  noxPL->set("Solver Options", *solverOptionsPL);
291 
292  // Status Tests ParameterList
293  RCP<ParameterList> statusTestsPL = Teuchos::parameterList();
294  statusTestsPL->set<std::string>("Test Type", "Combo");
295  statusTestsPL->set<std::string>("Combo Type", "OR");
296  statusTestsPL->set<int>("Number of Tests", 2);
297  RCP<ParameterList> test0PL = Teuchos::parameterList();
298  test0PL->set<std::string>("Test Type", "NormF");
299  test0PL->set<double>("Tolerance", 1e-08);
300  statusTestsPL->set("Test 0", *test0PL);
301  RCP<ParameterList> test1PL = Teuchos::parameterList();
302  test1PL->set<std::string>("Test Type", "MaxIters");
303  test1PL->set<int>("Maximum Iterations", 10);
304  statusTestsPL->set("Test 1", *test1PL);
305  noxPL->set("Status Tests", *statusTestsPL);
306 
307  // Solver ParameterList
308  RCP<ParameterList> solverPL = Teuchos::parameterList();
309  solverPL->set("NOX", *noxPL);
310 
311  return solverPL;
312 }
313 
314 } // namespace Tempus
315 #endif // Tempus_Stepper_impl_hpp
Tempus::Stepper::validSecondOrderODE_DAE
void validSecondOrderODE_DAE(const Teuchos::RCP< const Thyra::ModelEvaluator< Scalar > > &model) const
Validate ME supports 2nd order implicit ODE/DAE evaluation, f(xdotdot,xdot,x,t) [= 0]...
Definition: Tempus_Stepper_impl.hpp:193
Tempus::Stepper::modelWarning
virtual void modelWarning() const
Definition: Tempus_Stepper_impl.hpp:77
Tempus::Stepper::defaultSolverParameters
Teuchos::RCP< Teuchos::ParameterList > defaultSolverParameters() const
Definition: Tempus_Stepper_impl.hpp:243
Tempus::Stepper::validSecondOrderExplicitODE
void validSecondOrderExplicitODE(const Teuchos::RCP< const Thyra::ModelEvaluator< Scalar > > &model) const
Validate that the model supports explicit second order ODE evaluation, f(x,xdot,t) [=xdotdot]...
Definition: Tempus_Stepper_impl.hpp:117
Tempus::Stepper::getValidParametersBasic
void getValidParametersBasic(Teuchos::RCP< Teuchos::ParameterList > pl) const
Definition: Tempus_Stepper_impl.hpp:17
Tempus::Stepper::validImplicitODE_DAE
void validImplicitODE_DAE(const Teuchos::RCP< const Thyra::ModelEvaluator< Scalar > > &model) const
Validate ME supports implicit ODE/DAE evaluation, f(xdot,x,t) [= 0].
Definition: Tempus_Stepper_impl.hpp:148
Tempus::Stepper::validExplicitODE
void validExplicitODE(const Teuchos::RCP< const Thyra::ModelEvaluator< Scalar > > &model) const
Validate that the model supports explicit ODE evaluation, f(x,t) [=xdot].
Definition: Tempus_Stepper_impl.hpp:90