Skip to content

Rate limiter: causal command damping and second-order kinematic bounding

This tool ensures that a robot's motor is never ordered to change its speed faster than it physically can. When a control command makes a sudden, unrealistic jump, this module automatically smooths it out into a safe acceleration ramp, clamping the inputs within the motor's actual physical envelope.

A robot's real motor cannot execute an unbounded jump safely. If the command stream says "joint 1 goes from 0.1 to 1.5 rad/s between this tick and the next", the motor will either refuse, saturate, or dangerously approximate it. The rate limiter is the module that makes sure the applied command can actually be tracked, by bounding how fast it is allowed to change.

It is not a filter that decides whether a deviation is a spike or a real change. It does not need to: it just refuses to move faster than the motors allow. The bound is on the command, not on the signal.

The command stream

A joint is commanded to go from 0 to 1.5 rad in a single tick. The control loop runs at 100 Hz, so a tick is 10 ms. The motor's real limit is 5 rad/s of velocity and 20 rad/s² of acceleration.

The jump from 0 to 1.5 rad/s in one tick is a 150 rad/s² acceleration — more than seven times the motor's real limit.

1. Apply the limiter

import numpy as np
from dense_armor.utility.control.rate_limiter import rate_limited_follower

u_des = np.zeros(300)
u_des[100:] = 1.5
u = rate_limited_follower(u_des, max_vel=5.0, max_accel=20.0, dt=0.01)
print(u[99:104].round(4), int(np.argmax(u >= 1.5)))

[0.    0.002 0.006 0.012 0.02 ] 141

The desired command jumps from 0 to 1.5 at sample 100; the applied command rises smoothly (0.002, 0.006, 0.012, …, acceleration limited to 20) and reaches 1.5 at sample 141.

u is the applied command. It is 0 before the step, then ramps up at 20 rad/s² until it hits 1.5 rad/s. The ramp takes 1.5 / 20 = 0.075 s — about 7.5 ticks. The command is the same shape as before, but every rate of change in it is inside the motor's envelope.

2. What "rate limited" means

The limiter tracks two things: the last applied command u_prev, and the change it is allowed to make in one tick. The rule is:

Δ = u_des − u_prev
Δ_max = a_max · dt
if |Δ| ≤ Δ_max:
    u = u_des
else:
    u = u_prev + sign(Δ) · Δ_max

Two bounds apply, not one. v_max clamps the absolute value of the command itself; a_max clamps the change between two consecutive commands. A command that is inside v_max but jumps by more than a_max · dt in one tick is still not applied as-is: it is ramped.

Hand case. dt = 0.01 s, a_max = 20 rad/s², v_max = 5 rad/s, u_prev = 0, u_des = 1.5.

Δ = 1.5
Δ_max = 20 · 0.01 = 0.2
|1.5| > 0.2, so u = 0 + 0.2 = 0.2 rad/s

The applied command moves by 0.2 rad/s. The next tick computes the same, so it takes 1.5 / 0.2 = 7.5 ticks to reach the target. If the target were above v_max (say 6.0), the limiter would ramp up to 5.0 and hold there — clamped by the velocity bound, not the acceleration bound.

3. Why causal damping

A purely local check ("is this command unusually far from the last one?") is not enough to decide whether the jump is a real intended command or a glitch. What matters is whether the motor can execute it. The rate limiter does not try to classify the command; it just makes sure the command never asks the motor to do something it cannot do. The output is always inside the motor's envelope, whether the input was a spike, a step change, or a smooth ramp that the driver generated.

This is why a rate limiter and a detector are not the same tool:

  • A detector decides "is this deviation real or noise?". It can be wrong.
  • A rate limiter decides "can the motor execute this change in one tick?". It has a single, physical answer.

On a real robot you usually want both: the detector says what to trust, the limiter says what to actually send to the motor.

4. Grounding

The limiter is the velocity-and-acceleration-limited special case of the profile that Berscheid and Kröger (2021), Jerk-limited real-time trajectory generation with arbitrary target state compute in full. Ruckig (the paper's algorithm and open-source library) solves the time-optimal jerk-limited profile in closed form for any target state, on every control cycle. The limiter here is simpler: it does not limit jerk, and it does not solve for a target — it just clamps the change between two consecutive commands.

The choice of the simpler form is deliberate: the target state in a real loop is not a fixed target but a moving reference (from the trajectory generator), and the outer controllers on top of the limiter do not need jerk-limited optimality to guarantee safety. They only need the rate bound.

5. Chained with the other control modules

The limiter sits between the kinematic controller and the CBF filter:

import numpy as np
from dense_armor.utility.control.trajectory import quintic_trajectory
from dense_armor.utility.control.kinematic_controller import kinematic_tracking_controller

t, q, v, a = quintic_trajectory(np.zeros(2), np.array([0.5, 1.0]), T=2.0)
dt, qa = t[1] - t[0], np.array([0.05, -0.05])
for i in range(len(t)):
    qa = qa + dt * kinematic_tracking_controller(qa, q[i], v[i], kp=5.0)
print(np.abs(qa - q[-1]).round(4))

[0.0007 0.0014]

The kinematic controller follows a 2-joint quintic path starting 0.05 rad off; at the end the error is below 0.0015 rad.

The kinematic controller produces a velocity that tracks the reference; the limiter makes sure that velocity never asks the motor to change faster than it can; the CBF filter makes sure the final velocity does not point into a forbidden region. Each module bounds a different aspect of the same command.

API reference

rate_limiter

utility/rate_limiter.py

Causal velocity+acceleration-limited command follower -- bounds how fast an applied command can physically change, instead of trying to classify whether a deviation is a spurious spike or a genuine intended change.

WHY THIS EXISTS, NOT A SIMPLER DETECTOR: an earlier attempt at real-time command damping used a neighbor-consensus classifier (the same family as this package's own arbiter.py/healing-style filters) made causal (past- only window, same convention as streaming.py's own port of arbiter.py). That attempt hit a real, structural dead end, tested on real robot joint commands: causally, a real spike and a real regime change are indistinguishable at the instant they happen -- the classifier needs a future window to tell them apart, and a causal version of it lost to a trivial same-radius moving median by 5.5x RMSE (1.7% win rate, 120 real trials). This module sidesteps that classification problem entirely: it never asks whether a deviation is real, it just bounds the physically possible rate of change -- the same principle real robot controllers already use (torque/velocity/acceleration limits).

THEORY: grounded in Berscheid, L. & Kroger, T. (2021), "Jerk-limited Real-time Trajectory Generation with Arbitrary Target States", Robotics: Science and Systems XVII, arXiv:2105.04830 (fetched and verified directly before use, indexed in Dense-Evolution-Discovery's quantumrag under robotica_generazione_traiettoria) -- Ruckig, a time-optimal online trajectory generator respecting velocity/acceleration/jerk limits, causal by construction (uses only the current kinematic state, no lookahead), validated on 1e9 real trajectories, ~20us real compute per DoF. rate_limited_follower below is a deliberately SIMPLER special case, NOT a reimplementation of Ruckig's full time-optimal jerk synthesis -- a causal double-integrator velocity+acceleration limiter (bounds the first two derivatives; jerk itself is still a step function at each clamp transition).

VALIDATED, honestly, on TWO independent real physical domains (real LeRobot robot-arm command streams, not synthetic), promoted from Dense-Evolution-Discovery only after both checked out (see docs/rate_limiter_real_joint_commands.md there): - SO-101 (single 6-DoF arm, real 30Hz): 120 real trials (6 joints x 20 seeds, 5% spike density, 5x real local std magnitude). Real safety metric (max instantaneous jump in the applied output) wins 120/120 against a trivial same-radius moving median. Average tracking fidelity (RMSE vs the real clean signal) LOSES to the moving median (mean 0.79 vs 0.44, wins only 19/120 individual trials) -- a hard rate limiter cannot distinguish an injected spike from genuine fast real motion, so it lags on joints/seeds with more real fast movement. - ALOHA (bimanual, 14-DoF, real 50Hz -- a genuinely different real robot, not just a different episode of the same one): 280 real trials. Safety metric again wins 280/280. Fidelity is an honest, real divergence from SO-101, reported as found: per-trial win rate stays a minority (20.0%) but the MEAN RMSE here actually favors the rate limiter (0.0045 vs 0.0107) -- likely a heavy-tailed moving-median failure mode on some real trials, not investigated further since the safety property (this mechanism's actual purpose) is what needed cross-domain confirmation, and it replicated exactly.

HONEST TAKEAWAY: this is a safety bound, not a general-purpose signal cleaner. If the real goal is "never let a raw command reach the motor unbounded", this mechanism delivers that with a 100% real track record across two independent real robots. If the real goal is "recover the closest approximation to the true intended signal", it does not reliably beat a trivial moving median -- use a detector (arbiter.py, streaming.py, cusum.py) for that instead.

rate_limited_follower 

rate_limited_follower(
    x_raw: ndarray,
    max_vel: float,
    max_accel: float,
    dt: float = 1.0,
) -> np.ndarray

Causally tracks a raw incoming command stream with an applied output whose velocity and acceleration are both bounded -- uses only the previous applied position/velocity and the CURRENT raw target, never future values (verified directly: truncating the array to end at the current index gives an identical result at that index).

Parameters

x_raw : np.ndarray Raw incoming command stream (e.g. an LLM's per-step target position for a robot joint). max_vel, max_accel : float Real physical limits, in the same units as x_raw per real dt. Not universal constants -- derive from the real target system's own real limits (e.g. a joint's real 99th-percentile observed velocity/acceleration on known-good data), the same convention used in both real-domain validations above. dt : float Real time step between samples.

Returns

np.ndarray The applied (rate-limited) command stream, same length as x_raw.

Source code in dense_armor/utility/control/rate_limiter.py 
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
def rate_limited_follower(x_raw: np.ndarray, max_vel: float, max_accel: float, dt: float = 1.0) -> np.ndarray:
    """Causally tracks a raw incoming command stream with an applied
    output whose velocity and acceleration are both bounded -- uses only
    the previous applied position/velocity and the CURRENT raw target,
    never future values (verified directly: truncating the array to end
    at the current index gives an identical result at that index).

    Parameters
    ----------
    x_raw : np.ndarray
        Raw incoming command stream (e.g. an LLM's per-step target
        position for a robot joint).
    max_vel, max_accel : float
        Real physical limits, in the same units as x_raw per real dt.
        Not universal constants -- derive from the real target system's
        own real limits (e.g. a joint's real 99th-percentile observed
        velocity/acceleration on known-good data), the same convention
        used in both real-domain validations above.
    dt : float
        Real time step between samples.

    Returns
    -------
    np.ndarray
        The applied (rate-limited) command stream, same length as x_raw.
    """
    n = len(x_raw)
    out = np.empty(n)
    pos = float(x_raw[0])
    vel = 0.0
    out[0] = pos
    for i in range(1, n):
        target = float(x_raw[i])
        desired_vel = (target - pos) / dt
        max_dvel = max_accel * dt
        vel = float(np.clip(desired_vel, vel - max_dvel, vel + max_dvel))
        vel = float(np.clip(vel, -max_vel, max_vel))
        pos = pos + vel * dt
        out[i] = pos
    return out

Details

The rate limiter was promoted from Dense-Evolution-Discovery after validation on two independent real physical domains (the SO-101 and ALOHA robot arms) on the same 20 real joint excursions used to validate the trajectory generator and the kinematic controller. On every excursion the applied command stays inside the motor's envelope and the joint reaches the reference within the expected ramp time.

The trade-off is fidelity versus safety: the applied command lags the desired command by up to a_max · dt at every tick. On the SO-101 data the peak velocity of the limited command is lower than the peak velocity of the recorded command for the same start, end, and elapsed time — this is expected, not a bug. The limiter is a lower bound on how fast the robot can respond, not an estimate of how fast it will.

See also: CBF filter — the spatial complement (WHERE the command can go). Kinematic controller — where the command comes from. CUSUM and ARL theory — if the real goal is recovering or classifying a signal rather than bounding a command's rate of change, a detector is the right tool, not this module.