hide long namesshow long names
hide short namesshow short names
Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

NAG Toolbox: nag_opt_nlp2_sparse_jacobian (e04vj)

 Contents

    1  Purpose
    2  Syntax
    7  Accuracy
    9  Example

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:
At Mark 22: lencw, leniw and lenrw were removed from the interface

Description

When using nag_opt_nlp2_sparse_solve (e04vh), if you set the optional parameter 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, Fx , 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, nag_opt_nlp2_sparse_jacobian (e04vj) finds that the Jacobian can be permuted to the form:
Gx A3 A2 A4 ,  
where A2 , A3  and A4  are constant. Note that Gx  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  by setting them to zero before calling usrfun. A knowledgeable user would be able to move such elements from Fx  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 Description of the s in nag_opt_nlp2_sparse_solve (e04vh).

Compulsory Input Parameters

1:     nf int64int32nag_int scalar
nf, the number of problem functions in Fx , 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 .
Constraint: nf>0.
2:     usrfun – function handle or string containing name of m-file
usrfun must define the problem functions Fx . This function is passed to nag_opt_nlp2_sparse_jacobian (e04vj) as the external argument 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
There is nothing special about the current call to usrfun.
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 , the number of variables, as defined in the call to nag_opt_nlp2_sparse_jacobian (e04vj).
3:     xn – double array
The variables x  at which the problem functions are to be calculated. The array 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, the number of problem functions.
6:     fnf – 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 to indicate that g is not required.
8:     leng int64int32nag_int scalar
The dimension of the array g.
9:     gleng – double array
Concerns the calculations of the derivatives of the function fx .
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 at the current x . (For example, the problem functions may not be defined there).
nag_opt_nlp2_sparse_jacobian (e04vj) evaluates Fx at random perturbation of the initial point x , say xp . If the functions cannot be evaluated at xp , you can set 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 status-2 .
2:     fnf – double array
The computed Fx according to the setting of needf.
If needf=0 , f is not required and is ignored.
If needf > 0 , the components of Fx must be calculated and assigned to f. nag_opt_nlp2_sparse_jacobian (e04vj) will always call usrfun with needf>0 .
To simplify the code, you may ignore the value of needf and compute Fx on every entry to usrfun.
3:     gleng – double array
nag_opt_nlp2_sparse_jacobian (e04vj) will always call usrfun with 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. lena should be an overestimate of the number of elements in the linear part of the Jacobian.
Constraint: lena1.
4:     leng int64int32nag_int scalar
The dimension of the arrays igfun and jgvar that define the varying Jacobian elements i,j,Gij. leng should be an overestimate of the number of elements in the nonlinear part of the Jacobian.
Constraint: leng1.
5:     xn – double array
An initial estimate of the variables x . The contents of 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:     xlown – double array
7:     xuppn – double array
Contain the lower and upper bounds lx  and ux  on the variables x .
To specify a nonexistent lower bound lx j =- , set xlowj -bigbnd , where bigbnd  is the optional parameter Infinite Bound Size. To specify a nonexistent upper bound xuppj bigbnd .
To fix the j th variable (say, xj=β , where β < bigbnd ), set xlowj=xuppj=β .
8:     cwlencw – cell array of strings
lencw, the dimension of the array, must satisfy the constraint lencw600.
Constraint: lencw600.
9:     iwleniw int64int32nag_int array
leniw, the dimension of the array, must satisfy the constraint leniw600.
Constraint: leniw600.
10:   rwlenrw – double array
lenrw, the dimension of the array, must satisfy the constraint lenrw600.
Constraint: lenrw600.

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, the number of variables.
Constraint: 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.

Output Parameters

1:     iafunlena int64int32nag_int array
2:     javarlena int64int32nag_int array
Define the coordinates i,j and values Aij of the nonzero elements of the linear part A of the function Fx=fx + Ax .
In particular, nea triples iafunk,javark,ak define the row and column indices i=iafunk and j=javark of the element Aij=ak .
3:     nea int64int32nag_int scalar
Is the number of nonzero entries in A such that Fx=fx + Ax .
4:     alena – double array
Define the coordinates i,j and values Aij of the nonzero elements of the linear part A of the function Fx=fx + Ax .
In particular, nea triples iafunk,javark,ak define the row and column indices i=iafunk and j=javark of the element Aij=ak .
5:     igfunleng int64int32nag_int array
6:     jgvarleng int64int32nag_int array
Define the coordinates i,j of the nonzero elements of G , the nonlinear part of the derivatives Jx=Gx + A of the function Fx=fx + Ax .
7:     neg int64int32nag_int scalar
The number of nonzero entries in G .
8:     cwlencw – cell array of strings
cw=state.cwlencw=600.
Communication array, used to store information between calls to nag_opt_nlp2_sparse_jacobian (e04vj).
9:     iwleniw int64int32nag_int array
iw=state.iwleniw=600.
Communication array, used to store information between calls to nag_opt_nlp2_sparse_jacobian (e04vj).
10:   rwlenrw – double array
rw=state.rwlenrw=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
ifail=0 unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

Errors or warnings detected by the function:
   ifail=1
Constraint: lencw600.
Constraint: leniw600.
Constraint: lenrw600.
The initialization function nag_opt_nlp2_sparse_init (e04vg) has not been called.
   ifail=2
Constraint: lena1.
Constraint: leng1.
   ifail=3
User-supplied function usrfun indicates that functions are undefined near given point x.
You have indicated that the problem functions are undefined by setting 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.
   ifail=4
User-supplied function usrfun 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 on exit from usrfun.
   ifail=5
Either lena or leng is too small.
   ifail=6
Cannot estimate Jacobian structure at given point x.
   ifail=7
Internal error.
   ifail=8
Internal memory allocation was insufficient. Please contact NAG.
   ifail=-99
An unexpected error has been triggered by this routine. Please contact NAG.
   ifail=-399
Your licence key may have expired or may not have been installed correctly.
   ifail=-999
Dynamic memory allocation failed.

Accuracy

Not applicable.

Further Comments

None.

Example

This example shows how to call nag_opt_nlp2_sparse_jacobian (e04vj) to determine the sparsity pattern of the Jacobian before calling nag_opt_nlp2_sparse_solve (e04vh) to solve a sparse nonlinear programming problem without providing the Jacobian information in usrfun.
It is a reformulation of Problem 74 from Hock and Schittkowski (1981) and involves the minimization of the nonlinear function
fx = 10-6 x33 + 23 × 10-6 x43+3 x3+2 x4  
subject to the bounds
-0.55x1 0.55, -0.55x2 0.55, 0x3 1200, 0x4 1200,  
to the nonlinear constraints
1000sin-x1-0.25+1000sin-x2-0.25-x3 = -894.8, 1000sinx1-0.25+1000sinx1-x2-0.25-x4 = -894.8, 1000sinx2-0.25+1000sinx2-x1-0.25 = -1294.8,  
and to the linear constraints
-x1+x2-0.55, -x1-x2-0.55.  
The initial point, which is infeasible, is
x0 = 0, 0, 0, 0 T ,  
and fx0=0.
The optimal solution (to five figures) is
x*=0.11887,-0.39623,679.94,1026.0T,  
and fx*=5126.4. All the nonlinear constraints are active at the solution.
The formulation of the problem combines the constraints and the objective into a single vector ( F ).
F = 1000 sin -x1 - 0.25 + 1000 sin -x2 - 0.25 - x3 1000 sin x1 - 0.25 + 1000 sin x1 - x2 - 0.25 - x4 1000 sin x2 - 0.25 + 1000 sin x2 - x1 - 0.25 -x1 + x2 x1 - x2 10-6 x33 + 23 × 10-6 x43 + 3x3 + 2x4  
function e04vj_example


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

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;

[iarow, iacol, nea, a, igrow, igcol, neg, cw, iw, rw, cuser, ifail] = ...
    e04vj(...
          nf, @usrfun, lena, leng, x, xlow, xupp, cw, iw, rw);

fprintf(' Matrix A:\n');
fprintf(' Non-zero entries = %3d\n',nea);
fprintf(' values         : ');
fprintf('%3.0f',a(1:nea));
fprintf('\n row indices    : ');
fprintf('%3d',iarow(1:nea));
fprintf('\n column indices : ');
fprintf('%3d',iacol(1:nea));
fprintf('\n\n Matrix G:\n');
fprintf(' Non-zero entries = %3d\n',neg);
fprintf(' row indices    : ');
fprintf('%3d',igrow(1:neg));
fprintf('\n column indices : ');
fprintf('%3d',igcol(1:neg));
fprintf('\n');



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
e04vj example results

 Matrix A:
 Non-zero entries =   4
 values         :  -1  1  1 -1
 row indices    :   4  5  4  5
 column indices :   1  1  2  2

 Matrix G:
 Non-zero entries =  10
 row indices    :   1  2  3  1  2  3  6  6  1  2
 column indices :   1  1  1  2  2  2  3  4  3  4

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015