[ceph.git] / ceph / src / boost / libs / numeric / odeint / doc / details_iterators.qbk

[/============================================================================
  Boost.odeint

  Copyright 2012-2013 Karsten Ahnert
  Copyright 2012-2013 Mario Mulansky
  Copyright 2012 Sylwester Arabas

  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)
=============================================================================/]


[section Iterators and Ranges]

[section Examples]

odeint supports iterators that iterate along an approximate solution of an ordinary differential equation. Iterators offer you an alternative to the integrate functions. Furthermore, many of the standard algorithms in the C++ standard library and Boost.Range can be used with the odeint's iterators.

[import ../examples/const_step_iterator.cpp]

Several iterator types are provided, in consistence with the
__integrate_functions. Hence there are `const_step_iterator`,
`adaptive_step_iterator`, `n_step_iterator` and `times_iterator` -- each of
them in two versions: either with only the `state` or with a
`std::pair<state,time>` as value type.  They are all single pass iterators. In
the following, we show a few examples of how to use those iterators together
with std algorithms.

[const_step_iterator_accumulate]

In this example all x-values of the solution are accumulated. Note, how
dereferencing the iterator gives the current state `x` of the ODE (the second
argument of the accumulate lambda). The iterator
itself does not occur directly in this example but it is generated by the
factory functions `make_const_step_iterator_begin` and
`make_const_step_iterator_end`. odeint also supports Boost.Range, that allows
to write the above example in a more compact form with the factory function
`make_const_step_range`, but now using `boost::accumulate` from __bost_range:

[const_step_iterator_accumulate_range]

The second iterator type is also a iterator with const step size. But the value type of this iterator consists here of a pair of the time and the state of the solution of the ODE. An example is

[const_step_time_iterator_accumulate_range]

The factory functions are now `make_const_step_time_iterator_begin`,
`make_const_step_time_iterator_end` and `make_const_step_time_range`.
Note, how the lambda now expects a `std::pair` as this is the value type of
the `const_step_time_iterator`'s.


[import ../examples/adaptive_iterator.cpp]

Next, we discuss the adaptive iterators which are completely
analogous to the const step iterators, but are based on adaptive stepper
routines and thus adjust the step size during the iteration. Examples are

[adaptive_iterator_accumulate_range]

[adaptive_time_iterator_accumulate_range]

[note 'adaptive_iterator` and `adaptive_time_iterator' can only be used with
__controlled_stepper or __dense_output_stepper.]

In general one can say that iterating over a range of a `const_step_iterator`
behaves like an `integrate_const` function call, and similarly for
`adaptive_iterator` and `integrate_adaptive`, `n_step_iterator` and
`integrate_n_steps`, and finally `times_iterator` and `integrate_times`.

Below we list the most important properties of the exisiting iterators:

[endsect]

[section const_step_iterator]

* Definition: `const_step_iterator< Stepper , System , State >`
* `value_type` is `State`
* `reference_type` is `State const&`
* Factory functions
  * `make_const_step_iterator_begin( stepper , system , state , t_start , t_end , dt )`
  * `make_const_step_iterator_end( stepper , system , state )`
  * `make_const_step_range( stepper , system , state , t_start , t_end , dt )`
* This stepper works with all steppers fulfilling the Stepper concept or the DenseOutputStepper concept.
* The value of `state` is the current state of the ODE during the iteration.

[endsect]

[section const_step_time_iterator]

* Definition: `const_step_time_iterator< Stepper , System , State >`
* `value_type` is `std::pair< State , Stepper::time_type >`
* `reference_type` is `std::pair< State const& , Stepper::time_type > const&`
* Factory functions
  * `make_const_step_time_iterator_begin( stepper , system , state , t_start , t_end , dt )`
  * `make_const_step_time_iterator_end( stepper , system , state )`
  * `make_const_step_time_range( stepper , system , state , t_start , t_end , dt )`
* This stepper works with all steppers fulfilling the Stepper concept or the DenseOutputStepper concept.
* This stepper updates the value of `state`. The value of `state` is the current state of the ODE during the iteration.


[endsect]


[section adaptive_step_iterator]

* Definition: `adaptive_iterator< Stepper , System , State >`
* `value_type` is `State`
* `reference_type` is `State const&`
* Factory functions
  * `make_adaptive_iterator_begin( stepper , system , state , t_start , t_end , dt )`
  * `make_adaptive_iterator_end( stepper , system , state )`
  * `make_adaptive_range( stepper , system , state , t_start , t_end , dt )`
* This stepper works with all steppers fulfilling the ControlledStepper concept or the DenseOutputStepper concept.
* For steppers fulfilling the ControlledStepper concept `state` is modified according to the current state of the ODE. For DenseOutputStepper the state is not modified due to performance optimizations, but the steppers itself.


[endsect]

[section adaptive_step_time_iterator]

* Definition: `adaptive_iterator< Stepper , System , State >`
* `value_type` is `std::pair< State , Stepper::time_type >`
* `reference_type` is `std::pair< State const& , Stepper::time_type > const&`
* Factory functions
  * `make_adaptive_time_iterator_begin( stepper , system , state , t_start , t_end , dt )`
  * `make_adaptive_time_iterator_end( stepper , system , state )`
  * `make_adaptive_time_range( stepper , system , state , t_start , t_end , dt )`
* This stepper works with all steppers fulfilling the ControlledStepper concept or the DenseOutputStepper concept.
* For steppers fulfilling the ControlledStepper concept `state` is modified according to the current state of the ODE. For DenseOutputStepper the state is not modified due to performance optimizations, but the stepper itself.


[endsect]


[section n_step_iterator]

* Definition: `n_step_iterator< Stepper , System , State >`
* `value_type` is `State`
* `reference_type` is `State const&`
* Factory functions
  * `make_n_step_iterator_begin( stepper , system , state , t_start , dt , num_of_steps )`
  * `make_n_step_iterator_end( stepper , system , state )`
  * `make_n_step_range( stepper , system , state , t_start , dt , num_of_steps )`
* This stepper works with all steppers fulfilling the Stepper concept or the DenseOutputStepper concept.
* The value of `state` is the current state of the ODE during the iteration.

[endsect]

[section n_step_time_iterator]

* Definition: `n_step_time_iterator< Stepper , System , State >`
* `value_type` is `std::pair< State , Stepper::time_type >`
* `reference_type` is `std::pair< State const& , Stepper::time_type > const&`
* Factory functions
  * `make_n_step_time_iterator_begin( stepper , system , state , t_start , dt , num_of_steps )`
  * `make_n_step_time_iterator_end( stepper , system , state )`
  * `make_n_step_time_range( stepper , system , state , t_start , dt , num_of_steps )`
* This stepper works with all steppers fulfilling the Stepper concept or the DenseOutputStepper concept.
* This stepper updates the value of `state`. The value of `state` is the current state of the ODE during the iteration.


[endsect]


[section times_iterator]

* Definition: `times_iterator< Stepper , System , State , TimeIterator >`
* `value_type` is `State`
* `reference_type` is `State const&`
* Factory functions
  * `make_times_iterator_begin( stepper , system , state , t_start , t_end , dt )`
  * `make_times_iterator_end( stepper , system , state )`
  * `make_times_range( stepper , system , state , t_start , t_end , dt )`
* This stepper works with all steppers fulfilling the Stepper concept, the ControlledStepper concept or the DenseOutputStepper concept.
* The value of `state` is the current state of the ODE during the iteration.

[endsect]

[section times_time_iterator]

* Definition: `times_time_iterator< Stepper , System , State , TimeIterator>`
* `value_type` is `std::pair< State , Stepper::time_type >`
* `reference_type` is `std::pair< State const& , Stepper::time_type > const&`
* Factory functions
  * `make_times_time_iterator_begin( stepper , system , state , t_start , t_end , dt )`
  * `make_times_time_step_iterator_end( stepper , system , state )`
  * `make_times_time_range( stepper , system , state , t_start , t_end , dt )`
* This stepper works with all steppers fulfilling the Stepper concept, the ControlledStepper concept or the DenseOutputStepper concept.
* This stepper updates the value of `state`. The value of `state` is the current state of the ODE during the iteration.

[endsect]


[endsect]
Commit	Line	Data
7c673cae FG	1	[/============================================================================
	2	Boost.odeint
	3
	4	Copyright 2012-2013 Karsten Ahnert
	5	Copyright 2012-2013 Mario Mulansky
	6	Copyright 2012 Sylwester Arabas
	7
	8	Use, modification and distribution is subject to the Boost Software License,
	9	Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
	10	http://www.boost.org/LICENSE_1_0.txt)
	11	=============================================================================/]
	12
	13
	14	[section Iterators and Ranges]
	15
	16	[section Examples]
	17
	18	odeint supports iterators that iterate along an approximate solution of an ordinary differential equation. Iterators offer you an alternative to the integrate functions. Furthermore, many of the standard algorithms in the C++ standard library and Boost.Range can be used with the odeint's iterators.
	19
	20	[import ../examples/const_step_iterator.cpp]
	21
	22	Several iterator types are provided, in consistence with the
	23	__integrate_functions. Hence there are `const_step_iterator`,
	24	`adaptive_step_iterator`, `n_step_iterator` and `times_iterator` -- each of
	25	them in two versions: either with only the `state` or with a
	26	`std::pair<state,time>` as value type. They are all single pass iterators. In
	27	the following, we show a few examples of how to use those iterators together
	28	with std algorithms.
	29
	30	[const_step_iterator_accumulate]
	31
	32	In this example all x-values of the solution are accumulated. Note, how
	33	dereferencing the iterator gives the current state `x` of the ODE (the second
	34	argument of the accumulate lambda). The iterator
	35	itself does not occur directly in this example but it is generated by the
	36	factory functions `make_const_step_iterator_begin` and
	37	`make_const_step_iterator_end`. odeint also supports Boost.Range, that allows
	38	to write the above example in a more compact form with the factory function
	39	`make_const_step_range`, but now using `boost::accumulate` from __bost_range:
	40
	41	[const_step_iterator_accumulate_range]
	42
	43	The second iterator type is also a iterator with const step size. But the value type of this iterator consists here of a pair of the time and the state of the solution of the ODE. An example is
	44
	45	[const_step_time_iterator_accumulate_range]
	46
	47	The factory functions are now `make_const_step_time_iterator_begin`,
	48	`make_const_step_time_iterator_end` and `make_const_step_time_range`.
	49	Note, how the lambda now expects a `std::pair` as this is the value type of
	50	the `const_step_time_iterator`'s.
	51
	52
	53	[import ../examples/adaptive_iterator.cpp]
	54
	55	Next, we discuss the adaptive iterators which are completely
	56	analogous to the const step iterators, but are based on adaptive stepper
	57	routines and thus adjust the step size during the iteration. Examples are
	58
	59	[adaptive_iterator_accumulate_range]
	60
	61	[adaptive_time_iterator_accumulate_range]
	62
	63	[note 'adaptive_iterator` and `adaptive_time_iterator' can only be used with
	64	__controlled_stepper or __dense_output_stepper.]
65
66	In general one can say that iterating over a range of a `const_step_iterator`
67	behaves like an `integrate_const` function call, and similarly for
68	`adaptive_iterator` and `integrate_adaptive`, `n_step_iterator` and
69	`integrate_n_steps`, and finally `times_iterator` and `integrate_times`.
70
71	Below we list the most important properties of the exisiting iterators:
72
73	[endsect]
74
75	[section const_step_iterator]
76
77	* Definition: `const_step_iterator< Stepper , System , State >`
78	* `value_type` is `State`
79	* `reference_type` is `State const&`
80	* Factory functions
81	* `make_const_step_iterator_begin( stepper , system , state , t_start , t_end , dt )`
82	* `make_const_step_iterator_end( stepper , system , state )`
83	* `make_const_step_range( stepper , system , state , t_start , t_end , dt )`
84	* This stepper works with all steppers fulfilling the Stepper concept or the DenseOutputStepper concept.
85	* The value of `state` is the current state of the ODE during the iteration.
86
87	[endsect]
88
89	[section const_step_time_iterator]
90
91	* Definition: `const_step_time_iterator< Stepper , System , State >`
92	* `value_type` is `std::pair< State , Stepper::time_type >`
93	* `reference_type` is `std::pair< State const& , Stepper::time_type > const&`
94	* Factory functions
95	* `make_const_step_time_iterator_begin( stepper , system , state , t_start , t_end , dt )`
96	* `make_const_step_time_iterator_end( stepper , system , state )`
97	* `make_const_step_time_range( stepper , system , state , t_start , t_end , dt )`
98	* This stepper works with all steppers fulfilling the Stepper concept or the DenseOutputStepper concept.
99	* This stepper updates the value of `state`. The value of `state` is the current state of the ODE during the iteration.
100
101
102	[endsect]
103
104
105	[section adaptive_step_iterator]
106
107	* Definition: `adaptive_iterator< Stepper , System , State >`
108	* `value_type` is `State`
109	* `reference_type` is `State const&`
110	* Factory functions
111	* `make_adaptive_iterator_begin( stepper , system , state , t_start , t_end , dt )`
112	* `make_adaptive_iterator_end( stepper , system , state )`
113	* `make_adaptive_range( stepper , system , state , t_start , t_end , dt )`
114	* This stepper works with all steppers fulfilling the ControlledStepper concept or the DenseOutputStepper concept.
115	* For steppers fulfilling the ControlledStepper concept `state` is modified according to the current state of the ODE. For DenseOutputStepper the state is not modified due to performance optimizations, but the steppers itself.
116
117
118	[endsect]
119
120	[section adaptive_step_time_iterator]
121
122	* Definition: `adaptive_iterator< Stepper , System , State >`
123	* `value_type` is `std::pair< State , Stepper::time_type >`
124	* `reference_type` is `std::pair< State const& , Stepper::time_type > const&`
125	* Factory functions
126	* `make_adaptive_time_iterator_begin( stepper , system , state , t_start , t_end , dt )`
127	* `make_adaptive_time_iterator_end( stepper , system , state )`
128	* `make_adaptive_time_range( stepper , system , state , t_start , t_end , dt )`
129	* This stepper works with all steppers fulfilling the ControlledStepper concept or the DenseOutputStepper concept.
130	* For steppers fulfilling the ControlledStepper concept `state` is modified according to the current state of the ODE. For DenseOutputStepper the state is not modified due to performance optimizations, but the stepper itself.
131
132
133	[endsect]
134
135
136	[section n_step_iterator]
137
138	* Definition: `n_step_iterator< Stepper , System , State >`
139	* `value_type` is `State`
140	* `reference_type` is `State const&`
141	* Factory functions
142	* `make_n_step_iterator_begin( stepper , system , state , t_start , dt , num_of_steps )`
143	* `make_n_step_iterator_end( stepper , system , state )`
144	* `make_n_step_range( stepper , system , state , t_start , dt , num_of_steps )`
145	* This stepper works with all steppers fulfilling the Stepper concept or the DenseOutputStepper concept.
146	* The value of `state` is the current state of the ODE during the iteration.
147
148	[endsect]
149
150	[section n_step_time_iterator]
151
152	* Definition: `n_step_time_iterator< Stepper , System , State >`
153	* `value_type` is `std::pair< State , Stepper::time_type >`
154	* `reference_type` is `std::pair< State const& , Stepper::time_type > const&`
155	* Factory functions
156	* `make_n_step_time_iterator_begin( stepper , system , state , t_start , dt , num_of_steps )`
157	* `make_n_step_time_iterator_end( stepper , system , state )`
158	* `make_n_step_time_range( stepper , system , state , t_start , dt , num_of_steps )`
159	* This stepper works with all steppers fulfilling the Stepper concept or the DenseOutputStepper concept.
160	* This stepper updates the value of `state`. The value of `state` is the current state of the ODE during the iteration.
161
162
163	[endsect]
164
165
166	[section times_iterator]
167
168	* Definition: `times_iterator< Stepper , System , State , TimeIterator >`
169	* `value_type` is `State`
170	* `reference_type` is `State const&`
171	* Factory functions
172	* `make_times_iterator_begin( stepper , system , state , t_start , t_end , dt )`
173	* `make_times_iterator_end( stepper , system , state )`
174	* `make_times_range( stepper , system , state , t_start , t_end , dt )`
175	* This stepper works with all steppers fulfilling the Stepper concept, the ControlledStepper concept or the DenseOutputStepper concept.
176	* The value of `state` is the current state of the ODE during the iteration.
177
178	[endsect]
179
180	[section times_time_iterator]
181
182	* Definition: `times_time_iterator< Stepper , System , State , TimeIterator>`
183	* `value_type` is `std::pair< State , Stepper::time_type >`
184	* `reference_type` is `std::pair< State const& , Stepper::time_type > const&`
185	* Factory functions
186	* `make_times_time_iterator_begin( stepper , system , state , t_start , t_end , dt )`
187	* `make_times_time_step_iterator_end( stepper , system , state )`
188	* `make_times_time_range( stepper , system , state , t_start , t_end , dt )`
189	* This stepper works with all steppers fulfilling the Stepper concept, the ControlledStepper concept or the DenseOutputStepper concept.
190	* This stepper updates the value of `state`. The value of `state` is the current state of the ODE during the iteration.
191
192	[endsect]
193
194
195	[endsect]