NAG Library Routine Document

d02njf (ivp_stiff_imp_sparjac)

1
Purpose

d02njf is a direct communication routine for integrating stiff systems of implicit ordinary differential equations coupled with algebraic equations when the Jacobian is a sparse matrix.

2
Specification

Fortran Interface
Integer, Intent (In):: neq, ldysav, itol, sdysav, nwkjac, njcpvt, itask, itrace
Integer, Intent (Inout):: inform(23), jacpvt(njcpvt), ifail
Real (Kind=nag_wp), Intent (In):: rtol(*), atol(*)
Real (Kind=nag_wp), Intent (Inout):: t, tout, y(neq), ydot(neq), rwork(50+4*neq), ysav(ldysav,sdysav), wkjac(nwkjac)
Logical, Intent (Inout):: lderiv(2)
External:: resid, jac, monitr
C Header Interface
#include <nagmk26.h>
void  d02njf_ (const Integer *neq, const Integer *ldysav, double *t, double *tout, double y[], double ydot[], double rwork[], const double rtol[], const double atol[], const Integer *itol, Integer inform[],
void (NAG_CALL *resid)(const Integer *neq, const double *t, const double y[], const double ydot[], double r[], Integer *ires),
double ysav[], const Integer *sdysav,
void (NAG_CALL *jac)(const Integer *neq, const double *t, const double y[], const double ydot[], const double *h, const double *d, const Integer *j, double pdj[]),
double wkjac[], const Integer *nwkjac, Integer jacpvt[], const Integer *njcpvt,
void (NAG_CALL *monitr)(const Integer *neq, const Integer *ldysav, const double *t, const double *hlast, double *hnext, double y[], const double ydot[], const double ysav[], const double r[], const double acor[], Integer *imon, Integer *inln, double *hmin, double *hmax, const Integer *nqu),
logical lderiv[], const Integer *itask, const Integer *itrace, Integer *ifail)

3
Description

d02njf is a general purpose routine 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 d02njf is given below. It calls the sparse matrix linear algebra setup routine d02nuf, the Backward Differentiation Formula (BDF) integrator setup routine d02nvf, its diagnostic counterpart d02nyf, and the sparse matrix linear algebra diagnostic routine d02nxf.
!     Declarations

      External resid, jac, monitr
          .
          .
          .
      ifail = 0
      Call d02nvf(...,ifail)
      Call d02nuf(neq, neqmax, jceval, nwkjac, ia, nia, ja, nja, &
      	   	  jacpvt, njcpvt, sens, u, eta, lblock, isplit,  &
     		  rwork, ifail)
      ifail = -1
      Call d02njf(neq, neqmax, t, tout, y, ydot, rwork, rtol,    &
      	          atol, itol, inform, resid, ysave, ny2dim, jac, &
     		  wkjac, nwkjac, jacpvt, njcpvt, monitr, lderiv, &
     		  itask, itrace, ifail)
      If(ifail.eq.1 .or. ifail.ge.14) Stop
      ifail = 0
      Call d02nxf(...)
      Call d02nyf(...)
          .
          .
          .
      Stop
      End
The linear algebra setup routine d02nuf and one of the integrator setup routines, d02mvf, d02nvf or d02nwf, must be called prior to the call of d02njf. Either or both of the integrator diagnostic routine d02nyf, or the sparse matrix linear algebra diagnostic routine d02nxf, may be called after the call to d02njf. There is also a routine, d02nzf, designed to permit you to change step size on a continuation call to d02njf without restarting the integration process.

4
References

See the D02M–N Sub-chapter Introduction.

5
Arguments

1:     neq – IntegerInput
On entry: the number of differential equations to be solved.
Constraint: neq1.
2:     ldysav – IntegerInput
On entry: a bound on the maximum number of equations to be solved during the integration.
Constraint: ldysavneq.
3:     t – Real (Kind=nag_wp)Input/Output
On entry: 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.
On exit: the value at which the computed solution y is returned (usually at tout).
4:     tout – Real (Kind=nag_wp)Input/Output
On entry: 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).
On exit: normally unchanged. However, when itask=6, tout contains the value of t at which initial values have been computed without performing any integration. See descriptions of itask and lderiv.
5:     yneq – Real (Kind=nag_wp) arrayInput/Output
On entry: the values of the dependent variables (solution). On the first call the first neq elements of y must contain the vector of initial values.
On exit: the computed solution vector, evaluated at t (usually t=tout).
6:     ydotneq – Real (Kind=nag_wp) arrayInput/Output
On entry: 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.
On exit: the time derivatives y of the vector y at the last integration point.
7:     rwork50+4×neq – Real (Kind=nag_wp) arrayCommunication Array
8:     rtol* – Real (Kind=nag_wp) arrayInput
Note: the dimension of the array rtol must be at least 1 if itol=1 or 2, and at least neq otherwise.
On entry: the relative local error tolerance.
Constraint: rtoli0.0 for all relevant i (see itol).
9:     atol* – Real (Kind=nag_wp) arrayInput
Note: the dimension of the array atol must be at least 1 if itol=1 or 3, and at least neq otherwise.
On entry: the absolute local error tolerance.
Constraint: atoli0.0 for all relevant i (see itol).
10:   itol – IntegerInput
On entry: a value to indicate the form of the local error test. itol indicates to d02njf 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 routine.
Constraint: itol=1, 2, 3 or 4.
11:   inform23 – Integer arrayCommunication Array
12:   resid – Subroutine, supplied by the user.External Procedure
resid must evaluate the residual
r=gt,y-At,yy  
in one case and
r=-At,yy  
in another.
The specification of resid is:
Fortran Interface
Subroutine resid ( neq, t, y, ydot, r, ires)
Integer, Intent (In):: neq
Integer, Intent (Inout):: ires
Real (Kind=nag_wp), Intent (In):: t, y(neq), ydot(neq)
Real (Kind=nag_wp), Intent (Out):: r(neq)
C Header Interface
#include <nagmk26.h>
void  resid (const Integer *neq, const double *t, const double y[], const double ydot[], double r[], Integer *ires)
1:     neq – IntegerInput
On entry: the number of equations being solved.
2:     t – Real (Kind=nag_wp)Input
On entry: t, the current value of the independent variable.
3:     yneq – Real (Kind=nag_wp) arrayInput
On entry: the value of yi, for i=1,2,,neq.
4:     ydotneq – Real (Kind=nag_wp) arrayInput
On entry: the value of yi, for i=1,2,,neq, at t.
5:     rneq – Real (Kind=nag_wp) arrayOutput
On exit: 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.
6:     ires – IntegerInput/Output
On entry: 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.
On exit: 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.
resid must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which d02njf is called. Arguments denoted as Input must not be changed by this procedure.
Note: resid should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d02njf. If your code inadvertently does return any NaNs or infinities, d02njf is likely to produce unexpected results.
13:   ysavldysavsdysav – Real (Kind=nag_wp) arrayCommunication Array
14:   sdysav – IntegerInput
On entry: the second dimension of the array ysav as declared in the (sub)program from which d02njf is called. An appropriate value for sdysav is described in the specifications of the integrator setup routines d02mvf, d02nvf and d02nwf. This value must be the same as that supplied to the integrator setup routine.
15:   jac – Subroutine, supplied by the NAG Library or the user.External Procedure
jac must evaluate the Jacobian of the system. If this option is not required, the actual argument for jac must be the dummy routine d02njz. (d02njz is included in the NAG Library.) 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 routine d02nuf.
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 an 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 .  
The specification of jac is:
Fortran Interface
Subroutine jac ( neq, t, y, ydot, h, d, j, pdj)
Integer, Intent (In):: neq, j
Real (Kind=nag_wp), Intent (In):: t, y(neq), ydot(neq), h, d
Real (Kind=nag_wp), Intent (Inout):: pdj(neq)
C Header Interface
#include <nagmk26.h>
void  jac (const Integer *neq, const double *t, const double y[], const double ydot[], const double *h, const double *d, const Integer *j, double pdj[])
1:     neq – IntegerInput
On entry: the number of equations being solved.
2:     t – Real (Kind=nag_wp)Input
On entry: t, the current value of the independent variable.
3:     yneq – Real (Kind=nag_wp) arrayInput
On entry: yi, for i=1,2,,neq, the current solution component.
4:     ydotneq – Real (Kind=nag_wp) arrayInput
On entry: the derivative of the solution at the current point t.
5:     h – Real (Kind=nag_wp)Input
On entry: the current step size.
6:     d – Real (Kind=nag_wp)Input
On entry: the argument d which depends on the integration method.
7:     j – IntegerInput
On entry: the column of the Jacobian that jac must return in the array pdj.
8:     pdjneq – Real (Kind=nag_wp) arrayInput/Output
On entry: is set to zero.
On exit: 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.
jac must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which d02njf is called. Arguments denoted as Input must not be changed by this procedure.
Note: jac should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d02njf. If your code inadvertently does return any NaNs or infinities, d02njf is likely to produce unexpected results.
16:   wkjacnwkjac – Real (Kind=nag_wp) arrayCommunication Array
17:   nwkjac – IntegerInput
On entry: the dimension of the array wkjac as declared in the (sub)program from which d02njf is called. 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 routine d02nuf. This value must be the same as that supplied to d02nuf.
18:   jacpvtnjcpvt – Integer arrayCommunication Array
19:   njcpvt – IntegerInput
On entry: the dimension of the array jacpvt as declared in the (sub)program from which d02njf is called. 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 routine d02nuf. This value must be same as that supplied to d02nuf.
20:   monitr – Subroutine, supplied by the NAG Library or the user.External Procedure
monitr performs tasks requested by you. If this option is not required, the actual argument for monitr must be the dummy routine d02nby. (d02nby is included in the NAG Library.)
The specification of monitr is:
Fortran Interface
Subroutine monitr ( neq, ldysav, t, hlast, hnext, y, ydot, ysav, r, acor, imon, inln, hmin, hmax, nqu)
Integer, Intent (In):: neq, ldysav, nqu
Integer, Intent (Inout):: imon
Integer, Intent (Out):: inln
Real (Kind=nag_wp), Intent (In):: t, hlast, ydot(neq), ysav(ldysav,*), r(neq), acor(neq,2)
Real (Kind=nag_wp), Intent (Inout):: hnext, y(neq), hmin, hmax
C Header Interface
#include <nagmk26.h>
void  monitr (const Integer *neq, const Integer *ldysav, const double *t, const double *hlast, double *hnext, double y[], const double ydot[], const double ysav[], const double r[], const double acor[], Integer *imon, Integer *inln, double *hmin, double *hmax, const Integer *nqu)
1:     neq – IntegerInput
On entry: the number of equations being solved.
2:     ldysav – IntegerInput
On entry: an upper bound on the number of equations to be solved.
3:     t – Real (Kind=nag_wp)Input
On entry: the current value of the independent variable.
4:     hlast – Real (Kind=nag_wp)Input
On entry: the last step size successfully used by the integrator.
5:     hnext – Real (Kind=nag_wp)Input/Output
On entry: the step size that the integrator proposes to take on the next step.
On exit: the next step size to be used. If this is different from the input value, imon must be set to 4.
6:     yneq – Real (Kind=nag_wp) arrayInput/Output
On entry: y, the values of the dependent variables evaluated at t.
On exit: these values must not be changed unless imon is set to 2.
7:     ydotneq – Real (Kind=nag_wp) arrayInput
On entry: the time derivatives y of the vector y.
8:     ysavldysav* – Real (Kind=nag_wp) arrayInput
Note: the second dimension of ysav is sdysav as in the call of d02njf.
On entry: workspace to enable you to carry out interpolation using either of the routines d02xjf or d02xkf.
9:     rneq – Real (Kind=nag_wp) arrayInput
On entry: if imon=0 and inln=3, the first neq elements contain the residual vector At,yy-gt,y.
10:   acorneq2 – Real (Kind=nag_wp) arrayInput
On entry: 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 real function d02zaf as follows:
ifail = 1
errloc = d02zaf(neq, acor(1,2), acor(1,1), ifail)
! CHECK IFAIL BEFORE PROCEEDING
11:   imon – IntegerInput/Output
On entry: 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.
On exit: may be reset to determine subsequent action in d02njf.
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.
12:   inln – IntegerOutput
On exit: 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.
13:   hmin – Real (Kind=nag_wp)Input/Output
On entry: the minimum step size to be taken on the next step.
On exit: the minimum step size to be used. If this is different from the input value, imon must be set to 3 or 4.
14:   hmax – Real (Kind=nag_wp)Input/Output
On entry: the maximum step size to be taken on the next step.
On exit: the maximum step size to be used. If this is different from the input value, imon must be set to 3 or 4. If hmax is set to zero, no limit is assumed.
15:   nqu – IntegerInput
On entry: the order of the integrator used on the last step. This is supplied to enable you to carry out interpolation using either of the routines d02xjf or d02xkf.
monitr must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which d02njf is called. Arguments denoted as Input must not be changed by this procedure.
Note: monitr should not return floating-point NaN (Not a Number) or infinity values, since these are not handled by d02njf. If your code inadvertently does return any NaNs or infinities, d02njf is likely to produce unexpected results.
21:   lderiv2 – Logical arrayInput/Output
On entry: 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.
On exit: 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..
22:   itask – IntegerInput
On entry: 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 routines before the first call to the integrator, or specified in the optional input routine 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 d02njf is recalled with a different value of itask (and tout altered), the initialization procedure is repeated, possibly leading to different initial conditions.
Constraint: 1itask6.
23:   itrace – IntegerInput
On entry: 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, 3 is assumed.
itrace=-1
No output is generated.
itrace=0
Only warning messages are printed on the current error message unit (see x04aaf).
itrace>0
Warning messages are printed as above, and on the current advisory message unit (see x04abf) 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.
24:   ifail – IntegerInput/Output
On entry: ifail must be set to 0, -1 or 1. If you are unfamiliar with this argument you should refer to Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1 or 1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if ifail0 on exit, the recommended value is -1. When the value -1 or 1 is used it is essential to test the value of ifail on exit.
On exit: ifail=0 unless the routine detects an error or a warning has been flagged (see Section 6).

6
Error Indicators and Warnings

If on entry ifail=0 or -1, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
ifail=1
Either the integrator setup routine has not been called prior to the first call of this routine, or a communication array has become corrupted.
Either the linear algebra setup routine has not been called prior to the first call of this routine, or a communication array has become corrupted.
Either the routine was entered on a continuation call without a prior call of this routine, or a communication array has become corrupted.
Either the value of njcpvt is not the same as the value supplied to the setup routine or a communication array has become corrupted.
njcpvt=value and njcpvt=value in d02nuf.
Either the value of nwkjac is not the same as the value supplied to the setup routine or a communication array has become corrupted.
nwkjac=value and nwkjac=value in d02nuf.
Either the value of sdysav is not the same as the value supplied to the setup routine or a communication array has become corrupted.
sdysav=value, sdysav (setup) =value.
Failure during internal time interpolation. tout and the current time are too close.
itask=value and tout=value and the current time is value.
ires was set to an illegal value during initialization.
ires=value at time value.
itask=3 and tout is more than an integration step behind the current time.
tout=value, current time minus step size: value.
monitr appears to have overwritten the solution vector.
Further integration will not be attempted.
monitr set imon=value.
Constraint: -2imon4.
monitr set inln=value.
Constraint: inln=3.
On entry, an illegal (negative) maximum number of steps was provided in a prior call to a setup routine. maxstp=value.
On entry, an illegal (negative) maximum stepsize was provided in a prior call to a setup routine. hmax=value.
On entry, an illegal (negative) minimum stepsize was provided in a prior call to a setup routine. hmin=value.
On entry, atol=value.
Constraint: atol0.0.
On entry, ires=value and dydt=0.0 for all elements.
Check the evaluation of the residual for this value of ires.
On entry, itask=value.
Constraint: 1itask5.
On entry, itask=4 or 5 and tcrit is before the current time in the direction of integration.
itask=value, tcrit=value and the current time is value.
On entry, itask=4 or 5 and tcrit is before tout in the direction of integration.
itask=value, tcrit=value and tout=value.
On entry, itol=value.
Constraint: 1itol4.
On entry, neq=value.
Constraint: neq1.
On entry, neq=value and ldysav=value.
Constraint: neqldysav.
On entry, rtol=value.
Constraint: rtol0.0.
On entry, tout is less than t with respect to the direction of integration given by the sign of h0 in a prior call to a setup routine.
tout=value, t=value and h0=value.
On entry, tout is too close to t to start integration.
tout=value and t=value.
The initial stepsize, h=value, is too small.
Weight number i=value used in the local error test is too small. Check the values of rtol and atol.
atoli and yi may both be zero.
Weight i=value.
ifail=2
At time value the maximum number of allowed steps on this call was taken before reaching the next output point tout=value.
Maximum number of steps =value.
See d02mvf for details of maxstp.
ifail=3
Too much accuracy requested for precision of the machine at time value.
The tolerances should be checked; the requested accuracy should be reduced by a factor of at least value.
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.
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.
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.
ifail=6
At time value, error weight value became zero. Check the values of atol, rtol and itol supplied.
ifail=7
resid set ires=3, which signals that an error condition has occurred in the solution vector, its time derivative or in the value of t. It was not possible to remove this condition.
ires=value at t=value.
ifail=8
Attempt was made to reduce the step size to a value less than the minimum step size during the calculation of initial values.
Minimum stepsize: value.
Nonlinear solver failed to converge using a damped Newton method to solve for initial values.
Damping factor: value; convergence rate: value.
The residual routine returned an error when calculating the initial values of the solution and its time derivative.
The user problem has one or more inconsistencies between the ires=1 and ires=-1 parts. Integration will not be attempted.
Workspace error occurred when trying to form the Jacobian matrix in calculating the initial values of the solution and its time derivative.
ifail=9
A singular Jacobian has been encountered. You should check the problem formulation and Jacobian calculation.
ifail=10
Larger integer workspace required.
Provided: value; required: value.
Not enough integer store provided for internal storage pointers.
Units of store needed: value. Amount provided: value.
Not enough integer store provided for sparse matrix solver.
Units of store needed: value. Amount provided: value.
Not enough real store provided for sparse matrix solver.
Units of store needed: value. Amount provided: value.
ifail=11
resid set ires=2, which signals that the integration should terminate. ires=value at time value.
ifail=12
A return was forced by setting imon=-2, but the integration was successful as far as t.
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. (This ONLY applies when you are NOT operating in one step mode; that is, when itask2 or 5.)
ifail=14
On entry, too much accuracy requested for precision of the machine at the start of problem. The tolerances should be checked; the requested accuracy should be reduced by a factor of at least value.
ifail=15
Either the sparse matrix linear algebra setup routine was not called first or a communication array has become corrupted.
ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 3.9 in How to Use the NAG Library and its Documentation for further information.
ifail=-399
Your licence key may have expired or may not have been installed correctly.
See Section 3.8 in How to Use the NAG Library and its Documentation for further information.
ifail=-999
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.

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

8
Parallelism and Performance

d02njf is not thread safe and should not be called from a multithreaded user program. Please see Section 3.12.1 in How to Use the NAG Library and its Documentation for more information on thread safety.
d02njf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
d02njf makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9
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 routine, d02nxf, 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 routine d02nvf) 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 routine d02nwf).

10
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 routine d02nvf) and a modified Newton method. The Jacobian is evaluated, in turn, using the 'A' (Analytical) and 'F' (Full information) options. We provide a monitor routine to terminate the integration when the value of the component a falls below 0.9.

10.1
Program Text

Program Text (d02njfe.f90)

10.2
Program Data

Program Data (d02njfe.d)

10.3
Program Results

Program Results (d02njfe.r)

GnuplotProduced by GNUPLOT 4.6 patchlevel 3 0 0.2 0.4 0.6 0.8 1 1.2 0.001 0.01 0.1 1 10 0.00000 0.00001 0.00001 0.00002 0.00002 0.00003 0.00003 0.00004 Solution (a,c) Solution (b) x(logscale) Example Program Stiff DAE with Sparse Jacobian Stiff Robertson Problem using BDF with Newton Iterations a b c gnuplot_plot_1 gnuplot_plot_2 gnuplot_plot_3