25.4 Evolution

The highest level of the system is the evolution function which combines the results of a stepping function and control function to reliably advance the solution forward over an interval (t_0, t_1). If the control function signals that the step-size should be decreased the evolution function backs out of the current step and tries the proposed smaller step-size. This process is continued until an acceptable step-size is found.

Function: gsl_odeiv_evolve * gsl_odeiv_evolve_alloc (size_t dim)

This function returns a pointer to a newly allocated instance of an evolution function for a system of dim dimensions.

Function: int gsl_odeiv_evolve_apply (gsl_odeiv_evolve * e, gsl_odeiv_control * con, gsl_odeiv_step * step, const gsl_odeiv_system * dydt, double * t, double t1, double * h, double y[])

This function advances the system (e, dydt) from time t and position y using the stepping function step. The new time and position are stored in t and y on output. The initial step-size is taken as h, but this will be modified using the control function c to achieve the appropriate error bound if necessary. The routine may make several calls to step in order to determine the optimum step-size. An estimate of the local error for the step can be obtained from the components of the array e->yerr[]. If the step-size has been changed the value of h will be modified on output. The maximum time t1 is guaranteed not to be exceeded by the time-step. On the final time-step the value of t will be set to t1 exactly.

If the user-supplied functions defined in the system dydt return a status other than GSL_SUCCESS the step will be aborted. In this case, t and y will be restored to their pre-step values and the error code from the user-supplied function will be returned. To distinguish between error codes from the user-supplied functions and those from gsl_odeiv_evolve_apply itself, any user-defined return values should be distinct from the standard GSL error codes.

Function: int gsl_odeiv_evolve_reset (gsl_odeiv_evolve * e)

This function resets the evolution function e. It should be used whenever the next use of e will not be a continuation of a previous step.

Function: void gsl_odeiv_evolve_free (gsl_odeiv_evolve * e)

This function frees all the memory associated with the evolution function e.

Where a system has discontinuous changes in the derivatives at known times it is advisable to evolve the system between each discontinuity in sequence. For example, if a step-change in an external driving force occurs at times t_a, t_b, t_c, \dots then evolving over the ranges (t_0,t_a), (t_a,t_b), …, (t_c,t_1) is more efficient than using the single range (t_0,t_1).

Evolving the system directly through a discontinuity with a strict tolerance may result in extremely small steps being taken at the edge of the discontinuity (e.g. down to the limit of machine precision). In this case it may be necessary to impose a minimum step size hmin suitable for the problem:

while (t < t1)
{
   gsl_odeiv_evolve_apply (e, c, s, &sys, &t, t1, &h, y);
   if (h < hmin) { h = hmin; } ;
}

The value of h returned by gsl_odeiv_evolve_apply is always a suggested value and can be modified whenever needed.