## ▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

## 1Purpose

e04rpf 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.

## 2Specification

Fortran Interface
 Subroutine e04rpf ( nq, qi, qj, dimq, nnzq, q,
 Integer, Intent (In) :: nq, qi(nq), qj(nq), dimq, nnzq(nq), nnzqsum, irowq(nnzqsum), icolq(nnzqsum) Integer, Intent (Inout) :: idblk, ifail Real (Kind=nag_wp), Intent (In) :: q(nnzqsum) Type (c_ptr), Intent (In) :: handle
#include <nag.h>
 void e04rpf_ (void **handle, const Integer *nq, const Integer qi[], const Integer qj[], const Integer *dimq, const Integer nnzq[], const Integer *nnzqsum, const Integer irowq[], const Integer icolq[], const double q[], Integer *idblk, Integer *ifail)
The routine may be called by the names e04rpf or nagf_opt_handle_set_quadmatineq.

## 3Description

After the initialization routine e04raf has been called, e04rpf 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:
 $∑ i,j=1 n xi xj Q ij ⪰0$ (1)
or to extend an existing linear matrix inequality constraint by bilinear terms:
 $∑ i,j=1 n xi xj Q ij k .$ (2)
Here ${Q}_{ij}^{k}$ are $d×d$ (sparse) symmetric matrices and $k$, if present, is the number of the existing constraint. This routine will typically be used on semidefinite programming problems with bilinear matrix constraints (BMI-SDP)
 $minimize x∈ℝn 12 xTHx + cTx (a) subject to ∑ i,j=1 n xi xj Qijk + ∑ i=1 n xi Aik - A0k ⪰ 0 , k=1,…,mA , (b) lB≤Bx≤uB, (c) lx≤x≤ux . (d)$ (3)
The routine 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 idblk is used to distinguish whether a new matrix constraint should be added (${\mathbf{idblk}}=0$) or if an existing linear matrix inequality should be extended (${\mathbf{idblk}}>0$). In the latter case, idblk should be set to $k$, the number of the existing inequality. See e04rnf for details about formulation of linear matrix constraints and their numbering and a further description of idblk. See Section 3.1 in the E04 Chapter Introduction for more details about the NAG optimization modelling suite. In the further text, the index $k$ will be omitted.

### 3.1Input data organization

It is expected that only some of the matrices ${Q}_{ij}$ will be nonzero, therefore, only their index pairs $i,j$ are listed in arrays qi and qj. Note that a pair $i,j$ should not repeat, i.e., a matrix ${Q}_{ij}$ should not be defined more than once. No particular ordering of pairs $i,j$ is expected but other input arrays irowq, icolq, q and nnzq need to respect the chosen order.
Note:  the dimension of ${Q}_{ij}$ must respect the size of the linear matrix inequality if they are supposed to expand it (case ${\mathbf{idblk}}>0$).
Matrices ${Q}_{ij}$ are symmetric and thus only their upper triangles are passed to the routine. They are stored in sparse coordinate storage format (see Section 2.1.1 in the F11 Chapter 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}_{ij}$ matrices are passed to the routine in three arrays: irowq for row indices, icolq 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}_{ij}$ matrix need to be stored next to each other. The first ${\mathbf{nnzq}}\left(1\right)$ nonzeros belong to ${Q}_{{i}_{1}{j}_{1}}$ where ${i}_{1}={\mathbf{qi}}\left(1\right)$, ${j}_{1}={\mathbf{qj}}\left(1\right)$, the following ${\mathbf{nnzq}}\left(2\right)$ nonzeros to the next one given by qi, qj and so on. The array nnzq thus splits arrays irowq, icolq and q into sections so that each section defines one ${Q}_{ij}$ matrix. See Table 1 below. Routines e04rdf and e04rnf use the same data organization so further examples can be found there.
 irowq upper triangle upper triangle upper triangle icolq nonzeros nonzeros $\cdots$ nonzeros q $\underbrace{\text{from ​}{Q}_{{i}_{1}{j}_{1}}}$ $\underbrace{\text{from ​}{Q}_{{i}_{2}{j}_{2}}}$ $\underbrace{\text{from ​}{Q}_{{i}_{{\mathbf{nq}}}{j}_{{\mathbf{nq}}}}}$ ${\mathbf{nnzq}}\left(1\right)$ ${\mathbf{nnzq}}\left(2\right)$ ${\mathbf{nnzq}}\left({\mathbf{nq}}\right)$ ${i}_{1}={\mathbf{qi}}\left(1\right)$ ${i}_{2}={\mathbf{qi}}\left(2\right)$ ${i}_{{\mathbf{nq}}}={\mathbf{qi}}\left({\mathbf{nq}}\right)$ ${j}_{1}={\mathbf{qj}}\left(1\right)$ ${j}_{2}={\mathbf{qj}}\left(2\right)$ ${j}_{{\mathbf{nq}}}={\mathbf{qj}}\left({\mathbf{nq}}\right)$
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

## 5Arguments

1: $\mathbf{handle}$Type (c_ptr) Input
On entry: the handle to the problem. It needs to be initialized (e.g., by e04raf) and must not be changed between calls to the NAG optimization modelling suite.
2: $\mathbf{nq}$Integer Input
On entry: the number of index pairs $i,j$ of the nonzero matrices ${Q}_{ij}$.
Constraint: ${\mathbf{nq}}>0$.
3: $\mathbf{qi}\left({\mathbf{nq}}\right)$Integer array Input
4: $\mathbf{qj}\left({\mathbf{nq}}\right)$Integer array Input
On entry: the index pairs $i,j$ of the nonzero matrices ${Q}_{ij}$ in any order.
Constraint: $1\le i,j\le n$ where $n$ is the number of decision variables in the problem set during the initialization of the handle by e04raf. The pairs do not repeat.
5: $\mathbf{dimq}$Integer Input
On entry: $d$, the dimension of matrices ${Q}_{ij}$.
Constraints:
• ${\mathbf{dimq}}>0$;
• if ${\mathbf{idblk}}>0$, dimq needs to be identical to the dimension of matrices of the constraint $k$.
6: $\mathbf{nnzq}\left({\mathbf{nq}}\right)$Integer array Input
On entry: the numbers of nonzero elements in the upper triangles of ${Q}_{ij}$ matrices.
Constraint: ${\mathbf{nnzq}}\left(i\right)>0$.
7: $\mathbf{nnzqsum}$Integer Input
On entry: the dimension of the arrays irowq, icolq and q, at least the total number of all nonzeros in all ${Q}_{ij}$ matrices.
Constraints:
• ${\mathbf{nnzqsum}}>0$;
• ${\mathbf{nnzqsum}}\ge \sum _{\mathit{k}=1}^{{\mathbf{nq}}}{\mathbf{nnzq}}\left(\mathit{k}\right)$.
8: $\mathbf{irowq}\left({\mathbf{nnzqsum}}\right)$Integer array Input
9: $\mathbf{icolq}\left({\mathbf{nnzqsum}}\right)$Integer array Input
10: $\mathbf{q}\left({\mathbf{nnzqsum}}\right)$Real (Kind=nag_wp) array Input
On entry: the nonzero elements of the upper triangles of matrices ${Q}_{ij}$ stored in coordinate storage format. The first ${\mathbf{nnzq}}\left(1\right)$ elements belong to the first ${Q}_{{i}_{1}{j}_{1}}$, the following ${\mathbf{nnzq}}\left(2\right)$ to ${Q}_{{i}_{2}{j}_{2}}$, etc.
Constraint: $1\le {\mathbf{irowq}}\left(i\right)\le {\mathbf{dimq}}$, ${\mathbf{irowq}}\left(i\right)\le {\mathbf{icolq}}\left(i\right)\le {\mathbf{dimq}}$.
11: $\mathbf{idblk}$Integer Input/Output
On entry: if ${\mathbf{idblk}}=0$, a new matrix constraint is created; otherwise, ${\mathbf{idblk}}=k>0$, the number of the existing linear matrix constraint to be expanded with the bilinear terms.
Constraint: ${\mathbf{idblk}}\ge 0$.
On exit: if ${\mathbf{idblk}}=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, ${\mathbf{idblk}}>0$ stays unchanged.
12: $\mathbf{ifail}$Integer Input/Output
On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $-1$ is recommended. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit: ${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).

## 6Error Indicators and Warnings

If on entry ${\mathbf{ifail}}=0$ or $-1$, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
${\mathbf{ifail}}=1$
The supplied handle does not define a valid handle to the data structure for the NAG optimization modelling suite. It has not been properly initialized or it has been corrupted.
${\mathbf{ifail}}=2$
The problem cannot be modified right now, the solver is running.
${\mathbf{ifail}}=3$
On entry, ${\mathbf{idblk}}=⟨\mathit{\text{value}}⟩$.
Bilinear terms of the matrix inequality block with the given idblk have already been defined.
${\mathbf{ifail}}=4$
On entry, ${\mathbf{idblk}}=⟨\mathit{\text{value}}⟩$.
The given idblk does not match with any existing matrix inequality block.
The maximum idblk is currently $⟨\mathit{\text{value}}⟩$.
On entry, ${\mathbf{idblk}}=⟨\mathit{\text{value}}⟩$.
The given idblk refers to a nonexistent matrix inequality block.
No matrix inequalities have been added yet.
${\mathbf{ifail}}=5$
On entry, ${\mathbf{dimq}}=⟨\mathit{\text{value}}⟩$, ${\mathbf{idblk}}=⟨\mathit{\text{value}}⟩$.
The correct dimension of the given idblk is $⟨\mathit{\text{value}}⟩$.
Constraint: dimq must match the dimension of the block supplied earlier.
${\mathbf{ifail}}=6$
On entry, ${\mathbf{dimq}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{dimq}}>0$.
On entry, $i=⟨\mathit{\text{value}}⟩$ and ${\mathbf{nnzq}}\left(i\right)=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{nnzq}}\left(i\right)>0$.
On entry, ${\mathbf{idblk}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{idblk}}\ge 0$.
On entry, ${\mathbf{nnzqsum}}=⟨\mathit{\text{value}}⟩$ and $\mathrm{sum}\left({\mathbf{nnzq}}\right)=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{nnzqsum}}\ge \mathrm{sum}\left({\mathbf{nnzq}}\right)$.
On entry, ${\mathbf{nq}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{nq}}>0$.
${\mathbf{ifail}}=8$
On entry, an error occurred in matrix ${Q}_{ij}$ of index $k=⟨\mathit{\text{value}}⟩$, ${\mathbf{qi}}\left(k\right)=⟨\mathit{\text{value}}⟩$, ${\mathbf{qj}}\left(k\right)=⟨\mathit{\text{value}}⟩$.
For $j=⟨\mathit{\text{value}}⟩$, ${\mathbf{icolq}}\left(j\right)=⟨\mathit{\text{value}}⟩$ and ${\mathbf{dimq}}=⟨\mathit{\text{value}}⟩$.
Constraint: $1\le {\mathbf{icolq}}\left(j\right)\le {\mathbf{dimq}}$.
On entry, an error occurred in matrix ${Q}_{ij}$ of index $k=⟨\mathit{\text{value}}⟩$, ${\mathbf{qi}}\left(k\right)=⟨\mathit{\text{value}}⟩$, ${\mathbf{qj}}\left(k\right)=⟨\mathit{\text{value}}⟩$.
For $j=⟨\mathit{\text{value}}⟩$, ${\mathbf{irowq}}\left(j\right)=⟨\mathit{\text{value}}⟩$ and ${\mathbf{dimq}}=⟨\mathit{\text{value}}⟩$.
Constraint: $1\le {\mathbf{irowq}}\left(j\right)\le {\mathbf{dimq}}$.
On entry, an error occurred in matrix ${Q}_{ij}$ of index $k=⟨\mathit{\text{value}}⟩$, ${\mathbf{qi}}\left(k\right)=⟨\mathit{\text{value}}⟩$, ${\mathbf{qj}}\left(k\right)=⟨\mathit{\text{value}}⟩$.
For $j=⟨\mathit{\text{value}}⟩$, ${\mathbf{irowq}}\left(j\right)=⟨\mathit{\text{value}}⟩$ and ${\mathbf{icolq}}\left(j\right)=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{irowq}}\left(\mathit{j}\right)\le {\mathbf{icolq}}\left(\mathit{j}\right)$ (elements within the upper triangle).
On entry, an error occurred in matrix ${Q}_{ij}$ of index $k=⟨\mathit{\text{value}}⟩$, ${\mathbf{qi}}\left(k\right)=⟨\mathit{\text{value}}⟩$, ${\mathbf{qj}}\left(k\right)=⟨\mathit{\text{value}}⟩$.
More than one element of ${Q}_{ij}$ has row index $⟨\mathit{\text{value}}⟩$ and column index $⟨\mathit{\text{value}}⟩$.
Constraint: each element of ${Q}_{ij}$ must have a unique row and column index.
${\mathbf{ifail}}=9$
On entry, index pair with ${\mathbf{qi}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{qj}}=⟨\mathit{\text{value}}⟩$ repeats.
Constraint: each index pair qi, qj must be unique.
On entry, $k=⟨\mathit{\text{value}}⟩$, ${\mathbf{qi}}\left(k\right)=⟨\mathit{\text{value}}⟩$ and $n=⟨\mathit{\text{value}}⟩$.
Constraint: $1\le {\mathbf{qi}}\left(k\right)\le n$.
On entry, $k=⟨\mathit{\text{value}}⟩$, ${\mathbf{qj}}\left(k\right)=⟨\mathit{\text{value}}⟩$ and $n=⟨\mathit{\text{value}}⟩$.
Constraint: $1\le {\mathbf{qj}}\left(k\right)\le n$.
${\mathbf{ifail}}=-99$
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

Not applicable.

## 8Parallelism and Performance

e04rpf is not threaded in any implementation.

None.

## 10Example

This example demonstrates how semidefinite programming can be used in control theory. See also e04raf for links to further examples in the suite.
The problem, from static output feedback (SOF) control Syrmos et al. (1997), solved here is the linear time-invariant (LTI) ‘test’ system
 $x.=Ax+Bu y=Cx$ (4)
subject to static output feedback
 $u=Ky .$ (5)
Here $A\in {ℝ}^{n×n}$, $B\in {ℝ}^{n×m}$ and $C\in {ℝ}^{p×n}$ are given matrices, $x\in {ℝ}^{n}$ is the vector of state variables, $u\in {ℝ}^{m}$ is the vector of control inputs, $y\in {ℝ}^{p}$ is the vector of system outputs, and $K\in {ℝ}^{m×p}$ is the unknown feedback gain matrix.
The problem is to find $K$ such that (4) is time-stable when subject to (5), i.e., all eigenvalues of the closed-loop system matrix $A+BKC$ belong to the left half-plane. From the Lyapunov stability theory, this holds if and only if there exists a symmetric positive definite matrix $P$ such that
 $(A+BKC)T P+ P(A+BKC) ≺0 .$
Hence, by introducing the new variable, the Lyapunov matrix $P$, we can formulate the SOF problem as a feasibility BMI-SDP problem in variables $K$ and $P$. As we cannot formulate the problem with sharp matrix inequalities, we can solve the following system instead (note that the objective function is added to bound matrix $P$):
 $minimize K,P trace(P) subject to (A+BKC)T P+P(A+BKC) ⪯ -I , P⪰I.$ (6)
For $n=p=2$, $m=1$,
 $A= ( −1 2 −3 −4 ) , B= ( −1 −1 ) , C=I$
and the unknown matrices expressed as
 $P = ( x1 x2 x2 x3 ) , K = ( x4 x5 ) ,$
the problem (6) can be rewritten in the form (3) as follows:
 $minimize x∈ℝ5 x1+x3 subject to ( 2x1 ⁢ x4 + 2 x2 ⁢ x4 x1 ⁢ x5 + x2 ⁢ x4 + x2 ⁢ x5 + x3 ⁢ x4 sym. 2x2 ⁢ x5 + 2x3 ⁢ x5 ) + ( 2x1 + 6x2 −2x1 + 5x2 + 3x3 sym. −4x2 + 8x3 ) - I ⪰ 0 , ( x1 x2 sym. x3 ) - I ⪰ 0 .$
This formulation has been stored in a generic BMI-SDP data file which is processed and solved by the example program.

### 10.1Program Text

Program Text (e04rpfe.f90)

### 10.2Program Data

Program Data (e04rpfe.d)

### 10.3Program Results

Program Results (e04rpfe.r)