NAG Toolbox: nag_ode_ivp_stiff_imp_revcom (d02nn)

Purpose

Syntax

Description

% 
% data initialization
% 
call linear algebra setup routine 
call integrator setup routine 
irevcm = int32(0);
[..., irevcm, ...] = d02nn();
while (irevcm > 0)
  if (irevcm > 7 and irevcm < 11)
    if (irevcm == 8)
      supply the jacobian matrix                              (i)
    elseif (irevcm == 9)
      perform monitoring tasks requested by the user         (ii)
    elseif (irevcm == 10)
      indicates an unsuccessful step 
    end  else    evaluate the residual                                   (iii)
  end 
  [..., irevcm, ...] = d02nn();
end
% 
% post processing (optional linear algebra diagnostic call 
% (sparse case only), optional integrator diagnostic call) 
%

[errloc, ifail] = d02za(rwork(51+neqmax:51+neqmax+neq-1), rwork(51:51+neq-1));
% Check ifail before proceeding

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{t}$ – double scalar

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.

2:     $\mathrm{tout}$ – double scalar

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: $\mathbf{tout}\ne \mathbf{t}$.

3:     $\mathrm{y}\left(\mathbf{neq}\right)$ – double array

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.

4:     $\mathrm{ydot}\left(\mathbf{neq}\right)$ – double array

On initial entry: if $\mathbf{lderiv}\left(1\right)=\mathit{true}$, ydot must contain approximations to the time derivatives $y^{\prime }$ of the vector $y$. If $\mathbf{lderiv}\left(1\right)=\mathit{false}$, then ydot need not be set on entry.

5:     $\mathrm{rwork}\left(50+4\times \mathbf{neq}\right)$ – double array

On initial entry: must be the same array as used by one of the method setup functions nag_ode_ivp_stiff_dassl (d02mv), nag_ode_ivp_stiff_bdf (d02nv) or nag_ode_ivp_stiff_blend (d02nw), and by one of the storage setup functions nag_ode_ivp_stiff_fulljac_setup (d02ns), nag_ode_ivp_stiff_bandjac_setup (d02nt) or nag_ode_ivp_stiff_sparjac_setup (d02nu). The contents of rwork must not be changed between any call to a setup function and the first call to nag_ode_ivp_stiff_imp_revcom (d02nn).

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

6:     $\mathrm{rtol}\left(:\right)$ – double array

The dimension of the array rtol must be at least $1$ if $\mathbf{itol}=1$ or $2$, and at least $\mathbf{neq}$ otherwise

On initial entry: the relative local error tolerance.

Constraint: $\mathbf{rtol}\left(i\right)\ge 0.0$ for all relevant $i$ (see itol).

7:     $\mathrm{atol}\left(:\right)$ – double array

The dimension of the array atol must be at least $1$ if $\mathbf{itol}=1$ or $3$, and at least $\mathbf{neq}$ otherwise

On initial entry: the absolute local error tolerance.

Constraint: $\mathbf{atol}\left(i\right)\ge 0.0$ for all relevant $i$ (see itol).

8:     $\mathrm{itol}$ – int64int32nag_int scalar

On initial entry: a value to indicate the form of the local error test. itol indicates to nag_ode_ivp_stiff_imp_revcom (d02nn) 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	$\mathbf{rtol}\left(1\right)\times \left|y_i\right|+\mathbf{atol}\left(1\right)$
2	scalar	vector	$\mathbf{rtol}\left(1\right)\times \left|y_i\right|+\mathbf{atol}\left(i\right)$
3	vector	scalar	$\mathbf{rtol}\left(i\right)\times \left|y_i\right|+\mathbf{atol}\left(1\right)$
4	vector	vector	$\mathbf{rtol}\left(i\right)\times \left|y_i\right|+\mathbf{atol}\left(i\right)$

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

Constraint: $\mathbf{itol}=1$, $2$, $3$ or $4$.

9:     $\mathrm{inform}\left(23\right)$ – int64int32nag_int array

10:   $\mathrm{ysav}\left(\mathit{ldysav},\mathbf{sdysav}\right)$ – double array

11:   $\mathrm{wkjac}\left(\mathbf{nwkjac}\right)$ – double array

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.

12:   $\mathrm{jacpvt}\left(\mathit{njcpvt}\right)$ – int64int32nag_int array

On initial entry: the dimension of the array jacpvt. 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 functions nag_ode_ivp_stiff_bandjac_setup (d02nt) and nag_ode_ivp_stiff_sparjac_setup (d02nu) for banded and sparse matrix linear algebra respectively. This value must be the same as that supplied to the linear algebra setup function. When full matrix linear algebra is chosen, the array jacpvt is not used and hence njcpvt should be set to $1$.

13:   $\mathrm{imon}$ – int64int32nag_int scalar

On intermediate re-entry: may be reset to determine subsequent action in nag_ode_ivp_stiff_imp_revcom (d02nn).

$\mathbf{imon}=-2$

Integration is to be halted. A return will be made from nag_ode_ivp_stiff_imp_revcom (d02nn) to the calling (sub)program with $\mathbf{ifail}=\mathbf{12}$.

$\mathbf{imon}=-1$

Allow nag_ode_ivp_stiff_imp_revcom (d02nn) to continue with its own internal strategy. The integrator will try up to three restarts unless $\mathbf{imon}\ne -1$.

$\mathbf{imon}=0$

Return to the internal nonlinear equation solver, where the action taken is determined by the value of inln.

$\mathbf{imon}=1$

Normal exit to nag_ode_ivp_stiff_imp_revcom (d02nn) to continue integration.

$\mathbf{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^{\prime }$ by using the values supplied in y and ydot by the monitr operation (see Description) as initial estimates.

$\mathbf{imon}=3$

Try to continue with the same step size and order as was to be used before entering the monitr operation (see Description). hmin and hmax may be altered if desired.

$\mathbf{imon}=4$

Continue the integration but using a new value of hnext and possibly new values of hmin and hmax.

14:   $\mathrm{inln}$ – int64int32nag_int scalar

On intermediate re-entry: with $\mathbf{imon}=0$ and $\mathbf{irevcm}=9$, inln specifies the action to be taken by the internal nonlinear equation solver. By setting $\mathbf{inln}=3$ and returning to nag_ode_ivp_stiff_imp_revcom (d02nn), the residual vector is evaluated and placed in $\mathbf{rwork}\left(50+2\times \mathbf{neq}+\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{neq}$ and then the monitr operation (see Description) is invoked again. At present this is the only option available: inln must not be set to any other value.

15:   $\mathrm{ires}$ – int64int32nag_int scalar

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

$\mathbf{ires}=2$

Indicates to nag_ode_ivp_stiff_imp_revcom (d02nn) that control should be passed back immediately to the calling (sub)program with the error indicator set to $\mathbf{ifail}=\mathbf{11}$.

$\mathbf{ires}=3$

Indicates to nag_ode_ivp_stiff_imp_revcom (d02nn) 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 nag_ode_ivp_stiff_imp_revcom (d02nn) returns to the calling (sub)program with the error indicator set to $\mathbf{ifail}=\mathbf{7}$.

$\mathbf{ires}=4$

Indicates to nag_ode_ivp_stiff_imp_revcom (d02nn) to stop its current operation and to enter the monitr operation (see Description) immediately.

16:   $\mathrm{irevcm}$ – int64int32nag_int scalar

On initial entry: must contain $0$.

On intermediate re-entry: should remain unchanged.

Constraint: $0\le \mathbf{irevcm}\le 11$.

17:   $\mathrm{lderiv}\left(2\right)$ – logical array

On initial entry: $\mathbf{lderiv}\left(1\right)$ must be set to true if you have supplied both an initial $y$ and an initial $y^{\prime }$. $\mathbf{lderiv}\left(1\right)$ must be set to false if only the initial $y$ has been supplied.

$\mathbf{lderiv}\left(2\right)$ must be set to true if the integrator is to use a modified Newton method to evaluate the initial $y$ and $y^{\prime }$. Note that $y$ and $y^{\prime }$, if supplied, are used as initial estimates. This method involves taking a small step at the start of the integration, and if $\mathbf{itask}=6$ on entry, t and tout will be set to the result of taking this small step. $\mathbf{lderiv}\left(2\right)$ must be set to false if the integrator is to use functional iteration to evaluate the initial $y$ and $y^{\prime }$, and if this fails a modified Newton method will then be attempted. $\mathbf{lderiv}\left(2\right)=\mathit{true}$ is recommended if there are implicit equations or the initial $y$ and $y^{\prime }$ are zero.

18:   $\mathrm{itask}$ – int64int32nag_int scalar

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

$\mathbf{itask}=1$

Normal computation of output values of $y\left(t\right)$ at $t=\mathbf{tout}$ (by overshooting and interpolating).

$\mathbf{itask}=2$

Take one step only and return.

$\mathbf{itask}=3$

Stop at the first internal integration point at or beyond $t=\mathbf{tout}$ and return.

$\mathbf{itask}=4$

Normal computation of output values of $y\left(t\right)$ at $t=\mathbf{tout}$ but without overshooting $t=\mathbf{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 (e.g., see nag_ode_ivp_stiff_bdf (d02nv)) may be equal to or beyond tout, but not before it in the direction of integration.

$\mathbf{itask}=5$

Take one step only and return, without passing tcrit (e.g., see nag_ode_ivp_stiff_bdf (d02nv)). tcrit must be specified under $\mathbf{itask}=4$.

$\mathbf{itask}=6$

The integrator will solve for the initial values of $y$ and $y^{\prime }$ 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^{\prime }$. 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_revcom (d02nn) 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\le \mathbf{itask}\le 6$.

19:   $\mathrm{itrace}$ – int64int32nag_int scalar

On initial entry: the level of output that is printed by the integrator. itrace may take the value $-1$, $0$, $1$, $2$ or $3$.

$\mathbf{itrace}<-1$

$-1$ is assumed and similarly if $\mathbf{itrace}>3$, then $3$ is assumed.

$\mathbf{itrace}=-1$

No output is generated.

$\mathbf{itrace}=0$

Only warning messages are printed on the current error message unit (see nag_file_set_unit_error (x04aa)).

$\mathbf{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:     $\mathrm{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.)

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

Constraint: $\mathbf{neq}\ge 1$.

2:     $\mathrm{sdysav}$ – int64int32nag_int scalar

Default: the second dimension of the array ysav.

On initial entry: 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.

3:     $\mathrm{nwkjac}$ – int64int32nag_int scalar

Default: the dimension of the array wkjac.

On initial entry: the dimension of the array wkjac. 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 functions nag_ode_ivp_stiff_fulljac_setup (d02ns), nag_ode_ivp_stiff_bandjac_setup (d02nt) and nag_ode_ivp_stiff_sparjac_setup (d02nu) for full, banded and sparse matrix linear algebra respectively. This value must be the same as that supplied to the linear algebra setup function.

Output Parameters

1:     $\mathrm{t}$ – double scalar

On final exit: the value at which the computed solution $y$ is returned (usually at tout).

2:     $\mathrm{tout}$ – double scalar

Is unaltered unless $\mathbf{itask}=6$ and $\mathbf{lderiv}\left(2\right)=\mathit{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.

3:     $\mathrm{y}\left(\mathbf{neq}\right)$ – double array

On final exit: the computed solution vector evaluated at t (usually $t=\mathbf{tout}$).

4:     $\mathrm{ydot}\left(\mathbf{neq}\right)$ – double array

On final exit: contains the time derivatives $y^{\prime }$ of the vector $y$ at the last integration point.

5:     $\mathrm{rwork}\left(50+4\times \mathbf{neq}\right)$ – double array

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

6:     $\mathrm{inform}\left(23\right)$ – int64int32nag_int array

7:     $\mathrm{ysav}\left(\mathit{ldysav},\mathbf{sdysav}\right)$ – double array

8:     $\mathrm{wkjac}\left(\mathbf{nwkjac}\right)$ – double array

On intermediate exit: the Jacobian is overwritten.

9:     $\mathrm{jacpvt}\left(\mathit{njcpvt}\right)$ – int64int32nag_int array

10:   $\mathrm{imon}$ – int64int32nag_int scalar

On intermediate exit: used to pass information between nag_ode_ivp_stiff_imp_revcom (d02nn) and the monitr operation (see Description). With $\mathbf{irevcm}=9$, imon contains a flag indicating under what circumstances the return from nag_ode_ivp_stiff_imp_revcom (d02nn) occurred:

$\mathbf{imon}=-2$

Exit from nag_ode_ivp_stiff_imp_revcom (d02nn) after $\mathbf{ires}=4$ (set in the resid operation (see Description) caused an early termination (this facility could be used to locate discontinuities).

$\mathbf{imon}=-1$

The current step failed repeatedly.

$\mathbf{imon}=0$

Exit from nag_ode_ivp_stiff_imp_revcom (d02nn) after a call to the internal nonlinear equation solver.

$\mathbf{imon}=1$

The current step was successful.

11:   $\mathrm{inln}$ – int64int32nag_int scalar

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

12:   $\mathrm{ires}$ – int64int32nag_int scalar

On intermediate exit: with $\mathbf{irevcm}=1$, $2$, $3$, $4$, $5$, $6$, $7$ or $11$, ires specifies the form of the residual to be returned by the resid operation (see Description).

If $\mathbf{ires}=1$, then $-r=g\left(t,y\right)-A\left(t,y\right)y^{\prime }$ must be returned.

If $\mathbf{ires}=-1$, then $-\hat{r}=-A\left(t,y\right)y^{\prime }$ must be returned.

13:   $\mathrm{irevcm}$ – int64int32nag_int scalar

On intermediate exit: indicates what action you must take before re-entering nag_ode_ivp_stiff_imp_revcom (d02nn). The possible exit values of irevcm are $1$, $2$, $3$, $4$, $5$, $6$, $7$, $8$, $9$, $10$ or $11$ which should be interpreted as follows:

$\mathbf{irevcm}=1$, $2$, $3$, $4$, $5$, $6$, $7$ or $11$

Indicates that a resid operation (see Description) is required: you must supply the residual of the system. For each of these values of irevcm, $y_{\mathit{i}}$ is located in $\mathbf{y}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{neq}$.

For $\mathbf{irevcm}=1$, $3$, $6$ or $11$, $y_{\mathit{i}}^{\prime }$ is located in $\mathbf{ydot}\left(\mathit{i}\right)$ and $r_{\mathit{i}}$ should be stored in $\mathbf{rwork}\left(50+2\times \mathbf{neq}+\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{neq}$.

For $\mathbf{irevcm}=2$, $y_{\mathit{i}}^{\prime }$ is located in $\mathbf{rwork}\left(50+\mathbf{neq}+\mathit{i}\right)$ and $r_{\mathit{i}}$ should be stored in $\mathbf{rwork}\left(50+2\times \mathbf{neq}+\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{neq}$.

For $\mathbf{irevcm}=4$ or $7$, $y_{\mathit{i}}^{\prime }$ is located in $\mathbf{ydot}\left(\mathit{i}\right)$ and $r_{\mathit{i}}$ should be stored in $\mathbf{rwork}\left(50+\mathbf{neq}+\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{neq}$.

For $\mathbf{irevcm}=5$, $y_{\mathit{i}}^{\prime }$ is located in $\mathbf{rwork}\left(50+2\times \mathbf{neq}+\mathit{i}\right)$ and $r_{\mathit{i}}$ should be stored in $\mathbf{ydot}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,\mathbf{neq}$.

$\mathbf{irevcm}=8$

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

If full matrix linear algebra is being used, then the $\left(i,j\right)$th element of the Jacobian must be stored in $\mathbf{wkjac}\left(\left(j-1\right)\times \mathbf{neq}+i\right)$.

If banded matrix linear algebra is being used, then the $\left(i,j\right)$th element of the Jacobian
must be stored in $\mathbf{wkjac}\left(\left(i-1\right)\times m_B+k\right)$, where $m_B=m_L+m_U+1$ and $k=\min \left(m_L-i+1,0\right)+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, then nag_ode_ivp_stiff_sparjac_enq (d02nr) must be called to determine which column of the Jacobian is required and where it should be stored.

 [j, iplace] = d02nr(inform); 

will return in j the number of the column of the Jacobian that is required and will set $\mathbf{iplace}=1$ or $2$ (see nag_ode_ivp_stiff_sparjac_enq (d02nr)). If $\mathbf{iplace}=1$, you must store the nonzero element $\left(i,j\right)$ of the Jacobian in $\mathbf{rwork}\left(50+2\times \mathbf{neq}+i\right)$; otherwise it must be stored in $\mathbf{rwork}\left(50+\mathbf{neq}+i\right)$.

$\mathbf{irevcm}=9$

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

$\mathbf{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 $\mathbf{rwork}\left(19\right)$. No values must be changed before re-entering nag_ode_ivp_stiff_imp_revcom (d02nn); this facility enables you to determine the number of unsuccessful steps.

On final exit: $\mathbf{irevcm}=0$ indicating that the user-specified task has been completed or an error has been encountered (see the descriptions for itask and ifail).

14:   $\mathrm{lderiv}\left(2\right)$ – logical array

On final exit: $\mathbf{lderiv}\left(1\right)$ is normally unchanged. However if $\mathbf{itask}=6$ and internal initialization was successful then $\mathbf{lderiv}\left(1\right)=\mathit{true}$.

$\mathbf{lderiv}\left(2\right)=\mathit{true}$, if implicit equations were detected. Otherwise $\mathbf{lderiv}\left(2\right)=\mathit{false}$.

15:   $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

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

   $\mathbf{ifail}=1$

On entry, the integrator detected an illegal input, or that a linear algebra and/or integrator setup function has not been called prior to the call to the integrator. If $\mathbf{itrace}\ge 0$, the form of the error will be detailed on the current error message unit (see nag_file_set_unit_error (x04aa)).

   $\mathbf{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  $\mathbf{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 $\mathbf{y}\left(1\right),\mathbf{y}\left(2\right),\dots ,\mathbf{y}\left(\mathbf{neq}\right)$ contain the computed values of the solution at the current point t.

W  $\mathbf{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  $\mathbf{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  $\mathbf{ifail}=6$

Some error weight $w_i$ became zero during the integration (see the description of itol). Pure relative error control ($\mathbf{atol}\left(i\right)=0.0$) was requested on a variable (the $i$th) which has now vanished. The integration was successful as far as t.

   $\mathbf{ifail}=7$

The resid operation (see Description) set the error flag $\mathbf{ires}=3$ continually despite repeated attempts by the integrator to avoid this.

   $\mathbf{ifail}=8$

$\mathbf{lderiv}\left(1\right)=\mathit{false}$ on entry but the internal initialization function was unable to initialize $y^{\prime }$ (more detailed information may be directed to the current error message unit, see nag_file_set_unit_error (x04aa)).

   $\mathbf{ifail}=9$

A singular Jacobian $\frac{\partial r}{\partial y}$ has been encountered. You should check the problem formulation and Jacobian calculation.

   $\mathbf{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  $\mathbf{ifail}=11$

The resid operation (see Description) signalled the integrator to halt the integration and return by setting $\mathbf{ires}=2$. Integration was successful as far as t.

W  $\mathbf{ifail}=12$

The monitr operation (see Description) set $\mathbf{imon}=-2$ and so forced a return but the integration was successful as far as t.

W  $\mathbf{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 $\mathbf{itask}\ne 2$ or $5$.)

   $\mathbf{ifail}=14$

The values of rtol and atol are so small that nag_ode_ivp_stiff_imp_revcom (d02nn) is unable to start the integration.

   $\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: d02nn_example

function d02nn_example


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

% Initialize integration method setup variables and arrays.
neq    = int64(3);
neqmax = int64(neq);
nwkjac = int64(neqmax*(neqmax + 1));
maxord = int64(5);
sdysav = int64(maxord+1);
maxstp = int64(200);
mxhnil = int64(5);

h0    = 0;
hmax  = 10;
hmin  = 1.0e-10;
tcrit = 0;
petzld = false;

const  = zeros(6, 1);
rwork  = zeros(50+4*neqmax, 1);

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

% Sparse Jacobian supplied, setup
ia     = int64(0);
ja     = int64(0);
njcpvt = int64(150);
nwkjac = int64(100);
eta    = 1.0e-4;
u      = 0.1;
sens   = 0.0;
lblock = true;

[jacpvt, rwork, ifail] = d02nu(...
    neq, neqmax, 'Analytical', nwkjac, ia, ja, ...
    njcpvt, sens, u, eta, lblock, rwork);

% Integration input variable intialization
t      = 0;
tout   = 10;
y      = [1; 0; 0];
ydot   = [0; 0; 0];
rtol   = [0.0001];
atol   = [1e-07];
itol   = int64(1);
inform = zeros(23, 1, 'int64');
ysave  = zeros(neq, sdysav);
wkjac  = zeros(nwkjac,1);
imon   = int64(0);
inln   = int64(0);
ires   = int64(1);
irevcm = int64(0);
lderiv = [false; false];
itask  = int64(3);
itrace = int64(0);

nfails = 0;

% pointers into rwork locations
lacorb = neqmax + 50;
lsavrb = lacorb + neqmax;
l1 = lsavrb+1; l2 = l1+1; l3 = l2+1;
m1 = lacorb+1; m2 = m1+1; m3 = m2+1;

fprintf('  Analytic Jacobian\n\n');
fprintf('     x           y_1          y_2           y_3\n');
fprintf(' %8.3f      %5.1f        %5.1f         %5.1f\n', t, y);
first_time = true;

% Main reverse communication loop controlled by irevcm

while (irevcm ~= 0 || first_time)
  first_time = false;

  [t, tout, y, ydot, rwork, inform, ysave, wkjac, ...
   jacpvt, imon, inln, ires, irevcm, lderiv, ifail] = ...
     d02nn(t, tout, y, ydot, rwork, rtol, atol, itol, inform, ...
     ysave, wkjac, jacpvt, imon, inln, ires, irevcm, lderiv, itask, itrace);

  if irevcm == 1 || irevcm == 3 || irevcm == 6 || irevcm == 11
    % Equivalent to resid evaluation in forward communication routines
    % ydot stored in ydot, resid returned in rwork(l1)
    rwork(l1) = -ydot(1) - ydot(2) - ydot(3);
    rwork(l2) = -ydot(2);
    rwork(l3) = -ydot(3);
    if (ires == 1)
      rwork(l1) =                                             rwork(l1);
      rwork(l2) = 0.04*y(1) - 1e4*y(2)*y(3) - 3e7*y(2)*y(2) + rwork(l2);
      rwork(l3) =                             3e7*y(2)*y(2) + rwork(l3);
    end
  elseif (irevcm == 2)
    % Equivalent to resid evaluation in forward communication routines
    % ydot stored in rwork(l1:), resid returned in rwork(l1)
    rwork(l1) = -rwork(l1) - rwork(l2) - rwork(l3);
    rwork(l2) = -rwork(l2);
    rwork(l3) = -rwork(l3);
  elseif (irevcm == 4 || irevcm == 7)
    % Equivalent to resid evaluation in forward communication routines
    % ydot stored in ydot, resid returned in rwork(m1)
    rwork(m1) = -ydot(1) - ydot(2) - ydot(3);
    rwork(m2) = -ydot(2);
    rwork(m3) = -ydot(3);
    if (ires == 1)
      rwork(m1) =                                             rwork(m1);
      rwork(m2) = 0.04*y(1) - 1e4*y(2)*y(3) - 3e7*y(2)*y(2) + rwork(m2);
      rwork(m3) =                             3e7*y(2)*y(2) + rwork(m3);
    end
  elseif (irevcm == 5)
    % Equivalent to resid evaluation in forward communication routines
    % ydot stored in rwork(l1:), resid returned in ydot
    ydot(1) = -rwork(l1) - rwork(l2) - rwork(l);
    ydot(2) = 0.04*y(1) - 1e4*y(2)*y(3) - 3e7*y(2)*y(2) - rwork(l2);
    ydot(3) =                             3e7*y(2)*y(2) - rwork(l3);
  elseif (irevcm == 8)
    % Equivalent to jac evaluation in forward communication routines
    [j, iplace] = d02nr(inform);
    hxd = rwork(16)*rwork(20);
    if (iplace < 2)
      if (j < 2)
        rwork(l1) = 1 - hxd*(0);
        rwork(l2) = 0 - hxd*(0.04);
        rwork(l3) = 0 - hxd*(0);
      elseif (j == 2)
        rwork(l1) = 1 - hxd*(0);
        rwork(l2) = 1 - hxd*(-1e4*y(3)-6e7*y(2));
        rwork(l3) = 0 - hxd*(6e7*y(2));
      elseif (j > 2)
        rwork(l1) = 1 - hxd*(0);
        rwork(l2) = 0 - hxd*(-1e4*y(2));
        rwork(l3) = 1 - hxd*(0);
      end
    else
      if (j < 2)
        rwork(m1) = 1 - hxd*(0);
        rwork(m2) = 0 - hxd*(0.04);
        rwork(m3) = 0 - hxd*(0);
      elseif (j == 2)
        rwork(m1) = 1 - hxd*(0);
        rwork(m2) = 1 - hxd*(-1e4*y(3)-6e7*y(2));
        rwork(m3) = 0 - hxd*(6e7*y(2));
      elseif (j > 2)
        rwork(m1) = 1 - hxd*(0);
        rwork(m2) = 0 - hxd*(-1e4*y(2));
        rwork(m3) = 1 - hxd*(0);
      end
    end
  elseif (irevcm == 10)
    % Step failure
    nfails = nfails + 1;
  end
end

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

[y, ifail] = d02mz(tout, neq, neq, ysave, rwork);

% Print solution and diagnostics
fprintf(' %8.3f      %5.1f        %5.1f         %5.1f\n', t, y);
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,nit);
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);
fprintf('   number of failed steps                      = %5d\n\n',nfails);

icall = int64(0);
[liwreq, liwusd, lrwreq, lrwusd, nlu, nz, ngp, isplit, igrow, nblock] = ...
    d02nx(icall, true, 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);

d02nn example results

  Analytic Jacobian

     x           y_1          y_2           y_3
    0.000        1.0          0.0           0.0
 Warning: Equation(=i1) and possibly other equations are
 implicit and in calculating the initial values the
 equations will be treated as implicit.
 In above message i1 =         1
   10.767        0.8          0.0           0.2

Diagnostic information
 integration status:
   last and next step sizes =  0.90181,  0.90181
   integration stopped at x = 10.76669
 algorithm statistics:
   number of time-steps and Newton iterations  =    55    80
   number of residual and jacobian evaluations =    89    17
   order of method last used and next to use   =     4     4
   component with largest error                =     3
   number of failed steps                      =     4

 sparse jacobian statistics:
   njcpvt - required =  99, used = 150
   nwkjac - required =  31, used =  75
   No. of LU-decomps =  17, No. of nonzeros =   8
   No. of function calls to form Jacobian =   0, try isplit =  73
 Growth estimate = 1531, No. of blocks on diagonal   1