pySimBlocks 0.1.0__py3-none-any.whl

pySimBlocks/blocks/operators/rate_limiter.py

@@ -0,0 +1,214 @@
+# ******************************************************************************
+#                                  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 RateLimiter(Block):
+    """
+    Discrete-time rate limiter block.
+
+    Summary:
+        Limits the rate of change of the output signal by constraining the
+        maximum allowed increase and decrease per time step.
+
+    Parameters:
+        rising_slope : scalar or array-like, optional
+            Maximum allowed positive rate of change (>= 0).
+        falling_slope : scalar or array-like, optional
+            Maximum allowed negative rate of change (<= 0).
+        initial_output : scalar or array-like, optional
+            Initial output y(-1). If not provided, y(-1) = u(0).
+        sample_time : float, optional
+            Block execution period.
+
+    Inputs:
+        in : array (m,n)
+            Input signal (must be 2D).
+
+    Outputs:
+        out : array (m,n)
+            Rate-limited output signal.
+
+    Notes:
+        - Stateful block.
+        - Direct feedthrough.
+        - Broadcasting rules (to match input shape (m,n)):
+            * scalar (1,1) broadcasts to (m,n)
+            * vector (m,1) broadcasts across columns to (m,n)
+            * matrix (m,n) must match exactly
+        - Once resolved, input shape must remain constant.
+    """
+
+    direct_feedthrough = True
+
+    def __init__(
+        self,
+        name: str,
+        rising_slope: ArrayLike = np.inf,
+        falling_slope: ArrayLike = -np.inf,
+        initial_output: ArrayLike | None = None,
+        sample_time: float | None = None,
+    ):
+        super().__init__(name, sample_time)
+
+        self.inputs["in"] = None
+        self.outputs["out"] = None
+
+        # Raw parameters (2D normalized)
+        self.rising_raw = self._to_2d_array("rising_slope", rising_slope)
+        self.falling_raw = self._to_2d_array("falling_slope", falling_slope)
+        self.y0_raw = None if initial_output is None else self._to_2d_array("initial_output", initial_output)
+
+        # Basic sign constraints (raw)
+        if np.any(self.rising_raw < 0):
+            raise ValueError(f"[{self.name}] rising_slope must be >= 0.")
+        if np.any(self.falling_raw > 0):
+            raise ValueError(f"[{self.name}] falling_slope must be <= 0.")
+
+        # Resolved parameters (broadcasted to input shape once known)
+        self.rising_slope: ArrayLike | None = None
+        self.falling_slope: ArrayLike | None  = None
+        self._resolved_shape: tuple[int, int] | None = None
+
+        # State
+        self.state["y"] = None
+        self.next_state["y"] = None
+
+
+    # --------------------------------------------------------------------------
+    # Public methods
+    # --------------------------------------------------------------------------
+    def initialize(self, t0: float) -> None:
+        u = self.inputs["in"]
+        if u is None:
+            raise RuntimeError(f"[{self.name}] Input 'in' is None at initialization.")
+
+        u = np.asarray(u, dtype=float)
+        if u.ndim != 2:
+            raise ValueError(
+                f"[{self.name}] Input 'in' must be a 2D array. Got ndim={u.ndim} with shape {u.shape}."
+            )
+
+        self._resolve_for_input(u)
+
+        if self.y0_raw is not None:
+            y0 = self._broadcast_param(self.y0_raw, u.shape, "initial_output")
+        else:
+            y0 = u.copy()
+
+        self.state["y"] = y0.copy()
+        self.outputs["out"] = y0.copy()
+
+    # ------------------------------------------------------------------
+    def output_update(self, t: float, dt: float) -> None:
+        u = self.inputs["in"]
+        if u is None:
+            raise RuntimeError(f"[{self.name}] Input 'in' is None.")
+
+        u = np.asarray(u, dtype=float)
+        if u.ndim != 2:
+            raise ValueError(
+                f"[{self.name}] Input 'in' must be a 2D array. Got ndim={u.ndim} with shape {u.shape}."
+            )
+
+        if self.state["y"] is None:
+            raise RuntimeError(f"[{self.name}] RateLimiter not initialized (state 'y' is None).")
+
+        self._resolve_for_input(u)
+
+        y_prev = self.state["y"]
+        if y_prev.shape != u.shape:
+            # extra safety: state shape must match input shape
+            raise ValueError(
+                f"[{self.name}] Internal state shape mismatch: y has shape {y_prev.shape}, input has shape {u.shape}."
+            )
+
+        du = u - y_prev
+        du_min = self.falling_slope * dt
+        du_max = self.rising_slope * dt
+
+        du_limited = np.clip(du, du_min, du_max)
+        self.outputs["out"] = y_prev + du_limited
+
+    # ------------------------------------------------------------------
+    def state_update(self, t: float, dt: float) -> None:
+        self.next_state["y"] = None if self.outputs["out"] is None else self.outputs["out"].copy()
+
+
+    # --------------------------------------------------------------------------
+    # Private methods
+    # --------------------------------------------------------------------------
+    def _broadcast_param(self, p: np.ndarray, target_shape: tuple[int, int], name: str) -> np.ndarray:
+        """
+        Broadcast p to target_shape using explicit rules:
+            - scalar (1,1) -> (m,n)
+            - vector (m,1) -> repeat along columns to (m,n)
+            - matrix (m,n) -> exact match
+        """
+        m, n = target_shape
+
+        if self._is_scalar_2d(p):
+            return np.full(target_shape, float(p[0, 0]), dtype=float)
+
+        if p.ndim == 2 and p.shape[1] == 1 and p.shape[0] == m:
+            if n == 1:
+                return p.astype(float, copy=False)
+            return np.repeat(p.astype(float, copy=False), n, axis=1)
+
+        if p.shape == target_shape:
+            return p.astype(float, copy=False)
+
+        raise ValueError(
+            f"[{self.name}] {name} has incompatible shape {p.shape} for input shape {target_shape}. "
+            f"Allowed: scalar (1,1), vector (m,1), or matrix (m,n)."
+        )
+
+    # ------------------------------------------------------------------
+    def _resolve_for_input(self, u: np.ndarray) -> None:
+        """
+        Resolve (broadcast) slopes and initial_output to match the current input shape.
+        Done once. After that, input shape is fixed.
+        """
+        if u.ndim != 2:
+            raise ValueError(
+                f"[{self.name}] Input 'in' must be a 2D array. Got ndim={u.ndim} with shape {u.shape}."
+            )
+
+        if self._resolved_shape is None:
+            self._resolved_shape = u.shape
+            self.rising_slope = self._broadcast_param(self.rising_raw, u.shape, "rising_slope")
+            self.falling_slope = self._broadcast_param(self.falling_raw, u.shape, "falling_slope")
+
+            # Re-check signs after broadcasting (useful if vector/matrix provided)
+            if np.any(self.rising_slope < 0):
+                raise ValueError(f"[{self.name}] rising_slope must be >= 0.")
+            if np.any(self.falling_slope > 0):
+                raise ValueError(f"[{self.name}] falling_slope must be <= 0.")
+            return
+
+        if u.shape != self._resolved_shape:
+            raise ValueError(
+                f"[{self.name}] Input 'in' shape changed after initialization: "
+                f"expected {self._resolved_shape}, got {u.shape}."
+            )

pySimBlocks/blocks/operators/saturation.py

@@ -0,0 +1,178 @@
+# ******************************************************************************
+#                                  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 Saturation(Block):
+    """
+    Discrete-time saturation operator.
+
+    Summary:
+        Applies element-wise saturation to the input signal by enforcing
+        lower and upper bounds.
+
+    Parameters:
+        u_min : scalar or array-like, optional
+            Lower saturation bound.
+            Accepted: scalar -> (1,1), 1D -> (m,1), 2D -> (m,n).
+            Broadcasting rules are limited and explicit (see Notes).
+        u_max : scalar or array-like, optional
+            Upper saturation bound.
+        sample_time : float, optional
+            Block execution period.
+
+    Inputs:
+        in : array (m,n)
+            Input signal (must be 2D).
+
+    Outputs:
+        out : array (m,n)
+            Saturated output signal.
+
+    Notes:
+        - Stateless block.
+        - Direct feedthrough.
+        - Input must be 2D. No implicit reshape/flatten.
+        - Broadcasting rules for bounds (to match input shape (m,n)):
+            * scalar (1,1) broadcasts to (m,n)
+            * vector (m,1) broadcasts across columns to (m,n)
+            * matrix (m,n) must match exactly
+        - Any other shape mismatch raises ValueError.
+    """
+
+    direct_feedthrough = True
+
+    def __init__(
+        self,
+        name: str,
+        u_min: ArrayLike = -np.inf,
+        u_max: ArrayLike = np.inf,
+        sample_time: float | None = None,
+    ):
+        super().__init__(name, sample_time)
+
+        self.inputs["in"] = None
+        self.outputs["out"] = None
+
+        self.u_min_raw = self._to_2d_array("u_min", u_min)
+        self.u_max_raw = self._to_2d_array("u_max", u_max)
+
+        # These will become "resolved" (broadcasted) once we know input shape
+        self.u_min = None
+        self.u_max = None
+        self._resolved_shape: tuple[int, int] | None = None
+
+
+    # --------------------------------------------------------------------------
+    # Public methods
+    # --------------------------------------------------------------------------
+    def initialize(self, t0: float) -> None:
+        u = self.inputs["in"]
+        if u is None:
+            raise RuntimeError(f"[{self.name}] Input 'in' is None at initialization.")
+
+        u = np.asarray(u, dtype=float)
+        if u.ndim != 2:
+            raise ValueError(
+                f"[{self.name}] Input 'in' must be a 2D array. Got ndim={u.ndim} with shape {u.shape}."
+            )
+
+        self._resolve_bounds_for_input(u)
+        self.outputs["out"] = np.clip(u, self.u_min, self.u_max)
+
+    # ------------------------------------------------------------------
+    def output_update(self, t: float, dt: float) -> None:
+        u = self.inputs["in"]
+        if u is None:
+            raise RuntimeError(f"[{self.name}] Input 'in' is None.")
+
+        u = np.asarray(u, dtype=float)
+        if u.ndim != 2:
+            raise ValueError(
+                f"[{self.name}] Input 'in' must be a 2D array. Got ndim={u.ndim} with shape {u.shape}."
+            )
+
+        self._resolve_bounds_for_input(u)
+        self.outputs["out"] = np.clip(u, self.u_min, self.u_max)
+
+    # ------------------------------------------------------------------
+    def state_update(self, t: float, dt: float) -> None:
+        return  # stateless
+
+
+    # --------------------------------------------------------------------------
+    # Private methods
+    # --------------------------------------------------------------------------
+    def _resolve_bounds_for_input(self, u: np.ndarray) -> None:
+        """
+        Resolve (broadcast) u_min/u_max to match the current input shape.
+        Resolution is done once (first time input is available). After that,
+        input shape is expected to remain constant.
+        """
+        if u.ndim != 2:
+            raise ValueError(
+                f"[{self.name}] Input 'in' must be a 2D array. Got ndim={u.ndim} with shape {u.shape}."
+            )
+
+        if self._resolved_shape is None:
+            self._resolved_shape = u.shape
+
+            self.u_min = self._broadcast_bound(self.u_min_raw, u.shape, "u_min")
+            self.u_max = self._broadcast_bound(self.u_max_raw, u.shape, "u_max")
+
+            if np.any(self.u_min > self.u_max):
+                raise ValueError(f"[{self.name}] u_min must be <= u_max for all components.")
+            return
+
+        # Already resolved => enforce constant input shape
+        if u.shape != self._resolved_shape:
+            raise ValueError(
+                f"[{self.name}] Input 'in' shape changed after bounds were resolved: "
+                f"expected {self._resolved_shape}, got {u.shape}."
+            )
+
+    def _broadcast_bound(self, b: np.ndarray, target_shape: tuple[int, int], name: str) -> np.ndarray:
+        """
+        Broadcast bound b to target_shape using explicit rules.
+        """
+        m, n = target_shape
+
+        # scalar -> full matrix
+        if self._is_scalar_2d(b):
+            return np.full(target_shape, float(b[0, 0]), dtype=float)
+
+        # vector (m,1) -> broadcast across columns
+        if b.ndim == 2 and b.shape[1] == 1 and b.shape[0] == m:
+            if n == 1:
+                return b.astype(float, copy=False)
+            return np.repeat(b.astype(float, copy=False), n, axis=1)
+
+        # matrix -> must match exactly
+        if b.shape == target_shape:
+            return b.astype(float, copy=False)
+
+        raise ValueError(
+            f"[{self.name}] {name} has incompatible shape {b.shape} for input shape {target_shape}. "
+            f"Allowed: scalar (1,1), vector (m,1), or matrix (m,n)."
+        )

pySimBlocks/blocks/operators/sum.py

@@ -0,0 +1,188 @@
+# ******************************************************************************
+#                                  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 pySimBlocks.core.block import Block
+
+
+class Sum(Block):
+    """
+    Multi-input summation block.
+
+    Summary:
+        Computes an element-wise sum/subtraction of multiple input signals.
+
+    Parameters:
+        signs : str
+            Sequence of '+' and '-' defining the sign of each input (e.g. '++-', '+-').
+            If None, defaults to '++' (two inputs).
+        sample_time : float, optional
+            Block execution period.
+
+    Inputs:
+        in1, in2, ..., inN : array (m,n)
+            Input signals (must be 2D).
+            Scalar (1,1) inputs can be broadcast to the common target shape.
+
+    Outputs:
+        out : array (m,n)
+            Element-wise signed sum.
+
+    Notes:
+        - Direct feedthrough.
+        - Stateless.
+        - Shape policy:
+            * all inputs must be 2D
+            * all non-scalar inputs must share exactly the same shape
+            * scalar (1,1) inputs can be broadcast to that shape
+            * no other broadcasting is allowed
+    """
+
+    direct_feedthrough = True
+
+    def __init__(
+        self,
+        name: str,
+        signs: str | None = None,
+        sample_time: float | None = None,
+    ):
+        super().__init__(name, sample_time)
+
+        if signs is None:
+            signs = "++"
+
+        if not isinstance(signs, str):
+            raise TypeError(f"[{self.name}] 'signs' must be a str.")
+
+        if len(signs) == 0:
+            raise ValueError(f"[{self.name}] 'signs' must not be empty.")
+
+        if any(s not in ("+", "-") for s in signs):
+            raise ValueError(f"[{self.name}] 'signs' must contain only '+' or '-'.")
+
+        self.signs = [1.0 if s == "+" else -1.0 for s in signs]
+        self.num_inputs = len(self.signs)
+
+        for i in range(self.num_inputs):
+            self.inputs[f"in{i+1}"] = None
+
+        self.outputs["out"] = None
+
+
+    # --------------------------------------------------------------------------
+    # Public methods
+    # --------------------------------------------------------------------------
+    def initialize(self, t0: float) -> None:
+        """
+        If all inputs are already available, compute output.
+        Otherwise output stays None until first output_update().
+        """
+        if any(self.inputs[f"in{i+1}"] is None for i in range(self.num_inputs)):
+            self.outputs["out"] = None
+            return
+
+        self.outputs["out"] = self._compute_output()
+
+    # ------------------------------------------------------------------
+    def output_update(self, t: float, dt: float) -> None:
+        # Validate presence + 2D constraint
+        arrays = []
+        for i in range(self.num_inputs):
+            key = f"in{i+1}"
+            u = self.inputs[key]
+            if u is None:
+                raise RuntimeError(f"[{self.name}] Input '{key}' is not connected or not set.")
+
+            a = np.asarray(u, dtype=float)
+            if a.ndim != 2:
+                raise ValueError(
+                    f"[{self.name}] Input '{key}' must be a 2D array. Got ndim={a.ndim} with shape {a.shape}."
+                )
+            arrays.append(a)
+
+        self.outputs["out"] = self._compute_output(prevalidated_arrays=arrays)
+
+    # ------------------------------------------------------------------
+    def state_update(self, t: float, dt: float) -> None:
+        return  # stateless
+
+
+    # --------------------------------------------------------------------------
+    # Private methods
+    # --------------------------------------------------------------------------
+    def _resolve_common_shape(self, arrays: list[np.ndarray]) -> tuple[int, int]:
+        """
+        Determine target shape among inputs.
+
+        - Scalars (1,1) are broadcastable
+        - Any non-scalar fixes the target shape
+        - If multiple non-scalars exist, they must all match exactly
+        - If all scalars => target is (1,1)
+        """
+        non_scalar_shapes = {a.shape for a in arrays if not self._is_scalar_2d(a)}
+
+        if len(non_scalar_shapes) == 0:
+            return (1, 1)
+
+        if len(non_scalar_shapes) == 1:
+            return next(iter(non_scalar_shapes))
+
+        raise ValueError(
+            f"[{self.name}] Inconsistent input shapes for Sum: "
+            f"{[a.shape for a in arrays]}. All non-scalar inputs must have the same shape."
+        )
+
+    # ------------------------------------------------------------------
+    def _broadcast_scalar_only(self, arr: np.ndarray, target_shape: tuple[int, int], input_name: str) -> np.ndarray:
+        """
+        Broadcast only scalar (1,1) to target_shape.
+        Non-scalar must match target_shape exactly.
+        """
+        if self._is_scalar_2d(arr):
+            if target_shape == (1, 1):
+                return arr.astype(float, copy=False)
+            return np.full(target_shape, float(arr[0, 0]), dtype=float)
+
+        if arr.shape != target_shape:
+            raise ValueError(
+                f"[{self.name}] Input '{input_name}' shape {arr.shape} is incompatible with target shape {target_shape}. "
+                f"Only scalar (1,1) inputs can be broadcast."
+            )
+        return arr.astype(float, copy=False)
+
+    # ------------------------------------------------------------------
+    def _compute_output(self, prevalidated_arrays: list[np.ndarray] | None = None) -> np.ndarray:
+        """
+        Compute signed element-wise sum with strict scalar-only broadcast.
+        """
+        if prevalidated_arrays is None:
+            arrays = [np.asarray(self.inputs[f"in{i+1}"], dtype=float) for i in range(self.num_inputs)]
+        else:
+            arrays = prevalidated_arrays
+
+        target_shape = self._resolve_common_shape(arrays)
+
+        total = np.zeros(target_shape, dtype=float)
+        for i, (s, a) in enumerate(zip(self.signs, arrays), start=1):
+            a2 = self._broadcast_scalar_only(a, target_shape, input_name=f"in{i}")
+            total += s * a2
+
+        return total