The modeler can tell CONOPT that second order information is available as the Hessian of the Lagrangian, assumed to be a sparse matrix, by registering a 2DLagrStr callback routine using COIDEF_2DLagrStr() before the solve. The number of nonzero elements and the sparsety pattern of the Hessian of the Lagrangian are defined in two setup calls to 2DLagrStr. It is possible during the first setup call to “un-register” the 2DLagrStr by returning the function value -1. This might be required if it turns out that the Hessian is too expensive to evaluate or cannot be computed after all. There is also a maximum size allowed by CONOPT that may prevent further use of the Hessian. The numerical values of the Hessian must be returned by the subsequent call of 2DLagrVal, which is described in 2DLagrVal. The two setup calls will be called during model setup just after ReadMatrix and the numerical calls will be scattered throughout the optimization, usually with no more than one call per iteration.

2DLagrStr - Structure of the Second Derivatives of the Lagrangian

This optional callback routine can be registered using COIDEF_2DLagrStr(). The purpose is to compute and return the sparsety pattern of the Hessian of the Lagrangian. The elements of the Hessian must be sorted column-wise, i.e. the column numbers in COLNO must be non-decreasing. Within each column the elements must be sorted row-wise, i.e. the elements of ROWNO must be increasing for sequences for which COLNO is constant.

int COI_CALLCONV 2DLagrStr( int* ROWNO, int* COLNO, int* NODRV,

int* N, int* M, int* NHESS, void* USRMEM );

where:

ROWNO: Vector of row numbers of the lower triangular part of the Hessian. Must be defined by the modeler when MODE = 2 and is provided as a help to the modeler when MODE = 3.
COLNO: Vector of column numbers of the lower triangular part of the Hessian. Must be defined by the modeler when MODE = 2 and is provided as a help to the modeler when MODE = 3. The elements of the Hessian must be sorted column wise, i.e. COLNO must be non-decreasing. Within each column the elements must be sorted row-wise, i.e. the elements of ROWNO must be increasing for sequences for which COLNO is constant. The row and column numbers are interpreted according to Base, i.e. they are between 1 and N when Base = 1 (Fortran conventions) and between 0 and N-1 when Base = 0 (C conventions).
NODRV: Can be set to 1 if the derivatives for some reason could not be computed, for example because some of them were not defined. Is initialized to 0 by CONOPT. CONOPT will not use second order methods in the current point if NODRV is 1.
N: The number of variables in the model as defined in COIDEF_NumVar(). Provided by CONOPT.
M: The number of constraints in the model as defined in COIDEF_NumCon(). Provided by CONOPT.
NHESS: The number of nonzero elements in the Hessian. When MODE = 1 CONOPT will define the maximum number of elements it will accept in NHESS, and 2DLagrVal must return the actual number of element. If the actual number is larger than the input value of NHESS then CONOPT will not use the Hessian of the Lagrangian and 2DLagrVal will not be called again. When MODE > 1 NHESS is defined by CONOPT as the value provided by the modeler in the first call.
USRMEM: User memory as defined in COIDEF_UsrMem() (Only for Fortran and C API).

2DLagrVal - Values of Second Derivatives of the Lagrangian

Note: This callback must be registered if the 2DLagrStr callback is registered.

This optional callback routines can be registered using COIDEF_2DLagrVal(). It has three modes with the following purposes:

1. Compute and return the number of nonzero elements on the diagonal and in the lower triangular part of the Hessian of the Lagrangian in NHESS. When CONOPT calls 2DLagrVal it will provide a maximum on the number of elements it will accept, also in NHESS, and the modeler can choose to abort and return 2DLagrVal = -1 if this maximum is exceeded. Otherwise, if the number of nonzero elements is too large, CONOPT will not call 2DLagrVal again.

2. Compute and return the sparsety pattern of the Hessian of the Lagrangian. The elements of the Hessian must be sorted column-wise, i.e. the column numbers in COLNO must be non-decreasing. Within each column the elements must be sorted row-wise, i.e. the elements of ROWNO must be increasing for sequences for which COLNO is constant., and

3. Compute the numerical values of the Hessian of the Lagrangian as defined in the introduction to this section. The order of the elements is the same as the order used for the sparsety pattern in the 2^nd call.

int COI_CALLCONV 2DLagrVal( double* X, double* U, int* ROWNO, 
        int* COLNO, double* VALUE, int* NODRV, int* N, 
        int* M, int* NHESS, int* MODE, void* USRMEM );

where:

MODE: Distinguishes between the three modes described above.
X: Vector with the point in which the Hessian of the Lagrangian should be computed. Defined by CONOPT when MODE = 3.
U: The vector of weights on the individual constraints. The Lagrangian is defined as L = SUM(r in rows)U(r) . function(r). U is defined by CONOPT when MODE = 3.
ROWNO: Vector of row numbers of the lower triangular part of the Hessian. Must be defined by the modeler when MODE = 2 and is provided as a help to the modeler when MODE = 3.
COLNO: Vector of column numbers of the lower triangular part of the Hessian. Must be defined by the modeler when MODE = 2 and is provided as a help to the modeler when MODE = 3. The elements of the Hessian must be sorted column wise, i.e. COLNO must be non-decreasing. Within each column the elements must be sorted row-wise, i.e. the elements of ROWNO must be increasing for sequences for which COLNO is constant. The row and column numbers are interpreted according to Base, i.e. they are between 1 and N when Base = 1 (Fortran conventions) and between 0 and N-1 when Base = 0 (C conventions).
VALUE: Vector returning the values of the second derivatives when MODE = 3. The individual elements must be defined in the order used for ROWNO and COLNO. VALUE will be initialized to zero when 2DLagrVal is called and it must be defined by the modeler.
NODRV: Can be set to 1 if the derivatives for some reason could not be computed, for example because some of them were not defined. Is initialized to 0 by CONOPT. CONOPT will not use second order methods in the current point if NODRV is 1.
N: The number of variables in the model as defined in COIDEF_NumVar(). Provided by CONOPT.
M: The number of constraints in the model as defined in COIDEF_NumCon(). Provided by CONOPT.
NHESS: The number of nonzero elements in the Hessian. When MODE = 1 CONOPT will define the maximum number of elements it will accept in NHESS, and 2DLagrVal must return the actual number of element. If the actual number is larger than the input value of NHESS then CONOPT will not use the Hessian of the Lagrangian and 2DLagrVal will not be called again. When MODE > 1 NHESS is defined by CONOPT as the value provided by the modeler in the first call.
USRMEM: User memory as defined in COIDEF_UsrMem() (Only for Fortran and C API).

2DLagrVal will only be called in points in which the constraint values have been computed successfully before with FDEval. Checks for function evaluation errors can therefore usually be limited. Note that 2DLagrVal in some cases can be called in a point that is different from the last point in which FDEval was called.

The maximum number of Hessian nonzero elements accepted by CONOPT is computed as the option value RVHESS multiplied by the number of nonlinear Jacobian elements. The default value of RVHESS is 10. If the Hessian has more than 10 times as many elements as the Jacobian it is expected that it is too expensive to compute and that directional 2^nd derivatives in some form are more efficient to use. The modeler may allow CONOPT to use a denser Hessian by increasing RVHESS.

There is a rudimentary debugger of the values returned by 2DLagrVal. It can be turned on by setting Debug2D in COIDEF_Debug2D() or with the option LKDEB2. Information on the debugger including messages and error return codes can be found in Error Return Codes.