pySimBlocks 0.1.0__tar.gz

pysimblocks-0.1.0/LICENSE.md

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

pysimblocks-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: pySimBlocks
+Version: 0.1.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
+Project-URL: Homepage, https://github.com/AlessandriniAntoine/pySimBlocks
+Project-URL: Repository, https://github.com/AlessandriniAntoine/pySimBlocks
+Project-URL: Issues, https://github.com/AlessandriniAntoine/pySimBlocks/issues
+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
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: pyyaml
+Requires-Dist: PySide6
+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: tests
+Requires-Dist: pytest; extra == "tests"
+Requires-Dist: pytest-qt; extra == "tests"
+Dynamic: license-file
+
+# pySimBlocks
+
+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 
+using either:
+
+- A pure Python API
+- A graphical editor (PySide6)
+- YAML project configuration
+- 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
+
+## Installation
+
+### From GitHub
+
+Install directly from GitHub using pip:
+```
+pip install git+https://github.com/AlessandriniAntoine/pySimBlocks
+```
+
+### Locally
+
+Clone the repository and install locally:
+```
+git clone https://github.com/AlessandriniAntoine/pySimBlocks.git
+cd pySimBlocks
+pip install .
+```
+
+## Getting Started
+
+### Quick Example
+
+The following example models a simple first-order low-pass filter, defined by
+the difference equation:
+
+$$ y[k] =  \alpha x[k] + (1-\alpha) y[k-1] $$
+
+It can be implemented in pySimBlocks using the following code:
+
+```python
+from pySimBlocks import Model, Simulator, SimulationConfig, PlotConfig
+from pySimBlocks.blocks.operators import Gain, Sum, Delay
+from pySimBlocks.blocks.sources import WhiteNoise
+from pySimBlocks.project.plot_from_config import plot_from_config
+
+# 1. Create the blocks
+noise = WhiteNoise(name="noise", std=1.0)
+delay = Delay(name="delay")
+filtered = Sum("filtered", signs="++")
+alpha_gain = Gain(name="alpha", gain=0.1)
+complement = Gain(name="complement", gain=0.9)
+
+# 2. Build the model
+model = Model("Example")
+for block in [noise, delay, filtered, alpha_gain, complement]:
+    model.add_block(block)
+
+model.connect("noise", "out", "alpha", "in")
+model.connect("delay", "out", "complement", "in")
+model.connect("alpha", "out", "filtered", "in1")
+model.connect("complement", "out", "filtered", "in2")
+model.connect("filtered", "out", "delay", "in")
+
+# 3. Simulate the model
+sim_cfg = SimulationConfig(dt=0.05, T=30.)
+sim = Simulator(model, sim_cfg)
+logs = sim.run(logging=["noise.outputs.out", "filtered.outputs.out"])
+
+# 4. Plot the results
+plot_cfg = PlotConfig([
+    {"title": "Noisy signal vs Filtered",
+     "signals": ["noise.outputs.out", "filtered.outputs.out"],},
+    ])
+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)
+
+See [examples/quick_start/filter.py](./examples/quick_start/filter.py)
+to run the example yourself.
+
+### Graphical Editor
+
+The exact same model can be constructed visually using the graphical editor (as
+shown in the image above of this README).
+
+To open the graphical editor, run:
+```bash
+pysimblocks gui examples/quick_start/gui
+```
+
+The quick-start GUI project is stored in a single
+[examples/quick_start/gui/project.yaml](./examples/quick_start/gui/project.yaml) file.
+
+### Learning Resources
+
+
+#### Tutorials
+
+Three step-by-step tutorials are available detailed in the
+[guide](./docs/User_Guide/getting_started.md):
+
+  | | 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 |
+
+
+#### Other Examples
+
+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.)
+- Hardware and real-time use cases
+- Comparisons with external tools
+
+See [examples/README.md](./examples/README.md) for an overview.
+
+## Information
+
+### License
+
+pySimBlocks is licensed under [LGPL-3.0-or-later](./LICENSE.md).
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pysimblocks-0.1.0/README.md

@@ -0,0 +1,145 @@
+# pySimBlocks
+
+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 
+using either:
+
+- A pure Python API
+- A graphical editor (PySide6)
+- YAML project configuration
+- 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
+
+## Installation
+
+### From GitHub
+
+Install directly from GitHub using pip:
+```
+pip install git+https://github.com/AlessandriniAntoine/pySimBlocks
+```
+
+### Locally
+
+Clone the repository and install locally:
+```
+git clone https://github.com/AlessandriniAntoine/pySimBlocks.git
+cd pySimBlocks
+pip install .
+```
+
+## Getting Started
+
+### Quick Example
+
+The following example models a simple first-order low-pass filter, defined by
+the difference equation:
+
+$$ y[k] =  \alpha x[k] + (1-\alpha) y[k-1] $$
+
+It can be implemented in pySimBlocks using the following code:
+
+```python
+from pySimBlocks import Model, Simulator, SimulationConfig, PlotConfig
+from pySimBlocks.blocks.operators import Gain, Sum, Delay
+from pySimBlocks.blocks.sources import WhiteNoise
+from pySimBlocks.project.plot_from_config import plot_from_config
+
+# 1. Create the blocks
+noise = WhiteNoise(name="noise", std=1.0)
+delay = Delay(name="delay")
+filtered = Sum("filtered", signs="++")
+alpha_gain = Gain(name="alpha", gain=0.1)
+complement = Gain(name="complement", gain=0.9)
+
+# 2. Build the model
+model = Model("Example")
+for block in [noise, delay, filtered, alpha_gain, complement]:
+    model.add_block(block)
+
+model.connect("noise", "out", "alpha", "in")
+model.connect("delay", "out", "complement", "in")
+model.connect("alpha", "out", "filtered", "in1")
+model.connect("complement", "out", "filtered", "in2")
+model.connect("filtered", "out", "delay", "in")
+
+# 3. Simulate the model
+sim_cfg = SimulationConfig(dt=0.05, T=30.)
+sim = Simulator(model, sim_cfg)
+logs = sim.run(logging=["noise.outputs.out", "filtered.outputs.out"])
+
+# 4. Plot the results
+plot_cfg = PlotConfig([
+    {"title": "Noisy signal vs Filtered",
+     "signals": ["noise.outputs.out", "filtered.outputs.out"],},
+    ])
+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)
+
+See [examples/quick_start/filter.py](./examples/quick_start/filter.py)
+to run the example yourself.
+
+### Graphical Editor
+
+The exact same model can be constructed visually using the graphical editor (as
+shown in the image above of this README).
+
+To open the graphical editor, run:
+```bash
+pysimblocks gui examples/quick_start/gui
+```
+
+The quick-start GUI project is stored in a single
+[examples/quick_start/gui/project.yaml](./examples/quick_start/gui/project.yaml) file.
+
+### Learning Resources
+
+
+#### Tutorials
+
+Three step-by-step tutorials are available detailed in the
+[guide](./docs/User_Guide/getting_started.md):
+
+  | | 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 |
+
+
+#### Other Examples
+
+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.)
+- Hardware and real-time use cases
+- Comparisons with external tools
+
+See [examples/README.md](./examples/README.md) for an overview.
+
+## Information
+
+### License
+
+pySimBlocks is licensed under [LGPL-3.0-or-later](./LICENSE.md).
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pysimblocks-0.1.0/examples/advanced/hardware/block_diagram.py

@@ -0,0 +1,162 @@
+import time
+from pathlib import Path
+
+import numpy as np
+import parameters as prm
+from emioapi import EmioMotors
+
+from pySimBlocks.project import load_simulator_from_project
+from pySimBlocks.real_time import RealTimeRunner
+
+try:
+    BASE_DIR = Path(__file__).parent.resolve()
+except Exception:
+    BASE_DIR = Path("")
+
+
+# ------------------------------------------------------------------------------
+# Process
+# ------------------------------------------------------------------------------
+def process_block_diagram(shared_markers_pos, shared_ref_ol, shared_ref_cl, 
+                          shared_control_mode, shared_update, 
+                          event_frame, event_measure):
+    """pySimBlocks runner process.
+    """
+    init_angles = np.array([0.7, 0, 0.7, 0])
+    motors = setup_motors(init_angles)
+
+    # init pySimBlocks runner
+    runner = setup_block_diagram()
+
+    # Initialize variables
+    measure = np.zeros((prm.nb_markers * 2, 1))
+    ref_ol = np.zeros((2, 1))
+    ref_cl = np.zeros((2, 1))
+    control_mode = np.zeros((1, 1))
+    command = np.zeros((2, 1))
+
+    # Initial time for dt measurement
+    t = time.perf_counter()
+    dt_init = 1/60
+    dt_list = []
+
+    while True:
+        event_frame.wait()
+        event_frame.clear()
+
+        send_motors_command(motors, command, init_angles)
+
+        event_measure.wait()
+        event_measure.clear()
+
+        if dt_init is not None:
+            t = time.perf_counter()
+            dt = dt_init
+            dt_init = None
+        else:
+            t2 = time.perf_counter()
+            dt = t2 - t
+            t = t2
+        dt_list.append(dt)
+
+        # data from camera
+        with shared_markers_pos.get_lock():
+            measure[:, 0] = shared_markers_pos[:]
+
+        with shared_update.get_lock():
+            if shared_update.value:
+                with shared_ref_ol.get_lock():
+                    ref_ol[:, 0] = shared_ref_ol[:]
+                with shared_ref_cl.get_lock():
+                    ref_cl[:, 0] = shared_ref_cl[:]
+                with shared_control_mode.get_lock():
+                    control_mode[0,0] = shared_control_mode.value
+                shared_update.value = False
+
+        outs = runner.tick(
+            inputs={
+                "Camera": measure,
+                "Ref_ol": ref_ol,
+                "Ref_cl": ref_cl,
+                "Mode": control_mode
+            },
+            dt=dt,
+            pace=False
+        )
+        command = outs["Cmd"]
+
+
+# ------------------------------------------------------------------------------
+# Helpers
+# ------------------------------------------------------------------------------
+def setup_block_diagram():
+    sim, _plot_cfg = load_simulator_from_project(BASE_DIR / "project.yaml")
+    runner = RealTimeRunner(
+        sim,
+        input_blocks=["Camera", "Ref_cl", "Ref_ol", "Mode"],
+        output_blocks=["Cmd"],
+        target_dt=1/60
+    )
+    runner.initialize()
+    return runner
+
+
+# -------------------------------------------------------
+def setup_motors(init_angles=[0, 0, 0, 0]):
+    motors = EmioMotors()
+    while not motors.open():
+        print("Waiting for motors to open...")
+        time.sleep(1)
+    print("Motors opened successfully.")
+    motors.position_p_gain = [2000, 800, 2000, 800]
+    motors.position_i_gain = [0, 0, 0, 0]
+    motors.position_d_gain = [50, 0, 50, 0]
+    time.sleep(1)
+    motors.angles = init_angles
+    return motors
+
+# -------------------------------------------------------
+def send_motors_command(motors, command, init_angles=np.array([0, 0, 0, 0])):
+    command = command.flatten()
+    motors.angles = [command[0] + init_angles[0], init_angles[1],
+                     command[1] + init_angles[2], init_angles[3]]
+
+# -------------------------------------------------------
+def get_motors_position(motors, init_angles=np.array([0, 0, 0, 0])):
+    motors_pos = np.array(motors.angles) - init_angles
+    return motors_pos[[0, 2]].reshape((2, 1))
+
+# ------------------------------------------------------------------------------
+# BLOCK DIAGRAM FUNCTIONS
+# ------------------------------------------------------------------------------
+def select_cmd(t, dt, u_cl, u_ol, mode):
+    try:
+        mode = mode.item()
+    except Exception:
+        return {"u": np.zeros((2,1))}
+
+    if mode == 0:
+        return {"u": u_ol}
+    elif mode == 1:
+        return {"u": u_cl}
+    else:
+        return {"u": np.zeros((2,1))}
+
+# -------------------------------------------------------
+def filter_first_order(t, dt, u, u_prev):
+    """Apply a first-order low-pass filter to the signal."""
+    if dt <= 0:
+        return {"u_filter" : np.zeros((2,1))}
+    cutoffFreq = 30.  # Cutoff frequency in Hz
+    samplingFreq = 1 / dt
+
+    timeConstant = 1 / (2 * np.pi * cutoffFreq)
+    samplingPeriod = 1 / samplingFreq
+    alpha = samplingPeriod / (timeConstant + samplingPeriod)
+    uf = alpha * u + (1 - alpha) * u_prev
+
+    return {"u_filter" : uf}
+
+
+if __name__ == "__main__":
+    setup_block_diagram()