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

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

  Copyright 2011-2012 Karsten Ahnert
  Copyright 2011 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 Stepper]

This concepts specifies the interface a simple stepper has to fulfill to be used within the __integrate_functions.

[heading Description]

The basic stepper concept.
A basic stepper following this Stepper concept is able to perform a single step of the solution /x(t)/ of an ODE to obtain /x(t+dt)/ using a given step size /dt/.
Basic steppers can be Runge-Kutta steppers, symplectic steppers as well as implicit steppers.
Depending on the actual stepper, the ODE is defined as __system, __symplectic_system, __simple_symplectic_system or __implicit_system.
Note that all error steppers are also basic steppers.

[heading Refinement of]

* DefaultConstructable
* CopyConstructable


[heading Associated types]

*  '''<para>'''[*state_type]'''</para>'''
'''<para>'''`Stepper::state_type`'''</para>'''
'''<para>'''The type characterizing the state of the ODE, hence ['x].'''</para>'''

*  '''<para>'''[*deriv_type]'''</para>'''
'''<para>'''`Stepper::deriv_type`'''</para>'''
'''<para>'''The type characterizing the derivative of the ODE, hence ['d x/dt].'''</para>'''

*  '''<para>'''[*time_type]'''</para>'''
'''<para>'''`Stepper::time_type`'''</para>'''
'''<para>'''The type characterizing the dependent variable of the ODE, hence the time ['t].'''</para>'''

*  '''<para>'''[*value_type]'''</para>'''
'''<para>'''`Stepper::value_type`'''</para>'''
'''<para>'''The numerical data type which is used within the stepper, something like `float`, `double`, `complex&lt; double &gt;`.'''</para>'''

*  '''<para>'''[*order_type]'''</para>'''
'''<para>'''`Stepper::order_type`'''</para>'''
'''<para>'''The type characterizing the order of the ODE, typically `unsigned short`.'''</para>'''

*  '''<para>'''[*stepper_category]'''</para>'''
'''<para>'''`Stepper::stepper_category`'''</para>'''
'''<para>'''A tag type characterizing the category of the stepper. This type must be convertible to `stepper_tag`.'''</para>'''


[heading Notation]

[variablelist 
  [[`Stepper`] [A type that is a model of Stepper]]
  [[`State`] [A type representing the state /x/ of the ODE]]
  [[`Time`] [A type representing the time /t/ of the ODE]]
  [[`stepper`] [An object of type `Stepper`]]
  [[`x`] [Object of type `State`]]
  [[`t`, `dt`] [Objects of type `Time`]]
  [[`sys`] [An object defining the ODE. Depending on the Stepper this might be a model of __system, __symplectic_system, __simple_symplectic_system or __implicit_system ]]
]

[heading Valid Expressions]

[table
  [[Name] [Expression] [Type] [Semantics]]
  [[Get the order] [`stepper.order()`] [`order_type`] [Returns the order of the stepper.]]
  [[Do step] [`stepper.do_step( sys , x , t , dt )`] [`void`] [Performs one step of step size `dt`.  The newly obtained state is written in place in `x`.] ]

  [/ [Do step with reference] [`stepper.do_step( boost::ref(sys) , x , t , dt )`] [`void`] [Performs one step of step size `dt`.  The newly obtained state is written in place in `x`.] ]

  [/ [Do step out-of-place] [`stepper.do_step( sys , in , t , out , dt )`] [`void`] [Performs one step. The newly obtained state is written to `out`] ]
]

[heading Models]

* `runge_kutta4`
* `euler`
* `runge_kutta_cash_karp54`
* `runge_kutta_dopri5`
* `runge_kutta_fehlberg78`
* `modified_midpoint`
* `rosenbrock4`

[endsect]
Commit	Line	Data
7c673cae FG	1	[/============================================================================
	2	Boost.odeint
	3
	4	Copyright 2011-2012 Karsten Ahnert
	5	Copyright 2011 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 Stepper]
	15
	16	This concepts specifies the interface a simple stepper has to fulfill to be used within the __integrate_functions.
	17
	18	[heading Description]
	19
	20	The basic stepper concept.
	21	A basic stepper following this Stepper concept is able to perform a single step of the solution /x(t)/ of an ODE to obtain /x(t+dt)/ using a given step size /dt/.
	22	Basic steppers can be Runge-Kutta steppers, symplectic steppers as well as implicit steppers.
	23	Depending on the actual stepper, the ODE is defined as __system, __symplectic_system, __simple_symplectic_system or __implicit_system.
	24	Note that all error steppers are also basic steppers.
	25
	26	[heading Refinement of]
	27
	28	* DefaultConstructable
	29	* CopyConstructable
	30
	31
	32	[heading Associated types]
	33
	34	* '''<para>'''[*state_type]'''</para>'''
	35	'''<para>'''`Stepper::state_type`'''</para>'''
	36	'''<para>'''The type characterizing the state of the ODE, hence ['x].'''</para>'''
	37
	38	* '''<para>'''[*deriv_type]'''</para>'''
	39	'''<para>'''`Stepper::deriv_type`'''</para>'''
	40	'''<para>'''The type characterizing the derivative of the ODE, hence ['d x/dt].'''</para>'''
	41
	42	* '''<para>'''[*time_type]'''</para>'''
	43	'''<para>'''`Stepper::time_type`'''</para>'''
	44	'''<para>'''The type characterizing the dependent variable of the ODE, hence the time ['t].'''</para>'''
	45
	46	* '''<para>'''[*value_type]'''</para>'''
	47	'''<para>'''`Stepper::value_type`'''</para>'''
	48	'''<para>'''The numerical data type which is used within the stepper, something like `float`, `double`, `complex< double >`.'''</para>'''
	49
	50	* '''<para>'''[*order_type]'''</para>'''
	51	'''<para>'''`Stepper::order_type`'''</para>'''
	52	'''<para>'''The type characterizing the order of the ODE, typically `unsigned short`.'''</para>'''
	53
	54	* '''<para>'''[*stepper_category]'''</para>'''
	55	'''<para>'''`Stepper::stepper_category`'''</para>'''
	56	'''<para>'''A tag type characterizing the category of the stepper. This type must be convertible to `stepper_tag`.'''</para>'''
	57
	58
	59	[heading Notation]
	60
	61	[variablelist
	62	[[`Stepper`] [A type that is a model of Stepper]]
	63	[[`State`] [A type representing the state /x/ of the ODE]]
	64	[[`Time`] [A type representing the time /t/ of the ODE]]
65	[[`stepper`] [An object of type `Stepper`]]
66	[[`x`] [Object of type `State`]]
67	[[`t`, `dt`] [Objects of type `Time`]]
68	[[`sys`] [An object defining the ODE. Depending on the Stepper this might be a model of __system, __symplectic_system, __simple_symplectic_system or __implicit_system ]]
69	]
70
71	[heading Valid Expressions]
72
73	[table
74	[[Name] [Expression] [Type] [Semantics]]
75	[[Get the order] [`stepper.order()`] [`order_type`] [Returns the order of the stepper.]]
76	[[Do step] [`stepper.do_step( sys , x , t , dt )`] [`void`] [Performs one step of step size `dt`. The newly obtained state is written in place in `x`.] ]
77
78	[/ [Do step with reference] [`stepper.do_step( boost::ref(sys) , x , t , dt )`] [`void`] [Performs one step of step size `dt`. The newly obtained state is written in place in `x`.] ]
79
80	[/ [Do step out-of-place] [`stepper.do_step( sys , in , t , out , dt )`] [`void`] [Performs one step. The newly obtained state is written to `out`] ]
81	]
82
83	[heading Models]
84
85	* `runge_kutta4`
86	* `euler`
87	* `runge_kutta_cash_karp54`
88	* `runge_kutta_dopri5`
89	* `runge_kutta_fehlberg78`
90	* `modified_midpoint`
91	* `rosenbrock4`
92
93	[endsect]