Autopysta

Autopysta is a Python library for simulating 2D traffic flow on highways. It is written in C++ for high performance and wrapped using SWIG for Python compatibility. The library allows users to create realistic highway traffic scenarios with customizable vehicle behaviors, lane-changing logic, and road configurations.

Table of Contents

• Autopysta
  • Table of Contents
  • Platform Support
  • Key Features
  • Installing Autopysta from PyPI
  • Compiling Autopysta from Source
    • Prerequisites
    • Steps to Compile Autopysta
  • Running an Example
    • Example: Running the Different Vehicle Creators Example
  • Quick Start Example: Using Autopysta to Simulate Different Vehicle Creators
  • Explanation of the Simulation Example
  • Additional Features
  • Documentation

Platform Support

Autopysta supports Windows, Linux, and macOS. However, the specific Python versions supported on each platform are still under testing and validation. Currently:

• Windows: Tentatively supports Python 3.8, pending further compatibility testing.
• Linux and macOS: Compatible with Python 3.8 and later, though compatibility with other versions is being evaluated.

Key Features

1. Flexible Vehicle Behavior
   Autopysta provides a variety of vehicle models that dictate acceleration, deceleration, and lane-changing dynamics. Examples include:

   • Intelligent Driver Model (IDM)
   • Gipps Model
   • Newell Random Acceleration Model

2. Vehicle Creation Options
   Users can choose different vehicle creation strategies for each lane, defining how vehicles are added to the simulation.

3. Customizable Highway Geometry
   Configure highways with parameters such as road length, number of lanes, and merge/diverge points for ramps.

Installing Autopysta from PyPI

If you don’t want to compile from source, you can install Autopysta directly from PyPI (precompiled binaries are available for supported platforms):

pip install autopysta

This will install the latest version of Autopysta and its dependencies, allowing you to skip the manual build process.

Compiling Autopysta from Source

To compile Autopysta from source, you will need to build the C++ components, generate the Python wrappers, and copy the necessary binaries to the appropriate directories.

Prerequisites

Before building from source, ensure you have the following installed:

• Python (version 3.8 on Windows, 3.8 or higher on Linux/macOS)
• CMake (for building the C++ components)
• setuptools and wheel (pip install setuptools wheel)
• SWIG (for generating Python wrappers)

Steps to Compile Autopysta

1. Clone the Repository
   Run the following commands to clone the repository and navigate to its directory:

   git clone https://bitbucket.org/rdelpiano/autopysta.git
   cd autopysta
   

2. Build the Extension
   Use the following command to build the C++ extension:

   python setup.py build_ext
   

   This will:

   1. Use CMake to compile the C++ code.
   2. Generate the autopysta.py wrapper and the platform-specific _autopysta.* shared library.
   3. Copy the generated binaries to:
      1. The root autopysta directory.
      2. The examples/autopysta directory.

3. Verify the Build
   After building, check the autopysta directory (both in the tests/ and inside examples/) for:

   1. autopysta.py: Python wrapper.
   2. _autopysta.*: Shared library file specific to your platform (e.g., _autopysta.so on Linux/macOS or _autopysta.pyd on Windows).

Running an Example

Once the build is complete, you can run any example provided in the examples directory.

Example: Running the Different Vehicle Creators Example

Navigate to the examples/ directory:

cd examples

Run the different_creators.py (or any other example script):

python different_creators.py

This script simulates traffic with different vehicle creation strategies, as shown in the "Quick Start Example" below.

Quick Start Example: Using Autopysta to Simulate Different Vehicle Creators

Autopysta offers various ways to populate lanes with vehicles, each governed by different driving models and behaviors. Here’s an example of setting up a simulation with different vehicle creators to model distinct traffic conditions.

# ------------------------------------------------------------------------------
# Case Study: Using Different Vehicle Creators
#
# This example demonstrates the use of different vehicle creators to populate 
# lanes with vehicles using distinct driving models. The creators used are:
# 1. `FixedStateCreator`: Generates vehicles with specified spacing and speed.
# 2. `FixedDemandCreator`: Generates vehicles based on a fixed traffic flow rate.
# ------------------------------------------------------------------------------

# Import the library
import autopysta as ap

# Display the current version of autopysta
print(ap.version())

# Define the highway geometry for the simulation. The Geometry object takes:
# 1. `length`: The length of the highway (meters).
# 2. `lanes`: Number of lanes.
# 3. `merge_pos`: Position where a merge ramp ends (0 for no merge ramp).
# 4. `diverge_pos`: Position where a diverge ramp starts (highway length for no diverge ramp).
length = 1000
initial_lanes = 4
merge_position = 300
diverge_position = 700
highway_geometry = ap.Geometry(length, initial_lanes, merge_position, diverge_position)

# Define the driving models for acceleration/deceleration.
# Default parameters are used for both models.
idm_model = ap.idm()
gipps_model = ap.gipps()

# Specify the types of vehicle creators for each lane. The creators define the
# conditions under which vehicles are added to the lanes:
# - `FixedStateCreator`: Generates vehicles based on specified spacing and speed.
# - `FixedDemandCreator`: Generates vehicles based on a fixed flow rate.
# If only one creator is given, it will apply to all lanes. The final parameter 
# is optional, specifying a maximum number of vehicles (default is unlimited).
spacing = 15
speed = 10
flow_rate = 0.5
lane_creators = [
    ap.FixedStateCreator(gipps_model, spacing, speed),  # Lane 1
    ap.FixedDemandCreator(idm_model, flow_rate),        # Lane 2
    ap.FixedStateCreator(idm_model, spacing, speed),    # Lane 3
    ap.FixedDemandCreator(gipps_model, flow_rate),      # Lane 4 (if present)
]


# Define the lane-changing model. To disable lane changing, use `no_lch`.
lane_change_model = ap.lcm_gipps()

# Initialize the Simulation object with the defined settings. The simulation is
# set to run for 80 seconds with a timestep of 0.1 seconds.
# No vehicles are predefined, so we use an empty list.
# We set verbose mode to get some extra output and see the shape of the geometry
total_time = 80
vehicles=[]
time_step = 0.1
verbose = True
simulation = ap.Simulation(
    lane_change_model,
    total_time,
    highway_geometry,
    lane_creators,
    vehicles,
    time_step
)


# Run the simulation. The `run()` method returns a `Results` object containing
# trajectory data from the simulation.
simulation_results = simulation.run()

# The `plot_x_vs_t` method generates trajectory plots. It can be used to plot
# all lanes or specific lanes, as shown below.
plotting = True
if plotting:
    simulation_results.plot_x_vs_t()       # Plot all lanes
    simulation_results.plot_x_vs_t(lane=1) # Plot only lane 1
    simulation_results.plot_x_vs_t(lane=2) # Plot only lane 2
    simulation_results.plot_x_vs_t(lane=3) # Plot only lane 3
    simulation_results.plot_x_vs_t(lane=4) # Plot only lane 4 (if applicable)

Explanation of the Simulation Example

• Geometry Setup: Creates a highway with a length of 1000 meters and 4 lanes. The highway includes a merge ramp at 300 meters and a diverge ramp at 700.
• Vehicle Models: The IDM, Gipps, and Newell Random Acceleration models are assigned to control vehicle dynamics. Different models can represent various driving styles or traffic conditions.
• Lane Creators: Vehicles are added based on either a fixed spacing (FixedStateCreator) or a flow rate (FixedDemandCreator). This allows the simulation of both congested and free-flowing traffic conditions.
• Lane-Changing Logic: The lane-change model (lcm_gipps) handles vehicle lane changes based on the surrounding traffic conditions, with optional parameters for enabling or disabling lane changes.
• Simulation Execution: The simulation runs for a set period, returning vehicle trajectories for analysis.

Additional Features

• Verbose Mode: Enables detailed output during the simulation, useful for understanding and troubleshooting the behavior of individual vehicles.
• Plotting: The plot_x_vs_t() method generates time-space plots for vehicle trajectories, providing a visual representation of the simulation results.

Documentation

For more detailed information on various aspects of Autopysta, please refer to the following documentation files:

• Bindings Documentation:
  Details on how the C++ classes and functions are exposed to Python.

• Build System Documentation:
  Information about the CMake build process, integration with SWIG, and the usage of pybind11_mkdoc.

• Publishing Instructions:
  Guidelines for publishing new versions of Autopysta.

• TODO List:
  A list of planned features and improvements.