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)[source]

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://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/e04/e04vjf.html

Parameters
nfint

, the number of problem functions in , including the objective function (if any) and the linear and nonlinear constraints. Simple upper and lower bounds on can be defined using the arguments and and should not be included in .

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

must define the problem functions .

This function is passed to nlp2_sparse_jacobian as the external argument .

Parameters
statusint

Indicates the first call to .

There is nothing special about the current call to .

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

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

needfint

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

ffloat, ndarray, shape

This will be set by nlp2_sparse_jacobian.

needgint

nlp2_sparse_jacobian will call with to indicate that is not required.

gfloat, ndarray, shape

Concerns the calculations of the derivatives of the function .

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
statusint

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

nlp2_sparse_jacobian evaluates at random perturbation of the initial point , say .

If the functions cannot be evaluated at , you can set , nlp2_sparse_jacobian will use another random perturbation.

If for some reason you wish to terminate the current problem, set .

ffloat, array-like, shape

The computed according to the setting of .

If , is not required and is ignored.

If , the components of must be calculated and assigned to . nlp2_sparse_jacobian will always call with .

To simplify the code, you may ignore the value of and compute on every entry to .

gfloat, array-like, shape

nlp2_sparse_jacobian will always call with : is not required to be set on exit but must be declared correctly.

lenaint

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

lengint

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

xfloat, array-like, shape

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

xlowfloat, array-like, shape

Contain the lower and upper bounds and on the variables .

To specify a nonexistent lower bound , set , where is the option ‘Infinite Bound Size’.

To specify a nonexistent upper bound .

To fix the th variable (say, , where ), set .

xuppfloat, array-like, shape

Contain the lower and upper bounds and on the variables .

To specify a nonexistent lower bound , set , where is the option ‘Infinite Bound Size’.

To specify a nonexistent upper bound .

To fix the th variable (say, , where ), set .

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

Define the coordinates of the nonzero elements of the linear part of the function .

javarint, ndarray, shape

Define the coordinates of the nonzero elements of the linear part of the function .

neaint

Is the number of nonzero entries in such that .

afloat, ndarray, shape

Define the coordinates and values of the nonzero elements of the linear part of the function .

In particular, triples define the row and column indices and of the element .

igfunint, ndarray, shape

Define the coordinates of the nonzero elements of , the nonlinear part of the derivatives of the function .

jgvarint, ndarray, shape

Define the coordinates of the nonzero elements of , the nonlinear part of the derivatives of the function .

negint

The number of nonzero entries in .

Raises
NagValueError
(errno )

The initialization function nlp2_sparse_init() has not been called.

(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

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

(errno )

Either or is too small. Increase both of them and corresponding array sizes. and .

(errno )

Cannot estimate Jacobian structure at given point .

(errno )

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

(errno )

Internal memory allocation was insufficient. Please contact NAG.

Warns
NagAlgorithmicWarning
(errno )

User-supplied function requested termination.

Notes

When using nlp2_sparse_solve(), if you set the option and provides none of the derivatives, you may need to call nlp2_sparse_jacobian to determine the input arrays , , , and . 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, , at three random perturbations of the given initial point . 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:

where , and are constant. Note that 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 by setting them to zero before calling . A knowledgeable user would be able to move such elements from in and enter them as part of , and 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