LSODE

Syntax | Return Value | Arguments | Keywords | Examples | See Also | Version History

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.

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:

dy₀ / dx = –0.5y_0,        dy₁ / dx = 4.0 – 0.3y₁ – 0.1y₀

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

An index used for input and output to specify the state of the calculation. This argument contains a positive value if the function was successfully completed. Negative values indicate different errors.

Note
A preliminary call with tout = t is not counted as a first call here, as no initialization or checking of input is done. (Such a call is sometimes useful for the purpose of outputting the initial condition s.) Thus, the first call for which tout ≠ t requires STATUS = 1 on input.

Note
Since the normal output value of STATUS is 2, it does not need to be reset for normal continuation. Also, since a negative input value of STATUS will be regarded as illegal, a negative output value requires the user to change it, and possibly other inputs, before calling the solver again.

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.

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

Examples

To integrate the example system of differential equations for one time step, H:

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


PRO LSODETEST

   ; Define the step size:
   H = 0.5

   ; Define an initial X value:
   X = 0.0

   ; Define initial Y values:
   Y = [4.0, 6.0]

   ; Integrate over the interval (0, 0.5):
   result = LSODE(Y, X, H, 'differential')

   ; Print the result:
   PRINT, result

END

LSODETEST

IDL prints:

3.11523     6.85767 

This is the exact solution vector to 5-decimal precision.

See Also

DERIV, DERIVSIG, RK4

References

Version History