1 | /* |
2 | [auto_generated] |
3 | boost/numeric/odeint/stepper/base/explicit_stepper_base.hpp |
4 | |
5 | [begin_description] |
6 | Base class for all explicit Runge Kutta steppers. |
7 | [end_description] |
8 | |
9 | Copyright 2010-2013 Karsten Ahnert |
10 | Copyright 2010-2012 Mario Mulansky |
11 | Copyright 2012 Christoph Koke |
12 | |
13 | Distributed under the Boost Software License, Version 1.0. |
14 | (See accompanying file LICENSE_1_0.txt or |
15 | copy at http://www.boost.org/LICENSE_1_0.txt) |
16 | */ |
17 | |
18 | |
19 | #ifndef BOOST_NUMERIC_ODEINT_STEPPER_BASE_EXPLICIT_STEPPER_BASE_HPP_INCLUDED |
20 | #define BOOST_NUMERIC_ODEINT_STEPPER_BASE_EXPLICIT_STEPPER_BASE_HPP_INCLUDED |
21 | |
22 | |
23 | #include <boost/utility/enable_if.hpp> |
24 | #include <boost/type_traits/is_same.hpp> |
25 | |
26 | #include <boost/numeric/odeint/util/bind.hpp> |
27 | #include <boost/numeric/odeint/util/unwrap_reference.hpp> |
28 | |
29 | #include <boost/numeric/odeint/util/state_wrapper.hpp> |
30 | #include <boost/numeric/odeint/util/resizer.hpp> |
31 | #include <boost/numeric/odeint/util/is_resizeable.hpp> |
32 | |
33 | #include <boost/numeric/odeint/stepper/stepper_categories.hpp> |
34 | |
35 | #include <boost/numeric/odeint/stepper/base/algebra_stepper_base.hpp> |
36 | |
37 | namespace boost { |
38 | namespace numeric { |
39 | namespace odeint { |
40 | |
41 | /* |
42 | * base class for explicit steppers |
43 | * models the stepper concept |
44 | * |
45 | * this class provides the following overloads |
46 | * do_step( sys , x , t , dt ) |
47 | * do_step( sys , in , t , out , dt ) |
48 | * do_step( sys , x , dxdt_in , t , dt ) |
49 | * do_step( sys , in , dxdt_in , t , out , dt ) |
50 | */ |
51 | |
52 | template< |
53 | class Stepper , |
54 | unsigned short Order , |
55 | class State , |
56 | class Value , |
57 | class Deriv , |
58 | class Time , |
59 | class Algebra , |
60 | class Operations , |
61 | class Resizer |
62 | > |
63 | class explicit_stepper_base : public algebra_stepper_base< Algebra , Operations > |
64 | { |
65 | public: |
66 | |
67 | #ifndef DOXYGEN_SKIP |
68 | typedef explicit_stepper_base< Stepper , Order , State , Value , Deriv , Time , Algebra , Operations , Resizer > internal_stepper_base_type; |
69 | #endif // DOXYGEN_SKIP |
70 | |
71 | |
72 | typedef State state_type; |
73 | typedef Value value_type; |
74 | typedef Deriv deriv_type; |
75 | typedef Time time_type; |
76 | typedef Resizer resizer_type; |
77 | typedef Stepper stepper_type; |
78 | typedef stepper_tag stepper_category; |
79 | typedef algebra_stepper_base< Algebra , Operations > algebra_stepper_base_type; |
80 | typedef typename algebra_stepper_base_type::algebra_type algebra_type; |
81 | typedef typename algebra_stepper_base_type::operations_type operations_type; |
82 | typedef unsigned short order_type; |
83 | |
84 | #ifndef DOXYGEN_SKIP |
85 | typedef state_wrapper< state_type > wrapped_state_type; |
86 | typedef state_wrapper< deriv_type > wrapped_deriv_type; |
87 | #endif // DOXYGEN_SKIP |
88 | |
89 | |
90 | static const order_type order_value = Order; |
91 | |
92 | |
93 | explicit_stepper_base( const algebra_type &algebra = algebra_type() ) |
94 | : algebra_stepper_base_type( algebra ) |
95 | { } |
96 | |
97 | /** |
98 | * \return Returns the order of the stepper. |
99 | */ |
100 | order_type order( void ) const |
101 | { |
102 | return order_value; |
103 | } |
104 | |
105 | |
106 | /* |
107 | * Version 1 : do_step( sys , x , t , dt ) |
108 | * |
109 | * the two overloads are needed in order to solve the forwarding problem |
110 | */ |
111 | template< class System , class StateInOut > |
112 | void do_step( System system , StateInOut &x , time_type t , time_type dt ) |
113 | { |
114 | do_step_v1( system , x , t , dt ); |
115 | } |
116 | |
117 | /** |
118 | * \brief Second version to solve the forwarding problem, can be called with Boost.Range as StateInOut. |
119 | */ |
120 | template< class System , class StateInOut > |
121 | void do_step( System system , const StateInOut &x , time_type t , time_type dt ) |
122 | { |
123 | do_step_v1( system , x , t , dt ); |
124 | } |
125 | |
126 | /* |
127 | * Version 2 : do_step( sys , x , dxdt , t , dt ) |
128 | * |
129 | * this version does not solve the forwarding problem, boost.range can not be used |
130 | * |
131 | * the disable is needed to avoid ambiguous overloads if state_type = time_type |
132 | */ |
133 | template< class System , class StateInOut , class DerivIn > |
134 | typename boost::disable_if< boost::is_same< DerivIn , time_type > , void >::type |
135 | do_step( System system , StateInOut &x , const DerivIn &dxdt , time_type t , time_type dt ) |
136 | { |
137 | this->stepper().do_step_impl( system , x , dxdt , t , x , dt ); |
138 | } |
139 | |
140 | |
141 | /* |
142 | * named Version 2: do_step_dxdt_impl( sys , in , dxdt , t , dt ) |
143 | * |
144 | * this version is needed when this stepper is used for initializing |
145 | * multistep stepper like adams-bashforth. Hence we provide an explicitely |
146 | * named version that is not disabled. Meant for internal use only. |
147 | */ |
148 | template < class System, class StateInOut, class DerivIn > |
149 | void do_step_dxdt_impl( System system, StateInOut &x, const DerivIn &dxdt, |
150 | time_type t, time_type dt ) |
151 | { |
152 | this->stepper().do_step_impl( system , x , dxdt , t , x , dt ); |
153 | } |
154 | |
155 | |
156 | /* |
157 | * Version 3 : do_step( sys , in , t , out , dt ) |
158 | * |
159 | * this version does not solve the forwarding problem, boost.range can not be used |
160 | */ |
161 | template< class System , class StateIn , class StateOut > |
162 | void do_step( System system , const StateIn &in , time_type t , StateOut &out , time_type dt ) |
163 | { |
164 | typename odeint::unwrap_reference< System >::type &sys = system; |
165 | m_resizer.adjust_size(in, [this](auto&& arg) { return this->resize_impl<StateIn>(std::forward<decltype(arg)>(arg)); }); |
166 | sys( in , m_dxdt.m_v ,t ); |
167 | this->stepper().do_step_impl( system , in , m_dxdt.m_v , t , out , dt ); |
168 | } |
169 | |
170 | |
171 | /* |
172 | * Version 4 : do_step( sys , in , dxdt , t , out , dt ) |
173 | * |
174 | * this version does not solve the forwarding problem, boost.range can not be used |
175 | */ |
176 | template< class System , class StateIn , class DerivIn , class StateOut > |
177 | void do_step( System system , const StateIn &in , const DerivIn &dxdt , time_type t , StateOut &out , time_type dt ) |
178 | { |
179 | this->stepper().do_step_impl( system , in , dxdt , t , out , dt ); |
180 | } |
181 | |
182 | |
183 | /* |
184 | * named Version 4: do_step_dxdt_impl( sys , in , dxdt , t , out, dt ) |
185 | * |
186 | * this version is needed when this stepper is used for initializing |
187 | * multistep stepper like adams-bashforth. Hence we provide an explicitely |
188 | * named version. Meant for internal use only. |
189 | */ |
190 | template < class System, class StateIn, class DerivIn, class StateOut > |
191 | void do_step_dxdt_impl( System system, const StateIn &in, |
192 | const DerivIn &dxdt, time_type t, StateOut &out, |
193 | time_type dt ) |
194 | { |
195 | this->stepper().do_step_impl( system , in , dxdt , t , out , dt ); |
196 | } |
197 | |
198 | template< class StateIn > |
199 | void adjust_size( const StateIn &x ) |
200 | { |
201 | resize_impl( x ); |
202 | } |
203 | |
204 | private: |
205 | |
206 | stepper_type& stepper( void ) |
207 | { |
208 | return *static_cast< stepper_type* >( this ); |
209 | } |
210 | |
211 | const stepper_type& stepper( void ) const |
212 | { |
213 | return *static_cast< const stepper_type* >( this ); |
214 | } |
215 | |
216 | |
217 | template< class StateIn > |
218 | bool resize_impl( const StateIn &x ) |
219 | { |
220 | return adjust_size_by_resizeability( m_dxdt , x , typename is_resizeable<deriv_type>::type() ); |
221 | } |
222 | |
223 | |
224 | template< class System , class StateInOut > |
225 | void do_step_v1( System system , StateInOut &x , time_type t , time_type dt ) |
226 | { |
227 | typename odeint::unwrap_reference< System >::type &sys = system; |
228 | m_resizer.adjust_size(x, [this](auto&& arg) { return this->resize_impl<StateInOut>(std::forward<decltype(arg)>(arg)); }); |
229 | sys( x , m_dxdt.m_v ,t ); |
230 | this->stepper().do_step_impl( system , x , m_dxdt.m_v , t , x , dt ); |
231 | } |
232 | |
233 | |
234 | resizer_type m_resizer; |
235 | |
236 | protected: |
237 | |
238 | wrapped_deriv_type m_dxdt; |
239 | }; |
240 | |
241 | |
242 | /******* DOXYGEN *********/ |
243 | |
244 | /** |
245 | * \class explicit_stepper_base |
246 | * \brief Base class for explicit steppers without step size control and without dense output. |
247 | * |
248 | * This class serves as the base class for all explicit steppers with algebra and operations. |
249 | * Step size control and error estimation as well as dense output are not provided. explicit_stepper_base |
250 | * is used as the interface in a CRTP (currently recurring template pattern). In order to work |
251 | * correctly the parent class needs to have a method `do_step_impl( system , in , dxdt_in , t , out , dt )`. |
252 | * This is method is used by explicit_stepper_base. explicit_stepper_base derives from |
253 | * algebra_stepper_base. An example how this class can be used is |
254 | * |
255 | * \code |
256 | * template< class State , class Value , class Deriv , class Time , class Algebra , class Operations , class Resizer > |
257 | * class custom_euler : public explicit_stepper_base< 1 , State , Value , Deriv , Time , Algebra , Operations , Resizer > |
258 | * { |
259 | * public: |
260 | * |
261 | * typedef explicit_stepper_base< 1 , State , Value , Deriv , Time , Algebra , Operations , Resizer > base_type; |
262 | * |
263 | * custom_euler( const Algebra &algebra = Algebra() ) { } |
264 | * |
265 | * template< class Sys , class StateIn , class DerivIn , class StateOut > |
266 | * void do_step_impl( Sys sys , const StateIn &in , const DerivIn &dxdt , Time t , StateOut &out , Time dt ) |
267 | * { |
268 | * m_algebra.for_each3( out , in , dxdt , Operations::scale_sum2< Value , Time >( 1.0 , dt ); |
269 | * } |
270 | * |
271 | * template< class State > |
272 | * void adjust_size( const State &x ) |
273 | * { |
274 | * base_type::adjust_size( x ); |
275 | * } |
276 | * }; |
277 | * \endcode |
278 | * |
279 | * For the Stepper concept only the `do_step( sys , x , t , dt )` needs to be implemented. But this class |
280 | * provides additional `do_step` variants since the stepper is explicit. These methods can be used to increase |
281 | * the performance in some situation, for example if one needs to analyze `dxdt` during each step. In this case |
282 | * one can use |
283 | * |
284 | * \code |
285 | * sys( x , dxdt , t ); |
286 | * stepper.do_step( sys , x , dxdt , t , dt ); // the value of dxdt is used here |
287 | * t += dt; |
288 | * \endcode |
289 | * |
290 | * In detail explicit_stepper_base provides the following `do_step` variants |
291 | * - `do_step( sys , x , t , dt )` - The classical `do_step` method needed to fulfill the Stepper concept. The state is updated in-place. |
292 | * A type modelling a Boost.Range can be used for x. |
293 | * - `do_step( sys , in , t , out , dt )` - This method updates the state out-of-place, hence the result of the step is stored in `out`. |
294 | * - `do_step( sys , x , dxdt , t , dt )` - This method updates the state in-place, but the derivative at the point `t` must be |
295 | * explicitly passed in `dxdt`. For an example see the code snippet above. |
296 | * - `do_step( sys , in , dxdt , t , out , dt )` - This method update the state out-of-place and expects that the derivative at the point |
297 | * `t` is explicitly passed in `dxdt`. It is a combination of the two `do_step` methods above. |
298 | * |
299 | * \note The system is always passed as value, which might result in poor performance if it contains data. In this case it can be used with `boost::ref` |
300 | * or `std::ref`, for example `stepper.do_step( boost::ref( sys ) , x , t , dt );` |
301 | * |
302 | * \note The time `t` is not advanced by the stepper. This has to done manually, or by the appropriate `integrate` routines or `iterator`s. |
303 | * |
304 | * \tparam Stepper The stepper on which this class should work. It is used via CRTP, hence explicit_stepper_base |
305 | * provides the interface for the Stepper. |
306 | * \tparam Order The order of the stepper. |
307 | * \tparam State The state type for the stepper. |
308 | * \tparam Value The value type for the stepper. This should be a floating point type, like float, |
309 | * double, or a multiprecision type. It must not necessary be the value_type of the State. For example |
310 | * the State can be a `vector< complex< double > >` in this case the Value must be double. |
311 | * The default value is double. |
312 | * \tparam Deriv The type representing time derivatives of the state type. It is usually the same type as the |
313 | * state type, only if used with Boost.Units both types differ. |
314 | * \tparam Time The type representing the time. Usually the same type as the value type. When Boost.Units is |
315 | * used, this type has usually a unit. |
316 | * \tparam Algebra The algebra type which must fulfill the Algebra Concept. |
317 | * \tparam Operations The type for the operations which must fulfill the Operations Concept. |
318 | * \tparam Resizer The resizer policy class. |
319 | */ |
320 | |
321 | |
322 | /** |
323 | * \fn explicit_stepper_base::explicit_stepper_base( const algebra_type &algebra ) |
324 | * \brief Constructs a explicit_stepper_base class. This constructor can be used as a default |
325 | * constructor if the algebra has a default constructor. |
326 | * \param algebra A copy of algebra is made and stored inside explicit_stepper_base. |
327 | */ |
328 | |
329 | /** |
330 | * \fn explicit_stepper_base::order_type order( void ) const |
331 | * \return Returns the order of the stepper. |
332 | */ |
333 | |
334 | /** |
335 | * \fn explicit_stepper_base::do_step( System system , StateInOut &x , time_type t , time_type dt ) |
336 | * \brief This method performs one step. It transforms the result in-place. |
337 | * |
338 | * \param system The system function to solve, hence the r.h.s. of the ordinary differential equation. It must fulfill the |
339 | * Simple System concept. |
340 | * \param x The state of the ODE which should be solved. After calling do_step the result is updated in x. |
341 | * \param t The value of the time, at which the step should be performed. |
342 | * \param dt The step size. |
343 | */ |
344 | |
345 | |
346 | /** |
347 | * \fn explicit_stepper_base::do_step( System system , StateInOut &x , const DerivIn &dxdt , time_type t , time_type dt ) |
348 | |
349 | * \brief The method performs one step. Additionally to the other method |
350 | * the derivative of x is also passed to this method. It is supposed to be used in the following way: |
351 | * |
352 | * \code |
353 | * sys( x , dxdt , t ); |
354 | * stepper.do_step( sys , x , dxdt , t , dt ); |
355 | * \endcode |
356 | * |
357 | * The result is updated in place in x. This method is disabled if Time and Deriv are of the same type. In this |
358 | * case the method could not be distinguished from other `do_step` versions. |
359 | * |
360 | * \note This method does not solve the forwarding problem. |
361 | * |
362 | * \param system The system function to solve, hence the r.h.s. of the ODE. It must fulfill the |
363 | * Simple System concept. |
364 | * \param x The state of the ODE which should be solved. After calling do_step the result is updated in x. |
365 | * \param dxdt The derivative of x at t. |
366 | * \param t The value of the time, at which the step should be performed. |
367 | * \param dt The step size. |
368 | */ |
369 | |
370 | /** |
371 | * \fn void explicit_stepper_base::do_step( System system , const StateIn &in , time_type t , StateOut &out , time_type dt ) |
372 | * \brief The method performs one step. The state of the ODE is updated out-of-place. |
373 | * \note This method does not solve the forwarding problem. |
374 | * |
375 | * \param system The system function to solve, hence the r.h.s. of the ODE. It must fulfill the |
376 | * Simple System concept. |
377 | * \param in The state of the ODE which should be solved. in is not modified in this method |
378 | * \param t The value of the time, at which the step should be performed. |
379 | * \param out The result of the step is written in out. |
380 | * \param dt The step size. |
381 | */ |
382 | |
383 | /** |
384 | * \fn void explicit_stepper_base::do_step( System system , const StateIn &in , const DerivIn &dxdt , time_type t , StateOut &out , time_type dt ) |
385 | * \brief The method performs one step. The state of the ODE is updated out-of-place. |
386 | * Furthermore, the derivative of x at t is passed to the stepper. |
387 | * It is supposed to be used in the following way: |
388 | * |
389 | * \code |
390 | * sys( in , dxdt , t ); |
391 | * stepper.do_step( sys , in , dxdt , t , out , dt ); |
392 | * \endcode |
393 | * |
394 | * \note This method does not solve the forwarding problem. |
395 | * |
396 | * \param system The system function to solve, hence the r.h.s. of the ODE. It must fulfill the |
397 | * Simple System concept. |
398 | * \param in The state of the ODE which should be solved. in is not modified in this method |
399 | * \param dxdt The derivative of x at t. |
400 | * \param t The value of the time, at which the step should be performed. |
401 | * \param out The result of the step is written in out. |
402 | * \param dt The step size. |
403 | */ |
404 | |
405 | /** |
406 | * \fn void explicit_stepper_base::adjust_size( const StateIn &x ) |
407 | * \brief Adjust the size of all temporaries in the stepper manually. |
408 | * \param x A state from which the size of the temporaries to be resized is deduced. |
409 | */ |
410 | |
411 | } // odeint |
412 | } // numeric |
413 | } // boost |
414 | |
415 | #endif // BOOST_NUMERIC_ODEINT_STEPPER_BASE_EXPLICIT_STEPPER_BASE_HPP_INCLUDED |
416 | |