naginterfaces.library.opt.handle_set_quadmatineq(handle, qi, qj, dimq, nnzq, irowq, icolq, q, idblk)[source]

handle_set_quadmatineq is a part of the NAG optimization modelling suite and defines bilinear matrix terms either in a new matrix constraint or adds them to an existing linear matrix inequality.

For full information please refer to the NAG Library document for e04rp

https://www.nag.com/numeric/nl/nagdoc_29.2/flhtml/e04/e04rpf.html

Parameters
handleHandle

The handle to the problem. It needs to be initialized (e.g., by handle_init()) and must not be changed between calls to the NAG optimization modelling suite.

qiint, array-like, shape

The index pairs of the nonzero matrices in any order.

qjint, array-like, shape

The index pairs of the nonzero matrices in any order.

dimqint

, the dimension of matrices .

nnzqint, array-like, shape

The numbers of nonzero elements in the upper triangles of matrices.

irowqint, array-like, shape

The nonzero elements of the upper triangles of matrices stored in coordinate storage format. The first elements belong to the first , the following to , etc.

icolqint, array-like, shape

The nonzero elements of the upper triangles of matrices stored in coordinate storage format. The first elements belong to the first , the following to , etc.

qfloat, array-like, shape

The nonzero elements of the upper triangles of matrices stored in coordinate storage format. The first elements belong to the first , the following to , etc.

idblkint

If , a new matrix constraint is created; otherwise, , the number of the existing linear matrix constraint to be expanded with the bilinear terms.

Returns
idblkint

If on entry, the number of the new matrix constraint is returned. By definition, it is the number of matrix inequalities already defined plus one. Otherwise, stays unchanged.

Raises
NagValueError
(errno )

has not been initialized.

(errno )

does not belong to the NAG optimization modelling suite, has not been initialized properly or is corrupted.

(errno )

has not been initialized properly or is corrupted.

(errno )

The problem cannot be modified right now, the solver is running.

(errno )

On entry, .

Bilinear terms of the matrix inequality block with the given have already been defined.

(errno )

On entry, .

The given refers to a nonexistent matrix inequality block.

No matrix inequalities have been added yet.

(errno )

On entry, .

The given does not match with any existing matrix inequality block.

The maximum is currently .

(errno )

On entry, , .

The correct dimension of the given is .

Constraint: must match the dimension of the block supplied earlier.

(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

On entry, .

Constraint: .

(errno )

On entry, and .

Constraint: .

(errno )

On entry, and .

Constraint: .

(errno )

On entry, an error occurred in matrix of index , , .

For , and .

Constraint: .

(errno )

On entry, an error occurred in matrix of index , , .

For , and .

Constraint: .

(errno )

On entry, an error occurred in matrix of index , , .

For , and .

Constraint: (elements within the upper triangle).

(errno )

On entry, an error occurred in matrix of index , , .

More than one element of has row index and column index .

Constraint: each element of must have a unique row and column index.

(errno )

On entry, , and .

Constraint: .

(errno )

On entry, , and .

Constraint: .

(errno )

On entry, index pair with and repeats.

Constraint: each index pair , must be unique.

Notes

After the initialization function handle_init() has been called, handle_set_quadmatineq may be used to define bilinear matrix terms. It may be used in two ways, either to add to the problem formulation a new bilinear matrix inequality (BMI) which does not have linear terms:

or to extend an existing linear matrix inequality constraint by bilinear terms:

Here are (sparse) symmetric matrices and , if present, is the number of the existing constraint. This function will typically be used on semidefinite programming problems with bilinear matrix constraints (BMI-SDP)

The function can be called multiple times to define an additional matrix inequality or to extend an existing one, but it cannot be called twice to extend the same matrix inequality. The argument is used to distinguish whether a new matrix constraint should be added () or if an existing linear matrix inequality should be extended (). In the latter case, should be set to , the number of the existing inequality. See handle_set_linmatineq() for details about formulation of linear matrix constraints and their numbering and a further description of . See the E04 Introduction for more details about the NAG optimization modelling suite. In the further text, the index will be omitted.

Input data organization

It is expected that only some of the matrices will be nonzero, therefore, only their index pairs are listed in arrays and . Note that a pair should not repeat, i.e., a matrix should not be defined more than once. No particular ordering of pairs is expected but other input arrays , , and need to respect the chosen order.

Note: the dimension of must respect the size of the linear matrix inequality if they are supposed to expand it (case ).

Matrices are symmetric and thus only their upper triangles are passed to the function. They are stored in sparse coordinate storage format (see the F11 Introduction), i.e., every nonzero from the upper triangles is coded as a triplet of row index, column index and the numeric value. All these triplets from all matrices are passed to the function in three arrays: for row indices, for column indices and for the values. No particular order of nonzeros within one matrix is enforced but all nonzeros belonging to one matrix need to be stored next to each other. The first nonzeros belong to where , , the following nonzeros to the next one given by , and so on. The array thus splits arrays , and into sections so that each section defines one matrix. See Table [label omitted] below. Functions handle_set_linmatineq() and sdp_read_sdpa() use the same data organization so further examples can be found there.

 irowq upper triangle upper triangle upper triangle icolq nonzeros nonzeros ⋯ nonzeros q from Qi1j1 from Qi2j2 from Qinqjnq nnzq nnzq nnzq[nq−1] i1=qi i2=qi inq=qi[nq−1] j1=qj j2=qj jnq=qj[nq−1]
References

Syrmos, V L, Abdallah, C T, Dorato, P and Grigoriadis, K, 1997, Static output feedback – a survey, Journal Automatica (Journal of IFAC) (Volume 33) (2), 125–137