# NAG FL Interfaced02nuf (ivp_​stiff_​sparjac_​setup)

## ▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

## 1Purpose

d02nuf is a setup routine which must be called prior to an integrator in Sub-chapter D02M–N, if sparse matrix linear algebra is required.

## 2Specification

Fortran Interface
 Subroutine d02nuf ( neq, ia, nia, ja, nja, sens, u, eta,
 Integer, Intent (In) :: neq, neqmax, nwkjac, ia(nia), nia, ja(nja), nja, njcpvt, isplit Integer, Intent (Inout) :: ifail Integer, Intent (Out) :: jacpvt(njcpvt) Real (Kind=nag_wp), Intent (In) :: sens, u, eta Real (Kind=nag_wp), Intent (Inout) :: rwork(50+4*neqmax) Logical, Intent (In) :: lblock Character (1), Intent (In) :: jceval
#include <nag.h>
 void d02nuf_ (const Integer *neq, const Integer *neqmax, const char *jceval, const Integer *nwkjac, const Integer ia[], const Integer *nia, const Integer ja[], const Integer *nja, Integer jacpvt[], const Integer *njcpvt, const double *sens, const double *u, const double *eta, const logical *lblock, const Integer *isplit, double rwork[], Integer *ifail, const Charlen length_jceval)
The routine may be called by the names d02nuf or nagf_ode_ivp_stiff_sparjac_setup.

## 3Description

d02nuf defines the linear algebra to be used as sparse matrix linear algebra, permits you to specify the method for calculating the Jacobian and its structure, and checks the validity of certain input values.

## 4References

See the D02M–N Sub-chapter Introduction.

## 5Arguments

1: $\mathbf{neq}$Integer Input
On entry: the number of differential equations.
Constraint: $1\le {\mathbf{neq}}\le {\mathbf{neqmax}}$.
2: $\mathbf{neqmax}$Integer Input
On entry: a bound on the maximum number of differential equations to be solved during the integration.
Constraint: ${\mathbf{neqmax}}\ge {\mathbf{neq}}$.
3: $\mathbf{jceval}$Character(1) Input
On entry: 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, 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 d02nuf; 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 d02nuf.
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 d02ndf or d02njf must be either d02ndz or d02njz respectively.
If integration is to be performed by reverse communication (d02nmf or d02nnf) 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: $\mathbf{nwkjac}$Integer Input
On entry: the size of the array wkjac, which you are supplying to the integrator, as declared in the (sub)program from which d02nuf is called.
Suggested value: ${\mathbf{nwkjac}}=4×{\mathbf{neqmax}}$ if ${\mathbf{jceval}}=\text{'N'}$ or $\text{'A'}$. If nwkjac is less than this estimate, a message is printed on the current advisory message unit (see x04abf), and execution continues.
Constraint: if ${\mathbf{jceval}}=\text{'S'}$, $\text{'F'}$ or $\text{'D'}$, ${\mathbf{nwkjac}}\ge \mathit{nelement}+2×{\mathbf{neq}}$, where $\mathit{nelement}$ is the total number of nonzeros.
5: $\mathbf{ia}\left({\mathbf{nia}}\right)$Integer array Input
On entry: 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: $\mathbf{nia}$Integer Input
On entry: the dimension of the array ia as declared in the (sub)program from which d02nuf is called.
Constraints:
• if ${\mathbf{jceval}}=\text{'S'}$, $\text{'F'}$ or $\text{'D'}$, ${\mathbf{nia}}\ge {\mathbf{neq}}+1$;
• otherwise ${\mathbf{nia}}\ge 1$.
7: $\mathbf{ja}\left({\mathbf{nja}}\right)$Integer array Input
On entry: 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=ja(k)$
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
 $( 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 )$
where $x$ represents nonzero elements (13 in all) the arrays ia and ja should be
 $ia(k) 1 4 6 9 12 14 ja(k) 1 3 4 2 03 01 2 3 2 4 5 4 5$
ja is not used if ${\mathbf{jceval}}=\text{'N'}$ or $\text{'A'}$.
8: $\mathbf{nja}$Integer Input
On entry: the dimension of the array ja as declared in the (sub)program from which d02nuf is called.
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$.
9: $\mathbf{jacpvt}\left({\mathbf{njcpvt}}\right)$Integer array Communication Array
On exit: data relating to the Jacobian sparsity structure.
10: $\mathbf{njcpvt}$Integer Input
On entry: the length of the array jacpvt, which you are supplying to the integrator, as dimensioned in the sub(program) from which d02nuf is called.
Suggested value: ${\mathbf{njcpvt}}=20×{\mathbf{neqmax}}$ if ${\mathbf{jceval}}=\text{'N'}$ or $\text{'A'}$. If njcpvt is less than this estimate, a message is printed on the current advisory message unit (see x04abf), and execution continues.
Constraint: if ${\mathbf{jceval}}=\text{'S'}$, $\text{'F'}$ or $\text{'D'}$, ${\mathbf{njcpvt}}\ge 3×\mathit{nelement}+14×{\mathbf{neq}}$, where $\mathit{nelement}$ is the total number of nonzeros.
11: $\mathbf{sens}$Real (Kind=nag_wp) Input
On entry: a threshold argument used to determine whether or not a matrix element is zero; when sens is set to $0.0$ on entry, the routine will use . Otherwise the absolute value of sens is used.
12: $\mathbf{u}$Real (Kind=nag_wp) Input
On entry: 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.
13: $\mathbf{eta}$Real (Kind=nag_wp) Input
On entry: 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.
14: $\mathbf{lblock}$Logical Input
On entry: indicates if preordering is used before decomposition.
If ${\mathbf{lblock}}=\mathrm{.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, you should set ${\mathbf{lblock}}=\mathrm{.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 d02nxf for optional output concerning lblock.)
15: $\mathbf{isplit}$Integer Input
On entry: 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 d02nxf.
Suggested value: ${\mathbf{isplit}}=73$, unless you have information from a previous run of a similar problem.
16: $\mathbf{rwork}\left(50+4×{\mathbf{neqmax}}\right)$Real (Kind=nag_wp) array Communication 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 routine to the integrator and, therefore, the contents of this array must not be changed before calling the integrator.
17: $\mathbf{ifail}$Integer Input/Output
On entry: ifail must be set to $0$, $-1$ or $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$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ or $\mathbf{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).

## 6Error 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).
Errors or warnings detected by the routine:
${\mathbf{ifail}}=1$
On entry, $i=⟨\mathit{\text{value}}⟩$, ${\mathbf{ia}}\left(i\right)=⟨\mathit{\text{value}}⟩$, $i-1=⟨\mathit{\text{value}}⟩$, ${\mathbf{ia}}\left(i-1\right)=⟨\mathit{\text{value}}⟩$, ${\mathbf{neq}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ia}}\left(⟨\mathit{\text{value}}⟩\right)-{\mathbf{ia}}\left(⟨\mathit{\text{value}}⟩\right)\le {\mathbf{neq}}$.
On entry, $i=⟨\mathit{\text{value}}⟩$, ${\mathbf{ja}}\left(i\right)=⟨\mathit{\text{value}}⟩$ and ${\mathbf{neq}}=⟨\mathit{\text{value}}⟩$.
Constraint: $1\le {\mathbf{ja}}\left(i\right)\le {\mathbf{neq}}$ for all $i$.
On entry, ${\mathbf{ia}}\left(⟨\mathit{\text{value}}⟩\right)=⟨\mathit{\text{value}}⟩$ and ${\mathbf{ia}}\left(⟨\mathit{\text{value}}⟩\right)=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ia}}\left(⟨\mathit{\text{value}}⟩\right)\ge {\mathbf{ia}}\left(⟨\mathit{\text{value}}⟩\right)$.
On entry, ${\mathbf{ia}}\left(1\right)=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ia}}\left(1\right)=1$.
On entry, ${\mathbf{ia}}\left({\mathbf{neq}}+1\right)-1=⟨\mathit{\text{value}}⟩$ and ${\mathbf{neq}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{ia}}\left({\mathbf{neq}}+1\right)-1\ge {\mathbf{neq}}$.
On entry, ja defines duplicate elements in row $⟨\mathit{\text{value}}⟩$ and column $⟨\mathit{\text{value}}⟩$.
On entry, ${\mathbf{jceval}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{jceval}}=\text{'A'}$, $\text{'N'}$, $\text{'S'}$, $\text{'F'}$ or $\text{'D'}$.
On entry, ${\mathbf{neq}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{neq}}\ge 1$.
On entry, ${\mathbf{neq}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{neqmax}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{neq}}\le {\mathbf{neqmax}}$.
On entry, ${\mathbf{neqmax}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{neqmax}}\ge 1$.
On entry, ${\mathbf{nia}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{neq}}+1=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{nia}}\ge {\mathbf{neq}}+1$.
On entry, ${\mathbf{nja}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{ia}}\left({\mathbf{neq}}+1\right)-1=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{nja}}\ge {\mathbf{ia}}\left({\mathbf{neq}}+1\right)-1$.
On entry, ${\mathbf{njcpvt}}=⟨\mathit{\text{value}}⟩$ and $3×\left({\mathbf{ia}}\left({\mathbf{neq}}+1\right)-1\right)+14×{\mathbf{neq}}+1=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{njcpvt}}\ge 3×\left({\mathbf{ia}}\left({\mathbf{neq}}+1\right)-1\right)+14×{\mathbf{neq}}+1$.
On entry, ${\mathbf{nwkjac}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{ia}}\left({\mathbf{neq}}+1\right)-1+2×{\mathbf{neq}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{nwkjac}}\ge {\mathbf{ia}}\left({\mathbf{neq}}+1\right)-1+2×{\mathbf{neq}}$.
${\mathbf{ifail}}=-99$
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{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.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

Not applicable.