NAG Toolbox: nag_ode_ivp_adams_setup (d02qw)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{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.

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

2:     $\mathrm{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 $\mathbf{statef}=\text{'C'}$ or $\text{'R'}$.

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

3:     $\mathrm{vectol}$ – logical scalar

Specifies whether vector or scalar error control is to be employed for the local error test in the integration.

If $\mathbf{vectol}=\mathit{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}=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	$w_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 nag_ode_ivp_adams_setup (d02qw) with $\mathbf{statef}=\text{'C'}$ or $\text{'R'}$.

4:     $\mathrm{atol}\left(\mathbf{latol}\right)$ – double array

The absolute local error tolerance (see vectol).

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

5:     $\mathrm{rtol}\left(\mathbf{lrtol}\right)$ – double array

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:     $\mathrm{onestp}$ – logical scalar

The mode of operation of the integration function. If $\mathbf{onestp}=\mathit{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:     $\mathrm{crit}$ – logical scalar

Specifies whether or not there is a value for the independent variable beyond which integration is not to be attempted. Setting $\mathbf{crit}=\mathit{true}$ indicates that there is such a point, whereas $\mathbf{crit}=\mathit{false}$ indicates that there is no such restriction.

8:     $\mathrm{tcrit}$ – double scalar

With $\mathbf{crit}=\mathit{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:     $\mathrm{hmax}$ – double scalar

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}=\mathit{true}$ is being used.

10:   $\mathrm{maxstp}$ – int64int32nag_int scalar

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

11:   $\mathrm{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).

$\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:   $\mathrm{alterg}$ – logical scalar

Specifies whether or not the event functions have been redefined. alterg need not be set if $\mathbf{statef}=\text{'S'}$. On subsequent calls to nag_ode_ivp_adams_setup (d02qw), if neqg has been set positive, then $\mathbf{alterg}=\mathit{false}$ specifies that the event functions remain unchanged, whereas $\mathbf{alterg}=\mathit{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:   $\mathrm{sophst}$ – logical scalar

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

14:   $\mathrm{rwork}\left(\mathit{lrwork}\right)$ – double array

lrwork, the dimension of the array, must satisfy the constraint $\mathit{lrwork}\ge 21\times \left(1+\mathbf{neqf}\right)+2\times \mathrm{j}+\mathrm{k}\times \mathbf{neqg}+2$, where

$$\mathrm{j}=\left\{\begin{array}{ll}\mathbf{neqf}& \text{if }\mathbf{vectol}=\mathit{true}\\ 1& \text{if }\mathbf{vectol}=\mathit{false}\end{array}\right.$$

and

$$\mathrm{k}=\left\{\begin{array}{ll}14& \text{if }\mathbf{sophst}=\mathit{true}\\ 5& \text{if }\mathbf{sophst}=\mathit{false}\end{array}\right.$$

.

This must be the same argument 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:   $\mathrm{iwork}\left(\mathit{liwork}\right)$ – int64int32nag_int array

liwork, the dimension of the array, must satisfy the constraint

• if $\mathbf{sophst}=\mathit{true}$, $\mathit{liwork}\ge 21+4\times \mathbf{neqg}$;
• if $\mathbf{sophst}=\mathit{false}$, $\mathit{liwork}\ge 21+\mathbf{neqg}$.

This must be the same argument 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:     $\mathrm{latol}$ – int64int32nag_int scalar

Default: the dimension of the array atol.

The dimension of the array atol.

Constraints:

• if $\mathbf{vectol}=\mathit{true}$, $\mathbf{latol}\ge \mathbf{neqf}$;
• if $\mathbf{vectol}=\mathit{false}$, $\mathbf{latol}\ge 1$.

2:     $\mathrm{lrtol}$ – int64int32nag_int scalar

Default: the dimension of the array rtol.

The dimension of the array rtol.

Constraints:

• if $\mathbf{vectol}=\mathit{true}$, $\mathbf{lrtol}\ge \mathbf{neqf}$;
• if $\mathbf{vectol}=\mathit{false}$, $\mathbf{lrtol}\ge 1$.

Output Parameters

1:     $\mathrm{statef}$ – string (length ≥ 1)

Is set to 'C', except that if an error is detected, statef is unchanged.

2:     $\mathrm{alterg}$ – logical scalar

Is set to false.

3:     $\mathrm{rwork}\left(\mathit{lrwork}\right)$ – double array

4:     $\mathrm{iwork}\left(\mathit{liwork}\right)$ – int64int32nag_int array

5:     $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

   $\mathbf{ifail}=1$

Illegal input detected.

   $\mathbf{ifail}=-99$

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

   $\mathbf{ifail}=-399$

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

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: d02qw_example

function d02qw_example


fprintf('d02qw example results\n\n');

% Initialize parameters for Adams method setup
neqf   = int64(2);
neqg   = int64(2);
vectol = true;
atol   = [1e-06;  1e-06];
rtol   = [0.0001; 0.0001];
onestp = false;
crit   = true;
tcrit  = 10;
hmax   = 0;
maxstp = int64(0);
lrwork = 23*(1+neqf) + 14*neqg;
alterg = false;
sophst = true;

lrwork = 23*(1+neqf) + 14*neqg;
rwork  = zeros(lrwork,1);
liwork = 21 + 4*neqg;
iwork  = zeros(liwork, 1, 'int64');

% Adams method setup
[statefOut, altergOut, rwork, iwork, ifail] = ...
  d02qw('Start', neqf, vectol, atol, rtol, onestp, crit, tcrit, hmax, ...
        maxstp, neqg, alterg, sophst, rwork, iwork);

% Adams method integration
t      = 0;
y      = [0; 1];
tout   = 10;
[t, y, root, rwork, iwork, ifail] = ...
  d02qf(@fcn, t, y, tout, @g, neqg, rwork, iwork);

% Display results.
fprintf('Solution and root functions at t = %7.4f is:\n',t);
fprintf('\n y :');
fprintf('%10.4f',y);
yp = fcn(neqf,t,y);
fprintf('\n y'':');
fprintf('%10.4f',yp);
fprintf('\n g :');
for i=1:neqg
  root = g(neqf,t,y,yp,i);
  fprintf('%10.4f',root);
end
fprintf('\n');



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)+0.5;
  else
    result = y(1)-sqrt(0.5);
  end

d02qw example results

Solution and root functions at t =  0.7854 is:

 y :    0.7071    0.7071
 y':    0.7071   -0.7071
 g :    1.2071    0.0000