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

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

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://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d02/d02bhf.html

Parameters

xfloat

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

xendfloat

The final value of the independent variable $x$.

If $xend<x$ on entry, integration proceeds in a negative direction.

yfloat, array-like, shape $\left(n\right)$

The initial values of the solution $y_1,y_2,\dots ,y_{\text{n}}$.

tolfloat

Must be set to a positive tolerance for controlling the error in the integration and in the determination of the position where $g(x,y)=0.0$.

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

The relation between changes in $tol$ and the error in the determination of the position where $g(x,y)=0.0$ is less clear, but for $tol$ small enough the error should be approximately proportional to $tol$.

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

You are strongly recommended to call ivp_rkm_zero_simple with more than one value for $tol$ 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 $tol={10.0}^{-p}$ and $tol={10.0}^{-p-1}$ if $p$ 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, $\text{est}$, is made. For the current step to be accepted the following condition must be satisfied:

$irelab=0$

$\text{est}\le tol\times max\{1.0,\left|y_1\right|,\left|y_2\right|,\dots ,\left|y_{\text{n}}\right|\}$;

$irelab=1$

$\text{est}\le tol$;

$irelab=2$

$\text{est}\le tol\times max\{ϵ,\left|y_1\right|,\left|y_2\right|,\dots ,\left|y_{\text{n}}\right|\}$, 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 $irelab=1$ on entry, whereas if the error requirement is in terms of the number of correct significant digits, set $irelab=2$.

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

It should be borne in mind that the computed solution will be used in evaluating $g(x,y)$.

hmaxfloat

If $hmax=0.0$, no special action is taken.

If $hmax\ne 0.0$, a check is made for a change in sign of $g(x,y)$ at steps not greater than $\left|hmax\right|$.

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 $g(x,y)$ are expected within a distance $h$, say, of each other, a suitable value for $hmax$ might be $hmax=h/2$.

If only one change of sign in $g(x,y)$ is expected on the range $x$ to $xend$, the choice $hmax=0.0$ is most appropriate.

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

$fcn$ must evaluate the functions $f_i$ (i.e., the derivatives $y_i^{\prime }$) for given values of its arguments $x,y_1,\dots ,y_{\text{n}}$.

Parameters

xfloat

$x$, the value of the argument.

yfloat, ndarray, shape $\left(n\right)$

$y_{\text{i}}$, for $\text{i}=1,2,\dots ,\text{n}$, the value of the argument.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

ffloat, array-like, shape $\left(n\right)$

The value of $f_{\text{i}}$, for $\text{i}=1,2,\dots ,\text{n}$.

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

$g$ must evaluate the function $g(x,y)$ at a specified point.

Parameters

xfloat

$x$, the value of the independent variable.

yfloat, ndarray, shape $\left(n\right)$

The value of $y_{\text{i}}$, for $\text{i}=1,2,\dots ,\text{n}$.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

retvalfloat

The value of $g(x,y)$ at the specified point.

dataarbitrary, optional

User-communication data for callback functions.

Returns

xfloat

The point where $g(x,y)=0.0$ unless an error has occurred, when it contains the value of $x$ at the error. In particular, if $g(x,y)\ne 0.0$ anywhere on the range $x$ to $xend$, it will contain $xend$ on exit.

yfloat, ndarray, shape $\left(n\right)$

The computed values of the solution at the final point $x=x$.

tolfloat

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

Raises

NagValueError

(errno $1$)

On entry, $irelab=⟨value⟩$.

Constraint: $0\le irelab\le 2$.

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n>0$.

(errno $1$)

On entry, $tol=⟨value⟩$.

Constraint: $tol>0.0$.

(errno $3$)

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

(errno $5$)

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 $6$)

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

The error code internally was $⟨value⟩$. Please contact NAG.

(errno $7$)

Unexpected internal error in call to interpolation routine.

The interpolation routine returned error flag $⟨value⟩$.

Warns

NagAlgorithmicWarning

(errno $2$)

The value of $tol$, $⟨value⟩$, is too small for the function to make any further progress across the integration range. Current value of $x=⟨value⟩$.

(errno $4$)

No change in sign of the function $g(x,y)$ 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

$$y_i^{\prime }=f_i(x,y_1,y_2,\dots ,y_{\text{n}})\text{,}i=1,2,\dots ,\text{n}\text{,}$$

from $x=x$ towards $x=xend$ using a Merson form of the Runge–Kutta method. The system is defined by $fcn$, which evaluates $f_i$ in terms of $x$ and $y_1,y_2,\dots ,y_{\text{n}}$ (see Parameters), and the values of $y_1,y_2,\dots ,y_{\text{n}}$ must be given at $x=x$.

As the integration proceeds, a check is made on the function $g(x,y)$ 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 $g(x,y)$ is a continuous function of the variables, so that a solution of $g(x,y)=0$ can be determined by searching for a change in sign in $g(x,y)$.

The accuracy of the integration and, indirectly, of the determination of the position where $g(x,y)=0$, is controlled by $tol$.

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