pySimBlocks 0.1.0__py3-none-any.whl

pySimBlocks/docs/blocks/sources/sinusoidal.md

@@ -0,0 +1,60 @@
+# Sinusoidal
+
+## Summary
+
+The **Sinusoidal** block generates sinusoidal signals with configurable
+amplitude, frequency, phase and offset for each output dimension.
+
+---
+
+## Mathematical definition
+
+For each output component $i$, the signal is defined as:
+
+$$
+y_i(t) = A_i \sin(2\pi f_i t + \varphi_i) + o_i
+$$
+
+where:
+- $A_i$ is the amplitude,
+- $f_i$ is the frequency in Hertz,
+- $\varphi_i$ is the phase shift,
+- $o_i$ is the constant offset.
+
+---
+
+## Parameters
+
+| Name        | Type | Description | Optional |
+|------------|-------------|-------------|-------------|
+| `amplitude` | scalar or vector or matrix | Sinusoidal amplitude. Can be a scalar or vector. | False |
+| `frequency` | scalar or vector or matrix | Sinusoidal frequency in Hertz. Can be a scalar or vector. | False |
+| `phase` | scalar or vector or matrix | Phase shift in radians. Default is zero. | True |
+| `offset` | scalar or vector or matrix | Constant offset added to the signal. Default is zero. | True |
+| `sample_time` | float | Block sample time. If omitted, the global simulation time step is used. | True |
+
+---
+
+## Inputs
+
+This block has **no inputs**.
+
+---
+
+## Outputs
+
+| Port | Description |
+|------|------------|
+| `out` | Constant output signal. |
+
+---
+
+## Notes
+
+- The block has no internal state.
+- Each output dimension may have its own frequency and phase.
+- Scalar parameters are automatically broadcast.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/sources/step.md

@@ -0,0 +1,63 @@
+# Step
+
+## Summary
+
+The **Step** block generates a signal that switches from an initial value
+to a final value at a specified time.
+
+---
+
+## Mathematical definition
+
+The step signal is defined as:
+
+$$
+y(t) =
+\begin{cases}
+y_{\text{before}}, & t < t_0 \\
+y_{\text{after}},  & t \geq t_0
+\end{cases}
+$$
+
+where:
+- $y_{\text{before}}$ is the value before the step,
+- $y_{\text{after}}$ is the value after the step,
+- $t_0$ is the step time.
+
+---
+
+## Parameters
+
+| Name        | Type | Description | Optional |
+|------------|-------------|-------------|-------------|
+| `value_before` | scalar or vector or matrix | Output value before the step time. Scalars are broadcast to all dimensions. | False |
+| `value_after` | scalar or vector or matrix | Output value after the step time. Must have the same dimension as `value_before`. | False |
+| `start_time` | float | Time at which the step occurs. | False |
+| `sample_time` | float | Block sample time. If omitted, the global simulation time step is used. | True |
+
+---
+
+## Inputs
+
+This block has **no inputs**.
+
+---
+
+## Outputs
+
+| Port | Description |
+|------|------------|
+| `out` | Constant output signal. |
+
+---
+
+## Notes
+
+- The block has no internal state.
+- A small numerical tolerance is used to ensure consistent switching
+  behavior on discrete time grids.
+- This block is typically used to generate reference signals.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/sources/white_noise.md

@@ -0,0 +1,58 @@
+# WhiteNoise
+
+## Summary
+
+The **WhiteNoise** block generates independent Gaussian noise samples
+for each output dimension at every simulation step.
+
+---
+
+## Mathematical definition
+
+For each output component $i$, the signal is defined as:
+
+$$
+y_i(t) \sim \mathcal{N}(\mu_i, \sigma_i^2)
+$$
+
+where:
+- $\mu_i$ is the mean,
+- $\sigma_i$ is the standard deviation.
+
+---
+
+## Parameters
+
+| Name        | Type | Description | Optional |
+|------------|-------------|-------------|-------------|
+| `mean` | scalar or vector or matrix | Mean value of the noise. Scalars are broadcast to all dimensions. Default is zero. | True |
+| `std` | scalar or vector or matrix | Standard deviation of the noise. Must be non-negative. Default is one. | True |
+| `seed` | integer | Random seed for reproducibility. If provided, the noise sequence is deterministic. | True |
+| `sample_time` | float | Block sample time. If omitted, the global simulation time step is used. | True |
+
+---
+
+## Inputs
+
+This block has **no inputs**.
+
+---
+
+## Outputs
+
+| Port | Description |
+|------|------------|
+| `out` | Gaussian noise output signal. |
+
+---
+
+## Notes
+
+- The block has no internal state.
+- Noise samples are drawn independently at each simulation step.
+- Each output dimension may have a different mean and standard deviation.
+- Scalar parameters are automatically broadcast.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/systems/linear_state_space.md

@@ -0,0 +1,66 @@
+# LinearStateSpace
+
+## Summary
+
+The **LinearStateSpace** block implements a discrete-time linear state-space system without direct feedthrough.
+
+---
+
+## Mathematical definition
+
+The system is defined by the equations:
+
+$$
+x[k+1] = A x[k] + B u[k]
+$$
+
+$$
+y[k] = C x[k]
+$$
+
+where:
+- $x[k]$ is the state vector,
+- $u[k]$ is the input vector,
+- $y[k]$ is the output vector.
+
+---
+
+## Parameters
+
+| Name        | Type | Description | Optional |
+|------------|-------------|-------------|-------------|
+| `A` | 2D array | State transition matrix of size (n, n). | False |
+| `B` | 2D array | Input matrix of size (n, m). | False |
+| `C` | 2D array | Output matrix of size (p, n). | False |
+| `x0` | 1D array | Initial state vector of size (n,). If omitted, the state is initialized to zero. | True |
+| `sample_time` | float | Block sample time. If omitted, the global simulation time step is used. | True |
+
+---
+
+## Inputs
+
+| Port | Description |
+|------|------------|
+| `u` | Input vector. |
+
+---
+
+## Outputs
+
+| Port | Description |
+|------|------------|
+| `x` | State vector. |
+| `y` | Output vector. |
+
+---
+
+## Notes
+
+- The block has internal state.
+- The system is strictly proper (no direct feedthrough).
+- Matrix $D$ is intentionally not supported to avoid algebraic loops.
+- The output is computed from the current state.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/systems/non_linear_state_space.md

@@ -0,0 +1,90 @@
+# Non Linear State Space
+
+## Summary
+
+The **NonLinearStateSpace** block represents a user-defined, discrete-time non linear
+state-space system.
+
+The system dynamics and outputs are defined by Python functions provided by the user,
+while the block itself enforces a strict execution and data-flow contract compatible
+with the pySimBlocks simulation semantics.
+
+---
+
+## Mathematical definition
+
+The block represents a discrete-time system of the form:
+
+$$
+\begin{aligned}
+x[k+1] &= f\bigl(t_k,\ \Delta t_k,\ x[k],\ u_1[k],\dots,u_m[k]\bigr) \\
+y[k]   &= g\bigl(t_k,\ \Delta t_k,\ x[k]\bigr)
+\end{aligned}
+$$
+
+where:
+- $ x[k] \in \mathbb{R}^n $ is the state vector,
+- $ u_i[k] $ are the input signals,
+- $ y[k] $ is the output signal,
+- $ t_k $ is the current simulation time,
+- $ \Delta t_k $ is the elapsed time since the previous activation.
+
+The functions $ f $ and $ g $ are implemented by the user and executed at each
+block activation.
+
+---
+
+## Parameters
+
+| Name | Type | Description | Required |
+|------|------|-------------|----------|
+| `file_path` | string | Path to the Python file containing the user-defined functions. | Yes |
+| `state_function_name` | string | Name of the state update function implementing $ f $. | Yes |
+| `output_function_name` | string | Name of the output function implementing  $ g $. | Yes |
+| `input_keys` | list[string] | Names of the input ports $ u_1, \dots, u_m $. | Yes |
+| `output_keys` | list[string] | Names of the output ports returned by the output function. | Yes |
+| `x0` | vector | Initial state vector \(x[0]\). | Yes |
+| `sample_time` | float | Execution period of the block. If omitted, the global simulation time step is used. | No | 
+
+--- 
+
+## Inputs 
+
+Inputs are dynamically defined by `input_keys`. 
+
+- Each input must be connected. 
+- Each input is a NumPy array of shape $ (n,1) $. 
+
+--- 
+
+## Outputs 
+
+Outputs are dynamically defined by `output_keys`. 
+
+- Each output is a NumPy array of shape $ (n,1) $. 
+- Outputs depend only on the current state (no direct feedthrough). 
+
+--- 
+
+## Execution semantics
+
+- The block **has internal state**.
+- The block **has no direct feedthrough**.
+- Execution follows the standard two-phase discrete-time semantics:
+  1. Outputs are computed from the current state.
+  2. The next state is computed from the current state and current inputs.
+
+---
+
+## Notes
+
+- This block provides a generic interface for embedding non linear models into a
+  block-diagram simulation.
+- The numerical stability and correctness of the system are the responsibility of
+  the user-defined functions.
+- Advanced users may instantiate this block directly from Python using callable
+  functions instead of file-based definitions.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/systems/polytopic_state_space.md

@@ -0,0 +1,72 @@
+# PolytopicStateSpace
+
+## Summary
+
+The **PolytopicStateSpace** block implements a discrete-time polytopic state-space model without direct feedthrough.
+
+---
+
+## Mathematical definition
+
+The system is defined by:
+
+$$
+x[k+1] = \sum_{i=1}^{r} w_i[k] (A_i x[k] + B_i u[k])
+$$
+
+$$
+y[k] = C x[k]
+$$
+
+where:
+- $x[k] \in \mathbb{R}^{nx}$ is the state vector,
+- $u[k] \in \mathbb{R}^{nu}$ is the input vector,
+- $w[k] \in \mathbb{R}^{r}$ is the vertex weight vector,
+- $y[k] \in \mathbb{R}^{ny}$ is the output vector.
+
+The block expects:
+- $A \in \mathbb{R}^{nx \times (r\,nx)}$ as $[A_1 \ \cdots \ A_r]$,
+- $B \in \mathbb{R}^{nx \times (r\,nu)}$ as $[B_1 \ \cdots \ B_r]$,
+- $C \in \mathbb{R}^{ny \times nx}$.
+
+---
+
+## Parameters
+
+| Name        | Type | Description | Optional |
+|------------|-------------|-------------|-------------|
+| `A` | 2D array | Stacked state matrix of size (nx, r*nx): `[A1, ..., Ar]`. | False |
+| `B` | 2D array | Stacked input matrix of size (nx, r*nu): `[B1, ..., Br]`. | False |
+| `C` | 2D array | Output matrix of size (ny, nx). | False |
+| `x0` | 1D array | Initial state vector of size (nx,). If omitted, initialized to zero. | True |
+| `sample_time` | float | Block sample time. If omitted, the global simulation time step is used. | True |
+
+---
+
+## Inputs
+
+| Port | Description |
+|------|------------|
+| `w` | Weight vector of shape (r,1) (or `(r,)` as parameterized array). |
+| `u` | Input vector of shape (nu,1). |
+
+---
+
+## Outputs
+
+| Port | Description |
+|------|------------|
+| `x` | State vector of shape (nx,1). |
+| `y` | Output vector of shape (ny,1). |
+
+---
+
+## Notes
+
+- The block has internal state.
+- The system is strictly proper (no direct feedthrough).
+- Input dimensions are validated at runtime.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/systems/sofa/sofa_exchange_i_o.md

@@ -0,0 +1,63 @@
+# SofaExchangeIO
+
+## Summary
+
+The **SofaExchangeIO** block provides an interface between a pySimBlocks model
+and an external SOFA controller by exposing dynamic input and output ports.
+
+---
+
+## Description
+
+This block does **not** execute a SOFA simulation.
+It must **only** be used when SOFA will be running the simulation loop.
+It acts only as a data exchange interface between:
+
+- a pySimBlocks control model, and
+- a SOFA controller that provides inputs and consumes outputs.
+
+The block is fully stateless and does not modify the signals it exchanges.
+
+---
+
+## Parameters
+
+| Name | Type | Description | Required |
+|------|------|-------------|----------|
+| `scene_file` | string | Path to the SOFA scene file to be simulated. | Yes |
+| `input_keys` | list[string] | Names of the input ports $ u_1, \dots, u_m $. | Yes |
+| `output_keys` | list[string] | Names of the output ports returned by the output function. | Yes |
+| `sample_time` | float | Execution period of the block. If omitted, the global simulation time step is used. | No | 
+
+---
+
+## Inputs
+
+Inputs are dynamically defined by `input_keys`.
+
+- Each input must be connected.
+- Each input is a NumPy array of shape (n, 1).
+- Each input corresponds to a command sent to the SOFA controller.
+
+---
+
+## Outputs
+
+Outputs are dynamically defined by `output_keys`.
+
+- Each output is a NumPy array of shape (n, 1).
+- Each output corresponds to a measurement extracted from the SOFA scene.
+- Each output is produced by the pySimBlocks controller logic.
+
+---
+
+## Notes
+
+- This block does not run a SOFA simulation.
+- It is intended to be embedded inside a SOFA controller.
+- The block has no internal state.
+- All data validation is performed at runtime.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/systems/sofa/sofa_plant.md

@@ -0,0 +1,62 @@
+# SofaPlant
+
+## Description
+
+The **SofaPlant** block embeds a [SOFA](https://www.sofa-framework.org/) simulation as a dynamic system inside a pySimBlocks model.
+
+Unlike *SofaExchangeIO*, which is used inside a SOFA controller, **SofaPlant runs the SOFA simulation itself** in a separate worker process and exposes it as a discrete-time plant.
+However, this block can be used in a diagram that will be run in both simulations with pySimBlocks as master and SOFA as master. In the second case, the block is automatically replaced by a *SofaExchangeIO* block.
+
+At each simulation step:
+- control inputs are sent to SOFA,
+- the scene advances by one time increment,
+- updated outputs are returned to pySimBlocks.
+
+## Mathematical abstraction
+
+The block can be seen as a discrete-time nonlinear system:
+
+$$
+y[k+1] = \mathcal{F}_{\text{SOFA}}(y[k], u[k])
+$$
+
+where:
+- $ u[k] $ are the inputs defined by `input_keys`,
+- $ y[k] $ are the outputs defined by `output_keys`,
+- $ \mathcal{F}_{\text{SOFA}} $ represents one SOFA simulation step.
+
+---
+
+## Parameters
+
+| Name | Type | Description | Required |
+|------|------|-------------|----------|
+| `scene_file` | string | Path to the SOFA scene file to be simulated. | Yes |
+| `input_keys` | list[string] | Names of the input ports $ u_1, \dots, u_m $. | Yes |
+| `output_keys` | list[string] | Names of the output ports returned by the output function. | Yes |
+| `sample_time` | float | Execution period of the block. If omitted, the global simulation time step is used. | No | 
+
+## Inputs
+
+Inputs are dynamically defined by `input_keys`.  
+
+- Each input must be connected.
+- Each input is a NumPy array of shape (n, 1).
+- Each input corresponds to a command sent to the SOFA controller.
+
+## Outputs
+
+Outputs are ynamically defined by `output_keys`.
+
+- Each output is a NumPy array of shape (n, 1).
+- Each output corresponds to a measurement extracted from the SOFA scene.
+
+## Execution semantics
+
+- The block has internal state.
+- There is no direct feedthrough.
+- One SOFA simulation step is executed per block activation.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/gui/__init__.py

@@ -0,0 +1,20 @@
+# ******************************************************************************
+#                                  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/gui/addons/__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/gui/addons/sofa/__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
+# ******************************************************************************