tf2ss 1.0.0__py3-none-any.whl

tf2ss/__init__.py

@@ -0,0 +1,13 @@
+"""
+Convert your MISO/SIMO/MIMO systems from transfer function to state-space.
+"""
+
+from .tf2ss import _get_lcm_norm_coeffs, _pad_numerators, tf2ss
+from .timeresp import forced_response
+
+__all__ = [
+    "_get_lcm_norm_coeffs",
+    "_pad_numerators",
+    "forced_response",
+    "tf2ss",
+]

tf2ss/test_tf2ss.py

@@ -0,0 +1,180 @@
+"""Tests of tf2ss on various sample systems and consistency with SLYCOT."""
+
+import control as ctrl
+import numpy as np
+import pytest
+from control.exception import slycot_check
+from scipy import signal
+
+from tf2ss import _get_lcm_norm_coeffs, _pad_numerators, tf2ss
+
+systems = [
+    ([[[0.5]]], [[[32]]]),
+    ([[[1]]], [[[1, 2]]]),  # H(s) = 1 / (s+2)
+    ([[[1, 1]]], [[[1, 3, 2]]]),  # H(s) = (s+1) / (s^2 + 3s + 2)
+    (
+        [[[1], [0.5]], [[0], [1]]],
+        [[[1, 2], [1, 2]], [[0, 1], [1, 2]]],
+    ),  # MIMO case - different denominators
+    (
+        [
+            [[0.0, 0.0, 1.0], [1.0, 0.0, 0.0]],
+            [[3.0, -1.0, 1.0], [0.0, 1.0, 0.0]],
+            [[0.0, 0.0, 1.0], [0.0, 2.0, 0.0]],
+        ],
+        [
+            [[1.0, 0.4, 3.0], [1.0, 1.0, 0.0]],
+            [[1.0, 0.4, 3.0], [1.0, 1.0, 0.0]],
+            [[1.0, 0.4, 3.0], [1.0, 1.0, 0.0]],
+        ],
+    ),  # MIMO case - different denominators
+    (
+        [
+            [[1.0, 6.0, 12.0, 7.0], [0.0, 1.0, 4.0, 3.0]],
+            [[0.0, 0.0, 1.0, 1.0], [1.0, 8.0, 20.0, 15.0]],
+        ],
+        [
+            [[1.0, 6.0, 11.0, 6.0], [1.0, 6.0, 11.0, 6.0]],
+            [[1.0, 6.0, 11.0, 6.0], [1.0, 6.0, 11.0, 6.0]],
+        ],
+    ),
+]
+
+
+def compare_poles(poles_1, poles_2):
+    # Check if all poles are stable (real part < 0)
+    assert np.all(poles_1 <= 0), "Unstable poles in 1"
+    assert np.all(poles_2 <= 0), "Unstable poles in 2"
+
+    # Sort poles by their real parts (most dominant first)
+    poles_1 = sorted(poles_1, key=lambda x: -np.real(x))
+    poles_2 = sorted(poles_2, key=lambda x: -np.real(x))
+
+    # Find the number of dominant poles to compare
+    min_length = min(len(poles_1), len(poles_2))
+
+    # Log information about the different dimensions if they exist
+    if len(poles_1) != len(poles_2):
+        print(
+            f"Note: Different number of poles detected - A_1: {len(poles_1)}, A_2: {len(poles_2)}"
+        )
+
+    # Compare the dominant poles
+    for i in range(min_length):
+        assert np.isclose(poles_1[i], poles_2[i], rtol=1e-5, atol=1e-5), (
+            f"Dominant pole {i} differs: {poles_1[i]} vs {poles_2[i]}"
+        )
+
+
+def compare_systems(sys_1: signal.StateSpace, sys_2: signal.StateSpace):
+    # Additional check: compare system responses
+    # This ensures that even with different numbers of poles, the systems behave similarly
+    t = np.linspace(0, 10, 1000)  # Time vector for simulation
+
+    # Generate step responses
+    # TODO: fix error - ValueError: System does not define that many inputs.
+    _, y_1 = signal.step(sys_1, T=t)
+    _, y_2 = signal.step(sys_2, T=t)
+
+    # Compare step responses
+    assert np.allclose(y_1, y_2, rtol=1e-4, atol=1e-4), (
+        "Step responses differ between original and minimal"
+    )
+
+    assert np.allclose(sys_1.A, sys_2.A, atol=1e-6), "Mismatch in A matrix"
+    assert np.allclose(sys_1.B, sys_2.B, atol=1e-6), "Mismatch in B matrix"
+    assert np.allclose(sys_1.C, sys_2.C, atol=1e-6), "Mismatch in C matrix"
+    assert np.allclose(sys_1.D, sys_2.D, atol=1e-6), "Mismatch in D matrix"
+
+
+@pytest.mark.parametrize("num, den", systems)
+def test_vs_slycot(num, den):
+    if not slycot_check():
+        pytest.skip("Slycot not available, skipping test")
+    A, B, C, D = tf2ss(num, den, minreal=False)
+
+    # Convert to control.TransferFunction format
+    n_outputs = len(num)
+    n_inputs = len(num[0])
+    tf_mimo = [
+        [ctrl.TransferFunction(num[i][j], den[i][j]) for j in range(n_inputs)]
+        for i in range(n_outputs)
+    ]
+
+    # Convert using control.tf2ss (uses slycot if available)
+    A_slycot, B_slycot, C_slycot, D_slycot = ctrl.ssdata(
+        ctrl.append(*[ctrl.append(*row) for row in tf_mimo])
+    )
+    poles = np.linalg.eigvals(A)
+    poles_slycot = np.linalg.eigvals(A_slycot)
+    import control
+
+    sys1 = control.StateSpace(A, B, C, D)
+    sys2 = control.StateSpace(A_slycot, B_slycot, C_slycot, D_slycot)
+
+    # Get transmission zeros for both systems
+    zeros1 = control.zeros(sys1)
+    zeros2 = control.zeros(sys2)
+
+    # Sort zeros for consistent comparison
+    zeros1 = np.sort_complex(zeros1)
+    zeros2 = np.sort_complex(zeros2)
+    print("zero found by us", zeros1)
+    print("zeros found by slycot", zeros2)
+
+    # Ensure same number of zeros
+    assert len(zeros1) == len(zeros2), (
+        f"Number of zeros differs: {len(zeros1)} vs {len(zeros2)}"
+    )
+
+    # Compare each zero
+    for i in range(len(zeros1)):
+        assert np.isclose(zeros1[i], zeros2[i], rtol=1e-5, atol=1e-5), (
+            f"Zero {i} differs: {zeros1[i]} vs {zeros2[i]}"
+        )
+
+    print("poles found by us", poles)
+    print("poles found by slycot", poles_slycot)
+    compare_poles(poles, poles_slycot)
+
+    # compare_systems(
+    #     signal.StateSpace(A, B, C, D),
+    #     signal.StateSpace(A_slycot, B_slycot, C_slycot, D_slycot),
+    # )
+
+
+@pytest.mark.parametrize("num, den", systems)
+def test_tf2ss_runability(num, den):
+    A, B, C, D = tf2ss(_pad_numerators(num), den)
+
+
+@pytest.mark.parametrize(
+    "den",
+    [
+        [
+            [
+                [1.0, 0.5],  # (s + 0.5)
+                [1.0, 0.5, 0.25],  # (s^2 + 0.5s + 0.25)
+            ]
+        ],  # [1.0, 1.0, 0.75, 0.125]
+        [[[1, 7, 6], [1, -5, -6]]],
+        [[[3, -6, -9, 0], [7, 21, 14, 0, 0]]],
+        [
+            [[3, -6, -9, 0], [1, 0]],
+            [[7, 21, 14, 0, 0], [1, 0]],
+        ],
+        [[[3, -6, -9, 0], [7, 21, 14, 0, 0]], [[1, 7, 6], [1, -5, -6]]],
+    ],
+)
+def test_coeffs_retrieval(den):
+    den_our = _get_lcm_norm_coeffs(den, mode="local")
+    sys = ctrl.tf(
+        [[[1] * len(den) for den in row] for row in den],
+        den,
+    )
+    if isinstance(sys, ctrl.TransferFunction):
+        _, den_ctrl, _ = sys._common_den()
+        _, den_min, _ = sys.minreal()._common_den()
+        assert np.allclose(den_our, den_ctrl, atol=1e-5)
+        # TODO: create test evaluating minimum realization when implemented
+        # assert np.allclose(den_our, den_min, atol=1e-5)

tf2ss/tf2ss.py

@@ -0,0 +1,401 @@
+"""Helper functions for tf2ss conversion."""
+
+from math import gcd
+from typing import Any, Literal, overload
+
+import numpy as np
+import sympy as sp
+from control import TransferFunction, tf
+from numpy.typing import NDArray
+from scipy.signal import tf2ss as tf2ss_siso
+
+
+def _pad_numerators(
+    numerators: list[list[list[int | float]]],
+) -> list[list[list[int | float]]]:
+    """Pad the numerator matrix of polynomials with zeros to have all equal length, padding from the left.
+
+    Parameters:
+        numerators: List of lists of numerators for each (output, input) transfer function.
+
+    Returns:
+        Padded numerator list with all numerators having the same length.
+
+    Examples:
+        >>> _pad_numerators([[[1], [1, 2]], [[1, 2, 3], [1]]])
+        [[[0, 0, 1], [0, 1, 2]], [[1, 2, 3], [0, 0, 1]]]
+    """
+    max_len = max(len(num) for row in numerators for num in row)
+    pad_with = 0 if isinstance(numerators[0][0][0], int) else 0.0
+    # type_ = type(numerators[0][0][0])
+    padded_numerators = [
+        [[pad_with] * (max_len - len(num)) + num for num in row]
+        for row in numerators
+    ]
+    return padded_numerators
+
+
+def list_to_poly(coefs: list[Any], s: sp.Symbol = sp.Symbol("s")) -> sp.Poly:
+    """Convert a list of coefficients (in descending order) into a sympy Poly.
+
+    Parameters:
+      coefs: List of coefficients (descending order).
+             For example, [1, 3, 2] represents 1*s**2 + 3*s + 2.
+      s: sympy symbol (default is s).
+
+    Returns:
+      A sympy Poly object.
+
+    Examples:
+        >>> p = list_to_poly([1, 3, 2])
+        >>> sp.expand(p.as_expr())
+        s**2 + 3*s + 2
+        >>> sp.expand(p.as_expr()) == sp.expand(sp.Symbol('s')**2 + 3*sp.Symbol('s') + 2)
+        True
+    """
+    poly_expr = sum(
+        coef * s ** (len(coefs) - i - 1) for i, coef in enumerate(coefs)
+    )
+    return sp.Poly(poly_expr, s)
+
+
+def compute_lcd_from_denominators(
+    denominators: list[list[list[float]]], s: sp.Symbol = sp.Symbol("s")
+) -> sp.Poly:
+    """Compute the least common denominator (LCD) of a MIMO system's denominators.
+
+    Parameters:
+      denominators: A list of lists of denominators. Each denominator is a list of coefficients
+                in descending order.
+      s: sympy symbol (default is s).
+
+    Returns:
+      A sympy Poly representing the LCD.
+
+    Examples:
+        >>> lcd = compute_lcd_from_denominators([[[1, 2]], [[1, 2]]])
+        >>> sp.expand(lcd.as_expr())
+        s + 2
+    """
+    # Start with the first denominator in the list
+    first_poly = list_to_poly(denominators[0][0], s)
+    lcd = first_poly
+    for row in denominators:
+        for den in row:
+            poly = list_to_poly(den, s)
+            lcd = sp.lcm(lcd, poly)
+    return lcd
+
+
+def compute_adjusted_num(
+    numerator: list[Any],
+    lcd: sp.Poly,
+    denominator: list[Any],
+    s: sp.Symbol = sp.Symbol("s"),
+) -> list[Any]:
+    """Compute the adjusted numerator polynomial coefficients given the numerator and denominator
+    of a transfer function and the common LCD.
+
+    This function multiplies the original numerator by the LCD and divides by the original
+    denominator. The resulting quotient (assumed to be exact) gives the adjusted numerator.
+
+    Parameters:
+      numerator: List of numerator coefficients (in descending order).
+      lcd: A sympy Poly representing the least common denominator.
+      denominator: List of denominator coefficients (in descending order).
+      s: sympy symbol (default is s).
+
+    Returns:
+      A numpy array of adjusted numerator coefficients (in descending order).
+
+    Examples:
+        >>> compute_adjusted_num([1, 1], list_to_poly([1, 3, 2]), [1, 3, 2])
+        [1, 1]
+    """
+    num_poly = list_to_poly(numerator, s)
+    den_poly = list_to_poly(denominator, s)
+    # Multiply numerator polynomial by LCD
+    new_expr = sp.expand(num_poly.as_expr() * lcd.as_expr())
+    new_poly = sp.Poly(new_expr, s)
+    quotient, remainder = sp.div(new_poly, den_poly)
+    if remainder.as_expr() != 0:
+        raise ValueError("Adjusted numerator division has non-zero remainder")
+    return quotient.all_coeffs()
+
+
+def transpose(matrix: list[list[Any]]) -> list[list[Any]]:
+    """Transpose a list of lists (matrix).
+
+    Parameters:
+        matrix: List of lists to be transposed.
+
+    Returns:
+        Transposed list of lists.
+
+    Examples:
+        >>> transpose([[1, 2, 3], [4, 5, 6]])
+        [[1, 4], [2, 5], [3, 6]]
+    """
+    return [list(row) for row in zip(*matrix)]
+
+
+def state_space_from_poly(poly: sp.Poly) -> tuple[NDArray, NDArray]:
+    """Compute the state-space representation (A, B) from the denominator polynomial using tf2ss.
+
+    Parameters:
+      poly: A sympy Poly representing the denominator.
+
+    Returns:
+      A, B: Matrices from the tf2ss representation of the system with transfer function 1/poly.
+
+    Examples:
+        >>> A, B = state_space_from_poly(list_to_poly([1, 2]))
+        >>> A.shape
+        (1, 1)
+        >>> B.shape
+        (1, 1)
+    """
+    lcd_coeffs = np.array(poly.all_coeffs(), dtype=np.float64)
+    A, B, _, _ = tf2ss_siso([1], lcd_coeffs)
+    return A, B
+
+
+@overload
+def _get_lcm_norm_coeffs(
+    denominators: list[list[list[float]]],
+    mode: Literal["global"],
+) -> list[float]: ...
+
+
+@overload
+def _get_lcm_norm_coeffs(
+    denominators: list[list[list[float]]],
+    mode: Literal["local"],
+) -> list[list[float]]: ...
+
+
+def _get_lcm_norm_coeffs(
+    denominators: list[list[list[float]]],
+    mode: Literal["global", "local"] = "global",
+) -> list[float] | list[list[float]]:
+    """Compute the least common multiple (LCM) of a list of floating-point polynomials.
+
+    Parameters:
+      denominators: A list of lists of lists of floating-point coefficients representing the denominators.
+      mode: A string indicating the mode of LCM computation. Can be "global" or "local".
+            "global" computes a single LCM for all denominators.
+            "local" computes LCMs for each input of denominators.
+
+    Returns:
+      If mode is "global", returns a list of floating-point coefficients representing the LCM.
+      If mode is "local", returns a list of lists of floating-point coefficients representing the LCMs for each column.
+
+    Examples:
+        >>> denominators = [[[1.0, 2.0], [1.0, 1.0]], [[1.0, 2.0], [1.0, 3.0]]]
+        >>> _get_lcm_norm_coeffs(denominators, mode="global")
+        [1.0, 6.0, 11.0, 6.0]
+
+        >>> denominators = [[[1.0, 2.0], [1.0, 1.0]], [[1.0, 2.0], [1.0, 3.0]]]
+        >>> _get_lcm_norm_coeffs(denominators, mode="local")
+        [[1.0, 2.0, 0.0], [1.0, 4.0, 3.0]]
+    """
+    if mode == "local":
+        # TransferFunction.common_den() right-pads the denominators with zeros
+        normalized_coeffs_list = [
+            _get_lcm_norm_coeffs([col], "global")
+            for col in transpose(denominators)
+        ]
+        max_len = max(len(coeffs) for coeffs in normalized_coeffs_list)
+        return [
+            coeffs + [0.0] * (max_len - len(coeffs))
+            for coeffs in normalized_coeffs_list
+        ]
+    else:
+        lcm_poly = compute_lcd_from_denominators(denominators)
+        # Extract coefficients as floats
+        lcd_coeffs = [float(c) for c in lcm_poly.all_coeffs()]
+
+        # Normalize by the greatest common divisor of integer coefficients
+        coeff_gcd = gcd(*(int(c) for c in lcd_coeffs if c != 0))
+        normalized_coeffs = [c / coeff_gcd for c in lcd_coeffs]
+    return normalized_coeffs
+
+
+def rjust(list_: list[int | float], width) -> list[int | float]:
+    """Examples:
+    >>> rjust([1, 2, 3], 4)
+    [1, 2, 3, 0]
+    >>> rjust([1, 2, 3, 4, 5], 4)
+    [1, 2, 3, 4]
+    """
+    pad_with = 0 if isinstance(list_[0], int) else 0.0
+
+    return list(list_[:width]) + [pad_with] * max(width - len(list_), 0)
+
+
+def controllable_canonical_form(
+    denominator: list[float] | sp.Poly,
+) -> tuple[NDArray, NDArray]:
+    """Compute the controllable canonical form (A, B) matrices for a given common denominator polynomial.
+
+    Parameters:
+        denominator (list): Coefficients of the denominator polynomial [a_n, ..., a_1, a_0],
+                            where the highest-degree term is first.
+
+    Returns:
+        tuple: (A, B) state-space representation in controllable canonical form.
+
+    Examples:
+        >>> controllable_canonical_form([1, 2, 3])
+        (array([[ 0.,  1.],
+            [-2., -3.]]), array([[0.],
+            [1.]]))
+
+    """
+    if isinstance(denominator, np.ndarray):
+        denominator = list(denominator)
+    elif isinstance(denominator, sp.Poly):
+        denominator = list(
+            np.array(denominator.all_coeffs(), dtype=np.float64)
+        )
+
+    n = len(denominator) - 1  # System order
+    if n < 1:
+        return np.array([0.0]), np.array([0.0])
+    # Construct the A matrix in controllable canonical form
+    A = np.zeros((n, n))
+    A[:-1, 1:] = np.eye(n - 1)  # Upper diagonal ones
+    A[-1, :] = -np.array(
+        denominator[1:]
+    )  # Last row is negative denominator coefficients
+
+    # Construct the B matrix (last column is 1)
+    B = np.zeros((n, 1))
+    B[-1, 0] = 1
+
+    return A, B
+
+
+# Underscores required for positional only arguments (https://github.com/python/mypy/issues/6187)
+@overload
+def tf2ss(
+    __sys: TransferFunction,
+    *,
+    minreal: bool = True,
+) -> tuple[NDArray, NDArray, NDArray, NDArray]: ...
+
+
+@overload
+def tf2ss(
+    __numerators: list[list[list[int | float]]],
+    __denominators: list[list[list[int | float]]],
+    *,
+    minreal: bool = True,
+) -> tuple[NDArray, NDArray, NDArray, NDArray]: ...
+
+
+def tf2ss(
+    *args: TransferFunction | list[list[list[int | float]]],
+    minreal: bool = True,
+) -> tuple[NDArray, NDArray, NDArray, NDArray]:
+    """Convert a MIMO transfer function to a minimal state-space realization.
+
+    Parameters:
+      *args: Either a single TransferFunction object or two lists (numerators and denominators).
+      minreal: Whether to perform minimal realization (default is True).
+
+    Returns:
+      A, B, C, D: Minimal state-space matrices of the MIMO system.
+
+    Examples:
+        >>> sys = TransferFunction([1], [1, 2])
+        >>> A, B, C, D = tf2ss(sys)
+        >>> A.shape[0] > 0
+        True
+
+        >>> numerators = [[[1]], [[1]]]
+        >>> denominators = [[[1, 2]], [[1, 2]]]
+        >>> A, B, C, D = tf2ss(numerators, denominators)
+        >>> A.shape[0] > 0
+        True
+    """
+    if len(args) == 1:
+        sys = args[0]
+        if not isinstance(sys, TransferFunction):
+            raise ValueError(
+                "Single argument must be a TransferFunction object."
+            )
+    elif len(args) == 2:
+        numerators, denominators = args
+        if not (
+            isinstance(numerators, list) and isinstance(denominators, list)
+        ):
+            raise ValueError(
+                "Two arguments must be lists of numerators and denominators."
+            )
+        sys = tf(numerators, denominators)
+    else:
+        raise ValueError(
+            "Invalid number of arguments. Provide either a TransferFunction or numerators and denominators."
+        )
+
+    if sys is None:
+        raise ValueError("Invalid transfer function")
+
+    if minreal:
+        sys = sys.minreal(tol=1e-8)
+
+    # TODO: Apparently, the common_den() method changes the number of outputs of the system (tested for case where noutputs < ninputs)
+    numerators_, denominators_, _ = sys._common_den()
+
+    denominators_ = np.expand_dims(denominators_, axis=0)
+    denominators_ = np.tile(denominators_, (numerators_.shape[0], 1, 1))
+
+    # Remove the last row of numerators if all elements are zero
+    # Seems to be a bug in control.common_den() that adds an extra row
+    def trim_zeros_along_axis(arr, axis, trim="b"):
+        """Trip zeros along the given axis, preserving at last one array."""
+        slices = [slice(None)] * arr.ndim
+        for idx in range(arr.shape[axis]):
+            slices[axis] = idx if trim == "f" else -idx - 1
+            if not np.all(arr[tuple(slices)] == 0):
+                break
+        start = idx if trim == "f" else 0
+        end = arr.shape[axis] - idx if trim == "b" else arr.shape[axis]
+        slices[axis] = slice(start, end)
+        return arr[tuple(slices)]
+
+    numerators_ = trim_zeros_along_axis(numerators_, axis=1, trim="b")
+    numerators_ = np.vectorize(lambda x: sp.Rational(str(x)))(numerators_)
+    denominators_ = np.vectorize(lambda x: sp.Rational(str(x)))(denominators_)
+    n_outputs = len(numerators_)
+    n_inputs = len(numerators_[0])
+    s = sp.Symbol("s")
+    # Step 1: Compute the LCD of all denominators.
+    lcd = compute_lcd_from_denominators(denominators_, s)
+    # Step 2: Get state-space representation (A, B) from the LCD.
+    # A, B_scalar = controllable_canonical_form(lcd)
+    A, B_scalar = state_space_from_poly(lcd)
+    n_states = A.shape[0]
+    C = np.zeros((n_outputs, n_states))
+    D = np.zeros((n_outputs, n_inputs))
+    # Step 3: For each transfer function, compute the adjusted numerator and fill C and D.
+    for i_out in range(n_outputs):
+        for j_in in range(n_inputs):
+            den = (
+                denominators_[i_out][j_in]
+                if denominators_.ndim == 3
+                else denominators_[j_in]
+            )
+            adjusted_num_coeffs = compute_adjusted_num(
+                numerators_[i_out][j_in], lcd, den, s
+            )
+            # In the controllable canonical (companion) form, the output matrix uses the reversed order.
+            C[i_out, :] = rjust(adjusted_num_coeffs[::-1], n_states)
+            # If the degree is less than n_states, assign the constant term to D.
+            if len(adjusted_num_coeffs) < n_states:
+                D[i_out, j_in] = adjusted_num_coeffs[-1]
+            else:
+                D[i_out, j_in] = 0
+    B = np.tile(B_scalar, (1, n_inputs))
+    return A, B, C, D