naginterfaces.library.opt.handle_​set_​linmatineq

naginterfaces.library.opt.handle_set_linmatineq(handle, dima, nnza, irowa, icola, a, blksizea=None, idblk=0)

handle_set_linmatineq is a part of the NAG optimization modelling suite and defines one or more linear matrix constraints of the problem.

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

https://support.nag.com/numeric/nl/nagdoc_30/flhtml/e04/e04rnf.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.

dimaint

$d$, the dimension of the matrices $A_{\text{i}}$, for $\text{i}=0,1,\dots ,\text{nvar}$.

nnzaint, array-like, shape $(\text{nvar}+1)$

$nnza\left[\text{i}\right]$, for $\text{i}=0,1,\dots ,\text{nvar}$, gives the number of nonzero elements in the upper triangle of matrix $A_i$. To define $A_i$ as a zero matrix, set $nnza\left[i\right]=0$. However, there must be at least one matrix with at least one nonzero.

irowaint, array-like, shape $\left(\text{nnzasum}\right)$

Nonzero elements in upper triangle of matrices $A_i$ stored in coordinate storage. The first $nnza\left[0\right]$ elements belong to $A_0$, the following $nnza\left[1\right]$ elements belong to $A_1$, etc. See explanation above.

icolaint, array-like, shape $\left(\text{nnzasum}\right)$

Nonzero elements in upper triangle of matrices $A_i$ stored in coordinate storage. The first $nnza\left[0\right]$ elements belong to $A_0$, the following $nnza\left[1\right]$ elements belong to $A_1$, etc. See explanation above.

afloat, array-like, shape $\left(\text{nnzasum}\right)$

Nonzero elements in upper triangle of matrices $A_i$ stored in coordinate storage. The first $nnza\left[0\right]$ elements belong to $A_0$, the following $nnza\left[1\right]$ elements belong to $A_1$, etc. See explanation above.

blksizeaNone or int, array-like, shape $\left(\text{nblk}\right)$, optional

If $\text{nblk}>1$, sizes $d_k$ of the diagonal blocks.

If $\text{nblk}=1$, $blksizea$ is not referenced.

idblkint, optional

If $idblk=0$, new matrix inequalities are created. This is the only value allowed at the moment; nonzero values are reserved for future releases of the NAG Library.

Returns

idblkint

The number of the last matrix inequality added. By definition, it is the number of matrix inequalities already defined plus $\text{nblk}$.

Raises

NagValueError

(errno $1$)

$handle$ has not been initialized.

(errno $1$)

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

(errno $1$)

$handle$ has not been initialized properly or is corrupted.

(errno $2$)

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

(errno $4$)

On entry, $\text{nvar}=⟨value⟩$, expected $value=⟨value⟩$.

Constraint: $\text{nvar}$ must match the current number of variables of the model in the $handle$.

(errno $4$)

On entry, $idblk=⟨value⟩$.

Constraint: $idblk=0$.

(errno $6$)

On entry, $dima=⟨value⟩$.

Constraint: $dima>0$.

(errno $6$)

On entry, $\text{nnzasum}=⟨value⟩$ and $\text{sum}\left(nnza\right)=⟨value⟩$.

Constraint: $\text{nnzasum}\ge \text{sum}\left(nnza\right)$.

(errno $6$)

On entry, $i=⟨value⟩$ and $nnza[i-1]=⟨value⟩$.

Constraint: $nnza[i-1]\ge 0$.

(errno $6$)

On entry, $\text{sum}\left(nnza\right)=⟨value⟩$.

Constraint: $\text{sum}\left(nnza\right)\ge 1$.

(errno $7$)

On entry, $\text{nblk}=⟨value⟩$.

Constraint: $\text{nblk}>0$.

(errno $7$)

On entry, $i=⟨value⟩$ and $blksizea[i-1]=⟨value⟩$.

Constraint: $blksizea[i-1]\ge 1$.

(errno $7$)

On entry, $dima=⟨value⟩$ and $\text{sum}\left(blksizea\right)=⟨value⟩$.

Constraint: $\text{sum}\left(blksizea\right)=dima$.

(errno $8$)

An error occurred in matrix $A_i$, $i=⟨value⟩$.

On entry, $j=⟨value⟩$, $irowa[j-1]=⟨value⟩$ and $dima=⟨value⟩$.

Constraint: $1\le irowa[j-1]\le dima$.

(errno $8$)

An error occurred in matrix $A_i$, $i=⟨value⟩$.

On entry, $j=⟨value⟩$, $icola[j-1]=⟨value⟩$ and $dima=⟨value⟩$.

Constraint: $1\le icola[j-1]\le dima$.

(errno $8$)

An error occurred in matrix $A_i$, $i=⟨value⟩$.

On entry, $j=⟨value⟩$, $irowa[j-1]=⟨value⟩$ and $icola[j-1]=⟨value⟩$.

Constraint: $irowa[\text{j}-1]\le icola[\text{j}-1]$ (elements within the upper triangle).

(errno $8$)

An error occurred in matrix $A_i$, $i=⟨value⟩$.

On entry, more than one element of $A_i$ has row index $⟨value⟩$ and column index $⟨value⟩$.

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

(errno $8$)

An error occurred in matrix $A_i$, $i=⟨value⟩$.

On entry, $j=⟨value⟩$, $irowa[j-1]=⟨value⟩$ and $icola[j-1]=⟨value⟩$. Maximum column index in this row given by the block structure defined by $blksizea$ is $⟨value⟩$.

Constraint: all elements of $A_i$ must respect the block structure given by $blksizea$.

Notes

After the initialization function handle_init() has been called, handle_set_linmatineq may be used to add one or more linear matrix inequalities

$$\sum _1^n{x}_i{A}_i-A_0⪰0$$

to the problem definition. Here $A_i$ are $d\times d$ symmetric matrices. The expression $S⪰0$ 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.

Typically, this will be used in linear semidefinite programming problems (SDP)

$$\begin{array}{c}\begin{array}{ccc}{minimize}_{x\in R^n}& c^{T}x& \text{(a)}\\ \text{subject to}& {\sum }_1^n{x}_i{A}_i^k-A_0^k⪰0\text{,}k=1,\dots ,m_A& \text{(b)}\\ & l_B\le Bx\le u_B& \text{(c)}\\ & l_x\le x\le u_x& \text{(d)}\end{array}\end{array}$$

or to define the linear part of bilinear matrix inequalities [equation](b) in (BMI-SDP)

$$\begin{array}{c}\begin{array}{ccc}{minimize}_{x\in R^n}& \frac{1}{2}{x}^{T}Hx+c^{T}x& \text{(a)}\\ \text{subject to}& {\sum }_1^n{x}_i{x}_j{Q}_{ij}^k+{\sum }_1^n{x}_i{A}_i^k-A_0^k⪰0\text{,}k=1,\dots ,m_A& \text{(b)}\\ & l_B\le Bx\le u_B& \text{(c)}\\ & l_x\le x\le u_x& \text{(d)}\end{array}\end{array}$$

handle_set_linmatineq can be called repeatedly to accumulate more matrix inequalities. See the E04 Introduction for more details about the NAG optimization modelling suite.

Input data organization

All the matrices $A_{\text{i}}$, for $\text{i}=0,1,\dots ,n$, 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. These triplets of all (upper triangle) nonzeros from all $A_i$ matrices are passed to the function in three arrays: $irowa$ for row indices, $icola$ for column indices and $a$ for the values. No particular order of nonzeros within one matrix is enforced but all nonzeros from $A_0$ must be stored first, followed by all nonzero from $A_1$, followed by $A_2$, etc.

The number of stored nonzeros from each $A_i$ matrix is given in $nnza\left[i\right]$, thus this array indicates which section of arrays $irowa$, $icola$ and $a$ belongs to which $A_i$ matrix. See Table [label omitted] and the example in Further Comments. See also sdp_read_sdpa() which uses the same data organization.

$irowa$	upper triangle	upper triangle		upper triangle
$icola$	nonzeros	nonzeros	$\cdots$	nonzeros
$a$	$\underset{}{\text{from}{A}_0}$	$\underset{}{\text{from}{A}_1}$		$\underset{}{\text{from}{A}_n}$
	$nnza\left[0\right]$	$nnza\left[1\right]$		$nnza\left[n\right]$

There are two possibilities for defining more matrix inequality constraints

$$\sum _1^n{x}_i{A}_i^k-A_0^k⪰0\text{,}k=1,2,\dots ,m_A$$

to the problem. The first is to call handle_set_linmatineq $m_A$ times and define a single matrix inequality at a time. This might be more straightforward and, therefore, it is recommended. Alternatively, it is possible to merge all $m_A$ constraints into one inequality and pass them in a single call to handle_set_linmatineq. It is easy to see that (4) can be equivalently expressed as one bigger matrix inequality with the following block diagonal structure

$$\begin{array}{c}\sum _1^n{x}_i\left(\begin{array}{cccc}{A}_i^1& & & \\ & A_i^2& & \\ & & \ddots & \\ & & & A_i^{m_A}\end{array}\right)-\left(\begin{array}{cccc}{A}_0^1& & & \\ & A_0^2& & \\ & & \ddots & \\ & & & A_0^{m_A}\end{array}\right)⪰0\text{.}\end{array}$$

If $d_k$ denotes the dimension of inequality $k$, the new merged inequality has dimension $d={\sum }_1^{m_A}{d}_k$ and each of the $A_i$ matrices is formed by $A_i^1,A_i^2,\dots ,A_i^{m_A}$ stored as $m_A$ diagonal blocks. In such a case, $\text{nblk}$ is set to $m_A$ and $blksizea[k-1]$ to $d_k$, the size of the $k$th diagonal blocks. This might be useful in connection with sdp_read_sdpa().

On the other hand, if there is no block structure and just one matrix inequality is provided, $\text{nblk}$ should be set to $1$ and $blksizea$ is not referenced.

Definition of Bilinear Matrix Inequalities (BMI)

handle_set_linmatineq is designed to be used together with handle_set_quadmatineq() to define bilinear matrix inequalities [equation](b). handle_set_linmatineq sets the linear part of the constraint and handle_set_quadmatineq() expands it by higher order terms. To distinquish which linear matrix inequality (or more precisely, which block) is to be expanded, handle_set_quadmatineq() needs the number of the block, $idblk$. The blocks are numbered as they are added, starting from $1$.

Whenever a matrix inequality (or a set of them expressed as diagonal blocks) is stored, the function returns $idblk$ of the last inequality added. $idblk$ is just the order of the inequality amongst all matrix inequalities accumulated through the calls. The first inequality has $idblk=1$, the second one $idblk=2$, etc. Therefore, if you call handle_set_linmatineq for the very first time with $\text{nblk}=42$, it adds $42$ inequalities with $idblk$ from $1$ to $42$ and the function returns $idblk=42$ (the number of the last one). A subsequent call with $\text{nblk}=1$ would add only one inequality, this time with $idblk=43$ which would be returned.

See also

naginterfaces.library.examples.opt.handle_solve_pennon_bmi_ex.main()

naginterfaces.library.examples.opt.handle_solve_pennon_lmi_ex.main()