d02nnf is a reverse communication routine for integrating stiff systems of implicit ordinary differential equations coupled with algebraic equations.

2 Specification

Fortran Interface

Subroutine d02nnf (

neq, ldysav, t, tout, y, ydot, rwork, rtol, atol, itol, inform, ysav, sdysav, wkjac, nwkjac, jacpvt, njcpvt, imon, inln, ires, irevcm, lderiv, itask, itrace, ifail)

Integer, Intent (In)	::	neq, ldysav, itol, sdysav, nwkjac, njcpvt, itask, itrace
Integer, Intent (Inout)	::	inform(23), jacpvt(njcpvt), imon, inln, ires, irevcm, 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)

C Header Interface

#include <nag.h>

void

d02nnf_ (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[], double ysav[], const Integer *sdysav, double wkjac[], const Integer *nwkjac, Integer jacpvt[], const Integer *njcpvt, Integer *imon, Integer *inln, Integer *ires, Integer *irevcm, logical lderiv[], const Integer *itask, const Integer *itrace, Integer *ifail)

The routine may be called by the names d02nnf or nagf_ode_ivp_stiff_imp_revcom.

3 Description

d02nnf 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

A (t, y) y^{'} = g (t, y) .

An outline of a typical calling program is given below:

!     Declarations 

      Call linear algebra setup routine 
      Call integrator setup routine 
      irevcm=0 
 1000 Call d02nnf(neq, neqmax, t, tout, y, ydot, rwork, rtol, 
       atol, itol, inform, ysave, ny2dim, wkjac, nwkjac, jacpvt, 
       njcpvt, imon, inln, ires, irevcm, lderiv, 
       itask, itrace, ifail)

      If (irevcm.gt.0) Then 
        If (irevcm.gt.7 .and. irevcm.lt.11) Then 
          If (irevcm.eq.8) Then 
            supply the Jacobian matrix                        (i) 
          Else If (irevcm.eq.9) Then 
            perform monitoring tasks requested by the user   (ii) 
          Else If (irevcm.eq.10) Then 
            indicates an unsuccessful step 
          End If 
        Else 
          evaluate the residual                             (iii) 
        Endif 
        Go To 1000 
      End If 

!     post processing (optional linear algebra diagnostic call 
!     (sparse case only), optional integrator diagnostic call) 

      Stop 
      End

There are three major operations that may be required of the calling subroutine on an intermediate return (

irevcm \neq 0

) from d02nnf; these are denoted (i), (ii) and (iii).

The following sections describe in greater detail exactly what is required of each of these operations.

(i)Supply the Jacobian matrix
You need only provide this facility if the argument $jceval ='A'$ (or $jceval ='F'$ if using sparse matrix linear algebra) in a call to the linear algebra setup routine (see jceval in d02nuf). If the Jacobian matrix is to be evaluated numerically by the integrator, then the remainder of section (i) can be ignored.

We must define the system of nonlinear equations which is solved internally by the integrator. The time derivative, $y^{'}$ , has the form

$y^{'} = (y - z) / (h d),$

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 $\frac{d}{d y^{'}} ( ) = (h d) \frac{d}{d y} ( )$ .

The system of nonlinear equations that is solved has the form

$A (t, y) y^{'} - g (t, y) = 0$

but is solved in the form

$f (t, y) = 0,$

where $f$ is the function defined by

$f (t, y) = (h d) (A (t, y) (y - z) / (h d) - g (t, y)) .$

It is the Jacobian matrix $\frac{\partial r}{\partial y}$ that you must supply as follows:

$\frac{\partial f_{i}}{\partial y_{j}} = a_{i j} (t, y) + h d \frac{\partial}{\partial y_{j}} (\sum_{k = 1}^{neq} a_{i k} (t, y) {y^{'}}_{k} - g_{i} (t, y)),$

where $t$ , $h$ and $d$ are located in $rwork (19)$ , $rwork (16)$ and $rwork (20)$ respectively and the arrays y and ydot contain the current solution and time derivatives respectively. Only the nonzero elements of the Jacobian need be set, since the locations where it is to be stored are preset to zero.

Hereafter in this document this operation will be referred to as JAC.

(ii)Perform tasks requested by you

This operation is essentially a monitoring function and additionally provides the opportunity of changing the current values of y, ydot, hnext (the step size that the integrator proposes to take on the next step), hmin (the minimum step size to be taken on the next step), and hmax (the maximum step size to be taken on the next step). The scaled local error at the end of a time step may be obtained by calling d02zaf as follows:

      ifail = 1
      errloc = d02zaf(neq,rowk(51+neqmax),rwork(51),ifail)
!     CHECK IFAIL BEFORE PROCEEDING

The following gives details of the location within the array rwork of variables that may be of interest to you:

Variable	Specification	Location
tcurr	the current value of the independent variable	$rwork (19)$
hlast	last step size successfully used by the integrator	$rwork (15)$
hnext	step size that the integrator proposes to take on the next step	$rwork (16)$
hmin	minimum step size to be taken on the next step	$rwork (17)$
hmax	maximum step size to be taken on the next step	$rwork (18)$
nqu	the order of the integrator used on the last step	$rwork (10)$

You are advised to consult the description of monitr in d02ngf for details on what optional input can be made.

If either y or ydot are changed, then imon must be set to

2

before return to d02nnf. If either of the values hmin or hmax are changed, then imon must be set

\geq 3

before return to d02nnf. If hnext is changed, then imon must be set to

4

before return to d02nnf.

In addition you can force d02nnf to evaluate the residual vector

A (t, y) y^{'} - g (t, y)

by setting

imon = 0

and

inln = 3

and then returning to d02nnf; on return to this monitoring operation the residual vector will be stored in

rwork (50 + 2 \times neq + i)

, for

i = 1, 2, \dots, neq

Hereafter in this document this operation will be referred to as MONITR.

(iii)Evaluate the residual
This operation must evaluate the residual

$- r = g (t, y) - A (t, y) y^{'}$ (1)

in one case and the reduced residual

$- \hat{r} = - A (t, y) y^{'}$ (2)

in another, where $t$ is located in $rwork (19)$ . The form of the residual that is returned is determined by the value of ires returned by d02nnf. If $ires = −1$ , then the residual defined by equation (2) above must be returned; if $ires = 1$ , then the residual returned by equation (1) above must be returned.

Hereafter in this document this operation will be referred to as RESID.

4 References

See the D02M–N Sub-chapter Introduction.

5 Arguments

Note: this routine uses reverse communication. Its use involves an initial entry, intermediate exits and re-entries, and a final exit, as indicated by the argument irevcm. Between intermediate exits and re-entries, all arguments other than ydot, rwork, wkjac, imon, inln and ires must remain unchanged.

1: $neq$ – Integer Input

On initial entry: the number of equations to be solved.

Constraint:

neq \geq 1

2: $ldysav$ – Integer Input

On initial entry: a bound on the maximum number of equations to be solved during the integration.

Constraint:

ldysav \geq neq

3: $t$ – Real (Kind=nag_wp) Input/Output

On initial 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 final exit: the value at which the computed solution

y

is returned (usually at tout).

4: $tout$ – Real (Kind=nag_wp) Input/Output

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

Constraint:

tout \neq t

On exit: is unaltered unless

itask = 6

and

lderiv (2) = .TRUE.

on entry (see also itask and lderiv) in which case tout will be set to the result of taking a small step at the start of the integration.

5: $y (neq)$ – Real (Kind=nag_wp) array Input/Output

On initial 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 final exit: the computed solution vector evaluated at t (usually

t = tout

6: $ydot (neq)$ – Real (Kind=nag_wp) array Input/Output

On initial entry: if

lderiv (1) = .TRUE.

, ydot must contain approximations to the time derivatives

y^{'}

of the vector

y

. If

lderiv (1) = .FALSE.

, ydot need not be set on entry.

On final exit: contains the time derivatives

y^{'}

of the vector

y

at the last integration point.

7: $rwork (50 + 4 \times neq)$ – Real (Kind=nag_wp) array Communication Array

On initial entry: must be the same array as used by one of the method setup routines d02mvf, d02nvf or d02nwf, and by one of the storage setup routines d02nsf, d02ntf or d02nuf. The contents of rwork must not be changed between any call to a setup routine and the first call to d02nnf.

On intermediate re-entry: must contain residual evaluations as described under the argument irevcm.

On intermediate exit: contains information for jac, resid and monitr operations as described under Section 3 and the argument irevcm.

8: $rtol (*)$ – Real (Kind=nag_wp) array Input

Note: the dimension of the array rtol must be at least

1

itol = 1

2

, and at least

neq

otherwise.

On initial entry: the relative local error tolerance.

Constraint:

rtol (i) \geq 0.0

for all relevant

i

(see itol).

9: $atol (*)$ – Real (Kind=nag_wp) array Input

Note: the dimension of the array atol must be at least

1

itol = 1

3

, and at least

neq

otherwise.

On initial entry: the absolute local error tolerance.

Constraint:

atol (i) \geq 0.0

for all relevant

i

(see itol).

10: $itol$ – Integer Input

On initial entry: a value to indicate the form of the local error test. itol indicates to d02nnf whether to interpret either or both of rtol or atol as a vector or a scalar. The error test to be satisfied is

‖ e_{i} / w_{i} ‖ < 1.0

, where

w_{i}

is defined as follows:

itol	rtol	atol	$w_{i}$
1	scalar	scalar	$rtol (1) \times \| y_{i} \| + atol (1)$
2	scalar	vector	$rtol (1) \times \| y_{i} \| + atol (i)$
3	vector	scalar	$rtol (i) \times \| y_{i} \| + atol (1)$
4	vector	vector	$rtol (i) \times \| y_{i} \| + atol (i)$

e_{i}

is an estimate of the local error in

y_{i}

, 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

4

11: $inform (23)$ – Integer array Communication Array

12: $ysav (ldysav, sdysav)$ – Real (Kind=nag_wp) array Communication Array

13: $sdysav$ – Integer Input

On initial entry: the second dimension of the array ysav as declared in the (sub)program from which d02nnf 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.

14: $wkjac (nwkjac)$ – Real (Kind=nag_wp) array Input/Output

On intermediate re-entry: elements of the Jacobian as defined under the description of irevcm. If a numerical Jacobian was requested then wkjac is used for workspace.

On intermediate exit: the Jacobian is overwritten.

15: $nwkjac$ – Integer Input

On initial entry: the dimension of the array wkjac as declared in the (sub)program from which d02nnf is called. The actual size depends on the linear algebra method used. An appropriate value for nwkjac is described in the specifications of the linear algebra setup routines d02nsf, d02ntf and d02nuf for full, banded and sparse matrix linear algebra respectively. This value must be the same as that supplied to the linear algebra setup routine.

16: $jacpvt (njcpvt)$ – Integer array Communication Array

17: $njcpvt$ – Integer Input

On initial entry: the dimension of the array jacpvt as declared in the (sub)program from which d02nnf is called. The actual size depends on the linear algebra method used. An appropriate value for njcpvt is described in the specifications of the linear algebra setup routines d02ntf and d02nuf for banded and sparse matrix linear algebra respectively. This value must be the same as that supplied to the linear algebra setup routine. When full matrix linear algebra is chosen, the array jacpvt is not used and hence njcpvt should be set to

1

18: $imon$ – Integer Input/Output

On intermediate exit: used to pass information between d02nnf and the monitr operation (see Section 3). With

irevcm = 9

, imon contains a flag indicating under what circumstances the return from d02nnf occurred:

$imon = −2$: Exit from d02nnf after $ires = 4$ (set in the resid operation (see Section 3) caused an early termination (this facility could be used to locate discontinuities).
$imon = −1$: The current step failed repeatedly.
$imon = 0$: Exit from d02nnf after a call to the internal nonlinear equation solver.
$imon = 1$: The current step was successful.

On intermediate re-entry: may be reset to determine subsequent action in d02nnf.

$imon = −2$: Integration is to be halted. A return will be made from d02nnf to the calling (sub)program with $ifail = 12$ .
$imon = −1$: Allow d02nnf to continue with its own internal strategy. The integrator will try up to three restarts unless $imon \neq −1$ .
$imon = 0$: Return to the internal nonlinear equation solver, where the action taken is determined by the value of inln.
$imon = 1$: Normal exit to d02nnf 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 internal initialization module solves for new values of $y$ and $y^{'}$ by using the values supplied in y and ydot by the monitr operation (see Section 3) as initial estimates.
$imon = 3$: Try to continue with the same step size and order as was to be used before entering the monitr operation (see Section 3). 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.

19: $inln$ – Integer Input/Output

On intermediate re-entry: with

imon = 0

and

irevcm = 9

, inln specifies the action to be taken by the internal nonlinear equation solver. By setting

inln = 3

and returning to d02nnf, the residual vector is evaluated and placed in

rwork (50 + 2 \times neq + i)

, for

i = 1, 2, \dots, neq

and then the monitr operation (see Section 3) is invoked again. At present this is the only option available: inln must not be set to any other value.

On intermediate exit: contains a flag indicating the action to be taken, if any, by the internal nonlinear equation solver.

20: $ires$ – Integer Input/Output

On intermediate exit: with

irevcm = 1

2

3

4

5

6

7

11

, ires specifies the form of the residual to be returned by the resid operation (see Section 3).

ires = 1

- r = g (t, y) - A (t, y) y^{'}

must be returned.

ires = −1

- \hat{r} = - A (t, y) y^{'}

must be returned.

On intermediate re-entry: should be unchanged unless one of the following actions is required of d02nnf in which case ires should be set accordingly.

$ires = 2$: Indicates to d02nnf that control should be passed back immediately to the calling (sub)program with the error indicator set to $ifail = 11$ .
$ires = 3$: Indicates to d02nnf 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 d02nnf returns to the calling (sub)program with the error indicator set to $ifail = 7$ .
$ires = 4$: Indicates to d02nnf to stop its current operation and to enter the monitr operation (see Section 3) immediately.

21: $irevcm$ – Integer Input/Output

On initial entry: must contain

0

On intermediate re-entry: should remain unchanged.

On intermediate exit: indicates what action you must take before re-entering d02nnf. The possible exit values of irevcm are

1

2

3

4

5

6

7

8

9

10

11

which should be interpreted as follows:

$irevcm = 1$ , $2$ , $3$ , $4$ , $5$ , $6$ , $7$ or $11$

Indicates that a resid operation (see Section 3) is required: you must supply the residual of the system. For each of these values of irevcm,

y_{i}

is located in

y (i)

, for

i = 1, 2, \dots, neq

For

irevcm = 1

3

6

11

y_{i}^{'}

is located in

ydot (i)

and

r_{i}

should be stored in

rwork (50 + 2 \times neq + i)

, for

i = 1, 2, \dots, neq

For

irevcm = 2

y_{i}^{'}

is located in

rwork (50 + neq + i)

and

r_{i}

should be stored in

rwork (50 + 2 \times neq + i)

, for

i = 1, 2, \dots, neq

For

irevcm = 4

7

y_{i}^{'}

is located in

ydot (i)

and

r_{i}

should be stored in

rwork (50 + neq + i)

, for

i = 1, 2, \dots, neq

For

irevcm = 5

y_{i}^{'}

is located in

rwork (50 + 2 \times neq + i)

and

r_{i}

should be stored in

ydot (i)

, for

i = 1, 2, \dots, neq

$irevcm = 8$

Indicates that a jac operation (see Section 3) is required: you must supply the Jacobian matrix.

If full matrix linear algebra is being used, the

(i, j)

th element of the Jacobian must be stored in

wkjac ((j - 1) \times neq + i)

If banded matrix linear algebra is being used, the

(i, j)

th element of the Jacobian
must be stored in

wkjac ((i - 1) \times m_{B} + k)

, where

m_{B} = m_{L} + m_{U} + 1

and

k = \min (m_{L} - i + 1, 0) + j

; here

m_{L}

and

m_{U}

are the number of subdiagonals and superdiagonals, respectively, in the band.

If sparse matrix linear algebra is being used, d02nrf must be called to determine which column of the Jacobian is required and where it should be stored.

Call d02nrf(j, iplace, inform)

will return in j the number of the column of the Jacobian that is required and will set

iplace = 1

2

(see d02nrf). If

iplace = 1

, you must store the nonzero element

(i, j)

of the Jacobian in

rwork (50 + 2 \times neq + i)

; otherwise it must be stored in

rwork (50 + neq + i)

$irevcm = 9$

Indicates that a monitr operation (see Section 3) can be performed.

$irevcm = 10$

Indicates that the current step was not successful, due to error test failure or convergence test failure. The only information supplied to you on this return is the current value of the variable

t

, located in

rwork (19)

. No values must be changed before re-entering d02nnf; this facility enables you to determine the number of unsuccessful steps.

On final exit:

irevcm = 0

indicating that the user-specified task has been completed or an error has been encountered (see the descriptions for itask and ifail).

Constraint:

0 \leq irevcm \leq 11

Note: any values you return to d02nnf as part of the reverse communication procedure should not include floating-point NaN (Not a Number) or infinity values, since these are not handled by d02nnf. If your code does inadvertently return any NaNs or infinities, d02nnf is likely to produce unexpected results.

22: $lderiv (2)$ – Logical array Input/Output

On initial entry:

lderiv (1)

must be set to .TRUE. if you have supplied both an initial

y

and an initial

y^{'}

lderiv (1)

must be set to .FALSE. if only the initial

y

has been supplied.

lderiv (2)

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.

lderiv (2)

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.

lderiv (2) = .TRUE.

is recommended if there are implicit equations or the initial

y

and

y^{'}

are zero.

On final exit:

lderiv (1)

is normally unchanged. However if

itask = 6

and internal initialization was successful then

lderiv (1) = .TRUE.

lderiv (2) = .TRUE.

, if implicit equations were detected. Otherwise

lderiv (2) = .FALSE.

23: $itask$ – Integer Input

On initial entry: the task to be performed by the integrator.

$itask = 1$: Normal computation of output values of $y (t)$ 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 $y (t)$ 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 (e.g., see d02nvf) 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 (e.g., see d02nvf). tcrit must be specified 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 d02nnf is recalled with a different value of itask (and tout altered) then the initialization procedure is repeated, possibly leading to different initial conditions.

Constraint:

1 \leq itask \leq 6

24: $itrace$ – Integer Input

On initial entry: the level of output that is printed by the integrator. itrace may take the value

−1

0

1

2

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.

25: $ifail$ – Integer Input/Output

On entry: ifail must be set to

0

−1

1

to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of

0

causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of

−1

means that an error message is printed while a value of

1

means that it is not.

If halting is not appropriate, the value

−1

1

is recommended. If message printing is undesirable, then the value

1

is recommended. Otherwise, the value

−1

is recommended since useful values can be provided in some output arguments even when

ifail \neq 0

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

−1

, explanatory error messages are output on the current error message unit (as defined by x04aaf).

Errors or warnings detected by the routine:

Note: in some cases d02nnf may return useful information.

$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 ⟩$ , njcpvt (setup) $= ⟨ value ⟩$ .

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 ⟩$ , nwkjac (setup) $= ⟨ value ⟩$ .

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

$itask = 3$ and tout is more than an integration step behind the current time.
$tout = ⟨ value ⟩$ , current time minus step size: $⟨ value ⟩$ .

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: $atol \geq 0.0$ .

On entry, $ires = ⟨ value ⟩$ and $\frac{d y}{d t} = 0.0$ for all elements.
Check the evaluation of the residual for this value of ires.

On entry, $irevcm = ⟨ value ⟩$ .
Constraint: $0 \leq irevcm \leq 11$ .

On entry, $itask = ⟨ value ⟩$ .
Constraint: $1 \leq itask \leq 5$ .

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: $1 \leq itol \leq 4$ .

On entry, $neq = ⟨ value ⟩$ .
Constraint: $neq \geq 1$ .

On entry, $neq = ⟨ value ⟩$ and $ldysav = ⟨ value ⟩$ .
Constraint: $neq \leq ldysav$ .

On entry, $rtol = ⟨ value ⟩$ .
Constraint: $rtol \geq 0.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 ⟩$ .

On re-entry, $imon = ⟨ value ⟩$ .
Constraint: $−2 \leq imon \leq 4$ .

On re-entry, $inln = ⟨ value ⟩$ for the case $irevcm = 9$ and $imon = 0$ .
Constraint: $inln = 3$ .

On re-entry, ires has been set to an illegal value during initialization.
$ires = ⟨ value ⟩$ at time $⟨ value ⟩$ .

On re-entry, the solution vector appears to have been overwritten.
Further integration will not be attempted.

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.
$atol (i)$ and $y (i)$ 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 ⟩$ .

$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 $y (1), y (2), \dots, y (neq)$ 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$: Nonlinear solver failed to converge using a damped Newton method to solve for initial values.
Damping factor: $⟨ value ⟩$ ; convergence rate: $⟨ value ⟩$ .

$ifail = 6$: At time $⟨ value ⟩$ , error weight $⟨ value ⟩$ became zero. Check the values of atol, rtol and itol supplied.

$ifail = 7$: On re-entry, $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 ⟩$ .

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

Workspace error occurred when trying to form the Jacobian matrix in calculating the initial values of the solution and its time derivative.

$ifail = 11$: On re-entry, $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 $itask \neq 2$ 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 = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$ifail = - 999$: Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface 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

atol (1)

small but positive).

8 Parallelism and Performance

d02nnf is not thread safe and should not be called from a multithreaded user program. Please see Section 1 in FL Interface Multithreading for more information on thread safety.

d02nnf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.

d02nnf 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

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; also on the type of linear algebra being used. For further details see Section 9 in d02ngf, d02nhf and d02njf of the documents for d02ngf (full matrix), d02nhf (banded matrix) or d02njf (sparse matrix).

In general, you are advised to choose the Backward Differentiation Formula option (setup routine d02nvf) but if efficiency is of great importance and especially if it is suspected that

\frac{\partial}{\partial y} (A^{- 1} g)

has complex eigenvalues near the imaginary axis for some part of the integration, you should try the BLEND option (setup routine d02nwf).

10 Example

We solve the well-known stiff Robertson problem written as a differential system in implicit form

\begin{array}{l} r_{1} = (a^{'} + b^{'} + c^{'}) \\ r_{2} = 0.04 a - 1.0 E 4 b c - 3.0 E 7 b^{2} - b^{'} \\ r_{3} = 3.0 E 7 b^{2} - c^{'} \end{array}

over the range

[0, 10]

with initial conditions

a = 1.0

and

b = c = 0.0

and with scalar error control (

itol = 1

). We integrate to the first internal integration point past

tout = 10.0

(

itask = 3

), using a BDF method (setup routine d02mvf) and a modified Newton method. We treat the Jacobian as sparse (setup routine d02nuf) and we calculate it analytically. In this program we also illustrate the monitoring of step failures (

irevcm = 10

) and the forcing of a return when the component falls below

0.9

in the evaluation of the residual by setting

ires = 2

d02nn: FL CL CPP AD

NAG FL Interfaced02nnf (ivp_​stiff_​imp_​revcom)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG FL Interface
d02nnf (ivp_stiff_imp_revcom)