# getSectorIndex

Compute conic-sector index of linear system

## Syntax

``RX = getSectorIndex(H,Q)``
``RX = getSectorIndex(H,Q,tol)``
``RX = getSectorIndex(H,Q,tol,fband)``
``````[RX,FX] = getSectorIndex(___)``````
``````[RX,FX,W1,W2,Z] = getSectorIndex(___)``````
``DX = getSectorIndex(H,Q,dQ)``
``DX = getSectorIndex(H,Q,dQ,tol)``

## Description

example

````RX = getSectorIndex(H,Q)` computes the relative index `RX` for the linear system `H` and the conic sector specified by `Q`. When `RX` < 1, all output trajectories y(t) = Hu(t) lie in the sector defined by:${\int }_{0}^{T}y{\left(t\right)}^{T}Q\text{\hspace{0.17em}}y\left(t\right)dt<0,$for all T ≥ 0. `getSectorIndex` can also check whether all I/O trajectories {u(t),y(t)} of a linear system G lie in the sector defined by:${\int }_{0}^{T}{\left(\begin{array}{c}y\left(t\right)\\ u\left(t\right)\end{array}\right)}^{T}Q\text{\hspace{0.17em}}\left(\begin{array}{c}y\left(t\right)\\ u\left(t\right)\end{array}\right)dt<0,$for all T ≥ 0. To do so, use `getSectorIndex` with ```H = [G;I]```, where `I = eyes(nu)`, and `nu` is the number of inputs of `G`.For more information about sector bounds and the relative index, see About Sector Bounds and Sector Indices.```
````RX = getSectorIndex(H,Q,tol)` computes the index with relative accuracy specified by `tol`.```
````RX = getSectorIndex(H,Q,tol,fband)` computes the passivity index by restricting the inequalities that define the index to a specified frequency interval. This syntax is available only when `Q` has as many negative eigenvalues as there are inputs in `H`. ```
``````[RX,FX] = getSectorIndex(___)``` also returns the frequency at which the index value `RX` is achieved. `FX` is set to `NaN` when the number of negative eigenvalues in `Q` differs from the number of inputs in `H`. You can use this syntax with any of the previous combinations of input arguments. ```
``````[RX,FX,W1,W2,Z] = getSectorIndex(___)``` also returns the decomposition of `Q` into its positive and negative parts, as well as the spectral factor `Z` when `Q` is dynamic. When `Q` is a matrix (constant sector bounds), `Z` = 1. You can use this syntax with any of the previous combinations of input arguments. ```
````DX = getSectorIndex(H,Q,dQ)` computes the index in the direction specified by the matrix `dQ`. If `DX` > 0, then the output trajectories of `H` fit in the conic sector specified by `Q`. For more information about the directional index, see About Sector Bounds and Sector Indices.The directional index is not available if `H` is a frequency-response data (`frd`) model.```
````DX = getSectorIndex(H,Q,dQ,tol)` computes the index with relative accuracy specified by `tol`.```

## Examples

collapse all

Test whether, on average, the I/O trajectories of $G\left(s\right)=\left(s+2\right)/\left(s+1\right)$ belong within the sector defined by:

`$S=\left\{\left(y,u\right):0.1{u}^{2}`

In U/Y space, this sector is the shaded region of the following diagram.

The `Q` matrix corresponding to this sector is given by:

`$Q=\left[\begin{array}{cc}1& -\left(a+b\right)/2\\ -\left(a+b\right)/2& ab\end{array}\right];\phantom{\rule{1em}{0ex}}a=0.1,\phantom{\rule{0.2777777777777778em}{0ex}}b=10.$`

A trajectory $y\left(t\right)=G\phantom{\rule{0.1em}{0ex}}u\left(t\right)$ lies within the sector S when for all T > 0,

`$0.1{\int }_{0}^{T}u{\left(t\right)}^{2}<\phantom{\rule{0.2777777777777778em}{0ex}}\phantom{\rule{0.2777777777777778em}{0ex}}{\int }_{0}^{T}u\left(t\right)y\left(t\right)dt<\phantom{\rule{0.2777777777777778em}{0ex}}\phantom{\rule{0.2777777777777778em}{0ex}}10{\int }_{0}^{T}u{\left(t\right)}^{2}dt.$`

To check whether trajectories of `G` satisfy the sector bound, represented by `Q`, compute the R-index for `H = [G;1]`.

```G = tf([1 2],[1 1]); a = 0.1; b = 10; Q = [1 -(a+b)/2 ; -(a+b)/2 a*b]; R = getSectorIndex([G;1],Q)```
```R = 0.4074 ```

This resulting `R` is less than 1, indicating that the trajectories fit within the sector. The value of `R` tells you how much tightly the trajectories fit in the sector. This value, `R` = 0.41, means that the trajectories would fit in a narrower sector with a base 1/0.41 = 2.4 times smaller.

## Input Arguments

collapse all

Model to analyze against sector bounds, specified as a dynamic system model such as a `tf`, `ss`, or `genss` model. `H` can be continuous or discrete. If `H` is a generalized model with tunable or uncertain blocks, `getSectorIndex` analyzes the current, nominal value of `H`.

To analyze whether all I/O trajectories {u(t),y(t)} of a linear system G lie in a particular sector, use ```H = [G;I]```.

If `H` is a model array, then `getSectorIndex` returns the passivity index as an array of the same size, where:

`index(k) = getSectorIndex(H(:,:,k),___)`

Here, `index` is either `RX`, or `DX`, depending on which input arguments you use.

Sector geometry, specified as:

• A matrix, for constant sector geometry. `Q` is a symmetric square matrix that is `ny` on a side, where `ny` is the number of outputs of `H`.

• An LTI model, for frequency-dependent sector geometry. `Q` satisfies Q(s)’ = Q(–s). In other words, Q(s) evaluates to a Hermitian matrix at each frequency.

The matrix `Q` must be indefinite to describe a well-defined conic sector. An indefinite matrix has both positive and negative eigenvalues.

Relative accuracy for the calculated sector index. By default, the tolerance is 1%, meaning that the returned index is within 1% of the actual index.

Frequency interval for calculating the sector index, specified as an array of the form `[fmin,fmax]`. When you provide `fband`, `getSectorIndex` restricts to the specified frequency interval the inequalities that define the index. Specify frequencies in units of `rad/TimeUnit`, where `TimeUnit` is the `TimeUnit` property of the dynamic system model `H`.

Direction in which to compute directional sector index, specified as a nonnegative definite matrix. The matrix `dQ` is a symmetric square matrix that is `ny` on a side, where `ny` is the number of outputs of `H`.

## Output Arguments

collapse all

Relative index of the system `H` for the sector specified by `Q`, returned as a scalar value, or an array if `H` is an array. If `RX` < 1, then the output trajectories of `H` fit inside the cone of `Q`.

The value of `RX` provides a measure of how tightly the output trajectories of `H` fit inside the cone. Let the following be an orthogonal decomposition of the symmetric matrix `Q` into its positive and negative parts.

`$Q={W}_{1}{W}_{1}^{T}-{W}_{2}{W}_{2}^{T},\text{ }{W}_{1}^{T}{W}_{2}=0.$`

(Such a decomposition is readily obtained from the Schur decomposition of `Q`.) Then, `RX` is the smallest R that satisfies:

`${\int }_{0}^{T}y{\left(t\right)}^{T}\left({W}_{1}{W}_{1}^{T}-{R}^{2}{W}_{2}{W}_{2}^{T}\right)\text{\hspace{0.17em}}y\left(t\right)dt<0,$`

for all T ≥ 0. Varying R is equivalent to adjusting the slant angle of the cone specified by Q until the cone fits tightly around the output trajectories of `H`. The cone base-to-height ratio is proportional to R.

Frequency at which the index `RX` is achieved, returned as a nonnegative scalar, or an array if `H` is an array. In general, the index varies with frequency (see `sectorplot`). The returned value is the largest value over all frequencies. `FX` is the frequency at which this value occurs, returned in units of `rad/TimeUnit`, where `TimeUnit` is the `TimeUnit` property of `H`.

Positive and negative factors of `Q`, returned as matrices. For a constant `Q`, `W1` and `W2` satisfy:

`$Q={W}_{1}{W}_{1}^{T}-{W}_{2}{W}_{2}^{T},\text{ }{W}_{1}^{T}{W}_{2}=0.$`

Bistable model in the factorization of `Q`, returned as:

• If `Q` is a constant matrix, `Z` = 1.

• If `Q` is frequency-dependent, then `Z` is a state-space (`ss`) model such that:

`$Q\left(j\omega \right)=Z{\left(j\omega \right)}^{H}\left({W}_{1}{W}_{1}^{T}-{W}_{2}{W}_{2}^{T}\right)Z\left(j\omega \right).$`

Directional sector index of the system `H` for the sector specified by `Q` in the direction `dQ`, returned as a scalar value, or an array if `H` is an array. The directional index is the largest τ which satisfies:

`${\int }_{0}^{T}y{\left(t\right)}^{T}\left(Q+\tau dQ\right)\text{\hspace{0.17em}}y\left(t\right)dt<0,$`

for all T ≥ 0.