DOCSEARCHbyAlgolia
Submit Docs

CityFlow Documentation

repository·master·Indexed 21 days ago

https://github.com/cityflow-project/cityflow

A high-performance, microscopic traffic simulator designed for multi-agent reinforcement learning (MARL) in large-scale urban environments. It features a Python interface, multithreading for speed, and tools for road network generation and SUMO roadnet conversion. The documentation covers installation via Docker or source, roadnet and flow file formats, and the use of a web-based frontend tool for visualizing simulation replays.

Tokens
12K
Snippets
35
Records
57
Agent score
76%

What's inside CityFlow

  1. Overview of CityFlow

    master

    CityFlow is a multi-agent reinforcement learning (MARL) environment designed for large-scale city traffic scenarios. It functions as a microscopic traffic simulator, meaning it simulates the individual behavior of every vehicle to provide high-fidelity detail of traffic evolution.

    Key features include:

    • Microscopic Simulation: High-level detail of individual vehicle behaviors.
    • Flexible Definitions: Supports customizable road networks and traffic flow patterns.
    • Python Interface: Provides a user-friendly API specifically designed for reinforcement learning workflows.
    • High Performance: Utilizes optimized data structures, simulation algorithms, and multithreading to enable city-wide traffic simulation at high speeds.

  2. What is CityFlow?

    master

    CityFlow is a multi-agent reinforcement learning (MARL) environment designed for large-scale city traffic scenarios. It functions as a microscopic traffic simulator, meaning it simulates the behavior of individual vehicles to provide high-level detail of traffic evolution.

    Key features include:

    • Microscopic Simulation: Detailed vehicle-level behavior.
    • Flexible Definitions: Supports customizable road networks and traffic flows.
    • Python Interface: Provides a developer-friendly API specifically for reinforcement learning workflows.
    • High Performance: Uses optimized data structures, simulation algorithms, and multithreading to enable city-wide traffic simulation at high speeds.

  3. Define traffic flows using the Flow File Format

    master

    The Flow file defines the traffic flow in CityFlow. Each flow entry specifies vehicle characteristics, the path they follow, and the timing of their appearance in the simulation.

    Each flow consists of the following fields:

    vehicle

    Defines the physical and behavioral parameters of the vehicles in this flow:

    • length: Length of the vehicle.
    • width: Width of the vehicle.
    • maxPosAcc: Maximum acceleration (m/s).
    • maxNegAcc: Maximum deceleration (m/s).
    • usualPosAcc: Usual acceleration (m/s).
    • usualNegAcc: Usual deceleration (m/s).
    • minGap: Minimum acceptable gap with the leading vehicle (meters).
    • maxSpeed: Maximum cruising speed (m/s).
    • headwayTime: Desired headway time (seconds). The gap maintained is calculated as current speed * headwayTime.

    route

    Defines the path vehicles will follow. You specify a source and a destination. You can optionally provide anchor points, and the CityFlow router will automatically connect them using shortest paths.

    interval

    Defines the time interval (in seconds) between consecutive vehicles in the flow. If the interval is too small and the road is blocked, vehicles will be held and released once sufficient space becomes available.

    startTime and endTime

    Defines the time window (in seconds) during which the flow will generate vehicles. The flow generates vehicles between startTime and endTime, inclusive.

  4. Manage Replay Files and Engine Behavior

    master

    Understanding how CityFlow handles replay files is critical for data management:

    • New Engine Initialization: Creating a new Engine object with an existing replayLogFile will clear the old contents of that file first.
    • Resetting the Engine: Calling eng.reset() does not clear the old replay; instead, it appends newly generated replay data to the end of the existing replayLogFile.
    • Runtime Changes: You can change the active replay file during runtime using the set_replay_file method.

  5. Understand the Roadnet File Format

    master

    The roadnet.json file defines the physical structure of the road network as a graph of intersections and roads.

    Core Abstractions

    • Road: A directional connection between two intersections. It contains one or more lanes.
    • Intersection: A node where roads meet. It contains:
      • roadLinks: Connections between specific roads within the intersection (e.g., a left turn or straight movement). These can be controlled by traffic signals.
      • trafficLight: A plan defining lightphases (durations and which roadLinks are active).
      • roadLinks contain laneLinks: Specific paths from an incoming lane to an outgoing lane.
    • roadLink: Defines how a vehicle moves from one road to another within an intersection. It includes a type (e.g., turn_left, turn_right, go_straight) and a list of laneLinks.
    • laneLink: Defines the path between a specific startLaneIndex and endLaneIndex using a series of coordinates (points).

  6. Format Chart Data for Replay Visualization

    master

    The replay player can display metric changes in a chart simultaneously with the simulation. To use this, provide a log file where each row represents a time step and each column represents a specific metric.

    Data Format Requirements:

    • The first line must be the title of the chart.
    • Each subsequent row corresponds to a time step.
    • Each column corresponds to a metric (e.g., vehicle count at a specific intersection).
    • Values in a row must be separated by one or more spaces or tabs.
    • The player connects values in the same column across different rows as points on a line.

    Example Format:

    Metric Title
0.3    0.4    0.1    ...(step 1)
0.5    0.2    0.2    ...(step 2)
    title
0.3            0.4              0.1          ...(step1)
0.5            0.2              0.2          ...(step2)

  7. Generate grid scenarios using tools

    master

    You can generate grid-based roadnet and flow files using the tools/generate_grid_scenario.py script.

    Example: Generate a 2x3 grid with a traffic light plan:

    python generate_grid_scenario.py 2 3 --roadnetFile roadnet.json --flowFile flow.json --dir . --tlPlan
    python generate_grid_scenario.py 2 3 --roadnetFile roadnet.json --flowFile flow.json --dir . --tlPlan

  8. Control the Replay Player

    master

    Once the replay is running, you can control the playback and navigation using the following methods:

    Navigation & View:

    • Mouse: Drag to navigate the map; use the mouse wheel to zoom.
    • Pause/Resume: Click the Pause button in the Control Box or double-click anywhere on the map.
    • Step-by-step: Press [ to take a step backward or ] to take a step forward.
    • Restart: Click the Start button again.

    Playback Speed:

    • Slider: Move the slider in the Control Box.
    • Keyboard: Press 1 to slow down or 2 to speed up.

    Debugging:

    • Enable the debug option to display IDs for vehicles, roads, and intersections when hovering with the mouse.
    • Note: Enabling debug mode will slow down the replay performance.

  10. Generate a grid road network with `generate_grid_scenario.py`

    master

    The generate_grid_scenario.py script is a utility used to create an $N \times M$ grid road network populated with traffic flows. You can specify the dimensions of the grid as positional arguments and use flags to customize lane configurations, vehicle properties, and traffic light plans.

    # Generate a basic 3x4 grid road network
python generate_grid_scenario.py 3 4

# Generate a 3x4 grid with 2 straight lanes and a predefined traffic light plan
python generate_grid_scenario.py 3 4 --numStraightLanes 2 --tlPlan

  12. Use the CityFlow Replay Frontend

    master

    To visualize CityFlow simulations, use the web-based frontend located in the frontend folder.

    Steps to start a replay:

    1. Navigate to the frontend folder and open index.html in a web browser.
    2. Load the roadnet log file. Note: Use the file specified by the roadnetLogFile field in your config (do not use roadnetFile). Wait for the loading message in the info box.
    3. Load the replay file (specified by the replayLogFile field in your config).
    4. (Optional) Load a chart data file to visualize metrics.
    5. Click the Start button.

    To get example replay files: Run the download_replay.py script located in the frontend folder.

    python download_replay.py