# hsvd

Hankel singular values of dynamic system

## Syntax

`hsv` = hsvd(`sys`)

`hsv` = hsvd(`sys`,'AbsTol',`ATOL`,'RelTol',`RTOL`,'Offset',`ALPHA`)

`hsv` = hsvd(`sys`, `opts`)

hsvd(sys)

[hsv,baldata] = hsvd(sys)

## Description

`hsv` = hsvd(`sys`) computes
the Hankel singular values `hsv` of the dynamic
system `sys`. In state coordinates that equalize
the input-to-state and state-to-output energy transfers, the Hankel
singular values measure the contribution of each state to the input/output
behavior. Hankel singular values are to model order what singular
values are to matrix rank. In particular, small Hankel singular values
signal states that can be discarded to simplify the model (see `balred`).

For models with unstable poles, `hsvd` only
computes the Hankel singular values of the stable part and entries
of `hsv` corresponding to unstable modes are set
to `Inf`.

`hsv` = hsvd(`sys`,'AbsTol',`ATOL`,'RelTol',`RTOL`,'Offset',`ALPHA`) specifies
additional options for the stable/unstable decomposition. See the `stabsep` reference page for more information
about these options. The default values are `ATOL = 0`, `RTOL
= 1e-8`, and `ALPHA = 1e-8`.

`hsv` = hsvd(`sys`, `opts`) computes
the Hankel singular values using the options specified in the `hsvdOptions` object `opts`.

`hsvd(sys)` displays a Hankel singular values
plot.

`[hsv,baldata] = hsvd(sys)` returns additional
data to speed up model order reduction with `balred`.
For example

sys = rss(20); % 20-th order model
[hsv,baldata] = hsvd(sys);
rsys = balred(sys,8:10,'Balancing',baldata);
bode(sys,'b',rsys,'r--')

computes three approximations of `sys` of orders
8, 9, 10.

There is more than one `hsvd` available. Type

help lti/hsvd

for more information.

## Examples

**Compute Hankel Singular Values**

This example illustrates how to compute Hankel singular values.

First, create a system with a stable pole very near to 0, then
calculate the Hankel singular values.

sys = zpk([1 2],[-1 -2 -3 -10 -1e-7],1)
hsvd(sys)
Zero/pole/gain:
(s-1) (s-2)
-----------------------------------
(s+1) (s+2) (s+3) (s+10) (s+1e-007)

For a better view of the Hankel singular values, switch the
plot to log scale by selecting **Y Scale** > **Log** from the right-click menu.

Notice the dominant Hankel singular value with 1e5 magnitude,
due to the mode `s=-1e-7` near the imaginary axis.
Set the `offset=1e-6` to treat this mode as unstable

hsvd(sys,'Offset',1e-7)

The dominant Hankel singular value is now shown as unstable.

## More About

expand all

You can change the properties of your plot, for example the
units. For information on the ways to change properties of your plots,
see Ways to Customize Plots.

The `AbsTol`, `RelTol`, and `ALPHA` parameters
are only used for models with unstable or marginally stable dynamics.
Because Hankel singular values are only meaningful for stable dynamics, `hsvd` must
first split such models into the sum of their stable and unstable
parts:

G = G_s + G_ns

This decomposition can be tricky when the model has modes close
to the stability boundary (e.g., a pole at `s=-1e-10`),
or clusters of modes on the stability boundary (e.g., double or triple
integrators). While `hsvd` is able to overcome these
difficulties in most cases, it sometimes produces unexpected results
such as

Large Hankel singular values for the
stable part.

This happens when the stable part `G_s` contains
some poles very close to the stability boundary. To force such modes
into the unstable group, increase the `'Offset'` option
to slightly grow the unstable region.

Too many modes are labeled "unstable."
For example, you see 5 red bars in the HSV plot when your model had
only 2 unstable poles.

The stable/unstable decomposition algorithm has built-in accuracy
checks that reject decompositions causing a significant loss of accuracy
in the frequency response. Such loss of accuracy arises, e.g., when
trying to split a cluster of stable and unstable modes near `s=0`.
Because such clusters are numerically equivalent to a multiple pole
at `s=0`, it is actually desirable to treat the whole
cluster as unstable. In some cases, however, large relative errors
in low-gain frequency bands can trip the accuracy checks and lead
to a rejection of valid decompositions. Additional modes are then
absorbed into the unstable part `G_ns`, unduly increasing
its order.

Such issues can be easily corrected by adjusting the `AbsTol` and `RelTol` tolerances.
By setting `AbsTol` to a fraction of smallest gain
of interest in your model, you tell the algorithm to ignore errors
below a certain gain threshold. By increasing `RelTol`,
you tell the algorithm to sacrifice some relative model accuracy in
exchange for keeping more modes in the stable part `G_s`.

## See Also

`balreal` | `balred` | `hsvdOptions`