The LSODE function uses adaptive numerical methods to advance a solution to a system of ordinary differential equations one time-step H, given values for the variables Y and X.

Examples

To integrate the example system of differential equations:

FUNCTION spring_friction, t, xv
  v = xv[1]
  x = xv[0]
  RETURN, [v, -v - x]
END
                
            
PRO LSODETEST
  ; Define the step size
  H = 0.1
  ; Define x position of the spring
  X = 0.0
                  
            
  ; y[0] is your starting point
  ; y[1] is the amplitude of the first bump
  yy=10
  y = [1, 2*yy/10.]
  result = fltarr(2,100)
  FOR i=0,99 DO BEGIN
  x = i*h
  result[*,i] = LSODE(Y, X, H, 'spring_friction')
  y = result[*,i]
  ENDFOR
  p=plot(findgen(100)*h, result[0,*])
END
                
            
LSODETEST
END

Syntax

Result = LSODE( Y, X, H, Derivs[, Status] [, ATOL=value] [, /QUIET] [, RTOL=value] )

Return Value

Returns the solution in a vector with the same number of elements as Y.

Arguments

Y

A vector of values for Y at X

X

A scalar value for the initial condition.

H

A scalar value giving interval length or step size.

Derivs

A scalar string specifying the name of a user-supplied IDL function that calculates the values of the derivatives Dydx at X. This function must accept two arguments: A scalar floating value X, and an n-element vector Y. It must return an n-element vector result.

For example, suppose the values of the derivatives are defined by the following relations:

dy0 / dx = –0.5y0,        dy1 / dx = 4.0 – 0.3y1 – 0.1y0

We can write a function called differential to express these relationships in the IDL language:

FUNCTION differential, X, Y
   RETURN, [-0.5 * Y[0], 4.0 - 0.3 * Y[1] - 0.1 * Y[0]]
END

Status

The status of the result. This argument contains a positive value if the function was successfully completed. Negative values indicate different errors.

Output Value

Description

 1

Nothing occurred.

 2

The integration was performed successfully, and no roots were found.

 3

The integration was successful, and one or more roots were found.

-1

An excessive amount of work was done on this call, but the integration was otherwise successful.

-2

The precision of the machine being used is insufficient for the requested amount of accuracy. Integration was successful.

-3

Illegal input was detected, before processing any integration steps. If the solver detects an infinite loop of calls to the solver with illegal input, it will cause the run to stop.

-4

There were repeated error test failures on one attempted step, before completing the requested task, but the integration was successful. The problem may have a singularity, or the input may be inappropriate.

-5

There were repeated convergence test failures on one attempted step, before completing the requested task, but the integration was successful. This may be caused by an inaccurate jacobian matrix, if one is being used.

-6

Error weight vector for element i became zero during the integration. Pure relative error control was requested on a variable which has now vanished. Integration was successful.

Keywords

ATOL

A scalar or array value that specifies the absolute tolerance. The default value is 1.0e-7. Use ATOL = 0.0 (or ATOL[i] = 0.0) for pure relative error control, and use RTOL = 0.0 for pure absolute error control. For an explanation of how to use ATOL and RTOL together, see RTOL below.

QUIET

Set this keyword to suppress warning messages. By default, warning messages will be output to the screen.

RTOL

A scalar value that specifies the relative tolerance. The default value is 1.0e-7. Use RTOL = 0.0 for pure absolute error control, and use ATOL = 0.0 (or ATOL[i] = 0.0) for pure relative error control.

The estimated local error in the Y[i] argument will be controlled to be less than

ewt[i] = RTOL*abs(Y[i]) + ATOL    ; If ATOL is a scalar.
ewt[i] = RTOL*abs(Y[i]) + ATOL[i] ; If ATOL is an array.

Thus, the local error test passes if, in each component, either the absolute error is less than ATOL (or ATOL[i]), or if the relative error is less than RTOL.

Actual, or global, errors might exceed these local tolerances, so choose values for ATOL and RTOL conservatively.

See Also

DERIV, DERIVSIG, RK4

References

  1. Alan C. Hindmarsh, ODEPACK, A Systematized Collection of ODE Solvers, in Scientific Computing, R. S. Stepleman et al. (eds.), North-Holland, Amsterdam, 1983, pp. 55-64.
  2. Linda R. Petzold, Automatic Selection of Methods for Solving Stiff and Nonstiff Systems of Ordinary Differential Equations, SIAM J. SCI. STAT. COMPUT. 4 (1983), pp. 136-148.
  3. Kathie L. Hiebert and Lawrence F. Shampine, Implicitly Defined Output Points for Solutions of ODE’s, Sandia Report SAND80-0180, February, 1980.

Version History

5.1

Introduced

6.1

Added QUIET keyword