NAG Library Routine Document

D02LXF

1  Purpose

2  Specification

3  Description

4  References

5  Parameters

1:     $\mathrm{NEQ}$ – INTEGERInput

On entry: the number of second-order ordinary differential equations to be solved by D02LAF.

Constraint: $\mathbf{NEQ}\ge 1$.

2:     $\mathrm{H}$ – REAL (KIND=nag_wp)Input

On entry: if $\mathbf{START}=\mathrm{.TRUE.}$, H may specify an initial step size to be attempted in D02LAF.

If $\mathbf{START}=\mathrm{.FALSE.}$, H may specify a step size to override the choice of next step attempted made internally to D02LAF.

The sign of H is not important, as the absolute value of H is chosen and the appropriate sign is selected by D02LAF.

If this option is not required then you must set $\mathbf{H}=0.0$.

3:     $\mathrm{TOL}$ – REAL (KIND=nag_wp)Input

On entry: must be set to a relative tolerance for controlling the error in the integration by D02LAF. D02LAF has been designed so that, for most problems, a reduction in TOL leads to an approximately proportional reduction in the error in the solution. However the actual relation between TOL and the accuracy of the solution cannot be guaranteed. You are strongly recommended to repeat the integration with a smaller value of TOL and compare the results. See the description of THRES and THRESP for further details of how TOL is used.

Constraint: $10\times \epsilon \le \mathbf{TOL}\le 1.0$ ($\epsilon$ is the machine precision, see X02AJF).

4:     $\mathrm{THRES}\left(\mathbf{NEQ}\right)$ – REAL (KIND=nag_wp) arrayInput

5:     $\mathrm{THRESP}\left(\mathbf{NEQ}\right)$ – REAL (KIND=nag_wp) arrayInput

On entry: THRES and THRESP may be set to thresholds for use in the error control of D02LAF. At each step in the numerical integration estimates of the local errors $\mathrm{E1}\left(\mathit{i}\right)$ and $\mathrm{E2}\left(\mathit{i}\right)$ in the solution, $y_{\mathit{i}}$, and its derivative, $y_{\mathit{i}}^{\prime }$, respectively are computed, for $\mathit{i}=1,2,\dots ,\mathbf{NEQ}$. For the step to be accepted conditions of the following type must be satisfied:

$$\begin{array}{l}\underset{1\le i\le \mathbf{NEQ}}{\max }\left(\frac{\mathrm{E1}\left(i\right)}{\max \left(\mathbf{THRES}\left(i\right),\left|y_i\right|\right)}\right)\le \mathbf{TOL}\text{,}\\ \\ \\ \underset{1\le i\le \mathbf{NEQ}}{\max }\left(\frac{\mathrm{E2}\left(i\right)}{\max \left(\mathbf{THRESP}\left(i\right),\left|y_i^{\prime }\right|\right)}\right)\le \mathbf{TOL}\text{.}\end{array}$$

If one or both of these is not satisfied then the step size is reduced and the solution is recomputed.

If $\mathbf{THRES}\left(1\right)\le 0.0$ on entry, then a value of $50.0\times \epsilon$ is used for $\mathbf{THRES}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{NEQ}$, where $\epsilon$ is machine precision. Similarly for THRESP.

Constraints:

• $\mathbf{THRES}\left(1\right)\le 0.0$ or $\mathbf{THRES}\left(\mathit{i}\right)>0.0$, for $\mathit{i}=1,2,\dots ,\mathbf{NEQ}$;
• $\mathbf{THRESP}\left(1\right)\le 0.0$ or $\mathbf{THRESP}\left(\mathit{i}\right)>0.0$, for $\mathit{i}=1,2,\dots ,\mathbf{NEQ}$.

6:     $\mathrm{MAXSTP}$ – INTEGERInput

On entry: a bound on the number of steps attempted in any one call of D02LAF.

If $\mathbf{MAXSTP}\le 0$ on entry, a value of $1000$ is used.

7:     $\mathrm{START}$ – LOGICALInput/Output

On entry: specifies whether or not the call of D02LAF is for a new problem. $\mathbf{START}=\mathrm{.TRUE.}$ indicates that a new problem is to be solved. $\mathbf{START}=\mathrm{.FALSE.}$ indicates the call of D02LXF is prior to a continuation call of D02LAF.

On exit: $\mathbf{START}=\mathrm{.FALSE.}$.

8:     $\mathrm{ONESTP}$ – LOGICALInput

On entry: the mode of operation for D02LAF.

$\mathbf{ONESTP}=\mathrm{.TRUE.}$

D02LAF will operate in one-step mode, that is it will return after each successful step.

$\mathbf{ONESTP}=\mathrm{.FALSE.}$

D02LAF will operate in interval mode, that is it will return at the end of the integration interval.

9:     $\mathrm{HIGH}$ – LOGICALInput

On entry: if $\mathbf{HIGH}=\mathrm{.TRUE.}$, a high-order method will be used, whereas if $\mathbf{HIGH}=\mathrm{.FALSE.}$, a low-order method will be used. (See the specification of D02LAF for further details.)

10:   $\mathrm{RWORK}\left(\mathbf{LRWORK}\right)$ – REAL (KIND=nag_wp) arrayCommunication Array

This must be the same parameter RWORK supplied to D02LAF. It is used to pass information to D02LAF and therefore the contents of this array must not be changed before calling D02LAF.

11:   $\mathrm{LRWORK}$ – INTEGERInput

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

Constraints:

• if $\mathbf{HIGH}=\mathrm{.TRUE.}$, $\mathbf{LRWORK}\ge 16+20\times \mathbf{NEQ}$;
• if $\mathbf{HIGH}=\mathrm{.FALSE.}$, $\mathbf{LRWORK}\ge 16+11\times \mathbf{NEQ}$.

12:   $\mathrm{IFAIL}$ – INTEGERInput/Output

On entry: IFAIL must be set to $0$, $-1\text{ or }1$. If you are unfamiliar with this parameter you should refer to Section 3.3 in the Essential Introduction for details.

For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{ or }1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, if you are not familiar with this parameter, the recommended value is $0$. When the value $-\mathbf{1}\text{ or }\mathbf{1}$ is used it is essential to test the value of IFAIL on exit.

On exit: $\mathbf{IFAIL}=\mathbf{0}$ unless the routine detects an error or a warning has been flagged (see Section 6).

6  Error Indicators and Warnings

$\mathbf{IFAIL}=1$

$\mathbf{THRES}\left(1\right)>0.0$ and for some $i$ $\mathbf{THRES}\left(i\right)\le 0.0$, $1\le i\le \mathbf{NEQ}$, and/or, $\mathbf{THRESP}\left(1\right)>0.0$ and for some $i$ $\mathbf{THRESP}\left(i\right)\le 0.0$, $1\le i\le \mathbf{NEQ}$.

$\mathbf{IFAIL}=2$

LRWORK is too small.

$\mathbf{IFAIL}=3$

TOL does not satisfy $10\times \epsilon \le \mathbf{TOL}\le 1.0$ ($\epsilon$ is the machine precision, see X02AJF)

$\mathbf{IFAIL}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

See Section 3.8 in the Essential Introduction for further information.

$\mathbf{IFAIL}=-399$

Your licence key may have expired or may not have been installed correctly.

See Section 3.7 in the Essential Introduction for further information.

$\mathbf{IFAIL}=-999$

Dynamic memory allocation failed.

See Section 3.6 in the Essential Introduction for further information.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example