OpenCDA: co-simulating cooperative driving in CARLA and SUMO

What it is for, and who it is for

OpenCDA is an open co-simulation-based research and engineering framework integrated with prototype cooperative driving automation, CDA, pipelines as well as regular automated driving components such as perception, localization, planning, and control. It enables CDA evaluation in a CARLA plus SUMO co-simulation environment and also provides a rich library of source code for CDA research pipelines.

The intended audience is stated in terms that are unusually specific. In collaboration with U.S.DOT CDA Research and the FHWA CARMA Program, OpenCDA is designed and built to support early-stage fundamental research for CDA research and development. Through collaboration with CARMA Collaborative, the tool provides a capability to the CDA research community and will interface with the CARMA XiL tools being developed by U.S.DOT to support more advanced simulation testing of CDA features.

That positioning explains both the strengths and the limits. It is a research framework, so the code is written to be read and modified, and it is built to interface with a specific US federal toolchain, so it is not a general purpose driving simulator.

The primary language is Python, the licence in the setup.py is MIT with the authors listed as Runsheng Xu and Xu Han, and the default branch is main with active development on develop. The last push to the repository was on 2026-08-18, and the published releases are v0.1.2 from 2022-03-14, v0.1.1 from 2021-10-09, and v0.1.0 from 2021-07-27, so the version numbers have barely moved while the code has.

The six key features, and the one that is the real differentiator

The feature list has six entries, and one of them stands out for a reason the README spells out.

Research pipeline: rich research pipelines, meaning open-source codes for basic and advanced CDA modules such as platooning and cooperative perception. Integration: OpenCDA utilizes CARLA and SUMO separately as well as integrates them together. Full-stack simulation: a simple prototype automated driving and cooperative driving platform, all in Python, containing perception, localization, planning, control, and V2X communication modules. Modularity: the framework is highly modularized. Benchmark: benchmark testing scenarios, benchmark baseline maps, state-of-the-art benchmark algorithms, and benchmark evaluation metrics. And connectivity and cooperation: OpenCDA supports various levels and categories of cooperation between CAVs in simulation, and this differentiates OpenCDA from other single vehicle simulation tools.

That last one is the claim to take seriously. Most driving simulators put one car in a road. Cooperative driving automation is about several vehicles sharing information, and a framework that models the communication channel itself can test a behaviour that depends on latency, packet loss, and trust between agents. That is why the framework includes V2X communication as a first-class module rather than a plugin, and it is the thing the OPV2V dataset work and the cooperative perception work in the changelog are built on.

The all-in-Python constraint is also load-bearing. A pure Python stack means a research pipeline can be written, run, and debug without leaving the language, which is a real advantage when the thing under study is an algorithm rather than a renderer.

Four components, and the scenario manager

OpenCDA consists of four major components: the Cooperative Driving System, the Co-Simulation Tools, the Data Manager and Repository, and the Scenario Manager.

The cooperative driving system is the vehicle side, and it is what the research pipelines plug into. The co-simulation tools are the integration with CARLA and SUMO, both separately and together, which is the part that lets a scenario run in one simulator, the other, or both at once with traffic being handed over between them. The data manager and repository handle the offline data dumping, which is the mechanism the OPV2V benchmark dataset was built from. And the scenario manager is the top level, where a scenario is defined and the run is configured.

The changelog shows how the scenario and traffic sides have evolved. In October 2021, CARLA 0.9.12 became supported along with different weather conditions, and traffic management improved so that users can set a customised range for background cars. In March 2022 the HD map manager came online, supporting the generation of a rasterisation map that includes road topology, traffic light information, and dynamic objects around each CAV in real time, which the changelog says can be used for RL planning, HD map learning, and scene understanding. In March 2023 the configuration system was reworked, with a default.yaml provided as a template for all scenarios so that users only change the parts that differ from the default parameters, which makes the configuration file much cleaner.

That last change is worth noting for anyone who has used the earlier versions, since it is the kind of refactor that silently changes how your config files are read.

The research output, and the honesty about scope

The What's New section lists the papers that came out of the framework, and it is a reasonable proxy for what the code can do.

The V2X-ViT paper on vehicle-to-everything cooperative perception with a Vision Transformer was accepted at ECCV 2022, and it is powered by OpenCDA. The OPV2V paper, an open benchmark dataset and fusion pipeline for perception with vehicle-to-vehicle communication, was accepted at ICRA 2022, and it uses the offline cooperative perception data dumping function in OpenCDA. And the framework's own paper, The OpenCDA Open-source Ecosystem for Cooperative Driving Automation Research, was accepted by IEEE Transactions on Intelligent Vehicles in January 2023, extending the scope of the original simulation framework to an ecosystem containing a model zoo, a suite of driving simulators at various resolutions, large-scale real-world and simulated datasets, complete development toolkits for benchmark training and testing, and a scenario database and generator.

The scope disclaimer is the sentence to read before you plan an experiment. The project says it continuously improves the performance of OpenCDA, that it is currently mainly tested in the customised maps and the Carla town06 map, and therefore that it does not guarantee the same level of robustness in other maps.

That is a research team stating exactly where their validation is. A paper that reports results on the authors' own maps is a result about those maps. The framework will run on a public map, and whether it produces sensible behaviour there is an empirical question the project is explicitly not answering for you.

The citation request is the standard one, with a BibTeX entry for the OpenCDA paper, and the contribution rules ask for issues and pull requests using the repository's template.

The Docker image, and what it has to contain

Docker support arrived in March 2023, and the Dockerfile in the repository is a description of what a co-simulation image actually has to contain.

The script's stated job is performing all the necessary tasks regarding the generation of a generic OpenCDA Docker image, including installation of CARLA and its additional maps, perception components with PyTorch and YOLOv5, and SUMO. The base Docker image is Ubuntu 20.04 with CUDA 11.4.2 and Vulkan SDK 1.3.204.1, and the comment notes that if you want a different base image you may need to modify the ubuntu2004/x86_64 reference when fetching keys according to the Ubuntu release and system architecture.

The contents are the reason this is a real engineering task rather than a packaging exercise. CARLA is a large download with additional map assets, and SUMO is a separate simulator with its own tool chain. The perception components bring in PyTorch and YOLOv5, so the image carries a GPU stack, which is why CUDA and the Vulkan SDK are pinned. And the build arguments are case sensitive, with USER defaulting to opencda inside each container.

The repository also has environment.yml, which is the conda route for people who are not using Docker, plus requirements.txt, requirements_ci.txt, setup.sh, and a scripts/ directory. The requirements list is the simulation and analysis stack: numpy 1.20.0, scipy 1.6.3, scikit-learn 0.24.2, opencv-python 4.5.2.52, pandas, seaborn, matplotlib 3.4.2, networkx 2.5.1, shapely 1.8.4, pygame, lxml, pillow, omegaconf for the configuration system, open3d for the point cloud work, and six for compatibility.

Those pins are old, and they are consistent with the release dates of the project, which is what you would expect from a framework whose last tagged version is from 2022 and whose Docker support landed in 2023.

Editorial conclusion

Adopt OpenCDA if you are prototyping cooperative driving automation and need a full stack in one Python codebase, with a scenario manager and traffic generation included. Do not adopt it for production vehicle code or for quantitative results on arbitrary maps, since the documentation disclaims robustness outside the maps it is tested on. Verify first which simulator versions and maps your study needs, because the supported CARLA version and the custom maps are the two constraints that will shape your schedule.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. ucla-mobility/OpenCDA on GitHub