UXsim: Traffic flow simulator in pure Python

UXsim is a lightweight traffic flow simulator in pure Python. You can model various traffic scenarios, from small toy networks to large metropolitan areas, by intuitive Python coding. Especially useful for academic research and educational use.

Quick Start

Install

For Python 3.10 or later

pip install uxsim

Sample code

from uxsim import World

# Units are standardized to seconds (s) and meters (m)
W = World(name="simple", tmax=2000)

W.addNode("start", x=0, y=0)
W.addNode("bottleneck", x=5000, y=0, flow_capacity=0.4)
W.addNode("goal", x=7500, y=0)

W.addLink("road1", start_node="start", end_node="bottleneck", length=5000)
W.addLink("road2", start_node="bottleneck", end_node="goal", length=2500)

W.adddemand(orig="start", dest="goal", t_start=0, t_end=600, flow=0.8)

W.exec_simulation()

W.analyzer.network_fancy()

Result

Traffic congestion caused by the bottleneck

Simulation Examples

Large-scale scenario

Approximately 60000 vehicles pass through a 10km x 10km grid network in 2 hours. The computation time was about 30 seconds on a standard desktop PC. In the first animation, thicker lines mean more vehicles and darker colors mean slower speeds.

Code (click to see)

from uxsim import World

# Define the main simulation
# Units are standardized to seconds (s) and meters (m)
W = World(
    name="grid",
    deltan=5,
    tmax=7200,
    print_mode=1, save_mode=1, show_mode=0,
    random_seed=0,
)

# Scenario
# automated network generation, deploy nodes as an imax x jmax grid
imax = 11
jmax = 11
nodes = {}
for i in range(imax):
    for j in range(jmax):
        nodes[i,j] = W.addNode(f"n{(i,j)}", i, j)

# create links between neighborhood nodes
links = {}
for i in range(imax):
    for j in range(jmax):
        if i != imax-1:
            links[i,j,i+1,j] = W.addLink(f"l{(i,j,i+1,j)}", nodes[i,j], nodes[i+1,j], length=1000, free_flow_speed=20, jam_density=0.2)
        if i != 0:
            links[i,j,i-1,j] = W.addLink(f"l{(i,j,i-1,j)}", nodes[i,j], nodes[i-1,j], length=1000, free_flow_speed=20, jam_density=0.2)
        if j != jmax-1:
            links[i,j,i,j+1] = W.addLink(f"l{(i,j,i,j+1)}", nodes[i,j], nodes[i,j+1], length=1000, free_flow_speed=20, jam_density=0.2)
        if j != 0:
            links[i,j,i,j-1] = W.addLink(f"l{(i,j,i,j-1)}", nodes[i,j], nodes[i,j-1], length=1000, free_flow_speed=20, jam_density=0.2)

# generate traffic demand between the boundary nodes
demand_flow = 0.035
demand_duration = 3600
for n1 in [(0,j) for j in range(jmax)]:
    for n2 in [(imax-1,j) for j in range(jmax)]:
        W.adddemand(nodes[n2], nodes[n1], 0, demand_duration, demand_flow)
        W.adddemand(nodes[n1], nodes[n2], 0, demand_duration, demand_flow)
for n1 in [(i,0) for i in range(imax)]:
    for n2 in [(i,jmax-1) for i in range(imax)]:
        W.adddemand(nodes[n2], nodes[n1], 0, demand_duration, demand_flow)
        W.adddemand(nodes[n1], nodes[n2], 0, demand_duration, demand_flow)

# execute simulation
W.exec_simulation()

# result
W.analyzer.print_simple_stats()
W.analyzer.network_anim(animation_speed_inverse=15, detailed=0, network_font_size=0)
W.analyzer.network_fancy()

AI-based traffic signal control using PyTorch

A traffic signal controller is trained by AI (deep reinforcement learning) using PyTorch. The first result shows no control with fixed signal timing; a gridlock occurs. The second result shows AI-based control; although the demand level is the same, traffic flows smoothly. A Jupyter Notebook of this example is available.

Main Features

• Lightweight, pure-Python, and fast mesoscopic simulation
• Simulate large-scale traffic networks, such as metropolitan areas with 1 million vehicles in a minute
• Based on theoretically valid models used in transportation research
• Apply traffic control mechanisms such as signals, tolls, and shared mobility
• Fully written in Python (core code ~1200 lines), easy to read and modify
• Supports approximate solvers for Dynamic User Equilibrium and Dynamic System Optimum
• Includes built-in analysis tools using matplotlib and pandas

Further Reading

To learn more about UXsim, please see:

• UXsim Technical Documentation: Detailed documents on tutorials, simulation mechanism, and specifications of modules/functions
• Simple demo in Jupyter Notebook or Google Colab: Interactive demonstrations
• Demos and examples: Various examples using Jupyter Notebooks and Python codes
• Scientific overview: Peer-reviewed article in Journal of Open Source Software

Terms of Use & License

UXsim is released under the MIT License. You are free to use it as long as the source is acknowledged.

When publishing works based on UXsim, please cite:

• Toru Seo. UXsim: lightweight mesoscopic traffic flow simulator in pure Python. Journal of Open Source Software, Vol. 10, No. 106, p. 7617, 2025.

@Article{seo2025uxsim,
  author    = {Toru Seo},
  journal   = {Journal of Open Source Software},
  title     = {{UXsim}: lightweight mesoscopic traffic flow simulator in pure {Python}},
  year      = {2025},
  number    = {106},
  pages     = {7617},
  volume    = {10},
  doi       = {10.21105/joss.07617},
  publisher = {The Open Journal},
  url       = {https://doi.org/10.21105/joss.07617},
}

Works using UXsim are summarized on the Github Wiki page. Please feel free to edit.

Contributing and Discussion

Contributions are welcome! Please see the Contributing Guideline.

If you have any questions or suggestions, please post them to the Issues or Discussions (in English or Japanese).

Author

Toru Seo, Institute of Science Tokyo