cavsandbox 0.11.1

Python simulation of longitudinal car-following with ACC, CACC, and human driver models

A Python simulation of longitudinal car-following for Adaptive Cruise Control (ACC), Cooperative ACC (CACC), and human driver models. Designed as a teaching and research tool for students and researchers studying car-following behavior, advanced cruise control, and connected and automated vehicles.

CAVSandbox models three driver types: human, ACC, and CACC. There is a built-in driver model for each of these types, but a plugin system allows the user to substitute their own driver models. The simulation includes realistic radar noise, IMU noise, and V2V communications. All scenario configuration is done in Excel; no code changes are needed to run or modify scenarios (except for new plugins).

Features

• Built-in driving models — IDM human driver, IDM ACC, CACC with V2V feedforward, prescribed lead vehicle profile
• Realistic sensor pipeline — radar noise and delay with Kalman or low-pass filter; IMU bias drift; V2V BSM comms with packet drop and multi-rate fusion Kalman filter. Also the ability to turn these off for simple pass-throughs, if desired.
• Vehicle response model — first-order actuator lag with passive drag; kinematic mode for quick prototyping
• Plugin system — drop a Python file in plugins/ to add new driving models or filters; no core edits required
• Live Pygame renderer — top-down road view color-coded by model type, scrolling road markers, real-time speed chart, pause/resume
• CSV playback — replay any saved run through the live renderer with seek, step, and variable speed controls
• Post-run output — CSV state log, five-panel matplotlib plots, YAML metadata, and input Excel copy, all written to results/
• Excel input — configure vehicles, scenario, and lead profile in a spreadsheet; no code changes needed

Quick Start

Prerequisites: Python 3.11+ and uv.

pip install uv
git clone https://github.com/ViennaMike/cavsandbox.git
cd cavsandbox
uv pip install -e .
python -m cacc_sim.main examples/quickstart.xlsx

A Pygame window opens showing a four-vehicle CACC platoon following a step-change deceleration. Results are written to results/quickstart_<timestamp>/ when the run completes.

For a complete walkthrough including how to modify scenarios and interpret results, see the Quick-Start Guide.

Common Commands

# Run a simulation (live window)
python -m cacc_sim.main examples/quickstart.xlsx

# Run headless (set simulation_speed=0 in the Excel simulation sheet)
python -m cacc_sim.main my_scenario.xlsx

# Replay a saved run
python -m cacc_sim.main results/my_scenario_<timestamp>/data.csv

# Regenerate plots from an existing CSV
python -m cacc_sim.plot results/my_scenario_<timestamp>/data.csv --show

# Run tests
pytest

Documentation

Document	Audience
Quick-Start Guide	All users — install, run, and modify your first scenario
Input Template	Blank template for the scenario input Excel workbook.
User Guide	Full reference for all parameters and output formats
Worked Examples	Pre-built research scenarios with interpretation
Plugin Author Guide	Write new driving models and filters
CACC Design Notes	Maintainers and contributors — architecture and design rationale

Project Status

All seventeen steps of the planned development sequence are complete. The simulation supports:

• Four built-in driving models plus the Wiedemann99 plugin
• Passthrough and realistic sensor pipelines (Kalman filter and low-pass filter)
• Passthrough and V2V comms with multi-rate fusion Kalman filter
• Full five-panel post-run plotting and CSV/YAML output
• Real-time Pygame visualization and CSV playback

License

MIT