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://support.nag.com/numeric/nl/nagdoc_30.2/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 typefrom 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