NAG Toolbox: nag_ode_ivp_stiff_sparjac_setup (d02nu)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{neq}$ – int64int32nag_int scalar

The number of differential equations.

Constraint: $1\le \mathbf{neq}\le \mathbf{neqmax}$.

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

A bound on the maximum number of differential equations to be solved during the integration.

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

3:     $\mathrm{jceval}$ – string (length ≥ 1)

Specifies the technique to be used to compute the Jacobian.

$\mathbf{jceval}=\text{'N'}$

The sparsity structure and the value of the Jacobian are to be determined numerically by the integrator.

$\mathbf{jceval}=\text{'S'}$

The sparsity structure of the Jacobian is supplied in the arrays ia and ja but its value is to be determined numerically. This is the recommended mode of operation unless it is a simple matter to supply the Jacobian.

$\mathbf{jceval}=\text{'A'}$

The Jacobian will be evaluated by calls to jac. The sparsity structure will be estimated by calls to jac; that is, no explicit sparsity structure need be supplied in the arrays ia and ja.

$\mathbf{jceval}=\text{'F'}$

The sparsity structure of the Jacobian is supplied in ia and ja, and its value will be determined by calls to jac. This is the recommended mode of operation if the jac is simple to form.

$\mathbf{jceval}=\text{'D'}$

The default choice is to be made. In this case 'D' is interpreted as 'S'.

If the sparsity structure is supplied in arrays ia and ja, then any evidence from the numerical or analytical formation of the Jacobian that this structure is not correct, is ignored.

Only the first character of the actual argument jceval is passed to nag_ode_ivp_stiff_sparjac_setup (d02nu); hence it is permissible for the actual argument to be more descriptive, e.g., ‘Numerical’, ‘Structural’, ‘Analytical’, ‘Full information’ or ‘Default’ in a call to nag_ode_ivp_stiff_sparjac_setup (d02nu).

If the option $\mathbf{jceval}=\text{'N'}$, $\text{'S'}$ or $\text{'D'}$ is used then the actual argument corresponding to jac in the call to nag_ode_ivp_stiff_exp_sparjac (d02nd) or nag_ode_ivp_stiff_imp_sparjac (d02nj) must be either nag_ode_ivp_stiff_exp_sparjac_dummy_jac (d02ndz) or nag_ode_ivp_stiff_imp_sparjac_dummy_jac (d02njz) respectively.

If integration is to be performed by reverse communication (nag_ode_ivp_stiff_exp_revcom (d02nm) or nag_ode_ivp_stiff_imp_revcom (d02nn)) then jceval should be set to either 'N' or 'A'. In this case ia and ja are not used and their lengths may be set to $1$.

Constraint: $\mathbf{jceval}=\text{'N'}$, $\text{'S'}$, $\text{'A'}$, $\text{'F'}$ or $\text{'D'}$.

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

Suggested value: $\mathbf{nwkjac}=4\times \mathbf{neqmax}$ if $\mathbf{jceval}=\text{'N'}$ or $\text{'A'}$. If nwkjac is less than this estimate, then a message is printed on the current advisory message unit (see nag_file_set_unit_advisory (x04ab)), and execution continues.

The size of the array wkjac, which you are supplying to the integrator, as declared in the (sub)program from which nag_ode_ivp_stiff_sparjac_setup (d02nu) is called.

Constraint: if $\mathbf{jceval}=\text{'S'}$, $\text{'F'}$ or $\text{'D'}$, $\mathbf{nwkjac}\ge \mathit{nelement}+2\times \mathbf{neq}$, where $\mathit{nelement}$ is the total number of nonzeros.

5:     $\mathrm{ia}\left(\mathbf{nia}\right)$ – int64int32nag_int array

If $\mathbf{jceval}=\text{'S'}$, $\text{'F'}$ or $\text{'D'}$, ia must contain details of the sparsity pattern to be used for the Jacobian. See ja.

ia is not used if $\mathbf{jceval}=\text{'N'}$ or $\text{'A'}$.

6:     $\mathrm{ja}\left(\mathbf{nja}\right)$ – int64int32nag_int array

If $\mathbf{jceval}=\text{'S'}$, $\text{'F'}$ or $\text{'D'}$, ja must contain details of the sparsity pattern to be used for the Jacobian. ja contains the row indices where nonzero elements occur, reading in column-wise order, and ia contains the starting locations in ja of the descriptions of columns $1,2,\dots ,\mathbf{neq}$ in that order, with $\mathbf{ia}\left(1\right)=1$. Thus for each column index $j=1,2,\dots ,\mathbf{neq}$, the values of the row index $i$ in column $j$ where a nonzero element may occur are given by

$$i=\mathbf{ja}\left(k\right)$$

where $\mathbf{ia}\left(j\right)\le k<\mathbf{ia}\left(j+1\right)$.

Thus the total number of nonzeros, $\mathit{nelement}$, must be $\mathbf{ia}\left(\mathbf{neq}+1\right)-1$. For example, for the following matrix

$$\left(\begin{array}{ccccc}x& 0& x& 0& 0\\ 0& x& x& x& 0\\ x& x& x& 0& 0\\ x& 0& 0& x& x\\ 0& 0& 0& x& x\end{array}\right)$$

where $x$ represents nonzero elements (13 in all) the arrays ia and ja should be

$$\begin{array}{cccccccccccccc}\mathbf{ia}\left(k\right)& 1& 4& 6& 9& 12& 14& & & & & & & \\ \mathbf{ja}\left(k\right)& 1& 3& 4& 2& \phantom{0}3& \phantom{0}1& 2& 3& 2& 4& 5& 4& 5\end{array}$$

ja is not used if $\mathbf{jceval}=\text{'N'}$ or $\text{'A'}$.

7:     $\mathrm{njcpvt}$ – int64int32nag_int scalar

Suggested value: $\mathbf{njcpvt}=20\times \mathbf{neqmax}$ if $\mathbf{jceval}=\text{'N'}$ or $\text{'A'}$. If njcpvt is less than this estimate, then a message is printed on the current advisory message unit (see nag_file_set_unit_advisory (x04ab)), and execution continues.

The length of the array jacpvt, which you are supplying to the integrator, as dimensioned in the sub(program) from which nag_ode_ivp_stiff_sparjac_setup (d02nu) is called.

Constraint: if $\mathbf{jceval}=\text{'S'}$, $\text{'F'}$ or $\text{'D'}$, $\mathbf{njcpvt}\ge 3\times \mathit{nelement}+14\times \mathbf{neq}$, where $\mathit{nelement}$ is the total number of nonzeros.

8:     $\mathrm{sens}$ – double scalar

A threshold argument used to determine whether or not a matrix element is zero; when sens is set to $0.0$ on entry, the function will use $\mathbf{sens}=100.0\times \mathit{machine precision}$. Otherwise the absolute value of sens is used.

9:     $\mathrm{u}$ – double scalar

Should have a value between $0.0$ and $0.9999$. Otherwise a default value of $0.1$ is used. When the sparsity pattern has been evaluated, the first Jacobian computed is decomposed with u governing the choice of pivots; subsequent Jacobian decompositions use the same pattern of decomposition until the sparsity pattern is re-evaluated. When searching a row for a pivot, any element is excluded from the search which is less than u times the largest of those elements in the row available as pivots. Thus decreasing u biases the algorithm towards maintaining sparsity at the expense of numerical stability.

10:   $\mathrm{eta}$ – double scalar

A relative pivot threshold, below which on subsequent decompositions (as described under u), an internal error is provoked.

$\mathbf{eta}>1.0$

No check on pivot size is made.

$\mathbf{eta}\le 0.0$

The default value $\mathbf{eta}=\text{1.0e−4}$ is used.

11:   $\mathrm{lblock}$ – logical scalar

Indicates if preordering is used before decomposition.

If $\mathbf{lblock}=\mathit{true}$, on entry, the Jacobian matrix is preordered to block lower triangular form before a decomposition is performed (this is the recommended mode). If you know the structure of the Jacobian to be irreducible, that is not permutable to block lower triangular form, then you should set $\mathbf{lblock}=\mathit{false}$. For example, a Jacobian arising from using the method of lines for parabolic partial differential equations would normally be irreducible. (See the specification of nag_ode_ivp_stiff_sparjac_diag (d02nx) for optional output concerning lblock.)

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

This must be the same workspace array as the array rwork supplied to the integrator. It is used to pass information from the setup function to the integrator and therefore the contents of this array must not be changed before calling the integrator.

Optional Input Parameters

1:     $\mathrm{nia}$ – int64int32nag_int scalar

Default: the dimension of the array ia.

The dimension of the array ia.

Constraints:

• if $\mathbf{jceval}=\text{'S'}$, $\text{'F'}$ or $\text{'D'}$, $\mathbf{nia}\ge \mathbf{neq}+1$;
• otherwise $\mathbf{nia}\ge 1$.

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

Default: the dimension of the array ja.

The dimension of the array ja.

Constraints:

• if $\mathbf{jceval}=\text{'S'}$, $\text{'F'}$ or $\text{'D'}$, $\mathbf{nja}\ge \mathbf{ia}\left(\mathbf{neq}+1\right)-1$;
• otherwise $\mathbf{nja}\ge 1$.

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

Suggested value: $\mathbf{isplit}=73$, unless you have information from a previous run of a similar problem.

Default: $73$

This argument is used for splitting the integer workspace jacpvt to effect an efficient decomposition. It must satisfy $1\le \mathbf{isplit}\le 99$. If isplit lies outside this range on entry, a default value of $73$ is used. An appropriate value for isplit for subsequent runs on similar problems is available via the optional output nag_ode_ivp_stiff_sparjac_diag (d02nx).

Output Parameters

1:     $\mathrm{jacpvt}\left(\mathbf{njcpvt}\right)$ – int64int32nag_int array

Data relating to the Jacobian sparsity structure.

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

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

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

Error Indicators and Warnings

   $\mathbf{ifail}=1$

On entry, an illegal input was detected.

   $\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: d02nu_example

function d02nu_example


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

% Initialize variables and arrays for setup routine

n      = int64(3);
ord    = int64(5);
sdy    = int64(ord + 1);
petzld = false;
con    = zeros(6);
tcrit  = 0;
hmin   = 1.0e-10;
hmax   = 10;
h0     = 0;
maxstp = int64(200);
mxhnil = int64(5);
lrwork = 50 + 4*n;
rwork  = zeros(lrwork);

% Setup integration method using d02nv.
[const, rwork, ifail] = d02nv(...
                              n, sdy, ord, 'Newton', petzld, con, tcrit, ...
                              hmin, hmax, h0, maxstp, mxhnil, 'Average-L2', ...
                              rwork);

% Setup for sparse Jacbian using d02nu
nwkjac = int64(100);
njcpvt = int64(150);
ia     = int64(0);
ja     = int64(0);
sens   = 0;
u      = 0.1;
eta    = 1.0e-4;
lblock = true;
jacpvt = zeros(njcpvt, 1);
[jacpvt, rwork, ifail] = d02nu(...
                               n, n, 'Numerical', nwkjac, ia, ja, njcpvt, ...
                               sens, u, eta, lblock, rwork);

% Initialize variables and arrays for integration
t      = 0;
tout   = 10;
y      = [1; 0; 0];
rtol   = [0.0001];
atol   = [1e-07];
itol   = int64(1);
inform = zeros(23, 1, 'int64');
ysave  = zeros(n, sdy);
wkjac  = zeros(nwkjac, 1);
itask  = int64(1);
itrace = int64(0);

% Integrate ODE from t=0 to t=tout, no monitoring, using d02nd
[t, y, ydot, rwork, inform, ysave, wkjac, jacpvt, ifail] = ...
    d02nd(t, tout, y, rwork, rtol, atol, itol, inform, @fcn, ysave, @jac, ...
          wkjac, jacpvt, 'd02nby', itask, itrace);

fprintf('Solution y and derivative y'' at t = %7.4f is:\n',t);
fprintf('\n %10s %10s\n','y','y''');
for i=1:n
  fprintf(' %10.4f %10.4f\n',y(i),ydot(i));
end



function [f, ires] = fcn(neq, t, y, ires)
% Evaluate derivative vector.
f = zeros(3,1);
f(1) = -0.04d0*y(1) + 1.0d4*y(2)*y(3);
f(2) =  0.04d0*y(1) - 1.0d4*y(2)*y(3) - 3.0d7*y(2)*y(2);
f(3) =                                  3.0d7*y(2)*y(2);

d02nu example results

Solution y and derivative y' at t = 10.0000 is:

          y         y'
     0.8414    -0.0075
     0.0000    -0.0000
     0.1586     0.0075