naginterfaces.library.opt.nlp2_​sparse_​jacobian

naginterfaces.library.opt.nlp2_sparse_jacobian(nf, usrfun, lena, leng, x, xlow, xupp, comm, data=None, io_manager=None)

nlp2_sparse_jacobian may be used before nlp2_sparse_solve() to determine the sparsity pattern for the Jacobian.

Deprecated since version 28.3.0.0: nlp2_sparse_jacobian is deprecated. Please use handle_solve_ssqp() instead. See also the Replacement Calls document.

For full information please refer to the NAG Library document for e04vj

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e04/e04vjf.html

Parameters

nfint

$\text{nf}$, the number of problem functions in $F\left(x\right)$, including the objective function (if any) and the linear and nonlinear constraints. Simple upper and lower bounds on $x$ can be defined using the arguments $xlow$ and $xupp$ and should not be included in $F$.

usrfuncallable (status, f, g) = usrfun(status, x, needf, f, needg, g, data=None)

$usrfun$ must define the problem functions $F\left(x\right)$.

This function is passed to nlp2_sparse_jacobian as the external argument $usrfun$.

Parameters

statusint

Indicates the first call to $usrfun$.

$status=0$

There is nothing special about the current call to $usrfun$.

$status=1$

nlp2_sparse_jacobian is calling your function for the first time. Some data may need to be input or computed and saved.

xfloat, ndarray, shape $\left(n\right)$

The variables $x$ at which the problem functions are to be calculated. The array $x$ must not be altered.

needfint

Indicates if $f$ must be assigned during the call to $usrfun$ (see $f$).

ffloat, ndarray, shape $\left(\text{nf}\right)$

This will be set by nlp2_sparse_jacobian.

needgint

nlp2_sparse_jacobian will call $usrfun$ with $needg=0$ to indicate that $g$ is not required.

gfloat, ndarray, shape $\left(\text{leng}\right)$

Concerns the calculations of the derivatives of the function $f\left(x\right)$.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

statusint

May be used to indicate that you are unable to evaluate $F$ at the current $x$. (For example, the problem functions may not be defined there).

nlp2_sparse_jacobian evaluates $F\left(x\right)$ at random perturbation of the initial point $x$, say $x_p$.

If the functions cannot be evaluated at $x_p$, you can set $status=-1$, nlp2_sparse_jacobian will use another random perturbation.

If for some reason you wish to terminate the current problem, set $status\le -2$.

ffloat, array-like, shape $\left(\text{nf}\right)$

The computed $F\left(x\right)$ according to the setting of $needf$.

If $needf=0$, $f$ is not required and is ignored.

If $needf>0$, the components of $F\left(x\right)$ must be calculated and assigned to $f$. nlp2_sparse_jacobian will always call $usrfun$ with $needf>0$.

To simplify the code, you may ignore the value of $needf$ and compute $F\left(x\right)$ on every entry to $usrfun$.

gfloat, array-like, shape $\left(\text{leng}\right)$

nlp2_sparse_jacobian will always call $usrfun$ with $needg=0$: $g$ is not required to be set on exit but must be declared correctly.

lenaint

$lena$ should be an overestimate of the number of elements in the linear part of the Jacobian.

lengint

$leng$ should be an overestimate of the number of elements in the nonlinear part of the Jacobian.

xfloat, array-like, shape $\left(n\right)$

An initial estimate of the variables $x$. The contents of $x$ will be used by nlp2_sparse_jacobian in the call of $usrfun$, and so each element of $x$ should be within the bounds given by $xlow$ and $xupp$.

xlowfloat, array-like, shape $\left(n\right)$

Contain the lower and upper bounds $l_x$ and $u_x$ on the variables $x$.

To specify a nonexistent lower bound ${\left[l_x\right]}_j=-\infty$, set $xlow[j-1]\le -\text{bigbnd}$, where $\text{bigbnd}$ is the option ‘Infinite Bound Size’.

To specify a nonexistent upper bound $xupp[j-1]\ge \text{bigbnd}$.

To fix the $j$th variable (say, $x_j=\beta$, where $\left|\beta \right|<\text{bigbnd}$), set $xlow[j-1]=xupp[j-1]=\beta$.

xuppfloat, array-like, shape $\left(n\right)$

Contain the lower and upper bounds $l_x$ and $u_x$ on the variables $x$.

To specify a nonexistent lower bound ${\left[l_x\right]}_j=-\infty$, set $xlow[j-1]\le -\text{bigbnd}$, where $\text{bigbnd}$ is the option ‘Infinite Bound Size’.

To specify a nonexistent upper bound $xupp[j-1]\ge \text{bigbnd}$.

To fix the $j$th variable (say, $x_j=\beta$, where $\left|\beta \right|<\text{bigbnd}$), set $xlow[j-1]=xupp[j-1]=\beta$.

commdict, communication object, modified in place

Communication structure.

This argument must have been initialized by a prior call to nlp2_sparse_init().

dataarbitrary, optional

User-communication data for callback functions.

io_managerFileObjManager, optional

Manager for I/O in this routine.

Returns

iafunint, ndarray, shape $\left(lena\right)$

Define the $i$ coordinates of the nonzero elements of the linear part $A$ of the function $F\left(x\right)=f\left(x\right)+Ax$.

javarint, ndarray, shape $\left(lena\right)$

Define the $j$ coordinates of the nonzero elements of the linear part $A$ of the function $F\left(x\right)=f\left(x\right)+Ax$.

neaint

Is the number of nonzero entries in $A$ such that $F\left(x\right)=f\left(x\right)+Ax$.

afloat, ndarray, shape $\left(lena\right)$

Define the coordinates $(i,j)$ and values $A_{ij}$ of the nonzero elements of the linear part $A$ of the function $F\left(x\right)=f\left(x\right)+Ax$.

In particular, $nea$ triples $(iafun[k-1],javar[k-1],a[k-1])$ define the row and column indices $i=iafun[k-1]$ and $j=javar[k-1]$ of the element $A_{ij}=a[k-1]$.

igfunint, ndarray, shape $\left(leng\right)$

Define the coordinates $(i,j)$ of the nonzero elements of $G$, the nonlinear part of the derivatives $J\left(x\right)=G\left(x\right)+A$ of the function $F\left(x\right)=f\left(x\right)+Ax$.

jgvarint, ndarray, shape $\left(leng\right)$

Define the coordinates $(i,j)$ of the nonzero elements of $G$, the nonlinear part of the derivatives $J\left(x\right)=G\left(x\right)+A$ of the function $F\left(x\right)=f\left(x\right)+Ax$.

negint

The number of nonzero entries in $G$.

Raises

NagValueError

(errno $1$)

The initialization function nlp2_sparse_init() has not been called.

(errno $2$)

On entry, $lena=⟨value⟩$.

Constraint: $lena\ge 1$.

(errno $2$)

On entry, $leng=⟨value⟩$.

Constraint: $leng\ge 1$.

(errno $3$)

User-supplied function $usrfun$ indicates that functions are undefined near given point $x$.

(errno $5$)

Either $lena$ or $leng$ is too small. Increase both of them and corresponding array sizes. $lena=⟨value⟩$ and $leng=⟨value⟩$.

(errno $6$)

Cannot estimate Jacobian structure at given point $x$.

(errno $7$)

Internal error: memory allocation failed when attempting to allocate workspace sizes $⟨value⟩$, $⟨value⟩$ and $⟨value⟩$. Please contact NAG.

(errno $8$)

Internal memory allocation was insufficient. Please contact NAG.

Warns

NagAlgorithmicWarning

(errno $4$)

User-supplied function $usrfun$ requested termination.

Notes

When using nlp2_sparse_solve(), if you set the option $\text{‘Derivative Option'}=0$ and $usrfun$ provides none of the derivatives, you may need to call nlp2_sparse_jacobian to determine the input arrays $iafun$, $javar$, $a$, $igfun$ and $jgvar$. These arrays define the pattern of nonzeros in the Jacobian matrix.

nlp2_sparse_jacobian determines the sparsity pattern for the Jacobian and identifies the constant elements automatically. To do so, nlp2_sparse_jacobian approximates the problem functions, $F\left(x\right)$, at three random perturbations of the given initial point $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, nlp2_sparse_jacobian finds that the Jacobian can be permuted to the form:

$$\begin{array}{c}\left(\begin{array}{cc}G\left(x\right)& A_3\\ A_2& A_4\end{array}\right)\text{,}\end{array}$$

where $A_2$, $A_3$ and $A_4$ are constant. Note that $G\left(x\right)$ might contain elements that are also constant, but nlp2_sparse_jacobian must classify them as nonlinear. This is because nlp2_sparse_solve() ‘removes’ linear variables from the calculation of $F$ by setting them to zero before calling $usrfun$. A knowledgeable user would be able to move such elements from $F\left(x\right)$ in $usrfun$ and enter them as part of $iafun$, $javar$ and $a$ for nlp2_sparse_solve().

References

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