Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

## Purpose

nag_ode_ivp_adams_setup (d02qw) is a setup function which must be called prior to the first call of either of the integrators nag_ode_ivp_adams_roots (d02qf) and nag_ode_ivp_adams_roots_revcom (d02qg) and may be called prior to any continuation call to these functions.

## Syntax

[statef, alterg, rwork, iwork, ifail] = d02qw(statef, neqf, vectol, atol, rtol, onestp, crit, tcrit, hmax, maxstp, neqg, alterg, sophst, rwork, iwork, 'latol', latol, 'lrtol', lrtol)
[statef, alterg, rwork, iwork, ifail] = nag_ode_ivp_adams_setup(statef, neqf, vectol, atol, rtol, onestp, crit, tcrit, hmax, maxstp, neqg, alterg, sophst, rwork, iwork, 'latol', latol, 'lrtol', lrtol)
Note: the interface to this routine has changed since earlier releases of the toolbox:
Mark 22: lrwork, liwork have been removed from the interface
.

## Description

nag_ode_ivp_adams_setup (d02qw) permits initialization of the integration method and setting of optional inputs prior to any call of nag_ode_ivp_adams_roots (d02qf) or nag_ode_ivp_adams_roots_revcom (d02qg). It must be called before the first call of either of the functions nag_ode_ivp_adams_roots (d02qf) or nag_ode_ivp_adams_roots_revcom (d02qg) and it may be called before any continuation call of either of the functions nag_ode_ivp_adams_roots (d02qf) or nag_ode_ivp_adams_roots_revcom (d02qg).

None.

## Parameters

### Compulsory Input Parameters

1:     statef – string (length ≥ 1)
Specifies whether the integration function (nag_ode_ivp_adams_roots (d02qf) or nag_ode_ivp_adams_roots_revcom (d02qg)) is to start a new system of ordinary differential equations, restart a system or continue with a system.
statef = 'S'${\mathbf{statef}}=\text{'S'}$
Start integration with a new differential system.
statef = 'R'${\mathbf{statef}}=\text{'R'}$
Restart integration with the current differential system.
statef = 'C'${\mathbf{statef}}=\text{'C'}$
Continue integration with the current differential system.
Constraint: statef = 'S'${\mathbf{statef}}=\text{'S'}$, 'R'$\text{'R'}$ or 'C'$\text{'C'}$.
2:     neqf – int64int32nag_int scalar
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 (d02qw) with statef = 'C'${\mathbf{statef}}=\text{'C'}$ or 'R'$\text{'R'}$.
Constraint: neqf1${\mathbf{neqf}}\ge 1$.
3:     vectol – logical scalar
Specifies whether vector or scalar error control is to be employed for the local error test in the integration.
If vectol = true${\mathbf{vectol}}=\mathbf{true}$, then vector error control will be used and you must specify values of rtol(i)${\mathbf{rtol}}\left(\mathit{i}\right)$ and atol(i)${\mathbf{atol}}\left(\mathit{i}\right)$, for i = 1,2,,neqf$\mathit{i}=1,2,\dots ,{\mathbf{neqf}}$.
Otherwise scalar error control will be used and you must specify values of just rtol(1)${\mathbf{rtol}}\left(1\right)$ and atol(1)${\mathbf{atol}}\left(1\right)$.
The error test to be satisfied is of the form
 sqrt( ∑ i = 1neqf ((ei)/(wi))2) ≤ 1.0. $∑i=1neqf (eiwi) 2≤1.0.$
where wi${w}_{i}$ is defined as follows:
 vectol wi${w}_{i}$ true rtol(i) × |yi| + atol(i)${\mathbf{rtol}}\left(i\right)×|{y}_{i}|+{\mathbf{atol}}\left(i\right)$ false rtol(1) × |yi| + atol(1)${\mathbf{rtol}}\left(1\right)×|{y}_{i}|+{\mathbf{atol}}\left(1\right)$
and ei${e}_{i}$ is an estimate of the local error in yi${y}_{i}$, computed internally. vectol must remain unchanged on subsequent calls to nag_ode_ivp_adams_setup (d02qw) with statef = 'C'${\mathbf{statef}}=\text{'C'}$ or 'R'$\text{'R'}$.
4:     atol(latol) – double array
latol, the dimension of the array, must satisfy the constraint
• if vectol = true${\mathbf{vectol}}=\mathbf{true}$, ${\mathbf{latol}}\ge {\mathbf{neqf}}$;
• if vectol = false${\mathbf{vectol}}=\mathbf{false}$, latol1${\mathbf{latol}}\ge 1$.
The absolute local error tolerance (see vectol).
Constraint: atol(i)0.0${\mathbf{atol}}\left(i\right)\ge 0.0$.
5:     rtol(lrtol) – double array
lrtol, the dimension of the array, must satisfy the constraint
• if vectol = true${\mathbf{vectol}}=\mathbf{true}$, ${\mathbf{lrtol}}\ge {\mathbf{neqf}}$;
• if vectol = false${\mathbf{vectol}}=\mathbf{false}$, lrtol1${\mathbf{lrtol}}\ge 1$.
The relative local error tolerance (see vectol).
Constraints:
• rtol(i)0.0${\mathbf{rtol}}\left(i\right)\ge 0.0$;
• if atol(i) = 0.0${\mathbf{atol}}\left(i\right)=0.0$, rtol(i)4.0 × machine precision.
6:     onestp – logical scalar
The mode of operation of the integration function. If onestp = true${\mathbf{onestp}}=\mathbf{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 – logical scalar
Specifies whether or not there is a value for the independent variable beyond which integration is not to be attempted. Setting crit = true${\mathbf{crit}}=\mathbf{true}$ indicates that there is such a point, whereas crit = false${\mathbf{crit}}=\mathbf{false}$ indicates that there is no such restriction.
8:     tcrit – double scalar
With crit = true${\mathbf{crit}}=\mathbf{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 – double scalar
If hmax0.0${\mathbf{hmax}}\ne 0.0$, a bound on the absolute step size during the integration is taken to be |hmax|$|{\mathbf{hmax}}|$.
If hmax = 0.0${\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 hmax = 0.0${\mathbf{hmax}}=0.0$ first.
Note:  this parameter only affects the step size if the option crit = true${\mathbf{crit}}=\mathbf{true}$ is being used.
10:   maxstp – int64int32nag_int scalar
A bound on the number of attempted steps in any one call to the integration function. If maxstp0${\mathbf{maxstp}}\le 0$ on entry, a value of 1000$1000$ is used.
11:   neqg – int64int32nag_int scalar
Specifies whether or not root-finding is required in nag_ode_ivp_adams_roots (d02qf) or nag_ode_ivp_adams_roots_revcom (d02qg).
neqg0${\mathbf{neqg}}\le 0$
No root-finding is attempted.
neqg > 0${\mathbf{neqg}}>0$
Root-finding is required and neqg event functions will be specified for the integration function.
12:   alterg – logical scalar
Specifies whether or not the event functions have been redefined. alterg need not be set if statef = 'S'${\mathbf{statef}}=\text{'S'}$. On subsequent calls to nag_ode_ivp_adams_setup (d02qw), if neqg has been set positive, then alterg = false${\mathbf{alterg}}=\mathbf{false}$ specifies that the event functions remain unchanged, whereas alterg = true${\mathbf{alterg}}=\mathbf{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.
13:   sophst – logical scalar
The type of search technique to be used in the root-finding. If sophst = true${\mathbf{sophst}}=\mathbf{true}$ then a sophisticated and reliable but expensive technique will be used, whereas for sophst = false${\mathbf{sophst}}=\mathbf{false}$ a simple but less reliable technique will be used. If neqg0${\mathbf{neqg}}\le 0$, sophst is not referenced.
14:   rwork(lrwork) – double array
lrwork, the dimension of the array, must satisfy the constraint lrwork21 × (1 + neqf) + 2 × j + k × neqg + 2$\mathit{lrwork}\ge 21×\left(1+{\mathbf{neqf}}\right)+2×\mathrm{j}+\mathrm{k}×{\mathbf{neqg}}+2$, where
j =
 { neqf if ​vectol = true 1 if ​vectol = false
$j={ neqf if ​vectol=true 1 if ​vectol=false$
and
k =
 { 14 if ​ sophst = true 5 if ​ sophst = false
$k={ 14 if ​ sophst=true 5 if ​ sophst=false$
.
This must be the same parameter rwork supplied to the integration function. It is used to pass information to the integration function and therefore the contents of this array must not be changed before calling the integration function.
15:   iwork(liwork) – int64int32nag_int array
liwork, the dimension of the array, must satisfy the constraint
• if sophst = true${\mathbf{sophst}}=\mathbf{true}$, liwork21 + 4 × neqg$\mathit{liwork}\ge 21+4×{\mathbf{neqg}}$;
• if sophst = false${\mathbf{sophst}}=\mathbf{false}$, liwork21 + neqg$\mathit{liwork}\ge 21+{\mathbf{neqg}}$.
This must be the same parameter iwork supplied to the integration function. It is used to pass information to the integration function and therefore the contents of this array must not be changed before calling the integration function.

### Optional Input Parameters

1:     latol – int64int32nag_int scalar
Default: The dimension of the array atol.
The dimension of the array atol as declared in the (sub)program from which nag_ode_ivp_adams_setup (d02qw) is called.
Constraints:
• if vectol = true${\mathbf{vectol}}=\mathbf{true}$, ${\mathbf{latol}}\ge {\mathbf{neqf}}$;
• if vectol = false${\mathbf{vectol}}=\mathbf{false}$, latol1${\mathbf{latol}}\ge 1$.
2:     lrtol – int64int32nag_int scalar
Default: The dimension of the array rtol.
The dimension of the array rtol as declared in the (sub)program from which nag_ode_ivp_adams_setup (d02qw) is called.
Constraints:
• if vectol = true${\mathbf{vectol}}=\mathbf{true}$, ${\mathbf{lrtol}}\ge {\mathbf{neqf}}$;
• if vectol = false${\mathbf{vectol}}=\mathbf{false}$, lrtol1${\mathbf{lrtol}}\ge 1$.

lrwork liwork

### Output Parameters

1:     statef – string (length ≥ 1)
Is set to 'C', except that if an error is detected, statef is unchanged.
2:     alterg – logical scalar
Is set to false.
3:     rwork(lrwork) – double array
4:     iwork(liwork) – int64int32nag_int array
5:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

## Error Indicators and Warnings

Errors or warnings detected by the function:
ifail = 1${\mathbf{ifail}}=1$
Illegal input detected.

## Accuracy

Not applicable.

Prior to a continuation call of the integration function, you may reset any of the optional parameters by calling nag_ode_ivp_adams_setup (d02qw) with statef = 'C'${\mathbf{statef}}=\text{'C'}$. You may reset:
 hmax to alter the maximum step size selection; rtol, atol to change the error requirements; maxstp to increase or decrease the number of attempted steps before an error exit is returned; onestp to change the operation mode of the integration function; crit, tcrit to alter the point beyond which integration must not be attempted; and neqg, alterg, sophst to alter the number and type of event functions, and also the search method.
If the behaviour of the system of differential equations has altered and you wish to restart the integration method from the value of t output from the integration function (see nag_ode_ivp_adams_roots (d02qf) and nag_ode_ivp_adams_roots_revcom (d02qg)), then statef should be set to statef = 'R'${\mathbf{statef}}=\text{'R'}$ and any of the optional parameters may be reset also. If you want to redefine the system of differential equations or start a new integration problem, then statef should be set to statef = 'S'${\mathbf{statef}}=\text{'S'}$. Resetting statef = 'R'${\mathbf{statef}}=\text{'R'}$ or 'S'$\text{'S'}$ on normal continuation calls causes a restart in the integration process, which is very inefficient when not needed.

## Example

t = 0;
y = [0;
1];
tout = 10;
neqg = int64(2);
rwork = zeros(97,1);
iwork = zeros(29,1,'int64');
[statefOut, altergOut, rwork, iwork, ifail] = ...
nag_ode_ivp_adams_setup('S', int64(2), true, [1e-06;1e-06], [0.0001; 0.0001], false, true, ...
10, 0, int64(0), int64(2), false, true, rwork, iwork);
[tOut, yOut, root, rworkOut, iworkOut, ifail] = ...
nag_ode_ivp_adams_roots(@fcn, t, y, tout, @g, neqg, rwork, iwork)

function f = fcn(neqf, x, y)
f=zeros(neqf,1);
f(1)=y(2);
f(2)=-y(1);
function result = g(neqf, x, y, yp, k)
if (k == 1)
result = yp(1);
else
result = y(1);
end

tOut =

0

yOut =

0
1

root =

1

rworkOut =

1.0e+153 *

0.0000
0
0
0
0
0
0
0
0
0
0
0.0000
0
0
0
0
0
0
0
0
0.0000
0
0.0000
0
0
0.0000
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0.0000
0.0000
0.0000
0.0000
0.0000
0
0
0
0.0000
0
0
0
6.7039
0
6.7039
6.7039
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0

iworkOut =

2
2
0
0
1
97
29
1
1
1
2
1
0
0
1
0
1000
0
0
0
0
2
0
0
0
0
0
0
0

ifail =

0

function d02qw_example
t = 0;
y = [0;
1];
tout = 10;
neqg = int64(2);
rwork = zeros(97,1);
iwork = zeros(29,1,'int64');
[statefOut, altergOut, rwork, iwork, ifail] = ...
d02qw('S', int64(2), true, [1e-06;1e-06], [0.0001; 0.0001], false, true, ...
10, 0, int64(0), int64(2), false, true, rwork, iwork);
[tOut, yOut, root, rworkOut, iworkOut, ifail] = ...
d02qf(@fcn, t, y, tout, @g, neqg, rwork, iwork)

function f = fcn(neqf, x, y)
f=zeros(neqf,1);
f(1)=y(2);
f(2)=-y(1);
function result = g(neqf, x, y, yp, k)
if (k == 1)
result = yp(1);
else
result = y(1);
end

tOut =

0

yOut =

0
1

root =

1

rworkOut =

1.0e+153 *

0.0000
0
0
0
0
0
0
0
0
0
0
0.0000
0
0
0
0
0
0
0
0
0.0000
0
0.0000
0
0
0.0000
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0.0000
0.0000
0.0000
0.0000
0.0000
0
0
0
0.0000
0
0
0
6.7039
0
6.7039
6.7039
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0

iworkOut =

2
2
0
0
1
97
29
1
1
1
2
1
0
0
1
0
1000
0
0
0
0
2
0
0
0
0
0
0
0

ifail =

0