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

naginterfaces.library.ode.ivp_bdf_zero_simple(x, xend, y, fcn, tol, relabs, pederv=None, output=None, g=None, data=None, io_manager=None, spiked_sorder='C')

ivp_bdf_zero_simple integrates a stiff system of first-order ordinary differential equations over an interval with suitable initial conditions, using a variable-order, variable-step method implementing the Backward Differentiation Formulae (BDF), until a user-specified function, if supplied, of the solution is zero, and returns the solution at points specified by you, if desired.

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

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/d02/d02ejf.html

Parameters

xfloat

The initial value of the independent variable $x$.

xendfloat

The final value of the independent variable. If $xend<x$, 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}}$ at $x=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 independent variable.

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

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

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

tolfloat

Must be set to a positive tolerance for controlling the error in the integration. Hence $tol$ affects the determination of the position where $g(x,y)=0.0$, if $g$ is supplied.

ivp_bdf_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.

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

You are strongly recommended to call ivp_bdf_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 the results obtained by calling ivp_bdf_zero_simple with $tol={10}^{-p}$ and $tol={10}^{-p-1}$ if $p$ correct decimal digits are required in the solution.

relabsstr, length 1

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:

$$\text{est}=\sqrt{\frac{1}{\text{n}}\sum _{i=1}^{\text{n}}{\left(e_i/({\tau }_r\times \left|y_i\right|+{\tau }_a)\right)}^2}\le 1.0$$

where ${\tau }_r$ and ${\tau }_a$ are defined by

$relabs$	${\tau }_r$	${\tau }_a$
‘M’	$tol$	$tol$
‘A’	0.0	$tol$
‘R’	$tol$	$ϵ$
‘D’	$tol$	$ϵ$

where $ϵ$ is a small machine-dependent number and $e_i$ is an estimate of the local error at $y_i$, computed internally. If the appropriate condition is not satisfied, the step size is reduced and the solution is 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, $relabs$ should be set to ‘A’ on entry, whereas if the error requirement is in terms of the number of correct significant digits, $relabs$ should be set to ‘R’. If you prefer a mixed error test, $relabs$ should be set to ‘M’, otherwise if you have no preference, $relabs$ should be set to the default ‘D’. Note that in this case ‘D’ is taken to be ‘R’.

pedervNone or callable pw = pederv(x, y, data=None), optional

Note: if this argument is None then a NAG-supplied facility will be used.

$pederv$ must evaluate the Jacobian of the system (that is, the partial derivatives $\frac{\partial f_i}{\partial y_j}$) for given values of the variables $x,y_1,y_2,\dots ,y_{\text{n}}$.

Parameters

xfloat

$x$, the value of the independent variable.

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

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

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

pwfloat, array-like, shape $(n,n)$

$pw[\text{i}-1,\text{j}-1]$ must contain the value of $\frac{\partial f_{\text{i}}}{\partial y_{\text{j}}}$, for $\text{j}=1,2,\dots ,\text{n}$, for $\text{i}=1,2,\dots ,\text{n}$.

outputNone or callable xsol = output(xsol, y, data=None), optional

Note: if this argument is None then a NAG-supplied facility will be used.

$output$ permits access to intermediate values of the computed solution (for example to print or plot them), at successive user-specified points.

It is initially called by ivp_bdf_zero_simple with $xsol=x$ (the initial value of $x$).

You must reset $xsol$ to the next point (between the current $xsol$ and $xend$) where $output$ is to be called, and so on at each call to $output$.

If, after a call to $output$, the reset point $xsol$ is beyond $xend$, ivp_bdf_zero_simple will integrate to $xend$ with no further calls to $output$; if a call to $output$ is required at the point $xsol=xend$, $xsol$ must be given precisely the value $xend$.

Parameters

xsolfloat

$x$, the value of the independent variable.

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

The computed solution at the point $xsol$.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

xsolfloat

You must set $xsol$ to the next value of $x$ at which $output$ is to be called.

gNone or callable retval = g(x, y, data=None), optional

Note: if this argument is None then a NAG-supplied facility will be used.

$g$ must evaluate the function $g(x,y)$ for specified values $x,y$.

It specifies the function $g$ for which the first position $x$ where $g(x,y)=0$ is to be found.

Parameters

xfloat

$x$, the value of the independent variable.

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

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

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

retvalfloat

The value of $g$ at the specified points.

dataarbitrary, optional

User-communication data for callback functions.

io_managerFileObjManager, optional

Manager for I/O in this routine.

spiked_sorderstr, optional

If $pw$ in $pederv$ is spiked (i.e., has unit extent in all but one dimension, or has size $1$), $spiked\_sorder$ selects the storage order to associate with it in the NAG Engine:

spiked_sorder = $\text{'C'}$

row-major storage will be used;

spiked_sorder = $\text{'F'}$

column-major storage will be used.

Returns

xfloat

If $g$ is supplied by you, $x$ contains the point where $g(x,y)=0.0$, unless $g(x,y)\ne 0.0$ anywhere on the range $x$ to $xend$, in which case, $x$ will contain $xend$. If $g$ is not supplied $x$ contains $xend$, unless an error has occurred, when it contains the value of $x$ at the error.

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 $x$ to $xend$ 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.

Raises

NagValueError

(errno $1$)

On entry, $relabs=⟨value⟩$.

Constraint: $relabs=\text{'M'}$, $\text{'A'}$, $\text{'R'}$ or $\text{'D'}$.

(errno $1$)

On entry, $x=⟨value⟩$ and $xend=⟨value⟩$.

Constraint: $x\ne xend$.

(errno $1$)

On entry, $tol=⟨value⟩$.

Constraint: $tol>0.0$.

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 1$.

(errno $3$)

No integration steps have been taken. Progress not possible with the input value of $tol=⟨value⟩$.

(errno $4$)

No integration steps have been taken. $xsol$ has been set illegally.

(errno $7$)

Integration successful as far as $x=⟨value⟩$, but an internal error has occurred during rootfinding.

(errno $9$)

Impossible error — internal variable $IERR=⟨value⟩$.

(errno $9$)

Impossible error — internal variable $IREVCM=⟨value⟩$.

Warns

NagAlgorithmicWarning

(errno $2$)

Integration successful as far as $x=⟨value⟩$, but further progress not possible with the input value of $tol=⟨value⟩$.

(errno $5$)

Integration successful as far as $x=⟨value⟩$, but $xsol$ has been reset illegally.

(errno $6$)

No change in sign of the function $g(x,y)$ was detected in the integration range.

(errno $8$)

Integration successful as far as $x=⟨value⟩$, but an internal error has occurred during interpolation.

Notes

In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

ivp_bdf_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$ to $x=xend$ using a variable-order, variable-step method implementing the BDF. 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). The initial values of $y_1,y_2,\dots ,y_{\text{n}}$ must be given at $x=x$.

The solution is returned via the $output$ at points specified by you, if desired: this solution is obtained by $C^1$ interpolation on solution values produced by the method. As the integration proceeds a check can be made on the user-specified function $g(x,y)$ to determine an interval where it changes sign. The position of this sign change is then determined accurately by $C^1$ interpolation to the solution. It is assumed that $g(x,y)$ is a continuous function of the variables, so that a solution of $g(x,y)=0.0$ can be determined by searching for a change in sign in $g(x,y)$. The accuracy of the integration, the interpolation and, indirectly, of the determination of the position where $g(x,y)=0.0$, is controlled by the arguments $tol$ and $relabs$. The Jacobian of the system $y^{\prime }=f(x,y)$ may be supplied in $pederv$, if it is available.

For a description of BDF 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

See also

naginterfaces.library.examples.ode.ivp_bdf_zero_simple_ex.main()