NAG FL Interface
d02qwf (ivp_​adams_​setup)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{statef}$ – Character(1) Input/Output

On entry: specifies whether the integration routine (d02qff or d02qgf) is to start a new system of ordinary differential equations, restart a system or continue with a system.

$\mathbf{statef}=\text{'S'}$

Start integration with a new differential system.

$\mathbf{statef}=\text{'R'}$

Restart integration with the current differential system.

$\mathbf{statef}=\text{'C'}$

Continue integration with the current differential system.

Constraint: $\mathbf{statef}=\text{'S'}$, $\text{'R'}$ or $\text{'C'}$.

On exit: is set to 'C', except that if an error is detected, statef is unchanged.

2: $\mathbf{neqf}$ – Integer Input

On entry: the number of ordinary differential equations to be solved by the integration routine. neqf must remain unchanged on subsequent calls to d02qwf with $\mathbf{statef}=\text{'C'}$ or $\text{'R'}$.

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

3: $\mathbf{vectol}$ – Logical Input

On entry: specifies whether vector or scalar error control is to be employed for the local error test in the integration.

If $\mathbf{vectol}=\mathrm{.TRUE.}$, vector error control will be used and you must specify values of $\mathbf{rtol}\left(\mathit{i}\right)$ and $\mathbf{atol}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{neqf}$.

Otherwise scalar error control will be used and you must specify values of just $\mathbf{rtol}\left(1\right)$ and $\mathbf{atol}\left(1\right)$.

The error test to be satisfied is of the form

$$\sqrt{\sum _{i=1}^{\mathbf{neqf}}{\left(\frac{e_i}{w_i}\right)}^2}\le 1.0\text{.}$$

where $w_i$ is defined as follows:

vectol	${\mathit{w}}_{\mathit{i}}$
.TRUE.	$\mathbf{rtol}\left(i\right)\times \left|y_i\right|+\mathbf{atol}\left(i\right)$
.FALSE.	$\mathbf{rtol}\left(1\right)\times \left|y_i\right|+\mathbf{atol}\left(1\right)$

and $e_i$ is an estimate of the local error in $y_i$, computed internally. vectol must remain unchanged on subsequent calls to d02qwf with $\mathbf{statef}=\text{'C'}$ or $\text{'R'}$.

4: $\mathbf{atol}\left(\mathbf{latol}\right)$ – Real (Kind=nag_wp) array Input

On entry: the absolute local error tolerance (see vectol).

Constraint: $\mathbf{atol}\left(i\right)\ge 0.0$.

5: $\mathbf{latol}$ – Integer Input

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

Constraints:

• if $\mathbf{vectol}=\mathrm{.TRUE.}$, $\mathbf{latol}\ge \mathbf{neqf}$;
• if $\mathbf{vectol}=\mathrm{.FALSE.}$, $\mathbf{latol}\ge 1$.

6: $\mathbf{rtol}\left(\mathbf{lrtol}\right)$ – Real (Kind=nag_wp) array Input

On entry: the relative local error tolerance (see vectol).

Constraints:

• $\mathbf{rtol}\left(i\right)\ge 0.0$;
• if $\mathbf{atol}\left(i\right)=0.0$, $\mathbf{rtol}\left(i\right)\ge 4.0\times \mathit{machine precision}$.

7: $\mathbf{lrtol}$ – Integer Input

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

Constraints:

• if $\mathbf{vectol}=\mathrm{.TRUE.}$, $\mathbf{lrtol}\ge \mathbf{neqf}$;
• if $\mathbf{vectol}=\mathrm{.FALSE.}$, $\mathbf{lrtol}\ge 1$.

8: $\mathbf{onestp}$ – Logical Input

On entry: the mode of operation of the integration routine. If $\mathbf{onestp}=\mathrm{.TRUE.}$, the integration routine will operate in one-step mode, that is it will return after each successful step. Otherwise the integration routine will operate in interval mode, that is it will return at the end of the integration interval.

9: $\mathbf{crit}$ – Logical Input

On entry: specifies whether or not there is a value for the independent variable beyond which integration is not to be attempted. Setting $\mathbf{crit}=\mathrm{.TRUE.}$ indicates that there is such a point, whereas $\mathbf{crit}=\mathrm{.FALSE.}$ indicates that there is no such restriction.

10: $\mathbf{tcrit}$ – Real (Kind=nag_wp) Input

On entry: with $\mathbf{crit}=\mathrm{.TRUE.}$, tcrit must be set to a value of the independent variable beyond which integration is not to be attempted. Otherwise tcrit is not referenced.

11: $\mathbf{hmax}$ – Real (Kind=nag_wp) Input

On entry: if $\mathbf{hmax}\ne 0.0$, a bound on the absolute step size during the integration is taken to be $\left|\mathbf{hmax}\right|$.

If $\mathbf{hmax}=0.0$, no bound is assumed on the step size during the integration.

A bound may be required if there are features of the solution on very short ranges of integration which may be missed. You should try $\mathbf{hmax}=0.0$ first.

Note:  this argument only affects the step size if the option $\mathbf{crit}=\mathrm{.TRUE.}$ is being used.

12: $\mathbf{maxstp}$ – Integer Input

On entry: a bound on the number of attempted steps in any one call to the integration routine. If $\mathbf{maxstp}\le 0$ on entry, a value of $1000$ is used.

13: $\mathbf{neqg}$ – Integer Input

On entry: specifies whether or not root-finding is required in d02qff or d02qgf.

$\mathbf{neqg}\le 0$

No root-finding is attempted.

$\mathbf{neqg}>0$

Root-finding is required and neqg event functions will be specified for the integration routine.

14: $\mathbf{alterg}$ – Logical Input/Output

On entry: specifies whether or not the event functions have been redefined. alterg need not be set if $\mathbf{statef}=\text{'S'}$. On subsequent calls to d02qwf, if neqg has been set positive, $\mathbf{alterg}=\mathrm{.FALSE.}$ specifies that the event functions remain unchanged, whereas $\mathbf{alterg}=\mathrm{.TRUE.}$ specifies that the event functions have changed. Because of the expense in reinitializing the root searching procedure, alterg should be set to .TRUE. only if the event functions really have been altered. alterg need not be set if the root-finding option is not used.

On exit: is set to .FALSE..

15: $\mathbf{sophst}$ – Logical Input

On entry: the type of search technique to be used in the root-finding. If $\mathbf{sophst}=\mathrm{.TRUE.}$ then a sophisticated and reliable but expensive technique will be used, whereas for $\mathbf{sophst}=\mathrm{.FALSE.}$ a simple but less reliable technique will be used. If $\mathbf{neqg}\le 0$, sophst is not referenced.

16: $\mathbf{rwork}\left(\mathbf{lrwork}\right)$ – Real (Kind=nag_wp) array Communication Array

This must be the same argument rwork supplied to the integration routine. It is used to pass information to the integration routine and, therefore, the contents of this array must not be changed before calling the integration routine.

17: $\mathbf{lrwork}$ – Integer Input

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

Constraint: $\mathbf{lrwork}\ge 21\times (1+\mathbf{neqf})+2\times \mathit{J}+\mathit{K}\times \mathbf{neqg}+2$, where

$$\mathit{J}=\{\begin{array}{ll}\mathbf{neqf}& \text{if }\mathbf{vectol}=\mathrm{.TRUE.}\\ 1& \text{if }\mathbf{vectol}=\mathrm{.FALSE.}\end{array}$$

and

$$\mathit{K}=\{\begin{array}{ll}14& \text{if }\mathbf{sophst}=\mathrm{.TRUE.}\\ 5& \text{if }\mathbf{sophst}=\mathrm{.FALSE.}\text{.}\end{array}$$

18: $\mathbf{iwork}\left(\mathbf{liwork}\right)$ – Integer array Communication Array

This must be the same argument iwork supplied to the integration routine. It is used to pass information to the integration routine and, therefore, the contents of this array must not be changed before calling the integration routine.

19: $\mathbf{liwork}$ – Integer Input

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

Constraints:

• if $\mathbf{sophst}=\mathrm{.TRUE.}$, $\mathbf{liwork}\ge 21+4\times \mathbf{neqg}$;
• if $\mathbf{sophst}=\mathrm{.FALSE.}$, $\mathbf{liwork}\ge 21+\mathbf{neqg}$.

20: $\mathbf{ifail}$ – Integer Input/Output

On entry: ifail must be set to $0$, $\mathrm{-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 $\mathrm{-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 $\mathrm{-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{atol}\left(⟨\mathit{\text{value}}⟩\right)=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{atol}\left(i\right)\ge 0.0$ for all $i$.

On entry, for $i=⟨\mathit{\text{value}}⟩$, $\mathbf{atol}\left(i\right)=0.0$, $\mathbf{rtol}\left(i\right)=⟨\mathit{\text{value}}⟩$ and $4\times \mathrm{eps}=⟨\mathit{\text{value}}⟩$.
Constraint: if $\mathbf{atol}\left(\mathrm{i}\right)=0.0$ then $\mathbf{rtol}\left(i\right)\ge 4\times \mathrm{eps}$ for all $i$.

On entry, $\mathbf{latol}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{latol}\ge 1$.

On entry, $\mathbf{liwork}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{liwork}\ge ⟨\mathit{\text{value}}⟩$.

On entry, $\mathbf{lrtol}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{lrtol}\ge 1$.

On entry, $\mathbf{lrwork}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{lrwork}\ge ⟨\mathit{\text{value}}⟩$.

On entry, $\mathbf{neqf}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{neqf}\ge 1$.

On entry, $\mathbf{rtol}\left(⟨\mathit{\text{value}}⟩\right)=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{rtol}\left(i\right)\ge 0.0$ for all $i$.

On entry, $\mathbf{statef}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{statef}=\text{'S'}$, $\text{'R'}$ or $\text{'C'}$.

On entry, $\mathbf{statef}=\text{'R'}$ or $\text{'C'}$, $\mathbf{alterg}=\mathrm{.FALSE.}$ and $\mathbf{neqg}=⟨\mathit{\text{value}}⟩$.
Constraint: if $\mathbf{statef}=\text{'R'}$ or $\text{'C'}$ and $\mathbf{alterg}=\mathrm{.FALSE.}$ then neqg must retain its value from the prior call with $\mathbf{statef}=\text{'S'}$.

On entry, $\mathbf{statef}=\text{'R'}$ or $\text{'C'}$ and $\mathbf{neqf}=⟨\mathit{\text{value}}⟩$.
Constraint: if $\mathbf{statef}=\text{'R'}$ or $\text{'C'}$ then neqf must retain its value, $⟨\mathit{\text{value}}⟩$, from the prior call with $\mathbf{statef}=\text{'S'}$.

On entry, $\mathbf{statef}=\text{'R'}$ or $\text{'C'}$ and $\mathbf{vectol}=\mathrm{.FALSE.}$.
Constraint: if $\mathbf{statef}=\text{'R'}$ or $\text{'C'}$ then vectol must retain its value from the prior call with $\mathbf{statef}=\text{'S'}$.

On entry, $\mathbf{statef}=\text{'R'}$ or $\text{'C'}$ and $\mathbf{vectol}=\mathrm{.TRUE.}$.
Constraint: if $\mathbf{statef}=\text{'R'}$ or $\text{'C'}$ then vectol must retain its value from the prior call with $\mathbf{statef}=\text{'S'}$.

On entry, $\mathbf{vectol}=\mathrm{.TRUE.}$, $\mathbf{latol}=⟨\mathit{\text{value}}⟩$ and $\mathbf{neqf}=⟨\mathit{\text{value}}⟩$.
Constraint: if $\mathbf{vectol}=\mathrm{.TRUE.}$ then $\mathbf{latol}\ge \mathbf{neqf}$.

On entry, $\mathbf{vectol}=\mathrm{.TRUE.}$, $\mathbf{lrtol}=⟨\mathit{\text{value}}⟩$ and $\mathbf{neqf}=⟨\mathit{\text{value}}⟩$.
Constraint: if $\mathbf{vectol}=\mathrm{.TRUE.}$ then $\mathbf{lrtol}\ge \mathbf{neqf}$.

$\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