naginterfaces.library.ode.ivp_​rkm_​zero_​simple

naginterfaces.library.ode.ivp_rkm_zero_simple(x, xend, y, tol, irelab, hmax, fcn, g, data=None)[source]

ivp_rkm_zero_simple integrates a system of first-order ordinary differential equations over an interval with suitable initial conditions, using a Runge–Kutta–Merson method, until a user-specified function of the solution is zero.

For full information please refer to the NAG Library document for d02bh

https://www.nag.com/numeric/nl/nagdoc_28.6/flhtml/d02/d02bhf.html

Parameters
xfloat

Must be set to the initial value of the independent variable .

xendfloat

The final value of the independent variable .

If on entry, integration proceeds in a negative direction.

yfloat, array-like, shape

The initial values of the solution .

tolfloat

Must be set to a positive tolerance for controlling the error in the integration and in the determination of the position where .

ivp_rkm_zero_simple has been designed so that, for most problems, a reduction in leads to an approximately proportional reduction in the error in the solution obtained in the integration.

The relation between changes in and the error in the determination of the position where is less clear, but for small enough the error should be approximately proportional to .

However, the actual relation between and the accuracy cannot be guaranteed.

You are strongly recommended to call ivp_rkm_zero_simple with more than one value for and to compare the results obtained to estimate their accuracy.

In the absence of any prior knowledge you might compare results obtained by calling ivp_rkm_zero_simple with and if correct decimal digits in the solution are required.

irelabint

Determines the type of error control. At each step in the numerical solution an estimate of the local error, , is made. For the current step to be accepted the following condition must be satisfied:

;

;

, where is machine precision.

If the appropriate condition is not satisfied, the step size is reduced and the solution recomputed on the current step.

If you wish to measure the error in the computed solution in terms of the number of correct decimal places, set on entry, whereas if the error requirement is in terms of the number of correct significant digits, set .

Where there is no preference in the choice of error test, will result in a mixed error test.

It should be borne in mind that the computed solution will be used in evaluating .

hmaxfloat

If , no special action is taken.

If , a check is made for a change in sign of at steps not greater than .

This facility should be used if there is any chance of ‘missing’ the change in sign by checking too infrequently.

For example, if two changes of sign of are expected within a distance , say, of each other, a suitable value for might be .

If only one change of sign in is expected on the range to , the choice is most appropriate.

fcncallable f = fcn(x, y, data=None)

must evaluate the functions (i.e., the derivatives ) for given values of its arguments .

Parameters
xfloat

, the value of the argument.

yfloat, ndarray, shape

, for , the value of the argument.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
ffloat, array-like, shape

The value of , for .

gcallable retval = g(x, y, data=None)

must evaluate the function at a specified point.

Parameters
xfloat

, the value of the independent variable.

yfloat, ndarray, shape

The value of , for .

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
retvalfloat

The value of at the specified point.

dataarbitrary, optional

User-communication data for callback functions.

Returns
xfloat

The point where unless an error has occurred, when it contains the value of at the error. In particular, if anywhere on the range to , it will contain on exit.

yfloat, ndarray, shape

The computed values of the solution at the final point .

tolfloat

Normally unchanged. However if the range from to the position where (or to the final value of if an error occurs) is so short that a small change in is unlikely to make any change in the computed solution, is returned with its sign changed. To check results returned with , ivp_rkm_zero_simple should be called again with a positive value of whose magnitude is considerably smaller than that of the previous call.

Raises
NagValueError
(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

The value of , , is too small for the function to take an initial step.

(errno )

An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.

(errno )

A serious error occurred in a call to the internal integrator.

The error code internally was . Please contact NAG.

(errno )

Unexpected internal error in call to interpolation routine.

The interpolation routine returned error flag .

Warns
NagAlgorithmicWarning
(errno )

The value of , , is too small for the function to make any further progress across the integration range. Current value of .

(errno )

No change in sign of the function was detected in the integration range.

Notes

No equivalent traditional C interface for this routine exists in the NAG Library.

ivp_rkm_zero_simple advances the solution of a system of ordinary differential equations

from towards using a Merson form of the Runge–Kutta method. The system is defined by , which evaluates in terms of and (see Parameters), and the values of must be given at .

As the integration proceeds, a check is made on the function specified by you, to determine an interval where it changes sign. The position of this sign change is then determined accurately by interpolating for the solution and its derivative. It is assumed that is a continuous function of the variables, so that a solution of can be determined by searching for a change in sign in .

The accuracy of the integration and, indirectly, of the determination of the position where , is controlled by .

For a description of Runge–Kutta methods and their practical implementation see Hall and Watt (1976).

References

Hall, G and Watt, J M (ed.), 1976, Modern Numerical Methods for Ordinary Differential Equations, Clarendon Press, Oxford