pySimBlocks 0.1.0__tar.gz → 0.2.0__tar.gz

{pysimblocks-0.1.0/pySimBlocks.egg-info → pysimblocks-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pySimBlocks
-Version: 0.1.0
+Version: 0.2.0
 Summary: A block-diagram simulation environment with PySide6 editor
 Author-email: Antoine Alessandrini <antoine.alessandrini@univ-lille.fr>
 License-Expression: LGPL-3.0-or-later
@@ -11,10 +11,6 @@ Keywords: simulation,block-diagram,control,discrete-time,pyside6
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
 Classifier: Intended Audience :: Education
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Scientific/Engineering :: Visualization
 Requires-Python: >=3.10
@@ -28,6 +24,11 @@ Requires-Dist: typing_extensions; python_version < "3.11"
 Provides-Extra: examples
 Requires-Dist: control; extra == "examples"
 Requires-Dist: qpsolvers[clarabel,osqp]; extra == "examples"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Requires-Dist: furo; extra == "docs"
+Requires-Dist: sphinxcontrib-video; extra == "docs"
 Provides-Extra: tests
 Requires-Dist: pytest; extra == "tests"
 Requires-Dist: pytest-qt; extra == "tests"
@@ -35,45 +36,34 @@ Dynamic: license-file
 
 # pySimBlocks
 
+[![PyPI version](https://img.shields.io/pypi/v/pySimBlocks.svg)](https://pypi.org/project/pySimBlocks/)
+[![Python](https://img.shields.io/pypi/pyversions/pySimBlocks.svg)](https://pypi.org/project/pySimBlocks/)
+[![License](https://img.shields.io/github/license/AlessandriniAntoine/pySimBlocks)](./LICENSE.md)
+[![Documentation](https://readthedocs.org/projects/pysimblocks/badge/?version=latest)](https://pysimblocks.readthedocs.io)
+
+---
+
 A deterministic block-diagram simulation framework for discrete-time modeling, 
 co-simulation and research prototyping in Python.
 
-pySimBlocks allows you to build, configure, and execute discrete-time systems 
+pySimBlocks allows you to build, configure, and execute discrete-time systems
 using either:
 
 - A pure Python API
 - A graphical editor (PySide6)
-- YAML project configuration
+- YAML project configuration with exportable Python runner (`run.py`)
 - Optional SOFA and hardware integration
 
-![pySimBlocks graphical editor](https://raw.githubusercontent.com/AlessandriniAntoine/pySimBlocks/main/docs/User_Guide/images/gui_example.png)
-
-## Features
-
-- Block-based modeling (Simulink-like)
-- Deterministic discrete-time simulation engine
-- PySide6 graphical editor
-- YAML-based project serialization
-- Exportable Python runner (`run.py`)
-- Extensible block architecture
+![pySimBlocks graphical editor](https://raw.githubusercontent.com/AlessandriniAntoine/pySimBlocks/main/docs/source/images/user_guide/gui_example.png)
 
 ## Installation
 
-### From GitHub
-
-Install directly from GitHub using pip:
-```
-pip install git+https://github.com/AlessandriniAntoine/pySimBlocks
+```bash
+pip install pySimBlocks
 ```
 
-### Locally
-
-Clone the repository and install locally:
-```
-git clone https://github.com/AlessandriniAntoine/pySimBlocks.git
-cd pySimBlocks
-pip install .
-```
+Full documentation — user guide, tutorials, and API reference — is available on
+[**Read the Docs**](https://pysimblocks.readthedocs.io).
 
 ## Getting Started
 
@@ -125,7 +115,7 @@ plot_from_config(logs, plot_cfg)
 
 The resulting plot should look like this:
 
-![Noise filtered](https://raw.githubusercontent.com/AlessandriniAntoine/pySimBlocks/main/docs/User_Guide/images/quick_example.png)
+![Noise filtered](https://raw.githubusercontent.com/AlessandriniAntoine/pySimBlocks/main/docs/source/images/user_guide/quick_example.png)
 
 See [examples/quick_start/filter.py](./examples/quick_start/filter.py)
 to run the example yourself.
@@ -148,14 +138,14 @@ The quick-start GUI project is stored in a single
 
 #### Tutorials
 
-Three step-by-step tutorials are available detailed in the
-[guide](./docs/User_Guide/getting_started.md):
+Three step-by-step tutorials are available in the
+[documentation](https://pysimblocks.readthedocs.io/en/latest/user_guide/tutorials/index.html):
 
   | | Tutorial | Description |
   |---|---|---|
-  | 1 | [Python API](./docs/User_Guide/tutorial_1_python.md) | Build a closed-loop PI control system in pure Python |
-  | 2 | [GUI](./docs/User_Guide/tutorial_2_gui.md) | Build the same system visually with the graphical editor |
-  | 3 | [SOFA](./docs/User_Guide/tutorial_3_sofa.md) | Replace the plant with a SOFA physics simulation |
+  | 1 | [Python API](https://pysimblocks.readthedocs.io/en/latest/user_guide/tutorials/tutorial_1_python.html) | Build a closed-loop PI control system in pure Python |
+  | 2 | [GUI](https://pysimblocks.readthedocs.io/en/latest/user_guide/tutorials/tutorial_2_gui.html) | Build the same system visually with the graphical editor |
+  | 3 | [SOFA](https://pysimblocks.readthedocs.io/en/latest/user_guide/tutorials/tutorial_3_sofa.html) | Replace the plant with a SOFA physics simulation |
 
 
 #### Other Examples
@@ -164,7 +154,7 @@ A collection of basic and advanced examples is available in the
 [examples](./examples) directory, including:
 
 - Control system demonstrations
-- SOFA-based simulations (tested with SOFA v24.06 and later.)
+- SOFA-based simulations (tested with SOFA v26.06 and later.)
 - Hardware and real-time use cases
 - Comparisons with external tools
 

{pysimblocks-0.1.0 → pysimblocks-0.2.0}/README.md

@@ -1,44 +1,33 @@
 # pySimBlocks
 
+[![PyPI version](https://img.shields.io/pypi/v/pySimBlocks.svg)](https://pypi.org/project/pySimBlocks/)
+[![Python](https://img.shields.io/pypi/pyversions/pySimBlocks.svg)](https://pypi.org/project/pySimBlocks/)
+[![License](https://img.shields.io/github/license/AlessandriniAntoine/pySimBlocks)](./LICENSE.md)
+[![Documentation](https://readthedocs.org/projects/pysimblocks/badge/?version=latest)](https://pysimblocks.readthedocs.io)
+
+---
+
 A deterministic block-diagram simulation framework for discrete-time modeling, 
 co-simulation and research prototyping in Python.
 
-pySimBlocks allows you to build, configure, and execute discrete-time systems 
+pySimBlocks allows you to build, configure, and execute discrete-time systems
 using either:
 
 - A pure Python API
 - A graphical editor (PySide6)
-- YAML project configuration
+- YAML project configuration with exportable Python runner (`run.py`)
 - Optional SOFA and hardware integration
 
-![pySimBlocks graphical editor](https://raw.githubusercontent.com/AlessandriniAntoine/pySimBlocks/main/docs/User_Guide/images/gui_example.png)
-
-## Features
-
-- Block-based modeling (Simulink-like)
-- Deterministic discrete-time simulation engine
-- PySide6 graphical editor
-- YAML-based project serialization
-- Exportable Python runner (`run.py`)
-- Extensible block architecture
+![pySimBlocks graphical editor](https://raw.githubusercontent.com/AlessandriniAntoine/pySimBlocks/main/docs/source/images/user_guide/gui_example.png)
 
 ## Installation
 
-### From GitHub
-
-Install directly from GitHub using pip:
-```
-pip install git+https://github.com/AlessandriniAntoine/pySimBlocks
+```bash
+pip install pySimBlocks
 ```
 
-### Locally
-
-Clone the repository and install locally:
-```
-git clone https://github.com/AlessandriniAntoine/pySimBlocks.git
-cd pySimBlocks
-pip install .
-```
+Full documentation — user guide, tutorials, and API reference — is available on
+[**Read the Docs**](https://pysimblocks.readthedocs.io).
 
 ## Getting Started
 
@@ -90,7 +79,7 @@ plot_from_config(logs, plot_cfg)
 
 The resulting plot should look like this:
 
-![Noise filtered](https://raw.githubusercontent.com/AlessandriniAntoine/pySimBlocks/main/docs/User_Guide/images/quick_example.png)
+![Noise filtered](https://raw.githubusercontent.com/AlessandriniAntoine/pySimBlocks/main/docs/source/images/user_guide/quick_example.png)
 
 See [examples/quick_start/filter.py](./examples/quick_start/filter.py)
 to run the example yourself.
@@ -113,14 +102,14 @@ The quick-start GUI project is stored in a single
 
 #### Tutorials
 
-Three step-by-step tutorials are available detailed in the
-[guide](./docs/User_Guide/getting_started.md):
+Three step-by-step tutorials are available in the
+[documentation](https://pysimblocks.readthedocs.io/en/latest/user_guide/tutorials/index.html):
 
   | | Tutorial | Description |
   |---|---|---|
-  | 1 | [Python API](./docs/User_Guide/tutorial_1_python.md) | Build a closed-loop PI control system in pure Python |
-  | 2 | [GUI](./docs/User_Guide/tutorial_2_gui.md) | Build the same system visually with the graphical editor |
-  | 3 | [SOFA](./docs/User_Guide/tutorial_3_sofa.md) | Replace the plant with a SOFA physics simulation |
+  | 1 | [Python API](https://pysimblocks.readthedocs.io/en/latest/user_guide/tutorials/tutorial_1_python.html) | Build a closed-loop PI control system in pure Python |
+  | 2 | [GUI](https://pysimblocks.readthedocs.io/en/latest/user_guide/tutorials/tutorial_2_gui.html) | Build the same system visually with the graphical editor |
+  | 3 | [SOFA](https://pysimblocks.readthedocs.io/en/latest/user_guide/tutorials/tutorial_3_sofa.html) | Replace the plant with a SOFA physics simulation |
 
 
 #### Other Examples
@@ -129,7 +118,7 @@ A collection of basic and advanced examples is available in the
 [examples](./examples) directory, including:
 
 - Control system demonstrations
-- SOFA-based simulations (tested with SOFA v24.06 and later.)
+- SOFA-based simulations (tested with SOFA v26.06 and later.)
 - Hardware and real-time use cases
 - Comparisons with external tools
 

{pysimblocks-0.1.0 → pysimblocks-0.2.0}/pySimBlocks/blocks/controllers/pid.py

@@ -18,6 +18,8 @@
 #  Authors: see Authors.txt
 # ******************************************************************************
 
+from __future__ import annotations
+
 import warnings
 
 import numpy as np
@@ -27,43 +29,26 @@ from pySimBlocks.core.block import Block
 
 
 class Pid(Block):
-    """
-    Discrete-time PID controller block.
-
-    Summary:
-        Implements a single-input single-output discrete PID controller,
-        similar to the Simulink PID block. The controller computes a control
-        command from an error signal using proportional, integral and/or
-        derivative actions, depending on the selected control mode.
-
-    Parameters (overview):
-        controller : str
-            Control mode. One of {"P", "PI", "PD", "PID"}.
-        Kp : float
-            Proportional gain.
-        Ki : float
-            Integral gain.
-        Kd : float
-            Derivative gain.
-        u_min : float, optional
-            Minimum output saturation.
-        u_max : float, optional
-            Maximum output saturation.
-        sample_time : float, optional
-            Controller sampling period.
-
-    I/O:
-        Inputs:
-            e : error signal.
-        Outputs:
-            u : control command.
-
-    Notes:
-        - The block is strictly SISO.
-        - Integral action introduces internal state.
-        - If a parameter is not provided, the block falls back to its
-          internal default value.
-        - Output saturation is applied only if u_min and/or u_max are defined.
+    """Discrete-time PID controller block.
+
+    Implements a single-input single-output discrete PID controller,
+    similar to the Simulink PID block. The controller computes a control
+    command from an error signal ``e`` using proportional, integral, and/or
+    derivative actions depending on the selected control mode.
+
+    Output saturation is applied only if ``u_min`` and/or ``u_max`` are set.
+    Anti-windup clamps the integrator state to the saturation bounds.
+
+    Attributes:
+        controller: Active control mode (``"P"``, ``"I"``, ``"PI"``,
+            ``"PD"``, or ``"PID"``).
+        integration_method: Integration scheme for the I term
+            (``"euler forward"`` or ``"euler backward"``).
+        Kp: Proportional gain as a (1,1) array.
+        Ki: Integral gain as a (1,1) array.
+        Kd: Derivative gain as a (1,1) array.
+        u_min: Lower saturation bound as a (1,1) array, or None.
+        u_max: Upper saturation bound as a (1,1) array, or None.
     """
 
     def __init__(
@@ -78,6 +63,27 @@ class Pid(Block):
         integration_method: str = "euler forward",
         sample_time: float | None = None,
     ):
+        """Initialize a PID controller block.
+
+        Args:
+            name: Unique identifier for this block instance.
+            controller: Control mode. Must be one of ``{"P", "I", "PI",
+                "PD", "PID"}``.
+            Kp: Proportional gain. Must be scalar-like.
+            Ki: Integral gain. Must be scalar-like.
+            Kd: Derivative gain. Must be scalar-like.
+            u_min: Minimum output saturation bound. None to disable.
+            u_max: Maximum output saturation bound. None to disable.
+            integration_method: Integration scheme for the I term.
+                Must be ``"euler forward"`` or ``"euler backward"``.
+            sample_time: Sampling period in seconds, or None to use the
+                global simulation dt.
+
+        Raises:
+            ValueError: If ``controller`` or ``integration_method`` is
+                invalid, if any gain is not scalar-like, or if
+                ``u_min > u_max``.
+        """
         super().__init__(name, sample_time)
 
         controller = controller.upper()
@@ -95,7 +101,6 @@ class Pid(Block):
                 f"[{self.name}] Unsupported method '{self.integration_method}'. Allowed: {allowed}"
             )
 
-        # Gains (SISO, (1,1))
         self.Kp = self._to_siso("Kp", Kp)
         self.Ki = self._to_siso("Ki", Ki)
         self.Kd = self._to_siso("Kd", Kd)
@@ -109,13 +114,10 @@ class Pid(Block):
                     f"[{self.name}] u_min ({self.u_min.item()}) must be <= u_max ({self.u_max.item()})."
                 )
 
-        # Warnings
         self._validate_gains()
 
-        # Direct feedthrough policy
         has_p = "P" in self.controller
         has_d = "D" in self.controller
-        has_i = "I" in self.controller
 
         if has_p or has_d:
             self.direct_feedthrough = True
@@ -123,11 +125,9 @@ class Pid(Block):
             # I-only
             self.direct_feedthrough = (self.integration_method == "euler backward")
 
-        # Ports
         self.inputs["e"] = None
         self.outputs["u"] = None
 
-        # State (SISO)
         self.state["x_i"] = np.zeros((1, 1), dtype=float)
         self.state["e_prev"] = np.zeros((1, 1), dtype=float)
         self.next_state["x_i"] = np.zeros((1, 1), dtype=float)
@@ -137,12 +137,25 @@ class Pid(Block):
     # --------------------------------------------------------------------------
     # Public methods
     # --------------------------------------------------------------------------
-    def initialize(self, t0: float):
-        # Start at zero command, keep internal states at zero.
+
+    def initialize(self, t0: float) -> None:
+        """Set the output to zero and keep internal states at zero.
+
+        Args:
+            t0: Initial simulation time in seconds.
+        """
         self.outputs["u"] = np.zeros((1, 1), dtype=float)
 
-    # ------------------------------------------------------------------
-    def output_update(self, t: float, dt: float):
+    def output_update(self, t: float, dt: float) -> None:
+        """Compute the PID control command from the current error input.
+
+        Args:
+            t: Current simulation time in seconds.
+            dt: Current time step in seconds.
+
+        Raises:
+            RuntimeError: If input ``e`` is not connected.
+        """
         e_in = self.inputs["e"]
         if e_in is None:
             raise RuntimeError(f"[{self.name}] Missing input 'e'.")
@@ -170,7 +183,6 @@ class Pid(Block):
 
         u = P + I + D
 
-        # Saturation
         if self.u_min is not None:
             u = np.maximum(u, self.u_min)
         if self.u_max is not None:
@@ -178,8 +190,16 @@ class Pid(Block):
 
         self.outputs["u"] = u
 
-    # ------------------------------------------------------------------
-    def state_update(self, t: float, dt: float):
+    def state_update(self, t: float, dt: float) -> None:
+        """Update the integrator state and store the previous error.
+
+        Args:
+            t: Current simulation time in seconds.
+            dt: Current time step in seconds.
+
+        Raises:
+            RuntimeError: If input ``e`` is not connected.
+        """
         e_in = self.inputs["e"]
         if e_in is None:
             raise RuntimeError(f"[{self.name}] Missing input 'e'.")
@@ -188,13 +208,12 @@ class Pid(Block):
 
         has_i = "I" in self.controller
 
-        # Integrator update only if I term is enabled
         if has_i:
             x_i_next = self.state["x_i"] + self.Ki * e * dt
         else:
             x_i_next = self.state["x_i"].copy()
 
-        # Anti-windup (clamp integral state if saturation is defined)
+        # Anti-windup: clamp integral state to saturation bounds
         if self.u_min is not None:
             x_i_next = np.maximum(x_i_next, self.u_min)
         if self.u_max is not None:
@@ -207,10 +226,9 @@ class Pid(Block):
     # --------------------------------------------------------------------------
     # Private methods
     # --------------------------------------------------------------------------
+
     def _to_siso(self, name: str, value: ArrayLike) -> np.ndarray:
-        """
-        Normalize scalar-like into (1,1). Reject anything else (strict SISO).
-        """
+        """Normalize a scalar-like value to a (1,1) array; reject anything else."""
         if np.isscalar(value):
             return np.array([[float(value)]], dtype=float)
 
@@ -227,8 +245,8 @@ class Pid(Block):
             f"[{self.name}] '{name}' must be scalar-like ((), (1,), or (1,1)). Got shape {arr.shape}."
         )
 
-    # ------------------------------------------------------------------
     def _validate_gains(self) -> None:
+        """Warn if a gain is zero for a mode that requires it."""
         kp = float(self.Kp[0, 0])
         ki = float(self.Ki[0, 0])
         kd = float(self.Kd[0, 0])

{pysimblocks-0.1.0 → pysimblocks-0.2.0}/pySimBlocks/blocks/controllers/state_feedback.py

@@ -18,45 +18,44 @@
 #  Authors: see Authors.txt
 # ******************************************************************************
 
+from __future__ import annotations
+
 import numpy as np
+from numpy.typing import ArrayLike
+
 from pySimBlocks.core.block import Block
 
 
 class StateFeedback(Block):
-    """
-    Discrete-time state-feedback controller block.
-
-    Summary:
-        Implements a static discrete-time state-feedback control law:
-            u = G @ r - K @ x
-
-    Parameters:
-        K : array-like, shape (m, n)
-            State feedback gain matrix.
-        G : array-like, shape (m, p)
-            Reference feedforward gain matrix.
-        sample_time : float, optional
-            Block execution period.
-
-    Inputs:
-        r : array (p, 1)
-            Reference vector.
-        x : array (n, 1)
-            State vector.
-
-    Outputs:
-        u : array (m, 1)
-            Control vector.
-
-    Notes:
-        - Stateless block.
-        - This block intentionally enforces column-vector inputs.
-        - No implicit flattening is performed.
+    """Discrete-time state-feedback controller block.
+
+    Implements a static discrete-time state-feedback control law:
+
+        u = G @ r - K @ x
+
+    Both inputs must be column vectors. No implicit flattening is performed.
+
+    Attributes:
+        K: State feedback gain matrix of shape (m, n).
+        G: Reference feedforward gain matrix of shape (m, p).
     """
 
     direct_feedthrough = True
 
-    def __init__(self, name: str, K, G, sample_time: float | None = None):
+    def __init__(self, name: str, K: ArrayLike, G: ArrayLike, sample_time: float | None = None):
+        """Initialize a StateFeedback block.
+
+        Args:
+            name: Unique identifier for this block instance.
+            K: State feedback gain matrix, array-like of shape (m, n).
+            G: Reference feedforward gain matrix, array-like of shape (m, p).
+            sample_time: Sampling period in seconds, or None to use the
+                global simulation dt.
+
+        Raises:
+            ValueError: If K or G are not 2D, or if their first dimensions
+                do not match.
+        """
         super().__init__(name, sample_time)
 
         self.K = np.asarray(K, dtype=float)
@@ -76,23 +75,27 @@ class StateFeedback(Block):
                 f"K is {self.K.shape} while G is {self.G.shape} (first dimension must match)."
             )
 
-        # cached expected sizes for input validation
         self._m = m
         self._n = n
         self._p = p
 
-        # Ports
         self.inputs["r"] = None
         self.inputs["x"] = None
         self.outputs["u"] = None
 
-        # freeze input shapes once seen (optional but consistent)
         self._input_shapes = {}
 
+
     # --------------------------------------------------------------------------
     # Public methods
     # --------------------------------------------------------------------------
-    def initialize(self, t0: float):
+
+    def initialize(self, t0: float) -> None:
+        """Set the output to zero, or compute u if inputs are already available.
+
+        Args:
+            t0: Initial simulation time in seconds.
+        """
         r = self.inputs["r"]
         x = self.inputs["x"]
         if r is None or x is None:
@@ -106,22 +109,45 @@ class StateFeedback(Block):
         except Exception as _:
             self.outputs["u"] = np.zeros((self._m, 1))
 
-    # ------------------------------------------------------------------
-    def output_update(self, t: float, dt: float):
+    def output_update(self, t: float, dt: float) -> None:
+        """Compute the control output u = G @ r - K @ x.
+
+        Args:
+            t: Current simulation time in seconds.
+            dt: Current time step in seconds.
+
+        Raises:
+            RuntimeError: If input ``r`` or ``x`` is not connected.
+            ValueError: If input shapes do not match the gain matrices.
+        """
         r = self._require_col_vector("r", self._p)
         x = self._require_col_vector("x", self._n)
 
         self.outputs["u"] = self.G @ r - self.K @ x
 
-    # ------------------------------------------------------------------
-    def state_update(self, t: float, dt: float):
-        pass
+    def state_update(self, t: float, dt: float) -> None:
+        """No-op: StateFeedback carries no internal state."""
 
 
     # --------------------------------------------------------------------------
     # Private methods
     # --------------------------------------------------------------------------
+
     def _require_col_vector(self, port: str, expected_rows: int) -> np.ndarray:
+        """Validate and return an input port value as a column vector.
+
+        Args:
+            port: Name of the input port to read.
+            expected_rows: Expected number of rows in the column vector.
+
+        Returns:
+            The input value as a 2D (n, 1) float array.
+
+        Raises:
+            RuntimeError: If the port value is None.
+            ValueError: If the array is not a column vector or has the
+                wrong number of rows.
+        """
         u = self.inputs[port]
         if u is None:
             raise RuntimeError(f"[{self.name}] Input '{port}' is not connected or not set.")

{pysimblocks-0.1.0 → pysimblocks-0.2.0}/pySimBlocks/blocks/interfaces/__init__.py

@@ -20,8 +20,12 @@
 
 from pySimBlocks.blocks.interfaces.external_input import ExternalInput
 from pySimBlocks.blocks.interfaces.external_output import ExternalOutput
+from pySimBlocks.blocks.interfaces.goto import Goto
+from pySimBlocks.blocks.interfaces.bus_from import BusFrom
 
 __all__ = [
     "ExternalInput",
-    "ExternalOutput"
+    "ExternalOutput",
+    "Goto",
+    "BusFrom",
 ]