NAG Library Function Document

nag_ode_ivp_adams_setup (d02qwc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:     state – Nag_Start *Input/Output

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

$\mathbf{state}=\mathrm{Nag\_NewStart}$

Start integration with a new differential system.

$\mathbf{state}=\mathrm{Nag\_ReStart}$

Restart integration with the current differential system.

$\mathbf{state}=\mathrm{Nag\_Continue}$

Continue integration with the current differential system.

Constraint: $\mathbf{state}=\mathrm{Nag\_NewStart}$, $\mathrm{Nag\_ReStart}$ or $\mathrm{Nag\_Continue}$.

On exit: state is set to $\mathrm{Nag\_Continue}$, except that if an error is detected, state is unchanged.

2:     neqf – IntegerInput

On entry: the number of ordinary differential equations to be solved by the integration function. neqf must remain unchanged on subsequent calls to nag_ode_ivp_adams_setup (d02qwc) with $\mathbf{state}=\mathrm{Nag\_Continue}$ or $\mathrm{Nag\_ReStart}$.

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

3:     vectol – Nag_BooleanInput

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{Nag\_TRUE}$, then 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}=0,1,\dots ,\mathbf{neqf}-1$. Otherwise scalar error control will be used and you must specify values of just $\mathbf{rtol}\left[0\right]$ and $\mathbf{atol}\left[0\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	$w_i$
Nag_TRUE	rtol$\left[i-1\right]\times \left|y_i\right|+\mathbf{atol}\left[i-1\right]$
Nag_FALSE	rtol$\left[0\right]\times \left|y_i\right|+\mathbf{atol}\left[0\right]$

and $e_i$ is an estimate of the local error in $y_i$, computed internally. vectol must remain unchanged on subsequent calls to nag_ode_ivp_adams_setup (d02qwc) with $\mathbf{state}=\mathrm{Nag\_Continue}$ or $\mathrm{Nag\_ReStart}$.

4:     atol[neqf] – const doubleInput

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

Constraint: $\mathbf{atol}\left[i\right]\ge 0.0$.

5:     rtol[neqf] – const doubleInput

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}$.

6:     one_step – Nag_BooleanInput

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

7:     crit – Nag_BooleanInput

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{Nag\_TRUE}$ indicates that there is such a point, whereas $\mathbf{crit}=\mathrm{Nag\_FALSE}$ indicates that there is no such restriction.

8:     tcrit – doubleInput

On entry: with $\mathbf{crit}=\mathrm{Nag\_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.

9:     hmax – doubleInput

On entry:

$\mathbf{hmax}\ne 0.0$

A bound on the absolute step size during the integration is taken to be $\left|\mathbf{hmax}\right|$.

$\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{Nag\_TRUE}$ is being used.

10:   max_step – IntegerInput

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

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

11:   neqg – IntegerInput

On entry: specifies whether or not root-finding is required in nag_ode_ivp_adams_roots (d02qfc).

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

12:   alter_g – Nag_Boolean *Input/Output

On entry: specifies whether or not the event functions have been redefined. alter_g need not be set if $\mathbf{state}=\mathrm{Nag\_NewStart}$. On subsequent calls to nag_ode_ivp_adams_setup (d02qwc), if neqg has been set positive, then $\mathbf{alter\_g}=\mathrm{Nag\_FALSE}$ specifies that the event functions remain unchanged, whereas $\mathbf{alter\_g}=\mathrm{Nag\_TRUE}$ specifies that the event functions have changed. Because of the expense in reinitializing the root searching procedure, alter_g should be set to Nag_TRUE only if the event functions really have been altered. alter_g need not be set if the root-finding option is not used.

On exit: alter_g is set to Nag_FALSE, except that if an error is detected, alter_g is unchanged.

13:   sophist – Nag_BooleanInput

On entry: the type of search technique to be used in the root-finding.

$\mathbf{sophist}=\mathrm{Nag\_TRUE}$

A sophisticated and reliable but expensive technique will be used, whereas for $\mathbf{sophist}=\mathrm{Nag\_FALSE}$ a simple but less reliable technique will be used.

$\mathbf{neqg}\le 0$

sophist is not referenced.

14:   opt – Nag_ODE_Adams *Output

On exit: the structure of type Nag_ODE_Adams will have been initialized to appropriate values for entry to the integration function nag_ode_ivp_adams_roots (d02qfc). opt must be passed unchanged to the integration function.

Memory will have been allocated by nag_ode_ivp_adams_setup (d02qwc) to several pointers within opt, this memory is used by the integration function nag_ode_ivp_adams_roots (d02qfc) and the interpolation function nag_ode_ivp_adams_interp (d02qzc). The library function nag_ode_ivp_adams_free (d02qyc) is provided so that this memory can be freed when all calls to nag_ode_ivp_adams_roots (d02qfc) and nag_ode_ivp_adams_interp (d02qzc) have been completed. A call to nag_ode_ivp_adams_free (d02qyc) may also be made prior to reentering nag_ode_ivp_adams_setup (d02qwc) with $\mathbf{state}=\mathrm{Nag\_NewStart}$.

15:   fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.

NE_BAD_PARAM

On entry, argument state had an illegal value.

NE_BOOL_NOT_SET

The Boolean argument crit has not been set to Nag_TRUE or Nag_FALSE.

NE_INT_ARG_LT

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

NE_NEQF_CHANGED

$\mathbf{state}=⟨\mathit{string}⟩$ but neqf has been changed. neqf was $⟨\mathit{\text{value}}⟩$ but is now $⟨\mathit{\text{value}}⟩$.

NE_NEQG_CHANGED

$\mathbf{alter\_g}=\mathrm{Nag\_FALSE}$ but neqg has been changed. neqg was $⟨\mathit{\text{value}}⟩$ but is now $⟨\mathit{\text{value}}⟩$.

NE_REAL_ARG_LT

On entry, $\mathbf{atol}\left[⟨\mathit{\text{value}}⟩\right]$ must not be less than 0.0: $\mathbf{atol}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$.

On entry, $\mathbf{rtol}\left[⟨\mathit{\text{value}}⟩\right]$ must not be less than 0.0: $\mathbf{rtol}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$.

NE_REAL_LT_COND

When $\mathbf{atol}\left[⟨\mathit{\text{value}}⟩\right]=0.0$, $\mathbf{rtol}\left[⟨\mathit{\text{value}}⟩\right]$ must not be less than $4\times \epsilon$. $\mathbf{rtol}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$, $4\times \epsilon =⟨\mathit{\text{value}}⟩$.

NE_STATE

$\mathbf{state}\ne \mathrm{Nag\_NewStart}$ on first call.

NE_VECTOL_CHANGED

$\mathbf{state}=⟨\mathit{string}⟩$ but vectol has been changed. vectol was $⟨\mathit{string}⟩$ but is now $⟨\mathit{string}⟩$.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example