pySimBlocks 0.1.0__py3-none-any.whl

pySimBlocks/docs/blocks/operators/algebraic_function.md

@@ -0,0 +1,76 @@
+# Algebraic Function
+
+## Summary
+
+The **Algebraic Function** block evaluates a user-defined, stateless Python
+function at each simulation step.
+
+It implements an algebraic mapping between input and output signals, possibly
+depending on the current simulation time.
+
+The python function that defines the algebraic relation must always return:
+- A dictionary containing the output signals, with keys matching the `output_keys` parameter.
+- It should always work and return outputs of the correct shape when called with any inputs.
+
+---
+
+## Mathematical definition
+
+The block implements a general algebraic relation of the form:
+
+$$
+y[k] = g(t_k, \Delta t_k, u_1[k], u_2[k], \dots)
+$$
+
+where:
+- $ u_i[k] $ are the input signals at step $k$,
+- $ y[k] $ is the output signal,
+- $ t_k $ is the current simulation time,
+- $ \Delta t_k $ is the time step since the previous activation.
+
+The function $ g $ is provided by the user as a Python function.
+
+---
+
+## Parameters
+
+| Name | Type | Description | Required |
+|------|------|-------------|----------|
+| `file_path` | string | Path to the Python file containing the user-defined function. | Yes |
+| `function_name` | string | Name of the function $ g $  to call inside the block. | 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) $. 
+
+--- 
+
+## Outputs 
+
+Outputs are dynamically defined by `output_keys`. 
+
+- Each output is a NumPy array of shape $ (n,1) $. 
+
+---
+
+## Execution semantics
+
+- The block is stateless.
+- The block has direct feedthrough.
+- At each activation, the function is evaluated as:
+
+```python
+g(t, dt, **inputs)
+```
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/operators/dead_zone.md

@@ -0,0 +1,67 @@
+# DeadZone
+
+## Summary
+
+The **DeadZone** block applies a dead-zone nonlinearity to its input signal.
+Values within a specified interval around zero are suppressed, while values
+outside the interval are shifted accordingly.
+
+---
+
+## Mathematical definition
+
+For each output component $i$, the signal is defined as:
+
+$$
+y_i =
+\begin{cases}
+0 & \text{if } u_{\min,i} \le u_i \le u_{\max,i} \\
+u_i - u_{\max,i} & \text{if } u_i > u_{\max,i} \\
+u_i - u_{\min,i} & \text{if } u_i < u_{\min,i}
+\end{cases}
+$$
+
+where:
+- $u_{\min,i}$ is the lower bound of the dead zone,
+- $u_{\max,i}$ is the upper bound of the dead zone.
+
+
+---
+
+## Parameters
+
+| Name        | Type | Description | Optional |
+|------------|-------------|-------------|-------------|
+| `lower_bound` | scalar or vector or matrix | Lower bound of the dead zone. Must be less than or equal to zero. Default is zero. | True |
+| `upper_bound` | scalar or vector or matrix | Upper bound of the dead zone. Must be greater than or equal to zero. Default is zero. | True |
+| `sample_time` | float | Block sample time. If omitted, the global simulation time step is used. | True |
+
+---
+
+## Inputs
+
+| Port | Description |
+|------|------------|
+| `in` | Input signal to be processed. |
+
+---
+
+## Outputs
+
+| Port | Description |
+|------|------------|
+| `out` | Output signal after dead-zone transformation. |
+
+---
+
+## Notes
+
+- The block has no internal state.
+- The block has direct feedthrough.
+- Bounds are broadcast to match the input dimension when needed.
+- The dead zone must always include zero.
+- This block is equivalent to the Simulink **Dead Zone** block.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/operators/delay.md

@@ -0,0 +1,76 @@
+# Delay
+
+## Summary
+
+The **Delay** block outputs a delayed version of its input signal by a fixed
+number of discrete simulation steps.
+
+The block can be reset to an initial output value via an optional reset input.
+This reset is a level-triggered signal: when the reset input is true (non-zero), the delay buffer is reset to the initial output value.
+It is not a rising-edge or falling-edge trigger.
+
+---
+
+## Mathematical definition
+
+For a delay of $N$ steps, the block implements:
+
+$$
+y[k] = u[k - N]
+$$
+
+where:
+- $u[k]$ is the input signal,
+- $y[k]$ is the delayed output signal.
+
+---
+
+## Parameters
+
+| Name        | Type | Description | Optional |
+|------------|-------------|-------------|-------------|
+| `num_delays` | integer | Number of discrete delay steps. Default is 1. | True |
+| `initial_output` | scalar or vector or matrix | Initial value to fill the delay buffer. If not provided, the buffer is initialized as zero. | True |
+| `sample_time` | float | Block sample time. If omitted, the global simulation time step is used. | True |
+
+---
+
+## Inputs
+
+| Port | Description |
+|------|------------|
+| `in` | Input signal to be delayed. |
+| `reset` | Optional reset signal. When true (non-zero), the delay buffer is reset to the initial output value. |
+
+---
+
+## Outputs
+
+
+| Port | Description |
+|------|------------|
+| `out` | Delayed output signal. |
+
+---
+
+## Notes
+
+- The block has internal state.
+- The block has no direct feedthrough.
+- The delay buffer stores the last $N$ input samples.
+- Output dimensions are inferred from the first valid input if not explicitly
+  initialized.
+- This block is equivalent to the Simulink **Delay** / **Unit Delay** block.
+- Policy:
+    + Signals are 2D arrays.
+    + Buffer always exists (never None).
+    + Shape is fixed either:
+        * immediately if initial_output is non-scalar 2D (shape != (1,1))
+        * otherwise at the first non-None input seen by the block
+    + If buffer is still "unfixed" and currently scalar (1,1), it can be
+      broadcast ONCE to match the first input shape.
+    + After shape is fixed, any shape mismatch raises.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/operators/demux.md

@@ -0,0 +1,64 @@
+# Demux
+
+## Summary
+
+The **Demux** block splits one input column vector into multiple output
+column vectors.
+
+---
+
+## Mathematical definition
+
+Given an input vector $\mathrm{in} \in \mathbb{R}^{n \times 1}$ and
+$p$ outputs:
+
+$$
+q = \left\lfloor \frac{n}{p} \right\rfloor, \quad
+m = n \bmod p
+$$
+
+The output segments are:
+- the first $m$ outputs have size $(q+1, 1)$,
+- the remaining $(p-m)$ outputs have size $(q, 1)$.
+
+This corresponds to an even split with the remainder distributed on the
+first outputs.
+
+---
+
+## Parameters
+
+| Name        | Type | Description | Optional |
+|------------|-------------|-------------|-------------|
+| `num_outputs` | integer | Number of output ports to create. | True |
+| `sample_time` | float | Block sample time. If omitted, the global simulation time step is used. | True |
+
+---
+
+## Inputs
+
+| Port | Description |
+|------|------------|
+| `in` | Input column vector of shape $(n,1)$. |
+
+---
+
+## Outputs
+
+| Port | Description |
+|------|------------|
+| `out1 … outP` | Output vector segments according to the split rule above. |
+
+---
+
+## Notes
+
+- The block has no internal state.
+- The block has direct feedthrough.
+- Input must be a column vector of shape $(n,1)$.
+- The parameter `num_outputs` must satisfy $1 \le p \le n$.
+- This block is equivalent to the Simulink **Demux** concept for vector splitting.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/operators/discrete_derivator.md

@@ -0,0 +1,61 @@
+# DiscreteDerivator
+
+## Summary
+
+The **DiscreteDerivator** block estimates the discrete-time derivative of an
+input signal using a backward finite-difference scheme.
+
+---
+
+## Mathematical definition
+
+The derivative is approximated as:
+
+$$
+y[k] = \frac{u[k] - u[k-1]}{dt}
+$$
+
+where:
+- $u[k]$ is the current input sample,
+- $u[k-1]$ is the previous input sample,
+- $dt$ is the simulation time step.
+
+---
+
+## Parameters
+
+| Name        | Type | Description | Optional |
+|------------|-------------|-------------|-------------|
+| `initial_output` | scalar or vector or matrix | Initial value to fill the delay buffer. If not provided, the buffer is initialized as zero. | True |
+| `sample_time` | float | Block sample time. If omitted, the global simulation time step is used. | True |
+
+---
+
+## Inputs
+
+| Port | Description |
+|------|------------|
+| `in` | Input signal for derivative estimation. |
+
+---
+
+## Outputs
+
+| Port | Description |
+|------|------------|
+| `out` | Estimated discrete-time derivative of the input signal. |
+
+---
+
+## Notes
+
+- The block has internal state.
+- The block has direct feedthrough.
+- A backward difference scheme is used because future input values are not
+  accessible.
+- Input dimension changes between steps are not allowed.
+- This block matches Simulink **Derivative** behavior in discrete-time mode.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/operators/discrete_integrator.md

@@ -0,0 +1,87 @@
+# DiscreteIntegrator
+
+## Summary
+
+The **DiscreteIntegrator** block integrates an input signal over time using
+a discrete-time numerical integration scheme.
+
+---
+
+## Mathematical definition
+
+The integrator state evolves according to:
+
+$$
+x[k+1] = x[k] + dt * u[k]
+$$
+
+The output depends on the selected integration method.
+
+### Euler forward
+
+$$
+y[k] = x[k]
+$$
+
+### Euler backward
+
+$$
+y[k] = x[k] + dt * u[k]
+$$
+
+where:
+- $u[k]$ is the input signal,
+- $x[k]$ is the internal integrated state,
+- $dt$ is the simulation time step.
+
+---
+
+## Parameters
+
+| Name        | Type | Description | Optional |
+|------------|-------------|-------------|-------------|
+| `initial_state` | scalar or vector or matrix | Initial value of the integrated state. If omitted, the state is initialized as a zero vector. | True |
+| `method` | string | Numerical integration method: `euler forward` or `euler backward`. | True |
+| `sample_time` | float | Block sample time. If omitted, the global simulation time step is used. | True |
+
+---
+
+## Inputs
+
+| Port | Description |
+|------|------------|
+| `in` | Input signal to be integrated. |
+
+---
+
+## Outputs
+
+| Port | Description |
+|------|------------|
+| `out` | Integrated output signal. |
+
+---
+
+## Notes
+
+- The block has internal state.
+- Direct feedthrough depends on the integration method:
+  - no direct feedthrough for forward Euler,
+  - direct feedthrough for backward Euler.
+- The integrator uses a fixed-step discrete formulation.
+- Input dimension changes between steps are not allowed.
+- This block is equivalent to the Simulink **Discrete-Time Integrator** block.
+- Policy:
+    + Never propagate None: output is always a 2D array (at least (1,1)).
+    + Shape is NOT frozen while we are in placeholder shape (1,1) and no explicit
+      non-scalar initial_state was given.
+    + As soon as a non-scalar input appears (shape != (1,1)), the shape becomes frozen.
+    + If initial_state is provided and non-scalar, it freezes the shape immediately.
+      If initial_state is scalar (1,1), it is treated as a placeholder: can be upgraded
+      once a non-scalar input appears.
+    + After shape is frozen, any non-scalar input shape mismatch raises ValueError.
+    + If shape is frozen to (m,n), scalar input (1,1) is broadcast to (m,n).
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/operators/gain.md

@@ -0,0 +1,97 @@
+# Gain Block
+
+## Description
+
+The **Gain** block applies a static transformation to its input signal using a gain **K**.
+
+Depending on the selected multiplication mode, it computes one of:
+
+- **Element-wise**:  
+  $$ y = K \odot u $$
+- **Left matrix product**:  
+  $$ y = K \cdot u $$
+- **Right matrix product**:  
+  $$ y = u \cdot K $$
+
+Where:
+- $u$ is the input signal (2D array),
+- $K$ is the gain,
+- $y$ is the output signal.
+
+---
+
+## Multiplication modes
+
+### 1) Element wise (K * u)
+
+Element-wise multiplication with strict shape rules (no implicit matrix product):
+
+- **K scalar**: `y = K * u`  
+  Works for any 2D `u` shape `(m,n)`.
+
+- **K vector (m,)**: `y = K[:,None] * u`  
+  Requires `u.shape[0] == m`. Output shape is `(m,n)`.
+
+- **K matrix (m,n)**: `y = K * u`  
+  Requires `u.shape == (m,n)`.
+
+Any other mismatch raises an error.
+
+---
+
+### 2) Matrix (K @ u)
+
+Left matrix product:
+
+- Requires **K is a 2D matrix** with shape `(p,m)`
+- Requires input `u` is 2D with shape `(m,ncols)`
+- Output `y` has shape `(p,ncols)`
+
+---
+
+### 3) Matrix (u @ K)
+
+Right matrix product:
+
+- Requires **K is a 2D matrix** with shape `(m,q)`
+- Requires input `u` is 2D with shape `(nrows,m)`
+- Output `y` has shape `(nrows,q)`
+
+---
+
+## Parameters
+
+| Name | Type | Description | Optional |
+|------|------|-------------|----------|
+| `gain` | scalar, vector (m,), or matrix (p,m) / (m,q) | Gain coefficient(s). | False |
+| `multiplication` | string enum | `"Element wise (K * u)"` \| `"Matrix (K @ u)"` \| `"Matrix (u @ K)"` | True (default: element-wise) |
+| `sample_time` | float | Block sample time. If omitted, the global simulation time step is used. | True |
+
+---
+
+## Inputs
+
+| Port | Description |
+|------|------------|
+| `in` | Input signal $u$ (**must be a 2D NumPy array**). |
+
+---
+
+## Outputs
+
+| Port | Description |
+|------|------------|
+| `out` | Output signal $y$ (2D array). |
+
+---
+
+## Notes
+
+- The Gain block is **stateless** and **direct feedthrough**.
+- Inputs must be **2D** (`ndim == 2`). No implicit reshape/flatten is applied.
+- Dimension mismatches raise an error.
+- This block is conceptually similar to Simulink **Gain**, but the multiplication behavior is made explicit via `multiplication`.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/operators/mux.md

@@ -0,0 +1,64 @@
+# Mux
+
+## Summary
+
+The **Mux** block concatenates multiple input column vectors vertically
+into a single output column vector.
+
+---
+
+## Mathematical definition
+
+Given $N$ input vectors $\mathrm{in}_i \in \mathbb{R}^{n_i \times 1}$,
+the output is defined as:
+
+$$
+\mathrm{out} =
+\begin{bmatrix}
+\mathrm{in}_1 \\
+\mathrm{in}_2 \\
+\vdots \\
+\mathrm{in}_N
+\end{bmatrix}
+$$
+
+The resulting output dimension is $(\sum_i n_i, 1)$.
+
+---
+
+## Parameters
+
+| Name        | Type | Description | Optional |
+|------------|-------------|-------------|-------------|
+| `num_inputs` | integer | Number of input ports to create. | True |
+| `sample_time` | float | Block sample time. If omitted, the global simulation time step is used. | True |
+
+---
+
+## Inputs
+
+| Port | Description |
+|------|------------|
+| `in1 … inN` | Input column vectors to be concatenated. |
+
+---
+
+## Outputs
+
+| Port | Description |
+|------|------------|
+| `out` | Vertically concatenated output vector. |
+
+---
+
+## Notes
+
+- The block has no internal state.
+- The block has direct feedthrough.
+- Input vectors are not required to have the same dimension.
+- All input ports must be connected for the block to produce an output.
+- This block is equivalent to the Simulink **Mux** block.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/operators/product.md

@@ -0,0 +1,51 @@
+# Product Block
+
+## Description
+
+The **Product** block computes a multiplication or division of multiple input signals.
+
+If multiplication is "Element-wise (*)", it performs element-wise multiplication or division:
+$$ y = u_1 oper_1 u_2 oper_2 \dots oper_{N-1} u_N $$
+where each coefficient \( oper_i \) is either * or /.
+
+If multiplication is "Matrix (@)", it performs matrix multiplication or division:
+$$ y = u_1 oper_1 u_2 oper_2 \dots oper_{N-1} u_N $$
+where each coefficient \( oper_i \) is either * (matrix product @) or / (matrix inverse).
+
+---
+
+## Parameters
+
+| Name | Type | Description | Optional |
+|------|------------|
+| `operations` | string | Specify the operations between inputs as a string of "*" and "/" characters. For example, for three inputs and operations "*", "/", the string would be "* /". The length of this string must be one less than the number of inputs. | False |
+| `multiplication` | string | Type of multiplication: "Element-wise (*)" or "Matrix (@)". | False |
+| `sample_time` | float | Block sample time. If omitted, the global simulation time step is used. | True |
+
+---
+
+## Inputs
+
+| Port | Description |
+|------|------------|
+| `in1 … inN` | Input signals to be multiplied or divided. All inputs must have identical dimensions or scalar |
+
+---
+
+## Outputs
+
+| Port | Description |
+|------|------------|
+| `out` | Result of the multiplication/division of all input signals. |
+
+---
+
+## Notes
+
+- The Sum block has no internal state.
+- The Sum block is direct-feedthrough.
+- The number of input ports is determined by the length of `operations` + 1 .
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later