]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 , detail::bind( &internal_stepper_base_type::template resize_impl<StateIn> , detail::ref( *this ) , detail::_1 ) ); | |
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 , detail::bind( &internal_stepper_base_type::template resize_impl< StateInOut > , detail::ref( *this ) , detail::_1 ) ); | |
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 |