hide long namesshow long names
hide short namesshow short names
Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

NAG Toolbox: nag_ode_ivp_2nd_rkn_setup (d02lx)


    1  Purpose
    2  Syntax
    7  Accuracy
    9  Example


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).


[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:
At Mark 22: lrwork was removed from the interface


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).




Compulsory Input Parameters

1:     h – double scalar
If start=true, h may specify an initial step size to be attempted in nag_ode_ivp_2nd_rkn (d02la).
If start=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.
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 (ε is the machine precision, see nag_machine_precision (x02aj)).
3:     thresneq – double array
4:     threspneq – double array
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 E1i and E2i in the solution, yi, and its derivative, yi, respectively are computed, for i=1,2,,neq. For the step to be accepted conditions of the following type must be satisfied:
max1ineq E1i maxthresi,yi tol, max1ineq E2i maxthrespi,yi tol.  
If one or both of these is not satisfied then the step size is reduced and the solution is recomputed.
If thres10.0 on entry, then a value of 50.0×ε is used for thresi, for i=1,2,,neq, where ε is machine precision. Similarly for thresp.
  • thres10.0 or thresi>0.0, for i=1,2,,neq;
  • thresp10.0 or threspi>0.0, for i=1,2,,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 on entry, a value of 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 indicates that a new problem is to be solved. start=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).
nag_ode_ivp_2nd_rkn (d02la) will operate in one-step mode, that is it will return after each successful step.
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, a high-order method will be used, whereas if high=false, a low-order method will be used. (See the specification of nag_ode_ivp_2nd_rkn (d02la) for further details.)
9:     rworklrwork – double array
lrwork, the dimension of the array, must satisfy the constraint
  • if high=true, lrwork16+20×neq;
  • if high=false, lrwork16+11×neq.
This must be the same argument 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.

Output Parameters

1:     start – logical scalar
2:     rworklrwork – double array
3:     ifail int64int32nag_int scalar
ifail=0 unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

Errors or warnings detected by the function:
thres1>0.0 and for some i thresi0.0, 1ineq, and/or, thresp1>0.0 and for some i threspi0.0, 1ineq.
lrwork is too small.
tol does not satisfy 10×εtol1.0 (ε is the machine precision, see nag_machine_precision (x02aj))
An unexpected error has been triggered by this routine. Please contact NAG.
Your licence key may have expired or may not have been installed correctly.
Dynamic memory allocation failed.


Not applicable.

Further Comments

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


See Example in nag_ode_ivp_2nd_rkn (d02la).
function d02lx_example

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

neq     = 2;

% Parameters values for integrator setup
h       = 0;
reltol  = 1e-4;
thresh  = zeros(neq,1);
threshp = zeros(neq,1);
maxstp  = int64(0); 
start   = true;
onestp  = true;
high    = false;
rwork   = zeros(16+20*neq,1);

% Call setup
[start, rwork, ifail] = ...
    d02lx(h, reltol, thresh, threshp, maxstp, start, onestp, high, rwork);

% Initializations for integration
t     = 0;
tend  = 20;
y     = [0.5; 0];
yp    = [0; sqrt(3)];
ydp   = zeros(neq, 1);

% take one time-step towards tend
[t, y, yp, ydp, rwork, ifail] = d02la(@fcn, t, tend, y, yp, ydp, rwork);

fprintf('Solution at first time step, t = %6.3f:\n', t);
fprintf('    y   = %6.3f, %6.3f\n',y);
fprintf('    y''  = %6.3f, %6.3f\n',yp);
fprintf('    y'''' = %6.3f, %6.3f\n',ydp);

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;
d02lx example results

Solution at first time step, t =  0.062:
    y   =  0.492,  0.108
    y'  = -0.246,  1.705
    y'' = -3.848, -0.841

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015