pySimBlocks 0.1.0__py3-none-any.whl

pySimBlocks/blocks/sources/constant.py

@@ -0,0 +1,82 @@
+# ******************************************************************************
+#                                  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 Constant(BlockSource):
+    """
+    Constant signal source block.
+
+    Summary:
+        Generates a constant output signal with a fixed value over time.
+        The output does not depend on time or any input signal.
+
+    Parameters (overview):
+        value : float or array-like
+            Constant output value. Can be scalar, vector, or matrix.
+        sample_time : float, optional
+            Block execution period.
+
+    I/O:
+        Inputs:
+            (none)
+        Outputs:
+            out : constant output signal.
+
+    Notes:
+        - The block has no internal state.
+        - The output value is held constant for the entire simulation.
+        - Scalar values are normalized to shape (1,1).
+        - 1D values are normalized to column vectors (n,1).
+        - 2D values are preserved as matrices (m,n).
+    """
+
+    def __init__(
+        self,
+        name: str,
+        value: ArrayLike = 1.0,
+        sample_time: float | None = None,
+    ):
+        super().__init__(name, sample_time)
+
+        # Accept numeric scalars and array-like
+        if not isinstance(value, (list, tuple, np.ndarray, float, int)):
+            raise TypeError(
+                f"[{self.name}] Constant 'value' must be numeric or array-like."
+            )
+
+        arr = self._to_2d_array("value", value, dtype=float)
+
+        self.value = arr
+        self.outputs["out"] = arr.copy()
+
+
+    # --------------------------------------------------------------------------
+    # Public methods
+    # --------------------------------------------------------------------------
+    def initialize(self, t0: float) -> None:
+        self.outputs["out"] = self.value.copy()
+
+    # ------------------------------------------------------------------
+    def output_update(self, t: float, dt: float) -> None:
+        self.outputs["out"] = self.value.copy()

pySimBlocks/blocks/sources/file_source.py

@@ -0,0 +1,294 @@
+# ******************************************************************************
+#                                  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 pathlib import Path
+from typing import Any, Dict
+
+import numpy as np
+
+from pySimBlocks.core.block_source import BlockSource
+
+
+class FileSource(BlockSource):
+    """
+    Source block that plays samples loaded from a file.
+
+    Supported file types:
+        - npz: load an array from a key in a .npz archive (key mandatory)
+        - npy: load an array from a .npy file (no key)
+        - csv: load one numeric column by name (key=column name)
+
+    Output policy:
+        - loaded data must be 1D or 2D
+        - each simulation step emits one row as a column vector
+        - when the end is reached:
+            * repeat=True  -> restart from first sample
+            * repeat=False -> output zeros
+    """
+
+    VALID_FILE_TYPES = {"npz", "npy", "csv"}
+
+    def __init__(
+        self,
+        name: str,
+        file_path: str,
+        key: str | None = None,
+        repeat: bool = False,
+        use_time: bool = False,
+        sample_time: float | None = None,
+    ):
+        super().__init__(name, sample_time)
+
+        self.file_path = str(file_path)
+        self.file_type = self._infer_file_type(self.file_path)
+        self.key = key
+        self.repeat = self._to_bool(repeat, "repeat")
+        self.use_time = self._to_bool(use_time, "use_time")
+
+        if self.use_time and self.file_type == "npy":
+            raise ValueError(
+                f"[{self.name}] use_time is supported only for NPZ and CSV inputs."
+            )
+        if self.use_time and self.repeat:
+            raise ValueError(
+                f"[{self.name}] repeat cannot be used when use_time=True."
+            )
+
+        self._time: np.ndarray | None = None
+        self._samples = self._load_samples()
+        self._index = 0
+        self._output_shape = (self._samples.shape[1], 1)
+
+        self.outputs["out"] = np.zeros(self._output_shape, dtype=float)
+
+    # --------------------------------------------------------------------------
+    # Class Methods
+    # --------------------------------------------------------------------------
+    @classmethod
+    def adapt_params(
+        cls,
+        params: Dict[str, Any],
+        params_dir: Path | None = None,
+    ) -> Dict[str, Any]:
+        """
+        Resolve relative file_path against parameters directory when provided.
+        """
+        adapted = dict(params)
+        file_path = adapted.get("file_path")
+        if file_path is None:
+            return adapted
+
+        path = Path(file_path).expanduser()
+        if not path.is_absolute() and params_dir is not None:
+            path = (params_dir / path).resolve()
+
+        adapted["file_path"] = str(path)
+        # Backward compatibility with older models that still contain file_type
+        adapted.pop("file_type", None)
+        return adapted
+
+    # --------------------------------------------------------------------------
+    # Public methods
+    # --------------------------------------------------------------------------
+    def initialize(self, t0: float) -> None:
+        if self.use_time:
+            self.outputs["out"] = self._current_output_at_time(t0)
+        else:
+            self._index = 0
+            self.outputs["out"] = self._current_output()
+
+    # ------------------------------------------------------------------
+    def output_update(self, t: float, dt: float) -> None:
+        if self.use_time:
+            self.outputs["out"] = self._current_output_at_time(t)
+        else:
+            self.outputs["out"] = self._current_output()
+            self._index += 1
+
+    # ------------------------------------------------------------------
+    def state_update(self, t: float, dt: float) -> None:
+        pass
+
+    # --------------------------------------------------------------------------
+    # Private methods
+    # --------------------------------------------------------------------------
+    def _load_samples(self) -> np.ndarray:
+        path = Path(self.file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"[{self.name}] File not found: {path}")
+
+        if self.file_type == "npz":
+            arr, time = self._load_npz(path)
+        elif self.file_type == "npy":
+            arr, time = self._load_npy(path)
+        else:
+            arr, time = self._load_csv(path)
+
+        if arr.ndim == 1:
+            arr = arr.reshape(-1, 1)
+        elif arr.ndim != 2:
+            raise ValueError(
+                f"[{self.name}] Loaded data must be 1D or 2D. Got shape {arr.shape}."
+            )
+
+        if arr.shape[0] == 0:
+            raise ValueError(f"[{self.name}] Loaded file contains no samples.")
+
+        self._time = time
+
+        return arr.astype(float, copy=False)
+
+    # ------------------------------------------------------------------
+    def _load_npz(self, path: Path) -> tuple[np.ndarray, np.ndarray | None]:
+        with np.load(path) as data:
+            keys = list(data.files)
+            if len(keys) == 0:
+                raise ValueError(f"[{self.name}] NPZ archive contains no arrays.")
+
+            selected_key = self.key
+            if not selected_key:
+                raise ValueError(
+                    f"[{self.name}] key is mandatory for NPZ input."
+                )
+
+            if selected_key not in data:
+                raise KeyError(
+                    f"[{self.name}] key '{selected_key}' not found in NPZ. "
+                    f"Available keys: {keys}"
+                )
+
+            arr = np.asarray(data[selected_key], dtype=float)
+            time = None
+            if self.use_time:
+                if "time" not in data:
+                    raise KeyError(
+                        f"[{self.name}] use_time=True requires NPZ key 'time'."
+                    )
+                time = np.asarray(data["time"], dtype=float).reshape(-1)
+                self._validate_time(time, arr.shape[0])
+            return arr, time
+
+    # ------------------------------------------------------------------
+    def _load_npy(self, path: Path) -> tuple[np.ndarray, np.ndarray | None]:
+        if self.key not in (None, ""):
+            raise ValueError(
+                f"[{self.name}] key is not used for NPY input."
+            )
+        return np.asarray(np.load(path), dtype=float), None
+
+    # ------------------------------------------------------------------
+    def _load_csv(self, path: Path) -> tuple[np.ndarray, np.ndarray | None]:
+        if not self.key:
+            raise ValueError(
+                f"[{self.name}] key is mandatory for CSV input and must be a column name."
+            )
+
+        arr = np.genfromtxt(path, delimiter=",", names=True, dtype=float)
+
+        if arr.size == 0:
+            raise ValueError(f"[{self.name}] CSV file is empty.")
+        if arr.dtype.names is None:
+            raise ValueError(
+                f"[{self.name}] CSV must contain a header row with column names."
+            )
+        if self.key not in arr.dtype.names:
+            raise KeyError(
+                f"[{self.name}] column '{self.key}' not found in CSV. "
+                f"Available columns: {list(arr.dtype.names)}"
+            )
+
+        col = np.asarray(arr[self.key], dtype=float).reshape(-1, 1)
+        if np.isnan(col).any():
+            raise ValueError(
+                f"[{self.name}] CSV column '{self.key}' contains non-numeric or missing values."
+            )
+        time = None
+        if self.use_time:
+            if "time" not in arr.dtype.names:
+                raise KeyError(
+                    f"[{self.name}] use_time=True requires CSV column 'time'."
+                )
+            time = np.asarray(arr["time"], dtype=float).reshape(-1)
+            self._validate_time(time, col.shape[0])
+        return col, time
+
+    # ------------------------------------------------------------------
+    def _to_bool(self, value: bool | str, name: str) -> bool:
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, str):
+            lowered = value.strip().lower()
+            if lowered in {"true", "1", "yes"}:
+                return True
+            if lowered in {"false", "0", "no"}:
+                return False
+        raise ValueError(f"[{self.name}] '{name}' must be a bool.")
+
+    # ------------------------------------------------------------------
+    def _infer_file_type(self, file_path: str) -> str:
+        ext = Path(file_path).suffix.lower().lstrip(".")
+        if ext not in self.VALID_FILE_TYPES:
+            raise ValueError(
+                f"[{self.name}] Unsupported file extension '.{ext}'. "
+                f"Supported extensions: {sorted(self.VALID_FILE_TYPES)}"
+            )
+        return ext
+
+    # ------------------------------------------------------------------
+    def _current_output(self) -> np.ndarray:
+        n = self._samples.shape[0]
+        if self._index < n:
+            idx = self._index
+        elif self.repeat:
+            idx = self._index % n
+        else:
+            return np.zeros(self._output_shape, dtype=float)
+
+        row = self._samples[idx]
+        return np.asarray(row, dtype=float).reshape(-1, 1)
+
+    # ------------------------------------------------------------------
+    def _current_output_at_time(self, t: float) -> np.ndarray:
+        if self._time is None:
+            raise RuntimeError(
+                f"[{self.name}] Internal error: use_time=True but time data is missing."
+            )
+
+        idx = int(np.searchsorted(self._time, t, side="right") - 1)
+        if idx < 0:
+            idx = 0
+
+        row = self._samples[idx]
+        return np.asarray(row, dtype=float).reshape(-1, 1)
+
+    # ------------------------------------------------------------------
+    def _validate_time(self, time: np.ndarray, n_samples: int) -> None:
+        if time.ndim != 1:
+            raise ValueError(f"[{self.name}] time must be a 1D array.")
+        if time.shape[0] != n_samples:
+            raise ValueError(
+                f"[{self.name}] time length ({time.shape[0]}) must match number of samples ({n_samples})."
+            )
+        if np.isnan(time).any():
+            raise ValueError(f"[{self.name}] time contains NaN values.")
+        if not np.all(np.diff(time) > 0.0):
+            raise ValueError(
+                f"[{self.name}] time must be strictly increasing."
+            )

pySimBlocks/blocks/sources/function_source.py

@@ -0,0 +1,197 @@
+# ******************************************************************************
+#                                  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_source import BlockSource
+
+
+class FunctionSource(BlockSource):
+    """
+    User-defined source block with no inputs.
+
+    Summary:
+        Computes:
+            y = f(t, dt)
+
+    Notes:
+        - The function must accept exactly (t, dt).
+        - Function must return a dict with keys matching output_keys.
+        - Each output value can be scalar, 1D, or 2D (internally normalized to 2D).
+        - Output shape is frozen independently for each output key.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        function: Callable,
+        output_keys: List[str] | None = None,
+        sample_time: float | None = None,
+    ):
+        super().__init__(name, sample_time)
+
+        if function is None or not callable(function):
+            raise TypeError(f"[{self.name}] 'function' must be callable.")
+
+        self._func = function
+        self.output_keys = ["out"] if output_keys is None else list(output_keys)
+        if len(self.output_keys) == 0:
+            raise ValueError(f"[{self.name}] output_keys cannot be empty.")
+
+        self.outputs: Dict[str, np.ndarray | None] = {k: None for k in self.output_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 YAML parameters by loading a callable from (file_path, function_name).
+        """
+        adapted = dict(params)
+
+        if "function" in adapted:
+            return adapted
+
+        has_file = "file_path" in adapted
+        has_name = "function_name" in adapted
+        if not has_file and not has_name:
+            return adapted
+        if not has_file or not has_name:
+            raise ValueError(
+                "FunctionSource adapter requires both 'file_path' and 'function_name'."
+            )
+
+        path = Path(adapted["file_path"]).expanduser()
+        if not path.is_absolute() and params_dir is not None:
+            path = (params_dir / path).resolve()
+
+        if not path.exists():
+            raise FileNotFoundError(f"Function file not found: {path}")
+
+        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)
+
+        func_name = adapted["function_name"]
+        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")
+
+        adapted.pop("file_path", None)
+        adapted.pop("function_name", None)
+        adapted["function"] = func
+        if "output_keys" not in adapted:
+            adapted["output_keys"] = ["out"]
+        return adapted
+
+    # --------------------------------------------------------------------------
+    # Public Methods
+    # --------------------------------------------------------------------------
+    def initialize(self, t0: float) -> None:
+        self._validate_signature()
+        out = self._call_func(t0, 0.0)
+        for key in self.output_keys:
+            self.outputs[key] = out[key]
+
+    # ------------------------------------------------------------------
+    def output_update(self, t: float, dt: float) -> None:
+        out = self._call_func(t, dt)
+        for key in self.output_keys:
+            self.outputs[key] = out[key]
+
+    # --------------------------------------------------------------------------
+    # Private Methods
+    # --------------------------------------------------------------------------
+    def _call_func(self, t: float, dt: float) -> Dict[str, np.ndarray]:
+        try:
+            out = self._func(t, dt)
+        except Exception as e:
+            raise RuntimeError(f"[{self.name}] function call error: {e}")
+
+        if not isinstance(out, dict):
+            raise RuntimeError(
+                f"[{self.name}] function must return a dict with output keys: "
+                f"{self.output_keys}."
+            )
+
+        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())})."
+            )
+
+        normalized: Dict[str, np.ndarray] = {}
+        for key in self.output_keys:
+            y = self._to_2d_array(key, out[key], dtype=float)
+            if y.ndim != 2:
+                raise ValueError(
+                    f"[{self.name}] output '{key}' must be scalar, 1D, or 2D."
+                )
+
+            if self._out_shapes[key] is None:
+                self._out_shapes[key] = y.shape
+            elif y.shape != self._out_shapes[key]:
+                raise ValueError(
+                    f"[{self.name}] output '{key}' shape changed: expected "
+                    f"{self._out_shapes[key]}, got {y.shape}."
+                )
+            normalized[key] = y
+
+        return normalized
+
+    # ------------------------------------------------------------------
+    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 exactly arguments (t, dt)."
+            )
+        if params[0].name != "t" or params[1].name != "dt":
+            raise ValueError(
+                f"[{self.name}] function arguments must be exactly (t, dt)."
+            )
+
+        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.")
+            if p.default is not inspect.Parameter.empty:
+                raise ValueError(
+                    f"[{self.name}] default values are not allowed in function signature."
+                )

pySimBlocks/blocks/sources/ramp.py

@@ -0,0 +1,99 @@
+# ******************************************************************************
+#                                  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 Ramp(BlockSource):
+    """
+    Multi-dimensional ramp signal source block (Option B).
+
+    Summary:
+        Generates a ramp signal element-wise on a 2D output array:
+            y(t) = offset + slope * max(0, t - start_time)
+
+        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):
+        slope : float or array-like
+            Ramp slope. Scalar -> broadcast; otherwise fixes output shape.
+        start_time : float or array-like, optional
+            Ramp start time. Scalar -> broadcast; otherwise must match output shape.
+        offset : float or array-like, optional
+            Output value before the ramp starts. Scalar -> broadcast; otherwise must match output shape.
+        sample_time : float, optional
+            Block execution period.
+
+    Outputs:
+        out : ramp output signal (2D ndarray)
+
+    Notes:
+        - Stateless block.
+        - 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,
+        slope: ArrayLike,
+        start_time: ArrayLike = 0.0,
+        offset: ArrayLike | None = None,
+        sample_time: float | None = None,
+    ):
+        super().__init__(name, sample_time)
+
+        S = self._to_2d_array("slope", slope, dtype=float)
+        T = self._to_2d_array("start_time", start_time, dtype=float)
+
+        if offset is None:
+            O = np.array([[0.0]], dtype=float)  # scalar, will be broadcast if needed
+        else:
+            O = self._to_2d_array("offset", offset, dtype=float)
+
+        # Resolve common shape using strict scalar-only broadcasting policy
+        target_shape = self._resolve_common_shape({"slope": S, "start_time": T, "offset": O})
+
+        self.slope = self._broadcast_scalar_only("slope", S, target_shape)
+        self.start_time = self._broadcast_scalar_only("start_time", T, target_shape)
+        self.offset = self._broadcast_scalar_only("offset", O, target_shape)
+
+        # Output port
+        self.outputs["out"] = self.offset.copy()
+
+    # --------------------------------------------------------------------------
+    # Public methods
+    # --------------------------------------------------------------------------
+    def initialize(self, t0: float) -> None:
+        self.outputs["out"] = self.offset.copy()
+
+    # ------------------------------------------------------------------
+    def output_update(self, t: float, dt: float) -> None:
+        # Element-wise time shift
+        dt_mat = np.maximum(0.0, t - self.start_time)
+        self.outputs["out"] = self.offset + self.slope * dt_mat