naginterfaces.library.ode.ivp_​adams_​roots_​revcom

naginterfaces.library.ode.ivp_adams_roots_revcom(t, y, tout, neqg, irevcm, grvcm, kgrvcm, comm)

ivp_adams_roots_revcom is a reverse communication 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 d02qg

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

Parameters

tfloat

On initial entry: that is after a call to ivp_adams_setup() with $\text{statef}=\text{'S'}$, $t$ must be set to the initial value of the independent variable $x$.

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

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

On final exit: 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.

toutfloat

On initial entry: 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

On initial entry: 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 value as the argument $neqg$ used in the prior call to ivp_adams_setup().

irevcmint

On initial entry: must have the value $0$.

grvcmfloat

On initial entry: need not be set.

On intermediate entry: with $irevcm=9$, $10$, $11$ or $12$, $grvcm$ must contain the value of $g_k(x,y,y^{\prime })$, where $k$ is given by $kgrvcm$.

kgrvcmint

On intermediate entry: with $irevcm=9$, $10$, $11$ or $12$, $kgrvcm$ must remain unchanged from a previous call to ivp_adams_roots_revcom.

commdict, communication object, modified in place

Communication structure.

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

Returns

tfloat

On final exit: 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.

rootbool

On final exit: 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), $root=False$.

irevcmint

On intermediate exit: specifies what action you must take before re-entering ivp_adams_roots_revcom with $irevcm$ unchanged.

$irevcm=1$, $2$, $3$, $4$, $5$, $6$ or $7$

Indicates that you must supply $y^{\prime }=f(x,y)$, where $x$ is given by $trvcm$ and $y_{\text{i}}$ is returned in $y[\text{i}-1]$, for $\text{i}=1,2,\dots ,\text{neqf}$ when $yrvcm=0$ and $comm{[}^{\prime }rwor{k}^{\prime }\left]\right[yrvcm+\text{i}-2]$, for $\text{i}=1,2,\dots ,\text{neqf}$ when $yrvcm\ne 0$. $y_{\text{i}}^{\prime }$ should be placed in location $comm{[}^{\prime }rwor{k}^{\prime }\left]\right[yprvcm+\text{i}-2]$, for $\text{i}=1,2,\dots ,\text{neqf}$.

$irevcm=8$

Indicates that the current step was not successful due to error test failure. The only information supplied to you on this return is the current value of the independent variable $t$, as given by $trvcm$. No values must be changed before re-entering ivp_adams_roots_revcom. This facility enables you to determine the number of unsuccessful steps.

$irevcm=9$, $10$, $11$ or $12$

Indicates that you must supply $g_k(x,y,y^{\prime })$, where $k$ is given by $kgrvcm$, $x$ is given by $trvcm$, $y_i$ is given by $y[i-1]$ and $y_i^{\prime }$ is given by $comm{[}^{\prime }rwor{k}^{\prime }\left]\right[yprvcm-1+i-1]$. The result $g_k$ should be placed in the variable $grvcm$.

On final exit: has the value $0$, which indicates that an output point or root has been reached or an error has occurred (see $\text{errno}$).

trvcmfloat

On intermediate exit: the current value of the independent variable.

yrvcmint

On intermediate exit: with $irevcm=1$, $2$, $3$, $4$, $5$, $6$, $7$, $9$, $10$, $11$ or $12$, $yrvcm$ specifies the locations of the dependent variables $y$ for use in evaluating the differential system or the event functions.

$yrvcm=0$

$y_{\text{i}}$ is given by $y\left[\text{i}\right]$, for $\text{i}=1,2,\dots ,\text{neqf}$.

$yrvcm\ne 0$

$y_{\text{i}}$ is given by $comm{[}^{\prime }rwor{k}^{\prime }\left]\right[yrvcm+\text{i}-2]$, for $\text{i}=1,2,\dots ,\text{neqf}$.

yprvcmint

On intermediate exit: with $irevcm=1$, $2$, $3$, $4$, $5$, $6$ or $7$, $yprvcm$ specifies the positions in $comm$[‘rwork’] at which you should place the derivatives $y^{\prime }$. $y_{\text{i}}^{\prime }$ should be placed in location $comm{[}^{\prime }rwor{k}^{\prime }\left]\right[yprvcm+\text{i}-2]$, for $\text{i}=1,2,\dots ,\text{neqf}$.

With $irevcm=9$, $10$, $11$ or $12$, $yprvcm$ specifies the locations of the derivatives $y^{\prime }$ for use in evaluating the event functions. $y_{\text{i}}^{\prime }$ is given by $comm{[}^{\prime }rwor{k}^{\prime }\left]\right[yprvcm+\text{i}-2]$, for $\text{i}=1,2,\dots ,\text{neqf}$.

kgrvcmint

On intermediate exit: with $irevcm=9$, $10$, $11$ or $12$, $kgrvcm$ specifies which event function $g_k(x,y,y^{\prime })$ you must evaluate.

Raises

NagValueError

(errno $1$)

On entry, $irevcm$ had an illegal value, $⟨value⟩$.

(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

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

Given the initial values $x,y_1,y_2,\dots ,y_{\text{neqf}}$ ivp_adams_roots_revcom 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. You define the system by reverse communication, evaluating $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$ by ivp_adams_roots_revcom. 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 ,neqg\text{.}$$

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. You also define each $g_j$ by reverse communication. 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).

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