boost::range detail documentation

doc/boost_sandbox_numeric_odeint/odeint_in_detail/using_boost__range.html

@@ -22,18 +22,206 @@
 </h3></div></div></div>
 <p>
         Most steppers in odeint also accept the state give as a range. A range is
-        sequence of values modelled by a range concept, see <a href="http://www.boost.org/doc/libs/release/libs/range/index.html" target="_top">Boost.Range</a>
+        sequence of values modelled by a range concept. See <a href="http://www.boost.org/doc/libs/release/libs/range/index.html" target="_top">Boost.Range</a>
-        for an overview over existing concepts and examples of ranges.
+        for an overview over existing concepts and examples of ranges. This means
+        that the <code class="computeroutput"><span class="identifier">state_type</span></code> of the
+        stepper must not necessarily used to call the <code class="computeroutput"><span class="identifier">do_step</span></code>
+        method.
       </p>
 <p>
-        state type mus not necessary be used in the steppers
+        One use case for <a href="http://www.boost.org/doc/libs/release/libs/range/index.html" target="_top">Boost.Range</a>
+        in odeint has been shown in <a class="link" href="../tutorial/chaotic_systems_and_lyapunov_exponents.html" title="Chaotic systems and Lyapunov exponents">Chaotic
+        system</a> where the state consists of two parts: one for the original
+        state and one for the perturbations. The ranges are used to initialize (solve)
+        only the system part where the perturbation part is not touched. After that
+        the complete state including also the perturbations is solved. Another use
+        case is a system consisting of coupled units where you want to initialize
+        each unit separately with the ODE of the uncoupled unit. An example is a
+        chain of coupled van-der-Pol-oscillators which are initialized uniformily
+        from the uncoupled van-der-Pol-oscillator. Then you can use <a href="http://www.boost.org/doc/libs/release/libs/range/index.html" target="_top">Boost.Range</a>
+        to solve only one individual oscillator in the chain.
       </p>
 <p>
-        example
+        An example was given in <a class="link" href="../tutorial/chaotic_systems_and_lyapunov_exponents.html" title="Chaotic systems and Lyapunov exponents">Chaotic
+        system</a> tutorial. Using Boost.Range usually means that your system
+        function needs to adapt to the iterators of Boost.Range. That is, your function
+        is called with a range and you need to get the iterators from that range.
+        This can easily be done. You have to implement your system as a class or
+        a struct and you have to templatize the <code class="computeroutput"><span class="keyword">operator</span><span class="special">()</span></code>. Then you can use the <code class="computeroutput"><span class="identifier">range_iterator</span></code>-meta
+        function and <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">begin</span></code> and <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">end</span></code> to
+        obtain the iterators of your range:
       </p>
 <p>
-        table which steppers support boost::range and with which algebra
+</p>
+<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">sys</span>
+<span class="special">{</span>
+    <span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">class</span> <span class="identifier">State</span> <span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Deriv</span> <span class="special">&gt;</span>
+    <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span> <span class="keyword">const</span> <span class="identifier">State</span> <span class="special">&amp;</span><span class="identifier">x_</span> <span class="special">,</span> <span class="identifier">Deriv</span> <span class="special">&amp;</span><span class="identifier">dxdt_</span> <span class="special">,</span> <span class="keyword">double</span> <span class="identifier">t</span> <span class="special">)</span> <span class="keyword">const</span>
+    <span class="special">{</span>
+         <span class="keyword">typename</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">range_iterator</span><span class="special">&lt;</span> <span class="keyword">const</span> <span class="identifier">State</span> <span class="special">&gt;::</span><span class="identifier">type</span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">begin</span><span class="special">(</span> <span class="identifier">x_</span> <span class="special">);</span>
+         <span class="keyword">typename</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">range_iterator</span><span class="special">&lt;</span> <span class="identifier">Deriv</span> <span class="special">&gt;::</span><span class="identifier">type</span> <span class="identifier">dxdt</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">begin</span><span class="special">(</span> <span class="identifier">dxdt_</span> <span class="special">);</span>
+
+         <span class="comment">// fill dxdt</span>
+    <span class="special">}</span>
+<span class="special">};</span>
+</pre>
+<p>
       </p>
+<p>
+        If your range is a random access-range you can also apply the bracket operator
+        to the iterator to access the elements in the range:
+</p>
+<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">sys</span>
+<span class="special">{</span>
+    <span class="keyword">template</span><span class="special">&lt;</span> <span class="keyword">class</span> <span class="identifier">State</span> <span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Deriv</span> <span class="special">&gt;</span>
+    <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span> <span class="keyword">const</span> <span class="identifier">State</span> <span class="special">&amp;</span><span class="identifier">x_</span> <span class="special">,</span> <span class="identifier">Deriv</span> <span class="special">&amp;</span><span class="identifier">dxdt_</span> <span class="special">,</span> <span class="keyword">double</span> <span class="identifier">t</span> <span class="special">)</span> <span class="keyword">const</span>
+    <span class="special">{</span>
+         <span class="keyword">typename</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">range_iterator</span><span class="special">&lt;</span> <span class="keyword">const</span> <span class="identifier">State</span> <span class="special">&gt;::</span><span class="identifier">type</span> <span class="identifier">x</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">begin</span><span class="special">(</span> <span class="identifier">x_</span> <span class="special">);</span>
+         <span class="keyword">typename</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">range_iterator</span><span class="special">&lt;</span> <span class="identifier">Deriv</span> <span class="special">&gt;::</span><span class="identifier">type</span> <span class="identifier">dxdt</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">begin</span><span class="special">(</span> <span class="identifier">dxdt_</span> <span class="special">);</span>
+
+         <span class="identifier">dxdt</span><span class="special">[</span><span class="number">0</span><span class="special">]</span> <span class="special">=</span> <span class="identifier">f1</span><span class="special">(</span> <span class="identifier">x</span><span class="special">[</span><span class="number">0</span><span class="special">]</span> <span class="special">,</span> <span class="identifier">x</span><span class="special">[</span><span class="number">1</span><span class="special">]</span> <span class="special">);</span>
+         <span class="identifier">dxdt</span><span class="special">[</span><span class="number">1</span><span class="special">]</span> <span class="special">=</span> <span class="identifier">f2</span><span class="special">(</span> <span class="identifier">x</span><span class="special">[</span><span class="number">0</span><span class="special">]</span> <span class="special">,</span> <span class="identifier">x</span><span class="special">[</span><span class="number">1</span><span class="special">]</span> <span class="special">);</span>
+    <span class="special">}</span>
+<span class="special">};</span>
+</pre>
+<p>
+      </p>
+<p>
+        The following two tables show which steppers and which algebras are compatible
+        with <a href="http://www.boost.org/doc/libs/release/libs/range/index.html" target="_top">Boost.Range</a>.
+      </p>
+<div class="table">
+<a name="boost_sandbox_numeric_odeint.odeint_in_detail.using_boost__range.steppers_supporting_boost_range"></a><p class="title"><b>Table&#160;1.10.&#160;Steppers supporting Boost.Range</b></p>
+<div class="table-contents"><table class="table" summary="Steppers supporting Boost.Range">
+<colgroup><col></colgroup>
+<thead><tr><th>
+                <p>
+                  Stepper
+                </p>
+              </th></tr></thead>
+<tbody>
+<tr><td>
+                <p>
+                  adams_bashforth_moulton
+                </p>
+              </td></tr>
+<tr><td>
+                <p>
+                  bulirsch_stoer_dense_out
+                </p>
+              </td></tr>
+<tr><td>
+                <p>
+                  bulirsch_stoer
+                </p>
+              </td></tr>
+<tr><td>
+                <p>
+                  controlled_runge_kutta
+                </p>
+              </td></tr>
+<tr><td>
+                <p>
+                  dense_output_runge_kutta
+                </p>
+              </td></tr>
+<tr><td>
+                <p>
+                  euler
+                </p>
+              </td></tr>
+<tr><td>
+                <p>
+                  explicit_error_generic_rk
+                </p>
+              </td></tr>
+<tr><td>
+                <p>
+                  explicit_generic_rk
+                </p>
+              </td></tr>
+<tr><td>
+                <p>
+                  rosenbrock4_controller
+                </p>
+              </td></tr>
+<tr><td>
+                <p>
+                  rosenbrock4_dense_output
+                </p>
+              </td></tr>
+<tr><td>
+                <p>
+                  rosenbrock4
+                </p>
+              </td></tr>
+<tr><td>
+                <p>
+                  runge_kutta4_classic
+                </p>
+              </td></tr>
+<tr><td>
+                <p>
+                  runge_kutta4
+                </p>
+              </td></tr>
+<tr><td>
+                <p>
+                  runge_kutta_cash_karp54_classic
+                </p>
+              </td></tr>
+<tr><td>
+                <p>
+                  runge_kutta_cash_karp54
+                </p>
+              </td></tr>
+<tr><td>
+                <p>
+                  runge_kutta_dopri5
+                </p>
+              </td></tr>
+<tr><td>
+                <p>
+                  runge_kutta_fehlberg78
+                </p>
+              </td></tr>
+<tr><td>
+                <p>
+                  symplectic_euler
+                </p>
+              </td></tr>
+<tr><td>
+                <p>
+                  symplectic_rkn_sb3a_mclachlan
+                </p>
+              </td></tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break"><div class="table">
+<a name="boost_sandbox_numeric_odeint.odeint_in_detail.using_boost__range.algebra_supporting_boost_range"></a><p class="title"><b>Table&#160;1.11.&#160;Algebra supporting Boost.Range</b></p>
+<div class="table-contents"><table class="table" summary="Algebra supporting Boost.Range">
+<colgroup><col></colgroup>
+<thead><tr><th>
+                <p>
+                  algebra
+                </p>
+              </th></tr></thead>
+<tbody>
+<tr><td>
+                <p>
+                  range_algebra
+                </p>
+              </td></tr>
+<tr><td>
+                <p>
+                  thrust_algebra
+                </p>
+              </td></tr>
+</tbody>
+</table></div>
+</div>
+<br class="table-break">
 </div>
 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 <td align="left"></td>

doc/boost_sandbox_numeric_odeint/old_reference/stepper_classes.html

@@ -21,7 +21,7 @@
       classes</a>
 </h3></div></div></div>
 <div class="table">
-<a name="boost_sandbox_numeric_odeint.old_reference.stepper_classes.stepper_algorithms"></a><p class="title"><b>Table&#160;1.10.&#160;Stepper Algorithms</b></p>
+<a name="boost_sandbox_numeric_odeint.old_reference.stepper_classes.stepper_algorithms"></a><p class="title"><b>Table&#160;1.12.&#160;Stepper Algorithms</b></p>
 <div class="table-contents"><table class="table" summary="Stepper Algorithms">
 <colgroup>
 <col>

doc/index.html

@@ -125,7 +125,7 @@
 </div>
 </div>
 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left"><p><small>Last revised: April 02, 2012 at 16:04:40 GMT</small></p></td>
+<td align="left"><p><small>Last revised: April 03, 2012 at 11:27:53 GMT</small></p></td>
 <td align="right"><div class="copyright-footer"></div></td>
 </tr></table>
 <hr>

libs/numeric/odeint/doc/details_boost_range.qbk

@@ -1,11 +1,44 @@
 [section Using boost::range]
 
-Most steppers in odeint also accept the state give as a range. A range is sequence of values modelled by a range concept, see __boost_range for an overview over existing concepts and examples of ranges.
+Most steppers in odeint also accept the state give as a range. A range is sequence of values modelled by a range concept. See __boost_range for an overview over existing concepts and examples of ranges. This means that the `state_type` of the stepper must not necessarily used to call the `do_step` method.
 
-state type mus not necessary be used in the steppers
+One use case for __boost_range in odeint has been shown in __tut_chaotic_system where the state consists of two parts: one for the original state and one for the perturbations. The ranges are used to initialize (solve) only the system part where the perturbation part is not touched, that is a range consisting only of the system part is used. After that the complete state including also the perturbations is solved.
 
-example
+Another use case is a system consisting of coupled units where you want to initialize each unit separately with the ODE of the uncoupled unit. An example is a chain of coupled van-der-Pol-oscillators which are initialized uniformily from the uncoupled van-der-Pol-oscillator. Then you can use __boost_range to solve only one individual oscillator in the chain.
 
-table which steppers support boost::range and with which algebra
+An example was given in __tut_chaotic_system tutorial. Using Boost.Range usually means that your system function needs to adapt to the iterators of Boost.Range. That is, your function is called with a range and you need to get the iterators from that range. This can easily be done. You have to implement your system as a class or a struct and you have to templatize the `operator()`. Then you can use the `range_iterator`-meta function and `boost::begin` and `boost::end` to obtain the iterators of your range:
+
+``
+class sys
+{
+    template< class State , class Deriv >
+    void operator()( const State &x_ , Deriv &dxdt_ , double t ) const
+    {
+         typename boost::range_iterator< const State >::type x = boost::begin( x_ );
+         typename boost::range_iterator< Deriv >::type dxdt = boost::begin( dxdt_ );
+
+         // fill dxdt
+    }
+};
+``
+
+If your range is a random access-range you can also apply the bracket operator to the iterator to access the elements in the range:
+``
+class sys
+{
+    template< class State , class Deriv >
+    void operator()( const State &x_ , Deriv &dxdt_ , double t ) const
+    {
+         typename boost::range_iterator< const State >::type x = boost::begin( x_ );
+         typename boost::range_iterator< Deriv >::type dxdt = boost::begin( dxdt_ );
+
+         dxdt[0] = f1( x[0] , x[1] );
+         dxdt[1] = f2( x[0] , x[1] );
+    }
+};
+``
+
+The following two tables show which steppers and which algebras are compatible with __boost_range.
+[include range_table.qbk]
 
 [endsect]

libs/numeric/odeint/doc/odeint.qbk

@@ -66,6 +66,8 @@
     [link boost_sandbox_numeric_odeint.odeint_in_detail.integrate_functions integrate functions]]
 [def __tut_solar_system
     [link boost_sandbox_numeric_odeint.tutorial.solar_system Solar System]]
+[def __tut_chaotic_system
+    [link boost_sandbox_numeric_odeint.tutorial.chaotic_systems_and_lyapunov_exponents Chaotic system]]
 [def __using_steppers
     [link boost_sandbox_numeric_odeint.odeint_in_detail.steppers.using_steppers Using steppers]]
 [def __generation_functions

libs/numeric/odeint/doc/range_table.qbk

@@ -0,0 +1,57 @@
+[/
+Steppers supporting __boost_range:
+
+* adams_bashforth_moulton
+* bulirsch_stoer_dense_out
+* bulirsch_stoer
+* controlled_runge_kutta
+* dense_output_runge_kutta
+* euler
+* explicit_error_generic_rk
+* explicit_generic_rk
+* rosenbrock4_controller
+* rosenbrock4_dense_output
+* rosenbrock4
+* runge_kutta4_classic
+* runge_kutta4
+* runge_kutta_cash_karp54_classic
+* runge_kutta_cash_karp54
+* runge_kutta_dopri5
+* runge_kutta_fehlberg78
+* symplectic_euler
+* symplectic_rkn_sb3a_mclachlan
+
+Algebras supporting __boost_range
+
+* range_algebra
+* thrust_algebra
+/]
+
+[table Steppers supporting Boost.Range
+  [[Stepper]]
+  [[adams_bashforth_moulton]]
+  [[bulirsch_stoer_dense_out]]
+  [[bulirsch_stoer]]
+  [[controlled_runge_kutta]]
+  [[dense_output_runge_kutta]]
+  [[euler]]
+  [[explicit_error_generic_rk]]
+  [[explicit_generic_rk]]
+  [[rosenbrock4_controller]]
+  [[rosenbrock4_dense_output]]
+  [[rosenbrock4]]
+  [[runge_kutta4_classic]]
+  [[runge_kutta4]]
+  [[runge_kutta_cash_karp54_classic]]
+  [[runge_kutta_cash_karp54]]
+  [[runge_kutta_dopri5]]
+  [[runge_kutta_fehlberg78]]
+  [[symplectic_euler]]
+  [[symplectic_rkn_sb3a_mclachlan]]
+]
+
+[table Algebra supporting Boost.Range
+  [[algebra]]
+  [[range_algebra]]
+  [[thrust_algebra]]
+]