NAG FL Interface
d02lxf (ivp_​2nd_​rkn_​setup)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{neq}$ – Integer Input

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

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

2: $\mathbf{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: $\mathbf{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: $\mathbf{thres}\left(\mathbf{neq}\right)$ – Real (Kind=nag_wp) array Input

5: $\mathbf{thresp}\left(\mathbf{neq}\right)$ – Real (Kind=nag_wp) array Input

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, 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: $\mathbf{maxstp}$ – Integer Input

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: $\mathbf{start}$ – Logical Input/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: $\mathbf{onestp}$ – Logical Input

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: $\mathbf{high}$ – Logical Input

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: $\mathbf{rwork}\left(\mathbf{lrwork}\right)$ – Real (Kind=nag_wp) array Communication Array

This must be the same argument 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: $\mathbf{lrwork}$ – Integer Input

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: $\mathbf{ifail}$ – Integer Input/Output

On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.

If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ 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$

On entry, $\mathbf{thres}\left(〈\mathit{\text{value}}〉\right)=〈\mathit{\text{value}}〉$ is not positive.

On entry, $\mathbf{thresp}\left(〈\mathit{\text{value}}〉\right)=〈\mathit{\text{value}}〉$ is not positive.

$\mathbf{ifail}=2$

On entry, $\mathbf{high}=\mathrm{.FALSE.}$ and $\mathbf{lrwork}=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{high}=\mathrm{.FALSE.}$ then $\mathbf{lrwork}\ge 〈\mathit{\text{value}}〉$.

On entry, $\mathbf{high}=\mathrm{.TRUE.}$ and $\mathbf{lrwork}=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{high}=\mathrm{.TRUE.}$ then $\mathbf{lrwork}\ge 〈\mathit{\text{value}}〉$.

On entry, $\mathbf{neq}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{neq}\ge 1$.

$\mathbf{ifail}=3$

On entry, $\mathbf{tol}=〈\mathit{\text{value}}〉$.
Constraint: $〈\mathit{\text{value}}〉<\mathbf{tol}<〈\mathit{\text{value}}〉$.

$\mathbf{ifail}=-99$

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

See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-399$

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

See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$\mathbf{ifail}=-999$

Dynamic memory allocation failed.

See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example