docs for generation functions

2025-05-09 23:24:01 +00:00 · 2012-04-05 09:12:43 +02:00 · 2012-04-05 09:12:43 +02:00 · 41949f94f8
commit 41949f94f8
parent 086dd5a298
4 changed files with 139 additions and 8 deletions
--- a/doc/boost_sandbox_numeric_odeint/odeint_in_detail/generation_functions.html
+++ b/doc/boost_sandbox_numeric_odeint/odeint_in_detail/generation_functions.html
@ -35,9 +35,8 @@
      </p>
 <p>
        The first two parameters are the absolute and the relative error tolerances
-        and the third parameter is the stepper. Of course you can also infer the
-        type from the classical <code class="computeroutput"><span class="identifier">result_of</span></code>
-        mechanism:
+        and the third parameter is the stepper. In C++03 you can infer the type from
+        the <code class="computeroutput"><span class="identifier">result_of</span></code> mechanism:
      </p>
 <p>
 </p>
@ -47,8 +46,71 @@
 <p>
      </p>
 <p>
-        explain the mechanis and how your own steppers can be used with the generation
-        functions
+        To use your own steppers with the <code class="computeroutput"><span class="identifier">make_controlled</span></code>
+        or <code class="computeroutput"><span class="identifier">make_dense_output</span></code> you
+        need to specialize two class templates. Suppose your steppers are called
+        <code class="computeroutput"><span class="identifier">custom_stepper</span></code>, <code class="computeroutput"><span class="identifier">custom_controller</span></code> and <code class="computeroutput"><span class="identifier">custom_dense_output</span></code>.
+        Then, the first class you need to specialize is <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">numeric</span><span class="special">::</span><span class="identifier">get_controller</span></code>,
+        a meta function returning the type of the controller:
+      </p>
+<p>
+</p>
+<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">numeric</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">odeint</span> <span class="special">{</span>
+
+<span class="keyword">template</span><span class="special">&lt;&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">get_controller</span><span class="special">&lt;</span> <span class="identifier">custom_stepper</span> <span class="special">&gt;</span>
+<span class="special">{</span>
+    <span class="keyword">typedef</span> <span class="identifier">custom_controller</span> <span class="identifier">type</span><span class="special">;</span>
+<span class="special">};</span>
+
+<span class="special">}</span> <span class="special">}</span> <span class="special">}</span>
+</pre>
+<p>
+      </p>
+<p>
+        The second one is a factory class <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">numeric</span><span class="special">::</span><span class="identifier">odeint</span><span class="special">::</span><span class="identifier">controller_factory</span></code>
+        which the constructs the controller from the tolerances and the stepper.
+        In our dummy implementation this class is
+      </p>
+<p>
+</p>
+<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">numeric</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">odeint</span> <span class="special">{</span>
+
+<span class="keyword">template</span><span class="special">&lt;&gt;</span>
+<span class="keyword">struct</span> <span class="identifier">controller_factory</span><span class="special">&lt;</span> <span class="identifier">custom_stepper</span> <span class="special">,</span> <span class="identifier">custom_controller</span> <span class="special">&gt;</span>
+<span class="special">{</span>
+    <span class="identifier">custom_controller</span> <span class="keyword">operator</span><span class="special">()(</span> <span class="keyword">double</span> <span class="identifier">abs_tol</span> <span class="special">,</span> <span class="keyword">double</span> <span class="identifier">rel_tol</span> <span class="special">,</span> <span class="keyword">const</span> <span class="identifier">custom_stepper</span> <span class="special">&amp;</span> <span class="special">)</span> <span class="keyword">const</span>
+    <span class="special">{</span>
+        <span class="keyword">return</span> <span class="identifier">custom_controller</span><span class="special">();</span>
+    <span class="special">}</span>
+<span class="special">};</span>
+
+<span class="special">}</span> <span class="special">}</span> <span class="special">}</span>
+</pre>
+<p>
+      </p>
+<p>
+        This is all to use the <code class="computeroutput"><span class="identifier">make_controlled</span></code>
+        mechanism. Now you can use your controller via
+      </p>
+<p>
+</p>
+<pre class="programlisting"><span class="keyword">auto</span> <span class="identifier">stepper5</span> <span class="special">=</span> <span class="identifier">make_controlled</span><span class="special">(</span> <span class="number">1.0e-6</span> <span class="special">,</span> <span class="number">1.0e-6</span> <span class="special">,</span> <span class="identifier">custom_stepper</span><span class="special">()</span> <span class="special">);</span>
+</pre>
+<p>
+      </p>
+<p>
+        For the dense_output_stepper everything works similar. Here you have to specialize
+        <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">numeric</span><span class="special">::</span><span class="identifier">odeint</span><span class="special">::</span><span class="identifier">get_dense_output</span></code> and <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">numeric</span><span class="special">::</span><span class="identifier">odeint</span><span class="special">::</span><span class="identifier">dense_output_factory</span></code>.
+        These two classes have the same syntax as their relatives <code class="computeroutput"><span class="identifier">get_controller</span></code>
+        and <code class="computeroutput"><span class="identifier">controller_factory</span></code>.
+      </p>
+<p>
+        Of course, all controllers and dense-output steppers in odeint can be used
+        with these mechanisms. In the table below you will find, which steppers is
+        contructed from <code class="computeroutput"><span class="identifier">make_controlled</span></code>
+        or <code class="computeroutput"><span class="identifier">make_dense_output</span></code> if applied
+        on a stepper from odeint:
      </p>
 <div class="table">
 <a name="boost_sandbox_numeric_odeint.odeint_in_detail.generation_functions.generation_functions_make_controlled__abs_error___rel_error___stepper__"></a><p class="title"><b>Table&#160;1.8.&#160;Generation functions make_controlled( abs_error , rel_error , stepper
--- a/doc/index.html
+++ b/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 04, 2012 at 06:30:00 GMT</small></p></td>
+<td align="left"><p><small>Last revised: April 05, 2012 at 07:11:14 GMT</small></p></td>
 <td align="right"><div class="copyright-footer"></div></td>
 </tr></table>
 <hr>
--- a/libs/numeric/odeint/doc/details_generation_functions.qbk
+++ b/libs/numeric/odeint/doc/details_generation_functions.qbk
@ -6,11 +6,25 @@ In the tutorial we have learned how we can use the generation functions `make_co

 [generation_functions_syntax_auto]

-The first two parameters are the absolute and the relative error tolerances and the third parameter is the stepper. In C++03 you can infer the type from the classical `result_of` mechanism:
+The first two parameters are the absolute and the relative error tolerances and the third parameter is the stepper. In C++03 you can infer the type from the `result_of` mechanism:

 [generation_functions_syntax_result_of]

-explain the mechanis and how your own steppers can be used with the generation functions
+To use your own steppers with the `make_controlled` or `make_dense_output` you need to specialize two class templates. Suppose your steppers are called `custom_stepper`, `custom_controller` and `custom_dense_output`. Then, the first class you need to specialize is `boost::numeric::get_controller`, a meta function returning the type of the controller:
+
+[generation_functions_get_controller]
+
+The second one is a factory class `boost::numeric::odeint::controller_factory` which the constructs the controller from the tolerances and the stepper. In our dummy implementation this class is
+
+[generation_functions_controller_factory]
+
+This is all to use the `make_controlled` mechanism. Now you can use your controller via
+
+[generation_functions_example_custom_controller]
+
+For the dense_output_stepper everything works similar. Here you have to specialize `boost::numeric::odeint::get_dense_output` and `boost::numeric::odeint::dense_output_factory`. These two classes have the same syntax as their relatives `get_controller` and `controller_factory`.
+
+Of course, all controllers and dense-output steppers in odeint can be used with these mechanisms. In the table below you will find, which steppers is contructed from `make_controlled` or `make_dense_output` if applied on a stepper from odeint:

 [include make_controlled_table.qbk]
 [include make_dense_output_table.qbk]
--- a/libs/numeric/odeint/examples/generation_functions.cpp
+++ b/libs/numeric/odeint/examples/generation_functions.cpp
@ -19,6 +19,55 @@ typedef std::array< double , 1 > state_type;

 using namespace boost::numeric::odeint;

+
+//[ generation_functions_own_steppers
+class custom_stepper
+{
+public:
+
+    typedef double value_type;
+    // ...
+};
+
+class custom_controller
+{
+    // ...
+};
+
+class custom_dense_output
+{
+    // ...
+};
+//]
+
+
+//[ generation_functions_get_controller
+namespace boost { namespace numeric { namespace odeint {
+
+template<>
+struct get_controller< custom_stepper >
+{
+    typedef custom_controller type;
+};
+
+} } }
+//]
+
+//[ generation_functions_controller_factory
+namespace boost { namespace numeric { namespace odeint {
+
+template<>
+struct controller_factory< custom_stepper , custom_controller >
+{
+    custom_controller operator()( double abs_tol , double rel_tol , const custom_stepper & ) const
+    {
+        return custom_controller();
+    }
+};
+
+} } }
+//]
+
 int main( int argc , char **argv )
 {
    {
@ -34,5 +83,11 @@ int main( int argc , char **argv )
        result_of::make_dense_output< stepper_type >::type stepper4 = make_dense_output( 1.0e-6 , 1.0e-6 , stepper_type() );
        //]
    }
+
+    {
+        //[ generation_functions_example_custom_controller
+        auto stepper5 = make_controlled( 1.0e-6 , 1.0e-6 , custom_stepper() );
+        //]
+    }
    return 0;
 }