MIXSim

MIXSim is a multiclass first-order macroscopic traffic simulation framework for mixed-autonomy signalized urban networks. Human-driven vehicles (HDVs) and Connected and Automated Vehicles (CAVs) are represented as separate classes within origin-destination commodities. Local class composition modifies both the triangular fundamental-diagram parameters and the saturation flow of signalized movements.

This repository contains the simulation core, reproducible manuscript studies, interactive HTML visualization examples, automated tests, documentation, and validated reference results.

Installation

git clone https://github.com/HarisFateh/MIXSim.git
cd MIXSim
python -m pip install -e ".[dev]"
pytest -q

Python 3.10 or newer is required.

Quick start

The two-intersection tutorial is the recommended first example:

python examples/two_intersection_tutorial.py --quick --skip-html

For the complete tutorial, including the standalone interactive HTML replay:

python examples/two_intersection_tutorial.py

The tutorial contains two signalized intersections with genuine OD-dependent route choices and demonstrates multiclass commodities, movement-specific saturation, virtual-origin queues, signal phases, routing fractions, conservation diagnostics, and browser-based playback.

See docs/two_intersection_tutorial.md.

Interactive HTML examples using the manuscript demand

Two dedicated visualization examples use the same demand builders as the numerical studies, avoiding duplicated or inconsistent demand definitions.

Isolated intersection

python examples/isolated_intersection_visualization.py

This uses the manuscript one-hour isolated-intersection demand profile and signal plan. The generated replay is:

outputs/isolated_intersection_visualization/isolated_intersection.html

4x4 grid

python examples/grid_network_visualization.py

This uses the manuscript one-hour grid OD demand, dynamic shortest-path routing, and the capacity-weighted Max Pressure baseline used in the CAV-penetration study. The generated replay is:

outputs/grid_network_visualization/grid_network.html

See docs/html_visualizations.md for options and file-size guidance.

Reproducible numerical studies

Study	Script
Isolated intersection: CAV penetration	studies/isolated_intersection_cav_penetration.py
4x4 grid: CAV penetration	studies/grid_cav_penetration.py
4x4 grid: CAV time gap	studies/grid_cav_time_gap.py
4x4 grid: mixed autonomy × signal control	studies/grid_signal_control_comparison.py
Demand-profile figures	studies/generate_demand_profiles.py
Fundamental-diagram figures	studies/figures/composition_dependent_fd.py, studies/figures/fd_sensitivity.py

Quick smoke tests:

python studies/isolated_intersection_cav_penetration.py --quick
python studies/grid_cav_penetration.py --quick
python studies/grid_cav_time_gap.py --quick
python studies/grid_signal_control_comparison.py --quick

Full reproduction instructions are in docs/reproduce_manuscript.md.

Metric convention

All reported system-level metrics use physical network accumulation A(t) plus virtual-origin queues B(t):

TST = dt/3600 * sum_t [A(t) + B(t)]
PA  = max_t [A(t) + B(t)]
CT  = first post-demand state with A(t) + B(t) <= 1e-4 veh

Validated numerical targets are stored in reference_results/.

Validation

Continuous integration runs on Python 3.10, 3.11, and 3.12. Local fast validation is:

python -m pip install -e ".[dev]"
python -m pip check
pytest -q
python -m compileall -q src examples studies tools
python examples/isolated_intersection_visualization.py --quick --output-dir outputs/ci_isolated_visual
python examples/grid_network_visualization.py --quick --output-dir outputs/ci_grid_visual

After running the full numerical studies:

python tools/validate_reference_results.py

See RELEASE_VALIDATION.md for the release validation record and REPRODUCIBILITY_NOTES.md for reproducibility decisions.

Repository structure

src/mixsim/          simulation library
examples/            tutorials and interactive HTML visualization examples
studies/             reproducible manuscript studies and figure scripts
tests/               automated unit and regression tests
tools/               reference-result validation utilities
docs/                installation, tutorials, model mapping, and reproduction notes
reference_results/   validated manuscript table values

Generated outputs, caches, build products, and virtual environments are excluded by .gitignore.

Citation

If you use MIXSim in your research, please cite:

Muhammad Haris and Claudio Roncoli,
MIXSim: A multiclass first order traffic model with composition-dependent dynamics for mixed-autonomy urban networks,
arXiv preprint, 2026.

arXiv:2610.23714

@article{haris2026mixsim,
  title   = {MIXSim: A multiclass first order traffic model with composition-dependent dynamics for mixed-autonomy urban networks},
  author  = {Haris, Muhammad and Roncoli, Claudio},
  journal = {arXiv preprint arXiv:2610.23714},
  year    = {2026}
}

License

MIXSim is released under the MIT License. See LICENSE.