aimct 0.1.0__py3-none-any.whl

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"

aimct/__main__.py

@@ -0,0 +1,203 @@
+"""``python -m aimct`` — run a controller bake-off on a built-in system.
+
+    python -m aimct compare --system cartpole --out my_study
+    python -m aimct compare --system quadrotor --t-final 12
+    python -m aimct list
+    python -m aimct live arm
+    python -m aimct preview mymodule.py:MyPlant --watch
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+import numpy as np
+
+from .study import run_study
+
+# name -> (factory, default study kwargs)
+_PRESETS = {
+    "mass_spring_damper": (
+        lambda: _msd(), dict(x0=[1.0, 0.0], dt=0.01, t_final=20.0, output_index=0),
+    ),
+    "pendulum": (
+        # regulate a disturbed pendulum back to rest (theta = 0 hangs down);
+        # auto_controllers designs the LQR about x = 0, so the reference is 0.
+        lambda: _pendulum(),
+        dict(x0=[0.6, 0.0], dt=0.01, t_final=6.0, reference=0.0,
+             output_index=0,
+             Q=np.diag([10.0, 1.0]), R=np.array([[0.5]]),
+             u_bounds=(-8.0, 8.0)),
+    ),
+    "cartpole": (
+        lambda: _cartpole(),
+        dict(x0=[0.0, 0.0, 0.2, 0.0], dt=0.01, t_final=5.0, output_index=2,
+             deriv_index=3, Q=np.diag([10.0, 1.0, 100.0, 10.0]),
+             R=np.array([[0.1]]), u_bounds=(-20.0, 20.0)),
+    ),
+    "quadrotor": (
+        lambda: _quad(),
+        dict(x0=[0.3, 1.0, 0.15, 0.0, 0.0, 0.0], dt=0.004, t_final=6.0,
+             output_index=0,
+             Q=np.diag(1.0 / np.array([0.1, 0.1, 0.2, 0.5, 0.5, 3.0]) ** 2),
+             R=np.diag(1.0 / np.array([0.15, 0.15]) ** 2),
+             u_bounds=(0.0, 0.30)),
+    ),
+}
+
+
+def _msd():
+    from .systems import MassSpringDamper
+    return MassSpringDamper()
+
+
+def _pendulum():
+    from .systems import Pendulum
+    return Pendulum()
+
+
+def _cartpole():
+    from .systems import CartPole
+    return CartPole()
+
+
+def _quad():
+    from .systems import PlanarQuadrotor
+    return PlanarQuadrotor()
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="python -m aimct")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    pc = sub.add_parser("compare", help="run LQR + MPC (+ your own) on a system")
+    pc.add_argument("--system", required=True, choices=sorted(_PRESETS))
+    pc.add_argument("--out", default=None, help="directory for table.md / figure.png")
+    pc.add_argument("--t-final", type=float, default=None)
+    pc.add_argument("--dt", type=float, default=None)
+
+    sub.add_parser("list", help="list the built-in systems (* = has a compare preset)")
+
+    pl = sub.add_parser("live", help="interactive sandbox: drone / arm / diffdrive")
+    pl.add_argument("target", nargs="?", default="drone",
+                    choices=["drone", "drone3d", "arm", "arm3d", "diffdrive",
+                             "armbalance", "armbalance3d"],
+                    help="which sandbox (default: drone)")
+    pl.add_argument("--headless", action="store_true",
+                    help="run the physics smoke check without a GUI")
+    pl3 = sub.add_parser("live3d", help="alias for `live drone3d` (6-DOF drone sandbox)")
+    pl3.add_argument("--headless", action="store_true",
+                     help="run the physics smoke check without a GUI")
+    pl3.add_argument("--matplotlib", action="store_true",
+                     help="force the lightweight matplotlib-3D renderer")
+    pl3.add_argument("--web", action="store_true",
+                     help="serve the experimental WebGL/Three.js visualizer")
+
+    pp = sub.add_parser("preview", help="design-time preview for a DynamicalSystem "
+                                        "you are writing (see docs/DEV_PREVIEW.md)")
+    pp.add_argument("target", help="'module:Class' or 'path/to/file.py:Class'")
+    pp.add_argument("--out", default="design_preview.png",
+                    help="PNG path to (re)write (default: design_preview.png)")
+    pp.add_argument("--watch", action="store_true",
+                    help="poll the source file and rebuild on every change")
+    pp.add_argument("--poll", type=float, default=1.0, help="watch poll interval [s]")
+    pp.add_argument("--t-final", type=float, default=4.0)
+    pp.add_argument("--dt", type=float, default=0.01)
+
+    args = p.parse_args(argv)
+
+    if args.cmd == "preview":
+        from .dev import preview_once, watch
+
+        kw = dict(dt=args.dt, t_final=args.t_final)
+        if args.watch:
+            print(f"watching {args.target} -> {args.out} (Ctrl+C to stop)")
+            try:
+                watch(args.target, out=args.out, poll=args.poll, **kw)
+            except KeyboardInterrupt:
+                print("\nstopped")
+            return 0
+        report = preview_once(args.target, out=args.out, **kw)
+        print(report.summary())
+        print(f"\nwrote {args.out}")
+        return 0
+
+    if args.cmd == "list":
+        from . import systems as _sys
+
+        print("runnable via `aimct compare --system <name>`:")
+        for name in sorted(_PRESETS):
+            print(f"  {name}")
+        skip = {"DynamicalSystem", "LinearSystem"}
+        extra = [c for c in sorted(getattr(_sys, "__all__", []))
+                 if c not in skip and isinstance(getattr(_sys, c, None), type)]
+        print("\nalso in aimct.systems (import directly; no compare preset yet):")
+        for c in extra:
+            print(f"  aimct.systems.{c}")
+        return 0
+
+    if args.cmd in ("live", "live3d"):
+        import runpy
+        from pathlib import Path
+
+        target = "drone3d" if args.cmd == "live3d" else args.target
+        d = Path(__file__).resolve().parents[2] / "experiments"
+        if not d.is_dir():
+            print(
+                "The interactive sandboxes live under experiments/ in the source\n"
+                "checkout and are not shipped in the installed package. Clone the\n"
+                "repo and run from there:\n"
+                "  git clone https://github.com/zalihthomas-ui/ai-meets-control-theory\n"
+                "  cd ai-meets-control-theory\n"
+                f"  python -m aimct live {target}",
+                file=sys.stderr,
+            )
+            return 1
+        headless = getattr(args, "headless", False)
+        if target == "drone":
+            script = d / "live_drone" / "live.py"
+        elif target in ("arm", "arm3d"):
+            # same physics either way; --headless never needs PyVista
+            sub = "run.py" if (target == "arm" or headless) else "pv_arm.py"
+            script = d / "live_arm" / sub
+        elif target in ("armbalance", "armbalance3d"):
+            sub = "run.py" if (target == "armbalance" or headless) else "pv_arm.py"
+            script = d / "live_arm_balance" / sub
+        elif target == "diffdrive":
+            script = d / "live_diffdrive" / "run.py"
+        elif getattr(args, "web", False):
+            script = d / "live_drone_3d" / "web.py"
+        elif getattr(args, "matplotlib", False) or getattr(args, "headless", False):
+            script = d / "live_drone_3d" / "sim3d.py"
+        else:
+            # prefer the PyVista renderer; fall back to matplotlib if not installed
+            try:
+                import pyvista  # noqa: F401
+                script = d / "live_drone_3d" / "pv3d.py"
+            except Exception:
+                script = d / "live_drone_3d" / "sim3d.py"
+        sys.argv = [str(script)] + (["--headless"] if getattr(args, "headless", False) else [])
+        runpy.run_path(str(script), run_name="__main__")
+        return 0
+
+    factory, kw = _PRESETS[args.system]
+    kw = dict(kw)
+    if args.t_final is not None:
+        kw["t_final"] = args.t_final
+    if args.dt is not None:
+        kw["dt"] = args.dt
+    kw["out_dir"] = args.out
+
+    res = run_study(factory(), title=f"{args.system} bake-off", **kw)
+    print(res.to_markdown())
+    if hasattr(res, "summary"):
+        print()
+        print(res.summary())
+    if args.out:
+        print(f"\nwrote artifacts to {args.out}/")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

aimct/benchmarks/__init__.py

@@ -0,0 +1,96 @@
+"""
+Benchmark suites, metrics, and comparison harnesses.
+"""
+
+from aimct.benchmarks.capstone_scoring import (
+    CAPSTONE_BASELINES,
+    CAPSTONE_WEIGHTS,
+    capstone_leaderboard_table,
+    score_capstone,
+    score_capstone_entry,
+)
+from aimct.benchmarks.challenge_scoring import (
+    NORMALISERS,
+    WEIGHTS,
+    BaselineCosts,
+    ChallengeScoreResult,
+    SafetyEnvelope,
+    ScoreWeights,
+    evaluate_safety,
+    robust_degradation,
+    score_run,
+)
+from aimct.benchmarks.challenge_wrappers import (
+    ActuatorLag,
+    BlackBoxEnvironment,
+    BlackBoxPlant,
+    ImpulseDisturbance,
+    ImpulseInjector,
+    ParamPerturbed,
+    perturbed_system,
+)
+from aimct.benchmarks.harness import ComparisonResult, compare
+from aimct.benchmarks.metrics import (
+    compute_all_metrics,
+    control_energy,
+    iae,
+    ise,
+    itae,
+    peak_control,
+    peak_overshoot,
+    peak_time,
+    rise_time,
+    rmse,
+    saturation_duty_cycle,
+    settling_time,
+    slew_rate,
+    steady_state_error,
+)
+from aimct.benchmarks.sweep import SweepResult, sweep
+from aimct.benchmarks.tracking import TrackingResult, track_trajectory
+
+__all__ = [
+    "rise_time",
+    "settling_time",
+    "peak_overshoot",
+    "peak_time",
+    "steady_state_error",
+    "rmse",
+    "iae",
+    "itae",
+    "ise",
+    "control_energy",
+    "peak_control",
+    "slew_rate",
+    "saturation_duty_cycle",
+    "compute_all_metrics",
+    "compare",
+    "ComparisonResult",
+    "sweep",
+    "SweepResult",
+    "track_trajectory",
+    "TrackingResult",
+    # Challenge scoring & wrappers
+    "WEIGHTS",
+    "NORMALISERS",
+    "ScoreWeights",
+    "BaselineCosts",
+    "SafetyEnvelope",
+    "ChallengeScoreResult",
+    "robust_degradation",
+    "evaluate_safety",
+    "score_run",
+    "ParamPerturbed",
+    "perturbed_system",
+    "ActuatorLag",
+    "ImpulseDisturbance",
+    "ImpulseInjector",
+    "BlackBoxPlant",
+    "BlackBoxEnvironment",
+    # Capstone scoring & bake-off
+    "CAPSTONE_WEIGHTS",
+    "CAPSTONE_BASELINES",
+    "score_capstone_entry",
+    "score_capstone",
+    "capstone_leaderboard_table",
+]

aimct/benchmarks/capstone_scoring.py

@@ -0,0 +1,174 @@
+"""
+Capstone Evaluation Rubric and Multi-Controller Scoring Engine.
+
+Conforms to docs/references/capstone-rubric.md for the Module 09 five-way quadrotor bake-off.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Mapping, Sequence
+
+import numpy as np
+
+# Standard Capstone Composite Weights (spec §2 & §3)
+CAPSTONE_WEIGHTS: dict[str, float] = {
+    "rmse": 0.40,
+    "energy": 0.20,
+    "slew": 0.10,
+    "safety": 0.15,
+    "robustness": 0.15,
+}
+
+# Canonical Quadrotor Figure-8 Baselines
+CAPSTONE_BASELINES: dict[str, float] = {
+    "rmse": 0.050,      # 5 cm position tracking error
+    "energy": 150.0,    # 150 N^2*s total thrust effort
+    "slew": 2500.0,     # Actuator slew rate penalty
+    "safety": 0.10,     # Boundary penalty threshold
+}
+
+
+def score_capstone_entry(
+    metrics: Mapping[str, float],
+    baseline: Mapping[str, float] | None = None,
+    weights: Mapping[str, float] | None = None,
+    *,
+    robust_factor: float = 1.0,
+    safety_ok: bool = True,
+    dq_reasons: Sequence[str] | None = None,
+    max_ratio: float = 10.0,
+) -> dict[str, object]:
+    """
+    Scores a single capstone controller evaluation against baseline costs.
+
+    Formula (spec §3):
+      S = 100 * exp( - [ 0.40 * r_pos + 0.20 * r_energy + 0.10 * r_slew + 0.15 * r_safety ] )
+          * S_robust * I(No Hard Disqualifications)
+    """
+    w = dict(weights or CAPSTONE_WEIGHTS)
+    base = dict(baseline or CAPSTONE_BASELINES)
+    reasons = list(dq_reasons or [])
+
+    m_rmse = float(metrics.get("rmse", metrics.get("pos_rmse", metrics.get("itae", 1.0))))
+    m_energy = float(metrics.get("control_energy", metrics.get("energy", 100.0)))
+    m_slew = float(metrics.get("slew_rate", metrics.get("slew", 1000.0)))
+    m_safety = float(metrics.get("violation_penalty", metrics.get("safety", 0.0)))
+
+    b_rmse = float(base.get("rmse", 0.05))
+    b_energy = float(base.get("energy", 150.0))
+    b_slew = float(base.get("slew", 2500.0))
+    b_safety = float(base.get("safety", 0.10))
+
+    # Capped cost ratios
+    r_rmse = min(max_ratio, m_rmse / max(1e-6, b_rmse))
+    r_energy = min(max_ratio, m_energy / max(1e-6, b_energy))
+    r_slew = min(max_ratio, m_slew / max(1e-6, b_slew))
+    r_safety = min(max_ratio, (m_safety + 1e-4) / max(1e-6, b_safety)) if m_safety > 0 else 0.0
+
+    norm_cost = (
+        w.get("rmse", 0.40) * r_rmse
+        + w.get("energy", 0.20) * r_energy
+        + w.get("slew", 0.10) * r_slew
+        + w.get("safety", 0.15) * r_safety
+    )
+
+    perf_base = float(100.0 * np.exp(-norm_cost))
+    r_factor = float(np.clip(robust_factor, 0.20, 1.0))
+
+    if not safety_ok or len(reasons) > 0:
+        status = "DISQUALIFIED"
+        composite = 0.0
+    else:
+        status = "PASS"
+        composite = float(perf_base * r_factor)
+
+    terms = {
+        "rmse_ratio": r_rmse,
+        "energy_ratio": r_energy,
+        "slew_ratio": r_slew,
+        "safety_ratio": r_safety,
+        "norm_cost": norm_cost,
+    }
+
+    breakdown = {
+        "precision": float(np.exp(-r_rmse)),
+        "effort": float(np.exp(-r_energy)),
+        "smoothness": float(np.exp(-r_slew)),
+        "safety": 1.0 if safety_ok else 0.0,
+        "robustness": r_factor,
+    }
+
+    return {
+        "composite": composite,
+        "status": status,
+        "terms": terms,
+        "breakdown": breakdown,
+        "metrics": dict(metrics),
+        "dq_reasons": reasons,
+    }
+
+
+def score_capstone(
+    metrics_per_controller: Mapping[str, Mapping[str, float]],
+    baseline: Mapping[str, float] | None = None,
+    weights: Mapping[str, float] | None = None,
+) -> dict[str, object]:
+    """
+    Evaluates and ranks all controllers in the five-way bake-off.
+    """
+    scores: dict[str, dict] = {}
+    for name, m in metrics_per_controller.items():
+        is_safe = m.get("hard_fail", 0.0) == 0.0
+        robust = float(m.get("s_robust", m.get("robustness", 1.0)))
+        dq_reasons = []
+        if not is_safe:
+            dq_reasons.append("Safety envelope or obstacle penetration breached.")
+        if float(m.get("mean_latency_ms", 0.0)) > 2.0:
+            dq_reasons.append(f"Step latency {m.get('mean_latency_ms'):.2f} ms exceeded 2.0 ms deadline.")
+
+        scores[name] = score_capstone_entry(
+            m,
+            baseline=baseline,
+            weights=weights,
+            robust_factor=robust,
+            safety_ok=is_safe and len(dq_reasons) == 0,
+            dq_reasons=dq_reasons,
+        )
+
+    # Rank controllers by composite score descending
+    ranked = sorted(scores.items(), key=lambda item: item[1]["composite"], reverse=True)
+    winner = ranked[0][0] if ranked and ranked[0][1]["composite"] > 0 else "None"
+
+    return {
+        "scores": scores,
+        "ranked": ranked,
+        "winner": winner,
+        "leaderboard_md": capstone_leaderboard_table(scores),
+    }
+
+
+def capstone_leaderboard_table(scores: Mapping[str, dict]) -> str:
+    """
+    Generates a Markdown leaderboard table for the Capstone report.
+    """
+    lines = [
+        "| Rank | Controller Entry | Score / 100 | Status | Tracking RMSE [m] | Energy $E_u$ | Slew Rate | $S_{\\text{robust}}$ | Latency [ms] |",
+        "| :---: | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |",
+    ]
+
+    ranked = sorted(scores.items(), key=lambda item: item[1]["composite"], reverse=True)
+    for rank, (name, s) in enumerate(ranked, 1):
+        m = s["metrics"]
+        rmse_val = m.get("rmse", m.get("pos_rmse", float("nan")))
+        energy_val = m.get("energy", m.get("control_energy", float("nan")))
+        slew_val = m.get("slew", m.get("slew_rate", float("nan")))
+        rob_val = m.get("s_robust", s["breakdown"]["robustness"])
+        lat_val = m.get("mean_latency_ms", float("nan"))
+
+        lines.append(
+            f"| **{rank}** | **{name}** | **{s['composite']:.1f}** | `{s['status']}` | "
+            f"{rmse_val:.4g} | {energy_val:.4g} | {slew_val:.4g} | {rob_val:.2f} | {lat_val:.2f} |"
+        )
+
+    return "\n".join(lines) + "\n"