16.9 Function Types

MSKcallbackfunc
MSKint32t  (MSKAPI * MSKcallbackfunc) (
  MSKtask_t task,
  MSKuserhandle_t usrptr,
  MSKcallbackcodee caller,
  const MSKrealt * douinf,
  const MSKint32t * intinf,
  const MSKint64t * lintinf)

The progress callback function is a user-defined function which will be called by MOSEK occasionally during the optimization process. In particular, the callback function is called at the beginning of each iteration in the interior-point optimizer. For the simplex optimizers MSK_IPAR_LOG_SIM_FREQ controls how frequently the callback is called. The callback provides an code denoting the point in the solver from which the call happened, and a set of arrays containing information items related to the current state of the solver. Typically the user-defined callback function displays information about the solution process. The callback function can also be used to terminate the optimization process by returning a non-zero value.

The user must not call any MOSEK function directly or indirectly from the callback function. The only exception is the possibility to retrieve a current best integer solution from the mixed-integer optimizer, see Section Progress and data callback.

Parameters:
 
  • task (MSKtask_t) – An optimization task. (input)
  • usrptr (MSKuserhandle_t) – A pointer to a user-defined structure. (input/output)
  • caller (MSKcallbackcodee) – The caller key indicating the current progress of the solver. (input)
  • douinf (MSKrealt*) – An array of double information items. The elements correspond to the definitions in MSKdinfiteme. (input)
  • intinf (MSKint32t*) – An array of integer information items. The elements correspond to the definitions in MSKiinfiteme. (input)
  • lintinf (MSKint64t*) – An array of long information items. The elements correspond to the definitions in MSKliinfiteme. (input)
Return:
 

(MSKint32t) – If the return value is non-zero, MOSEK terminates whatever it is doing and returns control to the calling application.

MSKcallocfunc
void *  (MSKAPI * MSKcallocfunc) (
  MSKuserhandle_t usrptr,
  const size_t num,
  const size_t size)

A user-defined memory allocation function. The function must be compatible with the C calloc function.

Parameters:
 
  • usrptr (MSKuserhandle_t) – A pointer to a user-defined structure. (input)
  • num (size_t) – The number of elements. (input)
  • size (size_t) – The size of an element. (input)
Return:
 

(void*) – A pointer to the allocated memory.

MSKexitfunc
void  (MSKAPI * MSKexitfunc) (
  MSKuserhandle_t usrptr,
  const char * file,
  MSKint32t line,
  const char * msg)

A user-defined exit function which is called in case of fatal errors to handle an error message and terminate the program. The function should never return.

Parameters:
 
  • usrptr (MSKuserhandle_t) – A pointer to a user-defined structure. (input/output)
  • file (MSKstring_t) – The name of the file where the fatal error occurred. (input)
  • line (MSKint32t) – The line number in the file where the fatal error occurred. (input)
  • msg (MSKstring_t) – A message about the error. (input)
Return:
 

(void)

MSKfreefunc
void  (MSKAPI * MSKfreefunc) (
  MSKuserhandle_t usrptr,
  void * buffer)

A user-defined memory freeing function.

Parameters:
 
  • usrptr (MSKuserhandle_t) – A pointer to a user-defined structure. (input)
  • buffer (void*) – A pointer to the buffer which should be freed. (input/output)
Return:
 

(void)

MSKmallocfunc
void *  (MSKAPI * MSKmallocfunc) (
  MSKuserhandle_t usrptr,
  const size_t size)

A user-defined memory allocation function. The function must be compatible with the C malloc function.

Parameters:
 
  • usrptr (MSKuserhandle_t) – A pointer to a user-defined structure. (input)
  • size (size_t) – The number of characters to allocate. (input)
Return:
 

(void*) – A pointer to the allocated memory.

MSKnlgetspfunc
MSKint32t  (MSKAPI * MSKnlgetspfunc) (
  MSKuserhandle_t nlhandle,
  MSKint32t * numgrdobjnz,
  MSKint32t * grdobjsub,
  MSKint32t i,
  MSKbooleant * convali,
  MSKint32t * grdconinz,
  MSKint32t * grdconisub,
  MSKint32t yo,
  MSKint32t numycnz,
  const MSKint32t * ycsub,
  MSKint32t maxnumhesnz,
  MSKint32t * numhesnz,
  MSKint32t * hessubi,
  MSKint32t * hessubj)

Type definition of the callback function which is used to provide structural information about the nonlinear functions \(f\) and \(g\) in the optimization problem.

Hence, it is the user’s responsibility to provide a function satisfying the definition.

The user must not call any MOSEK function directly or indirectly from the callback function.

Parameters:
 
  • nlhandle (MSKuserhandle_t) – A pointer to a user-defined data structure specified when the function is attached to a task using the function MSK_putnlfunc. (input/output)
  • numgrdobjnz (MSKint32t*) – If requested, numgrdobjnz should be assigned the number of non-zero elements in the gradient of \(f\). (output)
  • grdobjsub (MSKint32t*) –

    If requested then it contains the positions of the non-zero elements in the gradient of \(f\). The elements are stored in

    \[\mathtt{grdobjsub}[\idxbeg,..,\idxend{numgrdobjnz}].\]
    (output)
  • i (MSKint32t) – Index of a constraint. If \(i<0\) or \(i\geq\mathtt{numcon}\), no information about a constraint is requested. (input)
  • convali (MSKbooleant*) – If requested, assign a true/false value indicating if constraint i contains general nonlinear terms. (output)
  • grdconinz (MSKint32t*) – If requested, it should be assigned the number of non-zero elements in \(\nabla g_i(x)\). (output)
  • grdconisub (MSKint32t*) – If requested, this array shall contain the indexes of the non-zeros in \(\nabla g_i(x)\). The length of the array must be the same as given in grdconinz. (output)
  • yo (MSKint32t) – If non-zero, then \(f\) shall be included when the gradient and the Hessian of the Lagrangian are computed. (input)
  • numycnz (MSKint32t) – Number of constraint functions which are included in the definition of the Lagrangian. See (1). (input)
  • ycsub (MSKint32t*) – Indexes of constraint functions which are included in the definition of the Lagrangian. See (1). (input)
  • maxnumhesnz (MSKint32t) – Length of the arguments hessubi and hessubj. (input)
  • numhesnz (MSKint32t*) –

    If requested, numhesnz should be assigned the number of non-zero elements in the lower triangular part of the Hessian of the Lagrangian:

    (1)\[L := \mathtt{yo} f(x) - \sum_{k=\idxbeg}^{\idxend{numycnz}} g_{\mathtt{ycsub[k]}}(x).\]
    (output)
  • hessubi (MSKint32t*) –

    If requested, hessubi and hessubj are used to convey the position of the non-zeros in the Hessian of the Lagrangian \(L\) (see (1)) as follows

    \[\nabla^2 L_{\mathtt{hessubi}[k],\mathtt{hessubj}[k]} (x) \neq 0.0\]

    for \(k=0,\ldots,\mathtt{numhesnz}-1\).

    All other positions in \(L\) are assumed to be zero. Please note that only the lower or the upper triangular part of the Hessian should be return.

    (output)
  • hessubj (MSKint32t*) – See the argument hessubi. (output)
Return:
 

(MSKint32t) – If the return is non-zero, MOSEK assumes that an error occurred during the structure computation, and optimization will be terminated.

MSKnlgetvafunc
MSKint32t  (MSKAPI * MSKnlgetvafunc) (
  MSKuserhandle_t nlhandle,
  const MSKrealt * xx,
  MSKrealt yo,
  const MSKrealt * yc,
  MSKrealt * objval,
  MSKint32t * numgrdobjnz,
  MSKint32t * grdobjsub,
  MSKrealt * grdobjval,
  MSKint32t numi,
  const MSKint32t * subi,
  MSKrealt * conval,
  const MSKint32t * grdconptrb,
  const MSKint32t * grdconptre,
  const MSKint32t * grdconsub,
  MSKrealt * grdconval,
  MSKrealt * grdlag,
  MSKint32t maxnumhesnz,
  MSKint32t * numhesnz,
  MSKint32t * hessubi,
  MSKint32t * hessubj,
  MSKrealt * hesval)

Type definition of the callback function which is used to provide structural and numerical information about the nonlinear functions \(f\) and \(g\) in an optimization problem.

For later use we need the definition of the Lagrangian \(L\) which is given by

(2)\[L := \mathtt{yo} * f(\mathtt{xx}) - \sum_{k=\idxbeg}^{\idxend{numi}} \mathtt{yc}_{\mathtt{subi[k]}} g_{\mathtt{subi[k]}} (\mathtt{xx}).\]

The user must not call any MOSEK function directly or indirectly from the callback function.

Parameters:
 
  • nlhandle (MSKuserhandle_t) – A pointer to a user-defined data structure. The pointer is passed to MOSEK when the function MSK_putnlfunc is called. (input/output)
  • xx (MSKrealt*) – The point at which the nonlinear function must be evaluated. The length equals the number of variables in the task. (input)
  • yo (MSKrealt) – Multiplier on the objective function \(f\). (input)
  • yc (MSKrealt*) – Multipliers for the constraint functions \(g_i\). The length is numcon. (input)
  • objval (MSKrealt*) – If requested, objval shall be assigned the value of \(f\) evaluated at \(xx\). (output)
  • numgrdobjnz (MSKint32t*) – If requested, numgrdobjnz shall be assigned the number of non-zero elements in the gradient of \(f\). (output)
  • grdobjsub (MSKint32t*) –

    If requested, it shall contain the position of the non-zero elements in the gradient of \(f\). The elements are stored in

    \[\mathtt{grdobjsub}[\idxbeg,\ldots,\idxend{numgrdobjnz}].\]
    (output)
  • grdobjval (MSKrealt*) –

    If requested, it shall contain the gradient of \(f\) evaluated at \(\mathtt{xx}\). The following data structure

    \[\mathtt{grdobjval[k]} = \frac{\partial f}{\partial x_{\mathtt{grdobjsub[k]} } } (\mathtt{xx})\]

    for \(k=\idxbeg,\ldots,\idxend{numgrdobjnz}\) is used.

    (output)
  • numi (MSKint32t) – Number of elements in subi. (input)
  • subi (MSKint32t*) – \(\mathtt{subi}[\idxbeg,...,\idxend{numi}]\) contain the indexes of the constraints that has to be evaluated. The length is numi. (input)
  • conval (MSKrealt*) –

    \(g(\mathtt{xx})\) for the required constraint functions i.e.

    \[\mathtt{conval[k]} = g_{\mathtt{subi[k]}}(\mathtt{xx)}\]

    for \(k=\idxbeg,\ldots,\idxend{numi}.\)

    (output)
  • grdconptrb (MSKint32t*) – If given, it specifies the structure of the gradients of the constraint functions. See the argument grdconval for details. (input)
  • grdconptre (MSKint32t*) – If given, it specifies the structure of the gradients of the constraint functions. See the argument grdconval for details. (input)
  • grdconsub (MSKint32t*) – It shall specifies the positions of the non-zeros in the gradients of the constraints. See the argument grdconval for details. (input)
  • grdconval (MSKrealt*) –

    If requested, it shall specify the values of the gradient of the nonlinear constraints.

    Together grdconptrb, grdconptre, grdconsub and grdconval are used to specify the gradients of the nonlinear constraint functions.

    The gradient data is stored as follows

    \[\begin{split}\begin{array}{l} \mathtt{grdconval[k]} = \frac{\partial g_{\mathtt{subi[i]}}(xx)}{\partial xx_{\mathtt{grdconsub[k]}}}, \quad \mbox{for} \\ \quad k=\mathtt{grdconptrb}[i],\ldots,\mathtt{grdconptre}[i]-1, \\ \quad i=\idxbeg,\ldots,\idxend{numi}. \end{array}\end{split}\]
    (output)
  • grdlag (MSKrealt*) –

    If requested, grdlag shall contain the gradient of the Lagrangian function, i.e.

    \[\mathtt{grdlag} = \nabla L.\]
    (output)
  • maxnumhesnz (MSKint32t) – Maximum number of non-zeros in the Hessian of the Lagrangian, i.e. maxnumhesnz is the length of the arrays hessubi, hessubj, and hesval. (input)
  • numhesnz (MSKint32t*) – If requested, numhesnz shall be assigned the number of non-zeros elements in the Hessian of the Lagrangian \(L\). See (2). (output)
  • hessubi (MSKint32t*) – See the argument hesval. (output)
  • hessubj (MSKint32t*) – See the argument hesval. (output)
  • hesval (MSKrealt*) –

    Together hessubi, hessubj, and hesval specify the Hessian of the Lagrangian function \(L\) defined in (2).

    The Hessian is stored in the following format:

    \[\mathtt{hesval}[k] = \nabla^2 L_{\min(\mathtt{hessubi}[k],\mathtt{hessubj}[k]),\max(\mathtt{hessubi}[k],\mathtt{hessubj}[k])}\]

    for \(k=\idxbeg,\ldots,\idxend{numhesnz[\idxbeg]}\). Please note that if an element is specified multiple times, then the elements are added together. Hence, only the lower or the upper triangular part of the Hessian should be returned.

    (output)
Return:
 

(MSKint32t) – If the return value is non-zero, MOSEK will assume an error happened during the function evaluation.

MSKreallocfunc
void *  (MSKAPI * MSKreallocfunc) (
  MSKuserhandle_t usrptr,
  void * ptr,
  const size_t size)

A user-defined memory reallocation function. The function must be compatible with the C realloc function.

Parameters:
 
  • usrptr (MSKuserhandle_t) – A pointer to a user-defined structure. (input)
  • ptr (void*) – The pointer to the allocated memory. (input/output)
  • size (size_t) – Size of the new block. (input)
Return:
 

(void*) – A pointer to the allocated memory.

MSKresponsefunc
MSKrescodee  (MSKAPI * MSKresponsefunc) (
  MSKuserhandle_t handle,
  MSKrescodee r,
  const char * msg)

Whenever MOSEK generates a warning or an error this function is called. The argument r contains the code of the error/warning and the argument msg contains the corresponding error/warning message. This function should always return MSK_RES_OK.

Parameters:
 
  • handle (MSKuserhandle_t) – A pointer to a user-defined data structure (or a null pointer). (input/output)
  • r (MSKrescodee) – The response code corresponding to the exception. (input)
  • msg (MSKstring_t) – A string containing the exception message. (input)
Return:
 

(MSKrescodee) – The function response code.

MSKstreamfunc
void  (MSKAPI * MSKstreamfunc) (
  MSKuserhandle_t handle,
  const char * str)

The message-stream callback function is a user-defined function which can be linked to any of the MOSEK streams. Doing so, the function is called whenever MOSEK sends a message to the stream.

The user must not call any MOSEK function directly or indirectly from the callback function.

Parameters:
 
  • handle (MSKuserhandle_t) – A pointer to a user-defined data structure (or a null pointer). (input/output)
  • str (MSKstring_t) – A string containing a message to a stream. (input)
Return:
 

(void)