3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4 <title>Integrate functions</title>
5 <link rel="stylesheet" href="../../../../../../../doc/src/boostbook.css" type="text/css">
6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
7 <link rel="home" href="../../index.html" title="Chapter 1. Boost.Numeric.Odeint">
8 <link rel="up" href="../odeint_in_detail.html" title="odeint in detail">
9 <link rel="prev" href="generation_functions.html" title="Generation functions">
10 <link rel="next" href="iterators_and_ranges.html" title="Iterators and Ranges">
12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13 <table cellpadding="2" width="100%"><tr>
14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../logo.jpg"></td>
15 <td align="center"><a href="../../../../../../../index.html">Home</a></td>
16 <td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
19 <td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
22 <div class="spirit-nav">
23 <a accesskey="p" href="generation_functions.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../odeint_in_detail.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="iterators_and_ranges.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
26 <div class="titlepage"><div><div><h3 class="title">
27 <a name="boost_numeric_odeint.odeint_in_detail.integrate_functions"></a><a class="link" href="integrate_functions.html" title="Integrate functions">Integrate
29 </h3></div></div></div>
31 Integrate functions perform the time evolution of a given ODE from some starting
32 time <span class="emphasis"><em>t<sub>0</sub></em></span> to a given end time <span class="emphasis"><em>t<sub>1</sub></em></span>
33 and starting at state <span class="emphasis"><em>x<sub>0</sub></em></span> by subsequent calls of a given
34 stepper's <code class="computeroutput"><span class="identifier">do_step</span></code> function.
35 Additionally, the user can provide an __observer to analyze the state during
36 time evolution. There are five different integrate functions which have different
37 strategies on when to call the observer function during integration. All
38 of the integrate functions except <code class="computeroutput"><span class="identifier">integrate_n_steps</span></code>
39 can be called with any stepper following one of the stepper concepts: <a class="link" href="../concepts/stepper.html" title="Stepper">Stepper</a> , <a class="link" href="../concepts/error_stepper.html" title="Error Stepper">Error
40 Stepper</a> , <a class="link" href="../concepts/controlled_stepper.html" title="Controlled Stepper">Controlled
41 Stepper</a> , <a class="link" href="../concepts/dense_output_stepper.html" title="Dense Output Stepper">Dense
42 Output Stepper</a>. Depending on the abilities of the stepper, the integrate
43 functions make use of step-size control or dense output.
46 <a name="boost_numeric_odeint.odeint_in_detail.integrate_functions.h0"></a>
47 <span class="phrase"><a name="boost_numeric_odeint.odeint_in_detail.integrate_functions.equidistant_observer_calls"></a></span><a class="link" href="integrate_functions.html#boost_numeric_odeint.odeint_in_detail.integrate_functions.equidistant_observer_calls">Equidistant
51 If observer calls at equidistant time intervals <span class="emphasis"><em>dt</em></span> are
52 needed, the <code class="computeroutput"><span class="identifier">integrate_const</span></code>
53 or <code class="computeroutput"><span class="identifier">integrate_n_steps</span></code> function
54 should be used. We start with explaining <code class="computeroutput"><span class="identifier">integrate_const</span></code>:
57 <code class="computeroutput"><span class="identifier">integrate_const</span><span class="special">(</span>
58 <span class="identifier">stepper</span> <span class="special">,</span>
59 <span class="identifier">system</span> <span class="special">,</span>
60 <span class="identifier">x0</span> <span class="special">,</span>
61 <span class="identifier">t0</span> <span class="special">,</span>
62 <span class="identifier">t1</span> <span class="special">,</span>
63 <span class="identifier">dt</span> <span class="special">)</span></code>
66 <code class="computeroutput"><span class="identifier">integrate_const</span><span class="special">(</span>
67 <span class="identifier">stepper</span> <span class="special">,</span>
68 <span class="identifier">system</span> <span class="special">,</span>
69 <span class="identifier">x0</span> <span class="special">,</span>
70 <span class="identifier">t0</span> <span class="special">,</span>
71 <span class="identifier">t1</span> <span class="special">,</span>
72 <span class="identifier">dt</span> <span class="special">,</span>
73 <span class="identifier">observer</span> <span class="special">)</span></code>
76 These integrate the ODE given by <code class="computeroutput"><span class="identifier">system</span></code>
77 with subsequent steps from <code class="computeroutput"><span class="identifier">stepper</span></code>.
78 Integration start at <code class="computeroutput"><span class="identifier">t0</span></code> and
79 <code class="computeroutput"><span class="identifier">x0</span></code> and ends at some <span class="emphasis"><em>t'
80 = t<sub>0</sub> + n dt</em></span> with <span class="emphasis"><em>n</em></span> such that <span class="emphasis"><em>t<sub>1</sub> -
81 dt < t' <= t<sub>1</sub></em></span>. <code class="computeroutput"><span class="identifier">x0</span></code>
82 is changed to the approximative solution <span class="emphasis"><em>x(t')</em></span> at the
83 end of integration. If provided, the <code class="computeroutput"><span class="identifier">observer</span></code>
84 is invoked at times <span class="emphasis"><em>t<sub>0</sub></em></span>, <span class="emphasis"><em>t<sub>0</sub> + dt</em></span>,
85 <span class="emphasis"><em>t<sub>0</sub> + 2dt</em></span>, ... ,<span class="emphasis"><em>t'</em></span>. <code class="computeroutput"><span class="identifier">integrate_const</span></code> returns the number of steps
86 performed during the integration. Note that if you are using a simple <a class="link" href="../concepts/stepper.html" title="Stepper">Stepper</a> or <a class="link" href="../concepts/error_stepper.html" title="Error Stepper">Error
87 Stepper</a> and want to make exactly <code class="computeroutput"><span class="identifier">n</span></code>
88 steps you should prefer the <code class="computeroutput"><span class="identifier">integrate_n_steps</span></code>
91 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
93 If <code class="computeroutput"><span class="identifier">stepper</span></code> is a <a class="link" href="../concepts/stepper.html" title="Stepper">Stepper</a> or <a class="link" href="../concepts/error_stepper.html" title="Error Stepper">Error Stepper</a>
94 then <code class="computeroutput"><span class="identifier">dt</span></code> is also the step
95 size used for integration and the observer is called just after every
99 If <code class="computeroutput"><span class="identifier">stepper</span></code> is a <a class="link" href="../concepts/controlled_stepper.html" title="Controlled Stepper">Controlled
100 Stepper</a> then <code class="computeroutput"><span class="identifier">dt</span></code>
101 is the initial step size. The actual step size will change due to error
102 control during time evolution. However, if an observer is provided the
103 step size will be adjusted such that the algorithm always calculates
104 <span class="emphasis"><em>x(t)</em></span> at <span class="emphasis"><em>t = t<sub>0</sub> + n dt</em></span> and calls
105 the observer at that point. Note that the use of <a class="link" href="../concepts/controlled_stepper.html" title="Controlled Stepper">Controlled
106 Stepper</a> is reasonable here only if <code class="computeroutput"><span class="identifier">dt</span></code>
107 is considerably larger than typical step sizes used by the stepper.
109 <li class="listitem">
110 If <code class="computeroutput"><span class="identifier">stepper</span></code> is a <a class="link" href="../concepts/dense_output_stepper.html" title="Dense Output Stepper">Dense Output
111 Stepper</a> then <code class="computeroutput"><span class="identifier">dt</span></code>
112 is the initial step size. The actual step size will be adjusted during
113 integration due to error control. If an observer is provided dense output
114 is used to calculate <span class="emphasis"><em>x(t)</em></span> at <span class="emphasis"><em>t = t<sub>0</sub> + n
119 <a name="boost_numeric_odeint.odeint_in_detail.integrate_functions.h1"></a>
120 <span class="phrase"><a name="boost_numeric_odeint.odeint_in_detail.integrate_functions.integrate_a_given_number_of_steps"></a></span><a class="link" href="integrate_functions.html#boost_numeric_odeint.odeint_in_detail.integrate_functions.integrate_a_given_number_of_steps">Integrate
121 a given number of steps</a>
124 This function is very similar to <code class="computeroutput"><span class="identifier">integrate_const</span></code>
125 above. The only difference is that it does not take the end time as parameter,
126 but rather the number of steps. The integration is then performed until the
127 time <code class="computeroutput"><span class="identifier">t0</span><span class="special">+</span><span class="identifier">n</span><span class="special">*</span><span class="identifier">dt</span></code>.
130 <code class="computeroutput"><span class="identifier">integrate_n_steps</span><span class="special">(</span>
131 <span class="identifier">stepper</span> <span class="special">,</span>
132 <span class="identifier">system</span> <span class="special">,</span>
133 <span class="identifier">x0</span> <span class="special">,</span>
134 <span class="identifier">t0</span> <span class="special">,</span>
135 <span class="identifier">dt</span> <span class="special">,</span>
136 <span class="identifier">n</span> <span class="special">)</span></code>
139 <code class="computeroutput"><span class="identifier">integrate_n_steps</span><span class="special">(</span>
140 <span class="identifier">stepper</span> <span class="special">,</span>
141 <span class="identifier">system</span> <span class="special">,</span>
142 <span class="identifier">x0</span> <span class="special">,</span>
143 <span class="identifier">t0</span> <span class="special">,</span>
144 <span class="identifier">dt</span> <span class="special">,</span>
145 <span class="identifier">n</span> <span class="special">,</span> <span class="identifier">observer</span> <span class="special">)</span></code>
148 Integrates the ODE given by <code class="computeroutput"><span class="identifier">system</span></code>
149 with subsequent steps from <code class="computeroutput"><span class="identifier">stepper</span></code>
150 starting at <span class="emphasis"><em>x<sub>0</sub></em></span> and <span class="emphasis"><em>t<sub>0</sub></em></span>. If provided,
151 <code class="computeroutput"><span class="identifier">observer</span></code> is called after
152 every step and at the beginning with <code class="computeroutput"><span class="identifier">t0</span></code>,
153 similar as above. The approximate result for <span class="emphasis"><em>x( t<sub>0</sub> + n dt )</em></span>
154 is stored in <code class="computeroutput"><span class="identifier">x0</span></code>. This function
155 returns the end time <code class="computeroutput"><span class="identifier">t0</span> <span class="special">+</span> <span class="identifier">n</span><span class="special">*</span><span class="identifier">dt</span></code>.
158 <a name="boost_numeric_odeint.odeint_in_detail.integrate_functions.h2"></a>
159 <span class="phrase"><a name="boost_numeric_odeint.odeint_in_detail.integrate_functions.observer_calls_at_each_step"></a></span><a class="link" href="integrate_functions.html#boost_numeric_odeint.odeint_in_detail.integrate_functions.observer_calls_at_each_step">Observer
160 calls at each step</a>
163 If the observer should be called at each time step then the <code class="computeroutput"><span class="identifier">integrate_adaptive</span></code> function should be used.
164 Note that in the case of <a class="link" href="../concepts/controlled_stepper.html" title="Controlled Stepper">Controlled
165 Stepper</a> or <a class="link" href="../concepts/dense_output_stepper.html" title="Dense Output Stepper">Dense
166 Output Stepper</a> this leads to non-equidistant observer calls as the
170 <code class="computeroutput"><span class="identifier">integrate_adaptive</span><span class="special">(</span>
171 <span class="identifier">stepper</span> <span class="special">,</span>
172 <span class="identifier">system</span> <span class="special">,</span>
173 <span class="identifier">x0</span> <span class="special">,</span>
174 <span class="identifier">t0</span> <span class="special">,</span>
175 <span class="identifier">t1</span> <span class="special">,</span>
176 <span class="identifier">dt</span> <span class="special">)</span></code>
179 <code class="computeroutput"><span class="identifier">integrate_adaptive</span><span class="special">(</span>
180 <span class="identifier">stepper</span> <span class="special">,</span>
181 <span class="identifier">system</span> <span class="special">,</span>
182 <span class="identifier">x0</span> <span class="special">,</span>
183 <span class="identifier">t0</span> <span class="special">,</span>
184 <span class="identifier">t1</span> <span class="special">,</span>
185 <span class="identifier">dt</span> <span class="special">,</span>
186 <span class="identifier">observer</span> <span class="special">)</span></code>
189 Integrates the ODE given by <code class="computeroutput"><span class="identifier">system</span></code>
190 with subsequent steps from <code class="computeroutput"><span class="identifier">stepper</span></code>.
191 Integration start at <code class="computeroutput"><span class="identifier">t0</span></code> and
192 <code class="computeroutput"><span class="identifier">x0</span></code> and ends at <span class="emphasis"><em>t<sub>1</sub></em></span>.
193 <code class="computeroutput"><span class="identifier">x0</span></code> is changed to the approximative
194 solution <span class="emphasis"><em>x(t<sub>1</sub>)</em></span> at the end of integration. If provided,
195 the <code class="computeroutput"><span class="identifier">observer</span></code> is called after
196 each step (and before the first step at <code class="computeroutput"><span class="identifier">t0</span></code>).
197 <code class="computeroutput"><span class="identifier">integrate_adaptive</span></code> returns
198 the number of steps performed during the integration.
200 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
201 <li class="listitem">
202 If <code class="computeroutput"><span class="identifier">stepper</span></code> is a <a class="link" href="../concepts/stepper.html" title="Stepper">Stepper</a> or <a class="link" href="../concepts/error_stepper.html" title="Error Stepper">Error Stepper</a>
203 then <code class="computeroutput"><span class="identifier">dt</span></code> is the step size
204 used for integration and <code class="computeroutput"><span class="identifier">integrate_adaptive</span></code>
205 behaves like <code class="computeroutput"><span class="identifier">integrate_const</span></code>
206 except that for the last step the step size is reduced to ensure we end
207 exactly at <code class="computeroutput"><span class="identifier">t1</span></code>. If provided,
208 the observer is called at each step.
210 <li class="listitem">
211 If <code class="computeroutput"><span class="identifier">stepper</span></code> is a <a class="link" href="../concepts/controlled_stepper.html" title="Controlled Stepper">Controlled
212 Stepper</a> then <code class="computeroutput"><span class="identifier">dt</span></code>
213 is the initial step size. The actual step size is changed according to
214 error control of the stepper. For the last step, the step size will be
215 reduced to ensure we end exactly at <code class="computeroutput"><span class="identifier">t1</span></code>.
216 If provided, the observer is called after each time step (and before
217 the first step at <code class="computeroutput"><span class="identifier">t0</span></code>).
219 <li class="listitem">
220 If stepper is a <a class="link" href="../concepts/dense_output_stepper.html" title="Dense Output Stepper">Dense
221 Output Stepper</a> then <code class="computeroutput"><span class="identifier">dt</span></code>
222 is the initial step size and <code class="computeroutput"><span class="identifier">integrate_adaptive</span></code>
223 behaves just like for <a class="link" href="../concepts/controlled_stepper.html" title="Controlled Stepper">Controlled
224 Stepper</a> above. No dense output is used.
228 <a name="boost_numeric_odeint.odeint_in_detail.integrate_functions.h3"></a>
229 <span class="phrase"><a name="boost_numeric_odeint.odeint_in_detail.integrate_functions.observer_calls_at_given_time_points"></a></span><a class="link" href="integrate_functions.html#boost_numeric_odeint.odeint_in_detail.integrate_functions.observer_calls_at_given_time_points">Observer
230 calls at given time points</a>
233 If the observer should be called at some user given time points the <code class="computeroutput"><span class="identifier">integrate_times</span></code> function should be used.
234 The times for observer calls are provided as a sequence of time values. The
235 sequence is either defined via two iterators pointing to begin and end of
236 the sequence or in terms of a <a href="http://www.boost.org/doc/libs/release/libs/range/" target="_top">Boost.Range</a>
240 <code class="computeroutput"><span class="identifier">integrate_times</span><span class="special">(</span>
241 <span class="identifier">stepper</span> <span class="special">,</span>
242 <span class="identifier">system</span> <span class="special">,</span>
243 <span class="identifier">x0</span> <span class="special">,</span>
244 <span class="identifier">times_start</span> <span class="special">,</span>
245 <span class="identifier">times_end</span> <span class="special">,</span>
246 <span class="identifier">dt</span> <span class="special">,</span>
247 <span class="identifier">observer</span> <span class="special">)</span></code>
250 <code class="computeroutput"><span class="identifier">integrate_times</span><span class="special">(</span>
251 <span class="identifier">stepper</span> <span class="special">,</span>
252 <span class="identifier">system</span> <span class="special">,</span>
253 <span class="identifier">x0</span> <span class="special">,</span>
254 <span class="identifier">time_range</span> <span class="special">,</span>
255 <span class="identifier">dt</span> <span class="special">,</span>
256 <span class="identifier">observer</span> <span class="special">)</span></code>
259 Integrates the ODE given by <code class="computeroutput"><span class="identifier">system</span></code>
260 with subsequent steps from <code class="computeroutput"><span class="identifier">stepper</span></code>.
261 Integration starts at <code class="computeroutput"><span class="special">*</span><span class="identifier">times_start</span></code>
262 and ends exactly at <code class="computeroutput"><span class="special">*(</span><span class="identifier">times_end</span><span class="special">-</span><span class="number">1</span><span class="special">)</span></code>.
263 <code class="computeroutput"><span class="identifier">x0</span></code> contains the approximate
264 solution at the end point of integration. This function requires an observer
265 which is invoked at the subsequent times <code class="computeroutput"><span class="special">*</span><span class="identifier">times_start</span><span class="special">++</span></code>
266 until <code class="computeroutput"><span class="identifier">times_start</span> <span class="special">==</span>
267 <span class="identifier">times_end</span></code>. If called with a <a href="http://www.boost.org/doc/libs/release/libs/range/" target="_top">Boost.Range</a>
268 <code class="computeroutput"><span class="identifier">time_range</span></code> the function behaves
269 the same with <code class="computeroutput"><span class="identifier">times_start</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">time_range</span>
270 <span class="special">)</span></code> and <code class="computeroutput"><span class="identifier">times_end</span>
271 <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">end</span><span class="special">(</span>
272 <span class="identifier">time_range</span> <span class="special">)</span></code>.
273 <code class="computeroutput"><span class="identifier">integrate_times</span></code> returns the
274 number of steps performed during the integration.
276 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
277 <li class="listitem">
278 If <code class="computeroutput"><span class="identifier">stepper</span></code> is a <a class="link" href="../concepts/stepper.html" title="Stepper">Stepper</a> or <a class="link" href="../concepts/error_stepper.html" title="Error Stepper">Error Stepper</a>
279 <code class="computeroutput"><span class="identifier">dt</span></code> is the step size used
280 for integration. However, whenever a time point from the sequence is
281 approached the step size <code class="computeroutput"><span class="identifier">dt</span></code>
282 will be reduced to obtain the state <span class="emphasis"><em>x(t)</em></span> exactly
285 <li class="listitem">
286 If <code class="computeroutput"><span class="identifier">stepper</span></code> is a <a class="link" href="../concepts/controlled_stepper.html" title="Controlled Stepper">Controlled
287 Stepper</a> then <code class="computeroutput"><span class="identifier">dt</span></code>
288 is the initial step size. The actual step size is adjusted during integration
289 according to error control. However, if a time point from the sequence
290 is approached the step size is reduced to obtain the state <span class="emphasis"><em>x(t)</em></span>
291 exactly at the time point.
293 <li class="listitem">
294 If <code class="computeroutput"><span class="identifier">stepper</span></code> is a <a class="link" href="../concepts/dense_output_stepper.html" title="Dense Output Stepper">Dense Output
295 Stepper</a> then <code class="computeroutput"><span class="identifier">dt</span></code>
296 is the initial step size. The actual step size is adjusted during integration
297 according to error control. Dense output is used to obtain the states
298 <span class="emphasis"><em>x(t)</em></span> at the time points from the sequence.
302 <a name="boost_numeric_odeint.odeint_in_detail.integrate_functions.h4"></a>
303 <span class="phrase"><a name="boost_numeric_odeint.odeint_in_detail.integrate_functions.convenience_integrate_function"></a></span><a class="link" href="integrate_functions.html#boost_numeric_odeint.odeint_in_detail.integrate_functions.convenience_integrate_function">Convenience
304 integrate function</a>
307 Additionally to the sophisticated integrate function above odeint also provides
308 a simple <code class="computeroutput"><span class="identifier">integrate</span></code> routine
309 which uses a dense output stepper based on <code class="computeroutput"><span class="identifier">runge_kutta_dopri5</span></code>
310 with standard error bounds <span class="emphasis"><em>10<sup>-6</sup></em></span> for the steps.
313 <code class="computeroutput"><span class="identifier">integrate</span><span class="special">(</span>
314 <span class="identifier">system</span> <span class="special">,</span>
315 <span class="identifier">x0</span> <span class="special">,</span>
316 <span class="identifier">t0</span> <span class="special">,</span>
317 <span class="identifier">t1</span> <span class="special">,</span>
318 <span class="identifier">dt</span> <span class="special">)</span></code>
321 <code class="computeroutput"><span class="identifier">integrate</span><span class="special">(</span>
322 <span class="identifier">system</span> <span class="special">,</span>
323 <span class="identifier">x0</span> <span class="special">,</span>
324 <span class="identifier">t0</span> <span class="special">,</span>
325 <span class="identifier">t1</span> <span class="special">,</span>
326 <span class="identifier">dt</span> <span class="special">,</span>
327 <span class="identifier">observer</span> <span class="special">)</span></code>
330 This function behaves exactly like <code class="computeroutput"><span class="identifier">integrate_adaptive</span></code>
331 above but no stepper has to be provided. It also returns the number of steps
332 performed during the integration.
335 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
336 <td align="left"></td>
337 <td align="right"><div class="copyright-footer">Copyright © 2009-2012 Karsten
338 Ahnert and Mario Mulansky<p>
339 Distributed under the Boost Software License, Version 1.0. (See accompanying
340 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
345 <div class="spirit-nav">
346 <a accesskey="p" href="generation_functions.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../odeint_in_detail.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="iterators_and_ranges.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>