pySimBlocks 0.1.0__py3-none-any.whl

pySimBlocks/project/load_simulator.py

@@ -0,0 +1,45 @@
+# ******************************************************************************
+#                                  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 Tuple
+
+from pySimBlocks.core.config import PlotConfig
+from pySimBlocks.core.model import Model
+from pySimBlocks.core.simulator import Simulator
+from pySimBlocks.project.build_model import build_model_from_dict
+from pySimBlocks.project.load_project_config import load_project_config
+
+
+def load_simulator_from_project(
+    project_yaml: str | Path,
+) -> Tuple[Simulator, PlotConfig | None]:
+    """
+    Build and return a ready-to-run Simulator from a unified project.yaml.
+    """
+    sim_cfg, model_dict, plot_cfg, project_name, params_dir = load_project_config(
+        project_yaml
+    )
+
+    model = Model(name=project_name)
+    build_model_from_dict(model, model_dict, params_dir=params_dir)
+
+    sim = Simulator(model, sim_cfg)
+    return sim, plot_cfg

pySimBlocks/project/plot_from_config.py

@@ -0,0 +1,174 @@
+# ******************************************************************************
+#                                  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
+import matplotlib.pyplot as plt
+
+from pySimBlocks.core.config import PlotConfig
+
+
+def _stack_logged_signal(logs: dict, sig: str) -> np.ndarray:
+    """
+    Stack a logged signal over time, preserving its 2D shape.
+
+    Returns:
+        data: np.ndarray of shape (T, m, n)
+
+    Raises:
+        ValueError: if the signal is not a list of 2D arrays with consistent shape.
+    """
+    samples = logs[sig]
+    if not isinstance(samples, list) or len(samples) == 0:
+        raise ValueError(f"Signal '{sig}' has no samples in logs.")
+
+    # Find first non-None sample to define shape
+    first = None
+    for s in samples:
+        if s is not None:
+            first = np.asarray(s)
+            break
+
+    if first is None:
+        raise ValueError(f"Signal '{sig}' is always None; cannot plot.")
+
+    if first.ndim != 2:
+        raise ValueError(f"Signal '{sig}' must be 2D. Got ndim={first.ndim} with shape {first.shape}.")
+
+    shape0 = first.shape
+
+    stacked = []
+    for k, s in enumerate(samples):
+        if s is None:
+            raise ValueError(f"Signal '{sig}' contains None at index {k}; cannot plot.")
+        a = np.asarray(s)
+        if a.ndim != 2:
+            raise ValueError(
+                f"Signal '{sig}' sample {k} must be 2D. Got ndim={a.ndim} with shape {a.shape}."
+            )
+        if a.shape != shape0:
+            raise ValueError(
+                f"Signal '{sig}' shape changed over time: expected {shape0}, got {a.shape} at sample {k}."
+            )
+        stacked.append(a)
+
+    data = np.stack(stacked, axis=0)  # (T, m, n)
+    return data
+
+
+def plot_from_config(
+    logs: dict,
+    plot_cfg: PlotConfig | None,
+    show: bool = True,
+    block: bool = True
+):
+    """
+    Plot logged simulation signals according to a PlotConfig.
+
+    Supports 2D signals:
+      - scalar (1,1)
+      - column vectors (n,1)
+      - matrices (m,n) with n>1
+
+    Plot semantics:
+      - each component is plotted as a separate curve
+      - labels:
+          scalar:      sig
+          vector:      sig[i]
+          matrix:      sig[r,c]
+    """
+    if plot_cfg is None:
+        return
+
+    # ------------------------------------------------------------
+    # Global validation: all plotted signals must be logged
+    # ------------------------------------------------------------
+    requested_signals = set()
+    for plot in plot_cfg.plots:
+        requested_signals.update(plot["signals"])
+
+    available_signals = set(logs.keys())
+    available_signals.discard("time")
+
+    missing = sorted(requested_signals - available_signals)
+    if missing:
+        raise KeyError(
+            "The following signals are requested for plotting but were not logged:\n"
+            + "\n".join(f"  - {sig}" for sig in missing)
+            + "\n\nAvailable logged signals:\n"
+            + "\n".join(f"  - {sig}" for sig in sorted(available_signals))
+        )
+
+    if "time" not in logs:
+        raise KeyError("Logs must contain a 'time' entry.")
+
+    # ------------------------------------------------------------
+    # Time base
+    # Your simulator logs time as np.array([t_step]) each step,
+    # so flatten() is appropriate.
+    # ------------------------------------------------------------
+    time = np.asarray(logs["time"]).flatten()
+    T = len(time)
+    if T == 0:
+        return
+
+    # ------------------------------------------------------------
+    # Plotting
+    # ------------------------------------------------------------
+    for plot in plot_cfg.plots:
+        title = plot.get("title", "")
+        signals = plot["signals"]
+
+        plt.figure()
+
+        for sig in signals:
+            data = _stack_logged_signal(logs, sig)  # (T, m, n)
+
+            if data.shape[0] != T:
+                raise ValueError(
+                    f"Time length mismatch for '{sig}': time has {T} samples but signal has {data.shape[0]}."
+                )
+
+            m, n = data.shape[1], data.shape[2]
+
+            # scalar
+            if (m, n) == (1, 1):
+                plt.step(time, data[:, 0, 0], where="post", label=sig)
+                continue
+
+            # vector column (n,1) -> label sig[i]
+            if n == 1:
+                for i in range(m):
+                    plt.step(time, data[:, i, 0], where="post", label=f"{sig}[{i}]")
+                continue
+
+            # matrix (m,n) -> label sig[r,c]
+            for r in range(m):
+                for c in range(n):
+                    plt.step(time, data[:, r, c], where="post", label=f"{sig}[{r},{c}]")
+
+        plt.xlabel("Time [s]")
+        plt.grid(True)
+        plt.legend()
+
+        if title:
+            plt.title(title)
+
+    if show:
+        plt.show(block=block)

pySimBlocks/project/pySimBlocks_blocks_index.yaml

@@ -0,0 +1,106 @@
+controllers:
+  pid:
+    class: Pid
+    module: pySimBlocks.blocks.controllers.pid
+  state_feedback:
+    class: StateFeedback
+    module: pySimBlocks.blocks.controllers.state_feedback
+interfaces:
+  external_input:
+    class: ExternalInput
+    module: pySimBlocks.blocks.interfaces.external_input
+  external_output:
+    class: ExternalOutput
+    module: pySimBlocks.blocks.interfaces.external_output
+observers:
+  luenberger:
+    class: Luenberger
+    module: pySimBlocks.blocks.observers.luenberger
+operators:
+  algebraic_function:
+    class: AlgebraicFunction
+    module: pySimBlocks.blocks.operators.algebraic_function
+  dead_zone:
+    class: DeadZone
+    module: pySimBlocks.blocks.operators.dead_zone
+  delay:
+    class: Delay
+    module: pySimBlocks.blocks.operators.delay
+  demux:
+    class: Demux
+    module: pySimBlocks.blocks.operators.demux
+  discrete_derivator:
+    class: DiscreteDerivator
+    module: pySimBlocks.blocks.operators.discrete_derivator
+  discrete_integrator:
+    class: DiscreteIntegrator
+    module: pySimBlocks.blocks.operators.discrete_integrator
+  gain:
+    class: Gain
+    module: pySimBlocks.blocks.operators.gain
+  mux:
+    class: Mux
+    module: pySimBlocks.blocks.operators.mux
+  product:
+    class: Product
+    module: pySimBlocks.blocks.operators.product
+  rate_limiter:
+    class: RateLimiter
+    module: pySimBlocks.blocks.operators.rate_limiter
+  saturation:
+    class: Saturation
+    module: pySimBlocks.blocks.operators.saturation
+  sum:
+    class: Sum
+    module: pySimBlocks.blocks.operators.sum
+  zero_order_hold:
+    class: ZeroOrderHold
+    module: pySimBlocks.blocks.operators.zero_order_hold
+optimizers:
+  quadratic_program:
+    class: QuadraticProgram
+    module: pySimBlocks.blocks.optimizers.quadratic_program
+sources:
+  chirp:
+    class: Chirp
+    module: pySimBlocks.blocks.sources.chirp
+  constant:
+    class: Constant
+    module: pySimBlocks.blocks.sources.constant
+  file_source:
+    class: FileSource
+    module: pySimBlocks.blocks.sources.file_source
+  function_source:
+    class: FunctionSource
+    module: pySimBlocks.blocks.sources.function_source
+  ramp:
+    class: Ramp
+    module: pySimBlocks.blocks.sources.ramp
+  sinusoidal:
+    class: Sinusoidal
+    module: pySimBlocks.blocks.sources.sinusoidal
+  step:
+    class: Step
+    module: pySimBlocks.blocks.sources.step
+  white_noise:
+    class: WhiteNoise
+    module: pySimBlocks.blocks.sources.white_noise
+systems:
+  linear_state_space:
+    class: LinearStateSpace
+    module: pySimBlocks.blocks.systems.linear_state_space
+  non_linear_state_space:
+    class: NonLinearStateSpace
+    module: pySimBlocks.blocks.systems.non_linear_state_space
+  polytopic_state_space:
+    class: PolytopicStateSpace
+    module: pySimBlocks.blocks.systems.polytopic_state_space
+  sofa_controller:
+    class: SofaPysimBlocksController
+    module: pySimBlocks.blocks.systems.sofa.sofa_controller
+  sofa_exchange_i_o:
+    class: SofaExchangeIO
+    module: pySimBlocks.blocks.systems.sofa.sofa_exchange_i_o
+  sofa_plant:
+    class: SofaPlant
+    module: pySimBlocks.blocks.systems.sofa.sofa_plant

pySimBlocks/real_time/__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.real_time.real_time_runner import RealTimeRunner
+
+__all__ = ["RealTimeRunner"]

pySimBlocks/real_time/real_time_runner.py

@@ -0,0 +1,148 @@
+# ******************************************************************************
+#                                  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 time
+import numpy as np
+from typing import Any, Dict, List, Optional
+from pySimBlocks.core.simulator import Simulator
+
+
+class RealTimeRunner:
+    """
+    Generic real-time runner for pySimBlocks.
+
+    Responsibilities:
+      - Provide an external clock (dt measured or provided).
+      - Push external inputs into ExternalInput blocks.
+      - Call Simulator.step(dt_override=...).
+      - Pull outputs from ExternalOutput blocks.
+
+    Notes:
+      - No threading, no I/O drivers here. The application owns that.
+      - Designed to be embedded in user-specific real-time apps.
+    """
+
+    def __init__(
+        self,
+        sim: Simulator,
+        input_blocks: List[str],
+        output_blocks: List[str],
+        *,
+        target_dt: Optional[float] = None,
+        time_source: str = "perf_counter",  # "perf_counter" | "time"
+    ):
+        """
+        Parameters
+        ----------
+        sim:
+            Initialized Simulator instance (model already compiled).
+        input_blocks:
+            Mapping external input name -> block name in model
+            Example: {"camera": "Camera", "ref": "Reference"}
+        output_blocks:
+            Mapping external output name -> block name in model
+            Example: {"motor": "Motor"}
+        target_dt:
+            If provided, runner will pace the loop to approximately this period
+            (best effort). If None, no pacing.
+        time_source:
+            Timer function selection.
+        """
+        self.sim = sim
+        self.input_blocks = {block_name: sim.model.get_block_by_name(block_name) for block_name in input_blocks}
+        self.output_blocks = {block_name: sim.model.get_block_by_name(block_name) for block_name in output_blocks}
+        self.target_dt = target_dt
+
+        if time_source == "perf_counter":
+            self._now = time.perf_counter
+        elif time_source == "time":
+            self._now = time.time
+        else:
+            raise ValueError("time_source must be 'perf_counter' or 'time'")
+
+        self._t_prev: Optional[float] = None
+
+    def initialize(self, t0: float = 0.0) -> None:
+        self.sim.initialize(t0)
+        self._t_prev = self._now()
+
+    def tick(
+        self,
+        inputs: Dict[str, Any],
+        *,
+        dt: Optional[float] = None,
+        pace: bool = False,
+    ) -> Dict[str, np.ndarray]:
+        """
+        Execute one real-time tick.
+
+        Parameters
+        ----------
+        inputs:
+            External inputs keyed by input_blocks mapping key.
+            Example: {"camera": markers_pos, "ref": ref_value}
+        dt:
+            Optional explicit dt_override. If None, dt is measured from wall clock.
+        pace:
+            If True and target_dt is set, sleep to approximate target period.
+
+        Returns
+        -------
+        outputs:
+            Dict mapping output key -> np.ndarray (n,1)
+        """
+        if self._t_prev is None:
+            self._t_prev = self._now()
+
+        t_now = self._now()
+        dt_meas = t_now - self._t_prev
+        dt_used = float(dt) if dt is not None else float(dt_meas)
+
+        # warning if dt is much larger than target_dt
+        if self.target_dt is not None and dt_used > 1.5 * self.target_dt:
+            print(f"[RealTimeRunner] Warning: dt={dt_used:.3f}s exceeds target_dt={self.target_dt:.3f}s")
+
+        # 1) push inputs
+        for block_name, block in self.input_blocks.items():
+            if block_name not in inputs:
+                raise KeyError(f"[RealTimeRunner] Missing input '{block_name}'")
+            block.inputs["in"] = inputs[block_name]
+
+        # 2) step with external dt
+        self.sim.step(dt_override=dt_used)
+
+        # 3) pull outputs
+        outputs: Dict[str, np.ndarray] = {}
+        for block_name, block in self.output_blocks.items():
+            y = block.outputs["out"]
+            if y is None:
+                raise RuntimeError(f"[RealTimeRunner] Output 'out' of block '{block_name}' is None")
+            outputs[block_name] = np.asarray(y, dtype=float).reshape(-1, 1)
+
+        # 4) bookkeeping + pacing
+        self._t_prev = t_now
+
+        if pace and self.target_dt is not None:
+            elapsed = self._now() - t_now
+            sleep_time = self.target_dt - elapsed
+            if sleep_time > 0:
+                time.sleep(sleep_time)
+
+        return outputs

pySimBlocks/tools/__init__.py

@@ -0,0 +1,19 @@
+# ******************************************************************************
+#                                  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
+# ******************************************************************************

pySimBlocks/tools/blocks_registry.py

@@ -0,0 +1,141 @@
+# ******************************************************************************
+#                                  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 __future__ import annotations
+
+import importlib
+import inspect
+from pathlib import Path
+from typing import Dict, Optional
+
+from pySimBlocks.gui.blocks.block_meta import BlockMeta
+
+BlockRegistry = Dict[str, Dict[str, BlockMeta]]
+
+def load_block_registry(
+    metadata_root: Path | str | None = None,    
+) -> BlockRegistry:
+    
+    if metadata_root is None:
+        metadata_root = Path(__file__).parents[1] / "gui" / "blocks"
+    else:
+        metadata_root = Path(metadata_root).resolve()
+    
+    if not metadata_root.exists():
+        raise FileNotFoundError(f"blocks_metadata directory not found: {metadata_root}")
+    
+    registry: BlockRegistry = {}
+
+    for py_path in metadata_root.rglob("*.py"):
+        _register_block_from_py(py_path, registry)
+
+    return registry
+
+def _register_block_from_py(
+        py_path: Path,
+        registry: BlockRegistry,
+) -> None:
+    """
+    Import a *.py file and register all BlockMeta subclasses inside.
+    """
+
+    module_name = _path_to_module(py_path)
+
+    module = importlib.import_module(module_name)
+
+    doc_path = _resolve_doc_path(py_path)
+
+    for _, obj in inspect.getmembers(module, inspect.isclass):
+        if not issubclass(obj, BlockMeta):
+            continue
+        if obj is BlockMeta:
+            continue
+
+        meta: BlockMeta = obj()
+
+        meta.doc_path = doc_path
+
+        category = meta.category
+        block_type = meta.type
+
+        registry.setdefault(category, {})
+
+        if block_type in registry[category]:
+            raise ValueError(
+                f"Duplicate block type '{block_type}' in category '{category}'.\n"
+                f"Conflict in module: {module_name}"
+            )
+        
+        registry[category][block_type] = meta
+
+def _path_to_module(py_path: Path) -> str:
+    """
+    Convert a file path to a Python module path.
+
+    Example:
+      pySimBlocks/blocks_metadata/operators/sum_meta.py
+      -> pySimBlocks.blocks_metadata.operators.sum_meta
+    """
+
+    py_path = py_path.with_suffix("")
+
+    package_root = Path(__file__).parents[1]  # pySimBlocks/
+
+    try:
+        rel_path = py_path.relative_to(package_root)
+    except ValueError:
+        raise RuntimeError(
+            f"File {py_path} is not inside package root {package_root}"
+        )
+
+    module_name = (
+        package_root.name
+        + "."
+        + rel_path.as_posix().replace("/", ".")
+    )
+
+    return module_name
+
+def _resolve_doc_path(py_path: Path) -> Optional[Path]:
+    """
+    Resolve the documentation markdown file corresponding to a YAML metadata file.
+
+    Example:
+        blocks_metadata/systems/sofa/sofa_plant.yaml
+        -> docs/blocks_metadata/systems/sofa/sofa_plant.md
+    """
+
+    try:
+        parts = list(py_path.parts)
+        idx = parts.index("gui")
+    except ValueError:
+        return None
+
+    doc_root = Path(*parts[:idx]) / "docs"
+
+    rel = Path(*parts[idx + 1 :]).with_suffix(".md")
+
+    doc_path = doc_root / rel
+
+    return doc_path if doc_path.exists() else None
+
+
+if __name__ == "__main__":
+    registry = load_block_registry()