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_imp_sparjac (d02nj)

 Contents

    1  Purpose
    2  Syntax
    7  Accuracy
    9  Example

Purpose

nag_ode_ivp_stiff_imp_sparjac (d02nj) is a forward communication function for integrating stiff systems of implicit ordinary differential equations coupled with algebraic equations when the Jacobian is a sparse matrix.

Syntax

[t, tout, y, ydot, rwork, inform, ysav, wkjac, jacpvt, lderiv, ifail] = d02nj(t, tout, y, ydot, rwork, rtol, atol, itol, inform, resid, ysav, jac, wkjac, jacpvt, monitr, lderiv, itask, itrace, 'neq', neq, 'sdysav', sdysav)
[t, tout, y, ydot, rwork, inform, ysav, wkjac, jacpvt, lderiv, ifail] = nag_ode_ivp_stiff_imp_sparjac(t, tout, y, ydot, rwork, rtol, atol, itol, inform, resid, ysav, jac, wkjac, jacpvt, monitr, lderiv, itask, itrace, 'neq', neq, 'sdysav', sdysav)
Note: the interface to this routine has changed since earlier releases of the toolbox:
At Mark 22: nwkjac and njcpvt were removed from the interface; neq was made optional

Description

nag_ode_ivp_stiff_imp_sparjac (d02nj) is a general purpose function for integrating the initial value problem for a stiff system of implicit ordinary differential equations coupled with algebraic equations, written in the form
At,yy=gt,y.  
It is designed specifically for the case where the resulting Jacobian is a sparse matrix (see the description of jac).
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_imp_sparjac (d02nj) is given below. It calls the sparse matrix linear algebra setup function nag_ode_ivp_stiff_sparjac_setup (d02nu), the Backward Differentiation Formula (BDF) integrator setup function nag_ode_ivp_stiff_bdf (d02nv), its diagnostic counterpart nag_ode_ivp_stiff_integ_diag (d02ny), and the sparse matrix linear algebra diagnostic function nag_ode_ivp_stiff_sparjac_diag (d02nx).
.
.
.
[...] = d02nv(...);
[...] = d02nu(...);
[..., ifail] = d02nj(...);
if (ifail ~= 1 and ifail < 14) 
  [...] = d02nx(...);
  [...] = d02ny(...);
end
.
.
.
The linear algebra setup function nag_ode_ivp_stiff_sparjac_setup (d02nu) and one of the integrator setup functions, nag_ode_ivp_stiff_dassl (d02mv), 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_imp_sparjac (d02nj). Either or both of the integrator diagnostic function nag_ode_ivp_stiff_integ_diag (d02ny), or the sparse matrix linear algebra diagnostic function nag_ode_ivp_stiff_sparjac_diag (d02nx), may be called after the call to nag_ode_ivp_stiff_imp_sparjac (d02nj). 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_imp_sparjac (d02nj) without restarting the integration process.

References

See the D02M–N Sub-chapter Introduction.

Parameters

Compulsory Input Parameters

1:     t – double scalar
t, 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 t at which a computed solution is desired. For the initial t, the input value of tout is used to determine the direction of integration. Integration is permitted in either direction (see also itask).
3:     yneq – double array
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:     ydotneq – double array
If lderiv1=true, ydot must contain approximations to the time derivatives y of the vector y.
If lderiv1=false, ydot need not be set on entry.
5:     rwork50+4×neq – double array
6:     rtol: – double array
The dimension of the array rtol must be at least 1 if itol=1 or 2, and at least neq otherwise
The relative local error tolerance.
Constraint: rtoli0.0 for all relevant i (see itol).
7:     atol: – double array
The dimension of the array atol must be at least 1 if itol=1 or 3, and at least neq otherwise
The absolute local error tolerance.
Constraint: atoli0.0 for all relevant i (see itol).
8:     itol int64int32nag_int scalar
A value to indicate the form of the local error test. itol indicates to nag_ode_ivp_stiff_imp_sparjac (d02nj) 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.0, where wi is defined as follows:
itol rtol atol wi
1 scalar scalar rtol1×yi+atol1
2 scalar vector rtol1×yi+atoli
3 vector scalar rtoli×yi+atol1
4 vector vector rtoli×yi+atoli
ei is an estimate of the local error in yi, computed internally, and the choice of norm to be used is defined by a previous call to an integrator setup function.
Constraint: itol=1, 2, 3 or 4.
9:     inform23 int64int32nag_int array
10:   resid – function handle or string containing name of m-file
resid must evaluate the residual
r=gt,y-At,yy  
in one case and
r=-At,yy  
in another.
[r, ires] = resid(neq, t, y, ydot, ires)

Input Parameters

1:     neq int64int32nag_int scalar
The number of equations being solved.
2:     t – double scalar
t, the current value of the independent variable.
3:     yneq – double array
The value of yi, for i=1,2,,neq.
4:     ydotneq – double array
The value of yi, for i=1,2,,neq, at t.
5:     ires int64int32nag_int scalar
The form of the residual that must be returned in array r.
ires=-1
The residual defined in equation (2) must be returned.
ires=1
The residual defined in equation (1) must be returned.

Output Parameters

1:     rneq – double array
ri must contain the ith component of r, for i=1,2,,neq, where
r=gt,y-At,yy (1)
or
r=-At,yy (2)
and where the definition of r is determined by the input value of ires.
2:     ires int64int32nag_int scalar
Should be unchanged unless one of the following actions is required of the integrator, in which case ires should be set accordingly.
ires=2
Indicates to the integrator that control should be passed back immediately to the calling (sub)program with the error indicator set to ifail=11.
ires=3
Indicates to the integrator that an error condition has occurred in the solution vector, its time derivative or in the value of t. 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=7.
ires=4
Indicates to the integrator to stop its current operation and to enter monitr immediately with argument imon=-2.
11:   ysavldysavsdysav – double array
12:   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 nag_ode_ivp_stiff_imp_sparjac_dummy_jac (d02njz). (nag_ode_ivp_stiff_imp_sparjac_dummy_jac (d02njz) is included in the NAG Toolbox.) You must indicate to the integrator whether this option is to be used by setting the argument jceval appropriately in a call to the sparse linear algebra setup function nag_ode_ivp_stiff_sparjac_setup (d02nu).
First we must define the system of nonlinear equations which is solved internally by the integrator. The time derivative, y, generated internally, has the form
y = y-z / hd ,  
where h is the current step size and d is a argument that depends on the integration method in use. The vector y is the current solution and the vector z depends on information from previous time steps. This means that d dy ​ ​ = hd d dy ​ ​ . The system of nonlinear equations that is solved has the form
A t,y y - g t,y = 0  
but it is solved in the form
r t,y = 0 ,  
where r is the function defined by
r t,y = hd A t,y y-z / hd - g t,y .  
It is the Jacobian matrix r y  that you must supply in jac as follows:
ri yj = aij t,y + hd yj k=1 neq aik t,y yk - gi t,y .  
[pdj] = jac(neq, t, y, ydot, h, d, j, pdj)

Input Parameters

1:     neq int64int32nag_int scalar
The number of equations being solved.
2:     t – double scalar
t, the current value of the independent variable.
3:     yneq – double array
yi, for i=1,2,,neq, the current solution component.
4:     ydotneq – double array
The derivative of the solution at the current point t.
5:     h – double scalar
The current step size.
6:     d – double scalar
The argument d which depends on the integration method.
7:     j int64int32nag_int scalar
The column of the Jacobian that jac must return in the array pdj.
8:     pdjneq – double array
Is set to zero.

Output Parameters

1:     pdjneq – double array
pdji should be set to the i,jth element of the Jacobian, where j is given by j. Only nonzero elements of this array need be set, since it is preset to zero before the call to jac.
13:   wkjacnwkjac – double array
The actual size depends on whether the sparsity structure is supplied or whether it is to be estimated. An appropriate value for nwkjac is described in the specification of the linear algebra setup function nag_ode_ivp_stiff_sparjac_setup (d02nu). This value must be the same as that supplied to nag_ode_ivp_stiff_sparjac_setup (d02nu).
14:   jacpvtnjcpvt int64int32nag_int array
The actual size depends on whether the sparsity structure is supplied or whether it is to be estimated. An appropriate value for njcpvt is described in the specification for the linear algebra setup function nag_ode_ivp_stiff_sparjac_setup (d02nu). This value must be same as that supplied to nag_ode_ivp_stiff_sparjac_setup (d02nu).
15:   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 nag_ode_ivp_stiff_exp_fulljac_dummy_monit (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 equations being solved.
2:     ldysav int64int32nag_int scalar
An upper bound on the number of 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:     yneq – double array
y, the values of the dependent variables evaluated at t.
7:     ydotneq – double array
The time derivatives y of the vector y.
8:     ysavldysavsdysav – 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:     rneq – double array
If imon=0 and inln=3, then the first neq elements contain the residual vector At,yy-gt,y.
10:   acorneq2 – double array
With imon=1, acori1 contains the weight used for the ith equation when the norm is evaluated, and acori2 contains the estimated local error for the ith 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=-2
Entry from the integrator after ires=4 (set in resid) caused an early termination (this facility could be used to locate discontinuities).
imon=-1
The current step failed repeatedly.
imon=0
Entry after a call to the internal nonlinear equation solver (see inln).
imon=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 4.
2:     yneq – double array
These values must not be changed unless imon is set to 2.
3:     imon int64int32nag_int scalar
May be reset to determine subsequent action in nag_ode_ivp_stiff_imp_sparjac (d02nj).
imon=-2
Integration is to be halted. A return will be made from the integrator to the calling (sub)program with ifail=12.
imon=-1
Allow the integrator to continue with its own internal strategy. The integrator will try up to three restarts unless imon-1 on exit.
imon=0
Return to the internal nonlinear equation solver, where the action taken is determined by the value of inln (see inln).
imon=1
Normal exit to the integrator to continue integration.
imon=2
Restart the integration at the current time point. The integrator will restart from order 1 when this option is used. The solution y, provided by monitr, will be used for the initial conditions.
imon=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=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=0. By setting inln=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 3 or 4.
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 3 or 4. If hmax is set to zero, no limit is assumed.
16:   lderiv2 – logical array
lderiv1 must be set to true if you have supplied both an initial y and an initial y. lderiv1 must be set to false if only the initial y has been supplied.
lderiv2 must be set to true if the integrator is to use a modified Newton method to evaluate the initial y and y. Note that y and y, if supplied, are used as initial estimates. This method involves taking a small step at the start of the integration, and if itask=6 on entry, t and tout will be set to the result of taking this small step. lderiv2 must be set to false if the integrator is to use functional iteration to evaluate the initial y and y, and if this fails a modified Newton method will then be attempted. lderiv2=true is recommended if there are implicit equations or the initial y and y are zero.
17:   itask int64int32nag_int scalar
The task to be performed by the integrator.
itask=1
Normal computation of output values of yt at t=tout (by overshooting and interpolating).
itask=2
Take one step only and return.
itask=3
Stop at the first internal integration point at or beyond t=tout and return.
itask=4
Normal computation of output values of yt at t=tout but without overshooting t=tcrit. 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=5
Take one step only and return, without passing tcrit. tcrit must be specified as under itask=4.
itask=6
The integrator will solve for the initial values of y and y only and then return to the calling (sub)program without doing the integration. This option can be used to check the initial values of y and y. Functional iteration or a ‘small’ backward Euler method used in conjunction with a damped Newton iteration is used to calculate these values (see lderiv). Note that if a backward Euler step is used then the value of t will have been advanced a short distance from the initial point.
Note:  if nag_ode_ivp_stiff_imp_sparjac (d02nj) is recalled with a different value of itask (and tout altered), then the initialization procedure is repeated, possibly leading to different initial conditions.
Constraint: 1itask6.
18:   itrace int64int32nag_int scalar
The level of output that is printed by the integrator. itrace may take the value -1, 0, 1, 2 or 3.
itrace<-1
-1 is assumed and similarly if itrace>3, then 3 is assumed.
itrace=-1
No output is generated.
itrace=0
Only warning messages are printed on the current error message unit (see nag_file_set_unit_error (x04aa)).
itrace>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 arrays y, ydot 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: neq1.
2:     sdysav int64int32nag_int scalar
Default: the second dimension of the array ysav.
The second dimension of the array ysav. an appropriate value for sdysav is described in the specifications of the integrator setup functions nag_ode_ivp_stiff_dassl (d02mv), 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.

Output Parameters

1:     t – double scalar
The value at which the computed solution y is returned (usually at tout).
2:     tout – double scalar
Normally unchanged. However, when itask=6, then tout contains the value of t at which initial values have been computed without performing any integration. See descriptions of itask and lderiv.
3:     yneq – double array
The computed solution vector, evaluated at t (usually t=tout).
4:     ydotneq – double array
The time derivatives y of the vector y at the last integration point.
5:     rwork50+4×neq – double array
6:     inform23 int64int32nag_int array
7:     ysavldysavsdysav – double array
8:     wkjacnwkjac – double array
Communication array, used to store information between calls to nag_ode_ivp_stiff_imp_sparjac (d02nj).
9:     jacpvtnjcpvt int64int32nag_int array
Communication array, used to store information between calls to nag_ode_ivp_stiff_imp_sparjac (d02nj).
10:   lderiv2 – logical array
lderiv1 is normally unchanged. However if itask=6 and internal initialization was successful then lderiv1=true.
lderiv2=true, if implicit equations were detected. Otherwise lderiv2=false.
11:   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:

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

   ifail=1
An illegal input was detected on entry, or after an internal call to monitr. If itrace>-1, then the form of the error will be detailed on the current error message unit (see nag_file_set_unit_error (x04aa)).
   ifail=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)).
W  ifail=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 y1,y2,,yneq contain the computed values of the solution at the current point t.
W  ifail=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=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=6
Some error weight wi became zero during the integration (see the description of itol). Pure relative error control (atoli=0.0) was requested on a variable (the ith) which has now vanished. The integration was successful as far as t.
   ifail=7
resid set its error flag (ires=3) continually despite repeated attempts by the integrator to avoid this.
   ifail=8
lderiv1=false on entry but the internal initialization function was unable to initialize y (more detailed information may be directed to the current error message unit, see nag_file_set_unit_error (x04aa)).
   ifail=9
A singular Jacobian r y  has been encountered. You should check the problem formulation and Jacobian calculation.
   ifail=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=11
resid signalled the integrator to halt the integration and return (ires=2). Integration was successful as far as t.
W  ifail=12
monitr set imon=-2 and so forced a return but the integration was successful as far as t.
W  ifail=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 itask2 or 5.)
   ifail=14
The values of rtol and atol are so small that nag_ode_ivp_stiff_imp_sparjac (d02nj) is unable to start the integration.
   ifail=15
The linear algebra setup function nag_ode_ivp_stiff_sparjac_setup (d02nu) was not called before the call to nag_ode_ivp_stiff_imp_sparjac (d02nj).
   ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
   ifail=-399
Your licence key may have expired or may not have been installed correctly.
   ifail=-999
Dynamic memory allocation failed.

Accuracy

The accuracy of the numerical solution may be controlled by a careful choice of the arguments 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=1 with atol1 small but positive).

Further Comments

Since numerical stability and memory are often conflicting requirements when solving ordinary differential systems where the Jacobian matrix is sparse we provide a diagnostic function, nag_ode_ivp_stiff_sparjac_diag (d02nx), whose aim is to inform you how much memory is required to solve the problem and to give you some indicators of numerical stability.
In general, you are advised to choose the BDF option (setup function nag_ode_ivp_stiff_bdf (d02nv)) but if efficiency is of great importance and especially if it is suspected that y A-1g  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 written as a mixed differential/algebraic system in implicit form
r1 = a+b+c-1.0 r2 = 0.04a-1.0E4bc-3.0E7b2-b r3 = 0.04a-1.0E4bc-3.0E7b2-c  
exploiting the fact that, from the initial conditions a=1.0 and b=c=0.0, we know that a+b+c=1 for all time. We integrate over the range 0,10.0 with vector relative error control and scalar absolute error control (itol=3) and using the BDF integrator (setup function nag_ode_ivp_stiff_bdf (d02nv)) and a modified Newton method. The Jacobian is evaluated, in turn, using the 'A' (Analytical) and 'F' (Full information) options. We provide a monitor function to terminate the integration when the value of the component a falls below 0.9.
function d02nj_example


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

% For communication with monitr.
global ncall tkeep ykeep jacobian;

jacobian = 'Analytic';
d02nj_subexample;
jacobian = 'Full_info';
d02nj_subexample;

  % Plot results.
fig1 = figure;
display_plot(tkeep, ykeep);


function d02nj_subexample

  global ncall tkeep ykeep jacobian;
  % Initialize setup variables and arrays.
  neq    = int64(3);
  neqmax = neq;
  maxord = int64(5);
  sdysav = maxord+1;
  petzld = true;
  const  = zeros(6, 1);
  tcrit  = 0;
  hmin   = 1.0e-10;
  hmax   = 10;
  h0     = 0;
  maxstp = int64(200);
  mxhnil = int64(5);
  rwork = zeros(50+4*neq, 1);

  % setup routine 
  [const, rwork, ifail] = d02nv(...
                                neqmax, sdysav, maxord, 'Newton', petzld, ...
                                const, tcrit, hmin, hmax, h0, maxstp, ...
                                mxhnil, 'Average-L2', rwork);

  % sparse Jacobian setup.
  nwkjac = int64(100);
  ia     = int64([1; 3; 6; 9]);
  ja     = int64([1; 2; 
                    1; 2; 3;
                    1; 2; 3]);
  njcpvt = int64(150);
  sens   = 1.0e-6;
  u      = 0.1;
  eta    = 1.0e-4;
  lblock = true;

  [jacpvt, rwork, ifail] = d02nu(...
                                 neq, neqmax, jacobian, nwkjac, ia, ja, ...
                                 njcpvt, sens, u, eta, lblock, rwork);
  
  % Initialize input arguments for integrator
  t      = 0;
  tout   = 10.0;
  y      = [1; 0; 0];
  ydot   = zeros(neq, 1);
  itol   = int64(3);
  rtol   = [0.0001; 0.001; 0.0001];
  atol   = [1e-07];
  inform = zeros(23,1,'int64');
  ysave  = zeros(neq, sdysav);
  wkjac  = zeros(nwkjac, 1);
  lderiv = [false; true];
  itrace = int64(0);
  itask  = int64(1);

  % Output header and initial results.
  fprintf('Jacobian = %s\n\n',jacobian);
  fprintf('    x                y\n');
  fprintf('%8.3f       %8.5f       %8.5f       %8.5f\n',t,y);
  
  if (jacobian(1)=='F')
    % Prepare to store results for plotting.
    ncall = 2;
    ykeep = y;
    tkeep = [t];
  end

  % Integrate to tout by overshooting (itask=1) using BDF with Newton,
  % and the Petzold error test.
  % The monitr routine forces a return when y(1)<= 0.9.
  % ifail = 12 is deliberately triggered, so turn warnings off temporarily
  wstat = warning();
  warning('OFF');
  [t, tout, y, ydot, rwork, inform, ysave, wkjac, jacpvt, lderiv, ifail] ...
    = d02nj(...
            t, tout, y, ydot, rwork, rtol, atol, itol, inform, @resid, ...
            ysave, @jac, wkjac, jacpvt, @monitr, lderiv, itask, itrace);
  warning(wstat);

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

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

  fprintf('\nDiagnostic information\n integration status:\n');
  fprintf('   last and next step sizes = %8.5f, %8.5f\n',hu, h);
  fprintf('   integration stopped at x = %8.5f\n',tcur);
  fprintf(' algorithm statistics:\n');
  fprintf('   number of time-steps and Newton iterations  = %5d %5d\n', ...
          nst,niter);
  fprintf('   number of residual and jacobian evaluations = %5d %5d\n', ...
          nre,nje);
  fprintf('   order of method last used and next to use   = %5d %5d\n', ...
          nqu,nq);
  fprintf('   component with largest error                = %5d\n',imxer);

  % d02nx is a sparse linear algebra diagnostic routine which can be
  % called after d02nj.
  icall = int64(0);
  [liwreq, liwusd, lrwreq, lrwusd, nlu, nz, ngp, isplit, igrow, nblock]...
     = d02nx(...
              icall, lblock, inform);
  fprintf(' sparse jacobian statistics:\n');
  fprintf('   njcpvt - required = %3d, used = %3d\n',liwreq,liwusd);
  fprintf('   nwkjac - required = %3d, used = %3d)\n',lrwreq,lrwusd);
  fprintf('   No. of LU-decomps = %3d, No. of nonzeros = %3d\n',nlu,nz);
  fprintf(['   No. of function calls to form Jacobian = %3d, try ', ...
           'isplit = %3d\n'], ngp, isplit);
  fprintf([' Growth estimate = %d, No. of blocks on diagonal %3d\n\n'], ...
          igrow, nblock);

function pdj = jac(neq, t, y, ydot, h, d, j, pdj)
  % Evaluate the Jacobian.
  pdj = zeros(neq,1);
  hxd = h*d;
  if j == 1
    pdj(1) = -hxd*(1.0);
    pdj(2) = -hxd*(0.04);
  elseif j == 2
    pdj(1) = -hxd*(1.0);
    pdj(2) = -hxd*(-1.0e4*y(3)-6.0e7*y(2)) + 1;
    pdj(3) = -hxd*(6.0e7*y(2));
  elseif j == 3
    pdj(1) = -hxd*(1.0);
    pdj(2) = -hxd*(-1.0e4*y(2));
    pdj(3) = -hxd*(0.0) + 1;
  end

function [hnext, y, imon, inln, hmin, hmax] = ...
  monitr(neq, neqmax, t, hlast, hnext, y, ydot, ...
         ysave, r, acor, imon, hmin, hmax, nqu)
  global ncall tkeep ykeep jacobian;

  % Terminate integration when y(1) <= 0.9
  if (y(1) <= 0.9)
    imon = int64(-2);
  end
  inln = int64(0);
  % Store current results for plotting later on.
  if (jacobian(1)=='F')
    tkeep(ncall,1) = t;
    ykeep(:,ncall) = y;
    ncall = ncall + 1;
  end
  
function [r, ires] = resid(neq, t, y, ydot, ires)
  r = zeros(neq,1);
  r(1) = 0;
  r(2) = -ydot(2);
  r(3) = -ydot(3);
  if ires == 1
    r(1) = y(1) + y(2) + y(3) - 1 + r(1);
    r(2) = 0.04*y(1) - 1.0e4*y(2)*y(3) - 3.0e7*y(2)*y(2) + r(2);
    r(3) = 3.0e7*y(2)*y(2) + r(3);
  end

function display_plot(x, y)
  % Formatting for title and axis labels.
  % Plot one of the curves and then add the other two.
  hline1 = semilogx(x, y(1,:));
  hold on
  [haxes, hline2, hline3] = plotyy(x, y(3,:),x, y(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:1.2]);
  set(haxes(2), 'YLim', [0.0 4e-5]);
  set(haxes(2), 'YMinorTick', 'on');
  set(haxes(2), 'YTick', [5e-6:5e-6: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', [0.0001 0.001 0.01 0.1 1 10]);
  end
  set(gca, 'box', 'off'); 
  % Add title.
  ht = title({'Stiff Robertson Problem (Implicit DAE):',...
              'BDF with Newton Iterations'});
  set(ht,'Position',[0.02,1.15,0.0]);
  % Label the x axis, and both y axes.
  xlabel('x');
  ylabel(haxes(1),'Solution (a,c)');
  ylabel(haxes(2),'Solution (b)');
  % Add a legend.
  legend('a','c','b','Location','Best');
  % Set some features of the three lines.
  set(hline1, 'Marker', '+','Linestyle','-','Color','red');
  set(hline2, 'Marker', '*','Linestyle',':','Color','green');
  set(hline3, 'Marker', 'x','Linestyle','--','Color','blue');
d02nj example results

Jacobian = Analytic

    x                y
   0.000        1.00000        0.00000        0.00000
   4.966        0.89195        0.00002        0.10803

Diagnostic information
 integration status:
   last and next step sizes =  0.60059,  0.60059
   integration stopped at x =  4.96639
 algorithm statistics:
   number of time-steps and Newton iterations  =    52   119
   number of residual and jacobian evaluations =   132    13
   order of method last used and next to use   =     4     4
   component with largest error                =     3
 sparse jacobian statistics:
   njcpvt - required =  99, used = 150
   nwkjac - required =  31, used =  75)
   No. of LU-decomps =  13, No. of nonzeros =   8
   No. of function calls to form Jacobian =   0, try isplit =  73
 Growth estimate = 1035, No. of blocks on diagonal   1

Jacobian = Full_info

    x                y
   0.000        1.00000        0.00000        0.00000
   4.966        0.89195        0.00002        0.10803

Diagnostic information
 integration status:
   last and next step sizes =  0.60059,  0.60059
   integration stopped at x =  4.96639
 algorithm statistics:
   number of time-steps and Newton iterations  =    52   119
   number of residual and jacobian evaluations =   131    13
   order of method last used and next to use   =     4     4
   component with largest error                =     3
 sparse jacobian statistics:
   njcpvt - required =  99, used = 150
   nwkjac - required =  31, used =  75)
   No. of LU-decomps =  13, No. of nonzeros =   8
   No. of function calls to form Jacobian =   0, try isplit =  73
 Growth estimate = 1035, No. of blocks on diagonal   1

d02nj_fig1.png

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