pySimBlocks 0.1.0__py3-none-any.whl

pySimBlocks/blocks/interfaces/external_output.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 pySimBlocks.core.block import Block
+
+
+class ExternalOutput(Block):
+    """
+    External output interface block.
+
+    Summary:
+        Pass-through block for external real-time commands/values.
+
+    Parameters:
+        sample_time: float, optional
+            Execution period of the block. If not specified, the simulator time
+            step is used.
+
+    I/O:
+        Input:
+            in: array (n,1)
+                Value produced by the model. Scalar, (n,), (n,1) accepted.
+        Output:
+            out: array (n,1)
+                Value forwarded to the external side as a column vector (n,1).
+
+    Policy:
+        - Accepts scalar, (n,), (n,1)
+        - Outputs strict (n,1)
+        - Once shape is known, it is frozen (cannot change)
+    """
+    direct_feedthrough = True
+
+    def __init__(self, name: str, sample_time: float | None = None):
+        super().__init__(name, sample_time)
+        self.inputs["in"] = None
+        self.outputs["out"] = 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:
+            self.outputs["out"] = None
+            return
+
+        self.outputs["out"] = self._to_col_vec(u)
+
+    # ------------------------------------------------------------------
+    def output_update(self, t: float, dt: float) -> None:
+        u = self.inputs["in"]
+        if u is None:
+            raise RuntimeError(f"[{self.name}] Missing input 'in'.")
+        self.outputs["out"] = self._to_col_vec(u)
+
+    # ------------------------------------------------------------------
+    def state_update(self, t: float, dt: float) -> None:
+        pass
+
+
+    # --------------------------------------------------------------------------
+    # Private methods
+    # --------------------------------------------------------------------------
+    def _to_col_vec(self, value) -> np.ndarray:
+        arr = np.asarray(value, dtype=float)
+
+        # scalar
+        if arr.ndim == 0:
+            arr = arr.reshape(1, 1)
+
+        # vector (n,)
+        elif arr.ndim == 1:
+            arr = arr.reshape(-1, 1)
+
+        # column (n,1)
+        elif arr.ndim == 2 and arr.shape[1] == 1:
+            pass
+
+        else:
+            raise ValueError(
+                f"[{self.name}] Input 'in' must be scalar, (n,), or (n,1). Got shape {arr.shape}."
+            )
+
+        # Freeze shape
+        if self._resolved_shape is None:
+            self._resolved_shape = arr.shape
+        elif arr.shape != self._resolved_shape:
+            raise ValueError(
+                f"[{self.name}] Input 'in' shape changed: expected {self._resolved_shape}, got {arr.shape}."
+            )
+
+        return arr

pySimBlocks/blocks/observers/__init__.py

@@ -0,0 +1,23 @@
+# ******************************************************************************
+#                                  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.observers.luenberger import Luenberger
+
+all = ["Luenberger"]

pySimBlocks/blocks/observers/luenberger.py

@@ -0,0 +1,175 @@
+# ******************************************************************************
+#                                  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 Luenberger(Block):
+    """
+    Discrete-time Luenberger state observer block.
+
+    Summary:
+        Estimates the state using:
+            y_hat[k] = C x_hat[k]
+            x_hat[k+1] = A x_hat[k] + B u[k] + L (y[k] - y_hat[k])
+
+    Parameters:
+        A : array-like, shape (n, n)
+        B : array-like, shape (n, m)
+        C : array-like, shape (p, n)
+        L : array-like, shape (n, p)
+        x0 : array-like, shape (n, 1), optional
+        sample_time : float, optional
+
+    Inputs:
+        u : array (m, 1)
+        y : array (p, 1)
+
+    Outputs:
+        x_hat : array (n, 1)
+        y_hat : array (p, 1)
+
+    Notes:
+        - Stateful block.
+        - No direct feedthrough.
+        - D matrix intentionally not supported.
+        - Input shapes are frozen once first seen.
+    """
+
+    direct_feedthrough = False
+
+    def __init__(
+        self,
+        name: str,
+        A,
+        B,
+        C,
+        L,
+        x0=None,
+        sample_time: float | None = None,
+    ):
+        super().__init__(name, sample_time)
+
+        # --- Matrices: strict 2D
+        self.A = np.asarray(A, dtype=float)
+        self.B = np.asarray(B, dtype=float)
+        self.C = np.asarray(C, dtype=float)
+        self.L = np.asarray(L, dtype=float)
+
+        for M_name, M in (("A", self.A), ("B", self.B), ("C", self.C), ("L", self.L)):
+            if M.ndim != 2:
+                raise ValueError(f"[{self.name}] {M_name} must be a 2D array. Got shape {M.shape}.")
+
+        n = self.A.shape[0]
+        if self.A.shape[1] != 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 to match A. Got B={self.B.shape}, A={self.A.shape}.")
+
+        if self.C.shape[1] != n:
+            raise ValueError(f"[{self.name}] C must have n columns to match A. Got C={self.C.shape}, A={self.A.shape}.")
+
+        p = self.C.shape[0]
+        m = self.B.shape[1]
+
+        if self.L.shape != (n, p):
+            raise ValueError(f"[{self.name}] L must have shape (n,p) = ({n},{p}). Got {self.L.shape}.")
+
+        self._n = n
+        self._m = m
+        self._p = p
+
+        # --- Initial state x0: strict (n,1), no flatten
+        if x0 is None:
+            x0_arr = np.zeros((n, 1), dtype=float)
+        else:
+            x0_arr = np.asarray(x0, dtype=float)
+            if x0_arr.ndim != 2 or x0_arr.shape != (n, 1):
+                raise ValueError(f"[{self.name}] x0 must have shape ({n},1). Got {x0_arr.shape}.")
+
+        self.state["x_hat"] = x0_arr.copy()
+        self.next_state["x_hat"] = x0_arr.copy()
+
+        # --- Ports
+        self.inputs["u"] = None
+        self.inputs["y"] = None
+        self.outputs["y_hat"] = None
+        self.outputs["x_hat"] = None
+
+        # Freeze input shapes once first seen
+        self._input_shapes = {}
+
+
+    # --------------------------------------------------------------------------
+    # Public methods
+    # --------------------------------------------------------------------------
+    def initialize(self, t0: float) -> None:
+        x_hat = self.state["x_hat"]
+        self.outputs["x_hat"] = x_hat.copy()
+        self.outputs["y_hat"] = self.C @ x_hat
+        self.next_state["x_hat"] = x_hat.copy()
+
+    # ------------------------------------------------------------------
+    def output_update(self, t: float, dt: float) -> None:
+        x_hat = self.state["x_hat"]
+        self.outputs["x_hat"] = x_hat.copy()
+        self.outputs["y_hat"] = self.C @ x_hat
+
+    # ------------------------------------------------------------------
+    def state_update(self, t: float, dt: float) -> None:
+        u = self._require_col_vector("u", self._m)
+        y = self._require_col_vector("y", self._p)
+
+        x_hat = self.state["x_hat"]
+        y_hat = self.C @ x_hat
+
+        self.next_state["x_hat"] = self.A @ x_hat + self.B @ u + self.L @ (y - y_hat)
+
+
+    # --------------------------------------------------------------------------
+    # Private methods
+    # --------------------------------------------------------------------------
+    def _require_col_vector(self, port: str, expected_rows: int) -> np.ndarray:
+        val = self.inputs[port]
+        if val is None:
+            raise RuntimeError(f"[{self.name}] Input '{port}' is not connected or not set.")
+
+        arr = np.asarray(val, dtype=float)
+
+        # Strict: column vector only (no implicit flatten)
+        if arr.ndim != 2 or arr.shape[1] != 1:
+            raise ValueError(f"[{self.name}] Input '{port}' must be a column vector (n,1). Got {arr.shape}.")
+
+        if arr.shape[0] != expected_rows:
+            raise ValueError(
+                f"[{self.name}] Input '{port}' has wrong dimension: expected ({expected_rows},1), got {arr.shape}."
+            )
+
+        # Freeze shape
+        if port not in self._input_shapes:
+            self._input_shapes[port] = arr.shape
+        elif arr.shape != self._input_shapes[port]:
+            raise ValueError(
+                f"[{self.name}] Input '{port}' shape changed: expected {self._input_shapes[port]}, got {arr.shape}."
+            )
+
+        return arr

pySimBlocks/blocks/operators/__init__.py

@@ -0,0 +1,47 @@
+# ******************************************************************************
+#                                  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.operators.dead_zone import DeadZone
+from pySimBlocks.blocks.operators.demux import Demux
+from pySimBlocks.blocks.operators.delay import Delay
+from pySimBlocks.blocks.operators.discrete_derivator import DiscreteDerivator
+from pySimBlocks.blocks.operators.discrete_integrator import DiscreteIntegrator
+from pySimBlocks.blocks.operators.gain import Gain
+from pySimBlocks.blocks.operators.mux import Mux
+from pySimBlocks.blocks.operators.product import Product
+from pySimBlocks.blocks.operators.rate_limiter import RateLimiter
+from pySimBlocks.blocks.operators.saturation import Saturation
+from pySimBlocks.blocks.operators.sum import Sum
+from pySimBlocks.blocks.operators.zero_order_hold import ZeroOrderHold
+
+__all__ = [
+    "DeadZone",
+    "Demux",
+    "Delay",
+    "DiscreteDerivator",
+    "DiscreteIntegrator",
+    "Gain",
+    "Mux",
+    "Product",
+    "RateLimiter",
+    "Saturation",
+    "Sum",
+    "ZeroOrderHold"
+]

pySimBlocks/blocks/operators/algebraic_function.py

@@ -0,0 +1,258 @@
+# ******************************************************************************
+#                                  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 importlib.util
+import inspect
+from pathlib import Path
+from typing import Any, Callable, Dict, List
+
+import numpy as np
+
+from pySimBlocks.core.block import Block
+
+
+class AlgebraicFunction(Block):
+    """
+    User-defined algebraic function block.
+
+    Summary:
+        Stateless block defined by a user-provided Python function:
+            y = g(t, dt, u1, u2, ...)
+
+    Parameters:
+        function : callable
+            User-defined function.
+        input_keys : list[str]
+            Names of input ports.
+        output_keys : list[str]
+            Names of output ports.
+        sample_time : float, optional
+            Block execution period.
+
+    Notes:
+        - Stateless.
+        - Function must return a dict with exactly output_keys.
+        - Inputs/outputs must be 2D numpy arrays (matrices allowed).
+        - Input/output shapes are frozen per port after first resolution.
+    """
+
+    direct_feedthrough = True
+    is_source = False
+
+    def __init__(
+        self,
+        name: str,
+        function: Callable,
+        input_keys: List[str],
+        output_keys: List[str],
+        sample_time: float | None = None,
+    ):
+        super().__init__(name=name, sample_time=sample_time)
+
+        if function is None or not callable(function):
+            raise TypeError(f"[{self.name}] 'function' must be callable.")
+
+        self._func = function
+        self.input_keys = list(input_keys)
+        self.output_keys = list(output_keys)
+
+        if len(self.input_keys) == 0:
+            raise ValueError(f"[{self.name}] input_keys cannot be empty.")
+        if len(self.output_keys) == 0:
+            raise ValueError(f"[{self.name}] output_keys cannot be empty.")
+
+        self.inputs: Dict[str, np.ndarray | None] = {k: None for k in self.input_keys}
+        self.outputs: Dict[str, np.ndarray | None] = {k: None for k in self.output_keys}
+
+        # Shape freeze per port
+        self._in_shapes: Dict[str, tuple[int, int] | None] = {k: None for k in self.input_keys}
+        self._out_shapes: Dict[str, tuple[int, int] | None] = {k: None for k in self.output_keys}
+
+    # --------------------------------------------------------------------------
+    # Class Methods
+    # --------------------------------------------------------------------------
+    @classmethod
+    def adapt_params(cls,
+                     params: Dict[str, Any],
+                     params_dir: Path | None = None) -> Dict[str, Any]:
+        """
+        Adapt parameters from yaml format to class constructor format.
+        Adapt function file and name in a yaml format into callable.
+        """
+        # --- 1. Extract function file and name
+        if params_dir is None:
+            raise ValueError("parameters_dir must be provided for AlgebraicFunction adapter.")
+        try:
+            file_path = params["file_path"]
+            func_name = params["function_name"]
+        except KeyError as e:
+            raise ValueError(
+                f"AlgebraicFunction adapter missing parameter: {e}"
+            )
+
+        # --- 2. Resolve file path (relative to project.yaml directory)
+        path = Path(file_path).expanduser()
+        if not path.is_absolute():
+            path = (params_dir / path).resolve()
+
+        if not path.exists():
+            raise FileNotFoundError(f"Function file not found: {path}")
+
+        # --- 3. Load module
+        spec = importlib.util.spec_from_file_location(path.stem, path)
+        module = importlib.util.module_from_spec(spec)
+        assert spec.loader is not None
+        spec.loader.exec_module(module)
+
+        # --- 4. Extract function
+        try:
+            func = getattr(module, func_name)
+        except AttributeError:
+            raise AttributeError(
+                f"Function '{func_name}' not found in {path}"
+            )
+
+        if not callable(func):
+            raise TypeError(
+                f"'{func_name}' in {path} is not callable"
+            )
+
+        # --- 5. Build adapted parameter dict
+        adapted = dict(params)
+        adapted.pop("file_path", None)
+        adapted.pop("function_name", None)
+        adapted["function"] = func
+
+        return adapted
+
+
+    # --------------------------------------------------------------------------
+    # Public Methods
+    # --------------------------------------------------------------------------
+    def initialize(self, t0: float):
+        self._validate_signature()
+
+        out = self._call_func(t0, 0, **self.inputs)
+        if not isinstance(out, dict):
+            raise RuntimeError(f"[{self.name}] function must return a dict.")
+
+        if set(out.keys()) != set(self.output_keys):
+            raise RuntimeError(
+                f"[{self.name}] output keys mismatch "
+                f"(expected {self.output_keys}, got {list(out.keys())})."
+            )
+        for k in self.output_keys:
+            self.outputs[k] = out[k]
+
+    # ------------------------------------------------------------------
+    def output_update(self, t: float, dt: float):
+        # collect inputs
+        kwargs: Dict[str, np.ndarray] = {}
+        for k in self.input_keys:
+            u = self.inputs[k]
+            if u is None:
+                raise RuntimeError(f"[{self.name}] input '{k}' is not set.")
+            u = np.asarray(u)  # allow array-like injection, but freeze as ndarray 2D
+            self._check_freeze_shape("input", k, u, self._in_shapes)
+            kwargs[k] = u
+
+        # call function
+        out = self._call_func(t, dt, **kwargs)
+
+
+
+        # assign outputs
+        for k in self.output_keys:
+            y = out[k]
+            y = np.asarray(y)
+            self._check_freeze_shape("output", k, y, self._out_shapes)
+            self.outputs[k] = y
+
+    # ------------------------------------------------------------------
+    def state_update(self, t: float, dt: float):
+        return  # stateless
+
+
+    # --------------------------------------------------------------------------
+    # Private Methods
+    # --------------------------------------------------------------------------
+    def _call_func(self, t: float, dt: float, **kwargs) -> Dict[str, np.ndarray]:
+        try:
+            out =  self._func(t, dt, **kwargs)
+        except Exception as e:
+            raise RuntimeError(f"[{self.name}] function call error: {e}\n"
+                               f"Must always return a dict with output keys: {self.output_keys}")
+
+        if not isinstance(out, dict):
+            raise RuntimeError(f"[{self.name}] function must return a dict.")
+
+        if not set(self.output_keys).issubset(out.keys()):
+            raise RuntimeError(
+                f"[{self.name}] missing output keys "
+                f"(expected {self.output_keys}, got {list(out.keys())})."
+            )
+
+        for k in self.output_keys:
+            y = out[k]
+            if not isinstance(y, np.ndarray):
+                raise RuntimeError(f"{self.name}: output '{k}' is not a numpy array")
+            if y.ndim > 2:
+                raise RuntimeError(f"{self.name}: output '{k}' must be at most 2D (got shape {y.shape})")
+        return out
+
+    # ------------------------------------------------------------------
+    def _validate_signature(self) -> None:
+        sig = inspect.signature(self._func)
+        params = list(sig.parameters.values())
+
+        if len(params) < 2:
+            raise ValueError(f"[{self.name}] function must have at least arguments (t, dt).")
+
+        if params[0].name != "t" or params[1].name != "dt":
+            raise ValueError(f"[{self.name}] first arguments must be (t, dt).")
+
+        # no *args / **kwargs / defaults
+        for p in params:
+            if p.kind not in (inspect.Parameter.POSITIONAL_OR_KEYWORD,):
+                raise ValueError(f"[{self.name}] *args and **kwargs are not allowed.")
+
+        declared = [p.name for p in params[2:]]
+        if set(declared) != set(self.input_keys):
+            raise ValueError(
+                f"[{self.name}] function arguments mismatch.\n"
+                f"Expected inputs: {self.input_keys}\n"
+                f"Function declares: {declared}"
+            )
+
+    # ------------------------------------------------------------------
+    def _check_freeze_shape(self, which: str, key: str, arr: np.ndarray, store: Dict[str, tuple[int, int] | None]) -> None:
+        if not isinstance(arr, np.ndarray):
+            raise TypeError(f"[{self.name}] {which} '{key}' is not a numpy array.")
+        if arr.ndim != 2:
+            raise ValueError(f"[{self.name}] {which} '{key}' must be a 2D array. Got shape {arr.shape}.")
+
+        if store[key] is None:
+            store[key] = arr.shape
+            return
+
+        if arr.shape != store[key]:
+            raise ValueError(
+                f"[{self.name}] {which} '{key}' shape changed: expected {store[key]}, got {arr.shape}."
+            )