pySimBlocks 0.1.0__py3-none-any.whl

pySimBlocks/gui/blocks/interfaces/external_output.py

@@ -0,0 +1,63 @@
+# ******************************************************************************
+#                                  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.gui.blocks.block_meta import BlockMeta
+from pySimBlocks.gui.blocks.parameter_meta import ParameterMeta
+from pySimBlocks.gui.blocks.port_meta import PortMeta
+
+
+class ExternalOutputMeta(BlockMeta):
+
+    def __init__(self):
+        self.name = "ExternalOutput"
+        self.category = "interfaces"
+        self.type = "external_output"
+        self.summary = "Pass-through block for external real-time commands/values."
+        self.description = (
+            "Pass-through block intended to expose a model command/value to an\n"
+            "external real-time application (motors, network, hardware driver, etc.).\n\n"
+            "This block does not perform any synchronization. It only enforces the\n"
+            "pySimBlocks signal convention (column vectors of shape (n,1))."
+        )
+
+        self.parameters = [
+            ParameterMeta(
+                name="sample_time",
+                type="float"
+            )
+        ]
+
+        self.inputs = [
+            PortMeta(
+                name="in",
+                display_as="in",
+                shape=["n", 1],
+                description="Model command/value signal."
+            )
+        ]
+
+        self.outputs = [
+            PortMeta(
+                name="out",
+                display_as="out",
+                shape=["m", 1],
+                description="External output signal."
+            )
+        ]

pySimBlocks/gui/blocks/observers/luenberger.py

@@ -0,0 +1,108 @@
+# ******************************************************************************
+#                                  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.gui.blocks.block_meta import BlockMeta
+from pySimBlocks.gui.blocks.parameter_meta import ParameterMeta
+from pySimBlocks.gui.blocks.port_meta import PortMeta
+
+
+class LuenbergerMeta(BlockMeta):
+
+    def __init__(self):
+        self.name = "Luenberger"
+        self.category = "observers"
+        self.type = "luenberger"
+        self.summary = "Discrete-time Luenberger state observer."
+        self.description = (
+            "Implements the discrete-time observer equations:\n"
+            "$$\n"
+            "x̂[k+1] = A x̂[k] + B u[k] + L (y[k] - C x̂[k])\n"
+            "$$\n"
+            "$$\n"
+            "ŷ[k] = C x̂[k]\n"
+            "$$\n"
+        )
+
+        self.parameters = [
+            ParameterMeta(
+                name="A",
+                type="matrix",
+                required=True,
+                description="System state matrix."
+            ),
+            ParameterMeta(
+                name="B",
+                type="matrix",
+                required=True,
+                description="Input matrix."
+            ),
+            ParameterMeta(
+                name="C",
+                type="matrix",
+                required=True,
+                description="Output matrix."
+            ),
+            ParameterMeta(
+                name="L",
+                type="matrix",
+                required=True,
+                description="Observer gain matrix."
+            ),
+            ParameterMeta(
+                name="x0",
+                type="vector",
+                description="Initial estimated state."
+            ),
+            ParameterMeta(
+                name="sample_time",
+                type="float",
+                description="Block execution period."
+            ),
+        ]
+
+        self.inputs = [
+            PortMeta(
+                name="u",
+                display_as="u",
+                shape=["m", 1],
+                description="Control input."
+            ),
+            PortMeta(
+                name="y",
+                display_as="y",
+                shape=["p", 1],
+                description="Measured output."
+            ),
+        ]
+
+        self.outputs = [
+            PortMeta(
+                name="x_hat",
+                display_as="x_hat",
+                shape=["n", 1],
+                description="Estimated state vector."
+            ),
+            PortMeta(
+                name="y_hat",
+                display_as="y_hat",
+                shape=["p", 1],
+                description="Estimated output."
+            ),
+        ]

pySimBlocks/gui/blocks/operators/algebraic_function.py

@@ -0,0 +1,232 @@
+# ******************************************************************************
+#                                  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 os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Literal
+
+from PySide6.QtWidgets import QFormLayout, QLabel, QLineEdit, QPushButton
+
+from pySimBlocks.gui.blocks.block_meta import BlockMeta, ParameterMeta
+from pySimBlocks.gui.blocks.port_meta import PortMeta
+from pySimBlocks.gui.models import BlockInstance, PortInstance
+
+
+class AlgebraicFunctionMeta(BlockMeta):
+
+    def __init__(self):
+        self.name = "AlgebraicFunction"
+        self.category = "operators"
+        self.type = "algebraic_function"
+        self.summary = "User-defined stateless algebraic function implemented in Python."
+        self.description = (
+            "This block evaluates a user-provided Python function of the form:\n\n"
+            "    y = g(t, dt, u1, u2, ...)\n\n"
+            "The function is loaded from an external Python file and executed at each\n"
+            "simulation step. Input and output ports are explicitly declared via\n"
+            "`input_keys` and `output_keys`.\n\n"
+            "This block is stateless and has direct feedthrough."
+        )
+
+        self.parameters = [
+            ParameterMeta(
+                name="file_path",
+                type="string",
+                required=True,
+                description="Path to the Python file containing the function relative to the project.yaml file."
+            ),
+            ParameterMeta(
+                name="function_name",
+                type="string",
+                required=True,
+                description="Name of the function to call inside the Python file."
+            ),
+            ParameterMeta(
+                name="input_keys",
+                type="list[string]",
+                required=True,
+                description="List of input port names. These must match the function arguments after (t, dt)."
+            ),
+            ParameterMeta(
+                name="output_keys",
+                type="list[string]",
+                required=True,
+                description="List of output port names. The function must return a dict with exactly these keys."
+            ),
+            ParameterMeta(
+                name="sample_time",
+                type="float",
+                description="Optional execution period of the block."
+            ),
+        ]
+
+        self.inputs = [
+            PortMeta(
+                name="in",
+                display_as="",
+                shape=[],
+            )
+        ]
+
+        self.outputs = [
+            PortMeta(
+                name="out",
+                display_as="",
+                shape=[],
+            )
+        ]
+
+
+    # --------------------------------------------------------------------------
+    # Port resolution
+    # --------------------------------------------------------------------------
+    def resolve_port_group(
+        self,
+        port_meta: PortMeta,
+        direction: Literal['input', 'output'],
+        instance: "BlockInstance"
+    ) -> list["PortInstance"]:
+
+        ports = []
+        if direction == "input":
+            keys = instance.parameters.get("input_keys", [])
+            if keys is None:
+                return []
+            for key in keys:
+                ports.append(
+                    PortInstance(
+                        name=f"{key}",
+                        display_as=key,
+                        direction="input",
+                        block=instance
+                    )
+                )
+            return ports
+
+        elif direction == "output":
+            keys = instance.parameters.get("output_keys", [])
+            if keys is None:
+                return []
+            for key in keys:
+                ports.append(
+                    PortInstance(
+                        name=f"{key}",
+                        display_as=key,
+                        direction="output",
+                        block=instance
+                    )
+                )
+            return ports
+
+        return super().resolve_port_group(port_meta, direction, instance)
+
+    # --------------------------------------------------------------------------
+    # Dialog methods
+    # --------------------------------------------------------------------------
+    def build_param(
+        self,
+        session,
+        form: QFormLayout,
+        readonly: bool = False,
+    ):
+        # --- Block name ---
+        name_edit = QLineEdit(session.instance.name)
+        name_edit.textChanged.connect(
+            lambda val: self._on_param_changed(val, "name", session, readonly)
+        )
+        form.addRow(QLabel("Block name:"), name_edit)
+        if readonly:
+            name_edit.setReadOnly(True)
+        session.name_edit = name_edit
+
+        # --- Parameters ---
+        for pmeta in self.parameters:
+            if pmeta.name == "file_path":
+                self.build_file_param_row(
+                    session,
+                    form,
+                    pmeta,
+                    readonly=readonly,
+                    file_filter="Python files (*.py);;All files (*)",
+                )
+                continue
+
+            label, widget = self._create_param_row(session, pmeta, readonly)
+            if widget is None:
+                continue
+            if readonly:
+                self._set_readonly_style(widget)
+
+            form.addRow(label, widget)
+            session.param_widgets[pmeta.name] = widget
+            session.param_labels[pmeta.name] = label
+
+    # ------------------------------------------------------
+    def build_post_param(self, session, form: QFormLayout, readonly: bool = False):
+        open_btn = QPushButton("Open file")
+        open_btn.clicked.connect(lambda: self._open_file_from_session(session))
+        form.addRow(QLabel(""), open_btn)
+        session.open_file_btn = open_btn
+        self._refresh_open_button_state(session)
+
+    # ------------------------------------------------------
+    def refresh_form(self, session):
+        super().refresh_form(session)
+        self._refresh_open_button_state(session)
+
+    # ------------------------------------------------------
+    def _resolve_file_path(self, session) -> Path | None:
+        raw = session.local_params.get("file_path")
+        if not raw:
+            return None
+
+        path = Path(str(raw)).expanduser()
+        if not path.is_absolute() and session.project_dir is not None:
+            path = (session.project_dir / path).resolve()
+        return path
+
+    # ------------------------------------------------------
+    def _refresh_open_button_state(self, session) -> None:
+        btn = getattr(session, "open_file_btn", None)
+        if btn is None:
+            return
+
+        target = self._resolve_file_path(session)
+        exists = target is not None and target.is_file()
+        btn.setEnabled(exists)
+        if exists:
+            btn.setToolTip(str(target))
+        else:
+            btn.setToolTip("Set a valid existing file_path to open the file.")
+
+    # ------------------------------------------------------
+    def _open_file_from_session(self, session) -> None:
+        target = self._resolve_file_path(session)
+        if target is None or not target.is_file():
+            return
+
+        if sys.platform.startswith("darwin"):
+            subprocess.Popen(["open", str(target)])
+        elif os.name == "nt":
+            os.startfile(str(target))
+        else:
+            subprocess.Popen(["xdg-open", str(target)])

pySimBlocks/gui/blocks/operators/dead_zone.py

@@ -0,0 +1,79 @@
+# ******************************************************************************
+#                                  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.gui.blocks.block_meta import BlockMeta
+from pySimBlocks.gui.blocks.parameter_meta import ParameterMeta
+from pySimBlocks.gui.blocks.port_meta import PortMeta
+
+
+class DeadZoneMeta(BlockMeta):
+
+    def __init__(self):
+        self.name = "DeadZone"
+        self.category = "operators"
+        self.type = "dead_zone"
+        self.summary = "Discrete-time dead zone operator."
+        self.description = (
+            "Applies a dead-zone nonlinearity to the input signal:\n"
+            "$$\n"
+            "y = 0 \\quad \\text{if } \\text{lower\\_bound} \\le u \\le \\text{upper\\_bound}\n"
+            "$$\n"
+            "$$\n"
+            "y = u - \\text{upper\\_bound} \\quad \\text{if } u > \\text{upper\\_bound}\n"
+            "$$\n"
+            "$$\n"
+            "y = u - \\text{lower\\_bound} \\quad \\text{if } u < \\text{lower\\_bound}\n"
+            "$$\n"
+        )
+
+        self.parameters = [
+            ParameterMeta(
+                name="lower_bound",
+                type="scalar | vector | matrix",
+                default=0.0
+            ),
+            ParameterMeta(
+                name="upper_bound",
+                type="scalar | vector | matrix",
+                default=0.0
+            ),
+            ParameterMeta(
+                name="sample_time",
+                type="float"
+            )
+        ]
+
+        self.inputs = [
+            PortMeta(
+                name="in",
+                display_as="in",
+                shape=["n", "m"],
+                description="Input signal."
+            )
+        ]
+
+        self.outputs = [
+            PortMeta(
+                name="out",
+                display_as="out",
+                shape=["n", "m"],
+                description="Output signal after dead-zone operation."
+            )
+        ]

pySimBlocks/gui/blocks/operators/delay.py

@@ -0,0 +1,79 @@
+# ******************************************************************************
+#                                  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.gui.blocks.block_meta import BlockMeta
+from pySimBlocks.gui.blocks.parameter_meta import ParameterMeta
+from pySimBlocks.gui.blocks.port_meta import PortMeta
+
+
+class DelayMeta(BlockMeta):
+
+    def __init__(self):
+        self.name = "Delay"
+        self.category = "operators"
+        self.type = "delay"
+        self.summary = "N-step discrete-time delay block."
+        self.description = (
+            "Implements a discrete delay of $N$ simulation steps:\n"
+            "$$\n"
+            "y[k] = u[k - N]\n"
+            "$$\n"
+        )
+
+        self.parameters = [
+            ParameterMeta(
+                name="num_delays",
+                type="int",
+                autofill=True,
+                default=1
+            ),
+            ParameterMeta(
+                name="initial_output",
+                type="scalar | vector | matrix"
+            ),
+            ParameterMeta(
+                name="sample_time",
+                type="float"
+            )
+        ]
+
+        self.inputs = [
+            PortMeta(
+                name="in",
+                display_as="in",
+                shape=["n", "m"],
+                description="Input signal."
+            ),
+            PortMeta(
+                name="reset",
+                display_as="reset",
+                shape=[],
+                description="Reset signal (0/1). When high (1), the delay state is reset to the initial output value."
+            )
+        ]
+
+        self.outputs = [
+            PortMeta(
+                name="out",
+                display_as="out",
+                shape=["n", "m"],
+                description="Delayed output signal."
+            )
+        ]

pySimBlocks/gui/blocks/operators/demux.py

@@ -0,0 +1,98 @@
+# ******************************************************************************
+#                                  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 typing import Literal
+
+from pySimBlocks.gui.blocks.block_meta import BlockMeta
+from pySimBlocks.gui.blocks.parameter_meta import ParameterMeta
+from pySimBlocks.gui.blocks.port_meta import PortMeta
+from pySimBlocks.gui.models import BlockInstance, PortInstance
+
+
+class DemuxMeta(BlockMeta):
+
+    def __init__(self):
+        self.name = "Demux"
+        self.category = "operators"
+        self.type = "demux"
+        self.summary = "Vector split block (inverse of Mux)."
+        self.description = (
+            "Splits one input column vector into multiple output segments.\n"
+            "For input length $n$ and $p$ outputs:\n"
+            "$$\n"
+            "q = n // p, \\quad m = n \\% p\n"
+            "$$\n"
+            "The first $m$ outputs have $(q+1)$ elements and the remaining\n"
+            "$(p-m)$ outputs have $q$ elements.\n"
+        )
+
+        self.parameters = [
+            ParameterMeta(
+                name="num_outputs",
+                type="int",
+                autofill=True,
+                default=2
+            ),
+            ParameterMeta(
+                name="sample_time",
+                type="float"
+            )
+        ]
+
+        self.inputs = [
+            PortMeta(
+                name="in",
+                display_as="in",
+                shape=["n", 1],
+                description="Input column vector to split."
+            )
+        ]
+
+        self.outputs = [
+            PortMeta(
+                name="out",
+                display_as="",
+                shape=["k", 1],
+                description="Output vector segments."
+            )
+        ]
+
+    def resolve_port_group(
+        self,
+        port_meta: PortMeta,
+        direction: Literal["input", "output"],
+        instance: "BlockInstance"
+    ) -> list["PortInstance"]:
+
+        if direction == "output" and port_meta.name == "out":
+            num_outputs = instance.parameters.get("num_outputs", 0)
+            ports = []
+            for i in range(1, num_outputs + 1):
+                ports.append(
+                    PortInstance(
+                        name=f"{port_meta.name}{i}",
+                        display_as=f"{i}",
+                        direction="output",
+                        block=instance
+                    )
+                )
+            return ports
+
+        return super().resolve_port_group(port_meta, direction, instance)