# lmivar

Specify matrix variables in LMI problem

## Syntax

``X = lmivar(type,structure)``
``[X,n,sX] = lmivar(type,structure)``

## Description

example

````X = lmivar(type,structure)` defines a new matrix variable in the LMI system currently described. The array `structure` specifies the structure of the variable. The optional output `X` is an identifier that can be used for subsequent reference to the variable. Before using `lmivar` to create any variables, initialize the LMI system using `setlmis`.```

example

````[X,n,sX] = lmivar(type,structure)` returns the total number of decision variables in the problem thus far, and a matrix indicating the dependence of `X` on the decision variables.```

## Examples

collapse all

Consider an LMI system with three matrix variables ${X}_{1}$, ${X}_{2}$, and ${X}_{3}$ such that

• ${X}_{1}$ is a 3-by-3 symmetric matrix (unstructured),

• ${X}_{2}$ is a 2-by-4 rectangular matrix (unstructured),

• ${X}_{3}$ =

`$\left(\begin{array}{ccc}\Delta & 0& 0\\ 0& {\delta }_{1}& 0\\ 0& 0& {\delta }_{2}{I}_{2}\end{array}\right),$`

where Δ is an arbitrary 5-by-5 symmetric matrix, ${\delta }_{1}$ and ${\delta }_{2}$ are scalars, and ${I}_{2}$ denotes the identity matrix of size 2.

Define these three variables using `lmivar`.

```setlmis([]) X1 = lmivar(1,[3 1]); % Type 1 X2 = lmivar(2,[2 4]); % Type 2 of dimension 2-by-4 X3 = lmivar(1,[5 1;1 0;2 0]); % Type 1```

The last command defines ${X}_{3}$ as a variable of Type 1 with one full block of size 5 and two scalar blocks of sizes 1 and 2, respectively.

Combined with the extra outputs `n` and `sX` of `lmivar`, Type 3 allows you to specify fairly complex matrix variable structures. For instance, consider a matrix variable X with structure given by:

`$X=\left(\begin{array}{cc}{X}_{1}& 0\\ 0& {X}_{2}\end{array}\right)$`

where ${X}_{1}$ and ${X}_{2}$ are 2-by-3 and 3-by-2 rectangular matrices, respectively. Specify this structure as follows.

Define the rectangular variables ${X}_{1}$ and ${X}_{2}$.

```setlmis([]) [X1,n,sX1] = lmivar(2,[2 3]); [X2,n,sX2] = lmivar(2,[3 2]);```

The outputs `sX1` and `sX2` give the decision variable content of ${X}_{1}$ and ${X}_{2}$.

`sX1`
```sX1 = 2×3 1 2 3 4 5 6 ```
`sX2`
```sX2 = 3×2 7 8 9 10 11 12 ```

For instance, `sX2(1,1) = 7` means that the (1,1) entry of ${X}_{2}$ is the seventh decision variable.

Next, use Type 3 to specify the matrix variable X, and define its structure in terms of the structures of ${X}_{1}$ and ${X}_{2}$.

`[X,n,sX] = lmivar(3,[sX1,zeros(2);zeros(3),sX2]);`

Confirm that the resulting `X` has the desired structure.

`sX`
```sX = 5×5 1 2 3 0 0 4 5 6 0 0 0 0 0 7 8 0 0 0 9 10 0 0 0 11 12 ```

## Input Arguments

collapse all

Matrix variable type, specified as 1, 2, or 3.

• 1 — Symmetric matrix with a block diagonal structure. Use `structure` to specify the size and structure of the diagonal blocks.

• 2 — Full rectangular matrix. Use `structure` to specify the dimensions of the matrix.

• 3 — Other structure. Use `structure` to provide further information about the structure of the variable.

Matrix variable structure, specified as an array. How you specify the structure depends on the variable type.

`type``structure`
`type = 1`

For a matrix variable with `N` diagonal blocks, specify `structure` as an `N`-by-2 matrix, where the ith row describes the ith diagonal block.

• `structure(i,1)` specifies the block size.

• `structure(i,2)` specifies the block type.

• `structure(i,2) = 0` for a scalar block (a scalar multiple of the identity matrix).

• `structure(i,2) = 1` for a full block (arbitrary symmetric matrix).

• `structure(i,2) = -1` for a zero block.

For instance, if the first block of `X` is a single scalar value, and the second block of `X` is a 3-by-3 full block, then specify `structure` as ```[1 0; 3 1]```.

`type = 2`

For a full rectangular m-by-n matrix variable, specify `structure = [m,n]`.

`type = 3`

You can use Type 3 to specify sophisticated matrix variable structures. To specify a variable `X` of Type 3, first identify how many free independent entries are involved in `X`. These constitute the set of decision variables associated with `X`. If the problem already involves n decision variables, label the new free variables as xn+1, . . ., xn+p. You then specify the structure of `X` in terms of those free variables. To do so, specify `structure` as a matrix of the same dimensions as `X`, where `structure(i,j)` is:

• `0`, if `X(i,j) = 0`.

• `k`, if `X(i,j) ` is the kth decision variable.

• `-k`, if `X(i,j) ` is `(-1)` times the kth decision variable.

To help specify matrix variables of Type 3, use the `n` and `sX` output variables of `lmivar` to check the number of decision variables and entry-wise dependence of `X` on the decision variables, respectively.

For examples specifying Type 3 LMI variables, see Type 3 Matrix Variables and Advanced LMI Techniques.

## Output Arguments

collapse all

Identifier for matrix variable, returned as a positive integer. The value of this identifier is `k`, where `k-1` is the number of matrix variables previously declared in this LMI problem. The value of this identifier is not affected by subsequent modifications of the LMI system.

Number of decision variables in the system so far, returned as a positive integer. This value includes the decision variables in `X` and those in previously defined LMI variables.

Dependence of `X` on decision variables, returned as a matrix. Each entry in `sX` is either `0`, the index of a decision variable, or minus the index of a decision variable. For instance, suppose that `X` depends on two decision variables, x1 and x1, as follows:

`$X=\left(\begin{array}{cc}0& -{x}_{1}\\ {x}_{2}& 0\end{array}\right)$`

When you create the variable `X`, the `lmivar` command returns the following `sX`.

```sX = 2×2 0 -1 2 0 ```

## Version History

Introduced before R2006a