Harmonic oscillator

First of all, you have to specify the data type that represents a state x of your system. Mathematically, this usually is an n-dimensional vector with real numbers or complex numbers as scalar objects. For odeint the most natural way is to use vector< double > or vector< complex< double > > to represent the system state. However, odeint can deal with other container types as well, e.g. boost::array< double , N >, as long as it is fulfills some requirements defined below.

To integrate a differential equation numerically, one also has to define the rhs of the equation x' = f(x). In odeint you supply this function in terms of an object that implements the ()-operator with a certain parameter structure. Hence, the straight forward way would be to just define a function, e.g:

/* The type of container used to hold the state vector */
typedef std::vector< double > state_type;

const double gam = 0.15;

/* The rhs of x' = f(x) */
void harmonic_oscillator( const state_type &x , state_type &dxdt , const double /* t */ )
{
    dxdt[0] = x[1];
    dxdt[1] = -x[0] - gam*x[1];
}

The parameters of the function must follow the example above where x is the current state, here a two-component vector containing position q and momentum p of the oscillator, dxdt is the derivative x' and should be filled by the function with f(x), and t is the current time. Note that in this example t is not required to calculate f, however odeint expects the function signature to have exactly three parameters (there are exception, discussed later).

A more sophisticated approach is to implement the system as a class where the rhs function is defined as the ()-operator of the class with the same parameter structure as above:

/* The rhs of x' = f(x) defined as a class */
class harm_osc {

    double m_gam;

public:
    harm_osc( double gam ) : m_gam(gam) { }

    void operator() ( const state_type &x , state_type &dxdt , const double /* t */ )
    {
        dxdt[0] = x[1];
        dxdt[1] = -x[0] - m_gam*x[1];
    }
};

odeint can deal with instances of such classes instead of pure functions which allows for cleaner code.

Stepper Types

Numerical integration works iteratively, that means you start at a state x(t) and perform a time-step of length dt to obtain the approximate state x(t+dt). There exist many different methods to perform such a time-step each of which has a certain order q. If the order of a method is q than it is accurate up to term ~dt^q that means the error in x made by such a step is ~dt^q+1. odeint provides several steppers of different orders from which you can choose:

Table 1.2. Stepper Algorithms

Algorithm	Class	Concept	System Concept	Order	Error Estimation	Dense Output	Internal state	Remarks
Explicit Euler	`euler`	Dense Output Stepper	System	1	No	Yes	No	Very simple, only for demonstrating purpose
Modified Midpoint	`modified_midpoint`	Stepper	System	configurable (2)	No	No	No	Used in Bulirsch-Stoer implementation
Runge-Kutta 4	`runge_kutta4`	Stepper	System	4	No	No	No	The classical Runge Kutta scheme, good general scheme without error control
Cash-Karp	`runge_kutta_cash_karp54`	Error Stepper	System	5	Yes (4)	No	No	Good general scheme with error estimation, to be used in controlled_error_stepper
Dormand-Prince 5	`runge_kutta_dopri5`	Error Stepper	System	5	Yes (4)	Yes	Yes	Standard method with error control and dense output, to be used in controlled_error_stepper and in dense_output_controlled_explicit_fsal.
Fehlberg 78	`runge_kutta_fehlberg78`	Error Stepper	System	8	Yes (7)	No	No	Good high order method with error estimation, to be used in controlled_error_stepper.
Adams Bashforth	`adams_bashforth`	Stepper	System	configurable	No	No	Yes	Multistep method
Adams Moulton	`adams_moulton`	Stepper	System	configurable	No	No	Yes	Multistep method
Adams Bashforth Moulton	`adams_bashforth_moulton`	Stepper	System	configurable	No	No	Yes	Combined multistep method
Controlled Runge Kutta	`controlled_runge_kutta`	Controlled Stepper	System	depends	Yes	No	depends	Error control for Error Stepper. Requires an Error Stepper from above. Order depends on the given ErrorStepper
Dense Output Runge Kutta	`dense_output_runge_kutta`	Dense Output Stepper	System	depends	No	Yes	Yes	Dense output for Stepper and Error Stepper from above if they provide dense output functionality (like `euler` and `runge_kutta_dopri5`). Order depends on the given stepper.
Bulirsch-Stoer	`bulirsch_stoer`	Controlled Stepper	System	variable	Yes	No	No	Stepper with step size and order control. Very good if high precision is required.
Bulirsch-Stoer Dense Output	`bulirsch_stoer_dense_out`	Dense Output Stepper	System	variable	Yes	Yes	No	Stepper with step size and order control as well as dense output. Very good if high precision and dense output is required.
Implicit Euler	`implicit_euler`	Stepper	Implicit System	1	No	No	No	Basic implicit routine. Requires the Jacobian. Works only with Boost.UBlas vectors as state types.
Rosenbrock 4	`rosenbrock4`	Error Stepper	Implicit System	4	Yes	Yes	No	Good for stiff systems. Works only with Boost.UBlas vectors as state types.
Controlled Rosenbrock 4	`rosenbrock4_controller`	Controlled Stepper	Implicit System	4	Yes	Yes	No	Rosenbrock 4 with error control. Works only with Boost.UBlas vectors as state types.
Dense Output Rosenbrock 4	`rosenbrock4_dense_output`	Dense Output Stepper	Implicit System	4	Yes	Yes	No	Controlled Rosenbrock 4 with dense output. Works only with Boost.UBlas vectors as state types.
Symplectic Euler	`symplectic_euler`	Stepper	Symplectic System Simple Symplectic System	1	No	No	No	Basic symplectic solver for separable Hamiltonian system
Symplectic RKN McLachlan	`symplectic_rkn_sb3a_mclachlan`	Stepper	Symplectic System Simple Symplectic System	6	No	No	No	Symplectic solver for separable Hamiltonian system with order 6

Some of steppers in the table above are special: Some need the Jacobian of the ODE, others are constructed for special ODE-systems like Hamiltonian systems. We will show typical examples and use-cases in this tutorial and which kind of steppers should be applied.

Integration with Constant Step Size

The basic stepper just performs one time-step and doesn't give you any information about the error that was made (except that you know it is of order q+1). Such steppers are used with constant step size that should be chosen small enough to have reasonable small errors. However, you should apply some sort of validity check of your results (like observing conserved quantities) because you have no other control of the error. The following example defines a basic stepper based on the classical Runge-Kutta scheme of 4th order. The declaration of the stepper requires the state type as template parameter. The integration can now be done by using the integrate_const( Stepper, System, state, start_time, end_time, step_size ) function from odeint:

runge_kutta4< state_type > stepper;
integrate_const( stepper , harmonic_oscillator , x , 0.0 , 10.0 , 0.01 );

This call integrates the system defined by harmonic_oscillator using the RK4 method from t=0 to 10 with a step-size dt=0.01 and the initial condition given in x. The result, x(t=10) is stored in x (in-place). Each stepper defines a do_step method which can used directly. So, you write down the above example as

const double dt = 0.01;
for( double t=0.0 ; t<10.0 ; t+= dt )
    stepper.do_step( harmonic_oscillator , x , t , dt );

Integration with Adaptive Step Size

To improve the numerical results and additionally minimize the computational effort, the application of a step size control is advisable. Step size control is realized via stepper algorithms that additionally provide an error estimation of the applied step. odeint provides a number of such ErrorSteppers and we will show their usage on the example of explicit_error_rk54_ck -- a 5th order Runge-Kutta method with 4th order error estimation and coefficients introduced by Cash and Karp.

typedef runge_kutta_cash_karp54< state_type > error_stepper_type;

Given the error stepper, one still needs an instance that checks the error and adjusts the step size accordingly. In odeint, this is done by ControlledSteppers. For the runge_kutta_cash_karp54 stepper a controlled_runge_kutta stepper exists which can be used via

typedef controlled_runge_kutta< error_stepper_type > controlled_stepper_type;
controlled_stepper_type controlled_stepper;
integrate_adaptive( controlled_stepper , harmonic_oscillator , x , 0.0 , 10.0 , 0.01 );

As above, this integrates the system defined by harmonic_oscillator, but now using an adaptive step size method based on the Runge-Kutta Cash-Karp 54 scheme from t=0 to 10 with an initial step size of dt=0.01 (will be adjusted) and the initial condition given in x. The result, x(t=10), will also be stored in x (in-place).

In the above example an error stepper is nested in a controlled stepper. This is a nice technique; however one drawback is that one always needs to define both steppers. Of course, one could also write the instantiation of the controlled stepper into the call of the integrate function but a complete knowledge of the underlying stepper types is still necessary. Another point is, that the error tolerances for the step size control are not easily included into the controlled stepper. Both issues can be solved by using make_controlled:

integrate_adaptive( make_controlled< error_stepper_type >( 1.0e-10 , 1.0e-6 ) ,
                    harmonic_oscillator , x , 0.0 , 10.0 , 0.01 );

make_controlled can be used with many of the steppers of odeint. The first parameter is the absolute error tolerance eps_abs and the second is the relative error tolerance eps_rel which is used during the integration. The template parameter determines from which error stepper a controlled stepper should be instantiated. An alternative syntax of make_controlled is

integrate_adaptive( make_controlled( 1.0e-10 , 1.0e-6 , error_stepper_type() ) ,
                    harmonic_oscillator , x , 0.0 , 10.0 , 0.01 );

For the Runge Kutta controller the error made during one step is compared with eps_abs + eps_rel * ( a_x * |x| + a_dxdt * dt * |dxdt| ). If the error is smaller than this value the current step is accept otherwise it is rejected and the step size is decreased. Note, that the step size is also increased if the error gets too small compared to the rhs of the above relation. The full instantiation of the controlled_runge_kutta with all parameters is therefore

double abs_err = 1.0e-10 , rel_err = 1.0e-6 , a_x = 1.0 , a_dxdt = 1.0;
controlled_stepper_type controlled_stepper(
    default_error_checker< double >( abs_err , rel_err , a_x , a_dxdt ) );
integrate_adaptive( controlled_stepper , harmonic_oscillator , x , 0.0 , 10.0 , 0.01 );

When using make_controlled the parameter a_x and a_dxdt are used with their standard values of 1.

In the tables below, one can find all steppers which are working with make_controlled and make_dense_output which is the analog for the dense output steppers.

Table 1.3. Generation functions make_controlled( abs_error , rel_error , stepper )

Stepper	Result of make_controlled	Remarks
`runge_kutta_cash_karp54`	`controlled_runge_kutta< runge_kutta_cash_karp54 , default_error_checker<...> >`	a_x=1, a_dxdt=1
`runge_kutta_fehlberg78`	`controlled_runge_kutta< runge_kutta_fehlberg78 , default_error_checker<...> >`	a_x=1, a_dxdt=1
`runge_kutta_dopri5`	`controlled_runge_kutta< runge_kutta_dopri5 , default_error_checker<...> >`	a _x=1, a_dxdt=1
`rosenbrock4`	`rosenbrock4_controlled< rosenbrock4 >`	-

Table 1.4. Generation functions make_dense_output( abs_error , rel_error , stepper )

Stepper	Result of make_dense_output	Remarks
`runge_kutta_dopri5`	`dense_output_runge_kutta< controlled_runge_kutta< runge_kutta_dopri5 , default_error_checker<...> > >`	a _x=1, a_dxdt=1
`rosenbrock4`	`rosenbrock4_dense_output< rosenbrock4_controller< rosenbrock4 > >`	-

When using make_controlled or make_dense_output one should be aware which exact type is used and how the step size control works.

The full cpp file for this example can be found here: harmonic_oscillator.cpp