pySimBlocks 0.1.0__py3-none-any.whl

pySimBlocks/docs/blocks/operators/rate_limiter.md

@@ -0,0 +1,70 @@
+# RateLimiter
+
+## Summary
+
+The **RateLimiter** block limits the rate of change of its output signal by
+constraining how fast the output can increase or decrease between successive
+time steps.
+
+---
+
+## Mathematical definition
+
+The rate-limited output is computed as:
+
+$$
+\Delta u = u[k] - y[k-1]
+$$
+
+$$
+y[k] = y[k-1] + \mathrm{clip}(\Delta u,\; s^{-} dt,\; s^{+} dt)
+$$
+
+where:
+- $u[k]$ is the current input,
+- $y[k-1]$ is the previous output,
+- $s^{+}$ is the rising slope (maximum positive rate),
+- $s^{-}$ is the falling slope (maximum negative rate),
+- $dt$ is the simulation time step.
+
+---
+
+## Parameters
+
+| Name        | Type | Description | Optional |
+|------------|-------------|-------------|-------------|
+| `rising_slope` | scalar or vector or matrix | Maximum allowed positive rate of change. Default is no positive rate limit. | True |
+| `falling_slope` | scalar or vector or matrix | Maximum allowed negative rate of change. Default is no negative rate limit. | True |
+| `initial_output` | scalar or vector or matrix | | Initial output value used as $y[-1]$. If not provided, the initial output is set equal to the first input. | True |
+| `sample_time` | float | Block sample time. If omitted, the global simulation time step is used. | True |
+
+---
+
+## Inputs
+
+| Port | Description |
+|------|------------|
+| `in` | Input signal. |
+
+---
+
+## Outputs
+
+| Port | Description |
+|------|------------|
+| `out` | Rate-limited output signal. |
+
+---
+
+## Notes
+
+- The block has internal state.
+- The block has direct feedthrough.
+- Rate limits are applied component-wise.
+- Scalar parameters are automatically broadcast.
+- Absence of a rate limit in one direction is represented by an infinite slope.
+- This block is equivalent to the Simulink **Rate Limiter** block.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/operators/saturation.md

@@ -0,0 +1,62 @@
+# Saturation
+
+## Summary
+
+The **Saturation** block applies element-wise saturation to its input signal,
+limiting the output to specified lower and upper bounds.
+
+---
+
+## Mathematical definition
+
+The saturated output is defined as:
+
+$$
+y[k] = \mathrm{clip}(u[k], u_{\min}, u_{\max})
+$$
+
+where:
+- $u[k]$ is the input signal,
+- $u_{\min}$ is the lower saturation bound,
+- $u_{\max}$ is the upper saturation bound.
+
+---
+
+## Parameters
+
+| Name        | Type | Description | Optional |
+|------------|-------------|-------------|-------------|
+| `u_min`     | scalar or vector o matrix | Lower saturation bound. If omitted, no lower bound is applied. | True |
+| `u_max`     | scalar or vector or matrix | Upper saturation bound. If omitted, no upper bound is applied. | True |
+| `sample_time` | float | Block sample time. If omitted, the global simulation time step is used. | True |
+
+---
+
+## Inputs
+
+| Port | Description |
+|------|------------|
+| `in` | Input signal. |
+
+---
+
+## Outputs
+
+| Port | Description |
+|------|------------|
+| `out` | Saturated output signal. |
+
+---
+
+## Notes
+
+- The block has no internal state.
+- The block has direct feedthrough.
+- Saturation is applied component-wise.
+- Scalar bounds are automatically broadcast to match the input dimension.
+- Absence of saturation is represented by infinite bounds.
+- This block is equivalent to the Simulink **Saturation** block.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/operators/sum.md

@@ -0,0 +1,49 @@
+# Sum Block
+
+## Description
+
+The **Sum** block computes a weighted sum of multiple input signals.
+
+It implements:
+
+$$ y = s_1 u_1 + s_2 u_2 + \dots + s_N u_N $$
+
+where each coefficient $ s_i $ is either +1 or −1.
+
+---
+
+## Parameters
+
+| Name        | Type | Description | Optional |
+|------------|-------------|-------------|-------------|
+| `signs` | string | Sequence of '+' and '−' characters defining the sign for each input. | 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 summed. All inputs must have identical dimensions or scalar. |
+
+---
+
+## Outputs
+
+| Port | Description |
+|------|------------|
+| `out` | Weighted sum of all input signals. |
+
+---
+
+## Notes
+
+- The Sum block has no internal state.
+- The number of input ports is determined by the length of `signs`.
+- This block is equivalent to the Simulink **Sum** block.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/operators/zero_order_hold.md

@@ -0,0 +1,61 @@
+# ZeroOrderHold
+
+## Summary
+
+The **ZeroOrderHold** block samples an input signal at discrete instants and
+holds the sampled value constant between sampling instants.
+
+---
+
+## Mathematical definition
+
+Let $T_s$ be the sampling period. The output is defined as:
+
+$$
+y[k] = u[k_s]
+$$
+
+where $k_s$ denotes the most recent sampling instant such that the elapsed
+time since $k_s$ is less than $T_s$.
+
+Between two sampling instants, the output remains constant.
+
+---
+
+## Parameters
+
+| Name        | Type | Description | Optional |
+|------------|-------------|-------------|-------------|
+| `sample_time` | float | Block sample time. If omitted, the global simulation time step is used. | True |
+
+---
+
+## Inputs
+
+| Port | Description |
+|------|------------|
+| `in` | Input signal to be sampled and held. |
+
+---
+
+## Outputs
+
+| Port | Description |
+|------|------------|
+| `out` | Output signal that holds the last sampled value. |
+
+---
+
+## Notes
+
+- The block has internal state.
+- The block has direct feedthrough.
+- The block models sampling and hold behavior only.
+- It does not modify the simulator execution rate.
+- The held value is updated when the elapsed time since the last sample
+  reaches the specified sampling period.
+- This block is equivalent to the Simulink **Zero-Order Hold** block.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/optimizers/quadratic_program.md

@@ -0,0 +1,98 @@
+# QuadraticProgram Block
+
+## Description
+
+The **QuadraticProgram** block solves a quadratic optimization problem at each simulation step.
+
+It computes the solution of the following quadratic program:
+
+$$
+\begin{aligned}
+\min_x \quad & \tfrac12 x^T P x + q^T x \\
+\text{subject to} \quad
+& Gx \le h \\
+& Ax = b \\
+& \ell \le x \le u
+\end{aligned}
+$$
+
+where:
+- $x$ is the decision variable,
+- $P$ is the quadratic cost matrix,
+- $q$ is the linear cost vector,
+- $G, h$ define inequality constraints,
+- $A, b$ define equality constraints,
+- $\ell, u$ define lower and upper bounds.
+
+All problem data are provided as inputs and may vary with time.
+
+---
+
+## Problem definition
+
+The quadratic program solved by this block is fully time-varying:
+
+- The cost function $(P, q)$ may change at each simulation step.
+- Constraints $(G, h)$, $(A, b)$, and bounds $(\ell, u)$ are optional.
+- If a constraint set is omitted, it is not enforced.
+
+This block is suitable for:
+- constrained control laws (e.g. saturated LQR),
+- control allocation,
+- one-step MPC formulations,
+- projection-based controllers.
+
+---
+
+## Parameters
+
+| Name | Type | Description | Optional |
+|------|------|-------------|----------|
+| `solver` | string | QP solver used internally via `qpsolvers` (e.g. `clarabel`). | True |
+
+---
+
+## Inputs
+
+| Port | Description |
+|------|------------|
+| `P` | Quadratic cost matrix $(n \times n)$. Must be square and compatible with `size`. |
+| `q` | Linear cost vector. Accepted shapes: $(n,)$ or $(n,1)$. |
+| `G` | Inequality constraint matrix $(m \times n)$. Must be provided together with `h`. |
+| `h` | Inequality constraint vector. Accepted shapes: $(m,)$ or $(m,1)$. |
+| `A` | Equality constraint matrix $(p \times n)$. Must be provided together with `b`. |
+| `b` | Equality constraint vector. Accepted shapes: $(p,)$ or $(p,1)$. |
+| `lb` | Lower bound on decision variables. Accepted shapes: $(n,)$ or $(n,1)$. |
+| `ub` | Upper bound on decision variables. Accepted shapes: $(n,)$ or $(n,1)$. |
+
+---
+
+## Outputs
+
+| Port | Description |
+|------|------------|
+| `x` | Optimal solution of the quadratic program $(n \times 1)$. |
+| `status` | Solver status code:<br>• `0`: optimal solution found<br>• `1`: problem infeasible<br>• `2`: solver or numerical error |
+| `cost` | Optimal value of the quadratic cost function. |
+
+---
+
+## Execution semantics
+
+- The block is **direct feedthrough**: outputs depend only on current inputs.
+- The block is **stateless**: no internal dynamics or memory are stored.
+- A new quadratic program is solved at each simulation step.
+
+---
+
+## Notes
+
+- Dimensions of the problem is inferred by the first input `P` and must be consistent across all inputs and steps.
+- All dimension checks are performed before calling the solver.
+- If the problem is infeasible or the solver fails, the output `status` reflects the error and the output vector is safely set to zero.
+- This block relies on the `qpsolvers` Python package for numerical optimization.
+- This block is conceptually similar to optimization blocks used in Simulink-based MPC and constrained control designs.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/sources/chirp.md

@@ -0,0 +1,102 @@
+# Chirp
+
+## Summary
+
+The **Chirp** block generates a frequency-swept sinusoidal signal
+(linear or logarithmic) with configurable amplitude, phase, offset,
+start time, and duration.
+
+---
+
+## Mathematical definition
+
+For each output component $i$:
+
+$$
+y_i(t) = A_i \sin(\phi_i(t)) + o_i
+$$
+
+with parameters:
+- $A_i$: amplitude,
+- $o_i$: offset,
+- $\phi_i(t)$: chirp phase,
+- $f_{0,i}$: initial frequency,
+- $f_{1,i}$: final frequency,
+- $T_i$: chirp duration,
+- $t_{0,i}$: chirp start time,
+- $\varphi_i$: initial phase.
+
+Define:
+$$
+\tau_i = \max(0, t - t_{0,i}), \quad
+\tau_{c,i} = \min(\tau_i, T_i)
+$$
+
+Linear mode:
+$$
+k_i = \frac{f_{1,i} - f_{0,i}}{T_i}
+$$
+$$
+\phi_i(t) =
+2\pi\left(f_{0,i}\tau_{c,i} + \frac{1}{2}k_i\tau_{c,i}^2\right)
++ 2\pi f_{1,i}\max(0, \tau_i - T_i)
++ \varphi_i
+$$
+
+Log mode:
+$$
+r_i = \frac{f_{1,i}}{f_{0,i}}
+$$
+$$
+\phi_i(t) =
+\frac{2\pi f_{0,i}T_i}{\ln(r_i)}
+\left(r_i^{\tau_{c,i}/T_i} - 1\right)
++ 2\pi f_{1,i}\max(0, \tau_i - T_i)
++ \varphi_i
+$$
+
+After duration, phase continuity is preserved and oscillation continues at $f_1$.
+
+---
+
+## Parameters
+
+| Name        | Type | Description | Optional |
+|------------|-------------|-------------|-------------|
+| `amplitude` | scalar or vector or matrix | Signal amplitude. Scalars are broadcast to all dimensions. | False |
+| `f0` | scalar or vector or matrix | Initial frequency in Hertz. Scalars are broadcast. | False |
+| `f1` | scalar or vector or matrix | Final frequency in Hertz. Scalars are broadcast. | False |
+| `duration` | scalar or vector or matrix | Sweep duration in seconds. Must be strictly positive. Scalars are broadcast. | False |
+| `start_time` | scalar or vector or matrix | Start time in seconds. Before this time, sweep is not active. Default is `0.0`. | True |
+| `offset` | scalar or vector or matrix | Constant offset added to output. Default is `0.0`. | True |
+| `phase` | scalar or vector or matrix | Initial phase in radians. Default is `0.0`. | True |
+| `mode` | string | Sweep mode: `linear` or `log`. Default is `linear`. | 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` | Chirp output signal. |
+
+---
+
+## Notes
+
+- The block has no internal state.
+- All array-like parameters must have compatible shapes.
+- Scalar parameters are broadcast to the common signal shape.
+- In `log` mode, `f0 > 0`, `f1 > 0`, and `f0 != f1` are required.
+- The output keeps oscillating after `duration` at frequency `f1`.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/sources/constant.md

@@ -0,0 +1,53 @@
+# Constant
+
+## Summary
+
+The **Constant** block generates a signal with a fixed value over time.
+The output does not depend on time, system state, or any input signal.
+
+---
+
+## Mathematical definition
+
+The block computes:
+
+$$
+y(t) = c
+$$
+
+where $c$ is a constant scalar or vector value.
+
+---
+
+## Parameters
+
+| Name        | Type | Description | Optional |
+|------------|-------------|-------------|-------------|
+| `value` | scalar or vector or matrix | Constant output value. Can be a scalar or vector. | 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.
+- The output value is copied at each simulation step.
+- This block is typically used as a reference or bias source.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/sources/file_source.md

@@ -0,0 +1,51 @@
+# FileSource Block
+
+## Description
+
+The FileSource block loads a sequence of numeric samples from a file and outputs one sample per simulation step.
+
+Supported file formats:
+- `npz`
+- `npy`
+- `csv`
+
+---
+
+## Parameters
+
+| Name | Type | Description | Optional |
+|------|------|-------------|----------|
+| `file_path` | str | Path to source file. | False |
+| `key` | str | Mandatory for `*.npz` (array key) and `*.csv` (column name). Unused for `*.npy`. | True |
+| `repeat` | bool | End-of-file behavior. If `false`, outputs zeros after the last sample. If `true`, restarts from the first sample. | True (default: `False`) |
+| `use_time` | bool | If `true` (only for `*.npz` and `*.csv`), uses a `time` signal and applies ZOH: at time `t`, output sample at largest index `i` such that `T[i] <= t`. | True (default: `False`) |
+| `sample_time` | float | Block sample time. If omitted, global simulation step is used. | True |
+
+---
+
+## Inputs
+
+None.
+
+---
+
+## Outputs
+
+| Port | Description |
+|------|-------------|
+| `out` | Current sample as a column vector. |
+
+---
+
+## Notes
+
+- File format is inferred from `file_path` extension (`.npz`, `.npy`, `.csv`).
+- `npz`: loaded array must be 1D or 2D.
+- `npy`: loaded array must be 1D or 2D.
+- `csv`: `key` selects one named numeric column, producing shape `(1,1)` at each step.
+- With `use_time=true`, `time` must exist and be strictly increasing.
+  - `npz`: requires key `time`.
+  - `csv`: requires column `time`.
+
+---
+© 2026 Université de Lille & INRIA - Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/sources/function_source.md

@@ -0,0 +1,52 @@
+# FunctionSource
+
+## Summary
+
+The **FunctionSource** block generates one or more signals from a user-defined Python function
+without any input ports.
+
+At each activation, it evaluates:
+
+$$
+y[k] = f(t_k, \Delta t_k)
+$$
+
+where $t_k$ is the current simulation time and $\Delta t_k$ is the elapsed time
+since the previous activation.
+
+---
+
+## Parameters
+
+| Name | Type | Description | Required |
+|------|------|-------------|----------|
+| `file_path` | string | Path to the Python file containing `f`. | Yes |
+| `function_name` | string | Name of the function to call inside the file. | Yes |
+| `output_keys` | list[string] | Names of the output ports. The function must return a dict with exactly these keys. | Yes |
+| `sample_time` | float | Execution period of the block. If omitted, the global simulation time step is used. | No |
+
+---
+
+## Inputs
+
+This block has **no inputs**.
+
+---
+
+## Outputs
+
+Outputs are dynamically defined by `output_keys`.
+
+---
+
+## Execution semantics
+
+- The function signature must be exactly: `f(t, dt)`.
+- The function must return a dict with keys exactly matching `output_keys`.
+- Each returned value may be scalar, 1D, or 2D and is normalized to a 2D array.
+- Output shape is frozen per output key after first evaluation and must stay constant.
+- The block is stateless.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later

pySimBlocks/docs/blocks/sources/ramp.md

@@ -0,0 +1,58 @@
+# Ramp
+
+## Summary
+
+The **Ramp** block generates a ramp signal for each output dimension.
+Each ramp starts at a specified time with a given slope and initial offset.
+
+---
+
+## Mathematical definition
+
+For each output component $i$, the signal is defined as:
+
+$$
+y_i(t) = o_i + s_i \max(0, t - t_{0,i})
+$$
+
+where:
+- $s_i$ is the slope,
+- $t_{0,i}$ is the start time,
+- $o_i$ is the initial offset.
+
+---
+
+## Parameters
+
+| Name        | Type | Description | Optional |
+|------------|-------------|-------------|-------------|
+| `slope` | scalar or vector or matrix | Ramp slope for each output dimension. Scalars are broadcast to all dimensions. | False |
+| `start_time` | scalar or vector or matrix | Time at which the ramp starts. Default is zero. | True |
+| `offset` | scalar or vector or matrix | Output value before the ramp starts. 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 a different slope and start time.
+- Scalar parameters are automatically broadcast.
+
+
+---
+© 2026 Université de Lille & INRIA – Licensed under LGPL-3.0-or-later