DirectSD-Python 0.1.0__py3-none-any.whl

directsd/sspace/plant.py

@@ -0,0 +1,198 @@
+"""
+GeneralizedPlant — the standard LFT augmented plant for sampled-data H2/Hinf design.
+
+In the DirectSD toolbox (and H∞ control theory generally), the *generalized plant*
+(also called augmented plant) partitions the plant into four sub-blocks::
+
+        [z]   [P11  P12] [w]
+        [y] = [P21  P22] [u]
+
+where:
+    w — exogenous inputs (disturbances, reference signals)
+    u — control inputs
+    z — performance outputs (signals to be minimised)
+    y — measurement outputs (signals available to the controller)
+
+This class provides the Python equivalent of MATLAB's natural matrix concatenation::
+
+    sys = [F*Fw  F          ← performance rows
+           0     rho        ← (can be multiple performance rows)
+          -F*Fw  -F]        ← measurement row
+
+Usage::
+
+    from directsd import GeneralizedPlant
+
+    sys = GeneralizedPlant([
+        [F*Fw,   F ],
+        [0,      rho],
+        [-F*Fw, -F ],
+    ])                       # 3-output × 2-input, n_meas=1, n_ctrl=1 by default
+
+    K, cost = sdh2(sys, T=0.1)
+"""
+
+import numpy as np
+import scipy.signal as sig
+from directsd.tf.interconnect import to_lti
+
+
+class GeneralizedPlant:
+    """
+    Standard generalized (augmented) plant for sampled-data H2/Hinf design.
+
+    Parameters
+    ----------
+    rows : list[list] or scipy.signal.StateSpace
+        Either a 2-D grid of SISO blocks (scalars, ``(num, den)`` tuples, or
+        ``scipy.signal.lti`` objects), or a pre-built ``StateSpace``.
+        The grid shape determines the total number of outputs and inputs.
+    n_perf : int, optional
+        Number of performance outputs (z-rows). Default: ``nout - n_meas``.
+    n_meas : int, optional
+        Number of measurement outputs (y-rows). Default: ``1``.
+    n_dist : int, optional
+        Number of exogenous inputs (w-columns). Default: ``nin - n_ctrl``.
+    n_ctrl : int, optional
+        Number of control inputs (u-columns). Default: ``1``.
+
+    Attributes
+    ----------
+    n_perf, n_meas, n_dist, n_ctrl : int
+        Partition sizes.
+    A, B, C, D : numpy.ndarray
+        State-space matrices (delegated from the internal StateSpace).
+
+    Examples
+    --------
+    Standard 1-DOF H2 plant (3 outputs, 2 inputs)::
+
+        sys = GeneralizedPlant([
+            [_mul(Fw, F),   F ],   # performance: weighted output
+            [0,             rho],  # performance: control cost
+            [_neg(_mul(Fw, F)), _neg(F)],  # measurement
+        ])
+
+    2-DOF plant (3 outputs, 2 inputs, n_meas=2)::
+
+        sys = GeneralizedPlant([
+            [_neg(F), _neg(F)],    # performance
+            [1,       0      ],    # measurement 1: reference
+            [0,       _neg(F)],    # measurement 2: plant output
+        ], n_meas=2)
+    """
+
+    def __init__(self, rows, *, n_perf=None, n_meas=1, n_dist=None, n_ctrl=1):
+        if isinstance(rows, sig.StateSpace):
+            ss = rows
+        else:
+            ss = _build_ss(rows)
+
+        nout = ss.C.shape[0]
+        nin = ss.B.shape[1]
+
+        self._ss = ss
+        self.n_meas = int(n_meas)
+        self.n_ctrl = int(n_ctrl)
+        self.n_perf = int(nout - n_meas) if n_perf is None else int(n_perf)
+        self.n_dist = int(nin - n_ctrl) if n_dist is None else int(n_dist)
+
+    # ── State-space matrix access ──────────────────────────────────────────────
+
+    @property
+    def A(self):
+        return self._ss.A
+
+    @property
+    def B(self):
+        return self._ss.B
+
+    @property
+    def C(self):
+        return self._ss.C
+
+    @property
+    def D(self):
+        return self._ss.D
+
+    # ── Interop ────────────────────────────────────────────────────────────────
+
+    def to_statespace(self) -> sig.StateSpace:
+        """Return the underlying ``scipy.signal.StateSpace``."""
+        return self._ss
+
+    @property
+    def P22(self) -> sig.StateSpace:
+        """
+        Extract P22 sub-block (lower-right corner: y ← u channel).
+
+        Returns a ``StateSpace`` with shared A matrix and the last
+        ``n_meas`` output rows and last ``n_ctrl`` input columns.
+        """
+        A = self._ss.A
+        B2 = self._ss.B[:, -self.n_ctrl:]
+        C2 = self._ss.C[-self.n_meas:, :]
+        D22 = self._ss.D[-self.n_meas:, -self.n_ctrl:]
+        return sig.StateSpace(A, B2, C2, D22)
+
+    def __repr__(self) -> str:
+        nout = self._ss.C.shape[0]
+        nin = self._ss.B.shape[1]
+        n = self._ss.A.shape[0]
+        return (
+            f"GeneralizedPlant({nout}×{nin}, states={n}, "
+            f"n_perf={self.n_perf}, n_meas={self.n_meas}, "
+            f"n_dist={self.n_dist}, n_ctrl={self.n_ctrl})"
+        )
+
+
+# ── Internal block-matrix assembler ───────────────────────────────────────────
+
+_coerce_lti = to_lti  # alias used by _block_abcd below
+
+
+def _block_abcd(P):
+    """Convert a SISO block to (A, B, C, D) arrays with shape (n,), (n,1), (1,n), (1,1)."""
+    if isinstance(P, list) and len(P) == 1:
+        P = P[0]
+    if np.isscalar(P) or (isinstance(P, np.ndarray) and P.ndim == 0):
+        return (np.zeros((0, 0)), np.zeros((0, 1)),
+                np.zeros((1, 0)), np.array([[float(P)]]))
+    ss = _coerce_lti(P).to_ss()
+    n = ss.A.shape[0]
+    return (ss.A,
+            ss.B.reshape(n, 1),
+            ss.C.reshape(1, n),
+            ss.D.reshape(1, 1))
+
+
+def _build_ss(rows) -> sig.StateSpace:
+    """
+    Assemble a MIMO StateSpace from a 2-D list of SISO blocks.
+
+    Each block gets independent state variables (block-diagonal A matrix).
+    """
+    nr = len(rows)
+    nc = len(rows[0])
+    blk = [[_block_abcd(rows[i][j]) for j in range(nc)] for i in range(nr)]
+    ns = [[blk[i][j][0].shape[0] for j in range(nc)] for i in range(nr)]
+    ntot = sum(ns[i][j] for i in range(nr) for j in range(nc))
+
+    A = np.zeros((ntot, ntot))
+    B = np.zeros((ntot, nc))
+    C = np.zeros((nr, ntot))
+    D = np.zeros((nr, nc))
+
+    off = 0
+    for j in range(nc):
+        for i in range(nr):
+            Aij, Bij, Cij, Dij = blk[i][j]
+            nij = ns[i][j]
+            if nij > 0:
+                A[off:off + nij, off:off + nij] = Aij
+                B[off:off + nij, j:j + 1] = Bij
+                C[i:i + 1, off:off + nij] = Cij
+            D[i, j] = Dij[0, 0]
+            off += nij
+
+    return sig.StateSpace(A, B, C, D)

directsd/tf/__init__.py

@@ -0,0 +1,9 @@
+"""
+Transfer-function utilities for DirectSD.
+"""
+
+from directsd.tf.interconnect import (
+    to_lti, nd, mul, neg, add, feedback, nd_mul, nd_neg,
+)
+
+__all__ = ['to_lti', 'nd', 'mul', 'neg', 'add', 'feedback', 'nd_mul', 'nd_neg']

directsd/tf/interconnect.py

@@ -0,0 +1,105 @@
+"""
+Transfer-function block diagram arithmetic.
+
+Provides scalar/tuple/(num,den)/lti-compatible operations for building
+interconnected SISO transfer functions before assembling them into a
+GeneralizedPlant.
+
+Functions
+---------
+to_lti   -- coerce any TF-like input to scipy.signal.lti
+nd       -- extract (num, den) 1-D arrays from any TF-like input
+mul      -- series (cascade) connection: P1 * P2 * ...
+neg      -- negate: -P
+add      -- parallel (sum) connection: P + Q
+feedback -- unity negative feedback: P / (1 + P)
+nd_mul   -- series connection, returns (num, den) tuple
+nd_neg   -- negate, returns (num, den) tuple
+"""
+
+import numpy as np
+import scipy.signal as sig
+
+
+def to_lti(P):
+    """
+    Coerce any TF-like input to a ``scipy.signal.lti`` object.
+
+    Accepts: scalar, ``(num, den)`` tuple, ``scipy.signal.lti`` subclass,
+    ``TransferFunction``, ``ZerosPolesGain``, or ``StateSpace``.
+    """
+    if isinstance(P, (sig.lti, sig.TransferFunction,
+                      sig.ZerosPolesGain, sig.StateSpace)):
+        return P
+    if isinstance(P, tuple) and len(P) == 2:
+        return sig.TransferFunction(*P)
+    if np.isscalar(P):
+        return sig.TransferFunction([float(P)], [1.0])
+    raise TypeError(f"Cannot coerce {type(P)} to lti")
+
+
+def nd(P):
+    """
+    Extract ``(num, den)`` 1-D arrays from any TF-like input.
+
+    Accepts the same types as :func:`to_lti`, plus raw ``(num, den)`` tuples.
+    """
+    if np.isscalar(P):
+        return np.array([float(P)]), np.array([1.0])
+    if isinstance(P, tuple) and len(P) == 2:
+        return (np.atleast_1d(np.array(P[0], float)).ravel(),
+                np.atleast_1d(np.array(P[1], float)).ravel())
+    if hasattr(P, 'to_tf'):
+        P = P.to_tf()
+    if isinstance(P, (sig.lti, sig.TransferFunction)):
+        return (np.atleast_1d(np.array(P.num, float)).ravel(),
+                np.atleast_1d(np.array(P.den, float)).ravel())
+    raise TypeError(f"Cannot extract (num, den) from {type(P)}")
+
+
+def mul(*plants):
+    """Series (cascade) connection of two or more transfer functions."""
+    n, d = nd(plants[0])
+    for p in plants[1:]:
+        pn, pd = nd(p)
+        n = np.polymul(n, pn)
+        d = np.polymul(d, pd)
+    return sig.TransferFunction(n, d)
+
+
+def neg(P):
+    """Negate a transfer function: returns ``-P``."""
+    n, d = nd(P)
+    return sig.TransferFunction(-n, d)
+
+
+def add(P, Q):
+    """Parallel (sum) connection: returns ``P + Q``."""
+    pn, pd = nd(P)
+    qn, qd = nd(Q)
+    return sig.TransferFunction(
+        np.polyadd(np.polymul(pn, qd), np.polymul(qn, pd)),
+        np.polymul(pd, qd),
+    )
+
+
+def feedback(P):
+    """Unity negative feedback: returns ``P / (1 + P)``."""
+    pn, pd = nd(P)
+    return sig.TransferFunction(pn, np.polyadd(pd, pn))
+
+
+def nd_mul(*plants):
+    """Series connection returning a ``(num, den)`` tuple."""
+    n, d = nd(plants[0])
+    for p in plants[1:]:
+        pn, pd = nd(p)
+        n = np.polymul(n, pn)
+        d = np.polymul(d, pd)
+    return (n, d)
+
+
+def nd_neg(P):
+    """Negate, returning a ``(num, den)`` tuple."""
+    n, d = nd(P)
+    return (-n, d)

directsd/zpk/__init__.py

@@ -0,0 +1 @@
+from directsd.zpk.zpk import Zpk, _zpk_snap