How commaai/controls_challenge works
Project type and purpose
• This is a domain-specific simulation and evaluation tool rather than a typical web app. Its goal is to simulate lateral dynamics of a car (via an ONNX “TinyPhysics” model), let user-provided controllers generate steering commands, and then evaluate those controllers by computing cost metrics.
File structure
• Top-level scripts:
• tinyphysics.py: main simulation loop + CLI for single or batch runs
• eval.py: runs comparative evaluations and generates an HTML report
• experiment.ipynb: notebook for exploratory analysis
• Directories:
• controllers/: each file (pid.py, zero.py, __init__.py) implements a controller plugin
• models/: holds the ONNX TinyPhysics model
• imgs/: (presumably) stores generated plots/images for reports
• Configs & metadata:
• requirements.txt: Python dependencies (e.g., onnxruntime)
• . github/workflows/main.yml: CI tests that ensure the scripts and controllers still run
README for additional insights
• Confirms the flow:
• Load real-world driving states (CSV)
• Call TinyPhysics model autoregressively to predict lateral accel
• Pass those predictions + target trajectory into a controller
• Controller returns steer_action → feed back into model
• Aggregate lataccel_cost and jerk_cost
• Shows CLI patterns and output targets (report.html)
a. Main components
1. Data Loader
2. Simulation Engine (TinyPhysics ONNX model + inference engine)
3. Controller Module (plugin architecture)
4. Cost Evaluator
5. Report Generator / Notebook Interface
6. Orchestration & CLI (tinyphysics.py, eval.py)
7. External: ONNX Runtime, Python environment, input CSV data, output HTML/images
b. Relationships & data flow
• Data Loader → initial states → Simulation Engine
• Simulation Engine outputs predicted lateral accel → Controller Module
• Controller generates steer_action → back to Simulation Engine (loop)
• After rollout: Simulation Engine + Controller → Cost Evaluator
• Cost Evaluator → Report Generator (HTML + imgs/) / Notebook
• CLI frontends (tinyphysics.py, eval.py) orchestrate entire flow
c. Architectural patterns
• Plugin pattern for controllers: controllers/__init__.py dynamically imports pid, zero, or user-written controllers
• Batching & orchestration: CLI parameters control whether you run one segment or many (–num_segs)
• Separation of concerns: simulation vs. control vs. evaluation vs. reporting
d. Key technologies
• Python 3.11
• onnxruntime (for TinyPhysics inference)
• NumPy/Pandas (likely in data processing)
• Matplotlib/Plotly (for imgs in reports)
• GitHub Actions (CI)