AI Meets Control Theory
From Classical Control to Intelligent Autonomous Systems
AI Meets Control Theory is a rigorous, from-scratch experimentation framework that systematically bridges classical control theory, modern state-space methods, constrained Model Predictive Control (MPC), Kalman filtering, adaptive control, and modern machine learning/reinforcement learning on physical dynamical systems. Under the core discipline "derive it, build it from scratch, simulate it, visualise it, and compare it honestly", every controller—from PID and LQR to active-set MPC, EKF/UKF, PPO actor-critic, and safety shields—is evaluated on identical plants, sensor noise profiles, disturbances, and actuator limits.
📄 Read the Living Technical Report (PDF) | 📖 User Guide & API Recipes | 💡 Examples Gallery | 🎨 Unified Visualization | 📊 Master Results & Verdicts Table | 🧭 Engineering Decision Guide | 🚁 Live 3D WebGL Sandbox | 🎯 Project Vision & Manifesto
Quickstart & Installation
# 1. Clone and install in editable mode with development & ML extras
git clone https://github.com/zalihthomas-ui/ai-meets-control-theory.git
cd ai-meets-control-theory
pip install -e ".[dev,ml]"
# 2. Run the fast test suite (443 fast / 451 total passing unit tests from scratch)
pytest -m "not slow"
# 3. Run a canonical multi-controller benchmark comparison
python -m aimct compare --system quadrotor
# 4. Launch interactive physics sandboxes (2D drone, 2-link arm, diff-drive, or 3D 6-DOF WebGL)
python -m aimct live # 2D quadrotor vs wind
python -m aimct live arm # 2-link manipulator
python -m aimct live diffdrive # mobile robot
python -m aimct live3d --web # 6-DOF WebGL sandbox
📖 Usage & Recipes: See docs/USAGE.md for the 5-axis framework guide (system × controller × trajectory × disturbance × parameters) and copy-paste recipes.
💡 Examples Gallery: See examples/README.md for 6 concise, copy-pasteable runnable scripts showcasing every major framework feature.
🎨 Unified Visualization: See docs/VISUALIZATION.md for replay animation (aimct.viz.animate) and real-time interactive sandboxes (aimct.viz.Sandbox).
🛠️ Design-Time Preview: See docs/DEV_PREVIEW.md for model inspection and Jacobian validation (python -m aimct preview <Plant> --watch).
📦 Packaging & Releases: See docs/PACKAGING.md for the PyPI distribution runbook and CHANGELOG.md for the version history.
The Experiments (01–34)
Every experiment is self-contained with its own configuration, runner, Markdown/CSV benchmark table, and publication-ready 4-panel figure. See docs/RESULTS.md for full metrics.
| Exp | Directory | Plant | Key Comparison | Empirical Finding & Verdict |
|---|---|---|---|---|
| 01 | 01_integrator_accuracy |
Mass-Spring-Damper | RK4 vs Forward Euler | Euler adds false numerical energy; 4th-order RK4 is mandatory for stable physics. |
| 02 | 02_linearization_validity |
Inverted Pendulum | Linear vs Nonlinear ODE | Linear state-space diverges at $ |
| 03 | 03_pid_stabilizes_unstable |
Inverted Pendulum | PID Clamping vs Raw PID | Conditional anti-windup clamping cuts overshoot from $53%$ to $39%$ and prevents windup instability. |
| 04 | 04_lqr_vs_pole_placement_cartpole |
Cart-Pole (Balance) | LQR (CARE) vs Pole Placement | LQR finds optimal gain without pole guessing; single-loop PID drifts $0.82,\text{m}$ off-rail. |
| 05 | 05_cartpole_basin_of_attraction |
Cart-Pole (Nonlinear) | LQR Basin of Attraction | Quantified $57^\circ$ recoverable envelope; actuator saturation prevents divergence. |
| 06 | 06_lqg_vs_lqr_measurement_noise |
Cart-Pole (Encoders) | Kalman Filter vs Luenberger | Fast observers amplify encoder noise ($16.2,\text{N}^2\text{s}$); LQG gives smooth, optimal effort ($2.2,\text{N}^2\text{s}$). |
| 07 | 07_cartpole_swingup_hybrid |
Cart-Pole (Swing-Up) | Spong Energy Shaping + LQR | Energy pumping lifts from $\theta=\pi$ to orbit; hysteresis supervisor catches in 1 switch. |
| 08 | 08_mpc_vs_lqr_constrained_cartpole |
Cart-Pole (Bounds) | Constrained MPC vs LQR | Active-set QP MPC strictly respects $ |
| 09 | 09_control_on_identified_model |
Cart-Pole (SysID) | Least-Squares / DMDc ID | LQR gain margins tolerate $20%$ parameter residual on $24,\text{s}$ data; $1,\text{s}$ data destabilizes. |
| 10 | 10_planning_learned_vs_true_model |
Cart-Pole (Neural MLP) | Sampling MPC on Neural Model | 4,804-param residual MLP matches true physics planning ($3%$ error); CARE terminal cost required. |
| 11 | 11_qlearning_vs_classical |
Inverted Pendulum | Tabular Q vs Energy Shaping | Model-free RL learns swing-up but chatters at $1.5,\text{rad}$; classical needs zero training data. |
| 12 | 12_shielded_qlearning |
Inverted Pendulum | Shielded RL vs Raw RL | Classical safety shield locks RL swing-up to $0.00,\text{rad}$ with $35%$ less control effort. |
| 13 | 13_robust_control_loop_shaping |
Stiff Dynamics | $\mathcal{H}_\infty$ Loop Shaping vs Nominal | Explicit sensitivity shaping guarantees stability under $\pm 40%$ parameter uncertainty. |
| 14 | 14_quadrotor_figure8_tracking |
Crazyflie 2.0 ($28,\text{g}$) | Flatness Feedforward vs MPC | Differential flatness inversion cuts RMS error by $15%$ to $43.5,\text{mm}$; preview MPC matches at $47.9,\text{mm}$. |
| 15 | 15_quadrotor_ekf_output_feedback |
Crazyflie 2.0 (Noisy) | EKF Observer vs Differencing | EKF reconstructs unmeasured velocity to $8,\text{mm/s}$; finite differencing explodes energy $150\times$. |
| 16 | 16_ekf_vs_ukf |
Inverted Pendulum | EKF vs Unscented UKF | UKF sigma points escape $\pi$-off false basin ($0.07,\text{rad}$); EKF gets trapped at $6.28,\text{rad}$. |
| 17 | 17_adaptive_vs_fixed_changing_plant |
MSD (Drifting $k$) | Lyapunov MRAC vs Fixed LQR | MRAC holds $< 1,\text{mm}$ error under $500%$ spring constant drift, eliminating static LQR droop. |
| 18 | 18_rl_zoo_vs_lqr |
Cart-Pole (Balance) | RL Zoo (DQN, PPO) vs LQR | Scratch continuous PPO matches LQR return $-0.3$ and $200/200$ hold, paying $240\text{k}$ sample cost. |
| 19 | 19_icc_leaderboard |
Multi-Plant Challenge | Blind Black-Box Leaderboard | MPC dominates precision (DC Motor $41.3$); Energy+LQR hybrid sweeps agility (Pendulum $23.8$, Track 3 $29.9$). |
| 20 | 20_quadrotor_obstacle_nmpc |
Crazyflie 2.0 (Keep-Out) | Sampling NMPC vs Flatness LQR | NMPC bends trajectory around keep-out ($+11,\text{mm}$ clearance); flatness LQR crashes straight through. |
| 21 | 21_grand_capstone_bakeoff |
Crazyflie 2.0 (Grand Course) | Five-Way Grand Bake-Off | Sampling NMPC scores 8.0 (0 violations); imitation tracks 41.4 mm but cuts keep-out 46 times; hybrid scores 7.9. |
| 22 | 22_diffdrive_path_following |
TurtleBot3-Burger (Unicycle) | Pure Pursuit vs Stanley vs Path LQR | Path LQR curvature feedforward gives tightest cross-track error ($9.25,\text{mm}$); pure pursuit cuts corners ($35,\text{mm}$). |
| 23 | 23_twolink_arm_tracking |
2-Link Planar Robot Arm | Computed Torque vs Slotine--Li MRAC | Nominal computed torque collapses under $+0.5,\text{kg}$ load ($394,\text{mm}$); Slotine--Li adapts to $4.93,\text{mm}$ ($100%$). |
| 24 | 24_ilqr_vs_sampling_mpc |
Cart-Pole & Crazyflie 2.0 | iLQR / RTI-NMPC vs Sampling MPC | iLQR converges $150\times$ tighter on quad ($1.34,\text{mm}$ error) and solves in $14.6,\text{ms}$ (meets $20,\text{ms}$ flight budget). |
| 25 | 25_diffdrive_moving_obstacle |
TurtleBot3-Burger (Dynamic Disks) | Blind Trackers vs Obstacle-Aware Planners | CEM derivative-free sampling navigates around non-convex obstacle fields ($36$ collision steps) where iLQR gradient fails to clear ($69$ steps). |
| 26 | 26_harder_reference_paths |
Crazyflie 2.0 (Lissajous, Spiral) | iLQR vs Sampling MPC across Geometries | iLQR beats CEM by $32\times\text{--}840\times$ RMS error; CEM latency ($28\text{--}31,\text{ms}$) violates $20,\text{ms}$ flight budget on all paths. |
| 27 | 27_bicycle_double_lane_change |
Dynamic Bicycle Sedan | Stanley vs LQR vs Kinematic MPC vs BC RL | Kinematic MPC wins nominal ($52.5,\text{mm}$); Stanley wins Pacejka $\mu=0.6$ ($734,\text{mm}$); BC RL fails off-road ($5.22,\text{m}$ RMS). |
| 28 | 28_furuta_pendulum_control |
Furuta Rotary Pendulum (QUBE-2) | LQR vs Linear MPC vs Energy Swing-Up | Upright stabilization in $40,\text{ms}$ ($e_{ss} < 6\times 10^{-7},\text{rad}$); MPC caps torque ($0.1343,\text{N}\cdot\text{m}$); Swing-up in $6.0,\text{s}$. |
| 29 | 29_dagger_vs_bc_lane_change |
Dynamic Bicycle (Pacejka $\mu=0.6$) | Plain BC vs DAgger (8 rounds) | Plain BC drifts off-road ($6.02,\text{m}$ RMS); DAgger relabeling matches expert LQR ($768.8,\text{mm}$ RMS) but inherits expert ceiling. |
| 30 | 30_two_tank_level_control |
Coupled Nonlinear Two-Tank | SISO PI vs Multivariable LQR vs Linear MPC | SISO PI eliminates nonlinear steady-state droop ($0.0,\text{cm}$); LQR/MPC cuts pump energy by $22%$ ($6659,\text{V}^2\text{s}$) with $0%$ level violation. |
| 31 | 31_sac_vs_ppo_sample_efficiency |
Inverted Pendulum (Swing-Up) | SAC (off-policy) vs PPO (on-policy) vs Hybrid | Off-policy SAC reaches $-966$ threshold in $8\text{k}$ steps ($15\text{--}20\times$ faster than PPO) and beats classical hybrid ($-364$ vs $-816$). |
| 33 | 33_ball_and_beam_control |
Ball & Beam (Quanser standard) | Cascade PID vs PFL vs Multivariable LQR vs Linear MPC | LQR / MPC settle in $1.49,\text{s}$ ($1.3%$ overshoot, zero droop); MPC caps torque to $0.784,\text{N}\cdot\text{m}$ (energy $0.0184$). |
| 34 | 34_dob_wind_rejection |
Planar Quadrotor (Crazyflie 2.0) | Nominal LQR vs LQI vs MRAC vs DOB+LQR | DOB settles $5\times$ faster ($0.58,\text{s}$) with $-61%$ lateral drift; MRAC drifts on unmatched forces. |
Framework Architecture & Package Layout
src/aimct/
systems/ DynamicalSystem base + LinearSystem, MassSpringDamper,
Pendulum, CartPole, PlanarQuadrotor (Crazyflie 2.0), DCMotor,
DifferentialDriveRobot, TwoLinkArm, BicycleVehicle,
FurutaPendulum, TwoTank, BallAndBeam
simulate.py rk4_step(), simulate() -> Trajectory(t, x, u, y)
controllers/ PID, StateFeedback, LQR, ObserverFeedback, MRAC, ComputedTorque,
DisturbanceObserver, QFilter, EnergyShapingSwingUp, HybridSwingUpLQR,
LinearMPC (with preview), SamplingMPC (CEM + obstacles),
ILQR (trajectory optimiser + real-time-iteration NMPC)
estimation/ LuenbergerObserver, KalmanFilter (LQE/FARE), DiscreteKalmanFilter,
ExtendedKalmanFilter, UnscentedKalmanFilter, observability_matrix
trajectories/ Lemniscate, Spline, Minimum-Jerk Polynomials, Dubins, Lissajous, Spiral, Rose
sysid/ least_squares_id, dmdc, to_continuous (block logm), prediction_error
ml/ MLP (backprop + Adam), LearnedDynamics (grey-box / residual)
rl/ ControlEnv (Gymnasium adapter), Discretizer, QLearning, DQN, REINFORCE, PPO, SAC,
imitation (BehaviorCloning, dagger)
hybrid/ ShieldedController (switch/filter blends, predicate helpers)
viz/ SystemArtist contract, animate() replay engine, Sandbox live GUI
dev/ Design-time preview dashboard (poles, controllability, Jacobian residuals)
benchmarks/ metrics.py (13 metrics), harness.py, sweep.py, challenge.py, tracking.py
plot_style.py Okabe-Ito color palette + publication-ready 4-panel comparison figures
The Core Engineering Cycle
Every method follows the same rigorous pipeline:
THEORY → DERIVATION → IMPLEMENTATION → SIMULATION → VISUALISATION → VALIDATION → COMPARISON → EXPERIMENT
- Understand the mathematics: First-principles ODEs, Riccati equations, Lyapunov stability, Hamiltonians, Hamilton-Jacobi-Bellman, GAE.
- Build from scratch: No black-box library magic in core algorithms. Custom Hamiltonian Schur CARE solver, custom active-set QP solver, custom backpropagation + Adam, custom sigma-point UKF, custom PPO actor-critic.
- Validate against reality: Hard actuator saturation, sensor noise, latency, parameter drift, unmeasured states, non-convex keep-out zones.
- Compare honestly: Side-by-side Pareto tables under identical random seeds, step sizes, and initial conditions.
Learning Curriculum
| Module | Topic | Description |
|---|---|---|
| 01 | Mathematical Foundations | Linear algebra, matrix exponential, RK4 integration, numerical optimization. |
| 02 | Dynamic System Modeling | First-principles physics, state-space representations, Jacobian linearisation. |
| 03 | Classical Control | Filtered derivative PID, conditional anti-windup clamping, frequency response. |
| 04 | Modern Control & Estimation | Controllability, observability, Ackermann pole placement, Luenberger observers, Kalman filters (linear, EKF, UKF). |
| 05 | Optimal & Constrained Control | Algebraic Riccati equations (CARE/DARE), LQR robustness margins, constrained active-set Model Predictive Control. |
| 06 | ML for Dynamical Systems | Least-squares SysID, DMDc, neural MLP backprop + Adam, residual LearnedDynamics, sampling-based MPC (CEM). |
| 07 | Reinforcement Learning | Gymnasium ControlEnv, Tabular Q-Learning, Deep Q-Networks (DQN), REINFORCE, and Proximal Policy Optimization (PPO). |
| 08 | AI + Control (Hybrid Safety) | Supervisory safety shielding, action filtering, control barrier functions, auditable intervention logging. |
| 09 | Robotics Capstones | Full 6-state Crazyflie 2.0 Quadrotor, differential flatness inversion, Bryson scaling, EKF output feedback, MRAC, obstacle NMPC. |
| 10 | Intelligent Control Challenge | Standardized black-box multi-track benchmark engine and cross-paradigm leaderboard. |
Status: Phase 2 Complete (Phase 3 Planned) 🚀
The core curriculum (Modules 01–10), 32 empirical benchmark experiments, living technical report, unified visualization layer (aimct.viz), design-time preview dashboard (aimct.dev), and 7 interactive sandboxes are complete with 451 passing unit tests across Python 3.10–3.13.
Phase 2 Delivered:
- Track A (Real Systems): Differential-drive mobile robots (Exp 22 path tracking, Exp 25 dynamic obstacle avoidance), 2-link planar manipulator arms (Exp 23 computed torque & Slotine–Li payload adaptation), dynamic bicycle vehicles (Exp 27 ISO-3888 double lane change with linear vs. Pacejka tire models), Furuta rotary inverted pendulums (Exp 28 Quanser QUBE-Servo 2 benchmark), coupled nonlinear process tanks (Exp 30 Quanser Coupled Two-Tank level control), ball and beam balance (Exp 33), and disturbance observer aerodynamic wind rejection (Exp 34).
- Track B (Algorithmic Depth, Imitation & Continuous RL): Real-time iteration Nonlinear MPC (Exp 24, 26, 25 iLQR / RTI-NMPC vs. Sampling MPC), interactive imitation learning (Exp 29 DAgger vs. Behavior Cloning lane-change recovery), and continuous off-policy Soft Actor-Critic (Exp 31 SAC vs. PPO sample efficiency).
- Track C & D: Reusable trajectory generation suite (
aimct.trajectories), tracking benchmark harness (aimct.benchmarks.tracking), unified visualization (aimct.viz), design-time preview (aimct.dev), and PyPI distribution packaging (aimct).
Phase 3 (Planned): Hardware-in-the-loop (HIL) physical deployment, flight log telemetry ingestion (CFclient/ROS2), dynamic bicycle vehicle model, Soft Actor-Critic (SAC), and direct collocation trajectory optimization.
See docs/roadmap.md for detailed deliverables and development history.
Contributing
See CONTRIBUTING.md for the workflow and engineering agreement, and the Code of Conduct. Found a security issue? See SECURITY.md for how to report it privately.
License
MIT — see LICENSE.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
aimct-0.2.0.tar.gz
(244.5 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
aimct-0.2.0-py3-none-any.whl
(198.5 kB
view details)
File details
Details for the file aimct-0.2.0.tar.gz.
File metadata
- Download URL: aimct-0.2.0.tar.gz
- Upload date:
- Size: 244.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
3546ba21266ddb0ec0154e480dab8b6922edf873476ff15d412dd54afddb171e
|
|
| MD5 |
e64008645f351d76218aca01bacae319
|
|
| BLAKE2b-256 |
3e3221d078d5a2c96c419f9bad350f7709a21ec553416de5815550dfab449d08
|
Provenance
The following attestation bundles were made for aimct-0.2.0.tar.gz:
Publisher:
release.yml on zalihthomas-ui/ai-meets-control-theory
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
aimct-0.2.0.tar.gz -
Subject digest:
3546ba21266ddb0ec0154e480dab8b6922edf873476ff15d412dd54afddb171e - Sigstore transparency entry: 2728820008
- Sigstore integration time:
-
Permalink:
zalihthomas-ui/ai-meets-control-theory@2ac9158fe82db760e841d742d44c50475792eba1 -
Branch / Tag:
refs/tags/v0.2.0 - Owner: https://github.com/zalihthomas-ui
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@2ac9158fe82db760e841d742d44c50475792eba1 -
Trigger Event:
push
-
Statement type:
File details
Details for the file aimct-0.2.0-py3-none-any.whl.
File metadata
- Download URL: aimct-0.2.0-py3-none-any.whl
- Upload date:
- Size: 198.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
5bd43f84e8b31fe32451768421a45ed894f034ceabb1678b0b4d62a30eeeed1e
|
|
| MD5 |
d3b0dcbebf68e97f38beb47d183a77b3
|
|
| BLAKE2b-256 |
91f7c6473fb988e4cceaf88f320edc3009b785e698ecfe3be419dc742a7c643f
|
Provenance
The following attestation bundles were made for aimct-0.2.0-py3-none-any.whl:
Publisher:
release.yml on zalihthomas-ui/ai-meets-control-theory
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
aimct-0.2.0-py3-none-any.whl -
Subject digest:
5bd43f84e8b31fe32451768421a45ed894f034ceabb1678b0b4d62a30eeeed1e - Sigstore transparency entry: 2728820154
- Sigstore integration time:
-
Permalink:
zalihthomas-ui/ai-meets-control-theory@2ac9158fe82db760e841d742d44c50475792eba1 -
Branch / Tag:
refs/tags/v0.2.0 - Owner: https://github.com/zalihthomas-ui
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@2ac9158fe82db760e841d742d44c50475792eba1 -
Trigger Event:
push
-
Statement type:
