NAG Library Routine Document
D02NEF
1 Purpose
D02NEF is a routine for integrating stiff systems of implicit ordinary differential equations coupled with algebraic equations.
2 Specification
SUBROUTINE D02NEF ( 
NEQ, T, TOUT, Y, YDOT, RTOL, ATOL, ITASK, RES, JAC, ICOM, COM, LCOM, IUSER, RUSER, IFAIL) 
INTEGER 
NEQ, ITASK, ICOM(50+NEQ), LCOM, IUSER(*), IFAIL 
REAL (KIND=nag_wp) 
T, TOUT, Y(NEQ), YDOT(NEQ), RTOL(*), ATOL(*), COM(LCOM), RUSER(*) 
EXTERNAL 
RES, JAC 

3 Description
D02NEF is a general purpose routine for integrating the initial value problem for a stiff system of implicit ordinary differential equations with coupled algebraic equations written in the form
D02NEF uses the DASSL implementation of the Backward Differentiation Formulae (BDF) of orders one to five to solve a system of the above form for
$y$ (
Y) and
${y}^{\prime}$ (
YDOT). Values for
Y and
YDOT at the initial time must be given as input. These values must be consistent, (i.e., if
T,
Y,
YDOT are the given initial values, they must satisfy
$F\left({\mathbf{T}},{\mathbf{Y}},{\mathbf{YDOT}}\right)=0$). The routine solves the system from
$t={\mathbf{T}}$ to
$t={\mathbf{TOUT}}$.
An outline of a typical calling program for D02NEF is given below. It calls the DASSL implementation of the BDF integrator setup routine
D02MWF and the banded matrix setup routine
D02NPF (if required), and, if the integration needs to proceed, calls
D02MCF before continuing the integration.
! Declarations
EXTERNAL RES, JAC
.
.
.
! Initialize the integrator
CALL D02MWF(...)
! Is the Jacobian matrix banded?
IF (BANDED) CALL D02NPF(...)
! Set DT to the required temporal resolution
! Set TEND to the final time
! Call the integrator for each temporal value:
1000 CALL D02NEF(...,RES,JAC,...)
! Continue integration?
IF (TOUT.LT.TEND .AND. ITASK.GE.0) THEN
IF (ITASK.NE.1) TOUT = MIN(TOUT+DT,TEND)
! Print solution
CALL D02MCF(...)
GO TO 1000
ENDIF
.
.
.
4 References
None.
5 Arguments
 1: $\mathrm{NEQ}$ – INTEGERInput

On entry: the number of differentialalgebraic equations to be solved.
Constraint:
${\mathbf{NEQ}}\ge 1$.
 2: $\mathrm{T}$ – REAL (KIND=nag_wp)Input/Output

On initial entry: the initial value of the independent variable, $t$.
On intermediate exit:
$t$, the current value of the independent variable.
On final exit: the value of the independent variable at which the computed solution
$y$ is returned (usually at
TOUT).
 3: $\mathrm{TOUT}$ – REAL (KIND=nag_wp)Input

On entry: the next value of $t$ at which a computed solution is desired.
On initial entry:
TOUT is used to determine the direction of integration. Integration is permitted in either direction (see also
ITASK).
Constraint:
${\mathbf{TOUT}}\ne {\mathbf{T}}$.
 4: $\mathrm{Y}\left({\mathbf{NEQ}}\right)$ – REAL (KIND=nag_wp) arrayInput/Output

On initial entry: the vector of initial values of the dependent variables $y$.
On intermediate exit:
the computed solution vector, $y$, evaluated at $t=T$.
On final exit: the computed solution vector, evaluated at $t$ (usually $t={\mathbf{TOUT}}$).
 5: $\mathrm{YDOT}\left({\mathbf{NEQ}}\right)$ – REAL (KIND=nag_wp) arrayInput/Output

On initial entry:
YDOT must contain approximations to the time derivatives
$y\text{'}$ of the vector
$y$ evaluated at the initial value of the independent variable.
On exit: the time derivatives $y\text{'}$ of the vector $y$ at the last integration point.
 6: $\mathrm{RTOL}\left(*\right)$ – REAL (KIND=nag_wp) arrayInput/Output

Note: the dimension of the array
RTOL depends on the value of
ITOL as set in
D02MWF; it
must be at least
${\mathbf{NEQ}}$ if
${\mathbf{ITOL}}=\mathrm{.TRUE.}$ and at least
$1$ if
${\mathbf{ITOL}}=\mathrm{.FALSE.}$.
On entry: the relative local error tolerance.
Constraint:
${\mathbf{RTOL}}\left(\mathit{i}\right)\ge 0.0$, for
$\mathit{i}=1,2,\dots ,n$where $n={\mathbf{NEQ}}$ when ${\mathbf{ITOL}}=\mathrm{.TRUE.}$ and $n=1$ otherwise.
On exit:
RTOL remains unchanged unless D02NEF exits with
${\mathbf{IFAIL}}={\mathbf{16}}$ in which case the values may have been increased to values estimated to be appropriate for continuing the integration.
 7: $\mathrm{ATOL}\left(*\right)$ – REAL (KIND=nag_wp) arrayInput/Output

Note: the dimension of the array
ATOL depends on the value of
ITOL as set in
D02MWF; it
must be at least
${\mathbf{NEQ}}$ if
${\mathbf{ITOL}}=\mathrm{.TRUE.}$ and at least
$1$ if
${\mathbf{ITOL}}=\mathrm{.FALSE.}$.
On entry: the absolute local error tolerance.
Constraint:
${\mathbf{ATOL}}\left(\mathit{i}\right)\ge 0.0$, for
$\mathit{i}=1,2,\dots ,n$where $n={\mathbf{NEQ}}$ when ${\mathbf{ITOL}}=\mathrm{.TRUE.}$ and $n=1$ otherwise.
On exit:
ATOL remains unchanged unless D02NEF exits with
${\mathbf{IFAIL}}={\mathbf{16}}$ in which case the values may have been increased to values estimated to be appropriate for continuing the integration.
 8: $\mathrm{ITASK}$ – INTEGERInput/Output

On initial entry: need not be set.
On exit: the task performed by the integrator on successful completion or an indicator that a problem occurred during integration.
 ${\mathbf{ITASK}}=2$
 The integration to TOUT was successfully completed (${\mathbf{T}}={\mathbf{TOUT}}$) by stepping exactly to TOUT.
 ${\mathbf{ITASK}}=3$
 The integration to TOUT was successfully completed (${\mathbf{T}}={\mathbf{TOUT}}$) by stepping past TOUT. Y and YDOT are obtained by interpolation.
 ${\mathbf{ITASK}}<0$
 Different negative values of ITASK returned correspond to different failure exits. IFAIL should always be checked in such cases and the corrective action taken where appropriate.
ITASK must remain
unchanged between calls to D02NEF.
 9: $\mathrm{RES}$ – SUBROUTINE, supplied by the user.External Procedure

RES must evaluate the residual
The specification of
RES is:
INTEGER 
NEQ, IRES, IUSER(*) 
REAL (KIND=nag_wp) 
T, Y(NEQ), YDOT(NEQ), R(NEQ), RUSER(*) 

 1: $\mathrm{NEQ}$ – INTEGERInput

On entry: the number of differentialalgebraic equations being solved.
 2: $\mathrm{T}$ – REAL (KIND=nag_wp)Input

On entry: $t$, the current value of the independent variable.
 3: $\mathrm{Y}\left({\mathbf{NEQ}}\right)$ – REAL (KIND=nag_wp) arrayInput

On entry: ${y}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,{\mathbf{NEQ}}$, the current solution component.
 4: $\mathrm{YDOT}\left({\mathbf{NEQ}}\right)$ – REAL (KIND=nag_wp) arrayInput

On entry: the derivative of the solution at the current point $t$.
 5: $\mathrm{R}\left({\mathbf{NEQ}}\right)$ – REAL (KIND=nag_wp) arrayOutput

On exit:
${\mathbf{R}}\left(\mathit{i}\right)$ must contain the
$\mathit{i}$th component of
$R$, for
$\mathit{i}=1,2,\dots ,{\mathbf{NEQ}}$ where
 6: $\mathrm{IRES}$ – INTEGERInput/Output

On entry: is always equal to zero.
On exit:
IRES should normally be left unchanged. However, if an illegal value of
Y is encountered,
IRES should be set to
$1$; D02NEF will then attempt to resolve the problem so that illegal values of
Y are not encountered.
IRES should be set to
$2$ if you wish to return control to the calling (sub)routine; this will cause D02NEF to exit with
${\mathbf{IFAIL}}={\mathbf{23}}$.
 7: $\mathrm{IUSER}\left(*\right)$ – INTEGER arrayUser Workspace
 8: $\mathrm{RUSER}\left(*\right)$ – REAL (KIND=nag_wp) arrayUser Workspace

RES is called with the arguments
IUSER and
RUSER as supplied to D02NEF. You should use the arrays
IUSER and
RUSER to supply information to
RES.
RES must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which D02NEF is called. Arguments denoted as
Input must
not be changed by this procedure.
 10: $\mathrm{JAC}$ – SUBROUTINE, supplied by the NAG Library or the user.External Procedure

Evaluates the matrix of partial derivatives,
$J$, where
If this option is not required, the actual argument for
JAC must be the dummy routine D02NEZ. (D02NEZ 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 setup routine
D02MWF.
The specification of
JAC is:
INTEGER 
NEQ, IUSER(*) 
REAL (KIND=nag_wp) 
T, Y(NEQ), YDOT(NEQ), PD(*), CJ, RUSER(*) 

 1: $\mathrm{NEQ}$ – INTEGERInput

On entry: the number of differentialalgebraic equations being solved.
 2: $\mathrm{T}$ – REAL (KIND=nag_wp)Input

On entry: $t$, the current value of the independent variable.
 3: $\mathrm{Y}\left({\mathbf{NEQ}}\right)$ – REAL (KIND=nag_wp) arrayInput

On entry: ${y}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,{\mathbf{NEQ}}$, the current solution component.
 4: $\mathrm{YDOT}\left({\mathbf{NEQ}}\right)$ – REAL (KIND=nag_wp) arrayInput

On entry: the derivative of the solution at the current point $t$.
 5: $\mathrm{PD}\left(*\right)$ – REAL (KIND=nag_wp) arrayInput/Output

On entry:
PD is preset to zero before the call to
JAC.
On exit: if the Jacobian is full then
${\mathbf{PD}}\left(\left(\mathit{j}1\right)\times {\mathbf{NEQ}}+\mathit{i}\right)={J}_{\mathit{i}\mathit{j}}$, for
$\mathit{i}=1,2,\dots ,{\mathbf{NEQ}}$ and
$\mathit{j}=1,2,\dots ,{\mathbf{NEQ}}$; if the Jacobian is banded then
${\mathbf{PD}}\left(\left(j1\right)\times \left(2{\mathbf{ML}}+{\mathbf{MU}}+1\right)+{\mathbf{ML}}+{\mathbf{MU}}+ij+1\right)={J}_{ij}$, for
$\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,j{\mathbf{MU}}\right)\le i\le \mathrm{min}\phantom{\rule{0.125em}{0ex}}\left(n,j+{\mathbf{ML}}\right)$; (see also in
F07BDF (DGBTRF)).
 6: $\mathrm{CJ}$ – REAL (KIND=nag_wp)Input

On entry:
CJ is a scalar constant which will be defined in D02NEF.
 7: $\mathrm{IUSER}\left(*\right)$ – INTEGER arrayUser Workspace
 8: $\mathrm{RUSER}\left(*\right)$ – REAL (KIND=nag_wp) arrayUser Workspace

JAC is called with the arguments
IUSER and
RUSER as supplied to D02NEF. You should use the arrays
IUSER and
RUSER to supply information to
JAC.
JAC must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which D02NEF is called. Arguments denoted as
Input must
not be changed by this procedure.
 11: $\mathrm{ICOM}\left(50+{\mathbf{NEQ}}\right)$ – INTEGER arrayCommunication Array

ICOM contains information which is usually of no interest, but is necessary for subsequent calls. However you may find the following useful:
 ${\mathbf{ICOM}}\left(22\right)$
 The order of the method to be attempted on the next step.
 ${\mathbf{ICOM}}\left(23\right)$
 The order of the method used on the last step.
 ${\mathbf{ICOM}}\left(26\right)$
 The number of steps taken so far.
 ${\mathbf{ICOM}}\left(27\right)$
 The number of calls to RES so far.
 ${\mathbf{ICOM}}\left(28\right)$
 The number of evaluations of the matrix of partial derivatives needed so far.
 ${\mathbf{ICOM}}\left(29\right)$
 The total number of error test failures so far.
 ${\mathbf{ICOM}}\left(30\right)$
 The total number of convergence test failures so far.
 12: $\mathrm{COM}\left({\mathbf{LCOM}}\right)$ – REAL (KIND=nag_wp) arrayCommunication Array

COM contains information which is usually of no interest, but is necessary for subsequent calls. However you may find the following useful:
 ${\mathbf{COM}}\left(3\right)$
 The step size to be attempted on the next step.
 ${\mathbf{COM}}\left(4\right)$
 The current value of the independent variable, i.e., the farthest point integration has reached. This will be different from T only when interpolation has been performed (${\mathbf{ITASK}}=3$).
 13: $\mathrm{LCOM}$ – INTEGERInput

On entry: the dimension of the array
COM as declared in the (sub)program from which D02NEF is called.
Constraint:
${\mathbf{LCOM}}\ge 40+\left(\mathit{maxorder}+4\right)\times {\mathbf{NEQ}}+{\mathbf{NEQ}}\times p+q$ where
$\mathit{maxorder}$ is the maximum order that can be used by the integration method (see
MAXORD in
D02MWF);
$p={\mathbf{NEQ}}$ when the Jacobian is full and
$p=\left(2\times {\mathbf{ML}}+{\mathbf{MU}}+1\right)$ when the Jacobian is banded; and,
$q=\left({\mathbf{NEQ}}/\left({\mathbf{ML}}+{\mathbf{MU}}+1\right)\right)+1$ when the Jacobian is to be evaluated numerically and
$q=0$ otherwise.
 14: $\mathrm{IUSER}\left(*\right)$ – INTEGER arrayUser Workspace
 15: $\mathrm{RUSER}\left(*\right)$ – REAL (KIND=nag_wp) arrayUser Workspace

IUSER and
RUSER are not used by D02NEF, but are passed directly to
RES and
JAC and should be used to pass information to these routines.
 16: $\mathrm{IFAIL}$ – INTEGERInput/Output

On entry:
IFAIL must be set to
$0$,
$1\text{ 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\text{ 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
${\mathbf{IFAIL}}\ne {\mathbf{0}}$ on exit, the recommended value is
$1$.
When the value $\mathbf{1}\text{ or}1$ is used it is essential to test the value of IFAIL on exit.
On exit:
${\mathbf{IFAIL}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see
Section 6).
6 Error Indicators and Warnings
If on entry
${\mathbf{IFAIL}}=0$ or
$1$, explanatory error messages are output on the current error message unit (as defined by
X04AAF).
Note: D02NEF may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
 ${\mathbf{IFAIL}}=1$

On entry, ${\mathbf{NEQ}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{NEQ}}\ge 1$.
 ${\mathbf{IFAIL}}=3$

On entry, ${\mathbf{T}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{TOUT}}\ne {\mathbf{T}}$.
TOUT is behind
T in the direction of
$h$:
${\mathbf{TOUT}}{\mathbf{T}}=\u2329\mathit{\text{value}}\u232a$,
$h=\u2329\mathit{\text{value}}\u232a$.
TOUT is too close to
T to start integration:
${\mathbf{TOUT}}{\mathbf{T}}=\u2329\mathit{\text{value}}\u232a$:
$\mathit{hmin}=\u2329\mathit{\text{value}}\u232a$.
 ${\mathbf{IFAIL}}=6$

Some element of
RTOL is less than zero.
 ${\mathbf{IFAIL}}=7$

Some element of
ATOL is less than zero.
 ${\mathbf{IFAIL}}=8$

A previous call to this routine returned with ${\mathbf{ITASK}}=\u2329\mathit{\text{value}}\u232a$ and no appropriate action was taken.
 ${\mathbf{IFAIL}}=11$

Either the initialization routine has not been called prior to the first call of this routine or a communication array has become corrupted.
 ${\mathbf{IFAIL}}=12$

Either the initialization routine has not been called prior to the first call of this routine or a communication array has become corrupted.
 ${\mathbf{IFAIL}}=13$

COM array is of insufficient length; length required
$\text{}=\u2329\mathit{\text{value}}\u232a$; actual length
${\mathbf{LCOM}}=\u2329\mathit{\text{value}}\u232a$.
 ${\mathbf{IFAIL}}=14$

All elements of
RTOL and
ATOL are zero.
 ${\mathbf{IFAIL}}=15$

Maximum number of steps taken on this call before reaching
TOUT:
${\mathbf{T}}=\u2329\mathit{\text{value}}\u232a$, maximum number of steps
$\text{}=\u2329\mathit{\text{value}}\u232a$.
 ${\mathbf{IFAIL}}=16$

Too much accuracy requested for precision of machine.
RTOL and
ATOL were increased by scale factor
$R$. Try running again with these scaled tolerances.
${\mathbf{T}}=\u2329\mathit{\text{value}}\u232a$,
$R=\u2329\mathit{\text{value}}\u232a$.
 ${\mathbf{IFAIL}}=17$

A solution component has become zero when a purely relative tolerance (zero absolute tolerance) was selected for that component. ${\mathbf{T}}=\u2329\mathit{\text{value}}\u232a$, ${\mathbf{Y}}\left(\mathit{I}\right)=\u2329\mathit{\text{value}}\u232a$ for component $\mathit{I}=\u2329\mathit{\text{value}}\u232a$.
 ${\mathbf{IFAIL}}=18$

The error test failed repeatedly with $\lefth\right=\mathit{hmin}$. ${\mathbf{T}}=\u2329\mathit{\text{value}}\u232a$. Stepsize $h=\u2329\mathit{\text{value}}\u232a$.
 ${\mathbf{IFAIL}}=19$

The corrector repeatedly failed to converge with $\lefth\right=\mathit{hmin}$. ${\mathbf{T}}=\u2329\mathit{\text{value}}\u232a$. Stepsize $h=\u2329\mathit{\text{value}}\u232a$.
 ${\mathbf{IFAIL}}=20$

The iteration matrix is singular. ${\mathbf{T}}=\u2329\mathit{\text{value}}\u232a$. Stepsize $h=\u2329\mathit{\text{value}}\u232a$.
 ${\mathbf{IFAIL}}=21$

The corrector could not converge and the error test failed repeatedly. ${\mathbf{T}}=\u2329\mathit{\text{value}}\u232a$. Stepsize $h=\u2329\mathit{\text{value}}\u232a$.
 ${\mathbf{IFAIL}}=22$

IRES was set to
$1$ during a call to
RES and could not be resolved.
${\mathbf{T}}=\u2329\mathit{\text{value}}\u232a$. Stepsize
$h=\u2329\mathit{\text{value}}\u232a$.
 ${\mathbf{IFAIL}}=23$

IRES was set to
$2$ during a call to
RES.
${\mathbf{T}}=\u2329\mathit{\text{value}}\u232a$. Stepsize
$\text{}=\u2329\mathit{\text{value}}\u232a$.
 ${\mathbf{IFAIL}}=24$

The initial
YDOT could not be computed.
${\mathbf{T}}=\u2329\mathit{\text{value}}\u232a$. Stepsize
$h=\u2329\mathit{\text{value}}\u232a$.
 ${\mathbf{IFAIL}}=25$

Repeated occurrences of input constraint violations have been detected. This could result in a potential infinite loop: ${\mathbf{ITASK}}=\u2329\mathit{\text{value}}\u232a$. Current violation corresponds to exit with ${\mathbf{IFAIL}}=\u2329\mathit{\text{value}}\u232a$.
 ${\mathbf{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.
 ${\mathbf{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.
 ${\mathbf{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. 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
${\mathbf{ITOL}}=0$ with
${\mathbf{ATOL}}\left(1\right)$ small but positive).
8 Parallelism and Performance
D02NEF is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
D02NEF 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 implementationspecific information.
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 banded systems the cost is proportional to ${\mathbf{NEQ}}\times {\left({\mathbf{ML}}+{\mathbf{MU}}+1\right)}^{2}$, while for full systems the cost is proportional to
${{\mathbf{NEQ}}}^{3}$. Note however that for moderately sized problems which are only mildly nonlinear the cost may be dominated by factors proportional to ${\mathbf{NEQ}}\times \left({\mathbf{ML}}+{\mathbf{MU}}+1\right)$ and ${{\mathbf{NEQ}}}^{2}$ respectively.
10 Example
For this routine two examples are presented. There is a single example program for D02NEF, with a main program and the code to solve the two example problems given in Example 1 (EX1) and Example 2 (EX2).
Example 1 (EX1)
This example solves the wellknown stiff Robertson problem written in implicit form
with initial conditions
$a=1.0$ and
$b=c=0.0$ over the range
$\left[0,0.1\right]$ the BDF method (setup routine
D02MWF and
D02NPF).
Example 2 (EX2)
This example illustrates the use of D02NEF to solve a simple algebraic problem by continuation. The equation $42y+0.1{e}^{y}t=0$ from $t=0$ (where $y=2$) to $t=1$.
10.1 Program Text
Program Text (d02nefe.f90)
10.2 Program Data
Program Data (d02nefe.d)
10.3 Program Results
Program Results (d02nefe.r)