Generalized Plant#

The input-output signals of the plant are

Input-Output Signals#
	Plant Input		Plant Output
\(z\)	input to operators	\(w\)	output from operators
\(z_p\)	performance output	\(w_p\)	Performance Input
\(y\)	output to controller	\(u\)	input from controller

The network with state \(x^N\) interfacing the operator \(F\) and the controller may be described as

\[\begin{split}\begin{align*} \mat{c}{x^N_{k+1} \hl z_k \\ z_{p k} \\ y_k} &= \mat{c|cc}{A & B_z & B_{z_p} & B_u \hl C_z & D_{zd} & D_{z w_p} & D_{zu} \\ C_{z_p} & D_{z_p d} & D_{z_p w_p} & D_{z_p u} \\ C_y & D_{yd} & D_{y w_p} & D_{yu}} \mat{c}{x_k^N \hl w_k \\ w_{pk} \\ u_k}. \end{align*}\end{split}\]

The dimensions of the signals are stored in a cell n, such as n.nz = 4and n.nzp = 0. This partitioning is used to pose the plants.

Individual Plants#

class plant.genplant.genplant#

GENPLANT A generalized plant with structured channel partitioning.

A generalized plant wraps a state-space system P and partitions its input/output channels into three groups:

Outputs (from network): \([z,\; z_p,\; y]\) — operator inputs, performance outputs, and controller inputs.
Inputs (to network): \([w,\; w_p,\; u]\) — operator outputs, performance inputs, and controller outputs.

The channel dimensions are stored as properties and used by the indexing methods to extract submatrices of P.

Note

The ordering convention is [z, zp, y] for outputs and [w, wp, u] inputs of the plant.

Example:

n.nz = 2; n.nw = 2; n.ny = 1; n.nu = 1; n.s = 1;
G = genplant(ss(A, B, C, D, 1), n);

Constructor Summary

genplant(P, n)#

GENPLANT Construct a generalized plant.

Wraps a state-space system and, optionally, records the dimensions of the channel partition.

Parameters:

P (ss or sdpss) – State-space system to wrap.
n (struct) – Channel dimensions. Required fields: nz, nw, ny, nu. Optional fields: nzp, nwp, s.

Returns:

A new genplant object.

Return type:

genplant

Property Summary

P#: State-space system (ss or sdpss object).

nu#: Dimension of controller output \(u\) (to network).

nw#: Dimension of operator output \(w\) (to network).

nwp#: Dimension of performance input \(w_p\) (to network).

ny#: Dimension of controller input \(y\) (from network).

nz#: Dimension of operator input \(z\) (from network).

nzp#: Dimension of performance output \(z_p\) (from network).

s#: Number of operators.

Method Summary

A()#

A State matrix of the wrapped system.

Returns:: Matrix \(A\).
Return type:: double

B()#

B Input matrix of the wrapped system.

Returns:: Matrix \(B\).
Return type:: double

Bu()#

BU Input matrix from controller output \(u\) to state.

Extracts the columns of B indexed by index_u().

Returns:: Submatrix \(B_u\).
Return type:: double

Bw()#

BW Input matrix from operator output \(w\) to state.

Extracts the columns of B indexed by index_w().

Returns:: Submatrix \(B_w\).
Return type:: double

Bwp()#

BWP Input matrix from performance input \(w_p\) to state.

Extracts the columns of B indexed by index_wp().

Returns:: Submatrix \(B_{w_p}\).
Return type:: double

C()#

C Output matrix of the wrapped system.

Returns:: Matrix \(C\).
Return type:: double

Cy()#

CY Output matrix from state to controller input \(y\).

Extracts the rows of C indexed by index_y().

Returns:: Submatrix \(C_y\).
Return type:: double

Cz()#

CZ Output matrix from state to operator input \(z\).

Extracts the rows of C indexed by index_z().

Returns:: Submatrix \(C_z\).
Return type:: double

Czp()#

CZP Output matrix from state to performance output \(z_p\).

Extracts the rows of C indexed by index_zp().

Returns:: Submatrix \(C_{z_p}\).
Return type:: double

D()#

D Feedthrough matrix of the wrapped system.

Returns:: Matrix \(D\).
Return type:: double

Dyu()#

DYU Direct feedthrough from controller output \(u\) to controller input \(y\).

Returns:: Submatrix \(D_{yu}\).
Return type:: double

Dyw()#

DYW Feedthrough from operator output \(w\) to controller input \(y\).

Returns:: Submatrix \(D_{yw}\).
Return type:: double

Dywp()#

DYWP Feedthrough from performance input \(w_p\) to controller input \(y\).

Returns:: Submatrix \(D_{yw_p}\).
Return type:: double

Dzpu()#

DZPU Feedthrough from controller output \(u\) to performance output \(z_p\).

Returns:: Submatrix \(D_{z_pu}\).
Return type:: double

Dzpw()#

DZPW Feedthrough from operator output \(w\) to performance output \(z_p\).

Returns:: Submatrix \(D_{z_pw}\).
Return type:: double

Dzpwp()#

DZPWP Feedthrough from performance input \(w_p\) to performance output \(z_p\).

Returns:: Submatrix \(D_{z_pw_p}\).
Return type:: double

Dzu()#

DZU Feedthrough from controller output \(u\) to operator input \(z\).

Returns:: Submatrix \(D_{zu}\).
Return type:: double

Dzw()#

DZW Feedthrough from operator output \(w\) to operator input \(z\).

Returns:: Submatrix \(D_{zw}\).
Return type:: double

Dzwp()#

DZWP Feedthrough from performance input \(w_p\) to operator input \(z\).

Returns:: Submatrix \(D_{zw_p}\).
Return type:: double

Ts()#

TS Sample time of the wrapped system.

Returns:: Sample time (0 for continuous, > 0 for discrete).
Return type:: double

add_oracle_input(ind_w, ind_z)#

ADD_ORACLE_INPUT Add external perturbation inputs at the operator.

Introduces additional performance inputs that perturb the operator channels:

\[w + \delta w \in F(z + \delta z)\]

The new inputs are appended to the \(w_p\) channel. No extra outputs are added.

Parameters:

ind_w (double (vector)) – Indices within the \(w\) channel to perturb.
ind_z (double (vector)) – Indices within the \(z\) channel to perturb.

Returns:

[obj, iwp] — updated plant and new performance input indices.

Return type:

genplant, double

add_oracle_shift(c)#

ADD_ORACLE_SHIFT Add a shifted perturbation input at the operator.

Introduces performance inputs corresponding to a uniform shift across operator channels:

\[w \in F(z + \delta z \otimes \mathbf{1}_s)\]

Parameters:: c (int) – Coordinate dimension (default: 1).
Returns:: [obj, iwp] — updated plant and new performance input indices.
Return type:: genplant, double

blkdiag(b2)#

BLKDIAG Block-diagonal interconnection of two generalized plants.

Constructs a new genplant whose system matrix is the block-diagonal of obj.P and b2.P, with input and output indices interleaved so that the \([z, z_p, y]\) / \([w, w_p, u]\) channel structure is preserved.

Parameters:: b2 (genplant) – The second plant.
Returns:: The block-diagonal plant.
Return type:: genplant

drop_performance()#

DROP_PERFORMANCE Remove the performance channel from the plant.

Constructs a new genplant with nzp = 0 and nwp = 0 by extracting only the \([z, y]\) / \([w, u]\) subsystem.

Returns:: Plant without the performance channel.
Return type:: genplant

dump_dim()#

DUMP_DIM Return channel dimensions as a struct.

Returns:: Struct with fields nw, nwp, nu, ny, nz, nzp, s.
Return type:: struct

eig()#

EIG get the eigenvalues of the A matrix. Should have absolute value less than one for stability

Returns:: e – vector of eigenvalues

index_notu()#

INDEX_NOTU Indices of the combined \([w,\; w_p]\) channels.

Returns all input indices except the controller output.

Returns:: Index vector 1:(nw + nwp).
Return type:: double (row vector)

index_u()#

INDEX_U Indices of the controller-output channel \(u\).

Returns:: Index vector for \(u\), offset by nw + nwp.
Return type:: double (row vector)

index_w()#

INDEX_W Indices of the operator-output channel \(w\).

Returns:: Index vector 1:nw.
Return type:: double (row vector)

index_wp()#

INDEX_WP Indices of the performance-input channel \(w_p\).

Returns:: Index vector for \(w_p\), offset by nw.
Return type:: double (row vector)

index_y()#

INDEX_Y Indices of the controller-input channel \(y\).

Returns:: Index vector for \(y\), offset by nz + nzp.
Return type:: double (row vector)

index_z()#

INDEX_Z Indices of the operator-input channel \(z\).

Returns:: Index vector 1:nz.
Return type:: double (row vector)

index_zp()#

INDEX_ZP Indices of the performance-output channel \(z_p\).

Returns:: Index vector for \(z_p\), offset by nz.
Return type:: double (row vector)

lft(b2)#

LFT Lower linear fractional transformation (star product).

Closes the feedback loop between obj (upper block) and b2 (lower block) along the shared \((u, y)\) channels. The resulting plant inherits the operator channels of obj and the controller channels of b2.

Parameters:: b2 (genplant or ss) – The lower plant or controller.
Returns:: The interconnected plant.
Return type:: genplant

lft_lower(b2)#

LFT_LOWER Lower linear fractional transformation (alias).

Equivalent to lft(). Provided for symmetry with lft_upper().

Parameters:: b2 (genplant) – The lower plant.
Returns:: The interconnected plant.
Return type:: genplant

lft_upper(b2, nz2, nw2)#

LFT_UPPER Upper linear fractional transformation.

Closes the feedback loop with b2 as the upper block and obj as the lower block. The resulting plant inherits the operator channels of b2 and the controller channels of obj.

Parameters:

b2 (genplant or ss) – The upper plant.
nz2 (int) – Number of output channels to close (used when b2 is a plain ss).
nw2 (int) – Number of input channels to close (used when b2 is a plain ss).

Returns:

The interconnected plant.

Return type:

genplant

lift(c)#

LIFT Kronecker lift of the plant by an identity matrix.

Replaces every matrix \(M\) in the state-space representation with \(M \otimes I_c\). All channel dimensions are multiplied by c.

Parameters:: c (int) – Lift dimension (size of the identity block).
Returns:: The lifted plant.
Return type:: genplant

nx()#

NX Number of states in the wrapped system.

Returns:: State dimension.
Return type:: int

perf_ergodic(Nw)#

PERF_ERGODIC Add performance channels for ergodic convergence.

Appends performance inputs and outputs that encode an ergodic convergence condition using the consensus matrix Nw.

Parameters:: Nw (double or empty) – Consensus weighting matrix. Pass [] to skip.
Returns:: [obj, iwp, izp] — updated plant, new performance input indices, and new performance output indices.
Return type:: genplant, double, double

perf_output_con(c, iz)#

PERF_OUTPUT_CON Add performance outputs for consensus tracking.

Appends outputs measuring the deviation from the average:

\[z_p^i = z^i - \mathrm{average}(z)\]

Parameters:

c (int) – Coordinate / Kronecker lift dimension (default: 1).
iz (double (vector)) – Indices of operator inputs to track (default: 1:nz).

Returns:

[obj, izp] — updated plant and new performance output indices.

Return type:

genplant, double

perf_output_opt(c, bind)#

PERF_OUTPUT_OPT Add performance outputs for the optimality condition.

Appends a performance output that sums selected operator outputs:

\[z_p = \sum_{i=1}^{s} w^i\]

Parameters:

c (int) – Coordinate / Kronecker lift dimension (default: 1).
bind (double (vector)) – Indices identifying repeated nonlinearity evaluations (default: 1:nw/c).

Returns:

[obj, izp] — updated plant and new performance output indices.

Return type:

genplant, double

perf_output_w(iw)#

PERF_OUTPUT_W Add performance outputs tracking the \(w\) channel.

Appends new rows to the \(z_p\) channel that directly observe selected operator outputs.

Parameters:: iw (double (vector)) – Indices within \(w\) to observe.
Returns:: [obj, izp] — updated plant and new performance output indices.
Return type:: genplant, double

perf_output_z(ind_z)#

PERF_OUTPUT_Z Add performance outputs tracking the \(z\) channel.

Appends new rows to the \(z_p\) channel that observe selected operator inputs.

Parameters:: ind_z (double (vector)) – Indices within \(z\) to observe.
Returns:: [obj, izp] — updated plant and new performance output indices.
Return type:: genplant, double

rhotrafo(rho)#

RHOTRAFO Apply an exponential discount (rho-transformation).

Scales A and B by \(\rho^{-1}\), which corresponds to an exponential weighting of the signals in discrete time.

Parameters:: rho (double) – Discount factor.
Returns:: The transformed plant (modified in place).
Return type:: genplant

ss()#

SS Extract the raw state-space object.

Returns:: The underlying ss system.
Return type:: ss

ss_zy_wu()#

SS_ZY_WU Extract plant matrices for the \([w, u] \to [z, y]\) subsystem.

Returns the nine matrices of the two-port partition:

\[\begin{split}\begin{bmatrix} z \\ y \end{bmatrix} = \begin{bmatrix} D_{11} & D_{12} \\ D_{21} & D_{22} \end{bmatrix} \begin{bmatrix} w \\ u \end{bmatrix} + \begin{bmatrix} C_1 \\ C_2 \end{bmatrix} x\end{split}\]

Returns:: [A, B1, B2, C1, D11, D12, C2, D21, D22]
Return type:: double (multiple outputs)

ssdata()#

SSDATA Extract state-space matrices of the wrapped system.

Returns:: [A, B, C, D] — the state-space quadruple.
Return type:: double (multiple outputs)

tf()#

TF Transfer function representation of the plant.

Returns:: Transfer function of P.
Return type:: tf

Cell of Plants (Subsystems)#

The genplant_poly class is used to store subsystems in the switched systems setting.

class plant.genplant.genplant_poly#

Bases: plant.genplant.genplant, matlab.mixin.indexing.RedefinesBrace

GENPLANT_POLY a generalized plant defined over corners of a polytope. Used for switched systems

Constructor Summary

genplant_poly(P_orig, n)#

Constructor

Parameters:

P (cell of sdpss) – state space systems for each subsystem
n (struct) – partition of the channels into [z, zp, y], [w, wp, u]

Method Summary

A()#: cell of A matrices in state space systems

B()#: cell of B matrices in state space systems

C()#: cell of C matrices in state space systems

D()#: cell of D matrices in state space systems

Dyu()#: controller output to controller input, direct feedthrough

Nss()#: number of subsystems

add_oracle_input(ind_w, ind_z)#

add external inputs at the operator F

\(w + \delta w \in F(z + dz)\) :param ind_w: at the input of the operator :param ind_z: at the output of the operator

Return:: iwp – new performance input indices

blkdiag(b2)#

block-diagonal of two plants, comporting with the indexing scheme

Parameters:: b2 (genplant) – the other plant

Returns: b_out (genplant): the block diagonal plant

lft(b2)#

LFT linear fractional transformation: feedback interconnection of obj and plant b2 along common channels (u, y) in each subsystem obj star b2

Parameters:: b2 (genplant) – the other plant

Returns: b_out (genplant): the lft plant

nx()#: number of states

perf_ergodic(Nw)#

PERF_ERGODIC inputs and outputs for ergodic convergence

Parameters:

Nw – given consensus matrix

Return:

iwp – new performance input indices
izp – new performance output indices

perf_output_con(c, ind_z)#

PERF_OUTPUT_CON: add performance to track the consensus output: z_p^i = z^i - text{average}(z)

Parameters:

c – dimension of the coordinate/kronecker lift
iz – indices of input of operators

Return:

izp – new performance output indices

perf_output_opt(c)#

PERF_OUTPUT_OPT add performance to track the w output condition, :param ind_w: indices of the input of the operator

Return:: izp – new performance output indices

perf_output_w(ind_w)#

PERF_OUTPUT_W: add performance to track the w output

Parameters:: ind_w – indices of the input of the operator
Return:: izp – new performance output indices

perf_output_z(ind_z)#

PERF_OUTPUT_Z: add performance to track the z output

Parameters:: ind_z – indices of the output of the operator
Return:: izp – new performance output indices

rhotrafo(rho)#

RHOTRAFO Apply an exponential discount (rho-transformation).

Scales A and B by \(\rho^{-1}\), which corresponds to an exponential weighting of the signals in discrete time.

Parameters:: rho (double) – Discount factor.
Returns:: The transformed plant (modified in place).
Return type:: genplant

ss()#: extract the state-space expression

ss_zy_wu(ind)#

get plant matrices for the [wu] -> [zy] subsytsem

Parameters:: ind – the index of the subsystem to get information from

Generalized Plant

Contents

Generalized Plant#

Individual Plants#

Cell of Plants (Subsystems)#