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 18odeint 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 22Several 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 25them 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 27the following, we show a few examples of how to use those iterators together 28with std algorithms. 29 30[const_step_iterator_accumulate] 31 32In this example all x-values of the solution are accumulated. Note, how 33dereferencing the iterator gives the current state `x` of the ODE (the second 34argument of the accumulate lambda). The iterator 35itself does not occur directly in this example but it is generated by the 36factory functions `make_const_step_iterator_begin` and 37`make_const_step_iterator_end`. odeint also supports Boost.Range, that allows 38to 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 43The 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 47The factory functions are now `make_const_step_time_iterator_begin`, 48`make_const_step_time_iterator_end` and `make_const_step_time_range`. 49Note, how the lambda now expects a `std::pair` as this is the value type of 50the `const_step_time_iterator`'s. 51 52 53[import ../examples/adaptive_iterator.cpp] 54 55Next, we discuss the adaptive iterators which are completely 56analogous to the const step iterators, but are based on adaptive stepper 57routines 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 66In general one can say that iterating over a range of a `const_step_iterator` 67behaves 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 71Below 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] 196