The windup problem​

A PID controller with output saturation has a nasty interaction: when the actuator is saturated, the integrator keeps accumulating error even though the output is clamped. When the error sign reverses, the integrator takes a long time to "wind down" before the output leaves saturation — causing overshoot and oscillation.

Error ─► [P]──────────────► sum ─► [saturation] ─► u
         [I → accumulate] ──►          │
         [D] ────────────► ┘           │
                 ▲                     │
                 └─── windup occurs ───┘
                      when e > 0 and u = u_max

Toy example: windup in action​

from synapsys.algorithms import PID
from synapsys.api import ss, c2d
import numpy as np

plant = c2d(ss([[-1]], [[1]], [[1]], [[0]]), dt=0.01)
pid_no_aw = PID(Kp=5.0, Ki=2.0, Kd=0.0, dt=0.01,
                u_min=-1.0, u_max=1.0,
                anti_windup=False)    # windup enabled

x = np.zeros(1)
setpoint = 5.0       # large step — will saturate the output

outputs = []
for _ in range(500):   # 5 s
    y = x              # y = x for this plant
    u = np.array([pid_no_aw.compute(setpoint, float(y[0]))])
    u_sat = np.clip(u, -1.0, 1.0)   # saturation outside PID
    x, _ = plant.evolve(x, u_sat)
    outputs.append(float(y[0]))

The output reaches setpoint but then heavily overshoots because the integrator accumulated $5 \times 500 \times 0.01 = 25$ (units) of error during saturation.

Back-calculation anti-windup​

The back-calculation scheme feeds the saturation error back to the integrator with gain $1/T_t$ (tracking time constant):

When the output is not saturated, $u_{sat} = u_{uns}$ so the correction term is zero — the integrator behaves normally. When saturated, the correction reduces the integrator at a rate proportional to the saturation error.

A common choice is $T_t = \sqrt{T_i / T_d}$ (geometric mean), or simply $T_t = T_i$ when there is no derivative term.

Synapsys implementation​

from synapsys.algorithms import PID

# Anti-windup ON (default) — u_min/u_max trigger back-calculation
pid = PID(
    Kp    = 5.0,
    Ki    = 2.0,
    Kd    = 0.1,
    dt    = 0.01,
    u_min = -1.0,
    u_max =  1.0,
    # anti_windup=True is default
)

u = pid.compute(setpoint=5.0, measurement=y)

The compute() method returns the clamped output and applies back-calculation internally — no external saturation needed.

Comparative simulation​

import numpy as np
import matplotlib.pyplot as plt
from synapsys.algorithms import PID
from synapsys.api import ss, c2d

plant = c2d(ss([[-0.5]], [[1]], [[1]], [[0]]), dt=0.01)

def run_sim(anti_windup: bool, n_steps: int = 800):
    pid = PID(Kp=5.0, Ki=2.0, Kd=0.05, dt=0.01,
              u_min=-1.0, u_max=1.0, anti_windup=anti_windup)
    x = np.zeros(1)
    ys, us = [], []
    for i in range(n_steps):
        setpoint = 3.0 if i < 400 else -3.0   # step then negative step
        y = float(x[0])
        u = np.array([pid.compute(setpoint, y)])
        x, _ = plant.evolve(x, u)
        ys.append(y); us.append(float(u[0]))
    return np.array(ys), np.array(us)

t = np.arange(800) * 0.01
y_no, u_no = run_sim(anti_windup=False)
y_aw, u_aw = run_sim(anti_windup=True)

fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(9, 6), sharex=True)
ax1.plot(t, y_no, label='No anti-windup', linestyle='--')
ax1.plot(t, y_aw, label='Anti-windup', linewidth=2)
ax1.axhline(3.0,  color='gray', linestyle=':', linewidth=0.8)
ax1.axhline(-3.0, color='gray', linestyle=':', linewidth=0.8)
ax1.set_ylabel("Output"); ax1.legend(); ax1.grid(True)

ax2.plot(t, u_no, linestyle='--'); ax2.plot(t, u_aw, linewidth=2)
ax2.axhline(1.0,  color='red', linestyle=':', linewidth=0.8, label='u_max')
ax2.axhline(-1.0, color='red', linestyle=':', linewidth=0.8, label='u_min')
ax2.set_ylabel("Control (u)"); ax2.set_xlabel("Time (s)")
ax2.legend(); ax2.grid(True)

plt.tight_layout(); plt.savefig("pid_antiwindup_comparison.png", dpi=150)

Tuning guidelines for research​

For discrete implementations, always use a sampling rate at least 10× the closed-loop bandwidth to avoid discretisation artefacts in the derivative term.

Connection to the broader literature​

The back-calculation scheme used in Synapsys follows Åström & Hägglund (2006) Advanced PID Control, Chapter 6. The discrete formulation uses the bilinear (Tustin) approximation for the integrator, which avoids the frequency-domain distortion of forward Euler at high gains.

@book{astrom2006advanced,
  author    = {Åström, Karl Johan and Hägglund, Tore},
  title     = {Advanced PID Control},
  publisher = {ISA — The Instrumentation, Systems, and Automation Society},
  year      = {2006},
  isbn      = {978-1556175169},
}

Summary​

The full API reference is at synapsys.algorithms →.

MIL → SIL → HIL is the standard V-model progression for embedded control: simulate everything first, then replace the plant model with real hardware one layer at a time. In most frameworks this requires rewriting large parts of the control loop. In Synapsys the transition is a one-line swap because the transport layer is fully abstracted from the algorithm.

The three stages​

The Synapsys abstraction that makes this work:

Agent ──► TransportStrategy (read / write)
              │
              ├── SharedMemoryTransport   ← MIL
              ├── ZMQTransport            ← SIL
              └── HardwareInterface       ← HIL

The Agent never calls transport directly — it calls _read() / _write(). Swap the transport, leave the agent unchanged.

Stage 1 — MIL: everything in one process​

from synapsys.api import ss, c2d
from synapsys.agents import PlantAgent, ControllerAgent, SyncEngine, SyncMode
from synapsys.algorithms import PID
from synapsys.transport import SharedMemoryTransport
import numpy as np

plant_d = c2d(ss([[-1]], [[1]], [[1]], [[0]]), dt=0.01)

pid = PID(Kp=4.0, Ki=1.0, dt=0.01)

def law(y: np.ndarray) -> np.ndarray:
    return np.array([pid.compute(setpoint=3.0, measurement=y[0])])

with SharedMemoryTransport("demo", {"y": 1, "u": 1}, create=True) as bus:
    bus.write("y", np.zeros(1))
    bus.write("u", np.zeros(1))
    sync = SyncEngine(SyncMode.LOCK_STEP, dt=0.01)
    PlantAgent("plant", plant_d, bus, sync).start(blocking=False)
    ControllerAgent("ctrl", law, bus, sync).start(blocking=True)

All in one script. Fast, deterministic, easy to unit-test.

Stage 2 — SIL: two processes over ZeroMQ​

Split plant and controller into separate processes. The controller algorithm does not change at all:

from synapsys.api import ss, c2d
from synapsys.agents import PlantAgent, SyncEngine, SyncMode
from synapsys.transport import ZMQTransport

plant_d = c2d(ss([[-1]], [[1]], [[1]], [[0]]), dt=0.01)

pub = ZMQTransport("tcp://*:5555",      mode="pub")   # publish y
sub = ZMQTransport("tcp://localhost:5556", mode="sub") # subscribe u

# ZMQTransport wraps both sockets in a single bus-like interface
# (see ZMQReqRepTransport for request-reply pattern)
sync = SyncEngine(SyncMode.WALL_CLOCK, dt=0.01)
PlantAgent("plant", plant_d, pub, sync, sub_transport=sub).start(blocking=True)

from synapsys.agents import ControllerAgent, SyncEngine, SyncMode
from synapsys.algorithms import PID
from synapsys.transport import ZMQTransport
import numpy as np

pid = PID(Kp=4.0, Ki=1.0, dt=0.01)

def law(y: np.ndarray) -> np.ndarray:
    return np.array([pid.compute(setpoint=3.0, measurement=y[0])])

sub = ZMQTransport("tcp://localhost:5555", mode="sub")  # subscribe y
pub = ZMQTransport("tcp://*:5556",         mode="pub")  # publish u

sync = SyncEngine(SyncMode.WALL_CLOCK, dt=0.01)
ControllerAgent("ctrl", law, sub, sync, pub_transport=pub).start(blocking=True)

The law function is identical to the MIL version. Only the transport changed.

Stage 3 — HIL: real hardware​

Replace the StateSpace plant with a HardwareInterface implementation for your device. Everything else — the PID, the sync engine, the ZMQ transport — stays:

from synapsys.agents import HardwareAgent, SyncEngine, SyncMode
from synapsys.hw import HardwareInterface
from synapsys.transport import ZMQTransport
import numpy as np

class MyDAQInterface(HardwareInterface):
    """Wrapper around a USB DAQ card (e.g. NI-DAQ, Arduino, STM32)."""

    def __init__(self):
        super().__init__(n_inputs=1, n_outputs=1)
        # self.daq = ...  initialise your hardware SDK here

    def read_outputs(self, timeout_ms: float = 100.0) -> np.ndarray:
        # return np.array([self.daq.read_channel(0)])
        return np.array([0.0])   # stub

    def write_inputs(self, u: np.ndarray, timeout_ms: float = 100.0) -> None:
        # self.daq.write_channel(0, float(u[0]))
        pass


# Drop-in replacement: HardwareAgent instead of PlantAgent
sub = ZMQTransport("tcp://localhost:5556", mode="sub")
pub = ZMQTransport("tcp://*:5555",         mode="pub")
sync = SyncEngine(SyncMode.WALL_CLOCK, dt=0.01)

HardwareAgent("hw", MyDAQInterface(), pub, sync, sub_transport=sub).start(blocking=True)

The controller process does not change. The swap is surgical.

Common pitfalls​

Timing jitter in SIL​

WALL_CLOCK sync relies on time.sleep() precision. On Linux with a standard kernel, expect ±0.5 ms jitter at 100 Hz. For tighter requirements:

# Use LOCK_STEP for in-process simulation (no timing issues)
sync = SyncEngine(SyncMode.LOCK_STEP, dt=0.01)

# Use WALL_CLOCK for cross-process / HIL
sync = SyncEngine(SyncMode.WALL_CLOCK, dt=0.01)

Initial condition mismatch​

Always initialise shared channels before starting agents:

bus.write("y", np.zeros(1))   # ← do this
bus.write("u", np.zeros(1))   # ← do this
PlantAgent(...).start(blocking=False)
ControllerAgent(...).start(blocking=True)

A controller that reads before the first plant write will get stale zeros — fine for ZOH semantics, but worth being explicit.

Summary​

The MIL → SIL → HIL transition with Synapsys is:

1. MIL: SharedMemoryTransport + PlantAgent + ControllerAgent
2. SIL: swap to ZMQTransport, split into two processes
3. HIL: swap PlantAgent for HardwareAgent(MyDAQInterface(), ...)

The control algorithm never changes. The law function you wrote on day one runs unchanged on the real hardware.

See the full SIL example at examples/advanced/02_sil_ai_controller/.

A quadrotor has four rotors, six rigid-body degrees of freedom, and fully coupled rotational dynamics — it is the MIMO benchmark of aerial robotics. This post walks through the complete design pipeline: physics → linearisation → LQR → Neural-LQR residual → 3D simulation.

State-space model​

The 12-state linearisation around the hover equilibrium uses position $(x, y, z)$, velocity $(\dot x, \dot y, \dot z)$, Euler angles $(\phi, \theta, \psi)$ and angular rates $(p, q, r)$. The four inputs are rotor thrust deviations $(\delta T_1 \ldots \delta T_4)$, mixed into collective thrust $\delta F$ and three torques $(\tau_\phi, \tau_\theta, \tau_\psi)$.

import numpy as np
from synapsys.api import ss, c2d
from synapsys.algorithms import lqr

# Build matrices (from examples/advanced/06_quadcopter_mimo/quadcopter_dynamics.py)
from quadcopter_dynamics import build_matrices

A, B, C, D = build_matrices()          # A: 12×12, B: 12×4
plant = ss(A, B, C, D)

print(f"Poles: {np.sort(np.real(plant.poles()))}")
# Several poles at 0 — marginally stable (rigid body)

The hover equilibrium has integrators for $(x, y, z)$ — any disturbance causes drift without active feedback. LQR closes those loops.

MIMO LQR design​

The MIMO Riccati equation is identical in form to the SISO case — Synapsys handles the matrix dimensions automatically:

# State cost: position and attitude tight, velocities light
q_pos  = 10.0;  q_vel = 1.0
q_att  = 20.0;  q_rate = 2.0

Q = np.diag([
    q_pos, q_pos, q_pos*2,      # x, y, z
    q_vel, q_vel, q_vel,        # ẋ, ẏ, ż
    q_att, q_att, q_att*0.5,    # φ, θ, ψ
    q_rate, q_rate, q_rate,     # p, q, r
])
R = np.eye(4) * 0.5             # actuator cost

K, P = lqr(A, B, Q, R)         # K: 4×12
print(f"K shape: {K.shape}")   # (4, 12)

Verify closed-loop stability:

A_cl = A - B @ K
eigs = np.linalg.eigvals(A_cl)
print(f"Stable: {np.all(np.real(eigs) < 0)}")   # True
print(f"Most negative: {np.real(eigs).min():.2f}")

Residual Neural-LQR​

The residual architecture augments the LQR baseline with a learned correction:

The key property: the MLP output layer is initialised to zero. At deployment the controller is exactly LQR — the residual adds correction only after training. This guarantees provable stability at initialisation.

import torch
import torch.nn as nn

class ResidualMLP(nn.Module):
    def __init__(self, n_states: int, n_inputs: int):
        super().__init__()
        self.net = nn.Sequential(
            nn.Linear(n_states, 64), nn.Tanh(),
            nn.Linear(64, 64),       nn.Tanh(),
            nn.Linear(64, n_inputs),             # output layer
        )
        # Zero-initialise output layer → MLP(e) = 0 at start
        nn.init.zeros_(self.net[-1].weight)
        nn.init.zeros_(self.net[-1].bias)

    def forward(self, e: torch.Tensor) -> torch.Tensor:
        return self.net(e)


mlp = ResidualMLP(n_states=12, n_inputs=4)

# Control law plugged into ControllerAgent
def neural_lqr_law(e: np.ndarray) -> np.ndarray:
    with torch.no_grad():
        e_t = torch.tensor(e, dtype=torch.float32)
        return (-K @ e) + mlp(e_t).numpy()

The MLP can later be trained via imitation learning (clone optimal trajectories) or RL (reward = tracking error + effort) without losing the stability guarantee as long as the residual is bounded.

Closed-loop simulation with Synapsys​

from synapsys.api import c2d
from synapsys.agents import PlantAgent, ControllerAgent, SyncEngine, SyncMode
from synapsys.broker import MessageBroker, Topic, SharedMemoryBackend
import numpy as np

dt = 0.02   # 50 Hz
plant_d = c2d(plant, dt=dt)

# Topics
topics = [Topic("quad/state", shape=(12,)), Topic("quad/u", shape=(4,))]
broker = MessageBroker()
for t in topics:
    broker.declare_topic(t)
broker.add_backend(SharedMemoryBackend("quad_bus", topics, create=True))

# Initial hover reference
ref = np.array([0, 0, 1.5,  0, 0, 0,  0, 0, 0,  0, 0, 0])

def law(y: np.ndarray) -> np.ndarray:
    e = ref - y
    return neural_lqr_law(e)

sync  = SyncEngine(SyncMode.LOCK_STEP, dt=dt)
plant_agent = PlantAgent("quad", plant_d, None, sync,
                         channel_y="quad/state", channel_u="quad/u",
                         broker=broker)
ctrl_agent  = ControllerAgent("ctrl", law, None, sync,
                               channel_y="quad/state", channel_u="quad/u",
                               broker=broker)

plant_agent.start(blocking=False)
ctrl_agent.start(blocking=True)
broker.close()

Results​

The figure-8 trajectory tracking shows:

• Position error < 0.08 m RMS after the first orbit
• Euler angles stay within ±5° during aggressive manoeuvres
• Control inputs are smooth — the actuator cost in $R$ did its job

Research extensions​

This architecture is directly applicable to several open research problems:

1. RL fine-tuning — use the zero-init MLP as the policy network in a PPO/SAC agent; the stability guarantee allows safe exploration.
2. Disturbance rejection — add a wind gust term to $A$ and observe how the LQR baseline handles structured disturbances vs. what the residual learns.
3. Adaptive $Q$/$R$ — meta-learn the Riccati weights across a distribution of payloads using the existing lqr() function as a differentiable layer.

The full simulation code is at examples/advanced/06_quadcopter_mimo/.

Physics and linearisation​

A rigid rod of mass $m$ and length $L$ is hinged at a cart. Let $\theta$ be the angle from the vertical upright. Linearising around $\theta = 0$ gives:

Choosing the state vector $x = [\theta,\; \dot{\theta}]^\top$ and the cart force $u$:

For $m = 0.5$ kg, $L = 0.3$ m, $g = 9.81$ m/s²:

import numpy as np
from synapsys.api import ss

m, L, g = 0.5, 0.3, 9.81

A = np.array([[0,      1   ],
              [g/L,    0   ]])
B = np.array([[0           ],
              [-1/(m*L**2) ]])
C = np.array([[1, 0]])
D = np.zeros((1, 1))

plant = ss(A, B, C, D)
print(plant)                  # StateSpace n_states=2 n_inputs=1 n_outputs=1
print(plant.is_stable())      # False — poles at ±√(g/L) = ±5.72 rad/s

The open-loop poles are $\pm\sqrt{g/L} \approx \pm 5.72$ rad/s — one is in the right half-plane, confirming instability.

LQR design​

LQR finds the state-feedback gain $K$ that minimises:

The tuning intuition: large $Q$ penalises state error (fast, aggressive), large $R$ penalises control effort (slow, conservative). Here we want tight angle control with moderate actuation:

from synapsys.algorithms import lqr

Q = np.diag([100.0, 1.0])   # penalise angle heavily, velocity lightly
R = np.array([[0.1]])        # moderate actuator cost

K, P = lqr(A, B, Q, R)
print(f"K = {K}")            # K = [[33.2  5.8]]

The closed-loop system matrix $A_{cl} = A - BK$ has eigenvalues that are all in the left half-plane — the pendulum is now stabilised.

A_cl = A - B @ K
print(np.linalg.eigvals(A_cl))   # e.g. [-4.1+2.3j  -4.1-2.3j]

Simulation​

from synapsys.api import c2d
import matplotlib.pyplot as plt

# Build closed-loop state-space
cl = ss(A_cl, B, C, D)

# Step response — initial condition θ₀ = 0.2 rad (≈ 11°)
t = np.linspace(0, 3, 600)
x0 = np.array([0.2, 0.0])          # [θ, θ_dot]

# simulate() accepts x0 for initial condition
u_zero = np.zeros((len(t), 1))     # no reference tracking, pure stabilisation
t_out, y = cl.simulate(t, u_zero, x0=x0)

plt.plot(t_out, y)
plt.xlabel("Time (s)")
plt.ylabel("θ (rad)")
plt.title("Inverted Pendulum — LQR stabilisation from θ₀ = 0.2 rad")
plt.grid(True)
plt.show()

The angle returns to zero in roughly 1.5 s without overshoot — the $Q/R$ balance gave us a well-damped response.

Discretisation for embedded deployment​

Real microcontrollers run discrete loops. ZOH discretisation at 100 Hz:

dt = 0.01  # 100 Hz
plant_d = c2d(plant, dt=dt)

print(plant_d)   # StateSpace n_states=2  dt=0.01

# The same K works — LQR was designed in continuous time
# For production, redesign K in discrete time for better performance:
from synapsys.algorithms import lqr
from synapsys.api import c2d

# Discretise A and B for discrete-time LQR (dare)
# plant_d.A, plant_d.B are the ZOH-discretised matrices
K_d, _ = lqr(plant_d.A, plant_d.B, Q, R)

The control loop on the microcontroller reduces to:

x = np.zeros(2)
for tick in range(n_steps):
    u = -K_d @ x
    x, y = plant_d.evolve(x, u)

Key takeaways​

The full notebook is available in examples/quickstart_en.ipynb.

Next in the series​

The next post covers MIMO control of a quadrotor — extending these ideas to a 12-state system with coupled dynamics and a residual Neural-LQR that adds a learned correction layer on top of the classical solution.

What you'll find here​

This blog is aimed at researchers, graduate students, and engineers who work at the intersection of classical control theory and modern software. Each post will focus on a concrete problem and show how to solve it end-to-end using Synapsys.

Series planned​

Quick taste: step response in 5 lines​

from synapsys.api import tf, feedback, step

G = tf([1], [1, 2, 1])   # G(s) = 1 / (s² + 2s + 1)
T = feedback(G)           # unity negative feedback
t, y = step(T)            # simulate step response

The closed-loop DC gain converges to 1.0, and the natural frequency $\omega_n = 1$ rad/s with $\zeta = 1$ (critically damped) — as expected from the denominator.

pip install synapsys   # or: uv add synapsys

Why Synapsys?​

Most Python control libraries focus on analysis. Synapsys adds a simulation and deployment layer on top: agents that run in real time, a transport-agnostic communication bus, and a hardware abstraction that makes MIL/SIL/HIL a configuration change rather than a rewrite.

It was built alongside graduate research in multi-agent control systems and is designed to be readable, testable, and academically citable.

Stay connected​

• Watch the repo on GitHub for new releases
• Open an issue if you have a topic you'd like covered

The first technical post — Stabilising an Inverted Pendulum with LQR — is coming up next.