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

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://www.nag.com/numeric/nl/nagdoc_28.6/flhtml/d02/d02qgf.html

Parameters
tfloat

On initial entry: that is after a call to ivp_adams_setup() with , must be set to the initial value of the independent variable .

yfloat, ndarray, shape , modified in place

On initial entry: the initial values of the solution .

On final exit: the computed values of the solution at the exit value of . If the integration is to be continued, possibly with a new value for , these values must not be changed.

toutfloat

On initial entry: the next value of at which a computed solution is required. For the initial , the input value of is used to determine the direction of integration. Integration is permitted in either direction. If on exit, must be reset beyond 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 must be . Otherwise it must be the same value as the argument used in the prior call to ivp_adams_setup().

irevcmint

On initial entry: must have the value .

grvcmfloat

On initial entry: need not be set.

On intermediate entry: with , , or , must contain the value of , where is given by .

kgrvcmint

On intermediate entry: with , , or , 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 at which has been computed. This may be an intermediate output point, a root, or a point at which an error has occurred. If the integration is to be continued, possibly with a new value for , must not be changed.

rootbool

On final exit: if root-finding was required ( on entry), specifies whether or not the output value of the argument is a root of one of the event functions. If , no root was detected, whereas indicates a root and you should make a call to ivp_adams_rootdiag() for further information.

If root-finding was not required ( on entry), .

irevcmint

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

, , , , , or

Indicates that you must supply , where is given by and is returned in , for when and , for when . should be placed in location , for .

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 , as given by . No values must be changed before re-entering ivp_adams_roots_revcom. This facility enables you to determine the number of unsuccessful steps.

, , or

Indicates that you must supply , where is given by , is given by , is given by and is given by . The result should be placed in the variable .

On final exit: has the value , which indicates that an output point or root has been reached or an error has occurred (see ).

trvcmfloat

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

yrvcmint

On intermediate exit: with , , , , , , , , , or , specifies the locations of the dependent variables for use in evaluating the differential system or the event functions.

is given by , for .

is given by , for .

yprvcmint

On intermediate exit: with , , , , , or , specifies the positions in [‘rwork’] at which you should place the derivatives . should be placed in location , for .

With , , or , specifies the locations of the derivatives for use in evaluating the event functions. is given by , for .

kgrvcmint

On intermediate exit: with , , or , specifies which event function you must evaluate.

Raises
NagValueError
(errno )

On entry, had an illegal value, .

(errno )

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

(errno )

The value of has been changed from to .

This is not permitted on a continuation call.

(errno )

On entry, but in ivp_adams_setup().

Integration cannot be attempted beyond .

(errno )

On entry, .

(errno )

On entry, and in ivp_adams_setup().

Constraint: if then in ivp_adams_setup().

(errno )

On entry, and in ivp_adams_setup().

Constraint: if then in ivp_adams_setup().

(errno )

On entry, and in ivp_adams_setup().

Constraint: if then in ivp_adams_setup().

(errno )

On entry, and in ivp_adams_setup().

Constraint: in ivp_adams_setup().

(errno )

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

(errno )

The setup function ivp_adams_setup() has not been called.

(errno )

The error tolerances are too stringent.

(errno )

Two successive errors detected at the current value of , .

Warns
NagAlgorithmicWarning
(errno )

The maximum number of steps has been attempted.

If integration is to be continued then the function may be called again and a further in ivp_adams_setup() steps will be attempted.

(errno )

Error weight has become zero during the integration.

in ivp_adams_setup() but is now . Integration successful as far as .

(errno )

The problem appears to be stiff.

(errno )

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 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 ivp_adams_roots_revcom integrates a non-stiff system of first-order differential equations of the type

from to using a variable-order variable-step Adams’ method. You define the system by reverse communication, evaluating in terms of and , and are supplied at by ivp_adams_roots_revcom. The function is capable of finding roots (values of ) of prescribed event functions of the form

Each is considered to be independent of the others so that roots are sought of each individually. The root reported by the function will be the first root encountered by any . 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 are looked for at the ends of each integration step. You also define each 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