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

# NAG Toolbox: nag_ode_ivp_rkts_setup (d02pq)

## Purpose

nag_ode_ivp_rkts_setup (d02pq) is a setup function which must be called prior to the first call of either of the integration functions nag_ode_ivp_rkts_range (d02pe) and nag_ode_ivp_rkts_onestep (d02pf).

## Syntax

[iwsav, rwsav, ifail] = d02pq(tstart, tend, yinit, tol, thresh, method, 'n', n, 'hstart', hstart)
[iwsav, rwsav, ifail] = nag_ode_ivp_rkts_setup(tstart, tend, yinit, tol, thresh, method, 'n', n, 'hstart', hstart)

## Description

nag_ode_ivp_rkts_setup (d02pq) and its associated functions (nag_ode_ivp_rkts_range (d02pe), nag_ode_ivp_rkts_onestep (d02pf), nag_ode_ivp_rkts_reset_tend (d02pr), nag_ode_ivp_rkts_interp (d02ps), nag_ode_ivp_rkts_diag (d02pt) and nag_ode_ivp_rkts_errass (d02pu)) solve the initial value problem for a first-order system of ordinary differential equations. The functions, based on Runge–Kutta methods and derived from RKSUITE (see Brankin et al. (1991)), integrate
 y′ = f(t,y)  given  y(t0) = y0 $y′=f(t,y) given y(t0)=y0$
where y$y$ is the vector of n$n$ solution components and t$t$ is the independent variable.
The integration proceeds by steps from the initial point t0${t}_{0}$ towards the final point tf${t}_{f}$. An approximate solution y$y$ is computed at each step. For each component yi${y}_{\mathit{i}}$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,n$, the error made in the step, i.e., the local error, is estimated. The step size is chosen automatically so that the integration will proceed efficiently while keeping this local error estimate smaller than a tolerance that you specify by means of parameters tol and thresh.
nag_ode_ivp_rkts_range (d02pe) can be used to solve the ‘usual task’, namely integrating the system of differential equations to obtain answers at points you specify. nag_ode_ivp_rkts_onestep (d02pf) is used for all more ‘complicated tasks’.
You should consider carefully how you want the local error to be controlled. Essentially the code uses relative local error control, with tol being the desired relative accuracy. For reliable computation, the code must work with approximate solutions that have some correct digits, so there is an upper bound on the value used for tol. It is impossible to compute a numerical solution that is more accurate than the correctly rounded value of the true solution, so you are not allowed to specify tol too small for the precision you are using. The magnitude of the local error in yi${y}_{i}$ on any step will not be greater than tol × max (μi,thresh(i))${\mathbf{tol}}×\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mu }_{i},{\mathbf{thresh}}\left(i\right)\right)$ where μi${\mu }_{i}$ is an average magnitude of yi${y}_{i}$ over the step. If thresh(i)${\mathbf{thresh}}\left(i\right)$ is smaller than the current value of μi${\mu }_{i}$, this is a relative error test and tol indicates how many significant digits you want in yi${y}_{i}$. If thresh(i)${\mathbf{thresh}}\left(i\right)$ is larger than the current value of μi${\mu }_{i}$, this is an absolute error test with tolerance tol × thresh(i)${\mathbf{tol}}×{\mathbf{thresh}}\left(i\right)$. Relative error control is the recommended mode of operation, but pure relative error control, thresh(i) = 0.0${\mathbf{thresh}}\left(i\right)=0.0$, is not permitted. See Section [Further Comments] for further information about error control.
nag_ode_ivp_rkts_range (d02pe) and nag_ode_ivp_rkts_onestep (d02pf) control local error rather than the true (global) error, the difference between the numerical and true solution. Control of the local error controls the true error indirectly. Roughly speaking, the code produces a solution that satisfies the differential equation with a discrepancy bounded in magnitude by the error tolerance. What this implies about how close the numerical solution is to the true solution depends on the stability of the problem. Most practical problems are at least moderately stable, and the true error is then comparable to the error tolerance. To judge the accuracy of the numerical solution, you could reduce tol substantially, e.g., use 0.1 × tol$0.1×{\mathbf{tol}}$, and solve the problem again. This will usually result in a rather more accurate solution, and the true error of the first integration can be estimated by comparison. Alternatively, a global error assessment can be computed automatically using the parameter method. Because indirect control of the true error by controlling the local error is generally satisfactory and because both ways of assessing true errors cost twice, or more, the cost of the integration itself, such assessments are used mostly for spot checks, selecting appropriate tolerances for local error control, and exploratory computations.
nag_ode_ivp_rkts_range (d02pe) and nag_ode_ivp_rkts_onestep (d02pf) each implement three Runge–Kutta formula pairs, and you must select one for the integration. The best choice for method depends on the problem. The order of accuracy is 3$3$, 5$5$ and 8$8$ respectively. As a rule, the smaller tol is, the larger you should take the order of the method. If the components thresh are small enough that you are effectively specifying relative error control, experience suggests
 tol efficient method 10 − 2 − 10 − 4${10}^{-2}-{10}^{-4}$ order 2$2$ and 3$3$ pair 10 − 3 − 10 − 6${10}^{-3}-{10}^{-6}$ order 4$4$ and 5$5$ pair 10 − 5 − ${10}^{-5}-$ order 7$7$ and 8$8$ pair
The overlap in the ranges of tolerances appropriate for a given method merely reflects the dependence of efficiency on the problem being solved. Making tol smaller will normally make the integration more expensive. However, in the range of tolerances appropriate to a method, the increase in cost is modest. There are situations for which one method, or even this kind of code, is a poor choice. You should not specify a very small value for thresh(i)${\mathbf{thresh}}\left(i\right)$, when the i$i$th solution component might vanish. In particular, you should not do this when yi = 0.0${y}_{i}=0.0$. If you do, the code will have to work hard with any value for method to compute significant digits, but the lowest order method is a particularly poor choice in this situation. All three methods are inefficient when the problem is ‘stiff’. If it is only mildly stiff, you can solve it with acceptable efficiency with the order 2$2$ and 3$3$ pair, but if it is moderately or very stiff, a code designed specifically for such problems will be much more efficient. The higher the order the more smoothness is required of the solution in order for the method to be efficient.
When assessment of the true (global) error is requested, this error assessment is updated at each step. Its value can be obtained at any time by a call to nag_ode_ivp_rkts_errass (d02pu). The code monitors the computation of the global error assessment and reports any doubts it has about the reliability of the results. The assessment scheme requires some smoothness of f(t,y)$f\left(t,y\right)$, and it can be deceived if f$f$ is insufficiently smooth. At very crude tolerances the numerical solution can become so inaccurate that it is impossible to continue assessing the accuracy reliably. At very stringent tolerances the effects of finite precision arithmetic can make it impossible to assess the accuracy reliably. The cost of this is roughly twice the cost of the integration itself with the 5th and 8th order methods, and three times with the 3rd order method.
The first step of the integration is critical because it sets the scale of the problem. The integrator will find a starting step size automatically if you set the parameter hstart to 0.0$0.0$. Automatic selection of the first step is so effective that you should normally use it. Nevertheless, you might want to specify a trial value for the first step to be certain that the code recognizes the scale on which phenomena occur near the initial point. Also, automatic computation of the first step size involves some cost, so supplying a good value for this step size will result in a less expensive start. If you are confident that you have a good value, provide it via the parameter hstart.

## References

Brankin R W, Gladwell I and Shampine L F (1991) RKSUITE: A suite of Runge–Kutta codes for the initial value problems for ODEs SoftReport 91-S1 Southern Methodist University

## Parameters

### Compulsory Input Parameters

1:     tstart – double scalar
The initial value of the independent variable, t0${t}_{0}$.
2:     tend – double scalar
The final value of the independent variable, tf${t}_{f}$, at which the solution is required. tstart and tend together determine the direction of integration.
Constraint: tend${\mathbf{tend}}$ must be distinguishable from tstart for the method and the precision of the machine being used.
3:     yinit(n) – double array
n, the dimension of the array, must satisfy the constraint n1${\mathbf{n}}\ge 1$.
y0${y}_{0}$, the initial values of the solution, yi${y}_{\mathit{i}}$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,n$.
4:     tol – double scalar
A relative error tolerance. The actual tolerance used is max (10 × machine precision,min (tol,0.01)); that is, the minimum tolerance is set at 10$10$ times machine precision and the maximum tolerance is set at 0.01$0.01$.
5:     thresh(n) – double array
n, the dimension of the array, must satisfy the constraint n1${\mathbf{n}}\ge 1$.
A vector of thresholds. For the i$i$th component, the actual threshold used is max (sqrt(safe range),thresh(i))$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(\sqrt{\mathbf{safe range}},{\mathbf{thresh}}\left(i\right)\right)$, where safe range$\mathbf{safe range}$ is the value returned by nag_machine_real_safe (x02am).
6:     method – int64int32nag_int scalar
The Runge–Kutta method to be used.
method = 1${\mathbf{method}}=1$ or -1$-1$
A 2(3)$2\left(3\right)$ pair is used.
method = 2${\mathbf{method}}=2$ or -2$-2$
A 4(5)$4\left(5\right)$ pair is used.
method = 3${\mathbf{method}}=3$ or -3$-3$
A 7(8)$7\left(8\right)$ pair is used.
Constraint: method = 1${\mathbf{method}}=1$, -1$-1$, 2$2$, -2$-2$, 3$3$ or -3$-3$. Note: if method > 0${\mathbf{method}}>0$ then global error assessment is to be computed with the main integration; if method < 0${\mathbf{method}}<0$ then global error assessment will not be computed.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The dimension of the arrays yinit, thresh. (An error is raised if these dimensions are not equal.)
n$n$, the number of ordinary differential equations in the system to be solved by the integration function.
Constraint: n1${\mathbf{n}}\ge 1$.
2:     hstart – double scalar
A value for the size of the first step in the integration to be attempted. The absolute value of hstart is used with the direction being determined by tstart and tend. The actual first step taken by the integrator may be different to hstart if the underlying algorithm determines that hstart is unsuitable. If hstart = 0.0${\mathbf{hstart}}=0.0$ then the size of the first step is computed automatically.
Default: 0.0$0.0$

None.

### Output Parameters

1:     iwsav(130$130$) – int64int32nag_int array
2:     rwsav(32 × n + 350$32×{\mathbf{n}}+350$) – double array
The contents of the communication arrays must not be changed prior to calling one of the integration functions.
3:     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$
Constraint: method = -3${\mathbf{method}}=-3$, -2$-2$, -1$-1$, 1$1$, 2$2$ or 3$3$.
Constraint: n1${\mathbf{n}}\ge 1$.
Constraint: ${\mathbf{tstart}}\ne {\mathbf{tend}}$.
On entry, tstart is too close to tend.

## Accuracy

Not applicable.

If nag_ode_ivp_rkts_onestep (d02pf) is to be used for the integration then the value of the parameter tend may be reset during the integration without the overhead associated with a complete restart; this can be achieved by a call to nag_ode_ivp_rkts_reset_tend (d02pr).
It is often the case that a solution component yi${y}_{i}$ is of no interest when it is smaller in magnitude than a certain threshold. You can inform the code of this by setting thresh(i)${\mathbf{thresh}}\left(i\right)$ to this threshold. In this way you avoid the cost of computing significant digits in yi${y}_{i}$ when only the fact that it is smaller than the threshold is of interest. This matter is important when yi${y}_{i}$ vanishes, and in particular, when the initial value yinit(i)${\mathbf{yinit}}\left(i\right)$ vanishes. An appropriate threshold depends on the general size of yi${y}_{i}$ in the course of the integration. Physical reasoning may help you select suitable threshold values. If you do not know what to expect of y$y$, you can find out by a preliminary integration using nag_ode_ivp_rkts_range (d02pe) with nominal values of thresh. As nag_ode_ivp_rkts_range (d02pe) steps from t0${t}_{0}$ towards tf${t}_{f}$ for each i = 1,2,,n$i=1,2,\dots ,n$ it forms ymax(i)${\mathbf{ymax}}\left(i\right)$, the largest magnitude of yi${y}_{i}$ computed at any step in the integration so far. Using this you can determine more appropriate values for thresh for an accurate integration. You might, for example, take thresh(i)${\mathbf{thresh}}\left(i\right)$ to be 10 × machine precision times the final value of ymax(i)${\mathbf{ymax}}\left(i\right)$.

## Example

```function nag_ode_ivp_rkts_setup_example
% Set initial conditions and input
method = int64(1);
tstart = 0;
tend = 2*pi;
yinit = [0;1];
hstart = 0;
thresh = [1e-08; 1e-08];
npts = 40;
tol0 =  1.0E-3;
ygot = zeros(npts+1, 2);
tgot = zeros(npts+1, 1);
err1 = zeros(npts+1, 2);
err2 = zeros(npts+1, 2);
ymax = zeros(1, 2);

% Set control for output
tinc = (tend-tstart)/npts;
tol = 10.0*tol0;

% We run through the calculation twice with two tolerance values
for i = 1:2

tol = tol*0.1;

% Call setup function
[iwsav, rwsav, ifail] = ...
nag_ode_ivp_rkts_setup(tstart, tend, yinit, tol, thresh, method);

fprintf('\nCalculation with TOL = %8.1e\n\n', tol);
fprintf('    t         y1        y2       err1     err2\n');
fprintf(' %6.3f   %7.3f   %7.3f   %7.3f   %7.3f\n', tstart, yinit, 0, 0);

tgot(1) = tstart;
ygot(1,:) = yinit;
twant = tstart;
for j=1:npts
twant = twant + tinc;
[tgot(j+1), ygot(j+1,:), ypgot, ymax, user, iwsav, rwsav, ifail] = ...
nag_ode_ivp_rkts_range(@f, twant, ygot(j, :), ymax, iwsav, rwsav);

err1(j+1, i) =  ygot(j+1, 1)-sin(tgot(j+1));
err2(j+1, i) =  ygot(j+1, 2)-cos(tgot(j+1));

if rem(j, 5) == 0
fprintf(' %6.3f   %7.3f   %7.3f   %7.3f   %7.3f\n', tgot(j+1), ygot(j+1, :), err1(j+1, i), err2(j+1));
end
end

[fevals, stepcost, waste, stepsok, hnext, iwsav, ifail] = ...
nag_ode_ivp_rkts_diag(iwsav, rwsav);
fprintf('Cost of the integration in evaluations of f is %d\n', fevals);

end

% Plot results
fig = figure('Number', 'off');
title('First-order ODEs using Runge-Kutta Low-order Method using Two Tolerances');
hold on;
axis([0 10 -1.2 1.2]);
xlabel('t');
ylabel('Solution (y, y'')');
plot(tgot, ygot(:, 1), '-xr');
text(ceil(tgot(npts+1)), ygot(npts+1, 1)-0.2, 'y', 'Color', 'r');
plot(tgot, ygot(:, 2), '-xg');
text(ceil(tgot(npts+1)), ygot(npts+1, 2), 'y''', 'Color', 'g');
% Plot errors with a different (log) scale
ax1 = gca;
ax2 = axes('Position',get(ax1,'Position'),...
'XAxisLocation','bottom',...
'YAxisLocation','right',...
'YScale', 'log', ...
'Color','none',...
'XColor','k','YColor','k');
hold on;
axis([0 10 1e-7 0.01]);
ylabel('abs(Error)');
plot(ax2, tgot, abs(err1(:, 1)), '-*b');
text(ceil(tgot(npts+1)), err1(npts+1, 1), 'y-error (tol=0.001)', 'Color', 'b');
plot(ax2, tgot, abs(err1(:, 2)), '-sm');
text(ceil(tgot(npts+1)), err1(npts+1, 2), 'y-error (tol=0.0001)', 'Color', 'm');

function [yp, user] = f(t, n, y, user)
yp = [y(2); -y(1)];
```
```

Calculation with TOL =  1.0e-03

t         y1        y2       err1     err2
0.000     0.000     1.000     0.000     0.000
0.785     0.707     0.707    -0.000    -0.000
1.571     0.999    -0.000    -0.001    -0.000
2.356     0.706    -0.706    -0.001     0.001
3.142    -0.000    -0.998    -0.000     0.002
3.927    -0.706    -0.705     0.001     0.002
4.712    -0.998     0.001     0.002     0.001
5.498    -0.705     0.706     0.002    -0.002
6.283     0.001     0.997     0.001    -0.003
Cost of the integration in evaluations of f is 421

Calculation with TOL =  1.0e-04

t         y1        y2       err1     err2
0.000     0.000     1.000     0.000     0.000
0.785     0.707     0.707    -0.000    -0.000
1.571     1.000    -0.000    -0.000    -0.000
2.356     0.707    -0.707    -0.000     0.001
3.142    -0.000    -1.000    -0.000     0.002
3.927    -0.707    -0.707     0.000     0.002
4.712    -1.000     0.000     0.000     0.001
5.498    -0.707     0.707     0.000    -0.002
6.283     0.000     1.000     0.000    -0.003
Cost of the integration in evaluations of f is 871

```
```function d02pq_example
% Set initial conditions and input
method = int64(1);
tstart = 0;
tend = 2*pi;
yinit = [0;1];
hstart = 0;
thresh = [1e-08; 1e-08];
npts = 40;
tol0 =  1.0E-3;
ygot = zeros(npts+1, 2);
tgot = zeros(npts+1, 1);
err1 = zeros(npts+1, 2);
err2 = zeros(npts+1, 2);
ymax = zeros(1, 2);

% Set control for output
tinc = (tend-tstart)/npts;
tol = 10.0*tol0;

% We run through the calculation twice with two tolerance values
for i = 1:2

tol = tol*0.1;

% Call setup function
[iwsav, rwsav, ifail] = d02pq(tstart, tend, yinit, tol, thresh, method);

fprintf('\nCalculation with TOL = %8.1e\n\n', tol);
fprintf('    t         y1        y2       err1     err2\n');
fprintf(' %6.3f   %7.3f   %7.3f   %7.3f   %7.3f\n', tstart, yinit, 0, 0);

tgot(1) = tstart;
ygot(1,:) = yinit;
twant = tstart;
for j=1:npts
twant = twant + tinc;
[tgot(j+1), ygot(j+1,:), ypgot, ymax, user, iwsav, rwsav, ifail] = ...
d02pe(@f, twant, ygot(j, :), ymax, iwsav, rwsav);

err1(j+1, i) =  ygot(j+1, 1)-sin(tgot(j+1));
err2(j+1, i) =  ygot(j+1, 2)-cos(tgot(j+1));

if rem(j, 5) == 0
fprintf(' %6.3f   %7.3f   %7.3f   %7.3f   %7.3f\n', tgot(j+1), ygot(j+1, :), err1(j+1, i), err2(j+1));
end
end

[fevals, stepcost, waste, stepsok, hnext, iwsav, ifail] = d02pt(iwsav, rwsav);
fprintf('Cost of the integration in evaluations of f is %d\n', fevals);

end

% Plot results
fig = figure('Number', 'off');
title('First-order ODEs using Runge-Kutta Low-order Method using Two Tolerances');
hold on;
axis([0 10 -1.2 1.2]);
xlabel('t');
ylabel('Solution (y, y'')');
plot(tgot, ygot(:, 1), '-xr');
text(ceil(tgot(npts+1)), ygot(npts+1, 1)-0.2, 'y', 'Color', 'r');
plot(tgot, ygot(:, 2), '-xg');
text(ceil(tgot(npts+1)), ygot(npts+1, 2), 'y''', 'Color', 'g');
% Plot errors with a different (log) scale
ax1 = gca;
ax2 = axes('Position',get(ax1,'Position'),...
'XAxisLocation','bottom',...
'YAxisLocation','right',...
'YScale', 'log', ...
'Color','none',...
'XColor','k','YColor','k');
hold on;
axis([0 10 1e-7 0.01]);
ylabel('abs(Error)');
plot(ax2, tgot, abs(err1(:, 1)), '-*b');
text(ceil(tgot(npts+1)), err1(npts+1, 1), 'y-error (tol=0.001)', 'Color', 'b');
plot(ax2, tgot, abs(err1(:, 2)), '-sm');
text(ceil(tgot(npts+1)), err1(npts+1, 2), 'y-error (tol=0.0001)', 'Color', 'm');

function [yp, user] = f(t, n, y, user)
yp = [y(2); -y(1)];
```
```

Calculation with TOL =  1.0e-03

t         y1        y2       err1     err2
0.000     0.000     1.000     0.000     0.000
0.785     0.707     0.707    -0.000    -0.000
1.571     0.999    -0.000    -0.001    -0.000
2.356     0.706    -0.706    -0.001     0.001
3.142    -0.000    -0.998    -0.000     0.002
3.927    -0.706    -0.705     0.001     0.002
4.712    -0.998     0.001     0.002     0.001
5.498    -0.705     0.706     0.002    -0.002
6.283     0.001     0.997     0.001    -0.003
Cost of the integration in evaluations of f is 421

Calculation with TOL =  1.0e-04

t         y1        y2       err1     err2
0.000     0.000     1.000     0.000     0.000
0.785     0.707     0.707    -0.000    -0.000
1.571     1.000    -0.000    -0.000    -0.000
2.356     0.707    -0.707    -0.000     0.001
3.142    -0.000    -1.000    -0.000     0.002
3.927    -0.707    -0.707     0.000     0.002
4.712    -1.000     0.000     0.000     0.001
5.498    -0.707     0.707     0.000    -0.002
6.283     0.000     1.000     0.000    -0.003
Cost of the integration in evaluations of f is 871

```