NAG Library Function Document

nag_opt_handle_init (e04rac)

 Contents

    1  Purpose
    7  Accuracy
    10  Example

1
Purpose

nag_opt_handle_init (e04rac) initializes a data structure for the NAG optimization modelling suite for problems such as, linear programming (LP), quadratic programming (QP), nonlinear programming (NLP), least squares (LSQ) problems, linear semidefinite programming (SDP) and semidefinite programming with bilinear matrix inequalities (BMI-SDP).

2
Specification

#include <nag.h>
#include <nage04.h>
void  nag_opt_handle_init (void **handle, Integer nvar, NagError *fail)

3
Description

nag_opt_handle_init (e04rac) initializes an empty problem with n decision variables, x, and returns a handle to the data structure. This handle may then be passed to some of the functions nag_opt_handle_set_linobj (e04rec), nag_opt_handle_set_quadobj (e04rfc), nag_opt_handle_set_nlnobj (e04rgc), nag_opt_handle_set_simplebounds (e04rhc), nag_opt_handle_set_linconstr (e04rjc), nag_opt_handle_set_nlnconstr (e04rkc), nag_opt_handle_set_nlnhess (e04rlc), nag_opt_handle_set_nlnls (e04rmc), nag_opt_handle_set_linmatineq (e04rnc) and nag_opt_handle_set_quadmatineq (e04rpc) to formulate the problem (define the objective function and constraints) and to a compatible solver, nag_opt_handle_solve_dfls (e04ffc), nag_opt_handle_solve_lp_ipm (e04mtc), nag_opt_handle_solve_ipopt (e04stc) or nag_opt_handle_solve_pennon (e04svc), to solve it. The handle must not be changed between calls. When the handle is no longer needed, nag_opt_handle_free (e04rzc) must be called to destroy it and deallocate all the allocated memory and data within. In addition, the suite comprises auxiliary functions for extracting or providing information to the handle (nag_opt_handle_set_get_real (e04rxc)), for printing (nag_opt_handle_print (e04ryc)), for setting optional parameters (nag_opt_handle_opt_set (e04zmc) and nag_opt_handle_opt_set_file (e04zpc)), for retrieving them (nag_opt_handle_opt_get (e04znc)) and for reading data files for linear semidefinite programming (nag_opt_sdp_read_sdpa (e04rdc)).
The handle can store various problem formulations, including linear programming (LP)
minimize xn cTx   (a) subject to   lBBxuB   (b) lxxux ,   (c) (1)
quadratic programming (QP)
minimize xn 12 xTHx + cTx   (a) subject to   lBBxuB   (b) lxxux ,   (c) (2)
nonlinear programming (NLP)
minimize xn fx   (a) subject to lggxug   (b) lBBxuB   (c) lxxux   (d) (3)
least squares (LSQ) problems
minimize xn i=1 mr ri x 2   (a) subject to lxxux ,   (b) (4)
linear semidefinite programming (SDP)
minimize xn cTx   (a) subject to   i=1 n xi Aik - A0k 0 ,  k=1,,mA   (b) lBBxuB   (c) lxxux   (d) (5)
or semidefinite programming with bilinear matrix inequalities (BMI-SDP)
minimize xn 12 xTHx + cTx   (a) subject to   i,j=1 n xi xj Qijk + i=1 n xi Aik - A0k 0 ,  k=1,,mA   (b) lBBxuB   (c) lxxux ,   (d) (6)
where H, Aik and Qijk denote symmetric matrices, B is a general rectangular matrix, mA is the number of semidefinite constraints (matrix inequalities) and c, l and u are vectors. The expression S0 stands for a constraint on eigenvalues of a symmetric matrix S, namely, all the eigenvalues should be non-negative, i.e., the matrix S should be positive semidefinite.

3.1
Life Cycle of the Handle

Each handle should pass four stages in its life as depicted in the diagram below. These are initialization, problem formulation, problem solution and deallocation. The initialization by nag_opt_handle_init (e04rac) and deallocation by nag_opt_handle_free (e04rzc) mark the beginning and the end of the life of the handle. During this time the handle must only be modified by the provided functions. Working with a handle which has not been properly initialized will result in fail.code= NE_HANDLE (uniform across the suite) and is potentially very dangerous as it may cause unpredictable behaviour.
After the handle has been initialized, various functions are provided to add the following basic building blocks to the problem formulation: objective function, simple variable bounds, (standard) linear and nonlinear constraints and matrix constraints. Some of these can be defined at most once (e.g., objective function) and an attempt to redefine them will return fail.code= NE_ALREADY_DEFINED. Others (matrix constraints) may be composed using several repetitive calls. The functions work in tight cooperation and if the provided data is not compatible with the previous information, fail.code= NE_REF_MATCH is returned.
The handle may be passed to one of the following functions to define the objective function: Only one objective may be defined. If none of them are used the problem will find a feasible point satisfying the constraints.
The functions for constraint definition are:
These functions may be called in an arbitrary order, however, a call to nag_opt_handle_set_linmatineq (e04rnc) must precede a call to nag_opt_handle_set_quadmatineq (e04rpc) for the matrix inequalities with bilinear terms and the nonlinear objective or constraints (nag_opt_handle_set_nlnobj (e04rgc) or nag_opt_handle_set_nlnconstr (e04rkc)) must precede the definition of the second derivatives by nag_opt_handle_set_nlnhess (e04rlc). A call to nag_opt_handle_set_linmatineq (e04rnc) can be repeated several times if more matrix inequality constraints are required.
When the problem is fully formulated, the handle can be passed to a solver which is compatible with the defined problem. The NAG optimization modelling suite comprises of nag_opt_handle_solve_dfls (e04ffc), nag_opt_handle_solve_lp_ipm (e04mtc), nag_opt_handle_solve_ipopt (e04stc) and nag_opt_handle_solve_pennon (e04svc). If the solver cannot deal with the given problem, fail.code= NE_SETUP_ERROR is returned. Once the solver is called, no further modifications of the problem formulation are allowed and calling any of the functions defining the objective function or the constraints will return fail.code= NE_PHASE. The solver may be called repetitively, for example, with various optional parameters and/or starting points.
Any optional parameters may be set by a call to nag_opt_handle_opt_set (e04zmc) at any time between the initialization by nag_opt_handle_init (e04rac) and the call to the solver or after the solver returns. Several optional parameters can be modified at once by nag_opt_handle_opt_set_file (e04zpc) when an option file is used. The current value of the optional parameters may be retrieved by nag_opt_handle_opt_get (e04znc).
For further details, see the documentation of the individual functions and the solvers which also contain a description of all the optional parameters.
Figure figure1
Figure 1

4
References

None.

5
Arguments

1:     handle void **Output
Note: handle does not need to be set on input.
On exit: holds a handle to the internal data structure where an empty problem with nvar variables is defined. You must not change the handle until the call to nag_opt_handle_free (e04rzc) (deallocation).
2:     nvar IntegerInput
On entry: n, the number of decision variables in the problem.
Constraint: nvar>0.
3:     fail NagError *Input/Output
The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

6
Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 2.3.1.2 in How to Use the NAG Library and its Documentation for further information.
NE_BAD_PARAM
On entry, argument value had an illegal value.
NE_INT
On entry, nvar=value.
Constraint: nvar>0.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
See Section 2.7.6 in How to Use the NAG Library and its Documentation for further information.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 2.7.5 in How to Use the NAG Library and its Documentation for further information.

7
Accuracy

Not applicable.

8
Parallelism and Performance

nag_opt_handle_init (e04rac) is not threaded in any implementation.

9
Further Comments

None.

10
Example

See examples associated with other functions in the suite:
the example in Section 10 in nag_opt_handle_solve_dfls (e04ffc) demonstrates how to use a DFO LSQ solver,
the example in Section 10 in nag_opt_handle_solve_lp_ipm (e04mtc) solves a small LP example using an LP IPM solver,
the example in Section 10 in nag_opt_sdp_read_sdpa (e04rdc) demonstrates how to use the SDPA file reader and how to solve linear semidefinite programming problems, including printing of the matrix Lagrangian multipliers,
the example in Section 10 in nag_opt_handle_set_quadobj (e04rfc) presents an alternative way to compute the nearest correlation matrix by means of nonlinear semidefinite programming,
a matrix completion problem (minimization of a rank of a partially unknown matrix) formulated as SDP is demonstrated in Section 10 in nag_opt_handle_set_simplebounds (e04rhc), the example also demonstrates the monitoring mode of the solver nag_opt_handle_solve_pennon (e04svc),
the example in Section 10 in nag_opt_handle_set_linconstr (e04rjc) solves LP/QP problems read in from an MPS file by nag_opt_miqp_mps_read (e04mxc),
an application for statistics, E optimal design, solved as an SDP problem is shown in Section 10 in nag_opt_handle_set_linmatineq (e04rnc),
the example in Section 10 in nag_opt_handle_set_quadmatineq (e04rpc) reads a BMI-SDP problem from a file which can be modified, in this case it solves a Static Output Feedback (SOF) problem,
the example in Section 10 in nag_opt_handle_set_get_real (e04rxc) demonstrates how an approximate solution can be extracted during a monitoring step of nag_opt_handle_solve_lp_ipm (e04mtc),
the example in Section 10 in nag_opt_handle_print (e04ryc) walks through the life cycle of the handle in which a BMI-SDP problem is formulated and solved,
an example in Section 10 in nag_opt_handle_solve_ipopt (e04stc) is a small test from Hock and Schittkowski set to show how to call the NLP solver,
the simple example in Section 10 in nag_opt_handle_solve_pennon (e04svc) demonstrates on the Lovász ϑ function eigenvalue optimization problem formulated as SDP.
© The Numerical Algorithms Group Ltd, Oxford, UK. 2017