NAG CL Interface
d02qfc (ivp_​adams_​roots)

1 Purpose

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

2 Specification

#include <nag.h>
void  d02qfc (Integer neqf,
void (*fcn)(Integer neqf, double x, const double y[], double f[], Nag_User *comm),
double *t, double y[], double tout,
double (*g)(Integer neqf, double x, const double y[], const double yp[], Integer k, Nag_User *comm),
Nag_User *comm, Nag_ODE_Adams *opt, NagError *fail)
The function may be called by the names: d02qfc or nag_ode_ivp_adams_roots.

3 Description

Given the initial values x , y 1 , y 2 , , y neqf the function integrates a non-stiff system of first order ordinary differential equations of the type, y i = f i x , y 1 , y 2 , , y neqf , for i=1,2,,neqf, 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 , , y neqf , and y 1 , y 2 , , y 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 = 0 ,   j = 1 , 2 , , neqg .  
(See d02qwc for the specification of 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, which evaluates g j in terms of x , y 1 , , y neqf and y 1 , , y neqf . 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 need to select the mode of operation, the error control, the root-finding technique and various integration inputs with a prior call of the setup function d02qwc.
For a description of the practical implementation of an Adams' formula see Shampine and Gordon (1975) and Shampine and Watts (1979).

4 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

5 Arguments

1: neqf Integer Input
On entry: the number of differential equations.
Constraint: neqf1 .
2: fcn function, supplied by the user External Function
fcn must evaluate the functions f i (that is the first derivatives y i ) for given values of its arguments x , y 1 , y 2 , , y neqf .
The specification of fcn is:
void  fcn (Integer neqf, double x, const double y[], double f[], Nag_User *comm)
1: neqf Integer Input
On entry: the number of differential equations.
2: x double Input
On entry: the current value of the argument x .
3: y[neqf] const double Input
On entry: y[i-1] contains the current value of the argument y i , for i=1,2,,neqf.
4: f[neqf] double Output
On exit: f[i-1] must contain the value of f i , for i=1,2,,neqf.
5: comm Nag_User *
Pointer to a structure of type Nag_User with the following member:
pPointer 
On entry/exit: the pointer commp should be cast to the required type, e.g., struct user *s = (struct user *)comm → p, to obtain the original object's address with appropriate type.
Note: fcn should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d02qfc. If your code inadvertently does return any NaNs or infinities, d02qfc is likely to produce unexpected results.
3: t double * Input/Output
On entry: after a call to d02qwc with state=Nag_NewStart (i.e., an initial entry), t must be set to the initial value of the independent variable x .
On 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.
4: y[neqf] double Input/Output
On entry: the initial values of the solution y 1 , y 2 , , y neqf .
On 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.
5: tout double Input
On 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.
6: g function, supplied by the user External Function
g must evaluate a given component of g x,y, y at a specified point.
If root-finding is not required the actual argument for g must be the NAG defined null double function pointer NULLDFN.
The specification of g is:
double  g (Integer neqf, double x, const double y[], const double yp[], Integer k, Nag_User *comm)
1: neqf Integer Input
On entry: the number of differential equations.
2: x double Input
On entry: the current value of the independent variable.
3: y[neqf] const double Input
On entry: the current values of the dependent variables.
4: yp[neqf] const double Input
On entry: the current values of the derivatives of the dependent variables.
5: k Integer Input
On entry: the component of g which must be evaluated.
6: comm Nag_User *
Pointer to a structure of type Nag_User with the following member:
pPointer 
On entry/exit: the pointer commp should be cast to the required type, e.g., struct user *s = (struct user *)comm → p, to obtain the original object's address with appropriate type.
Note: g should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d02qfc. If your code inadvertently does return any NaNs or infinities, d02qfc is likely to produce unexpected results.
7: comm Nag_User *
Pointer to a structure of type Nag_User with the following member:
pPointer 
On entry/exit: the pointer commp, of type Pointer, allows you to communicate information to and from fcn and g. An object of the required type should be declared, e.g., a structure, and its address assigned to the pointer commp by means of a cast to Pointer in the calling program. E.g. comm.p = (Pointer)&s.
8: opt Nag_ODE_Adams *
Pointer to a structure of type Nag_ODE_Adams as initialized by the setup function d02qwc with the following members:
rootNag_BooleanOutput
On exit: if root-finding was required ( neqg>0 in a call to the setup function d02qwc ), then root specifies whether or not the output value of the argument t is a root of one of the event functions. If root=Nag_FALSE , then no root was detected, whereas root=Nag_TRUE indicates a root.
If root-finding was not required ( neqg=0 ) then on exit root=Nag_FALSE .
If root=Nag_FALSE , then optindex, opttype, optevents and optresids are indeterminate.
indexIntegerOutput
On exit: the index k of the event equation g k x,y, y = 0 for which the root has been detected.
typeIntegerOutput
On exit: information about the root detected for the event equation defined by optindex. The possible values of type with their interpretations are as follows:
  • If type=1 , a simple root, or lack of distinguishing information available.
  • If type=2 , a root of even multiplicity is believed to have been detected, that is no change in sign of the event function was found.
  • If type=3 , a high order root of odd multiplicity.
  • If type=4 , a possible root, but due to high multiplicity or a clustering of roots accurate evaluation of the event function was prohibited by round-off error and/or cancellation.
In general, the accuracy of the root is less reliable for values of type>1 .
eventsInteger *Output
On exit: array pointer containing information about the k th event function on a very small interval containing the root, t. All roots lying in this interval are considered indistinguishable numerically and therefore should be regarded as defining a root at t. The possible values of events[j-1] , j = 1 , 2 , , neqg, with their interpretations are as follows:
  • events[j-1] = 0 , the j th event function did not have a root;
  • events[j-1] = -1 , the j th event function changed sign from positive to negative about a root, in the direction of integration;
  • events[j-1] = 1 , the j th event function changed sign from negative to positive about a root, in the direction of integration;
  • events[j-1] = 2 , a root was identified, but no change in sign was observed.
residsdoubleOutput
On exit: array pointer, optresids[j-1] , j = 1 , 2 , , neqg, contains value of the j th event function computed at the root, t.
ypdoubleOutput
On exit: array pointer to the approximate derivative of the solution component y i at the output value of t. These values are obtained by the evaluation of y = f x,y except when the output value of the argument t is tout and opttcurrtout , in which case they are obtained by interpolation.
tcurrdoubleOutput
On exit: the value of the independent variable which the integrator has actually reached. tcurr will always be at least as far as the output value of the argument t in the direction of integration, but may be further.
hlastdoubleOutput
On exit: the last successful step size used in the integration.
hnextdoubleOutput
On exit: the next step size which the integration would attempt.
ord_lastIntegerOutput
On exit: the order of the method last used (successfully) in the integration.
ord_nextIntegerOutput
On exit: the order of the method which the integration would attempt on the next step.
nsuccessIntegerOutput
On exit: the number of integration steps attempted that have been successful since the start of the current problem.
nfailIntegerOutput
On exit: the number of integration steps attempted that have failed since the start of the current problem.
tolfacdoubleOutput
On exit: a tolerance scale factor, tolfac1.0 , returned when d02qfc exits with fail.code=NE_ODE_TOL . If rtol and atol are uniformly scaled up by a factor of tolfac and d02qwc is called, the next call to d02qfc is deemed likely to succeed.
9: fail NagError * Input/Output
The NAG error argument (see Section 7 in the Introduction to the NAG Library CL Interface).

6 Error Indicators and Warnings

NE_DIRECTION_CHANGE
The value of tout, value, indicates a change in the integration direction. This is not permitted on a continuation call.
NE_MAX_STEP
The maximum number of steps have been attempted.
If integration is to be continued then the function may be called again and a further max_step steps will be attempted (see d02qwc for details of max_step ).
NE_NEQF
The value of neqf supplied is not the same as that given to the setup function d02qwc. neqf=value but the value given to
d02qwc was value.
NE_NO_G_FUN
Root finding has been requested by setting neqg>0 , neqg=value , but argument g is a null function.
NE_NO_SETUP
The setup function d02qwc has not been called.
NE_ODE_TOL
The error tolerances are too stringent. rtol and atol should be scaled up by the factor opttolfac and the integration function re-entered. opttolfac=value (see Section 9).
NE_SETUP_ERROR
The call to setup function d02qwc produced an error.
NE_SINGULAR_POINT
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.
NE_STIFF_PROBLEM
The problem appears to be stiff.
(See the D02 Chapter Introduction for a discussion of the term ‘stiff’). Although it is inefficient to use this integrator to solve stiff problems, integration may be continued by resetting fail and calling the function again.
NE_T_CHANGED
The value of t has been changed from value to value. This is not permitted on a continuation call.
NE_T_SAME_TOUT
On entry, tout=t , t is value.
NE_TOUT_TCRIT
tout=value but crit was set Nag_TRUE in setup call and integration cannot be attempted beyond tcrit=value .
NE_WEIGHT_ZERO
An error weight has become zero during the integration, see d02qwc document; atol[value] was set to 0.0 but y[value] is now 0.0. Integration successful as far as t=value .
The value of the array index is returned in fail.errnum.

7 Accuracy

The accuracy of integration is determined by the arguments vectol, rtol and atol in a prior call to d02qwc. Note that only the local error at each step is controlled by these arguments. The error estimates obtained are not strict bounds but are usually reliable over one step. Over a number of steps the overall error may accumulate in various ways, depending on the properties of the differential equation system. The code is designed so that a reduction in the tolerances should lead to an approximately proportional reduction in the error. You are strongly recommended to call d02qfc with more than one set of tolerances and to compare the results obtained to estimate their accuracy.
The accuracy obtained depends on the type of error test used. If the solution oscillates around zero a relative error test should be avoided, whereas if the solution is exponentially increasing an absolute error test should not be used. If different accuracies are required for different components of the solution then a component-wise error test should be used. For a description of the error test see the specifications of the arguments vectol, atol and rtol in the function document for d02qwc.
The accuracy of any roots located will depend on the accuracy of integration and may also be restricted by the numerical properties of g x,y, y . When evaluating g you should try to write the code so that unnecessary cancellation errors will be avoided.

8 Parallelism and Performance

d02qfc is not threaded in any implementation.

9 Further Comments

If the function fails with fail.code=NE_ODE_TOL , then the combination of atol and rtol may be so small that a solution cannot be obtained, in which case the function should be called again using larger values for rtol and/or atol when calling the setup function d02qwc. If the accuracy requested is really needed then you should consider whether there is a more fundamental difficulty. For example:
  1. (a)in the region of a singularity the solution components will usually be of a large magnitude. The function could be used in one-step mode to monitor the size of the solution with the aim of trapping the solution before the singularity. In any case numerical integration cannot be continued through a singularity, and analytical treatment may be necessary;
  2. (b)for ‘stiff’ equations, where the solution contains rapidly decaying components, the function will require a very small step size to preserve stability. This will usually be exhibited by excessive computing time and sometimes an error exit with fail.code=NE_ODE_TOL , but usually an error exit with fail.code=NE_MAX_STEP or NE_STIFF_PROBLEM. The Adams' methods are not efficient in such cases. A high proportion of failed steps (see argument optnfail) may indicate stiffness but there may be other reasons for this phenomenon.
d02qfc can be used for producing results at short intervals (for example, for graph plotting); you should set crit=Nag_TRUE and tcrit to the last output point required in a prior call to d02qwc and then set tout appropriately for each output point in turn in the call to d02qfc.
The structure opt will contain pointers which have been allocated memory by calls to d02qwc. This allocated memory is then accessed by d02qfc and, if required, d02qzc. When all calls to these functions have been completed the function d02qyc may be called to free memory allocated to the structure.

10 Example

We solve the equation
y = -y ,   y 0 = 0 , y 0 = 1  
reposed as
y 1 = y 2 y 2 = - y 1  
over the range 0,10.0 with initial conditions y 1 = 0.0 and y 2 = 1.0 using vector error control ( vectol=Nag_TRUE ) and computation of the solution at tout=10.0 with tcrit=10.0 ( crit=Nag_TRUE ). Also, we use d02qfc to locate the positions where y 1 = 0.0 or where the first component has a turning point, that is y 1 = 0.0 .

10.1 Program Text

Program Text (d02qfce.c)

10.2 Program Data

None.

10.3 Program Results

Program Results (d02qfce.r)