aimct 0.1.0__tar.gz

aimct-0.1.0/CHANGELOG.md

@@ -0,0 +1,94 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+### Added
+- **Real systems (Track A):** `DifferentialDriveRobot` (unicycle + first-order
+  actuator lag) and `TwoLinkArm` (planar Euler-Lagrange manipulator with a
+  settable wrist payload), both parameterised on real hardware classes
+  (TurtleBot3-Burger-class mobile robot; Quanser 2-DOF-arm-class manipulator).
+- **`aimct.controllers.ilqr`:** iterative-LQR trajectory optimiser + a
+  real-time-iteration nonlinear-MPC controller.
+- **`aimct.trajectories`:** `Lissajous`, `Rose`, `Spiral` reference paths
+  (alongside the existing `Lemniscate`/`MinimumJerk`/`Spline`/`Dubins`).
+- **`aimct.benchmarks.tracking`:** `track_trajectory` path-following harness
+  (RMS/cross-track error, completion %, energy) and `TrackingResult.animate()`.
+- **`aimct.viz`:** a unified visualization layer — `SystemArtist` (one draw
+  contract per system), `animate()` (replay any simulated run), `Sandbox` +
+  `Disturbance` (real-time interactive sandboxes with sliders/hot-keys), and
+  `aimct.viz.pv_arm` (a shared 3-D PyVista renderer for the arm systems).
+  Every `Sandbox` gets a help overlay, a "surprise me" randomiser, PNG
+  snapshotting, and a session-best score for free.
+- **Interactive sandboxes:** `live_arm` (unknown-payload identification),
+  `live_arm_balance` (double-inverted-pendulum balance under gravity),
+  `live_diffdrive` (path-follower recovery from a shove) — each with a 2-D
+  (matplotlib) and, for the arm sandboxes, a 3-D (PyVista) view. Run via
+  `python -m aimct live {arm,arm3d,diffdrive,armbalance,armbalance3d}`.
+- **`aimct.dev`:** a design-time preview tool for a `DynamicalSystem` under
+  development (pole map, controllability/observability, analytic-vs-numeric
+  Jacobian check, animated replay) — `python -m aimct preview MODULE:Class`.
+- **Experiments 22–26:** differential-drive path following, two-link-arm
+  tracking + adaptive payload rejection, iLQR/RTI-NMPC vs. sampling MPC (CEM),
+  moving-obstacle avoidance, and tracking-robustness on harder reference paths.
+
+### Fixed
+- `live_diffdrive`'s path follower could show its look-ahead point teleport
+  across the figure-8's self-intersection (a global nearest-point search
+  flipping branches); replaced with progress-hysteresis search.
+- CI's install step was missing the `ml` extra, so `pytest` failed to even
+  collect (`aimct.rl` imports `gymnasium` unconditionally) on every push.
+- `live_drone_3d/pv3d.py`'s interactive path called a PyVista method
+  (`add_callback`) absent from the installed PyVista version — switched to
+  `add_timer_event`.
+- Packaging: `aimct.__version__` and the built distribution's version had
+  drifted (`0.0.1` vs. `0.1.0`); `pyproject.toml` now takes its version from
+  `aimct.__version__` (single source of truth).
+
+## [0.1.0] - 2026-09-04
+
+### Added
+- **Core State-Space & Classical Control (`aimct.controllers`)**:
+  - From-scratch Continuous Algebraic Riccati Equation (CARE) and Discrete Algebraic Riccati Equation (DARE) solvers.
+  - Linear Quadratic Regulator (`LQR`) with Bryson scaling and integral augmentation (`LQI`).
+  - Proportional-Integral-Derivative (`PID`) controller with anti-windup clamping and low-pass derivative filtering.
+  - State Feedback with setpoint tracking (`StateFeedback`).
+  - Full-state and reduced-order Luenberger Observers (`LuenbergerObserver`).
+  - Continuous and Discrete Kalman Filters (`KalmanFilter`), Extended Kalman Filter (`EKF`), and Unscented Kalman Filter (`UKF`).
+- **Constrained & Optimal Control (`aimct.controllers`)**:
+  - Active-set dense Quadratic Program solver (`solve_qp`) with warm-starting.
+  - Receding-horizon Linear Model Predictive Control (`LinearMPC`) with hard input and soft state constraints.
+  - Model Predictive Path Integral / Sampling MPC (`SamplingMPC`).
+- **Nonlinear & Underactuated Hybrid Control (`aimct.controllers`)**:
+  - Mark Spong Partial Feedback Linearization (`EnergyShapingSwingUp`).
+  - Hysteresis mode-switching swing-up to balance handoff (`HybridSwingUpLQR`).
+  - Model Reference Adaptive Control (`MRAC`) with Lyapuov weight adaptation.
+- **Safe Control & Barrier Functions (`aimct.safety`, `aimct.shield`)**:
+  - Real-time Control Barrier Function Quadratic Program safety filters (`CBFShield`).
+  - Forward-invariance certificates around untrusted RL policies and manual inputs.
+- **Data-Driven & Physics-Informed Dynamics (`aimct.sysid`, `aimct.ml`)**:
+  - Sparse Identification of Nonlinear Dynamics (`SINDy`) with STLSQ regression.
+  - Continuous-depth Neural Ordinary Differential Equations (`NeuralODE`) with adjoint backpropagation.
+  - Proximal Policy Optimization (`PPO`) and Deep Deterministic Policy Gradients (`DDPG`).
+- **Dynamical Systems Benchmark Library (`aimct.systems`)**:
+  - Linear Mechanical Oscillator (`MassSpringDamper`, `InvertedMassSpringDamper`).
+  - Armature-Controlled DC Motor (`DCMotor`, `DCMotor2`).
+  - Inverted Pendulum on a Cart (`CartPole`).
+  - Simple Nonlinear Pendulum (`Pendulum`).
+  - Planar Quadrotor UAV (`PlanarQuadrotor`).
+  - Differential-Drive Mobile Robot (`DifferentialDriveRobot`).
+  - Two-Link Planar Manipulator (`TwoLinkArm`).
+- **Benchmarking & Scoring Engine (`aimct.benchmarks`)**:
+  - Automated multi-controller comparison harness (`compare`, `ComparisonResult`).
+  - Intelligent Control Challenge (ICC) 4-track scoring engine (`score_run`, Track 3 & 4 wrappers).
+  - Grand Capstone Five-Way Bake-Off rubric (`score_capstone`, `capstone_leaderboard_table`).
+- **Interactive Tools & Notebooks**:
+  - Guided interactive tour (`notebooks/01_tour.ipynb`).
+  - CLI entry point (`python -m aimct`).
+  - 3D real-time simulation visualization (`python -m aimct live3d`).

aimct-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zalihthomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aimct-0.1.0/MANIFEST.in

@@ -0,0 +1,18 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include pyproject.toml
+
+recursive-include src/aimct *.py py.typed
+
+# Exclude binary PDFs, experiment runs, checkpoints, and LaTeX artifacts
+global-exclude *.py[cod] __pycache__ *.so *.dylib *.dll
+global-exclude *.pdf
+global-exclude .git* .DS_Store Thumbs.db desktop.ini
+prune experiments/**/runs
+prune experiments/**/checkpoints
+prune docs/report/build
+prune docs/papers/*.pdf
+prune wandb
+prune htmlcov
+prune .pytest_cache

aimct-0.1.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: aimct
+Version: 0.1.0
+Summary: AI Meets Control Theory — A rigorous, code-first bridge from classical feedback control to modern machine learning and safe reinforcement learning
+Author-email: Zalih Thomas <zalihthomas@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/zalihthomas-ui/ai-meets-control-theory
+Project-URL: Documentation, https://github.com/zalihthomas-ui/ai-meets-control-theory#readme
+Project-URL: Repository, https://github.com/zalihthomas-ui/ai-meets-control-theory.git
+Project-URL: Bug Tracker, https://github.com/zalihthomas-ui/ai-meets-control-theory/issues
+Project-URL: Changelog, https://github.com/zalihthomas-ui/ai-meets-control-theory/blob/main/CHANGELOG.md
+Keywords: control-theory,reinforcement-learning,optimal-control,lqr,mpc,neural-odes,sindy,control-barrier-functions,robotics,dynamical-systems
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Requires-Dist: matplotlib>=3.8
+Provides-Extra: xcheck
+Requires-Dist: control>=0.10; extra == "xcheck"
+Provides-Extra: ml
+Requires-Dist: torch>=2.2; extra == "ml"
+Requires-Dist: gymnasium>=1.0; extra == "ml"
+Requires-Dist: stable-baselines3>=2.0; extra == "ml"
+Provides-Extra: viz
+Requires-Dist: pyvista>=0.44; extra == "viz"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Requires-Dist: control>=0.10; extra == "dev"
+Dynamic: license-file
+
+# AI Meets Control Theory
+
+### From Classical Control to Intelligent Autonomous Systems
+
+[![CI](https://github.com/zalihthomas-ui/ai-meets-control-theory/actions/workflows/ci.yml/badge.svg)](https://github.com/zalihthomas-ui/ai-meets-control-theory/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](pyproject.toml)
+[![Report: Living PDF](https://img.shields.io/badge/Report-Living%20PDF-brightgreen)](docs/report/ai-meets-control-theory.pdf)
+
+**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)](docs/report/ai-meets-control-theory.pdf)** &nbsp;|&nbsp; 📖 **[User Guide & API Recipes](docs/USAGE.md)** &nbsp;|&nbsp; 🎨 **[Unified Visualization](docs/VISUALIZATION.md)** &nbsp;|&nbsp; 📊 **[Master Results & Verdicts Table](docs/RESULTS.md)** &nbsp;|&nbsp; 🧭 **[Engineering Decision Guide](docs/DECISION-GUIDE.md)** &nbsp;|&nbsp; 🚁 **[Live 3D WebGL Sandbox](https://claude.ai/code/artifact/69b12b78-d7b2-4732-a7af-2af14930139b)** &nbsp;|&nbsp; 🎯 **[Project Vision & Manifesto](docs/vision.md)**
+
+---
+
+## Quickstart & Installation
+
+```bash
+# 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 (418 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`](docs/USAGE.md) for the 5-axis framework guide (*system × controller × trajectory × disturbance × parameters*) and copy-paste recipes.  
+🎨 **Unified Visualization:** See [`docs/VISUALIZATION.md`](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`](docs/DEV_PREVIEW.md) for model inspection and Jacobian validation (`python -m aimct preview <Plant> --watch`).  
+📦 **Packaging & Releases:** See [`docs/PACKAGING.md`](docs/PACKAGING.md) for the PyPI distribution runbook and [`CHANGELOG.md`](CHANGELOG.md) for the version history.
+
+---
+
+## The Experiments (01–28)
+
+Every experiment is self-contained with its own configuration, runner, Markdown/CSV benchmark table, and publication-ready 4-panel figure. See [`docs/RESULTS.md`](docs/RESULTS.md) for full metrics.
+
+| Exp | Directory | Plant | Key Comparison | Empirical Finding & Verdict |
+| :--- | :--- | :--- | :--- | :--- |
+| **01** | [`01_integrator_accuracy`](experiments/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`](experiments/02_linearization_validity/) | Inverted Pendulum | Linear vs Nonlinear ODE | Linear state-space diverges at $|\theta_0| > 23^\circ$; validity is strictly local. |
+| **03** | [`03_pid_stabilizes_unstable`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/08_mpc_vs_lqr_constrained_cartpole/) | Cart-Pole (Bounds) | Constrained MPC vs LQR | Active-set QP MPC strictly respects $|x| \le 0.5\,\text{m}$, while LQR violates rail by $23\%$. |
+| **09** | [`09_control_on_identified_model`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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}$. |
+
+---
+
+## Framework Architecture & Package Layout
+
+```
+src/aimct/
+  systems/        DynamicalSystem base + LinearSystem, MassSpringDamper,
+                  Pendulum, CartPole, PlanarQuadrotor (Crazyflie 2.0), DCMotor,
+                  DifferentialDriveRobot, TwoLinkArm, BicycleVehicle,
+                  FurutaPendulum
+  simulate.py     rk4_step(), simulate() -> Trajectory(t, x, u, y)
+  controllers/    PID, StateFeedback, LQR, ObserverFeedback, MRAC, ComputedTorque,
+                  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
+  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
+```
+
+1. **Understand the mathematics:** First-principles ODEs, Riccati equations, Lyapunov stability, Hamiltonians, Hamilton-Jacobi-Bellman, GAE.
+2. **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.
+3. **Validate against reality:** Hard actuator saturation, sensor noise, latency, parameter drift, unmeasured states, non-convex keep-out zones.
+4. **Compare honestly:** Side-by-side Pareto tables under identical random seeds, step sizes, and initial conditions.
+
+---
+
+## Learning Curriculum
+
+| Module | Topic | Description |
+| :--- | :--- | :--- |
+| **[01](modules/01-mathematical-foundations)** | Mathematical Foundations | Linear algebra, matrix exponential, RK4 integration, numerical optimization. |
+| **[02](modules/02-dynamic-system-modeling)**  | Dynamic System Modeling | First-principles physics, state-space representations, Jacobian linearisation. |
+| **[03](modules/03-classical-control)**        | Classical Control | Filtered derivative PID, conditional anti-windup clamping, frequency response. |
+| **[04](modules/04-modern-control)**           | Modern Control & Estimation | Controllability, observability, Ackermann pole placement, Luenberger observers, Kalman filters (linear, EKF, UKF). |
+| **[05](modules/05-optimal-control)**          | Optimal & Constrained Control | Algebraic Riccati equations (CARE/DARE), LQR robustness margins, constrained active-set Model Predictive Control. |
+| **[06](modules/06-machine-learning)**         | ML for Dynamical Systems | Least-squares SysID, DMDc, neural MLP backprop + Adam, residual LearnedDynamics, sampling-based MPC (CEM). |
+| **[07](modules/07-reinforcement-learning)**   | Reinforcement Learning | Gymnasium `ControlEnv`, Tabular Q-Learning, Deep Q-Networks (DQN), REINFORCE, and Proximal Policy Optimization (PPO). |
+| **[08](modules/08-ai-plus-control)**          | AI + Control (Hybrid Safety) | Supervisory safety shielding, action filtering, control barrier functions, auditable intervention logging. |
+| **[09](modules/09-robotics-capstones)**       | Robotics Capstones | Full 6-state Crazyflie 2.0 Quadrotor, differential flatness inversion, Bryson scaling, EKF output feedback, MRAC, obstacle NMPC. |
+| **[10](modules/10-intelligent-control-challenge)** | 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), 28 empirical benchmark experiments, living technical report, unified visualization layer (`aimct.viz`), design-time preview dashboard (`aimct.dev`), and 7 interactive sandboxes are complete with **418 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), and Furuta rotary inverted pendulums (Exp 28 Quanser QUBE-Servo 2 benchmark).
+- **Track B (Algorithmic Depth):** Real-time iteration Nonlinear MPC (Exp 24, 26, 25 iLQR / RTI-NMPC vs. Sampling MPC).
+- **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`](docs/roadmap.md) for detailed deliverables and development history.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow and engineering
+agreement, and the [Code of Conduct](CODE_OF_CONDUCT.md). Found a security
+issue? See [SECURITY.md](SECURITY.md) for how to report it privately.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

aimct-0.1.0/README.md

@@ -0,0 +1,165 @@
+# AI Meets Control Theory
+
+### From Classical Control to Intelligent Autonomous Systems
+
+[![CI](https://github.com/zalihthomas-ui/ai-meets-control-theory/actions/workflows/ci.yml/badge.svg)](https://github.com/zalihthomas-ui/ai-meets-control-theory/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](pyproject.toml)
+[![Report: Living PDF](https://img.shields.io/badge/Report-Living%20PDF-brightgreen)](docs/report/ai-meets-control-theory.pdf)
+
+**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)](docs/report/ai-meets-control-theory.pdf)**  |  📖 **[User Guide & API Recipes](docs/USAGE.md)**  |  🎨 **[Unified Visualization](docs/VISUALIZATION.md)**  |  📊 **[Master Results & Verdicts Table](docs/RESULTS.md)**  |  🧭 **[Engineering Decision Guide](docs/DECISION-GUIDE.md)**  |  🚁 **[Live 3D WebGL Sandbox](https://claude.ai/code/artifact/69b12b78-d7b2-4732-a7af-2af14930139b)**  |  🎯 **[Project Vision & Manifesto](docs/vision.md)**
+
+---
+
+## Quickstart & Installation
+
+```bash
+# 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 (418 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`](docs/USAGE.md) for the 5-axis framework guide (*system × controller × trajectory × disturbance × parameters*) and copy-paste recipes.  
+🎨 **Unified Visualization:** See [`docs/VISUALIZATION.md`](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`](docs/DEV_PREVIEW.md) for model inspection and Jacobian validation (`python -m aimct preview <Plant> --watch`).  
+📦 **Packaging & Releases:** See [`docs/PACKAGING.md`](docs/PACKAGING.md) for the PyPI distribution runbook and [`CHANGELOG.md`](CHANGELOG.md) for the version history.
+
+---
+
+## The Experiments (01–28)
+
+Every experiment is self-contained with its own configuration, runner, Markdown/CSV benchmark table, and publication-ready 4-panel figure. See [`docs/RESULTS.md`](docs/RESULTS.md) for full metrics.
+
+| Exp | Directory | Plant | Key Comparison | Empirical Finding & Verdict |
+| :--- | :--- | :--- | :--- | :--- |
+| **01** | [`01_integrator_accuracy`](experiments/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`](experiments/02_linearization_validity/) | Inverted Pendulum | Linear vs Nonlinear ODE | Linear state-space diverges at $|\theta_0| > 23^\circ$; validity is strictly local. |
+| **03** | [`03_pid_stabilizes_unstable`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/08_mpc_vs_lqr_constrained_cartpole/) | Cart-Pole (Bounds) | Constrained MPC vs LQR | Active-set QP MPC strictly respects $|x| \le 0.5\,\text{m}$, while LQR violates rail by $23\%$. |
+| **09** | [`09_control_on_identified_model`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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`](experiments/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}$. |
+
+---
+
+## Framework Architecture & Package Layout
+
+```
+src/aimct/
+  systems/        DynamicalSystem base + LinearSystem, MassSpringDamper,
+                  Pendulum, CartPole, PlanarQuadrotor (Crazyflie 2.0), DCMotor,
+                  DifferentialDriveRobot, TwoLinkArm, BicycleVehicle,
+                  FurutaPendulum
+  simulate.py     rk4_step(), simulate() -> Trajectory(t, x, u, y)
+  controllers/    PID, StateFeedback, LQR, ObserverFeedback, MRAC, ComputedTorque,
+                  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
+  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
+```
+
+1. **Understand the mathematics:** First-principles ODEs, Riccati equations, Lyapunov stability, Hamiltonians, Hamilton-Jacobi-Bellman, GAE.
+2. **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.
+3. **Validate against reality:** Hard actuator saturation, sensor noise, latency, parameter drift, unmeasured states, non-convex keep-out zones.
+4. **Compare honestly:** Side-by-side Pareto tables under identical random seeds, step sizes, and initial conditions.
+
+---
+
+## Learning Curriculum
+
+| Module | Topic | Description |
+| :--- | :--- | :--- |
+| **[01](modules/01-mathematical-foundations)** | Mathematical Foundations | Linear algebra, matrix exponential, RK4 integration, numerical optimization. |
+| **[02](modules/02-dynamic-system-modeling)**  | Dynamic System Modeling | First-principles physics, state-space representations, Jacobian linearisation. |
+| **[03](modules/03-classical-control)**        | Classical Control | Filtered derivative PID, conditional anti-windup clamping, frequency response. |
+| **[04](modules/04-modern-control)**           | Modern Control & Estimation | Controllability, observability, Ackermann pole placement, Luenberger observers, Kalman filters (linear, EKF, UKF). |
+| **[05](modules/05-optimal-control)**          | Optimal & Constrained Control | Algebraic Riccati equations (CARE/DARE), LQR robustness margins, constrained active-set Model Predictive Control. |
+| **[06](modules/06-machine-learning)**         | ML for Dynamical Systems | Least-squares SysID, DMDc, neural MLP backprop + Adam, residual LearnedDynamics, sampling-based MPC (CEM). |
+| **[07](modules/07-reinforcement-learning)**   | Reinforcement Learning | Gymnasium `ControlEnv`, Tabular Q-Learning, Deep Q-Networks (DQN), REINFORCE, and Proximal Policy Optimization (PPO). |
+| **[08](modules/08-ai-plus-control)**          | AI + Control (Hybrid Safety) | Supervisory safety shielding, action filtering, control barrier functions, auditable intervention logging. |
+| **[09](modules/09-robotics-capstones)**       | Robotics Capstones | Full 6-state Crazyflie 2.0 Quadrotor, differential flatness inversion, Bryson scaling, EKF output feedback, MRAC, obstacle NMPC. |
+| **[10](modules/10-intelligent-control-challenge)** | 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), 28 empirical benchmark experiments, living technical report, unified visualization layer (`aimct.viz`), design-time preview dashboard (`aimct.dev`), and 7 interactive sandboxes are complete with **418 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), and Furuta rotary inverted pendulums (Exp 28 Quanser QUBE-Servo 2 benchmark).
+- **Track B (Algorithmic Depth):** Real-time iteration Nonlinear MPC (Exp 24, 26, 25 iLQR / RTI-NMPC vs. Sampling MPC).
+- **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`](docs/roadmap.md) for detailed deliverables and development history.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow and engineering
+agreement, and the [Code of Conduct](CODE_OF_CONDUCT.md). Found a security
+issue? See [SECURITY.md](SECURITY.md) for how to report it privately.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

aimct-0.1.0/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aimct"
+dynamic = ["version"]
+description = "AI Meets Control Theory — A rigorous, code-first bridge from classical feedback control to modern machine learning and safe reinforcement learning"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Zalih Thomas", email = "zalihthomas@gmail.com" }
+]
+keywords = [
+    "control-theory",
+    "reinforcement-learning",
+    "optimal-control",
+    "lqr",
+    "mpc",
+    "neural-odes",
+    "sindy",
+    "control-barrier-functions",
+    "robotics",
+    "dynamical-systems",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "numpy>=1.26",
+    "scipy>=1.11",
+    "matplotlib>=3.8",
+]
+
+[project.optional-dependencies]
+# python-control: used to cross-check from-scratch implementations. The core
+# library still must not import it at runtime — keep it test-only.
+xcheck = ["control>=0.10"]
+ml = [
+    "torch>=2.2",
+    "gymnasium>=1.0",
+    "stable-baselines3>=2.0",
+]
+viz = ["pyvista>=0.44"]
+dev = [
+    "pytest>=8.0",
+    "build>=1.0",
+    "twine>=5.0",
+    "control>=0.10",
+]
+
+[project.scripts]
+aimct = "aimct.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/zalihthomas-ui/ai-meets-control-theory"
+Documentation = "https://github.com/zalihthomas-ui/ai-meets-control-theory#readme"
+Repository = "https://github.com/zalihthomas-ui/ai-meets-control-theory.git"
+"Bug Tracker" = "https://github.com/zalihthomas-ui/ai-meets-control-theory/issues"
+Changelog = "https://github.com/zalihthomas-ui/ai-meets-control-theory/blob/main/CHANGELOG.md"
+
+[tool.setuptools.dynamic]
+version = { attr = "aimct.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "slow: heavy RL / learned-model training tests (minutes). Skip with -m 'not slow'.",
+]

aimct-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aimct-0.1.0/src/aimct/__init__.py

@@ -0,0 +1,13 @@
+"""AI Meets Control Theory — reusable library.
+
+Subpackages
+-----------
+systems      : dynamical-system models with a common interface
+controllers  : PID, state feedback, LQR, MPC, neural, RL policies
+estimation   : observers, Kalman filters
+ml           : learned dynamics, surrogate models
+rl           : agents and environments
+benchmarks   : standardized systems + controller comparison harness
+"""
+
+__version__ = "0.1.0"