Squashed 'third_party/boostorg/odeint/' content from commit 6ff2719
Change-Id: If4892e29c1a5e6cf3a7aa51486a2725c251b0c7d
git-subtree-dir: third_party/boostorg/odeint
git-subtree-split: 6ff2719b6907b86596c3d43e88c1bcfdf29df560
diff --git a/doc/details_integrate_functions.qbk b/doc/details_integrate_functions.qbk
new file mode 100644
index 0000000..47af7ac
--- /dev/null
+++ b/doc/details_integrate_functions.qbk
@@ -0,0 +1,147 @@
+[/============================================================================
+ 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]