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_stiff_exp_fulljac (d02nb)

Purpose

nag_ode_ivp_stiff_exp_fulljac (d02nb) is a forward communication function for integrating stiff systems of explicit ordinary differential equations when the Jacobian is a full matrix.

Syntax

[t, y, ydot, rwork, inform, ysav, wkjac, ifail] = d02nb(t, tout, y, rwork, rtol, atol, itol, inform, fcn, ysav, jac, wkjac, monitr, itask, itrace, 'neq', neq, 'sdysav', sdysav)
[t, y, ydot, rwork, inform, ysav, wkjac, ifail] = nag_ode_ivp_stiff_exp_fulljac(t, tout, y, rwork, rtol, atol, itol, inform, fcn, ysav, jac, wkjac, monitr, itask, itrace, 'neq', neq, 'sdysav', sdysav)
Note: the interface to this routine has changed since earlier releases of the toolbox:
Mark 22: nwkjac has been removed from the interface; neq has been made optional
.

Description

nag_ode_ivp_stiff_exp_fulljac (d02nb) is a general purpose function for integrating the initial value problem for a stiff system of explicit ordinary differential equations,
y = g(t,y).
y=g(t,y).
It is designed specifically for the case where the Jacobian (g)/(y) g y  is a full matrix.
Both interval and step oriented modes of operation are available and also modes designed to permit intermediate output within an interval oriented mode.
An outline of a typical calling program for nag_ode_ivp_stiff_exp_fulljac (d02nb) is given below. It calls the full matrix linear algebra setup function nag_ode_ivp_stiff_fulljac_setup (d02ns), the Backward Differentiation Formula (BDF) integrator setup function nag_ode_ivp_stiff_bdf (d02nv), and its diagnostic counterpart nag_ode_ivp_stiff_integ_diag (d02ny).
.
.
.
[...] = d02nv(...);
[...] = d02ns(...);
[..., ifail] = d02nb(...);
if (ifail ~= 1 and ifail < 14) 
  [...] = d02ny(...);
end
.
.
.
The linear algebra setup function nag_ode_ivp_stiff_fulljac_setup (d02ns) and one of the integrator setup functions, nag_ode_ivp_stiff_bdf (d02nv) or nag_ode_ivp_stiff_blend (d02nw), must be called prior to the call of nag_ode_ivp_stiff_exp_fulljac (d02nb). The integrator diagnostic function nag_ode_ivp_stiff_integ_diag (d02ny) may be called after the call to nag_ode_ivp_stiff_exp_fulljac (d02nb). There is also a function, nag_ode_ivp_stiff_contin (d02nz), designed to permit you to change step size on a continuation call to nag_ode_ivp_stiff_exp_fulljac (d02nb) without restarting the integration process.

References

See the D02M–N sub-chapter Introduction.

Parameters

Compulsory Input Parameters

1:     t – double scalar
tt, the value of the independent variable. The input value of t is used only on the first call as the initial point of the integration.
2:     tout – double scalar
The next value of tt at which a computed solution is desired. For the initial tt, the input value of tout is used to determine the direction of integration. Integration is permitted in either direction (see also itask).
Constraint: toutttoutt.
3:     y(neq) – double array
neq, the dimension of the array, must satisfy the constraint neq1neq1.
The values of the dependent variables (solution). On the first call the first neq elements of y must contain the vector of initial values.
4:     rwork(50 + 4 × neq50+4×neq) – double array
5:     rtol( : :) – double array
Note: the dimension of the array rtol must be at least 11 if itol = 1itol=1 or 22, and at least neqneq otherwise.
The relative local error tolerance.
Constraint: rtol(i)0.0rtoli0.0 for all relevant ii (see itol).
6:     atol( : :) – double array
Note: the dimension of the array atol must be at least 11 if itol = 1itol=1 or 33, and at least neqneq otherwise.
The absolute local error tolerance.
Constraint: atol(i)0.0atoli0.0 for all relevant ii (see itol).
7:     itol – int64int32nag_int scalar
A value to indicate the form of the local error test. itol indicates to nag_ode_ivp_stiff_exp_fulljac (d02nb) whether to interpret either or both of rtol or atol as a vector or a scalar. The error test to be satisfied is ei / wi < 1.0ei/wi<1.0, where wiwi is defined as follows:
itol rtol atol wiwi
1 scalar scalar rtol(1) × |yi| + atol(1)rtol1×|yi|+atol1
2 scalar vector rtol(1) × |yi| + atol(i)rtol1×|yi|+atoli
3 vector scalar rtol(i) × |yi| + atol(1)rtoli×|yi|+atol1
4 vector vector rtol(i) × |yi| + atol(i)rtoli×|yi|+atoli
eiei is an estimate of the local error in yiyi, computed internally, and the choice of norm to be used is defined by a previous call to an integrator setup function.
Constraint: itol = 1itol=1, 22, 33 or 44.
8:     inform(2323) – int64int32nag_int array
9:     fcn – function handle or string containing name of m-file
fcn must evaluate the derivative vector for the explicit ordinary differential equation system, defined by y = g(t,y)y=g(t,y).
[f, ires] = fcn(neq, t, y, ires)

Input Parameters

1:     neq – int64int32nag_int scalar
The number of differential equations being solved.
2:     t – double scalar
tt, the current value of the independent variable.
3:     y(neq) – double array
The value of yiyi, for i = 1,2,,neqi=1,2,,neq.
4:     ires – int64int32nag_int scalar
ires = 1ires=1.

Output Parameters

1:     f(neq) – double array
The value yiyi, given by yi = gi(t,y)yi=gi(t,y), for i = 1,2,,neqi=1,2,,neq.
2:     ires – int64int32nag_int scalar
You may set ires as follows to indicate certain conditions in fcn to the integrator:
ires = 1ires=1
Indicates a normal return from fcn, that is ires has not been altered by you and integration continues.
ires = 2ires=2
Indicates to the integrator that control should be passed back immediately to the calling (sub)program with the error indicator set to ifail = 11ifail=11.
ires = 3ires=3
Indicates to the integrator that an error condition has occurred in the solution vector, its time derivative or in the value of tt. The integrator will use a smaller time step to try to avoid this condition. If this is not possible the integrator returns to the calling (sub)program with the error indicator set to ifail = 7ifail=7.
ires = 4ires=4
Indicates to the integrator to stop its current operation and to enter monitr immediately with parameter imon = 2imon=-2.
10:   ysav(ldysav,sdysav) – double array
ldysav, the first dimension of the array, must satisfy the constraint ldysavneqldysavneq.
An appropriate value for sdysav is described in the specification of the integrator setup functions nag_ode_ivp_stiff_bdf (d02nv) and nag_ode_ivp_stiff_blend (d02nw). This value must be the same as that supplied to the integrator setup function.
11:   jac – function handle or string containing name of m-file
jac must evaluate the Jacobian of the system. If this option is not required, the actual argument for jac must be the string 'd02nbz'. (nag_ode_ivp_stiff_exp_fulljac_dummy_jac (d02nbz) is included in the NAG Toolbox.) You must indicate to the integrator whether this option is to be used by setting the parameter jceval appropriately in a call to the full linear algebra setup function nag_ode_ivp_stiff_fulljac_setup (d02ns).
First we must define the system of nonlinear equations which is solved internally by the integrator. The time derivative, yy, generated internally, has the form
y = (yz) / (hd) ,
y = (y-z) / (hd) ,
where hh is the current step size and dd is a parameter that depends on the integration method in use. The vector yy is the current solution and the vector zz depends on information from previous time steps. This means that d/(dy) (​ ​) = (hd) d/(dy) (​ ​) d dy (​ ​) = (hd) d dy (​ ​) . The system of nonlinear equations that is solved has the form
y g (t,y) = 0
y - g (t,y) = 0
but it is solved in the form
r (t,y) = 0 ,
r (t,y) = 0 ,
where rr is the function defined by
r (t,y) = (hd) ( (yz) / (hd) g (t,y) ) .
r (t,y) =(hd) ( (y-z) / (hd) - g (t,y) ) .
It is the Jacobian matrix (r)/(y) r y  that you must supply in jac as follows:
(ri)/(yj) = 1(hd) (gi)/(yj) , if ​i = j,
(ri)/(yj) = (hd) (gi)/(yj) , otherwise.
ri yj =1-(hd) gi yj , if ​i=j, ri yj = -(hd) gi yj , otherwise.
[p] = jac(neq, t, y, h, d, p)

Input Parameters

1:     neq – int64int32nag_int scalar
The number of differential equations being solved.
2:     t – double scalar
tt, the current value of the independent variable.
3:     y(neq) – double array
yiyi, for i = 1,2,,neqi=1,2,,neq, the current solution component.
4:     h – double scalar
The current step size.
5:     d – double scalar
The parameter dd which depends on the integration method.
6:     p(neq,neq) – double array
Is set to zero.

Output Parameters

1:     p(neq,neq) – double array
p(i,j)pij must contain (ri)/(yj) ri yj , for i = 1,2,,neqi=1,2,,neq and j = 1,2,,neqj=1,2,,neq.
Only the nonzero elements of this array need be set, since it is preset to zero before the call to jac.
12:   wkjac(nwkjac) – double array
nwkjac, the dimension of the array, must satisfy the constraint nwkjacldysav × (ldysav + 1)nwkjacldysav×(ldysav+1).
This value must be the same as that supplied to the linear algebra setup function nag_ode_ivp_stiff_fulljac_setup (d02ns).
Constraint: nwkjacldysav × (ldysav + 1)nwkjacldysav×(ldysav+1).
13:   monitr – function handle or string containing name of m-file
monitr performs tasks requested by you. If this option is not required, then the actual argument for monitr must be the string 'd02nby'. (nag_ode_ivp_stiff_exp_fulljac_dummy_monit (d02nby) is included in the NAG Toolbox.)
[hnext, y, imon, inln, hmin, hmax] = monitr(neq, ldysav, t, hlast, hnext, y, ydot, ysav, r, acor, imon, hmin, hmax, nqu)

Input Parameters

1:     neq – int64int32nag_int scalar
The number of differential equations being solved.
2:     ldysav – int64int32nag_int scalar
An upper bound on the number of differential equations to be solved.
3:     t – double scalar
The current value of the independent variable.
4:     hlast – double scalar
The last step size successfully used by the integrator.
5:     hnext – double scalar
The step size that the integrator proposes to take on the next step.
6:     y(neq) – double array
yy, the values of the dependent variables evaluated at tt.
7:     ydot(neq) – double array
The time derivatives yy of the vector yy.
8:     ysav(ldysav,sdysavsdysav) – double array
Workspace to enable you to carry out interpolation using either of the functions nag_ode_ivp_stiff_nat_interp (d02xj) or nag_ode_ivp_stiff_c1_interp (d02xk).
9:     r(neq) – double array
If imon = 0imon=0 and inln = 3inln=3, the first neq elements contain the residual vector, yg(t,y)y-g(t,y).
10:   acor(neq,22) – double array
With imon = 1imon=1, acor(i,1)acori1 contains the weight used for the iith equation when the norm is evaluated, and acor(i,2)acori2 contains the estimated local error for the iith equation. The scaled local error at the end of a timestep may be obtained by calling the double function nag_ode_ivp_stiff_errest (d02za) as follows:
 [errloc, ifail] = d02za(acor(1:neq,2), acor(1:neq,1)); % Check ifail before proceeding 
11:   imon – int64int32nag_int scalar
A flag indicating under what circumstances monitr was called:
imon = 2imon=-2
Entry from the integrator after ires = 4ires=4 (set in fcn) caused an early termination (this facility could be used to locate discontinuities).
imon = 1imon=-1
The current step failed repeatedly.
imon = 0imon=0
Entry after a call to the internal nonlinear equation solver (see inln).
imon = 1imon=1
The current step was successful.
12:   hmin – double scalar
The minimum step size to be taken on the next step.
13:   hmax – double scalar
The maximum step size to be taken on the next step.
14:   nqu – int64int32nag_int scalar
The order of the integrator used on the last step. This is supplied to enable you to carry out interpolation using either of the functions nag_ode_ivp_stiff_nat_interp (d02xj) or nag_ode_ivp_stiff_c1_interp (d02xk).

Output Parameters

1:     hnext – double scalar
The next step size to be used. If this is different from the input value, then imon must be set to 44.
2:     y(neq) – double array
These values must not be changed unless imon is set to 22.
3:     imon – int64int32nag_int scalar
May be reset to determine subsequent action in nag_ode_ivp_stiff_exp_fulljac (d02nb).
imon = 2imon=-2
Integration is to be halted. A return will be made from the integrator to the calling (sub)program with ifail = 12ifail=12.
imon = 1imon=-1
Allow the integrator to continue with its own internal strategy. The integrator will try up to three restarts unless imon is set 1-1 on exit.
imon = 0imon=0
Return to the internal nonlinear equation solver, where the action taken is determined by the value of inln (see inln).
imon = 1imon=1
Normal exit to the integrator to continue integration.
imon = 2imon=2
Restart the integration at the current time point. The integrator will restart from order 11 when this option is used. The solution y, provided by monitr, will be used for the initial conditions.
imon = 3imon=3
Try to continue with the same step size and order as was to be used before the call to monitr. hmin and hmax may be altered if desired.
imon = 4imon=4
Continue the integration but using a new value of hnext and possibly new values of hmin and hmax.
4:     inln – int64int32nag_int scalar
The action to be taken by the internal nonlinear equation solver when monitr is exited with imon = 0imon=0. By setting inln = 3inln=3 and returning to the integrator, the residual vector is evaluated and placed in the array r, and then monitr is called again. At present this is the only option available: inln must not be set to any other value.
5:     hmin – double scalar
The minimum step size to be used. If this is different from the input value, then imon must be set to 33 or 44.
6:     hmax – double scalar
The maximum step size to be used. If this is different from the input value, then imon must be set to 33 or 44. If hmax is set to zero, no limit is assumed.
14:   itask – int64int32nag_int scalar
The task to be performed by the integrator.
itask = 1itask=1
Normal computation of output values of y(t)y(t) at t = toutt=tout (by overshooting and interpolating).
itask = 2itask=2
Take one step only and return.
itask = 3itask=3
Stop at the first internal integration point at or beyond t = toutt=tout and return.
itask = 4itask=4
Normal computation of output values of y(t)y(t) at t = toutt=tout but without overshooting t = tcritt=tcrit (e.g., see nag_ode_ivp_stiff_dassl (d02mv)). tcrit must be specified as an option in one of the integrator setup functions before the first call to the integrator, or specified in the optional input function before a continuation call. tcrit may be equal to or beyond tout, but not before it, in the direction of integration.
itask = 5itask=5
Take one step only and return, without passing tcrit (e.g., see nag_ode_ivp_stiff_dassl (d02mv)). tcrit must be specified as under itask = 4itask=4.
Constraint: itask = 1itask=1, 22, 33, 44 or 55.
15:   itrace – int64int32nag_int scalar
The level of output that is printed by the integrator. itrace may take the value 1-1, 00, 11, 22 or 33.
itrace < 1itrace<-1
1-1 is assumed and similarly if itrace > 3itrace>3, then 33 is assumed.
itrace = 1itrace=-1
No output is generated.
itrace = 0itrace=0
Only warning messages are printed on the current error message unit (see nag_file_set_unit_error (x04aa)).
itrace > 0itrace>0
Warning messages are printed as above, and on the current advisory message unit (see nag_file_set_unit_advisory (x04ab)) output is generated which details Jacobian entries, the nonlinear iteration and the time integration. The advisory messages are given in greater detail the larger the value of itrace.

Optional Input Parameters

1:     neq – int64int32nag_int scalar
Default: The dimension of the array y and the first dimension of the array ysav. (An error is raised if these dimensions are not equal.)
The number of differential equations to be solved.
Constraint: neq1neq1.
2:     sdysav – int64int32nag_int scalar
Default: The second dimension of the array ysav.
An appropriate value for sdysav is described in the specification of the integrator setup functions nag_ode_ivp_stiff_bdf (d02nv) and nag_ode_ivp_stiff_blend (d02nw). This value must be the same as that supplied to the integrator setup function.

Input Parameters Omitted from the MATLAB Interface

ldysav nwkjac

Output Parameters

1:     t – double scalar
The value at which the computed solution yy is returned (usually at tout).
2:     y(neq) – double array
The computed solution vector, evaluated at t (usually t = toutt=tout).
3:     ydot(neq) – double array
The time derivatives yy of the vector yy at the last integration point.
4:     rwork(50 + 4 × neq50+4×neq) – double array
5:     inform(2323) – int64int32nag_int array
6:     ysav(ldysav,sdysav) – double array
ldysav = neqldysav=neq.
Communication array, used to store information between calls to nag_ode_ivp_stiff_exp_fulljac (d02nb).
7:     wkjac(nwkjac) – double array
nwkjacldysav × (ldysav + 1)nwkjacldysav×(ldysav+1).
Communication array, used to store information between calls to nag_ode_ivp_stiff_exp_fulljac (d02nb).
8:     ifail – int64int32nag_int scalar
ifail = 0ifail=0 unless the function detects an error (see [Error Indicators and Warnings]).

Error Indicators and Warnings

Errors or warnings detected by the function:

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

  ifail = 1ifail=1
An illegal input was detected on entry, or after an internal call to monitr. If itrace > 1itrace>-1, then the form of the error will be detailed on the current error message unit (see nag_file_set_unit_error (x04aa)).
  ifail = 2ifail=2
The maximum number of steps specified has been taken (see the description of optional inputs in the integrator setup functions and the optional input continuation function, nag_ode_ivp_stiff_contin (d02nz)).
  ifail = 3ifail=3
With the given values of rtol and atol no further progress can be made across the integration range from the current point t. The components y(1),y(2),,y(neq)y1,y2,,yneq contain the computed values of the solution at the current point t.
W ifail = 4ifail=4
There were repeated error test failures on an attempted step, before completing the requested task, but the integration was successful as far as t. The problem may have a singularity, or the local error requirements may be inappropriate.
W ifail = 5ifail=5
There were repeated convergence test failures on an attempted step, before completing the requested task, but the integration was successful as far as t. This may be caused by an inaccurate Jacobian matrix or one which is incorrectly computed.
W ifail = 6ifail=6
Some error weight wiwi became zero during the integration (see the description of itol). Pure relative error control (atol(i) = 0.0atoli=0.0) was requested on a variable (the iith) which has now vanished. The integration was successful as far as t.
  ifail = 7ifail=7
fcn set its error flag (ires = 3ires=3) continually despite repeated attempts by the integrator to avoid this.
  ifail = 8ifail=8
Not used for this integrator.
  ifail = 9ifail=9
A singular Jacobian (r)/(y) r y  has been encountered. This error exit is unlikely to be taken when solving explicit ordinary differential equations. You should check the problem formulation and Jacobian calculation.
  ifail = 10ifail=10
An error occurred during Jacobian formulation or back-substitution (a more detailed error description may be directed to the current error message unit, see nag_file_set_unit_error (x04aa)).
W ifail = 11ifail=11
fcn signalled the integrator to halt the integration and return (ires = 2ires=2). Integration was successful as far as t.
W ifail = 12ifail=12
monitr set imon = 2imon=-2 and so forced a return but the integration was successful as far as t.
W ifail = 13ifail=13
The requested task has been completed, but it is estimated that a small change in rtol and atol is unlikely to produce any change in the computed solution. (Only applies when you are not operating in one step mode, that is when itask2itask2 or 55.)
  ifail = 14ifail=14
The values of rtol and atol are so small that nag_ode_ivp_stiff_exp_fulljac (d02nb) is unable to start the integration.
  ifail = 15ifail=15
The linear algebra setup function nag_ode_ivp_stiff_fulljac_setup (d02ns) was not called prior to calling nag_ode_ivp_stiff_exp_fulljac (d02nb).

Accuracy

The accuracy of the numerical solution may be controlled by a careful choice of the parameters rtol and atol, and to a much lesser extent by the choice of norm. You are advised to use scalar error control unless the components of the solution are expected to be poorly scaled. For the type of decaying solution typical of many stiff problems, relative error control with a small absolute error threshold will be most appropriate (that is, you are advised to choose itol = 1itol=1 with atol(1)atol1 small but positive).

Further Comments

The cost of computing a solution depends critically on the size of the differential system and to a lesser extent on the degree of stiffness of the problem. For nag_ode_ivp_stiff_exp_fulljac (d02nb) the cost is proportional to neq3neq3, though for problems which are only mildly nonlinear the cost may be dominated by factors proportional to neq2neq2 except for very large problems.
In general, you are advised to choose the Backward Differentiation Formula option (setup function nag_ode_ivp_stiff_bdf (d02nv)) but if efficiency is of great importance and especially if it is suspected that (g)/(y) g y  has complex eigenvalues near the imaginary axis for some part of the integration, you should try the BLEND option (setup function nag_ode_ivp_stiff_blend (d02nw)).

Example

This example solves the well-known stiff Robertson problem
a = 0.04a + 1.0E4bc
b = 0.04a 1.0E4bc 3.0E7b2
c = 3.0E7b2
a = -0.04a + 1.0E4bc b = 0.04a - 1.0E4bc - 3.0E7b2 c = 3.0E7b2
over the range [0,10][0,10] with initial conditions a = 1.0a=1.0 and b = c = 0.0b=c=0.0 using scalar error control (itol = 1itol=1) and computation of the solution at tout = 10.0tout=10.0 with tcrit (e.g., see nag_ode_ivp_stiff_dassl (d02mv)) set to 10.010.0 (itask = 4itask=4). nag_ode_ivp_stiff_exp_fulljac_dummy_monit (d02nby) is used for monitr, a BDF integrator (setup function nag_ode_ivp_stiff_bdf (d02nv)) is used and a modified Newton method is selected. This example illustrates the use of both a numerical and an analytical Jacobian.
function nag_ode_ivp_stiff_exp_fulljac_example
% Initialize variables and arrays.
neq = 3;
neqmax = neq;
nwkjac = neqmax*(neqmax+1);
maxord = 5;
sdysav = maxord + 1;
maxstp = 200;
mxhnil = 5;
const = zeros(1,sdysav);
h0 = 0.0;
hmax = 10.0;
hmin = 1.0e-10;
petzld = false;
inform = zeros(23, 1);
ysave = zeros(3, 6);
wkjac = zeros(12, 1);

fprintf('nag_ode_ivp_stiff_exp_fulljac example program results\n\n');

% First case. Integrate to tout without passing tout (set tcrit to
% tout and itask=4) using B.D.F formulae with a Newton method.
% Default values for the array const are used. Employ scalar
% tolerances and the Jacobian is evaluated internally.
t = 0.0;
tout = 10.0;
tcrit = tout;
itask = 4;
y = [1; 0; 0];
rwork = zeros(62,1);
rtol = [0.0001];
atol = [1e-07];
itol = 1;

% nag_ode_ivp_stiff_bdf is a setup routine to be called prior to nag_ode_ivp_stiff_exp_fulljac.
[const, rwork, ifail] = nag_ode_ivp_stiff_bdf(int64(neqmax), int64(sdysav), ...
    int64(maxord), 'Newton', petzld, const, tcrit, hmin, hmax, ...
    h0, int64(maxstp), int64(mxhnil), 'Average-L2', rwork);
if ifail ~= 0
    % Unsuccessful call.  Print message and exit.
    error('Warning: nag_ode_ivp_stiff_bdf returned with ifail = %1d ',ifail);
end

% nag_ode_ivp_stiff_fulljac_setup is a setup routine to be called prior to
% nag_ode_ivp_stiff_exp_fulljac.
[rwork, ifail] = ...
    nag_ode_ivp_stiff_fulljac_setup(int64(neq), int64(neqmax), 'Numerical', ...
    int64(nwkjac), rwork);

% Output initial results.
fprintf('  Numerical Jacobian\n\n');
fprintf('     X          Y(1)           Y(2)           Y(3)\n');
fprintf(' %8.3f      ', t);
fprintf('%1.5f        ',y);
fprintf('\n');

% Turn off tracing (set itrace to 1 to get trace) and call routine.
% The dummy routine nag_ode_ivp_stiff_exp_fulljac_dummy_jac is used because
% the Jacobian  is evaluated internally, while the dummy routine
% nag_ode_ivp_stiff_exp_fulljac_dummy_monit is used in place of the
% monitr routine.
itrace = 0;
[t, y, ydot, rwork, inform, ysave, wkjac, ifail] = ...
    nag_ode_ivp_stiff_exp_fulljac(t, tout, ...
    y, rwork, rtol, atol, int64(itol), int64(inform), @fcn, ...
    ysave, 'nag_ode_ivp_stiff_exp_fulljac_dummy_jac', wkjac, ...
    'nag_ode_ivp_stiff_exp_fulljac_dummy_monit', int64(itask), int64(itrace));
if ifail ~= 0
    % Unsuccessful call.  Print message and exit.
    error('Warning: nag_ode_ivp_stiff_exp_fulljac returned with ifail = %1d ',ifail);
end

% Output results.
fprintf(' %8.3f      ', t);
fprintf('%1.5f        ',y);
fprintf('\n');

% nag_ode_ivp_stiff_integ_diag is an integrator diagnostic routine
% which can be called after nag_ode_ivp_stiff_exp_fulljac.
[hu, h, tcur, tolsf, nst, nre, nje, nqu, nq, niter, imxer, algequ, ...
    ifail] = nag_ode_ivp_stiff_integ_diag(int64(neq), int64(neqmax), rwork, inform);

% Output diagnostics.
fprintf('\n hused = %1.5e   hnext = %1.5e   tcur = %1.5e\n',hu,h,tcur);
fprintf(' nst = %5d   nre = %5d     nje = %5d\n',nst,nre,nje);
fprintf(' nqu = %5d    nq = %5d   niter = %5d\n',nqu,nq,niter);
fprintf(' Max Err Comp = %1.0f  \n\n',imxer);

% Second case. integrate to tout without passing tout (set tcrit to tout
% and itask=4) using B.D.F formulae with a Newton method.  Default values
% for the array const are used. Employ scalar tolerances and the Jacobian
% is evaluated by jac.
t = 0.0;
y = [1; 0; 0];

[const, rwork, ifail] = nag_ode_ivp_stiff_bdf(int64(neqmax), int64(sdysav), ...
    int64(maxord), 'Newton', petzld, const, tcrit, hmin, hmax, ...
    h0, int64(maxstp), int64(mxhnil), 'Average-L2', rwork);
if ifail ~= 0
    error('Warning: nag_ode_ivp_stiff_bdf returned with ifail = %1d ',ifail);
end

[rwork, ifail] = ...
    nag_ode_ivp_stiff_fulljac_setup(int64(neq), int64(neqmax), 'Analytical', ...
    int64(nwkjac), rwork);

fprintf('  Analytic Jacobian\n\n');
fprintf('     X          Y(1)           Y(2)           Y(3)\n');
fprintf(' %8.3f      ', t);
fprintf('%1.5f        ',y);
fprintf('\n');

% jac evaluates Jacobian analytically.
itrace = 0; % set to 1 to get trace.
[t, y, ydot, rwork, inform, ysave, wkjac, ifail] = ...
    nag_ode_ivp_stiff_exp_fulljac(t, tout, ...
    y, rwork, rtol, atol, int64(itol), int64(inform), @fcn, ...
    ysave, @jac, wkjac, 'nag_ode_ivp_stiff_exp_fulljac_dummy_monit', ...
    int64(itask), int64(itrace));
if ifail ~= 0
    error('Warning: nag_ode_ivp_stiff_exp_fulljac returned with ifail = %1d ',ifail);
end

fprintf(' %8.3f      ', t);
fprintf('%1.5f        ',y);
fprintf('\n');

[hu, h, tcur, tolsf, nst, nre, nje, nqu, nq, niter, imxer, algequ, ifail] = ...
    nag_ode_ivp_stiff_integ_diag(int64(neq), int64(neqmax), rwork, inform);

fprintf('\n hused = %1.5e   hnext = %1.5e   tcur = %1.5e\n',hu,h,tcur);
fprintf(' nst = %5d   nre = %5d     nje = %5d\n',nst,nre,nje);
fprintf(' nqu = %5d    nq = %5d   niter = %5d\n',nqu,nq,niter);
fprintf(' Max Err Comp = %1.0f  \n\n',imxer);

% Now repeat the calculation with a larger number of points, and store
% the results for plotting.
nstep = 100;
itot = 10.0;
t = 0;
y = [1; 0; 0];
ncall = 1;
ykeep = y';
tkeep = t;
for j = 1:nstep
    if (j < 91)
        tout = exp(-0.26*(90-j))*(90*itot)/(nstep);
        tcrit = itot;
    else
        tout = (j*itot)/(nstep);
        tcrit = itot;
    end

    [const, rwork, ifail] = nag_ode_ivp_stiff_bdf(int64(neqmax), int64(sdysav), ...
        int64(maxord), 'Newton', petzld, const, tcrit, hmin, hmax, ...
        h0, int64(maxstp), int64(mxhnil), 'Average-L2', rwork);
    if ifail ~= 0
        error('Warning: nag_ode_ivp_stiff_bdf returned with ifail = %1d ',ifail);
    end

    [rwork, ifail] = ...
        nag_ode_ivp_stiff_fulljac_setup(int64(neq), int64(neqmax), ...
            'Numerical', int64(nwkjac), rwork);

    % Turn off warnings from NAG routines, because we'll handle these
    % ourselves.  Specifically, we'll ignore ifail=13 (task is complete,
    % but a small change in tolerance won't produce any change in the
    % computed solution).
    warning('off', 'NAG:warning');
    [t, y, ydot, rwork, inform, ysave, wkjac, ifail] = ...
            nag_ode_ivp_stiff_exp_fulljac(t, tout, ...
            y, rwork, rtol, atol, int64(itol), int64(inform), @fcn, ...
            ysave, 'nag_ode_ivp_stiff_exp_fulljac_dummy_jac', wkjac, ...
            'nag_ode_ivp_stiff_exp_fulljac_dummy_monit', int64(itask), int64(itrace));
    warning('on', 'NAG:warning');

    if ifail ~= 0
        if ifail ~= 13
            error(['Warning: nag_ode_ivp_stiff_exp_fulljac returned with ifail =  %1d and ', ...
                'T = %1.2e'], ifail, t);
        end
    end
    ncall = ncall + 1;
    tkeep(ncall) = t;
    ykeep(ncall,:) = y;

    [hu, h, tcur, tolsf, nst, nre, nje, nqu, nq, niter, imxer, algequ, ifail] = ...
    nag_ode_ivp_stiff_integ_diag(int64(neq), int64(neqmax), rwork, inform);
end
% Plot results.
fig = figure('Number', 'off');
display_plot(tkeep, ykeep)

function [f, ires] = fcn(neq, t, y, ires)
% Evaluate derivative vector.
f = zeros(3,1);
f(1) = -0.04d0*y(1) + 1.0d4*y(2)*y(3);
f(2) = 0.04d0*y(1) - 1.0d4*y(2)*y(3) - 3.0d7*y(2)*y(2);
f(3) = 3.0d7*y(2)*y(2);
function p = jac(neq, t, y, h, d, p)
% Evaluate the Jacobian.
p = zeros(neq, neq);
hxd = h*d;
p(1,1) = 1.0d0 - hxd*(-0.04d0);
p(1,2) = -hxd*(1.0d4*y(3));
p(1,3) = -hxd*(1.0d4*y(2));
p(2,1) = -hxd*(0.04d0);
p(2,2) = 1.0d0 - hxd*(-1.0d4*y(3)-6.0d7*y(2));
p(2,3) = -hxd*(-1.0d4*y(2));
p(3,2) = -hxd*(6.0d7*y(2));
p(3,3) = 1.0d0 - hxd*(0.0d0);
function display_plot(tkeep, ykeep)
% Formatting for title and axis labels.
titleFmt = {'FontName', 'Helvetica', 'FontWeight', 'Bold', 'FontSize', 14};
labFmt = {'FontName', 'Helvetica', 'FontWeight', 'Bold', 'FontSize', 13};
set(gca, 'FontSize', 13); % for legend, axis tick labels, etc.
% Plot one of the curves (semi-log) and then add the other two.
hline3 = semilogx(tkeep,ykeep(:,3));
hold on
[haxes, hline1, hline2] = plotyy(tkeep,ykeep(:,1), ...
    tkeep,ykeep(:,2), 'semilogx', 'semilogx');
% Set the axis limits and the tick specifications to beautify the plot.
set(haxes(1), 'YLim', [-0.05 1.2]);
set(haxes(1), 'XMinorTick', 'on', 'YMinorTick', 'on');
set(haxes(1), 'YTick', [0.0 0.2 0.4 0.6 0.8 1.0 1.2]);
set(haxes(2), 'YLim', [0.0 4e-5]);
set(haxes(2), 'YMinorTick', 'on');
set(haxes(2), 'YTick', [5.0e-6 1.0e-5 1.5e-5 2.0e-5 2.5e-5 3.0e-5 3.5e-5]);
for iaxis = 1:2
    % These properties must be the same for both sets of axes.
    set(haxes(iaxis), 'XLim', [0 12]);
    set(haxes(iaxis), 'XTick', [1.0e-9 1.0e-7 1.0e-5 1.0e-3 1.0e-1 10]);
    set(haxes(iaxis), 'FontSize', 13);
end
set(gca, 'box', 'off'); % so ticks aren't shown on opposite axes.
% Add title.
title(['Stiff Robertson Problem: BDF integrator, Full ', ...
    'Jacobian'], titleFmt{:});
% Label the x axis, and both y axes.
xlabel('x', labFmt{:});
ylabel(haxes(1),'Solution (a,c)', labFmt{:});
ylabel(haxes(2),'Solution (b)', labFmt{:});
% Add a legend.
legend('c','a','b','Location','Best');
% Set some features of the lines.
set(hline1, 'Marker', '+','Linestyle','-');
set(hline2, 'Marker', '*','Linestyle',':');
set(hline3, 'Marker', 'x','Linestyle','--');
 
nag_ode_ivp_stiff_exp_fulljac example program results

  Numerical Jacobian

     X          Y(1)           Y(2)           Y(3)
    0.000      1.00000        0.00000        0.00000        
   10.000      0.84136        0.00002        0.15863        

 hused = 5.18670e-01   hnext = 5.18670e-01   tcur = 1.00000e+01
 nst =    55   nre =   132     nje =    17
 nqu =     3    nq =     3   niter =    79
 Max Err Comp = 3  

  Analytic Jacobian

     X          Y(1)           Y(2)           Y(3)
    0.000      1.00000        0.00000        0.00000        
   10.000      0.84136        0.00002        0.15863        

 hused = 5.18670e-01   hnext = 5.18670e-01   tcur = 1.00000e+01
 nst =    55   nre =    81     nje =    17
 nqu =     3    nq =     3   niter =    79
 Max Err Comp = 3  


function d02nb_example
% Initialize variables and arrays.
neq = 3;
neqmax = neq;
nwkjac = neqmax*(neqmax+1);
maxord = 5;
sdysav = maxord + 1;
maxstp = 200;
mxhnil = 5;
const = zeros(1,sdysav);
h0 = 0.0;
hmax = 10.0;
hmin = 1.0e-10;
petzld = false;
inform = zeros(23, 1);
ysave = zeros(3, 6);
wkjac = zeros(12, 1);

fprintf('d02nb example program results\n\n');

% First case. Integrate to tout without passing tout (set tcrit to
% tout and itask=4) using B.D.F formulae with a Newton method.
% Default values for the array const are used. Employ scalar
% tolerances and the Jacobian is evaluated internally.
t = 0.0;
tout = 10.0;
tcrit = tout;
itask = 4;
y = [1; 0; 0];
rwork = zeros(62,1);
rtol = [0.0001];
atol = [1e-07];
itol = 1;

% d02nv is a setup routine to be called prior to d02nb.
[const, rwork, ifail] = d02nv(int64(neqmax), int64(sdysav), ...
    int64(maxord), 'Newton', petzld, const, tcrit, hmin, hmax, ...
    h0, int64(maxstp), int64(mxhnil), 'Average-L2', rwork);
if ifail ~= 0
    % Unsuccessful call.  Print message and exit.
    error('Warning: d02nv returned with ifail = %1d ',ifail);
end

% d02ns is a setup routine to be called prior to d02nb.
[rwork, ifail] = d02ns(int64(neq), int64(neqmax), 'Numerical', ...
    int64(nwkjac), rwork);

% Output initial results.
fprintf('  Numerical Jacobian\n\n');
fprintf('     X          Y(1)           Y(2)           Y(3)\n');
fprintf(' %8.3f      ', t);
fprintf('%1.5f        ',y);
fprintf('\n');

% Turn off tracing (set itrace to 1 to get trace) and call routine.  The
% dummy routine d02nbz is used because the Jacobian is evaluated
% internally, while the dummy routine d02nby is used in place of the
% monitr routine.
itrace = 0;
[t, y, ydot, rwork, inform, ysave, wkjac, ifail] = d02nb(t, tout, ...
    y, rwork, rtol, atol, int64(itol), int64(inform), @fcn, ...
    ysave, 'd02nbz', wkjac, 'd02nby', int64(itask), int64(itrace));
if ifail ~= 0
    % Unsuccessful call.  Print message and exit.
    error('Warning: d02nb returned with ifail = %1d ',ifail);
end

% Output results.
fprintf(' %8.3f      ', t);
fprintf('%1.5f        ',y);
fprintf('\n');

% d02ny is an integrator diagnostic routine which can be called after d02nb.
[hu, h, tcur, tolsf, nst, nre, nje, nqu, nq, niter, imxer, algequ, ...
    ifail] = d02ny(int64(neq), int64(neqmax), rwork, inform);

% Output diagnostics.
fprintf('\n hused = %1.5e   hnext = %1.5e   tcur = %1.5e\n',hu,h,tcur);
fprintf(' nst = %5d   nre = %5d     nje = %5d\n',nst,nre,nje);
fprintf(' nqu = %5d    nq = %5d   niter = %5d\n',nqu,nq,niter);
fprintf(' Max Err Comp = %1.0f  \n\n',imxer);

% Second case. integrate to tout without passing tout (set tcrit to tout
% and itask=4) using B.D.F formulae with a Newton method.  Default values
% for the array const are used. Employ scalar tolerances and the Jacobian
% is evaluated by jac.
t = 0.0;
y = [1; 0; 0];

[const, rwork, ifail] = d02nv(int64(neqmax), int64(sdysav), ...
    int64(maxord), 'Newton', petzld, const, tcrit, hmin, hmax, ...
    h0, int64(maxstp), int64(mxhnil), 'Average-L2', rwork);
if ifail ~= 0
    error('Warning: d02nv returned with ifail = %1d ',ifail);
end

[rwork, ifail] = d02ns(int64(neq), int64(neqmax), 'Analytical', ...
    int64(nwkjac), rwork);

fprintf('  Analytic Jacobian\n\n');
fprintf('     X          Y(1)           Y(2)           Y(3)\n');
fprintf(' %8.3f      ', t);
fprintf('%1.5f        ',y);
fprintf('\n');

% jac evaluates Jacobian analytically.
itrace = 0; % set to 1 to get trace.
[t, y, ydot, rwork, inform, ysave, wkjac, ifail] = d02nb(t, tout, ...
    y, rwork, rtol, atol, int64(itol), int64(inform), @fcn, ...
    ysave, @jac, wkjac, 'd02nby', int64(itask), int64(itrace));
if ifail ~= 0
    error('Warning: d02nb returned with ifail = %1d ',ifail);
end

fprintf(' %8.3f      ', t);
fprintf('%1.5f        ',y);
fprintf('\n');

[hu, h, tcur, tolsf, nst, nre, nje, nqu, nq, niter, imxer, algequ, ...
    ifail] = d02ny(int64(neq), int64(neqmax), rwork, inform);

fprintf('\n hused = %1.5e   hnext = %1.5e   tcur = %1.5e\n',hu,h,tcur);
fprintf(' nst = %5d   nre = %5d     nje = %5d\n',nst,nre,nje);
fprintf(' nqu = %5d    nq = %5d   niter = %5d\n',nqu,nq,niter);
fprintf(' Max Err Comp = %1.0f  \n\n',imxer);

% Now repeat the calculation with a larger number of points, and store
% the results for plotting.
nstep = 100;
itot = 10.0;
t = 0;
y = [1; 0; 0];
ncall = 1;
ykeep = y';
tkeep = t;
for j = 1:nstep
    if (j < 91)
        tout = exp(-0.26*(90-j))*(90*itot)/(nstep);
        tcrit = itot;
    else
        tout = (j*itot)/(nstep);
        tcrit = itot;
    end

    [const, rwork, ifail] = d02nv(int64(neqmax), int64(sdysav), ...
        int64(maxord), 'Newton', petzld, const, tcrit, hmin, hmax, ...
        h0, int64(maxstp), int64(mxhnil), 'Average-L2', rwork);
    if ifail ~= 0
        error('Warning: d02nv returned with ifail = %1d ',ifail);
    end

    [rwork, ifail] = d02ns(int64(neq), int64(neqmax), 'Numerical', ...
        int64(nwkjac), rwork);

    % Turn off warnings from NAG routines, because we'll handle these
    % ourselves.  Specifically, we'll ignore ifail=13 (task is complete,
    % but a small change in tolerance won't produce any change in the
    % computed solution).
    warning('off', 'NAG:warning');
    [t, y, ydot, rwork, inform, ysave, wkjac, ifail] = d02nb(t, tout, ...
        y, rwork, rtol, atol, int64(itol), int64(inform), @fcn, ...
        ysave, 'd02nbz', wkjac, 'd02nby', int64(itask), int64(itrace));
    warning('on', 'NAG:warning');

    if ifail ~= 0
        if ifail ~= 13
            error(['Warning: d02nb returned with ifail =  %1d and ', ...
                   'T = %1.2e\n'], ifail, t);
        end
    end
    ncall = ncall + 1;
    tkeep(ncall) = t;
    ykeep(ncall,:) = y;

    [hu, h, tcur, tolsf, nst, nre, nje, nqu, nq, niter, imxer, algequ, ...
        ifail] = d02ny(int64(neq), int64(neqmax), rwork, inform);
end
% Plot results.
fig = figure('Number', 'off');
display_plot(tkeep, ykeep)

function [f, ires] = fcn(neq, t, y, ires)
% Evaluate derivative vector.
f = zeros(3,1);
f(1) = -0.04d0*y(1) + 1.0d4*y(2)*y(3);
f(2) = 0.04d0*y(1) - 1.0d4*y(2)*y(3) - 3.0d7*y(2)*y(2);
f(3) = 3.0d7*y(2)*y(2);
function p = jac(neq, t, y, h, d, p)
% Evaluate the Jacobian.
p = zeros(neq, neq);
hxd = h*d;
p(1,1) = 1.0d0 - hxd*(-0.04d0);
p(1,2) = -hxd*(1.0d4*y(3));
p(1,3) = -hxd*(1.0d4*y(2));
p(2,1) = -hxd*(0.04d0);
p(2,2) = 1.0d0 - hxd*(-1.0d4*y(3)-6.0d7*y(2));
p(2,3) = -hxd*(-1.0d4*y(2));
p(3,2) = -hxd*(6.0d7*y(2));
p(3,3) = 1.0d0 - hxd*(0.0d0);
function display_plot(tkeep, ykeep)
% Formatting for title and axis labels.
titleFmt = {'FontName', 'Helvetica', 'FontWeight', 'Bold', 'FontSize', 14};
labFmt = {'FontName', 'Helvetica', 'FontWeight', 'Bold', 'FontSize', 13};
set(gca, 'FontSize', 13); % for legend, axis tick labels, etc.
% Plot one of the curves (semi-log) and then add the other two.
hline3 = semilogx(tkeep,ykeep(:,3));
hold on
[haxes, hline1, hline2] = plotyy(tkeep,ykeep(:,1), ...
    tkeep,ykeep(:,2), 'semilogx', 'semilogx');
% Set the axis limits and the tick specifications to beautify the plot.
set(haxes(1), 'YLim', [-0.05 1.2]);
set(haxes(1), 'XMinorTick', 'on', 'YMinorTick', 'on');
set(haxes(1), 'YTick', [0.0 0.2 0.4 0.6 0.8 1.0 1.2]);
set(haxes(2), 'YLim', [0.0 4e-5]);
set(haxes(2), 'YMinorTick', 'on');
set(haxes(2), 'YTick', [5.0e-6 1.0e-5 1.5e-5 2.0e-5 2.5e-5 3.0e-5 3.5e-5]);
for iaxis = 1:2
    % These properties must be the same for both sets of axes.
    set(haxes(iaxis), 'XLim', [0 12]);
    set(haxes(iaxis), 'XTick', [1.0e-9 1.0e-7 1.0e-5 1.0e-3 1.0e-1 10]);
    set(haxes(iaxis), 'FontSize', 13);
end
set(gca, 'box', 'off'); % so ticks aren't shown on opposite axes.
% Add title.
title(['Stiff Robertson Problem: BDF integrator, Full ', ...
    'Jacobian'], titleFmt{:});
% Label the x axis, and both y axes.
xlabel('x', labFmt{:});
ylabel(haxes(1),'Solution (a,c)', labFmt{:});
ylabel(haxes(2),'Solution (b)', labFmt{:});
% Add a legend.
legend('c','a','b','Location','Best');
% Set some features of the lines.
set(hline1, 'Marker', '+','Linestyle','-');
set(hline2, 'Marker', '*','Linestyle',':');
set(hline3, 'Marker', 'x','Linestyle','--');
 
d02nb example program results

  Numerical Jacobian

     X          Y(1)           Y(2)           Y(3)
    0.000      1.00000        0.00000        0.00000        
   10.000      0.84136        0.00002        0.15863        

 hused = 5.18670e-01   hnext = 5.18670e-01   tcur = 1.00000e+01
 nst =    55   nre =   132     nje =    17
 nqu =     3    nq =     3   niter =    79
 Max Err Comp = 3  

  Analytic Jacobian

     X          Y(1)           Y(2)           Y(3)
    0.000      1.00000        0.00000        0.00000        
   10.000      0.84136        0.00002        0.15863        

 hused = 5.18670e-01   hnext = 5.18670e-01   tcur = 1.00000e+01
 nst =    55   nre =    81     nje =    17
 nqu =     3    nq =     3   niter =    79
 Max Err Comp = 3  



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–2013