Performance Specifications#

A performance specification spec encodes a desired property of the algorithm as a constraint on the performance channel $(w_p, z_p)$ of the generalized plant. In Analysis, spec represents the property to be verified. In Synthesis, spec is the property that the returned algorithm should meet.

The usage-facing walkthrough is on the Specifications page. The channel each specification acts on is created by the plant’s perf_output_* and add_oracle_* methods (see Generalized Plant).

Linear Convergence#

class spec.spec_stability#

Bases: spec.spec_interface

SPEC_STABILITY Linear convergence / exponential stability specification.

Enforces exponential (linear) convergence of the algorithmic interconnection at rate $\rho \in (0, 1)$: for every initial condition there is a fixed point $x^*(x_0)$ with

\[\begin{split}\mav{c}{x_k - x^*(x_0) \\ w_k - w^*(x_0) \\ z_k - z^*(x_0)}_2 \leq \gamma_0 \, \rho^{k} \norm{x_0 - x^*(x_0)}_2, \qquad \forall k \in \N .\end{split}\]

The rate is stored in the inherited rho property and enters the LMI through the $\rho$-transformation of the plant. This specification carries no performance channel of its own (iwp and izp are empty); when $\rho < 1$ it $\rho$-weights every other specification on the same problem.

Constructor Summary

spec_stability(rho)#

SPEC_STABILITY Construct a linear-convergence specification.

Parameters:: rho (double) – Target convergence rate $\rho \in (0, 1]$ (default: 1, i.e. plain stability).
Returns:: A new stability specification.
Return type:: spec_stability

Quadratic Performance#

class spec.spec_quad#

Bases: spec.spec_interface

SPEC_QUAD General quadratic performance specification.

[zp]’ [Q S] [zp] < 0 [wp] [S’ R] [wp]

Constructor Summary

spec_quad(M, iwp, izp)#

SPEC_QUAD Construct a quadratic performance specification.

Parameters:

M (double) – Quadratic supply-rate matrix on $[z_p; w_p]$.
iwp (double (vector)) – Performance-input indices in the network.
izp (double (vector)) – Performance-output indices in the network.

Returns:

A new quadratic specification.

Return type:

spec_quad

Property Summary

M#: Quadratic performance matrix on $[z_p; w_p]$.

Method Summary

supply()#

SUPPLY Quadratic supply-rate matrix of the specification.

Returns the stored matrix M unchanged.

Returns:: Quadratic running-cost matrix $M$.
Return type:: double

$\ell_2$ Stability (ISS)#

class spec.spec_l2#

Bases: spec.spec_interface

SPEC_L2 $\ell_2$ stability specification.

Certifies that the performance input has bounded influence on the state, i.e. the algorithm is $\ell_2$-stable. This is not an $\ell_2$-gain: there is no performance output (izp = []), only a bounded quadratic penalty on the performance input $w_p$.

When the discount rate $\rho \in (0, 1)$, this specification implies Input-to-State Stability (ISS): there exist gains $\gamma_x, \gamma_w \geq 0$ with

\[\norm{x_k - x^*(x_0)}_2^2 \leq \gamma_x \, \rho^k \norm{x_0 - x^*(x_0)} + \gamma_w \max_{t \in 0, \ldots, k} \norm{w_{p,t}}_2^2, \qquad \forall k \in \N .\]

Constructor Summary

spec_l2(iwp, MU)#

SPEC_L2 Construct an $\ell_2$ stability specification.

Parameters:

iwp (double (vector)) – Performance-input indices in the network.
MU (double) – Optional $\ell_2$ bound (default: 1e4).

Returns:

A new $\ell_2$ stability specification.

Return type:

spec_l2

Property Summary

gain#: $\ell_2$ bound (large default, effectively a slack).

Method Summary

create_vars(cons, name, config)#

CREATE_VARS Create the $\ell_2$ bound variable and constraints.

Parameters:

cons – Accumulated LMI constraints.
name (char) – Name suffix for the created variable.
config (opt_config) – Configuration options.

Returns:

[vars, cons] — struct with field mu_l2 and the updated constraint set.

Return type:

struct, cell

set_p(p)#

SET_P Set the bisection parameter (the $\ell_2$ bound).

Parameters:: p (double) – New value of the swept parameter, e.g. a convergence rate $\rho$ or an $\ell_2$-gain bound.
Returns:: The updated specification.
Return type:: spec_l2

supply(vars_spec)#

SUPPLY Quadratic supply-rate matrix of the specification.

Returns $-\texttt{gain} \cdot I$ on the performance input channel.

Parameters:: vars_spec (struct) – Specification variables.
Returns:: Quadratic running-cost matrix $M$.
Return type:: double

supply_quad(vars_spec)#

SUPPLY_QUAD Decomposed quadratic supply rate.

When this specification is the optimization target, the bound mu_l2 is minimized; otherwise the base-class decomposition is used.

Parameters:: vars_spec (struct) – Specification variables (expects mu_l2).
Returns:: [quad, objective] — the decomposed quadratic and the objective contribution.
Return type:: quad_param, double

$\ell_2$ Gain#

class spec.spec_e2e#

Bases: spec.spec_interface

SPEC_E2E Energy-to-energy ($\ell_2$) gain specification.

Bounds the induced $\ell_2$-gain from the performance input to the performance output:

\[\limsup_{T \to \infty} \frac{\sum_{k=0}^{T} \norm{z_{p,k}}_2}{\sum_{k=0}^{T} \norm{w_{p,k}}_2} \; < \; \gamma .\]

for any $w_p$ with finite energy. For a linear system this is the $H_\infty$ gain. It is the specification minimized when sweeping for the best achievable gain.

Constructor Summary

spec_e2e(GAIN, iwp, izp)#

SPEC_E2E Construct an energy-to-energy gain specification.

Parameters:

GAIN (double) – Gain bound $\gamma$.
iwp (double (vector)) – Performance-input indices in the network.
izp (double (vector)) – Performance-output indices in the network.

Returns:

A new energy-to-energy gain specification.

Return type:

spec_e2e

Property Summary

gain#: $\ell_2$ gain $\gamma$ (hard constraint).

Method Summary

create_vars(cons, name, config)#

CREATE_VARS Create the gain variable and its constraints.

Parameters:

cons – Accumulated LMI constraints.
name (char) – Name suffix for the created variable.
config (opt_config) – Configuration options.

Returns:

[vars, cons] — struct with field mu_l2 and the updated constraint set.

Return type:

struct, cell

set_p(p)#

SET_P Set the bisection parameter (the $\ell_2$ gain).

Parameters:: p (double) – New value of the gain bound.
Returns:: The updated specification.
Return type:: spec_e2e

supply(vars_spec)#

SUPPLY Quadratic supply-rate matrix of the specification.

Builds the block-diagonal supply rate $\operatorname{blkdiag}(\gamma^{-1} I,\, -\gamma I)$ on $[z_p; w_p]$.

Parameters:: vars_spec (struct) – Specification variables.
Returns:: Quadratic running-cost matrix $M$.
Return type:: double

supply_quad(vars_spec)#

SUPPLY_QUAD Decomposed quadratic supply rate.

When this specification is the optimization target, the gain variable mu_l2 is minimized; otherwise the base-class decomposition is used.

Parameters:: vars_spec (struct) – Specification variables (expects mu_l2).
Returns:: [quad, objective] — the decomposed quadratic and the objective contribution.
Return type:: quad_param, double

Passivity#

class spec.spec_passivity#

Bases: spec.spec_interface

SPEC_PASSIVITY Passivity specification with input/output indices.

Imposes a (possibly indexed) passivity supply rate on the performance channel: for all horizons $T$ with $x = 0$,

\[\sum_{k=0}^{T} z_{p,k}^\top w_{p,k} \; \geq \; \sum_{k=0}^{T} \big( \nu_w \norm{w_{p,k}}^2 + \nu_z \norm{z_{p,k}}^2 \big),\]

where $\nu_w = \texttt{ind_w}$ is the input passivity index and $\nu_z = \texttt{ind_z}$ is the output passivity index. The plain passivity supply rate is recovered with both indices set to zero.

Constructor Summary

spec_passivity(ind_w, ind_z, iwp, izp)#

SPEC_PASSIVITY Construct a passivity specification.

Parameters:

ind_w (double) – Input passivity index $\nu_w$.
ind_z (double) – Output passivity index $\nu_z$.
iwp (double (vector)) – Performance-input indices in the network.
izp (double (vector)) – Performance-output indices in the network.

Returns:

A new passivity specification.

Return type:

spec_passivity

Raises:

Error if iwp and izp have different lengths.

Property Summary

ind_w#: Input passivity index $\nu_w$.

ind_z#: Output passivity index $\nu_z$.

Method Summary

create_vars(cons, name, config)#

CREATE_VARS Create the passivity margin variable.

Parameters:

cons – Accumulated LMI constraints.
name (char) – Name suffix for the created variable.
config (opt_config) – Configuration options.

Returns:

[vars, cons] — struct with field ind_pass and the (unchanged) constraint set.

Return type:

struct, cell

set_p(p)#

SET_P Set the bisection parameter (the input passivity index).

Parameters:: p (double) – New value of the input passivity index $\nu_w$.
Returns:: The updated specification.
Return type:: spec_passivity

supply(vars_spec)#

SUPPLY Quadratic supply-rate matrix for the passivity indices.

Parameters:: vars_spec (struct) – Specification variables.
Returns:: Quadratic running-cost matrix $M$.
Return type:: double

supply_quad(vars_spec)#

SUPPLY_QUAD Decomposed quadratic supply rate.

When this specification is the optimization target, a passivity margin ind_pass is introduced and maximized; otherwise the base-class decomposition is used.

Parameters:: vars_spec (struct) – Specification variables (expects ind_pass).
Returns:: [quad, objective] — the decomposed quadratic and the objective contribution.
Return type:: quad_param, double

Stochastic Sensitivity#

class spec.spec_h2#

Bases: spec.spec_interface

SPEC_H2 Stochastic stability specification with input/output indices.

The performance input $w_p$ is an i.d.d. zero-mean stochastic process with bounded covariance $mathbb{E}[||w_{p,k}||_2^2] leq sigma^2$ Imposes a stochastic stability constraint

\[\limsup_{T \rightarrow \infty} \frac{1}{T} \sum_{k=0}^{T} \mathbb{E}[|| z_{p,k}||^2_2] \leq \gamma^2 \sigma^2\]

This is analogous to a primal H2 norm in the linear system setting.

Note:: The h2 implementation requires that the stochastic input and

the oracle output are conditionally independent at each time k (zero feedthrough in $D_{z w_p}$).

Constructor Summary

spec_h2(gain, cov, iwp, izp)#

SPEC_PASSIVITY Construct a passivity specification.

Parameters:

GAIN (double) – Gain bound $\gamma$.
cov (double or symmetric matrix of double) – Covariance of noise process
iwp (double (vector)) – Performance-input indices in the network.
izp (double (vector)) – Performance-output indices in the network.

Returns:

A new passivity specification.

Return type:

spec_passivity

Raises:

Error if iwp and izp have different lengths.

Property Summary

cov#: covariance bound (scalar or matrix)

gain#: stochastic gain

Method Summary

create_vars(cons, name, config)#

CREATE_VARS Create the passivity margin variable.

Parameters:

cons – Accumulated LMI constraints.
name (char) – Name suffix for the created variable.
config (opt_config) – Configuration options.

Returns:

[vars, cons] — struct with field ind_pass and the (unchanged) constraint set.

Return type:

struct, cell

get_cov()#: GET_COV get the covariance matrix

get_objective(vars)#: get the objective in the h2 problem

set_p(p)#

SET_P Set the bisection parameter (the input passivity index).

Parameters:: p (double) – New value of the input passivity index $\nu_w$.
Returns:: The updated specification.
Return type:: spec_passivity

supply(vars_spec)#

SUPPLY Quadratic supply-rate matrix for the passivity indices.

Parameters:: vars_spec (struct) – Specification variables.
Returns:: Quadratic running-cost matrix $M$.
Return type:: double

supply_quad(vars_spec)#

SUPPLY_QUAD Decomposed quadratic supply rate for h2 synthesis

Parameters:: vars_spec (struct) – Specification variables (expects ind_pass).
Returns:: [quad, objective] — the decomposed quadratic and the objective contribution.
Return type:: quad_param, double

Performance Specifications

Contents

Performance Specifications#

Linear Convergence#

Quadratic Performance#

\(\ell_2\) Stability (ISS)#

\(\ell_2\) Gain#

Passivity#

Stochastic Sensitivity#