OpenCDA: An Open Cooperative Driving Automation Framework Integrated with Co-Simulation

In plain words

Self-driving cars will increasingly talk to each other: they share what they see, announce where they plan to go, and agree on joint moves such as driving in a tight convoy or merging into one. Testing that is hard. Real test tracks are expensive, and the simulators people use either model a single car well or model traffic well, rarely both.

OpenCDA is a toolkit that tries to cover both sides in one place. It runs a car-level simulator and a traffic simulator together, so a test can watch one car's sensors and controls and also the flow of cars around it. On top of that it provides a complete, modular driving software stack, so a researcher can swap in their own piece, such as a planner or a merge rule, and see how the whole system changes.

The paper's worked example is a convoy of cars that drive one behind another at a fixed short time gap, with a new car joining the convoy from a side lane. The authors compare two rules for choosing where the new car joins and report which one keeps the gaps safer and finishes the join faster. Everything is simulation, and the results are the authors' own.

TL;DR

OpenCDA is an open, Python-based framework for testing cooperative driving automation (CDA) algorithms. It couples CARLA (single-vehicle sensing and control) with SUMO (traffic), ships a full-stack CDA software stack and a scenario manager, and includes benchmark scenarios. Its platooning example reports author-reported results from simulation only. Treat it as a test bench, not as a validated algorithm: the GFS merge method is not in the repository, and several parameters in the paper differ from the shipped code.

Problem

Field tests of cooperative driving need several connected, automated vehicles and a large test area, which makes them expensive and sometimes unsafe §I. Simulation is the cheaper route, but the authors state that no open-source or commercial tool at the time combined traffic with the full CDA vehicle software pipeline §I. Platforms they review either stay at traffic level or cover only parts of the car software, such as platoon formation in one simulator §II. The framework assumes the user can run CARLA and SUMO, and it uses a two-lane freeway map for the platooning case §III.A §IV.B.

Method

The paper's contribution is a software framework rather than one new algorithm. It has three components: a co-simulation platform, a full-stack CDA system and a scenario manager §III fig. 1.

Co-simulation §III.A. CARLA renders the scene, simulates vehicle dynamics and provides sensors. SUMO generates background traffic with driver models. When co-simulation is on, SUMO controls the human-driven vehicles and feeds them into the CARLA server, where the connected automated vehicles (CAVs) react to them. The authors advise against full co-simulation for every test, and note that a single-simulator setup is enough for some questions §III.A.

CDA system §III.B. Each CAV runs a layered stack: sensing, perception, planning and actuation. A separate application layer exchanges status and intent over V2X and agrees on joint plans, such as joining a platoon. Each layer has defaults that can be replaced. The authors call this modularity and present the defaults as benchmarks §III.B.

Scenario manager §III.C. A YAML file describes the CARLA settings, the traffic, and each CAV's sensors and target speed. A loader merges it onto a default file. The manager then builds the scene, spawns the vehicles, can fire special events at set times or positions, and runs evaluation at the end §III.C fig. 3.

Class design §III.D fig. 2. A per-vehicle manager bundles perception, localisation, a behaviour agent (which plans), a control manager and a V2X manager. A platoon manager groups the vehicles of one convoy. The behaviour agent builds a local trajectory with a cubic-spline path and a speed profile that follows simple kinematics eq. 1 eq. 2 eq. 3 eq. 4.

# Trajectory sampling from a path and a target speed  [§III.D] [eq. 2-4]
# Input:  path_x, path_y (metres, 0.1 m apart); v_now, v_target (m/s)
# Output: trajectory points, one every dt seconds

def sample_trajectory(path_x, path_y, v_now, v_target, dt):
    # Cap the target speed by path curvature; the paper gives no
    # curvature limit, the code uses 5.0 m/s^2 lateral
    # [code: opencda/core/plan/local_planner_behavior.py#L411-L414]
    v_target = min(v_target, curvature_speed_cap(path_x, path_y))
    # One constant acceleration for the whole horizon, clipped to
    # [-6.5, 3.5] m/s^2; the paper leaves both limits unstated [eq. 2]
    # [code: opencda/core/plan/local_planner_behavior.py#L416-L419]
    accel = clip((v_target - v_now) / dt, -6.5, 3.5)
    travelled = 0.0
    points = []
    for step in range(horizon_steps(dt)):
        # Advance by constant-acceleration kinematics [eq. 3] [eq. 4]
        # [code: opencda/core/plan/local_planner_behavior.py#L421-L424]
        travelled += v_now * dt + 0.5 * accel * dt ** 2
        v_now += accel * dt
        # Take the path point at that arc length  [code: #L427-L434]
        points.append(path_point_at(path_x, path_y, travelled))
    return points

Platoon protocol §IV.A fig. 4. The platoon manager runs a finite state machine. The leader keeps driving at its own speed and listens for join requests. Followers stay in a maintaining mode, in which each one tracks the trajectory of the vehicle in front at a fixed time gap §IV.A. A follower blends the predecessor's position with its own previous position, and speed comes from the displacement over one step eq. 5 eq. 6.

# Car following on the predecessor's trajectory  [§IV.A] [eq. 5-6]
# Input:  pred_pos, pred_len (one coordinate along the path; length in m)
# Output: own (position, speed) for each step

def follow_predecessor(pred_pos, pred_len, ego_pos, gap, dt):
    # Desired gap, expressed in simulation steps  [eq. 5]
    weight = gap / dt
    track = []
    prev_pos = ego_pos
    for step_pos, step_len in zip(pred_pos, pred_len):
        # Predecessor position minus its length, blended with own
        # previous position  [eq. 5]
        pos = (step_pos - step_len + weight * prev_pos) / (1 + weight)
        # Speed from the displacement over one step  [eq. 6]
        speed = abs(pos - prev_pos) / dt
        track.append((pos, speed))
        prev_pos = pos
    return track

Joining §IV.A §IV.B.2. When a single CAV finds a platoon that accepts it, it picks a meeting point. The paper describes this as a decision by the leader, and says that some members may open a gap for the new car. The authors compare two rules for choosing which member the new car joins behind: a heuristic that takes the nearest member by Euclidean distance, and a Genetic Fuzzy System (GFS) that also uses platoon members' speeds and nearby human-driven vehicles §IV.B.2.

Scenarios §IV.B fig. 5 fig. 6 fig. 7. The platooning benchmark uses a customised two-lane freeway with a single-lane on-ramp, about 2800 m of mainline §IV.B. Two scenarios are reported: a five-vehicle convoy whose leader follows a speed profile §IV.B.1, and a merge from an on-ramp with mainline traffic §IV.B.2. Detection uses YOLOv5 and localisation fuses GNSS and IMU data §IV.B.

Metrics §IV.C. Safety is measured by an average time-to-collision over the steps in which the follower is slower than its predecessor eq. 7 and by a hazard count below a 2.5 s threshold §IV.C. Stability uses the time gap to the predecessor and the spread of acceleration §IV.C. Efficiency uses the time to complete the manoeuvre and the spread of acceleration during the join §IV.C.

Key equations, numbered in source order (the paper leaves them unlabelled, so numbers were counted from the LaTeX; see Pitfalls):

y_t = \alpha_0 + \alpha_1 x_t + \alpha_2 x_t^2 + \alpha_3 x_t^3 eq. 1

a_t = \begin{cases} \min\left(\frac{v_{target} - v_t}{\Delta t}, a^1\right), & v_{target} \ge v_t \\ \max\left(\frac{v_{target} - v_t}{\Delta t}, a^2\right), & \text{otherwise} \end{cases} eq. 2

x_t = v_{t-1}\Delta t + \frac{a_{t-1}\Delta t^2}{2} eq. 3

v_t = v_{t-1} + a_{t-1}\Delta t eq. 4

pos_j^t = \frac{pos_{j-1}^t - L_{j-1} + pos_j^{t-\Delta t} \cdot gap/\Delta t}{1 + gap/\Delta t} eq. 5

v_j^t = \frac{\lVert pos_j^t - pos_j^{t-\Delta t} \rVert}{\Delta t} eq. 6

ATTC = \frac{1}{N} \sum_{t=1}^{N} \frac{x_i^t - x_{i-1}^t - l}{v_i^t - v_{i-1}^t} eq. 7

Symbols as defined in the paper: \alpha are polynomial coefficients; a^1, a^2 are comfort acceleration and deceleration; \Delta t is the time step; gap is the desired time gap; L is vehicle length; N counts steps where v_i^t < v_{i-1}^t §III.D §IV.A §IV.C.

Hyperparameters

Values in the paper, and the shipped configuration where it sets one. "Not stated" means the paper gives no value. Code-only rows are marked.

Results

Author-reported, from simulation only. Setup: CARLA with SUMO co-simulation, the freeway map above, one platoon, and a heuristic merge as the baseline for the GFS §IV.B §V. Hardware, CARLA and SUMO versions, and run counts are not stated.

Headline claims, with their sources:

• Single-lane cycle 1: followers hold a mean time gap of 0.602 to 0.603 s around the 0.6 s target, with zero hazard events tab. 1 (a) §V.A.
• Single-lane cycle 2, with a human-driven vehicle in front: the leader follows at about 1.5 s, and followers keep 0.605 to 0.614 s §V.A tab. 1 (b). The human-driven speed profile is from real-world NGSIM-style data fig. 7.
• Merge, heuristic rule: one vehicle's gap drops below 0.2 s during the cut-in, which the authors call potentially dangerous §V.B. The table does not report this minimum gap tab. 1 (c).
• Merge, GFS rule: the new car keeps a gap above 0.6 s during the join and finishes in 9.9 s, against 13.1 s for the heuristic §V.B tab. 1 (d). The table gives 13.5 s for the heuristic (see Pitfalls).

Full author-reported values, copied from the paper's table. Columns are ATTC (s), hazard frequency (hf), average time gap (atg, s), time-gap standard deviation (tg_std, s), acceleration standard deviation for stability and for efficiency (acc_std, m/s^2), and time to complete the manoeuvre (tcm, s). "NA" is the paper's own entry.

Table caption: "The desired platoon time gap is set to 0.6 second" tab. 1.

Paper vs code

Code: official repository at code_commit (https://github.com/ucla-mobility/OpenCDA, linked from the abstract). Its LICENSE file is the Academic Software License, which allows academic and nonprofit research only, with no commercial use LICENSE. Source headers name a different non-commercial license, TDG-Attribution-NonCommercial-NoDistrib platoon_behavior_agent.py. This card describes behaviour in its own pseudocode and cites line numbers only; it quotes no code.

Discrepancies, each with both citations:

• Sampling step in the following law and kinematics. Paper: Δt is the simulation step §III.D eq. 5. Code: the step is trajectory_dt, 0.20 s by default and 0.25 s in the joining configs platoon_behavior_agent.py default.yaml platoon_joining_2lanefree_carla.yaml.
• Length term. Paper subtracts the predecessor's length L_{j-1} eq. 5. Code does not platoon_behavior_agent.py.
• Undocumented speed boost. Code widens the step by 0.0125 per m/s when the leader is more than 3 m/s slower platoon_behavior_agent.py. The paper does not mention it.
• Acceleration law. The code's single clipped expression matches the piecewise form of eq. 2 with a1 = 3.5 and a2 = -6.5 m/s^2 local_planner_behavior.py. It also adds a 5.0 m/s^2 lateral cap, while its comment says 3.6 local_planner_behavior.py.
• Path model. Paper's eq. 1 is a cubic in x. Code uses a 2-D cubic spline through the path local_planner_behavior.py.
• Leader speed profile. Paper: 25 m/s and 30 m/s, held 20 s each §IV.B.1. Code default: 85 and 95 km/h, 10 s holds default.yaml. The stability config sets max_speed to 80 km/h platoon_stability_2lanefree_carla.yaml. The stage logic is in platoon_stability_2lanefree_carla.py.
• Cycle 2 human-driven vehicle. Paper uses a human-driven vehicle with an NGSIM speed profile §IV.B.1 fig. 7. The repository contains no NGSIM profile and no vehicle in the stability scenario; its config has no traffic list platoon_stability_2lanefree_carla.yaml.
• Who chooses the join point. Paper: the leader decides §IV.B.2. Code: the joining vehicle runs the match and picks the nearest member, by distance, as its front vehicle platoon_behavior_agent.py platooning_plugin.py.
• GFS not in the repository. Paper compares against a Genetic Fuzzy System §IV.B.2. A search of the whole repository at this commit finds no fuzzy logic code, so the GFS result cannot be reproduced from it.
• Safety metrics. ATTC eq. 7, hazard frequency and time to complete the manoeuvre are not computed anywhere in the repository (searched by name). The code's per-step time to collision is distance divided by the speed difference, floored at 1 m/s, and it only sets the target speed behavior_agent.py. Its threshold is safety_time, 4 s default.yaml. No 2.5 s hazard threshold appears in the code; the 2.5 values in the configs are camera positions.
• Time-gap definition. Code uses the centre-to-centre distance over the ego speed platoon_behavior_agent.py platoon_behavior_agent.py. The paper does not define the gap.
• Acceleration in metrics. Code computes acceleration as the speed change divided by a hard-coded 0.05 s planer_debug_helper.py.

Pitfalls

• Equation numbering. The paper's equations have no labels. Numbers here were counted from the LaTeX source in order: 1 to 4 in the planner, 5 and 6 in the platooning section, and 7 in the metrics. Check them against the PDF before citing a number in another page.
• Equation 1 is inconsistent. Its text lists α0 to α2 as "the coefficients of cubic polynomial", but the equation has a term in α3 x^3 §III.D eq. 1.
• Acceleration index mismatch. eq. 2 defines a_t, but eq. 3 and eq. 4 use a_{t-1}. The code uses one constant acceleration over the whole horizon local_planner_behavior.py, which avoids the question but is not stated in the paper.
• Step size changes the gain. The following weight is gap/Δt eq. 5. With a 0.6 s gap, it is 12 at the 0.05 s simulation step but 3 at the 0.20 s code step. A port that uses the paper's Δt on the code's trajectory will behave differently.
• Possible step-count rounding. The horizon count is 2.0 // dt local_planner_behavior.py. Float floor division can return one less than expected for some step sizes, such as 0.2. I did not run this check here; test it before relying on the count.
• Stale comment in the planner. The planner's comment says the trajectory is sampled every 0.1 s, but the step is trajectory_dt local_planner_behavior.py.
• Speed units. Many config values and methods are in km/h, including max_speed, warm_up_speed and tailgate_speed, while the paper's equations use m/s. Convert before comparing.
• Freeway profile and speed cap. The paper's 30 m/s target is 108 km/h, above the 80 km/h max_speed in the stability config. How the cap interacts with the leader's commanded speed is not verified here.
• Figure and table references. The paper cites the GFS result as table subpart "(e)", but the table has four subparts, so GFS is (d) in source order. The text gives 13.1 s for the heuristic merge, while the table gives 13.5 s. The real-trajectory test is cited as fig. 4 (b), but fig. 4 is the protocol flow chart with no subparts; the human-driven speed profile is fig. 7. Figure numbers above follow source order: 1 overview, 2 class diagram, 3 flow, 4 protocol, 5 co-simulation snippet, 6 two scenarios, 7 human-driven speed, 8 profiles.
• Merge claims are not in the table. The "below 0.2 s" minimum gap is stated only in the text §V.B. Ask for the raw logs before using it.
• Metric filters. Both debug helpers drop the first 100 steps planer_debug_helper.py platoon_debug_helper.py. The paper does not say so.
• Unstated versions. CARLA and SUMO versions, hardware and run counts are not stated. The repository ships requirements.txt and environment.yml, which were not checked here.
• Single map, single platoon. The scenario script allows only one platoon platoon_stability_2lanefree_carla.py. The results cover one freeway layout and one platoon size.
• Licence limits reuse. The code is academic and non-commercial only. Do not copy code into a commercial product on the strength of this card.

Lineage

• Builds on: CARLA and SUMO, used as simulators §III.A. Neither has a card on this wiki.
• Compared against: a nearest-member join heuristic and a Genetic Fuzzy System for choosing the join point §IV.B.2. The GFS method cites Anoop et al. (2021) §IV.B.2; no card exists for it.
• Related concept: collaborative-perception. The framework lists cooperative perception as a supported application §I §III.B, but this paper does not evaluate it.
• Superseded by: not stated.