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_2nd_rkn_setup (d02lx)

## Purpose

nag_ode_ivp_2nd_rkn_setup (d02lx) is a setup function which must be called prior to the first call of the integrator nag_ode_ivp_2nd_rkn (d02la) and may be called prior to any continuation call to nag_ode_ivp_2nd_rkn (d02la).

## Syntax

[start, rwork, ifail] = d02lx(h, tol, thres, thresp, maxstp, start, onestp, high, rwork, 'neq', neq)
[start, rwork, ifail] = nag_ode_ivp_2nd_rkn_setup(h, tol, thres, thresp, maxstp, start, onestp, high, rwork, 'neq', neq)
Note: the interface to this routine has changed since earlier releases of the toolbox:
Mark 22: lrwork has been removed from the interface
.

## Description

nag_ode_ivp_2nd_rkn_setup (d02lx) permits you to set optional inputs prior to any call of nag_ode_ivp_2nd_rkn (d02la). It must be called before the first call of function nag_ode_ivp_2nd_rkn (d02la) and it may be called before any continuation call of function nag_ode_ivp_2nd_rkn (d02la).

None.

## Parameters

### Compulsory Input Parameters

1:     h – double scalar
If start = true${\mathbf{start}}=\mathbf{true}$, h may specify an initial step size to be attempted in nag_ode_ivp_2nd_rkn (d02la).
If start = false${\mathbf{start}}=\mathbf{false}$, h may specify a step size to override the choice of next step attempted made internally to nag_ode_ivp_2nd_rkn (d02la).
The sign of h is not important, as the absolute value of h is chosen and the appropriate sign is selected by nag_ode_ivp_2nd_rkn (d02la).
If this option is not required then you must set h = 0.0${\mathbf{h}}=0.0$.
2:     tol – double scalar
Must be set to a relative tolerance for controlling the error in the integration by nag_ode_ivp_2nd_rkn (d02la). nag_ode_ivp_2nd_rkn (d02la) has been designed so that, for most problems, a reduction in tol leads to an approximately proportional reduction in the error in the solution. However the actual relation between tol and the accuracy of the solution cannot be guaranteed. You are strongly recommended to repeat the integration with a smaller value of tol and compare the results. See the description of thres and thresp for further details of how tol is used.
Constraint: 10 × εtol1.0$10×\epsilon \le {\mathbf{tol}}\le 1.0$ (ε$\epsilon$ is the machine precision, see nag_machine_precision (x02aj)).
3:     thres(neq) – double array
4:     thresp(neq) – double array
neq, the dimension of the array, must satisfy the constraint neq1${\mathbf{neq}}\ge 1$.
thres and thresp may be set to thresholds for use in the error control of nag_ode_ivp_2nd_rkn (d02la). At each step in the numerical integration estimates of the local errors E1(i)$\mathrm{E1}\left(\mathit{i}\right)$ and E2(i)$\mathrm{E2}\left(\mathit{i}\right)$ in the solution, yi${y}_{\mathit{i}}$, and its derivative, yi${y}_{\mathit{i}}^{\prime }$, respectively are computed, for i = 1,2,,neq$\mathit{i}=1,2,\dots ,{\mathbf{neq}}$. For the step to be accepted conditions of the following type must be satisfied:
 max1 ≤ i ≤ neq  ((E1(i))/(max (thres(i),|yi|))) ≤ tol, max1 ≤ i ≤ neq  ((E2(i))/(max (thresp(i),|yi ′ |))) ≤ tol.
$max1≤i≤neq ( E1(i) max(thresi,|yi|) ) ≤ tol, max1≤i≤neq ( E2(i) max(threspi,|yi′|) ) ≤tol.$
If one or both of these is not satisfied then the step size is reduced and the solution is recomputed.
If thres(1)0.0${\mathbf{thres}}\left(1\right)\le 0.0$ on entry, then a value of 50.0 × ε$50.0×\epsilon$ is used for thres(i)${\mathbf{thres}}\left(\mathit{i}\right)$, for i = 1,2,,neq$\mathit{i}=1,2,\dots ,{\mathbf{neq}}$, where ε$\epsilon$ is machine precision. Similarly for thresp.
Constraints:
• thres(1)0.0${\mathbf{thres}}\left(1\right)\le 0.0$ or thres(i) > 0.0${\mathbf{thres}}\left(\mathit{i}\right)>0.0$, for i = 1,2,,neq$\mathit{i}=1,2,\dots ,{\mathbf{neq}}$;
• thresp(1)0.0${\mathbf{thresp}}\left(1\right)\le 0.0$ or thresp(i) > 0.0${\mathbf{thresp}}\left(\mathit{i}\right)>0.0$, for i = 1,2,,neq$\mathit{i}=1,2,\dots ,{\mathbf{neq}}$.
5:     maxstp – int64int32nag_int scalar
A bound on the number of steps attempted in any one call of nag_ode_ivp_2nd_rkn (d02la).
If maxstp0${\mathbf{maxstp}}\le 0$ on entry, a value of 1000$1000$ is used.
6:     start – logical scalar
Specifies whether or not the call of nag_ode_ivp_2nd_rkn (d02la) is for a new problem. start = true${\mathbf{start}}=\mathbf{true}$ indicates that a new problem is to be solved. start = false${\mathbf{start}}=\mathbf{false}$ indicates the call of nag_ode_ivp_2nd_rkn_setup (d02lx) is prior to a continuation call of nag_ode_ivp_2nd_rkn (d02la).
7:     onestp – logical scalar
The mode of operation for nag_ode_ivp_2nd_rkn (d02la).
onestp = true${\mathbf{onestp}}=\mathbf{true}$
nag_ode_ivp_2nd_rkn (d02la) will operate in one-step mode, that is it will return after each successful step.
onestp = false${\mathbf{onestp}}=\mathbf{false}$
nag_ode_ivp_2nd_rkn (d02la) will operate in interval mode, that is it will return at the end of the integration interval.
8:     high – logical scalar
If high = true${\mathbf{high}}=\mathbf{true}$, a high-order method will be used, whereas if high = false${\mathbf{high}}=\mathbf{false}$, a low-order method will be used. (See the specification of nag_ode_ivp_2nd_rkn (d02la) for further details.)
9:     rwork(lrwork) – double array
lrwork, the dimension of the array, must satisfy the constraint
• if high = true${\mathbf{high}}=\mathbf{true}$, lrwork16 + 20 × neq$\mathit{lrwork}\ge 16+20×{\mathbf{neq}}$;
• if high = false${\mathbf{high}}=\mathbf{false}$, lrwork16 + 11 × neq$\mathit{lrwork}\ge 16+11×{\mathbf{neq}}$.
This must be the same parameter rwork supplied to nag_ode_ivp_2nd_rkn (d02la). It is used to pass information to nag_ode_ivp_2nd_rkn (d02la) and therefore the contents of this array must not be changed before calling nag_ode_ivp_2nd_rkn (d02la).

### Optional Input Parameters

1:     neq – int64int32nag_int scalar
Default: The dimension of the arrays thres, thresp. (An error is raised if these dimensions are not equal.)
The number of second-order ordinary differential equations to be solved by nag_ode_ivp_2nd_rkn (d02la).
Constraint: neq1${\mathbf{neq}}\ge 1$.

lrwork

### Output Parameters

1:     start – logical scalar
start = false${\mathbf{start}}=\mathbf{false}$.
2:     rwork(lrwork) – double array
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$
thres(1) > 0.0${\mathbf{thres}}\left(1\right)>0.0$ and for some i$i$ thres(i)0.0${\mathbf{thres}}\left(i\right)\le 0.0$, 1ineq$1\le i\le {\mathbf{neq}}$, and/or, thresp(1) > 0.0${\mathbf{thresp}}\left(1\right)>0.0$ and for some i$i$ thresp(i)0.0${\mathbf{thresp}}\left(i\right)\le 0.0$, 1ineq$1\le i\le {\mathbf{neq}}$.
ifail = 2${\mathbf{ifail}}=2$
lrwork is too small.
ifail = 3${\mathbf{ifail}}=3$
tol does not satisfy 10 × εtol1.0$10×\epsilon \le {\mathbf{tol}}\le 1.0$ (ε$\epsilon$ is the machine precision, see nag_machine_precision (x02aj))

## Accuracy

Not applicable.

Prior to a continuation call of nag_ode_ivp_2nd_rkn (d02la), you may reset any of the optional parameters by calling nag_ode_ivp_2nd_rkn_setup (d02lx) with start = false${\mathbf{start}}=\mathbf{false}$. You may reset:
 h to override the internal step size selection; tol, thres, thresp to change the error requirements; maxstp to increase or decrease the number of steps attempted before an error exit is returned; onestp to change the mode of operation of nag_ode_ivp_2nd_rkn (d02la); high to change the order of the method being used.

## Example

```function nag_ode_ivp_2nd_rkn_setup_example
t = 0;
tend = 20;
y = [0.5;
0];
yp = [0;
1.732050807568877];
ydp = zeros(2, 1);
rwork = zeros(56,1);
[startOut, rwork, ifail] = ...
nag_ode_ivp_2nd_rkn_setup(0, 1e-4, zeros(2,1), zeros(2,1), int64(0), true, true, false, rwork);
[tOut, yOut, ypOut, ydpOut, rworkOut, ifail] = ...
nag_ode_ivp_2nd_rkn(@fcn, t, tend, y, yp, ydp, rwork)

function ydp = fcn(neq, t, y)
% Evaluate second derivatives.
r = sqrt(y(1)^2+y(2)^2)^3;
f = zeros(2,1);
ydp(1) = -y(1)/r;
ydp(2) = -y(2)/r;
```
```

tOut =

0.0624

yOut =

0.4923
0.1075

ypOut =

-0.2464
1.7054

ydpOut =

-3.8480
-0.8406

rworkOut =

1.0e+03 *

0.0001
0.0001
0.0001
0.0010
0
1.0000
0
0.0010
0
0
0.0020
0.0000
0.0000
0
0.0020
0.0560
0.0005
0
0
0.0017
-0.0040
0
-0.0002
0.0017
0.0000
0.0000
0.0000
0.0000
-0.0040
-0.0001
-0.0040
-0.0002
-0.0039
-0.0006
-0.0039
-0.0008
-0.0038
-0.0008
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0

ifail =

0

```
```function d02lx_example
t = 0;
tend = 20;
y = [0.5;
0];
yp = [0;
1.732050807568877];
ydp = zeros(2, 1);
rwork = zeros(56,1);
[startOut, rwork, ifail] = ...
d02lx(0, 1e-4, zeros(2,1), zeros(2,1), int64(0), true, true, false, rwork);
[tOut, yOut, ypOut, ydpOut, rworkOut, ifail] = ...
d02la(@fcn, t, tend, y, yp, ydp, rwork)

function ydp = fcn(neq, t, y)
% Evaluate second derivatives.
r = sqrt(y(1)^2+y(2)^2)^3;
f = zeros(2,1);
ydp(1) = -y(1)/r;
ydp(2) = -y(2)/r;
```
```

tOut =

0.0624

yOut =

0.4923
0.1075

ypOut =

-0.2464
1.7054

ydpOut =

-3.8480
-0.8406

rworkOut =

1.0e+03 *

0.0001
0.0001
0.0001
0.0010
0
1.0000
0
0.0010
0
0
0.0020
0.0000
0.0000
0
0.0020
0.0560
0.0005
0
0
0.0017
-0.0040
0
-0.0002
0.0017
0.0000
0.0000
0.0000
0.0000
-0.0040
-0.0001
-0.0040
-0.0002
-0.0039
-0.0006
-0.0039
-0.0008
-0.0038
-0.0008
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0

ifail =

0

```