naginterfaces.library.ode.ivp_​adams_​roots

naginterfaces.library.ode.ivp_adams_roots(fcn, t, y, tout, neqg, comm, g=None, data=None)

ivp_adams_roots is a function for integrating a non-stiff system of first-order ordinary differential equations using a variable-order variable-step Adams’ method. A root-finding facility is provided.

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

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

Parameters

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

$fcn$ must evaluate the functions $f_i$ (that is the first derivatives $y_i^{\prime }$) for given values of its arguments $x$, $y_1,y_2,\dots ,y_{\text{neqf}}$.

Parameters

xfloat

The current value of the argument $x$.

yfloat, ndarray, shape $\left(\text{neqf}\right)$

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

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

ffloat, array-like, shape $\left(\text{neqf}\right)$

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

tfloat

After a call to ivp_adams_setup() with $\text{statef}=\text{'S'}$ (i.e., an initial entry), $t$ must be set to the initial value of the independent variable $x$.

yfloat, array-like, shape $\left(\text{neqf}\right)$

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

toutfloat

The next value of $x$ at which a computed solution is required. For the initial $t$, the input value of $tout$ is used to determine the direction of integration. Integration is permitted in either direction. If $tout=t$ on exit, $tout$ must be reset beyond $t$ in the direction of integration, before any continuation call.

neqgint

The number of event functions which you are defining for root-finding. If root-finding is not required the value for $neqg$ must be $\le 0$. Otherwise it must be the same argument $neqg$ used in the prior call to ivp_adams_setup().

commdict, communication object, modified in place

Communication structure.

This argument must have been initialized by a prior call to ivp_adams_setup().

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

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

$g$ must evaluate a given component of $g(x,y,y^{\prime })$ at a specified point.

If root-finding is not required the actual argument for $g$ must be None.

Parameters

xfloat

The current value of the independent variable.

yfloat, ndarray, shape $\left(\text{neqf}\right)$

The current values of the dependent variables.

ypfloat, ndarray, shape $\left(\text{neqf}\right)$

The current values of the derivatives of the dependent variables.

kint

The component of $g$ which must be evaluated.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

retvalfloat

The value of the component of $g(x,y,y^{\prime })$ at the specified point.

dataarbitrary, optional

User-communication data for callback functions.

Returns

tfloat

The value of $x$ at which $y$ has been computed. This may be an intermediate output point, a root, $tout$ or a point at which an error has occurred. If the integration is to be continued, possibly with a new value for $tout$, $t$ must not be changed.

yfloat, ndarray, shape $\left(\text{neqf}\right)$

The computed values of the solution at the exit value of $t$. If the integration is to be continued, possibly with a new value for $tout$, these values must not be changed.

rootbool

If root-finding was required ($neqg>0$ on entry), $root$ specifies whether or not the output value of the argument $t$ is a root of one of the event functions. If $root=False$, no root was detected, whereas $root=True$ indicates a root and you should make a call to ivp_adams_rootdiag() for further information.

If root-finding was not required ($neqg=0$ on entry), then on exit $root=False$.

Raises

NagValueError

(errno $1$)

The value of $tout$, $⟨value⟩$, indicates a change in the integration direction. This is not permitted on a continuation call.

(errno $1$)

The value of $t$ has been changed from $⟨value⟩$ to $⟨value⟩$.

This is not permitted on a continuation call.

(errno $1$)

On entry, $tout=⟨value⟩$ but $\text{crit}=True$ in ivp_adams_setup().

Integration cannot be attempted beyond $\text{tcrit}=⟨value⟩$.

(errno $1$)

On entry, $tout=t=⟨value⟩$.

(errno $1$)

On entry, $neqg=⟨value⟩$ and $\text{neqg}=0$ in ivp_adams_setup().

Constraint: if $neqg\le 0$ then $neqg=\text{neqg}$ in ivp_adams_setup().

(errno $1$)

On entry, $neqg=⟨value⟩$ and $\text{neqg}=0$ in ivp_adams_setup().

Constraint: if $neqg>0$ then $\text{neqg}>0$ in ivp_adams_setup().

(errno $1$)

On entry, $neqg=⟨value⟩$ and $\text{neqg}=⟨value⟩$ in ivp_adams_setup().

Constraint: if $neqg\le 0$ then $\text{neqg}\le 0$ in ivp_adams_setup().

(errno $1$)

On entry, $\text{neqf}=⟨value⟩$ and $\text{neqf}=⟨value⟩$ in ivp_adams_setup().

Constraint: $\text{neqf}=\text{neqf}$ in ivp_adams_setup().

(errno $1$)

The call to setup function ivp_adams_setup() produced an error.

(errno $1$)

The setup function ivp_adams_setup() has not been called.

(errno $3$)

The error tolerances are too stringent.

(errno $7$)

Two successive errors detected at the current value of $t$, $⟨value⟩$.

Warns

NagAlgorithmicWarning

(errno $2$)

The maximum number of steps has been attempted.

If integration is to be continued then the function may be called again and a further $\text{maxstp}$ in ivp_adams_setup() steps will be attempted.

(errno $4$)

Error weight $i$ has become zero during the integration.

$\text{atol}\left[i\right]=0.0$ in ivp_adams_setup() but $y\left[i\right]$ is now $0.0$. Integration successful as far as $t$.

(errno $5$)

The problem appears to be stiff.

(errno $6$)

A change in sign of an event function has been detected but the root-finding process appears to have converged to a singular point of $t$ rather than a root. Integration may be continued by calling the function again.

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.

Given the initial values $x,y_1,y_2,\dots ,y_{\text{neqf}}$ ivp_adams_roots integrates a non-stiff system of first-order differential equations of the type

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

from $x=t$ to $x=tout$ using a variable-order variable-step Adams’ method. The system is defined by $fcn$, which evaluates $f_i$ in terms of $x$ and $y_1,y_2,\dots ,y_{\text{neqf}}$, and $y_1,y_2,\dots ,y_{\text{neqf}}$ are supplied at $x=t$. The function is capable of finding roots (values of $x$) of prescribed event functions of the form

$$g_j(x,y,y^{\prime })=0\text{,}j=1,2,\dots ,\text{neqg}\text{.}$$

(See ivp_adams_setup() for the specification of $\text{neqg}$.)

Each $g_j$ is considered to be independent of the others so that roots are sought of each $g_j$ individually. The root reported by the function will be the first root encountered by any $g_j$. Two techniques for determining the presence of a root in an integration step are available: the sophisticated method described in Watts (1985) and a simplified method whereby sign changes in each $g_j$ are looked for at the ends of each integration step. The event functions are defined by $g$ supplied by you which evaluates $g_j$ in terms of $x,y_1,\dots ,y_{\text{neqf}}$ and $y_1^{\prime },\dots ,y_{\text{neqf}}^{\prime }$. In one-step mode the function returns an approximation to the solution at each integration point. In interval mode this value is returned at the end of the integration range. If a root is detected this approximation is given at the root. You select the mode of operation, the error control, the root-finding technique and various optional inputs by a prior call to the setup function ivp_adams_setup().

For a description of the practical implementation of an Adams’ formula see Shampine and Gordon (1975) and Shampine and Watts (1979).

References

Shampine, L F and Gordon, M K, 1975, Computer Solution of Ordinary Differential Equations – The Initial Value Problem, W H Freeman & Co., San Francisco

Shampine, L F and Watts, H A, 1979, DEPAC – design of a user oriented package of ODE solvers, Report SAND79-2374, Sandia National Laboratory

Watts, H A, 1985, RDEAM – An Adams ODE code with root solving capability, Report SAND85-1595, Sandia National Laboratory