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

Peak-to-Peak

class spec.spec_p2p

Bases: spec.spec_interface

SPEC_P2P Peak-to-peak gain specification.

Bounds the induced peak-to-peak norm (the \(*\)-norm of a linear system) from the performance input to the performance output: the peak (over time) of the output is bounded by \(\gamma\) times the peak of the input,

\(\sup_{k \geq 0} \norm{z_{p,k}}_2 \; \leq \; \gamma \, \sup_{k \geq 0} \norm{w_{p,k}}_2.\)

Constructor Summary

spec_p2p(GAIN, iwp, izp)

SPEC_P2P Construct a peak-to-peak gain specification.

Parameters:

• GAIN (double) – Peak-to-peak gain bound \(\gamma\).

• iwp (double (vector)) – Performance-input indices in the network.

• izp (double (vector)) – Performance-output indices in the network.

Returns:

A new peak-to-peak specification.

Return type:

spec_p2p

if nargin < 4

rho = 1;

end

Property Summary

gain

Peak-to-peak gain \(\gamma\).

weight

Weighting between the peak and gain terms.

Method Summary

create_vars(cons, name, config)

CREATE_VARS Create the peak-to-peak variables and constraints.

Introduces mu_p2p and (when targeted) gam_p2p, with the ordering and non-negativity constraints of the peak-to-peak certificate.

Parameters:

• cons – Accumulated LMI constraints.

• name (char) – Name suffix for the created variables.

• config (opt_config) – Configuration options.

Returns:

[vars, cons] — struct with fields mu_p2p, gam_p2p and the updated constraint set.

Return type:

struct, cell

quad_terminal(vars_spec)

QUAD_TERMINAL tbd

Parameters:

vars_spec (struct) – Specification variables (expects mu_p2p, gam_p2p).

Returns:

Decomposed terminal quadratic.

Return type:

quad_param

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.

Builds the running quadratic on the performance input channel. When this specification is the optimization target, the peak gain gam_p2p is minimized.

Parameters:

vars_spec (struct) – Specification variables (expects mu_p2p, gam_p2p).

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

Ergodic Convergence

class spec.spec_ergodic

Bases: spec.spec_interface

SPEC_ERGODIC Ergodic (sublinear-rate) convergence specification.

Enforces asymptotic stability of the algorithmic interconnection in an ergodic (averaged) sense, appropriate for algorithms whose last iterate need not converge but whose running averages do. The specification is built on the consensus-weighted performance channel produced by plant.genplant.genplant.perf_ergodic(), using the weighted consensus matrix \(N_w\).

A strict-passivity margin erg_pass supplies an objective for the alternating methods used to certify ergodic convergence.

Constructor Summary

spec_ergodic()

SPEC_ERGODIC Construct an ergodic convergence specification.

Property Summary

Nw

Weighted consensus matrix \(N_w\).

erg_pass

Strict-passivity margin used as an objective.

Method Summary

augment_ergodic(sys)

AUGMENT_ERGODIC add new input and output channels to the system to allow for ergodic performance specifications to be met (duality gap). Reads the consensus structure from the system, appends the

ergodic performance channel to the plant via plant.genplant.genplant.perf_ergodic(), and returns both the specification and the augmented system.

param sys:

The optimization-algorithm system.

returns:

[sys_erg] — the ergodic specification and the system with the ergodic performance channel added.

rtype:

spec_ergodic, (system)

create_vars(cons, name, config)

CREATE_VARS Create the strict-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 erg_pass and the updated constraint set.

Return type:

struct, cell

set_p(p)

SET_P Set the bisection parameter (the strict-passivity margin).

Parameters:

p (double) – New value of the margin, e.g. for a peak-to-peak certifier or an \(\ell_2\)-gain bound.

Returns:

The updated specification.

Return type:

spec_ergodic

supply(vars_spec)

SUPPLY Ergodic supply rate (duality gap).

Builds a passivity-type supply rate from the consensus matrix \(N_w\) and adds a strict-passivity penalty scaled by erg_pass. Returns empty if \(N_w\) is empty.

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.

Starts from the base-class decomposition and, when this specification is the optimization target, adds a strict passivity penalty erg_pass to the \(Q\) block and uses it as the objective.

Parameters:

vars_spec (struct) – Specification variables (expects erg_pass).

Returns:

[quad, objective] — the decomposed quadratic and the objective contribution.

Return type:

quad_param, double