123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147 |
- [/============================================================================
- Boost.odeint
- Copyright 2011-2012 Karsten Ahnert
- Copyright 2011-2012 Mario Mulansky
- Use, modification and distribution is subject to the Boost Software License,
- Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
- http://www.boost.org/LICENSE_1_0.txt)
- =============================================================================/]
- [def _max_step_checker_ [classref boost::numeric::odeint::max_step_checker `max_step_checker`]]
- [section Integrate functions]
- Integrate functions perform the time evolution of a given ODE from some
- starting time ['t[sub 0]] to a given end time ['t[sub 1]] and starting at state ['x[sub 0]] by subsequent calls of a given stepper's `do_step` function.
- Additionally, the user can provide an __observer to analyze the state during time evolution, and
- a _max_step_checker_ to throw an exception if too many steps are taken between observer calls (i.e. too
- small step size).
- There are five different integrate functions which have different strategies on when to call the observer function during integration.
- All of the integrate functions except `integrate_n_steps` can be called with any stepper following one of the stepper concepts: __stepper , __error_stepper , __controlled_stepper , __dense_output_stepper.
- Depending on the abilities of the stepper, the integrate functions make use of step-size control or dense output.
- [heading Equidistant observer calls]
- If observer calls at equidistant time intervals /dt/ are needed, the
- `integrate_const` or `integrate_n_steps` function should be used.
- We start with explaining `integrate_const`:
- `integrate_const( stepper , system , x0 , t0 , t1 , dt )`
- `integrate_const( stepper , system , x0 , t0 , t1 , dt , observer )`
- `integrate_const( stepper , system , x0 , t0 , t1 , dt , observer , max_step_checker )`
- These integrate the ODE given by `system` with subsequent steps from `stepper`.
- Integration start at `t0` and `x0` and ends at some ['t' = t[sub 0] + n dt] with /n/ such that ['t[sub 1] - dt < t' <= t[sub 1]].
- `x0` is changed to the approximative solution ['x(t')] at the end of integration.
- If provided, the `observer` is invoked at times ['t[sub 0]], ['t[sub 0] + dt], ['t[sub 0] + 2dt], ... ,['t'].
- If provided, the `max_step_checker` counts the number of steps between observer calls and throws a
- `no_progress_error` this exceeds some limit (default: 500).
- `integrate_const` returns the number of steps performed during the integration.
- Note that if you are using a simple __stepper or __error_stepper and want to make exactly `n` steps you should prefer the `integrate_n_steps` function below.
- * If `stepper` is a __stepper or __error_stepper then `dt` is also the step size used for integration and the observer is called just after every step.
- * If `stepper` is a __controlled_stepper then `dt` is the initial step size.
- The actual step size will change due to error control during time evolution.
- However, if an observer is provided the step size will be adjusted such that the algorithm always calculates /x(t)/ at ['t = t[sub 0] + n dt] and calls the observer at that point.
- Note that the use of __controlled_stepper is reasonable here only if `dt` is considerably larger than typical step sizes used by the stepper.
- * If `stepper` is a __dense_output_stepper then `dt` is the initial step size.
- The actual step size will be adjusted during integration due to error control.
- If an observer is provided dense output is used to calculate /x(t)/ at ['t = t[sub 0] + n dt].
- [heading Integrate a given number of steps]
- This function is very similar to `integrate_const` above. The only difference
- is that it does not take the end time as parameter, but rather the number of
- steps. The integration is then performed until the time `t0+n*dt`.
- `integrate_n_steps( stepper , system , x0 , t0 , dt , n )`
- `integrate_n_steps( stepper , system , x0 , t0 , dt , n , observer )`
- `integrate_n_steps( stepper , system , x0 , t0 , dt , n , observer , max_step_checker )`
- Integrates the ODE given by `system` with subsequent steps from `stepper` starting at ['x[sub 0]] and ['t[sub 0]].
- If provided, `observer` is called after every step and at the beginning with
- `t0`, similar as above.
- Again, providing a `max_step_checker` will throw a `no_progress_error` if too many steps are performed
- between observer calls.
- The approximate result for ['x( t[sub 0] + n dt )] is stored in `x0`.
- This function returns the end time `t0 + n*dt`.
- [heading Observer calls at each step]
- If the observer should be called at each time step then the `integrate_adaptive` function should be used.
- Note that in the case of __controlled_stepper or __dense_output_stepper this leads to non-equidistant observer calls as the step size changes.
- `integrate_adaptive( stepper , system , x0 , t0 , t1 , dt )`
- `integrate_adaptive( stepper , system , x0 , t0 , t1 , dt , observer )`
- Integrates the ODE given by `system` with subsequent steps from `stepper`.
- Integration start at `t0` and `x0` and ends at ['t[sub 1]].
- `x0` is changed to the approximative solution ['x(t[sub 1])] at the end of integration.
- If provided, the `observer` is called after each step (and before the first step at `t0`).
- `integrate_adaptive` returns the number of steps performed during the integration.
- [note `integrate_adaptive` by design performs an observer call after each time step. Hence
- there is no need for a _max_step_checker_ as only exactly one step is ever performed between
- observer calls.
- ]
- * If `stepper` is a __stepper or __error_stepper then `dt` is the step size used for integration and `integrate_adaptive` behaves like `integrate_const` except that for the last step the step size is reduced to ensure we end exactly at `t1`.
- If provided, the observer is called at each step.
- * If `stepper` is a __controlled_stepper then `dt` is the initial step size.
- The actual step size is changed according to error control of the stepper.
- For the last step, the step size will be reduced to ensure we end exactly at `t1`.
- If provided, the observer is called after each time step (and before the first step at `t0`).
- * If stepper is a __dense_output_stepper then `dt` is the initial step size and `integrate_adaptive` behaves just like for __controlled_stepper above. No dense output is used.
- [heading Observer calls at given time points]
- If the observer should be called at some user given time points the `integrate_times` function should be used.
- The times for observer calls are provided as a sequence of time values.
- The sequence is either defined via two iterators pointing to begin and end of the sequence or in terms of a __boost_range object.
- `integrate_times( stepper , system , x0 , times_start , times_end , dt , observer )`
- `integrate_times( stepper , system , x0 , time_range , dt , observer )`
- Integrates the ODE given by `system` with subsequent steps from `stepper`.
- Integration starts at `*times_start` and ends exactly at `*(times_end-1)`.
- `x0` contains the approximate solution at the end point of integration.
- This function requires an observer which is invoked at the subsequent times `*times_start++` until `times_start == times_end`.
- If called with a __boost_range `time_range` the function behaves the same with `times_start = boost::begin( time_range )` and `times_end = boost::end( time_range )`.
- Additionally, a _max_step_checker_ can be provided, e.g.:
- `integrate_times( stepper , system , x0 , times_start , times_end , dt , observer , max_step_checker)`
- As above, this will throw a `no_progress_error` if too many steps are performed between observer calls.
- `integrate_times` returns the number of steps performed during the integration.
- * If `stepper` is a __stepper or __error_stepper `dt` is the step size used for integration.
- However, whenever a time point from the sequence is approached the step size `dt` will be reduced to obtain the state /x(t)/ exactly at the time point.
- * If `stepper` is a __controlled_stepper then `dt` is the initial step size.
- The actual step size is adjusted during integration according to error control.
- However, if a time point from the sequence is approached the step size is reduced to obtain the state /x(t)/ exactly at the time point.
- * If `stepper` is a __dense_output_stepper then `dt` is the initial step size.
- The actual step size is adjusted during integration according to error control.
- Dense output is used to obtain the states /x(t)/ at the time points from the sequence.
- [heading Convenience integrate function]
- Additionally to the sophisticated integrate function above odeint also provides a simple `integrate` routine which uses a dense output stepper based on `runge_kutta_dopri5` with standard error bounds ['10[super -6]] for the steps.
- `integrate( system , x0 , t0 , t1 , dt )`
- `integrate( system , x0 , t0 , t1 , dt , observer )`
- This function behaves exactly like `integrate_adaptive` above but no stepper has to be provided.
- It also returns the number of steps performed during the integration.
- [endsect]
|