Metadata-Version: 2.4
Name: cavsandbox
Version: 0.11.2
Summary: Python simulation of longitudinal car-following with ACC, CACC, and human driver models
Author-email: Mike McGurrin <mike.mcgurrin@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Michael McGurrin
        
        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.
License-File: LICENSE
Keywords: ACC,CACC,IDM,V2V,adaptive cruise control,automotive,autonomous vehicles,car-following,connected vehicles,cooperative adaptive cruise control,intelligent driver model,platoon,string stability,traffic simulation,transportation engineering
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.11
Requires-Dist: filelock
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: openpyxl
Requires-Dist: pandas
Requires-Dist: pygame
Requires-Dist: pyyaml
Description-Content-Type: text/markdown

![CAVSandbox logo with cars, sine waves, and open simulation with python tagline]( https://raw.githubusercontent.com/ViennaMike/CAVSandbox/main/docs/assets/cavsandbox-horizontal-1600px.png)

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`.

```bash
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](docs/quickstart_guide.md).

## Common Commands

```bash
# 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](docs/quickstart_guide.md)      | All users — install, run, and modify your first scenario         |
| [Input Template](examples/input_template.xlsx)     | Blank template for the scenario input Excel workbook.            |
| [User Guide](docs/user_guide.md)                   | Full reference for all parameters and output formats             |
| [Worked Examples](examples)                        | Pre-built research scenarios with interpretation                 |
| [Plugin Author Guide](docs/plugin_author_guide.md) | Write new driving models and filters                             |
| [CACC Design Notes](CACC_Design_Notes.md)          | 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
