# commaai/controls_challenge architecture

> Architecture diagram of the GitHub repository commaai/controls_challenge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/commaai/controls_challenge
- Repository: https://github.com/commaai/controls_challenge

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Orchestrator
    subgraph "CLI Orchestrator"
        TinyCLI["tinyphysics.py"]:::orchestrator
        EvalCLI["eval.py"]:::orchestrator
    end

    %% Simulation Layer
    subgraph "Simulation Layer"
        DataLoader["Data Loader"]:::core
        SimulationEngine["Simulation Engine"]:::core
        ONNXModel["tinyphysics.onnx"]:::core
        ONNXRuntime["ONNX Runtime"]:::external
    end

    %% Controller Plugins
    subgraph "Controller Module (Plugin Architecture)"
        ControllerInit["__init__.py"]:::plugin
        PID["pid.py"]:::plugin
        ZERO["zero.py"]:::plugin
    end

    %% Evaluation & Reporting
    subgraph "Evaluation & Reporting"
        CostEvaluator["Cost Evaluator"]:::eval
        ReportGenerator["Report Generator"]:::eval
        IMGS["imgs/"]:::eval
        Notebook["experiment.ipynb"]:::eval
    end

    %% External Dependencies
    subgraph "External Dependencies"
        Requirements["requirements.txt"]:::external
        CI[".github/workflows/main.yml"]:::external
        CSVData["Input CSV Data (CSV)"]:::external
        PythonEnv["Python Environment"]:::external
    end

    %% Orchestration flows
    TinyCLI -->|runs single or batch| DataLoader
    TinyCLI -->|orchestrates| SimulationEngine
    EvalCLI -->|runs comparative eval| CostEvaluator
    EvalCLI -->|generates| ReportGenerator

    %% Simulation flows
    DataLoader -->|"initial states"| SimulationEngine
    SimulationEngine -->|"v_ego, a_ego…"| ControllerInit
    ControllerInit -->|"steer_action"| SimulationEngine
    SimulationEngine -->|autoreg loop| ControllerInit

    %% Model dependencies
    SimulationEngine -->|loads model| ONNXModel
    ONNXModel -->|inference| ONNXRuntime

    %% Evaluation flows
    SimulationEngine -->|"rollouts"| CostEvaluator
    ControllerInit -->|"control data"| CostEvaluator
    CostEvaluator -->|"metrics"| ReportGenerator
    ReportGenerator --> IMGS
    ReportGenerator --> Notebook

    %% External deps usage
    Requirements -.-> PythonEnv
    PythonEnv -.-> SimulationEngine
    PythonEnv -.-> ControllerInit
    PythonEnv -.-> CostEvaluator
    CSVData --> DataLoader
    CI -.-> TinyCLI
    CI -.-> EvalCLI

    %% Click Events
    click TinyCLI "https://github.com/commaai/controls_challenge/blob/master/tinyphysics.py"
    click EvalCLI "https://github.com/commaai/controls_challenge/blob/master/eval.py"
    click DataLoader "https://github.com/commaai/controls_challenge/blob/master/tinyphysics.py"
    click SimulationEngine "https://github.com/commaai/controls_challenge/blob/master/tinyphysics.py"
    click ONNXModel "https://github.com/commaai/controls_challenge/blob/master/models/tinyphysics.onnx"
    click ControllerInit "https://github.com/commaai/controls_challenge/blob/master/controllers/__init__.py"
    click PID "https://github.com/commaai/controls_challenge/blob/master/controllers/pid.py"
    click ZERO "https://github.com/commaai/controls_challenge/blob/master/controllers/zero.py"
    click CostEvaluator "https://github.com/commaai/controls_challenge/blob/master/eval.py"
    click ReportGenerator "https://github.com/commaai/controls_challenge/blob/master/eval.py"
    click IMGS "https://github.com/commaai/controls_challenge/tree/master/imgs/"
    click Notebook "https://github.com/commaai/controls_challenge/blob/master/experiment.ipynb"
    click Requirements "https://github.com/commaai/controls_challenge/blob/master/requirements.txt"
    click CI "https://github.com/commaai/controls_challenge/blob/master/.github/workflows/main.yml"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
    classDef plugin fill:#ABEBC6,stroke:#196F3D,color:#145A32;
    classDef eval fill:#F9E79F,stroke:#B7950B,color:#7D6608;
    classDef orchestrator fill:#D7BDE2,stroke:#6C3483,color:#4A235A;
    classDef external fill:#D5D8DC,stroke:#566573,color:#2C3E50;
```
