pySimBlocks 0.1.0__py3-none-any.whl

pySimBlocks/blocks/sources/sinusoidal.py

@@ -0,0 +1,113 @@
+# ******************************************************************************
+#                                  pySimBlocks
+#                     Copyright (c) 2026 Université de Lille & INRIA
+# ******************************************************************************
+#  This program is free software: you can redistribute it and/or modify it
+#  under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or (at your
+#  option) any later version.
+#
+#  This program is distributed in the hope that it will be useful, but WITHOUT
+#  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+#  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
+#  for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+# ******************************************************************************
+#  Authors: see Authors.txt
+# ******************************************************************************
+
+import numpy as np
+from numpy.typing import ArrayLike
+from pySimBlocks.core.block_source import BlockSource
+
+
+class Sinusoidal(BlockSource):
+    """
+    Multi-dimensional sinusoidal signal source block (Option B).
+
+    Summary:
+        Generates sinusoidal signals element-wise on a 2D output array:
+            y(t) = amplitude * sin(2*pi*frequency*t + phase) + offset
+
+        Parameters may be scalars, vectors, or matrices. Only scalar-to-shape
+        broadcasting is allowed; all non-scalar parameters must share the same
+        shape.
+
+    Parameters (overview):
+        amplitude : float or array-like
+            Sinusoidal amplitude.
+        frequency : float or array-like
+            Sinusoidal frequency in Hertz.
+        phase : float or array-like, optional
+            Phase shift in radians.
+        offset : float or array-like, optional
+            Constant offset added to the signal.
+        sample_time : float, optional
+            Block execution period.
+
+    Outputs:
+        out : sinusoidal output signal (2D ndarray)
+
+    Notes:
+        - Stateless.
+        - Normalization:
+            scalar -> (1,1), 1D -> (n,1), 2D -> (m,n)
+        - Broadcasting:
+            Only (1,1) scalars are broadcast to the common shape.
+            No NumPy broadcasting beyond that.
+        - No implicit flattening is performed.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        amplitude: ArrayLike,
+        frequency: ArrayLike,
+        offset: ArrayLike = 0.0,
+        phase: ArrayLike = 0.0,
+        sample_time: float | None = None,
+    ):
+        super().__init__(name, sample_time)
+
+        A = self._to_2d_array("amplitude", amplitude, dtype=float)
+        F = self._to_2d_array("frequency", frequency, dtype=float)
+        O = self._to_2d_array("offset", offset, dtype=float)
+        P = self._to_2d_array("phase", phase, dtype=float)
+
+        target_shape = self._resolve_common_shape({
+            "amplitude": A,
+            "frequency": F,
+            "offset": O,
+            "phase": P,
+        })
+
+        self.amplitude = self._broadcast_scalar_only("amplitude", A, target_shape)
+        self.frequency = self._broadcast_scalar_only("frequency", F, target_shape)
+        self.offset = self._broadcast_scalar_only("offset", O, target_shape)
+        self.phase = self._broadcast_scalar_only("phase", P, target_shape)
+
+        self.outputs["out"] = np.zeros(target_shape, dtype=float)
+
+
+    # --------------------------------------------------------------------------
+    # Public methods
+    # --------------------------------------------------------------------------
+    def initialize(self, t0: float) -> None:
+        self._compute_output(t0)
+
+    # ------------------------------------------------------------------
+    def output_update(self, t: float, dt: float) -> None:
+        self._compute_output(t)
+
+
+    # --------------------------------------------------------------------------
+    # Private methods
+    # --------------------------------------------------------------------------
+    def _compute_output(self, t: float) -> None:
+        self.outputs["out"] = (
+            self.amplitude
+            * np.sin(2.0 * np.pi * self.frequency * t + self.phase)
+            + self.offset
+        )

pySimBlocks/blocks/sources/step.py

@@ -0,0 +1,138 @@
+# ******************************************************************************
+#                                  pySimBlocks
+#                     Copyright (c) 2026 Université de Lille & INRIA
+# ******************************************************************************
+#  This program is free software: you can redistribute it and/or modify it
+#  under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or (at your
+#  option) any later version.
+#
+#  This program is distributed in the hope that it will be useful, but WITHOUT
+#  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+#  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
+#  for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+# ******************************************************************************
+#  Authors: see Authors.txt
+# ******************************************************************************
+
+import numpy as np
+from numpy.typing import ArrayLike
+from pySimBlocks.core.block_source import BlockSource
+
+
+class Step(BlockSource):
+    """
+    Step signal source block.
+
+    Summary:
+        Generates a step signal that switches from an initial value to a final
+        value at a specified time.
+
+    Parameters (overview):
+        value_before : float or array-like
+            Output value before the step time. Scalar, vector, or matrix.
+        value_after : float or array-like
+            Output value after the step time. Scalar, vector, or matrix.
+        start_time : float
+            Time at which the step occurs.
+        sample_time : float, optional
+            Block execution period.
+
+    I/O:
+        Outputs:
+            out : step output signal.
+
+    Notes:
+        - The block has no internal state.
+        - Signals are normalized to 2D arrays:
+            scalar -> (1,1), 1D -> (n,1), 2D -> (m,n).
+        - If one value is scalar (1,1) and the other is not, scalar is broadcast
+          to match the other shape.
+        - EPS compensates floating-point rounding to ensure consistent behavior
+          on discrete time grids.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        value_before: ArrayLike = 0.0,
+        value_after: ArrayLike = 1.0,
+        start_time: float = 1.0,
+        sample_time: float | None = None,
+        eps: float = 1e-12,
+    ):
+        super().__init__(name, sample_time)
+
+        vb = self._to_2d_array("value_before", value_before, dtype=float)
+        va = self._to_2d_array("value_after", value_after, dtype=float)
+
+        vb, va = self._match_shapes_with_scalar_broadcast(vb, va)
+
+        # --- Validate start_time ---
+        if not isinstance(start_time, (float, int)):
+            raise TypeError(f"[{self.name}] start_time must be a float or int.")
+        self.start_time = float(start_time)
+
+        self.value_before = vb
+        self.value_after = va
+
+        self.outputs["out"] = None
+        self.EPS = float(eps)
+
+
+    # --------------------------------------------------------------------------
+    # Public methods
+    # --------------------------------------------------------------------------
+    def initialize(self, t0: float) -> None:
+        self.outputs["out"] = (
+            self.value_before.copy()
+            if t0 < self.start_time - self.EPS
+            else self.value_after.copy()
+        )
+
+    # ------------------------------------------------------------------
+    def output_update(self, t: float, dt: float) -> None:
+        self.outputs["out"] = (
+            self.value_before.copy()
+            if t < self.start_time - self.EPS
+            else self.value_after.copy()
+        )
+
+
+    # --------------------------------------------------------------------------
+    # Private methods
+    # --------------------------------------------------------------------------
+    @staticmethod
+    def _is_scalar_2d(arr: np.ndarray) -> bool:
+        return arr.shape == (1, 1)
+
+    # ------------------------------------------------------------------
+    def _match_shapes_with_scalar_broadcast(
+        self,
+        a: np.ndarray,
+        b: np.ndarray,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        """
+        If shapes differ:
+          - allow scalar (1,1) to broadcast to the other's shape
+          - otherwise raise ValueError
+        """
+        if a.shape == b.shape:
+            return a, b
+
+        a_is_scalar = self._is_scalar_2d(a)
+        b_is_scalar = self._is_scalar_2d(b)
+
+        if a_is_scalar and not b_is_scalar:
+            return np.full(b.shape, float(a[0, 0])), b
+
+        if b_is_scalar and not a_is_scalar:
+            return a, np.full(a.shape, float(b[0, 0]))
+
+        raise ValueError(
+            f"[{self.name}] 'value_before' and 'value_after' must have compatible shapes. "
+            f"Got {a.shape} vs {b.shape}. Only scalar-to-shape broadcasting is allowed."
+        )

pySimBlocks/blocks/sources/white_noise.py

@@ -0,0 +1,107 @@
+# ******************************************************************************
+#                                  pySimBlocks
+#                     Copyright (c) 2026 Université de Lille & INRIA
+# ******************************************************************************
+#  This program is free software: you can redistribute it and/or modify it
+#  under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or (at your
+#  option) any later version.
+#
+#  This program is distributed in the hope that it will be useful, but WITHOUT
+#  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+#  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
+#  for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+# ******************************************************************************
+#  Authors: see Authors.txt
+# ******************************************************************************
+
+import numpy as np
+from numpy.typing import ArrayLike
+from pySimBlocks.core.block_source import BlockSource
+
+
+class WhiteNoise(BlockSource):
+    """
+    Multi-dimensional Gaussian white noise source block (Option B).
+
+    Summary:
+        Generates independent Gaussian noise samples at each simulation step,
+        element-wise on a 2D output array:
+            y = mean + std * N(0,1)
+
+        Parameters may be scalars, vectors, or matrices. Only scalar-to-shape
+        broadcasting is allowed; all non-scalar parameters must share the same
+        shape.
+
+    Parameters (overview):
+        mean : float or array-like, optional
+            Mean value of the noise.
+        std : float or array-like, optional
+            Standard deviation of the noise (must be >= 0 element-wise).
+        seed : int, optional
+            Random seed for reproducibility.
+        sample_time : float, optional
+            Block execution period.
+
+    Outputs:
+        out : noise output signal (2D ndarray)
+
+    Notes:
+        - Stateless (but uses an internal RNG).
+        - Normalization:
+            scalar -> (1,1), 1D -> (n,1), 2D -> (m,n)
+        - Broadcasting:
+            Only (1,1) scalars are broadcast to the common shape.
+            No NumPy broadcasting beyond that.
+        - No implicit flattening is performed.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        mean: ArrayLike = 0.0,
+        std: ArrayLike = 1.0,
+        seed: int | None = None,
+        sample_time: float | None = None,
+    ):
+        super().__init__(name, sample_time)
+
+        M = self._to_2d_array("mean", mean, dtype=float)
+        S = self._to_2d_array("std", std, dtype=float)
+
+        target_shape = self._resolve_common_shape({
+            "mean": M,
+            "std": S,
+        })
+
+        self.mean = self._broadcast_scalar_only("mean", M, target_shape)
+        self.std = self._broadcast_scalar_only("std", S, target_shape)
+
+        # Validate std >= 0 element-wise
+        if np.any(self.std < 0.0):
+            raise ValueError(f"[{self.name}] std must be >= 0 (element-wise).")
+
+        self.rng = np.random.default_rng(seed)
+
+        self.outputs["out"] = np.zeros(target_shape, dtype=float)
+
+
+    # --------------------------------------------------------------------------
+    # Public methods
+    # --------------------------------------------------------------------------
+    def initialize(self, t0: float) -> None:
+        self.outputs["out"] = self._draw()
+
+    # ------------------------------------------------------------------
+    def output_update(self, t: float, dt: float) -> None:
+        self.outputs["out"] = self._draw()
+
+
+    # --------------------------------------------------------------------------
+    # Private methods
+    # --------------------------------------------------------------------------
+    def _draw(self) -> np.ndarray:
+        return self.mean + self.std * self.rng.standard_normal(self.mean.shape)

pySimBlocks/blocks/systems/__init__.py

@@ -0,0 +1,27 @@
+# ******************************************************************************
+#                                  pySimBlocks
+#                     Copyright (c) 2026 Université de Lille & INRIA
+# ******************************************************************************
+#  This program is free software: you can redistribute it and/or modify it
+#  under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or (at your
+#  option) any later version.
+#
+#  This program is distributed in the hope that it will be useful, but WITHOUT
+#  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+#  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
+#  for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+# ******************************************************************************
+#  Authors: see Authors.txt
+# ******************************************************************************
+
+from pySimBlocks.blocks.systems.linear_state_space import LinearStateSpace
+from pySimBlocks.blocks.systems.polytopic_state_space import PolytopicStateSpace
+
+__all__ = [
+    "LinearStateSpace",
+    "PolytopicStateSpace",
+]

pySimBlocks/blocks/systems/linear_state_space.py

@@ -0,0 +1,180 @@
+# ******************************************************************************
+#                                  pySimBlocks
+#                     Copyright (c) 2026 Université de Lille & INRIA
+# ******************************************************************************
+#  This program is free software: you can redistribute it and/or modify it
+#  under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation, either version 3 of the License, or (at your
+#  option) any later version.
+#
+#  This program is distributed in the hope that it will be useful, but WITHOUT
+#  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+#  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
+#  for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with this program.  If not, see <https://www.gnu.org/licenses/>.
+# ******************************************************************************
+#  Authors: see Authors.txt
+# ******************************************************************************
+
+import numpy as np
+from numpy.typing import ArrayLike
+from pySimBlocks.core.block import Block
+
+
+class LinearStateSpace(Block):
+    """
+    Discrete-time linear state-space system block.
+
+    Summary:
+        Implements a discrete-time linear state-space system without direct
+        feedthrough, defined by state and output equations.
+
+    Parameters (overview):
+        A : array-like
+            State transition matrix.
+        B : array-like
+            Input matrix.
+        C : array-like
+            Output matrix.
+        x0 : array-like, optional
+            Initial state vector.
+        sample_time : float, optional
+            Block execution period.
+
+    I/O:
+        Inputs:
+            u : input vector.
+        Outputs:
+            y : output vector.
+            x : state vector.
+
+    Notes:
+        - The system is strictly proper (no direct feedthrough).
+        - The block has internal state.
+        - Matrix D is intentionally not supported to avoid algebraic loops.
+        - The state is updated once per simulation step.
+    """
+
+    direct_feedthrough = False
+
+    def __init__(
+        self,
+        name: str,
+        A: ArrayLike,
+        B: ArrayLike,
+        C: ArrayLike,
+        x0: ArrayLike | None = None,
+        sample_time: float | None = None,
+    ):
+        super().__init__(name, sample_time)
+
+        self.A = np.asarray(A, dtype=float)
+        self.B = np.asarray(B, dtype=float)
+        self.C = np.asarray(C, dtype=float)
+
+        # --- basic matrix checks
+        if self.A.ndim != 2:
+            raise ValueError(f"[{self.name}] A must be 2D. Got shape {self.A.shape}.")
+        if self.B.ndim != 2:
+            raise ValueError(f"[{self.name}] B must be 2D. Got shape {self.B.shape}.")
+        if self.C.ndim != 2:
+            raise ValueError(f"[{self.name}] C must be 2D. Got shape {self.C.shape}.")
+
+        n = self.A.shape[0]
+        if self.A.shape != (n, n):
+            raise ValueError(f"[{self.name}] A must be square (n,n). Got {self.A.shape}.")
+
+        if self.B.shape[0] != n:
+            raise ValueError(
+                f"[{self.name}] B must have n rows. A is {self.A.shape}, B is {self.B.shape}."
+            )
+
+        if self.C.shape[1] != n:
+            raise ValueError(
+                f"[{self.name}] C must have n columns. A is {self.A.shape}, C is {self.C.shape}."
+            )
+
+        self._n = n
+        self._m = self.B.shape[1]
+        self._p = self.C.shape[0]
+
+        # --- initial state x0
+        if x0 is None:
+            x0_arr = np.zeros((n, 1), dtype=float)
+        else:
+            x0_arr = np.asarray(x0, dtype=float)
+            if x0_arr.ndim == 0:
+                # scalar x0 is not acceptable for n>1
+                x0_arr = x0_arr.reshape(1, 1)
+            elif x0_arr.ndim == 1:
+                x0_arr = x0_arr.reshape(-1, 1)
+            elif x0_arr.ndim == 2:
+                pass
+            else:
+                raise ValueError(f"[{self.name}] x0 must be 1D or 2D. Got shape {x0_arr.shape}.")
+
+            if x0_arr.shape != (n, 1):
+                raise ValueError(f"[{self.name}] x0 must have shape ({n}, 1). Got {x0_arr.shape}.")
+
+        self.state["x"] = x0_arr.copy()
+        self.next_state["x"] = x0_arr.copy()
+
+        # ports
+        self.inputs["u"] = None
+        self.outputs["y"] = None
+        self.outputs["x"] = None
+
+
+    # --------------------------------------------------------------------------
+    # Public methods
+    # --------------------------------------------------------------------------
+    def initialize(self, t0: float) -> None:
+        x = self.state["x"]
+        self.outputs["y"] = self.C @ x
+        self.outputs["x"] = x.copy()
+        self.next_state["x"] = x.copy()
+
+    # ------------------------------------------------------------------
+    def output_update(self, t: float, dt: float) -> None:
+        x = self.state["x"]
+        self.outputs["y"] = self.C @ x
+        self.outputs["x"] = x.copy()
+
+    # ------------------------------------------------------------------
+    def state_update(self, t: float, dt: float) -> None:
+        u = self.inputs["u"]
+        if u is None:
+            raise RuntimeError(f"[{self.name}] Input 'u' is not connected or not set.")
+
+        u_vec = self._to_col_vec("u", u, self._m)
+        x = self.state["x"]
+
+        self.next_state["x"] = self.A @ x + self.B @ u_vec
+
+
+    # --------------------------------------------------------------------------
+    # Private methods
+    # --------------------------------------------------------------------------
+    def _to_col_vec(self, name: str, value: ArrayLike, expected_rows: int) -> np.ndarray:
+        arr = np.asarray(value, dtype=float)
+
+        if arr.ndim == 0:
+            arr = arr.reshape(1, 1)
+        elif arr.ndim == 1:
+            arr = arr.reshape(-1, 1)
+        elif arr.ndim == 2:
+            pass
+        else:
+            raise ValueError(f"[{self.name}] {name} must be 1D or 2D. Got shape {arr.shape}.")
+
+        if arr.shape[1] != 1:
+            raise ValueError(f"[{self.name}] {name} must be a column vector (k,1). Got {arr.shape}.")
+
+        if arr.shape[0] != expected_rows:
+            raise ValueError(
+                f"[{self.name}] {name} must have shape ({expected_rows},1). Got {arr.shape}."
+            )
+
+        return arr