### Python Example: Saving and Loading CityFlow Simulation State

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/start.rst

This code snippet demonstrates the process of saving the current simulation state to an `Archive` object, optionally dumping it to a JSON file, and then loading the simulation state back either from the `Archive` object directly or from the saved file.

```python
archive = eng.snapshot() # create an archive object
archive.dump("save.json") # if you want to save the snapshot to a file

# do something

eng.load(archive)
# load 'archive' and the simulation will start from the status when 'archive'is created

# or if you want to load from 'save.json'
eng.load_from_file("save.json")
```

--------------------------------

### Example CityFlow Configuration File

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/start.rst

A sample JSON configuration file used to define various simulation parameters for CityFlow. This includes simulation interval, random seed, root directory, paths to roadnet and flow files, traffic light control settings, and options for saving replay logs.

```json
{
    "interval": 1.0,
    "seed": 0,
    "dir": "data/",
    "roadnetFile": "roadnet/testcase_roadnet_3x3.json",
    "flowFile": "flow/testcase_flow_3x3.json",
    "rlTrafficLight": false,
    "saveReplay": true,
    "roadnetLogFile": "frontend/web/testcase_roadnet_3x3.json",
    "replayLogFile": "frontend/web/testcase_replay_3x3.txt"
}
```

--------------------------------

### Install CityFlow from Source via Pip

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/install.rst

Installs the CityFlow library from the current directory using pip. This command is typically executed from the project's root directory after cloning the source code, setting up the local installation.

```shell
pip install .
```

--------------------------------

### Generate Grid Roadnet and Flow Files

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/start.rst

Demonstrates how to use the `generate_grid_scenario.py` script to create a grid-based road network and corresponding traffic flow files. This example generates a 2x3 grid, saving the roadnet to `roadnet.json` and flow to `flow.json` in the current directory, and includes a traffic light plan.

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

--------------------------------

### Run CityFlow Docker Container

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/install.rst

Starts an interactive container from the CityFlow Docker image. This command launches an environment where CityFlow is ready to use, along with Miniconda and Python 3.6.

```shell
docker run -it cityflowproject/cityflow:latest
```

--------------------------------

### Download CityFlow Example Replay Files

Source: https://github.com/cityflow-project/cityflow/blob/master/frontend/README.md

Execute this command in your terminal to download pre-configured example replay files. These files are essential for populating the CityFlow Frontend Tool with data for visualization and analysis. Ensure Python is installed and accessible in your system's PATH.

```shell
python download_replay.py
```

--------------------------------

### Verify CityFlow Installation in Python

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/install.rst

Demonstrates how to import the CityFlow library and initialize its 'Engine' object in Python. This snippet serves as a basic test to confirm that CityFlow has been successfully installed and is accessible in the Python environment, whether via Docker or source build.

```python
import cityflow
eng = cityflow.Engine
```

--------------------------------

### Install C++ Build Dependencies for Source Compilation

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/install.rst

Installs essential build tools and CMake on Ubuntu systems. These packages are prerequisites for compiling and building CityFlow from its source code.

```shell
sudo apt update && sudo apt install -y build-essential cmake
```

--------------------------------

### Clone CityFlow Source Code Repository

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/install.rst

Clones the CityFlow project's source code from its official GitHub repository to the local machine. This step is necessary before attempting to build CityFlow from source.

```shell
git clone https://github.com/cityflow-project/CityFlow.git
```

--------------------------------

### Create CityFlow Simulation Engine

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/start.rst

Initializes the CityFlow simulation engine. It requires a `config_path` pointing to the simulation configuration file and an optional `thread_num` to specify the number of threads for parallel processing. The engine object (`eng`) is then used to control the simulation.

```python
import cityflow
eng = cityflow.Engine(config_path, thread_num=1)
```

--------------------------------

### CityFlow API: Control Replay Saving

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/start.rst

Enables or disables the saving of simulation replays. Set `open` to `True` to start saving replays, and `False` to stop. This API functions only if `saveReplay` is configured as `true` in the simulation's JSON configuration file.

```APIDOC
set_save_replay(open)
  open: A boolean value; True to enable replay saving, False to disable it.
```

--------------------------------

### Pull CityFlow Docker Image

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/install.rst

Downloads the latest CityFlow Docker image from the official repository, providing a pre-configured environment for easy deployment and usage.

```shell
docker pull cityflowproject/cityflow:latest
```

--------------------------------

### CityFlow API: Load Simulation State from Archive

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/start.rst

Restores the simulation state from a previously created `Archive` object. This allows the simulation to resume from a specific point in time or a saved state.

```APIDOC
load(archive)
  archive: An 'Archive' object from which to load the simulation state.
```

--------------------------------

### CityFlow API: Load Simulation State from File

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/start.rst

Restores the simulation state by loading a snapshot file that was previously created using the `dump` method of an `Archive` object. This provides a way to persist and reload simulation states from disk.

```APIDOC
load_from_file(path)
  path: The file path to the snapshot file (e.g., a JSON file) to be loaded.
```

--------------------------------

### Advance CityFlow Simulation by One Step

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/start.rst

Executes a single simulation step in the CityFlow engine. This function advances the simulation time by the configured interval, updating vehicle positions and traffic light states.

```python
eng.next_step()
```

--------------------------------

### CityFlow API: Take Simulation Snapshot

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/start.rst

Captures the current state of the simulation. This method generates an `Archive` object, which encapsulates the complete simulation state and can be used for later restoration or saved to a file using its `dump` method.

```APIDOC
snapshot()
  Returns: An 'Archive' object containing the current simulation state.
```

--------------------------------

### CityFlow Control API Reference

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/start.rst

Documentation for CityFlow's control methods, specifically focusing on traffic light management. This API allows external control over traffic light phases within the simulation, enabling dynamic adjustments to traffic flow.

```APIDOC
set_tl_phase(intersection_id, phase_id):
```

--------------------------------

### Convert SUMO Roadnet to CityFlow Format using Python

Source: https://github.com/cityflow-project/cityflow/blob/master/tools/converter/readme.md

This command-line example demonstrates how to use the `converter.py` script to convert a SUMO roadnet file (e.g., `atlanta_sumo.net.xml`) into a CityFlow compatible JSON format (e.g., `atlanta_cityflow.json`). This process requires the 'sumo' library to be installed with the 'SUMO_HOME' environment variable properly set, and the 'sympy' library installed via pip.

```python
python converter.py --sumonet atlanta_sumo.net.xml --cityflownet atlanta_cityflow.json
```

--------------------------------

### CityFlow Data Access API Reference

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/start.rst

Comprehensive documentation for CityFlow's data access methods, allowing users to retrieve various simulation statistics and detailed vehicle information. This includes functions for querying vehicle counts, lane-specific data, individual vehicle properties, and simulation time.

```APIDOC
get_vehicle_count():
  - Get number of total running vehicles.
  - Return an int

get_vehicles(include_waiting=False):
  - Get all vehicle ids
  - Include vehicles in lane's waiting buffer if include_waiting=True
  - Return an list of vehicle ids

get_lane_vehicle_count():
  - Get number of running vehicles on each lane.
  - Return a dict with lane id as key and corresponding number as value.

get_lane_waiting_vehicle_count():
  - Get number of waiting vehicles on each lane. Currently, vehicles with speed less than 0.1m/s is considered as waiting.
  - Return a dict with lane id as key and corresponding number as value.

get_lane_vehicles():
  - Get vehicle ids on each lane.
  - Return a dict with lane id as key and list of vehicle id as value.

get_vehicle_info(vehicle_id):
  - Return a dict which contains information of the given vehicle.
  - The items include:
    + running: whether the vehicle is running.
    + If the vehicle is running:
      * speed: The speed of the vehicle.
      * distance: The distance the vehicle has travelled on the current lane or lanelink.
      * drivable: The id of the current drivable(lane or lanelink)
      * road: The id of the current road if the vehicle is running on a lane.
      * intersection: The next intersection if the vehicle is running on a lane.
      * route: A string contains ids of following roads in the vehicle's route which are separated by ' '.
  - Note that all items are stored as str.

get_vehicle_speed():
  - Get speed of each vehicle
  - Return a dict with vehicle id as key and corresponding speed as value.

get_vehicle_distance():
  - Get distance travelled on current lane of each vehicle.
  - Return a dict with vehicle id as key and corresponding distance as value.

get_leader(vehicle_id):
  - Return the id of the vehicle in front of vehicle_id.
  - Return an empty string "" when vehicle_id does not have a leader

get_current_time():
  - Get simulation time (in seconds)
  - Return a double

get_average_travel_time():
  - Get average travel time (in seconds)
  - Return a double
```

--------------------------------

### CityFlow API: Set Random Seed

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/start.rst

Sets the seed for the simulation's internal random number generator. This is useful for ensuring reproducibility of simulation runs.

```APIDOC
set_random_seed(seed)
  seed: The integer value to be used as the seed for the random generator.
```

--------------------------------

### CityFlow API: Set Replay Output File

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/start.rst

Configures the file path where newly generated replays will be saved. The `replay_file` path should be relative to the `dir` specified in the simulation's configuration file. This API is only effective when `saveReplay` is set to `true` in the config JSON.

```APIDOC
set_replay_file(replay_file)
  replay_file: The path (relative to the config's 'dir') where replay logs will be written.
```

--------------------------------

### CMake: Build Multiple C++ Executables from Source Files

Source: https://github.com/cityflow-project/cityflow/blob/master/tools/debug/CMakeLists.txt

This CMake script iterates through a predefined list of C++ source files. For each source file, it extracts the name, removes the '.cpp' extension to use as the executable name, adds an executable target, sets its C++ visibility properties to 'hidden', and links it privately against a specified project library. This automates the process of creating multiple executables from individual source files.

```CMake
set(SOURCE_FILES simple_run.cpp)

foreach(SRC_PATH ${SOURCE_FILES})
    get_filename_component(SRC_NAME ${SRC_PATH} NAME)
    string(REPLACE ".cpp" "" EXE_NAME ${SRC_NAME})
    add_executable(${EXE_NAME} ${SRC_PATH})
    set_target_properties(${EXE_NAME} PROPERTIES CXX_VISIBILITY_PRESET "hidden")
    target_link_libraries(${EXE_NAME} PRIVATE ${PROJECT_LIB_NAME})
endforeach()
```

--------------------------------

### Convert SUMO Roadnet to CityFlow Format

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/roadnet.rst

This command-line example demonstrates how to use the `converter.py` script to transform a SUMO road network file (`.net.xml`) into the CityFlow `roadnet.json` format. It specifies the input SUMO file and the desired output CityFlow JSON file.

```Shell
python converter.py --sumonet atlanta_sumo.net.xml --cityflownet atlanta_cityflow.json
```

--------------------------------

### CityFlow API: Reset Simulation

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/start.rst

Resets the entire simulation, clearing all vehicles and setting the simulation time back to zero. Optionally, the random seed can also be reset if specified. This operation appends new replays to the `replayLogFile` rather than clearing old ones.

```APIDOC
reset(seed=False)
  seed: (Optional) A boolean flag. If set to True, the random seed will also be reset (defaults to False).
```

--------------------------------

### CityFlow API: Set Traffic Light Phase

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/start.rst

Sets the phase of a specified traffic light. This method only works when `rlTrafficLight` is set to `true`. Both `intersection_id` and `phase_id` must be pre-defined in the `roadnetFile`.

```APIDOC
set_traffic_light_phase(intersection_id, phase_id)
  intersection_id: The ID of the traffic light intersection, as defined in 'roadnetFile'.
  phase_id: The index of the phase within the 'lightphases' array, defined in 'roadnetFile'.
```

--------------------------------

### CityFlow API: Set Vehicle Speed

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/start.rst

Sets the target speed for a specific vehicle. Note that the actual speed of the vehicle might differ from the requested speed due to the simulation's fundamental rules for collision avoidance.

```APIDOC
set_vehicle_speed(vehicle_id, speed)
  vehicle_id: The ID of the vehicle whose speed is to be set.
  speed: The target speed value for the vehicle.
```

--------------------------------

### CityFlow API: Set Vehicle Route

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/start.rst

Allows for dynamically changing the route of a vehicle while it is traveling. The `route` parameter should be a list of road IDs, excluding the vehicle's current road. The method returns a boolean indicating if the new route is valid and connectable.

```APIDOC
set_vehicle_route(vehicle_id, route)
  vehicle_id: The ID of the vehicle whose route is to be changed.
  route: A list of road IDs that define the new route (does not include the current road).
  Returns: True if the route is available and can be connected, False otherwise.
```

--------------------------------

### Configure CityFlow Project and Compiler Flags (CMake)

Source: https://github.com/cityflow-project/cityflow/blob/master/CMakeLists.txt

This snippet initializes the CMake project for CityFlow, sets the C++ standard to C++11, and defines various compiler flags for both release and debug builds. It also ensures position-independent code generation and includes the 'milo' directory for headers, establishing the foundational build environment.

```CMake
cmake_minimum_required(VERSION 3.0)
project(cityflow)

set(CMAKE_CXX_STANDARD "11" CACHE STRING "")
set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -DRAPIDJSON_HAS_STDSTRING=1")
set(CMAKE_CXX_FLAGS_RELEASE "-O2")
set(CMAKE_CXX_FLAGS_DEBUG "-g")
set(CMAKE_POSITION_INDEPENDENT_CODE ON)

if(POLICY CMP0063)
  cmake_policy(SET CMP0063 NEW)
endif()

if(NOT CMAKE_BUILD_TYPE)
    set(CMAKE_BUILD_TYPE Release)
endif(NOT CMAKE_BUILD_TYPE)

include_directories(extern/milo)
```

--------------------------------

### Configure Python Bindings and Link Libraries (CMake)

Source: https://github.com/cityflow-project/cityflow/blob/master/CMakeLists.txt

This final snippet uses pybind11 to create Python bindings for the CityFlow project, generating a module named after the project. It links the generated module with the project's core library and conditionally defines a 'VERSION' preprocessor macro if a version is specified, facilitating seamless Python integration and version tracking.

```CMake
pybind11_add_module(${PROJECT_NAME} MODULE src/cityflow.cpp)
target_link_libraries(${PROJECT_NAME} PRIVATE ${PROJECT_LIB_NAME})
if(VERSION)
    target_compile_definitions(${PROJECT_NAME} PRIVATE -DVERSION=${VERSION})
endif()
```

--------------------------------

### Integrate External Libraries and Source Directory (CMake)

Source: https://github.com/cityflow-project/cityflow/blob/master/CMakeLists.txt

This snippet integrates the pybind11 and RapidJSON libraries into the CityFlow build by adding their respective subdirectories and include paths. It also adds the main 'src' directory, which contains the core project source code, for compilation, ensuring all necessary components are part of the build.

```CMake
add_subdirectory(extern/pybind11)
include_directories(extern/rapidjson/include)

add_subdirectory(src)
```

--------------------------------

### Generate Grid Road Network with Specific Lane Count and Traffic Light Plan

Source: https://github.com/cityflow-project/cityflow/blob/master/tools/generator/readme.md

This command extends the basic grid generation by allowing specification of the number of straight lanes and enabling a predefined working traffic light plan. The `--numStraightLanes` argument sets the number of straight lanes, and `--tlPlan` activates the traffic light configuration.

```python
python generate_grid_scenario.py 3 4 --numStraightLanes 2 --tlPlan
```

--------------------------------

### API Documentation for Grid Scenario Generator Arguments

Source: https://github.com/cityflow-project/cityflow/blob/master/tools/generator/readme.md

This section details the various command-line arguments available for customizing the grid road network and traffic flow generation. It includes parameters for road dimensions, lane configurations, vehicle characteristics, and output file paths, along with their default values and types.

```APIDOC
Arguments for generate_grid_scenario.py:
  --rowDistance:
    Type: int
    Default: 300
    Description: Distance between consecutive intersections of each row (East-West Roads)
  --columnDistance:
    Type: int
    Default: 300
    Description: Distance between consecutive intersections of each column (South-North Roads)
  --intersectionWidth:
    Type: int
    Default: 30
    Description: Width of intersections
  --numLeftLanes:
    Type: int
    Default: 1
    Description: Number of left-turn lanes
  --numStraightLanes:
    Type: int
    Default: 1
    Description: Number of straight lanes
  --numRightLanes:
    Type: int
    Default: 1
    Description: Number of right-turn lanes
  --laneMaxSpeed:
    Type: int
    Default: 16.67
    Description: Maximum speed for lanes (meters/second)
  --vehLen:
    Type: float
    Default: 5.0
    Description: Vehicle length (meters)
  --vehWidth:
    Type: float
    Default: 2.0
    Description: Vehicle width (meters)
  --vehMaxPosAcc:
    Type: float
    Default: 2.0
    Description: Maximum positive acceleration for vehicles
  --vehMaxNegAcc:
    Type: float
    Default: 4.5
    Description: Maximum negative acceleration for vehicles
  --vehUsualPosAcc:
    Type: float
    Default: 2.0
    Description: Usual positive acceleration for vehicles
  --vehUsualNegAcc:
    Type: float
    Default: 4.5
    Description: Usual negative acceleration for vehicles
  --vehMinGap:
    Type: float
    Default: 2.5
    Description: Minimum gap between vehicles
  --vehMaxSpeed:
    Type: float
    Default: 16.67
    Description: Maximum speed for vehicles
  --vehHeadwayTime:
    Type: float
    Default: 1.5
    Description: Headway time for vehicles
  --dir:
    Type: str
    Default: "./"
    Description: Output directory for generated files
  --roadnetFile:
    Type: str
    Description: Path to the generated road network file
  --turn:
    Type: flag
    Description: If specified, generate turning flows instead of straight flows
  --tlPlan:
    Type: flag
    Description: If specified, generate working predefined traffic signal plan instead of plans with default orders
  --interval:
    Type: float
    Default: 2.0
    Description: Time (seconds) between each vehicle for each flow
  --flowFile:
    Type: str
    Description: Path to the generated flow file
```

--------------------------------

### Enable Unit Testing with GTest (CMake)

Source: https://github.com/cityflow-project/cityflow/blob/master/CMakeLists.txt

This CMake snippet configures the project to use Google Test (GTest) for unit testing. It finds the GTest package and, if found, enables testing and adds the 'tests' subdirectory to the build process, allowing test cases to be compiled and run as part of the project.

```CMake
# Tests
find_package(GTest)
if(GTEST_FOUND)
    enable_testing()
    add_subdirectory(tests)
endif()
```

--------------------------------

### CityFlow Project Library CMake Configuration

Source: https://github.com/cityflow-project/cityflow/blob/master/src/CMakeLists.txt

This CMake snippet defines the header and source files for the CityFlow project, creates a static library named after the project, sets target properties for symbol visibility, and links against the required Threads library. It also ensures that the current directory is included for public headers.

```CMake
set(PROJECT_HEADER_FILES
    utility/config.h
    utility/utility.h
    utility/barrier.h
    utility/optionparser.h
    engine/archive.h
    engine/engine.h
    flow/flow.h
    flow/route.h
    roadnet/roadnet.h
    roadnet/trafficlight.h
    vehicle/router.h
    vehicle/vehicle.h
    vehicle/lanechange.h
)

set(PROJECT_SOURCE_FILES
    utility/utility.cpp
    utility/barrier.cpp
    engine/archive.cpp
    engine/engine.cpp
    flow/flow.cpp
    roadnet/roadnet.cpp
    roadnet/trafficlight.cpp
    vehicle/router.cpp
    vehicle/vehicle.cpp
    vehicle/lanechange.cpp)

set(PROJECT_LIB_NAME ${PROJECT_NAME}_lib CACHE INTERNAL "")

find_package(Threads REQUIRED)

add_library(${PROJECT_LIB_NAME} ${PROJECT_HEADER_FILES} ${PROJECT_SOURCE_FILES})
set_target_properties(${PROJECT_LIB_NAME} PROPERTIES CXX_VISIBILITY_PRESET "hidden")
target_link_libraries(${PROJECT_LIB_NAME} PRIVATE Threads::Threads)
target_include_directories(${PROJECT_LIB_NAME} PUBLIC ${CMAKE_CURRENT_LIST_DIR})
```

--------------------------------

### CityFlow Replay Chart Data Log Format

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/replay.rst

This snippet illustrates the required structure for log files used to display metrics in the replay chart. The first line serves as the chart's title. Subsequent lines represent different time steps, with each column corresponding to a specific metric. Numerical values within a row must be separated by one or more spaces or tabs.

```Text
title
0.3            0.4              0.1          ...(step1)
0.5            0.2              0.2          ...(step2)
...(metric1)   ...(metric2)     ...(metric3)
```

--------------------------------

### Configure C++ Unit Tests with Address Sanitizer in CMake

Source: https://github.com/cityflow-project/cityflow/blob/master/tests/CMakeLists.txt

This CMake script finds C++ test source files, defines compilation and linking flags for address sanitization, includes Google Test directories, and then iterates through each source file to create an executable, set its properties (flags, linked libraries), and register it as a CTest test. It ensures that tests are built with specific sanitization flags and linked against the project's main library and Google Test.

```CMake
file(GLOB TEST_SRCS cpp/*.cpp)
set(FLAGS "-fsanitize=address -fno-omit-frame-pointer")
include_directories(${GTEST_INCLUDE_DIRS})
foreach(SRC_PATH ${TEST_SRCS})
    get_filename_component(SRC_NAME ${SRC_PATH} NAME)
    string(REPLACE ".cpp" "" EXE_NAME ${SRC_NAME})
    add_executable(${EXE_NAME} ${SRC_PATH})
    set_target_properties(${EXE_NAME} PROPERTIES APPEND_STRING PROPERTY LINK_FLAGS "${FLAGS}")
    set_target_properties(${EXE_NAME} PROPERTIES APPEND_STRING PROPERTY COMPILE_FLAGS "${FLAGS}")
    target_link_libraries(${EXE_NAME} PUBLIC ${PROJECT_LIB_NAME} ${GTEST_BOTH_LIBRARIES})
    add_test(NAME ${EXE_NAME}
            WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}
            COMMAND ${EXE_NAME})
endforeach()
```

--------------------------------

### Manage Git Submodules for CityFlow Dependencies (CMake)

Source: https://github.com/cityflow-project/cityflow/blob/master/CMakeLists.txt

This section defines required submodules (pybind11, rapidjson) and includes logic to check for their existence. If a submodule is missing, it attempts to update them using Git, providing robust dependency management for external components. It includes error handling for failed submodule updates, ensuring all necessary dependencies are present before compilation.

```CMake
set(REQUIRED_SUBMODULES
    "extern/pybind11/CMakeLists.txt"
    "extern/rapidjson/include"
)

foreach(REQUIRED_SUBMODULE ${REQUIRED_SUBMODULES})
    if(NOT EXISTS "${PROJECT_SOURCE_DIR}/${REQUIRED_SUBMODULE}")
        # update submodule 
        # https://cliutils.gitlab.io/modern-cmake/chapters/projects/submodule.html
        find_package(Git QUIET)
        if(GIT_FOUND AND EXISTS "${PROJECT_SOURCE_DIR}/.git")
        # Update submodules as needed
            option(GIT_SUBMODULE "Check submodules during build" ON)
            if(GIT_SUBMODULE)
                message(STATUS "Submodule update, this may take some time...")
                execute_process(COMMAND ${GIT_EXECUTABLE} submodule update --init --recursive
                                WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
                                RESULT_VARIABLE GIT_SUBMOD_RESULT)
                if(NOT GIT_SUBMOD_RESULT EQUAL "0")
                    message(FATAL_ERROR "git submodule update --init failed with ${GIT_SUBMOD_RESULT}, please checkout submodules")
                endif()
            endif()
        endif()
        break()
    else()
        message(STATUS "Found Submodule: ${REQUIRED_SUBMODULE}")
    endif()
endforeach()

foreach(REQUIRED_SUBMODULE ${REQUIRED_SUBMODULES})
    if(NOT EXISTS "${PROJECT_SOURCE_DIR}/${REQUIRED_SUBMODULE}")
        message(FATAL_ERROR "The submodule ${REQUIRED_SUBMODULE} was not downloaded! GIT_SUBMODULE was turned off or failed. Please update submodules and try again.")
    endif()
endforeach()
```

--------------------------------

### Generate Basic Grid Road Network with Python

Source: https://github.com/cityflow-project/cityflow/blob/master/tools/generator/readme.md

This command demonstrates how to generate a simple NxM grid road network using the `generate_grid_scenario.py` script. It takes two integer arguments for the number of rows and columns, respectively, to define the grid dimensions.

```python
python generate_grid_scenario.py 3 4
```

--------------------------------

### CityFlow Flow File Format Specification

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/flow.rst

Defines the complete structure and required fields for a CityFlow Flow file, including vehicle characteristics, route specifications, and timing parameters for vehicle generation. This format dictates how traffic flows are simulated within the CityFlow environment.

```APIDOC
Flow File Format:
  vehicle:
    description: Defines the parameters of a vehicle.
    properties:
      length: float (length of the vehicle)
      width: float (width of the vehicle)
      maxPosAcc: float (maximum acceleration in m/s)
      maxNegAcc: float (maximum deceleration in m/s)
      usualPosAcc: float (usual acceleration in m/s)
      usualNegAcc: float (usual deceleration in m/s)
      minGap: float (minimum acceptable gap with leading vehicle in meter)
      maxSpeed: float (maximum cruising speed in m/s)
      headwayTime: float (desired headway time in seconds with leading vehicle, keeps 'current speed * headwayTime' gap)
  route:
    description: Defines the route that all vehicles of this flow will follow.
    details: Specify source, destination, and optionally anchor points; router connects with shortest paths automatically.
  interval: float (defines the interval of consecutive vehicles in seconds)
    note: If the interval is too small, vehicles may be held due to blockage until space is available.
  startTime: int (Flow will generate vehicles from this time in seconds)
  endTime: int (Flow will generate vehicles up to and including this time in seconds)
```

--------------------------------

### CityFlow Roadnet JSON File Format Specification

Source: https://github.com/cityflow-project/cityflow/blob/master/docs/source/roadnet.rst

This JSON snippet illustrates the complete structure and required fields for the CityFlow `roadnet.json` file. It defines the schema for intersections, roads, roadlinks, lanelinks, and traffic light configurations, including properties like IDs, coordinates, widths, and connections.

```JavaScript
{
    "intersections": [
      {
        // id of the intersection
        "id": "intersection_1_0",
        // coordinate of center of intersection
        "point": {
          "x": 0,
          "y": 0
        },
        // width of the intersection
        "width": 10,
        // roads connected to the intersection
        "roads": [
          "road_1",
          "road_2"
        ],
        // roadLinks of the intersection
        "roadLinks": [
          {
            // 'turn_left', 'turn_right', 'go_straight'
            "type": "go_straight",
            // id of starting road
            "startRoad": "road_1",
            // id of ending road
            "endRoad": "road_2",
            // lanelinks of roadlink
            "laneLinks": [
              {
                // from startRoad's startLaneIndex lane to endRoad's endLaneIndex lane
                "startLaneIndex": 0,
                "endLaneIndex": 1,
                // points along the laneLink which describe the shape of laneLink
                "points": [
                  {
                    "x": -10,
                    "y": 2
                  },
                  {
                    "x": 10,
                    "y": -2
                  }
                ]
              }
            ]
          }
        ],
        // traffic light plan of the intersection
        "trafficLight": {
          "lightphases": [
            {
              // default duration of the phase
              "time": 30,
              // available roadLinks of current phase, index is the no. of roadlinks defined above.
              "availableRoadLinks": [
                0,
                2
              ]
            }
          ]
        },
        // true if it's a peripheral intersection (if it only connects to one road)
        "virtual": false
      }
    ],
    "roads": [
      {
        // id of road
        "id": "road_1",
        // id of start intersection
        "startIntersection": "intersection_1",
        // id of end intersection
        "endIntersection": "intersection_2",
        // points along the road which describe the shape of the road
        "points": [
          {
            "x": -200,
            "y": 0
          },
          {
            "x": 0,
            "y": 0
          }
        ],
        // property of each lane
        "lanes": [
          {
            "width": 4,
            "maxSpeed": 16.67
          }
        ]
      }
    ]
  }
```

--------------------------------

### Conditionally Add Debug Tools (CMake)

Source: https://github.com/cityflow-project/cityflow/blob/master/CMakeLists.txt

This snippet conditionally includes a 'tools/debug' subdirectory into the build. This inclusion only occurs if the CMake build type is explicitly set to 'Debug', ensuring that debug-specific utilities or configurations are only compiled and linked when needed for development and debugging purposes.

```CMake
if (${CMAKE_BUILD_TYPE} STREQUAL Debug)
    add_subdirectory(tools/debug)
endif()
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.