naginterfaces.library.ode.ivp_​adams_​roots

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

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://www.nag.com/numeric/nl/nagdoc_29.3/flhtml/d02/d02qff.html

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

must evaluate the functions (that is the first derivatives ) for given values of its arguments , .

Parameters
xfloat

The current value of the argument .

yfloat, ndarray, shape

, for , the current value of the argument.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
ffloat, array-like, shape

The value of , for .

tfloat

After a call to ivp_adams_setup() with (i.e., an initial entry), must be set to the initial value of the independent variable .

yfloat, array-like, shape

The initial values of the solution .

toutfloat

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

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

must evaluate a given component of at a specified point.

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

Parameters
xfloat

The current value of the independent variable.

yfloat, ndarray, shape

The current values of the dependent variables.

ypfloat, ndarray, shape

The current values of the derivatives of the dependent variables.

kint

The component of which must be evaluated.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
retvalfloat

The value of the component of at the specified point.

dataarbitrary, optional

User-communication data for callback functions.

Returns
tfloat

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.

yfloat, ndarray, shape

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.

rootbool

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), then on exit .

Raises
NagValueError
(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

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

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

(See ivp_adams_setup() for the specification of .)

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. The event functions are defined by supplied by you which evaluates in terms of and . 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