NAG Library ManualKeyword Search:

NAG Library Routine Document

d02qff (ivp_adams_roots)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

▸▿ 10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

1

Purpose

d02qff is a routine 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

Fortran Interface

Subroutine d02qff (

fcn, neqf, t, y, tout, g, neqg, root, rwork, lrwork, iwork, liwork, ifail)

Integer, Intent (In)	::	neqf, neqg, lrwork, liwork
Integer, Intent (Inout)	::	iwork(liwork), ifail
Real (Kind=nag_wp), External	::	g
Real (Kind=nag_wp), Intent (In)	::	tout
Real (Kind=nag_wp), Intent (Inout)	::	t, y(neqf), rwork(lrwork)
Logical, Intent (Out)	::	root
External	::	fcn

C Header Interface

#include nagmk26.h

void

d02qff_ (
void (NAG_CALL *fcn)( const Integer *neqf, const double *x, const double y[], double f[]),
const Integer *neqf, double *t, double y[], const double *tout,
double (NAG_CALL *g)( const Integer *neqf, const double *x, const double y[], const double yp[], const Integer *k),
const Integer *neqg, logical *root, double rwork[], const Integer *lrwork, Integer iwork[], const Integer *liwork, Integer *ifail)

3

Description

Given the initial values

x, y_{1}, y_{2}, \dots, y_{neqf}

d02qff integrates a non-stiff system of first-order differential equations of the type

y_{i}^{'} = f_{i} (x, y_{1}, y_{2}, \dots, y_{neqf}), i = 1, 2, \dots, neqf,

from

x = t

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}, \dots, y_{neqf}

, and

y_{1}, y_{2}, \dots, y_{neqf}

are supplied at

x = t

. The routine is capable of finding roots (values of

x

) of prescribed event functions of the form

g_{j} (x, y, y^{'}) = 0, j = 1, 2, \dots, neqg .

(See d02qwf 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 routine 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 supplied by you which evaluates

g_{j}

in terms of

x, y_{1}, \dots, y_{neqf}

and

y_{1}^{'}, \dots, y_{neqf}^{'}

. In one-step mode the routine 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 routine d02qwf.

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: $fcn$ – Subroutine, supplied by the user.External Procedure

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}, \dots, y_{neqf}

The specification of fcn is:

Fortran Interface

Subroutine fcn (

neqf, x, y, f)

Integer, Intent (In)	::	neqf
Real (Kind=nag_wp), Intent (In)	::	x, y(neqf)
Real (Kind=nag_wp), Intent (Out)	::	f(neqf)

C Header Interface

#include nagmk26.h

void	fcn ( const Integer neqf, const double x, const double y[], double f[])

1: $neqf$ – IntegerInput: On entry: the number of differential equations.
2: $x$ – Real (Kind=nag_wp)Input: On entry: the current value of the argument $x$ .
3: $y (neqf)$ – Real (Kind=nag_wp) arrayInput: On entry: $y_{i}$ , for $i = 1, 2, \dots, neqf$ , the current value of the argument.
4: $f (neqf)$ – Real (Kind=nag_wp) arrayOutput: On exit: the value of $f_{i}$ , for $i = 1, 2, \dots, neqf$ .

fcn must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which d02qff is called. Arguments denoted as Input must not be changed by this procedure.

Note: fcn should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d02qff. If your code inadvertently does return any NaNs or infinities, d02qff is likely to produce unexpected results.

2: $neqf$ – IntegerInput

On entry: the number of first-order ordinary differential equations to be solved by d02qff. It must contain the same value as the argument neqf used in a prior call to d02qwf.

Constraint:

neqf \geq 1

3: $t$ – Real (Kind=nag_wp)Input/Output

On entry: after a call to d02qwf with

statef ='S'

(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)$ – Real (Kind=nag_wp) arrayInput/Output

On entry: the initial values of the solution

y_{1}, y_{2}, \dots, 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$ – Real (Kind=nag_wp)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$ – real (Kind=nag_wp) Function, supplied by the user.External Procedure

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 dummy routine d02qfz. (d02qfz is included in the NAG Library.)

The specification of g is:

Fortran Interface

Function g (

neqf, x, y, yp, k)

Real (Kind=nag_wp)	::	g
Integer, Intent (In)	::	neqf, k
Real (Kind=nag_wp), Intent (In)	::	x, y(neqf), yp(neqf)

C Header Interface

#include nagmk26.h

double

g ( const Integer *neqf, const double *x, const double y[], const double yp[], const Integer *k)

1: $neqf$ – IntegerInput: On entry: the number of differential equations being solved.
2: $x$ – Real (Kind=nag_wp)Input: On entry: the current value of the independent variable.
3: $y (neqf)$ – Real (Kind=nag_wp) arrayInput: On entry: the current values of the dependent variables.
4: $yp (neqf)$ – Real (Kind=nag_wp) arrayInput: On entry: the current values of the derivatives of the dependent variables.
5: $k$ – IntegerInput: On entry: the component of $g$ which must be evaluated.

g must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which d02qff is called. Arguments denoted as Input must not be changed by this procedure.

Note: g should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d02qff. If your code inadvertently does return any NaNs or infinities, d02qff is likely to produce unexpected results.

7: $neqg$ – IntegerInput

On 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

\leq 0

. Otherwise it must be the same argument neqg used in the prior call to d02qwf.

8: $root$ – LogicalOutput

On 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 d02qyf for further information.

If root-finding was not required (

neqg = 0

on entry), then on exit

root = .FALSE.

9: $rwork (lrwork)$ – Real (Kind=nag_wp) arrayCommunication Array

This must be the same argument rwork as supplied to d02qwf. It is used to pass information from d02qwf to d02qff, and from d02qff to d02qxf, d02qyf and d02qzf. Therefore the contents of this array must not be changed before the call to d02qff or calling any of the routines d02qxf, d02qyf and d02qzf.

10: $lrwork$ – IntegerInput

On entry: the dimension of the array rwork as declared in the (sub)program from which d02qff is called.

This must be the same argument lrwork as supplied to d02qwf.

11: $iwork (liwork)$ – Integer arrayCommunication Array

This must be the same argument iwork as supplied to d02qwf. It is used to pass information from d02qwf to d02qff, and from d02qff to d02qxf, d02qyf and d02qzf. Therefore the contents of this array must not be changed before the call to d02qff or calling any of the routines d02qxf, d02qyf and d02qzf.

12: $liwork$ – IntegerInput

On entry: the dimension of the array iwork as declared in the (sub)program from which d02qff is called.

This must be the same argument liwork as supplied to d02qwf.

13: $ifail$ – IntegerInput/Output

On entry: ifail must be set to

0

- 1 ​ or ​ 1

. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value

- 1 ​ or ​ 1

is recommended. If the output of error messages is undesirable, then the value

1

is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if

ifail \neq 0

on exit, the recommended value is

- 1

. When the value $- 1 or 1$ is used it is essential to test the value of ifail on exit.

On exit:

ifail = 0

unless the routine detects an error or a warning has been flagged (see Section 6).

6

Error Indicators and Warnings

If on entry

ifail = 0

- 1

, explanatory error messages are output on the current error message unit (as defined by x04aaf).

Errors or warnings detected by the routine:

$ifail = 1$: On entry, the integrator detected an illegal input, or d02qwf has not been called before the call to the integrator.
This error may be caused by overwriting elements of rwork and iwork.

$ifail = 2$: The maximum number of steps has been attempted (at a cost of about $2$ calls to fcn per step). (See argument maxstp in d02qwf.) If integration is to be continued then you need only reset ifail and call the routine again and a further maxstp steps will be attempted.

$ifail = 3$: The step size needed to satisfy the error requirements is too small for the machine precision being used. (See argument tolfac in d02qxf.)

$ifail = 4$: Some error weight $w_{i}$ became zero during the integration (see arguments vectol, rtol and atol in d02qwf.) Pure relative error control ( $atol = 0.0$ ) was requested on a variable (the $i$ th) which has now become zero. (See argument badcmp in d02qxf.) The integration was successful as far as t.

$ifail = 5$: 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 ifail and calling the routine again.

$ifail = 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 t rather than a root. Integration may be continued by resetting ifail and calling the routine again.

$ifail = 7$: The code has detected two successive error exits at the current value of t and cannot proceed. Check all input variables.

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.

$ifail = - 999$: Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

7

Accuracy

The accuracy of integration is determined by the arguments vectol, rtol and atol in a prior call to d02qwf. 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 d02qff 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 routine document for d02qwf.

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

d02qff is not thread safe and should not be called from a multithreaded user program. Please see Section 3.12.1 in How to Use the NAG Library and its Documentation for more information on thread safety.

d02qff is not threaded in any implementation.

9

Further Comments

If d02qff fails with

ifail = 3

then the combination of atol and rtol may be so small that a solution cannot be obtained, in which case the routine should be called again with larger values for rtol and/or atol (see d02qwf). If the accuracy requested is really needed then you should consider whether there is a more fundamental difficulty. For example:

(a)

in the region of a singularity the solution components will usually be of a large magnitude. d02qff 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;

(b)

for ‘stiff’ equations, where the solution contains rapidly decaying components, the routine 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

ifail = 3

, but usually an error exit with

ifail = 2

5

. The Adams' methods are not efficient in such cases and you should consider using a routine from the Sub-chapter D02M–N. A high proportion of failed steps (see argument nfail) may indicate stiffness but there may be other reasons for this phenomenon.

d02qff can be used for producing results at short intervals (for example, for graph plotting); you should set

crit = .TRUE.

and tcrit to the last output point required in a prior call to d02qwf and then set tout appropriately for each output point in turn in the call to d02qff.

10

Example

This example solves the equation

y^{''} = - y, y (0) = 0, y^{'} (0) = 1

reposed as

\begin{array}{l} y_{1}^{'} = y_{2} \\ y_{2}^{'} = - y_{1} \end{array}

over the range

[0, 10.0]

with initial conditions

y_{1} = 0.0

and

y_{2} = 1.0

using vector error control (

vectol = .TRUE.

) and computation of the solution at

tout = 10.0

with

tcrit = 10.0

(

crit = .TRUE.

). Also, we use d02qff to locate the positions where

y_{1} = 0.0

or where the first component has a turning-point, that is

y_{1}^{'} = 0.0

NAG Library Routine Document

d02qff (ivp_adams_roots)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

6

Error Indicators and Warnings

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

10.2

Program Data

10.3

Program Results