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

naginterfaces.library.ode.ivp_rkm_val_simple(x, xend, y, tol, hmax, m, val, fcn, data=None)

ivp_rkm_val_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 specified component attains a given value.

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

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/d02/d02bgf.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 will proceed in the 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 $y_m=\alpha$.

ivp_rkm_val_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 $y_m=\alpha$ 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_val_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_val_simple with $tol={10.0}^{-p}$ and $tol={10.0}^{-p-1}$ if $p$ correct decimal digits in the solution are required.

hmaxfloat

Controls how the sign of $y_m-\alpha$ is checked.

$hmax=0.0$

$y_m-\alpha$ is checked at every internal integration step.

$hmax\ne 0.0$

The computed solution is checked for a change in sign of $y_m-\alpha$ at steps of 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 $y_m-\alpha$ are expected within a distance $h$, say, of each other then a suitable value for $hmax$ might be $hmax=h/2$. If only one change of sign in $y_m-\alpha$ is expected on the range $x$ to $xend$ then $hmax=0.0$ is most appropriate.

mint

The index $m$ of the component of the solution whose value is to be checked.

valfloat

The value of $\alpha$ in the equation $y_m=\alpha$ to be solved for $x$.

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}$.

dataarbitrary, optional

User-communication data for callback functions.

Returns

xfloat

The point where the component $y_m$ attains the value $\alpha$ unless an error has occurred, when it contains the value of $x$ at the error. In particular, if $y_m\ne \alpha$ anywhere on the range $x=x$ to $x=xend$, it will contain $xend$ on exit.

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

The computed values of the solution at a point near the solution $x$, unless an error has occurred when they contain the computed values at the final value of $x$.

tolfloat

Normally unchanged. However if the range from $x$ to the position where $y_m=\alpha$ (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 then, on return, $tol$ has its sign changed. To check results returned with $tol<0.0$, ivp_rkm_val_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, $m=⟨value⟩$ and $n=⟨value⟩$.

Constraint: $m\le n$.

(errno $1$)

On entry, $m=⟨value⟩$.

Constraint: $m>0$.

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n>0$.

(errno $1$)

On entry, $tol=⟨value⟩$.

Constraint: $tol>0.0$.

(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 $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 $4$)

No change in sign of the function $y_m-\alpha$ was detected in the integration range.

Notes

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

ivp_rkm_val_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 specified component $y_m$ of the solution to determine an interval where it attains a given value $\alpha$. The position where this value is attained is then determined accurately by interpolation on the solution and its derivative. It is assumed that the solution of $y_m=\alpha$ can be determined by searching for a change in sign in the function $y_m-\alpha$.

The accuracy of the integration and, indirectly, of the determination of the position where $y_m=\alpha$ is controlled by the argument $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