Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_opt_nlp2_sparse_jacobian (e04vj)

## Purpose

nag_opt_nlp2_sparse_jacobian (e04vj) may be used before nag_opt_nlp2_sparse_solve (e04vh) to determine the sparsity pattern for the Jacobian.

## Syntax

[iafun, javar, nea, a, igfun, jgvar, neg, cw, iw, rw, user, ifail] = e04vj(nf, usrfun, lena, leng, x, xlow, xupp, cw, iw, rw, 'n', n, 'user', user)
[iafun, javar, nea, a, igfun, jgvar, neg, cw, iw, rw, user, ifail] = nag_opt_nlp2_sparse_jacobian(nf, usrfun, lena, leng, x, xlow, xupp, cw, iw, rw, 'n', n, 'user', user)
Note: the interface to this routine has changed since earlier releases of the toolbox:
Mark 22: lencw, leniw, lenrw have been removed from the interface
.

## Description

When using nag_opt_nlp2_sparse_solve (e04vh), if you set the optional parameter ${\mathbf{Derivative Option}}=0$ and usrfun provides none of the derivatives, you may need to call nag_opt_nlp2_sparse_jacobian (e04vj) to determine the input arrays iafun, javar, a, igfun and jgvar. These arrays define the pattern of nonzeros in the Jacobian matrix. A typical sequence of calls could be
```[cw, iw, rw, ifail] = e04vg();
[..., cw, iw, rw, ...] = e04vj(...);
[cw, iw, rw, ifail] = e04vl('Derivative Option = 0', cw, iw, rw);
[..., cw, iw, rw, ...] = e04vh(...);
```
nag_opt_nlp2_sparse_jacobian (e04vj) determines the sparsity pattern for the Jacobian and identifies the constant elements automatically. To do so, nag_opt_nlp2_sparse_jacobian (e04vj) approximates the problem functions, F(x) $F\left(x\right)$, at three random perturbations of the given initial point x $x$. If an element of the approximate Jacobian is the same at all three points, then it is taken to be constant. If it is zero, it is taken to be identically zero. Since the random points are not chosen close together, the heuristic will correctly classify the Jacobian elements in the vast majority of cases. In general, nag_opt_nlp2_sparse_jacobian (e04vj) finds that the Jacobian can be permuted to the form:
 ( G(x) A3 ) A2 A4
,
$G(x) A3 A2 A4 ,$
where A2 ${A}_{2}$, A3 ${A}_{3}$ and A4 ${A}_{4}$ are constant. Note that G(x) $G\left(x\right)$ might contain elements that are also constant, but nag_opt_nlp2_sparse_jacobian (e04vj) must classify them as nonlinear. This is because nag_opt_nlp2_sparse_solve (e04vh) ‘removes’ linear variables from the calculation of F $F$ by setting them to zero before calling usrfun. A knowledgeable user would be able to move such elements from F(x) $F\left(x\right)$ in usrfun and enter them as part of iafun, javar and a for nag_opt_nlp2_sparse_solve (e04vh).

## References

Hock W and Schittkowski K (1981) Test Examples for Nonlinear Programming Codes. Lecture Notes in Economics and Mathematical Systems 187 Springer–Verlag

## Parameters

Note: all optional parameters are described in detail in Section [Description of the optional parameters] in (e04vh).

### Compulsory Input Parameters

1:     nf – int64int32nag_int scalar
nf$\mathit{nf}$, the number of problem functions in F(x) $F\left(x\right)$, including the objective function (if any) and the linear and nonlinear constraints. Simple upper and lower bounds on x $x$ can be defined using the parameters xlow and xupp and should not be included in F $F$.
Constraint: nf > 0${\mathbf{nf}}>0$.
2:     usrfun – function handle or string containing name of m-file
usrfun must define the problem functions F(x) $F\left(x\right)$. This function is passed to nag_opt_nlp2_sparse_jacobian (e04vj) as the external parameter usrfun.
[status, f, g, user] = usrfun(status, n, x, needf, nf, f, needg, leng, g, user)

Input Parameters

1:     status – int64int32nag_int scalar
Indicates the first call to usrfun.
status = 0 ${\mathbf{status}}=0$
There is nothing special about the current call to usrfun.
status = 1 ${\mathbf{status}}=1$
nag_opt_nlp2_sparse_jacobian (e04vj) is calling your function for the first time. Some data may need to be input or computed and saved.
2:     n – int64int32nag_int scalar
n $n$, the number of variables, as defined in the call to nag_opt_nlp2_sparse_jacobian (e04vj).
3:     x(n) – double array
The variables x $x$ at which the problem functions are to be calculated. The array x $x$ must not be altered.
4:     needf – int64int32nag_int scalar
Indicates if f must be assigned during the call to usrfun (see f).
5:     nf – int64int32nag_int scalar
nf$\mathit{nf}$, the number of problem functions.
6:     f(nf) – double array
This will be set by nag_opt_nlp2_sparse_jacobian (e04vj).
7:     needg – int64int32nag_int scalar
nag_opt_nlp2_sparse_jacobian (e04vj) will call usrfun with needg = 0${\mathbf{needg}}=0$ to indicate that g is not required.
8:     leng – int64int32nag_int scalar
The dimension of the array g as declared in the (sub)program from which nag_opt_nlp2_sparse_jacobian (e04vj) is called.
9:     g(leng) – double array
Concerns the calculations of the derivatives of the function f(x) $f\left(x\right)$.
10:   user – Any MATLAB object
usrfun is called from nag_opt_nlp2_sparse_jacobian (e04vj) with the object supplied to nag_opt_nlp2_sparse_jacobian (e04vj).

Output Parameters

1:     status – int64int32nag_int scalar
May be used to indicate that you are unable to evaluate F $F$ at the current x $x$. (For example, the problem functions may not be defined there).
nag_opt_nlp2_sparse_jacobian (e04vj) evaluates F(x) $F\left(x\right)$ at random perturbation of the initial point x $x$, say xp ${x}_{p}$. If the functions cannot be evaluated at xp ${x}_{p}$, you can set status = 1 ${\mathbf{status}}=-1$, nag_opt_nlp2_sparse_jacobian (e04vj) will use another random perturbation.
If for some reason you wish to terminate the current problem, set status2 ${\mathbf{status}}\le -2$.
2:     f(nf) – double array
The computed F(x) $F\left(x\right)$ according to the setting of needf.
If needf = 0 ${\mathbf{needf}}=0$, f is not required and is ignored.
If needf > 0 ${\mathbf{needf}}>0$, the components of F(x) $F\left(x\right)$ must be calculated and assigned to f. nag_opt_nlp2_sparse_jacobian (e04vj) will always call usrfun with needf > 0 ${\mathbf{needf}}>0$.
To simplify the code, you may ignore the value of needf and compute F(x) $F\left(x\right)$ on every entry to usrfun.
3:     g(leng) – double array
nag_opt_nlp2_sparse_jacobian (e04vj) will always call usrfun with needg = 0 ${\mathbf{needg}}=0$: g is not required to be set on exit but must be declared correctly.
4:     user – Any MATLAB object
3:     lena – int64int32nag_int scalar
The dimension of the arrays iafun, javar and a that hold (i,j,Aij)$\left(i,j,{A}_{ij}\right)$ as declared in the (sub)program from which nag_opt_nlp2_sparse_jacobian (e04vj) is called. lena should be an overestimate of the number of elements in the linear part of the Jacobian.
Constraint: lena1${\mathbf{lena}}\ge 1$.
4:     leng – int64int32nag_int scalar
The dimension of the arrays igfun and jgvar that define the varying Jacobian elements (i,j,Gij)$\left(i,j,{G}_{ij}\right)$ as declared in the (sub)program from which nag_opt_nlp2_sparse_jacobian (e04vj) is called. leng should be an overestimate of the number of elements in the nonlinear part of the Jacobian.
Constraint: leng1${\mathbf{leng}}\ge 1$.
5:     x(n) – double array
n, the dimension of the array, must satisfy the constraint n > 0${\mathbf{n}}>0$.
An initial estimate of the variables x $x$. The contents of x $x$ will be used by nag_opt_nlp2_sparse_jacobian (e04vj) in the call of usrfun, and so each element of x should be within the bounds given by xlow and xupp.
6:     xlow(n) – double array
7:     xupp(n) – double array
n, the dimension of the array, must satisfy the constraint n > 0${\mathbf{n}}>0$.
Contain the lower and upper bounds lx ${l}_{x}$ and ux ${u}_{x}$ on the variables x $x$.
To specify a nonexistent lower bound [lx]j = ${\left[{l}_{x}\right]}_{j}=-\infty$, set xlow(j) bigbnd ${\mathbf{xlow}}\left(j\right)\le -\mathit{bigbnd}$, where bigbnd $\mathit{bigbnd}$ is the optional parameter Infinite Bound Size. To specify a nonexistent upper bound xupp(j) bigbnd ${\mathbf{xupp}}\left(j\right)\ge \mathit{bigbnd}$.
To fix the j $j$th variable (say, xj = β ${x}_{j}=\beta$, where |β| < bigbnd $|\beta |<\mathit{bigbnd}$), set xlow(j) = xupp(j) = β ${\mathbf{xlow}}\left(j\right)={\mathbf{xupp}}\left(j\right)=\beta$.
8:     cw(lencw) – cell array of strings
lencw, the dimension of the array, must satisfy the constraint lencw600$\mathit{lencw}\ge 600$.
Constraint: lencw600$\mathit{lencw}\ge 600$.
9:     iw(leniw) – int64int32nag_int array
leniw, the dimension of the array, must satisfy the constraint leniw600$\mathit{leniw}\ge 600$.
Constraint: leniw600$\mathit{leniw}\ge 600$.
10:   rw(lenrw) – double array
lenrw, the dimension of the array, must satisfy the constraint lenrw600$\mathit{lenrw}\ge 600$.
Constraint: lenrw600$\mathit{lenrw}\ge 600$.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The dimension of the arrays x, xlow, xupp. (An error is raised if these dimensions are not equal.)
n$n$, the number of variables.
Constraint: n > 0${\mathbf{n}}>0$.
2:     user – Any MATLAB object
user is not used by nag_opt_nlp2_sparse_jacobian (e04vj), but is passed to usrfun. Note that for large objects it may be more efficient to use a global variable which is accessible from the m-files than to use user.

### Input Parameters Omitted from the MATLAB Interface

lencw leniw lenrw cuser iuser ruser

### Output Parameters

1:     iafun(lena) – int64int32nag_int array
2:     javar(lena) – int64int32nag_int array
Define the coordinates (i,j) $\left(i,j\right)$ and values Aij ${A}_{ij}$ of the nonzero elements of the linear part A $A$ of the function F(x) = f(x) + Ax $F\left(x\right)=f\left(x\right)+Ax$.
In particular, nea triples (iafun(k),javar(k),a(k)) $\left({\mathbf{iafun}}\left(k\right),{\mathbf{javar}}\left(k\right),{\mathbf{a}}\left(k\right)\right)$ define the row and column indices i = iafun(k) $i={\mathbf{iafun}}\left(k\right)$ and j = javar(k) $j={\mathbf{javar}}\left(k\right)$ of the element Aij = a(k) ${A}_{ij}={\mathbf{a}}\left(k\right)$.
3:     nea – int64int32nag_int scalar
Is the number of nonzero entries in A $A$ such that F(x) = f(x) + Ax $F\left(x\right)=f\left(x\right)+Ax$.
4:     a(lena) – double array
Define the coordinates (i,j) $\left(i,j\right)$ and values Aij ${A}_{ij}$ of the nonzero elements of the linear part A $A$ of the function F(x) = f(x) + Ax $F\left(x\right)=f\left(x\right)+Ax$.
In particular, nea triples (iafun(k),javar(k),a(k)) $\left({\mathbf{iafun}}\left(k\right),{\mathbf{javar}}\left(k\right),{\mathbf{a}}\left(k\right)\right)$ define the row and column indices i = iafun(k) $i={\mathbf{iafun}}\left(k\right)$ and j = javar(k) $j={\mathbf{javar}}\left(k\right)$ of the element Aij = a(k) ${A}_{ij}={\mathbf{a}}\left(k\right)$.
5:     igfun(leng) – int64int32nag_int array
6:     jgvar(leng) – int64int32nag_int array
Define the coordinates (i,j) $\left(i,j\right)$ of the nonzero elements of G $G$, the nonlinear part of the derivatives J(x) = G(x) + A $J\left(x\right)=G\left(x\right)+A$ of the function F(x) = f(x) + Ax $F\left(x\right)=f\left(x\right)+Ax$.
7:     neg – int64int32nag_int scalar
The number of nonzero entries in G $G$.
8:     cw(lencw) – cell array of strings
cw = state . cw${\mathbf{cw}}=\mathbf{state}.\text{cw}$lencw = 600$\mathit{lencw}=600$.
Communication array, used to store information between calls to nag_opt_nlp2_sparse_jacobian (e04vj).
9:     iw(leniw) – int64int32nag_int array
iw = state . iw${\mathbf{iw}}=\mathbf{state}.\text{iw}$leniw = 600$\mathit{leniw}=600$.
Communication array, used to store information between calls to nag_opt_nlp2_sparse_jacobian (e04vj).
10:   rw(lenrw) – double array
rw = state . rw${\mathbf{rw}}=\mathbf{state}.\text{rw}$lenrw = 600$\mathit{lenrw}=600$.
Communication array, used to store information between calls to nag_opt_nlp2_sparse_jacobian (e04vj).
11:   user – Any MATLAB object
12:   ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

## Error Indicators and Warnings

Errors or warnings detected by the function:

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

ifail = 1${\mathbf{ifail}}=1$
The initialization function nag_opt_nlp2_sparse_init (e04vg) has not been called or at least one of lencw, leniw or lenrw is less than 600$600$.
ifail = 2${\mathbf{ifail}}=2$
An input parameter is invalid.
ifail = 3${\mathbf{ifail}}=3$
Undefined user-supplied function.
You have indicated that the problem functions are undefined by setting status = 1 ${\mathbf{status}}=-1$ on exit from usrfun. This exit occurs if nag_opt_nlp2_sparse_jacobian (e04vj) is unable to find a point at which the functions are defined.
W ifail = 4${\mathbf{ifail}}=4$
User requested termination.
You have indicated the wish to terminate the call to nag_opt_nlp2_sparse_jacobian (e04vj) by setting status to a value < 1$\text{}<-1$ on exit from usrfun.
ifail = 5${\mathbf{ifail}}=5$
Either lena or leng is too small, resulting in insufficient array to store the Jacobian information. Increase lena and/or leng
ifail = 6${\mathbf{ifail}}=6$
Unable to estimate the Jacobian structure.
ifail = 7${\mathbf{ifail}}=7$
ifail = 8${\mathbf{ifail}}=8$

Not applicable.

None.

## Example

```function nag_opt_nlp2_sparse_jacobian_example
nf = int64(6);
lena = int64(300);
leng = int64(300);
x = [0;
0;
0;
0];
xlow = [-0.55;
-0.55;
0;
0];
xupp = [0.55;
0.55;
1200;
1200];
[cw, iw, rw, ifail] = nag_opt_nlp2_sparse_init();
[iafun, javar, nea, a, igfun, jgvar, neg, cwOut, iwOut, rwOut, cuser, ifail] = ...
nag_opt_nlp2_sparse_jacobian(nf, @usrfun, lena, leng, x, xlow, xupp, cw, iw, rw);
nea, neg, ifail

function [status, f, g, user] = usrfun(status, n, x, needf, nf, f, needg, leng, g, user)

% Always called with needf > 0
f(1) = 1000*sin(-x(1)-0.25) + 1000*sin(-x(2) -0.25) - x(3);
f(2) = 1000*sin(x(1)-0.25) + 1000*sin(x(1)-x(2) -0.25) - x(4);
f(3) = 1000*sin(x(2)-x(1)-0.25) + 1000*sin(x(2) -0.25);
f(4) = -x(1) + x(2);
f(5) = x(1) - x(2);
f(6) = 1.0d-6*x(3)^3 + 2.0d-6*x(4)^3/3 + 3*x(3) + 2*x(4);

% Always called with needg=0
```
```

nea =

4

neg =

10

ifail =

0

```
```function e04vj_example
nf = int64(6);
lena = int64(300);
leng = int64(300);
x = [0;
0;
0;
0];
xlow = [-0.55;
-0.55;
0;
0];
xupp = [0.55;
0.55;
1200;
1200];
[cw, iw, rw, ifail] = e04vg;
[iafun, javar, nea, a, igfun, jgvar, neg, cwOut, iwOut, rwOut, cuser, ifail] = ...
e04vj(nf, @usrfun, lena, leng, x, xlow, xupp, cw, iw, rw);
nea, neg, ifail

function [status, f, g, user] = usrfun(status, n, x, needf, nf, f, needg, leng, g, user)

% Always called with needf > 0
f(1) = 1000*sin(-x(1)-0.25) + 1000*sin(-x(2) -0.25) - x(3);
f(2) = 1000*sin(x(1)-0.25) + 1000*sin(x(1)-x(2) -0.25) - x(4);
f(3) = 1000*sin(x(2)-x(1)-0.25) + 1000*sin(x(2) -0.25);
f(4) = -x(1) + x(2);
f(5) = x(1) - x(2);
f(6) = 1.0d-6*x(3)^3 + 2.0d-6*x(4)^3/3 + 3*x(3) + 2*x(4);

% Always called with needg=0
```
```

nea =

4

neg =

10

ifail =

0

```