naginterfaces.library.opt.handle_set_quadmatineq¶

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://support.nag.com/numeric/nl/nagdoc_30.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 $(nq)$: The index pairs $i, j$ of the nonzero matrices $Q_{i j}$ in any order.
qjint, array-like, shape $(nq)$: The index pairs $i, j$ of the nonzero matrices $Q_{i j}$ in any order.
dimqint: $d$ , the dimension of matrices $Q_{i j}$ .
nnzqint, array-like, shape $(nq)$: The numbers of nonzero elements in the upper triangles of $Q_{i j}$ matrices.
irowqint, array-like, shape $(nnzqsum)$: The nonzero elements of the upper triangles of matrices $Q_{i j}$ stored in coordinate storage format. The first $n n z q [0]$ elements belong to the first $Q_{i_{1} j_{1}}$ , the following $n n z q [1]$ to $Q_{i_{2} j_{2}}$ , etc.
icolqint, array-like, shape $(nnzqsum)$: The nonzero elements of the upper triangles of matrices $Q_{i j}$ stored in coordinate storage format. The first $n n z q [0]$ elements belong to the first $Q_{i_{1} j_{1}}$ , the following $n n z q [1]$ to $Q_{i_{2} j_{2}}$ , etc.
qfloat, array-like, shape $(nnzqsum)$: The nonzero elements of the upper triangles of matrices $Q_{i j}$ stored in coordinate storage format. The first $n n z q [0]$ elements belong to the first $Q_{i_{1} j_{1}}$ , the following $n n z q [1]$ to $Q_{i_{2} j_{2}}$ , etc.
idblkint: If $i d b l k = 0$ , a new matrix constraint is created; otherwise, $i d b l k = k > 0$ , the number of the existing linear matrix constraint to be expanded with the bilinear terms.

Returns

idblkint: If $i d b l k = 0$ 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, $i d b l k > 0$ stays unchanged.

Raises

NagValueError

(errno $1$ )

$h a n d l e$ has not been initialized.

(errno $1$ )

$h a n d l e$ does not belong to the NAG optimization modelling suite, has not been initialized properly or is corrupted.

(errno $1$ )

$h a n d l e$ has not been initialized properly or is corrupted.

(errno $2$ )

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

(errno $3$ )

On entry, $i d b l k = ⟨ v a l u e ⟩$ .

Bilinear terms of the matrix inequality block with the given $i d b l k$ have already been defined.

(errno $4$ )

On entry, $i d b l k = ⟨ v a l u e ⟩$ .

The given $i d b l k$ refers to a nonexistent matrix inequality block.

No matrix inequalities have been added yet.

(errno $4$ )

On entry, $i d b l k = ⟨ v a l u e ⟩$ .

The given $i d b l k$ does not match with any existing matrix inequality block.

The maximum $i d b l k$ is currently $⟨ v a l u e ⟩$ .

(errno $5$ )

On entry, $d i m q = ⟨ v a l u e ⟩$ , $i d b l k = ⟨ v a l u e ⟩$ .

The correct dimension of the given $i d b l k$ is $⟨ v a l u e ⟩$ .

Constraint: $d i m q$ must match the dimension of the block supplied earlier.

(errno $6$ )

On entry, $i d b l k = ⟨ v a l u e ⟩$ .

Constraint: $i d b l k \geq 0$ .

(errno $6$ )

On entry, $nq = ⟨ v a l u e ⟩$ .

Constraint: $nq > 0$ .

(errno $6$ )

On entry, $d i m q = ⟨ v a l u e ⟩$ .

Constraint: $d i m q > 0$ .

(errno $6$ )

On entry, $nnzqsum = ⟨ v a l u e ⟩$ and $sum (n n z q) = ⟨ v a l u e ⟩$ .

Constraint: $nnzqsum \geq sum (n n z q)$ .

(errno $6$ )

On entry, $i = ⟨ v a l u e ⟩$ and $n n z q [i - 1] = ⟨ v a l u e ⟩$ .

Constraint: $n n z q [i - 1] > 0$ .

(errno $8$ )

On entry, an error occurred in matrix $Q_{i j}$ of index $k = ⟨ v a l u e ⟩$ , $q i [k - 1] = ⟨ v a l u e ⟩$ , $q j [k - 1] = ⟨ v a l u e ⟩$ .

For $j = ⟨ v a l u e ⟩$ , $i r o w q [j - 1] = ⟨ v a l u e ⟩$ and $d i m q = ⟨ v a l u e ⟩$ .

Constraint: $1 \leq i r o w q [j - 1] \leq d i m q$ .

(errno $8$ )

On entry, an error occurred in matrix $Q_{i j}$ of index $k = ⟨ v a l u e ⟩$ , $q i [k - 1] = ⟨ v a l u e ⟩$ , $q j [k - 1] = ⟨ v a l u e ⟩$ .

For $j = ⟨ v a l u e ⟩$ , $i c o l q [j - 1] = ⟨ v a l u e ⟩$ and $d i m q = ⟨ v a l u e ⟩$ .

Constraint: $1 \leq i c o l q [j - 1] \leq d i m q$ .

(errno $8$ )

On entry, an error occurred in matrix $Q_{i j}$ of index $k = ⟨ v a l u e ⟩$ , $q i [k - 1] = ⟨ v a l u e ⟩$ , $q j [k - 1] = ⟨ v a l u e ⟩$ .

For $j = ⟨ v a l u e ⟩$ , $i r o w q [j - 1] = ⟨ v a l u e ⟩$ and $i c o l q [j - 1] = ⟨ v a l u e ⟩$ .

Constraint: $i r o w q [j - 1] \leq i c o l q [j - 1]$ (elements within the upper triangle).

(errno $8$ )

On entry, an error occurred in matrix $Q_{i j}$ of index $k = ⟨ v a l u e ⟩$ , $q i [k - 1] = ⟨ v a l u e ⟩$ , $q j [k - 1] = ⟨ v a l u e ⟩$ .

More than one element of $Q_{i j}$ has row index $⟨ v a l u e ⟩$ and column index $⟨ v a l u e ⟩$ .

Constraint: each element of $Q_{i j}$ must have a unique row and column index.

(errno $9$ )

On entry, $k = ⟨ v a l u e ⟩$ , $q i [k - 1] = ⟨ v a l u e ⟩$ and $n = ⟨ v a l u e ⟩$ .

Constraint: $1 \leq q i [k - 1] \leq n$ .

(errno $9$ )

On entry, $k = ⟨ v a l u e ⟩$ , $q j [k - 1] = ⟨ v a l u e ⟩$ and $n = ⟨ v a l u e ⟩$ .

Constraint: $1 \leq q j [k - 1] \leq n$ .

(errno $9$ )

On entry, index pair with $q i = ⟨ v a l u e ⟩$ and $q j = ⟨ v a l u e ⟩$ repeats.

Constraint: each index pair $q i$ , $q j$ 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:

n \sum 1 x_{i} x_{j} Q_{i j} ⪰ 0

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

n \sum 1 x_{i} x_{j} Q_{i j}^{k} .

Here $Q_{i j}^{k}$ are $d \times d$ (sparse) symmetric matrices and $k$ , 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)

\begin{matrix} \begin{matrix} {m i n i m i z e}_{x \in R^{n}} & \frac{1}{2} x^{T} H x + c^{T} x & (a) subject to & \sum_{1}^{n} x_{i} x_{j} Q_{i j}^{k} + \sum_{1}^{n} x_{i} A_{i}^{k} - A_{0}^{k} ⪰ 0, k = 1, \dots, m_{A}, & (b) l_{B} \leq B x \leq u_{B}, & (c) l_{x} \leq x \leq u_{x} . & (d) \end{matrix} \end{matrix}

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 $i d b l k$ is used to distinguish whether a new matrix constraint should be added ( $i d b l k = 0$ ) or if an existing linear matrix inequality should be extended ( $i d b l k > 0$ ). In the latter case, $i d b l k$ should be set to $k$ , 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 $i d b l k$ . See the E04 Introduction for more details about the NAG optimization modelling suite. In the further text, the index $k$ will be omitted.

Input data organization

It is expected that only some of the matrices $Q_{i j}$ will be nonzero, therefore, only their index pairs $i, j$ are listed in arrays $q i$ and $q j$ . Note that a pair $i, j$ should not repeat, i.e., a matrix $Q_{i j}$ should not be defined more than once. No particular ordering of pairs $i, j$ is expected but other input arrays $i r o w q$ , $i c o l q$ , $q$ and $n n z q$ need to respect the chosen order.

Note: the dimension of $Q_{i j}$ must respect the size of the linear matrix inequality if they are supposed to expand it (case $i d b l k > 0$ ).

Matrices $Q_{i j}$ 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 $Q_{i j}$ matrices are passed to the function in three arrays: $i r o w q$ for row indices, $i c o l q$ for column indices and $q$ for the values. No particular order of nonzeros within one matrix is enforced but all nonzeros belonging to one $Q_{i j}$ matrix need to be stored next to each other. The first $n n z q [0]$ nonzeros belong to $Q_{i_{1} j_{1}}$ where $i_{1} = q i [0]$ , $j_{1} = q j [0]$ , the following $n n z q [1]$ nonzeros to the next one given by $q i$ , $q j$ and so on. The array $n n z q$ thus splits arrays $i r o w q$ , $i c o l q$ and $q$ into sections so that each section defines one $Q_{i j}$ 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.

$i r o w q$	upper triangle	upper triangle		upper triangle
$i c o l q$	nonzeros	nonzeros	$\dots$	nonzeros
$q$	$from Q_{i_{1} j_{1}}     $	$from Q_{i_{2} j_{2}}     $		$from Q_{i_{nq} j_{nq}}     $
	$n n z q [0]$	$n n z q [1]$		$n n z q [nq - 1]$
	$i_{1} = q i [0]$	$i_{2} = q i [1]$		$i_{nq} = q i [nq - 1]$
	$j_{1} = q j [0]$	$j_{2} = q j [1]$		$j_{nq} = q j [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

NAG and Python

Return to Front

naginterfaces.library.opt.handle_set_quadmatineq¶

naginterfaces.library.opt.handle_​set_​quadmatineq¶

naginterfaces.library.opt.handle_set_quadmatineq¶