Skip to content

Commit f2f2edf

Browse files
toruseotoruseo
authored
Merge pull request #253 from toruseo/develop
Reworked README.md
2 parents 6dfb30f + bfbb88b commit f2f2edf

File tree

1 file changed

+107
-179
lines changed

1 file changed

+107
-179
lines changed

‎README.md‎

Lines changed: 107 additions & 179 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# UXsim: Network traffic flow simulator in pure Python
1+
# UXsim: Traffic flow simulator in pure Python
22

33
[![PyPi](https://img.shields.io/pypi/v/uxsim.svg)](https://pypi.python.org/pypi/uxsim)
44
[![Conda Version](https://img.shields.io/conda/vn/conda-forge/uxsim.svg)](https://anaconda.org/conda-forge/uxsim)<!-- ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/uxsim)-->
@@ -8,207 +8,152 @@
88
[![arXiv](https://img.shields.io/badge/arXiv-2309.17114-b31b1b.svg)](http://dx.doi.org/10.48550/arXiv.2309.17114)
99
[![DOI](https://joss.theoj.org/papers/10.21105/joss.07617/status.svg)](https://doi.org/10.21105/joss.07617)
1010
[![Static Badge](https://img.shields.io/badge/readme-%E6%97%A5%E6%9C%AC%E8%AA%9E%20%F0%9F%87%AF%F0%9F%87%B5%20-pink)](https://github.com/toruseo/UXsim/blob/main/README.jp.md)
11+
[![Static Badge](https://img.shields.io/badge/docs-%F0%9F%93%96-lightblue)](https://toruseo.jp/UXsim/docs/)
1112

12-
*UXsim* is a free, open-source macroscopic and mesoscopic network traffic flow simulator written in Python.
13-
It simulates the movements of car travelers and traffic congestion in road networks.
14-
It is suitable for simulating large-scale (e.g., city-scale) traffic phenomena.
15-
UXsim is especially useful for scientific and educational purposes because of its simple, lightweight, and customizable features, but users are free to use UXsim for any purpose.
13+
*UXsim* is a lightweight traffic flow simulator in pure Python.
14+
It enables users to model various traffic scenarios, from small toy networks to large metropolitan areas, without external dependencies.
15+
Especially ideal for academic research and educational use.
1616

17-
If you are interested, please see:
17+
## Quick Start
18+
### Install
1819

19-
- [Jupyter Notebook](https://github.com/toruseo/UXsim/blob/main/demos_and_examples/demo_notebook_01en.ipynb) or [Google Colab](http://colab.research.google.com/github/toruseo/UXsim/blob/main/demos_and_examples/demo_notebook_05en_for_google_colab.ipynb): Interactive demonstrations and tutorials
20-
- [Technical Documentation](https://toruseo.jp/UXsim/docs/index.html): Detailed documents on tutorials, simulation mechanism, and specifications of modules/functions
20+
For Python 3.10 or later
2121

22-
## Main Features
23-
24-
- Simple, lightweight, and easy-to-use Python implementation of modern standard models of dynamic network traffic flow
25-
- Macroscopic and mesoscopic traffic simulation: Simulating over 60000 vehicles in a city in 30 seconds, or even 1 million vehicles in a metropolitan area in 40 seconds depending on the simulation setting
26-
- Dynamic traffic assignment: Traffic flow simulation with a given network and time-dependent OD demand
27-
- Approximate solvers for Dynamic User Equilibrium and Dynamic System Optimum are also available
28-
- Theoretically valid models commonly used in academic and professional transportation research
29-
- Implementation of traffic control and management schemes such as taxi/shared-mobility, traffic signals, road pricing, and so on
30-
- Flexible and customizable thanks to pure Python implementation
31-
- Basic analysis of simulation results and their export to `pandas.DataFrame` and CSV files
32-
- Visualization of simulation results using `Matplotlib`; interactive GUI is also available
33-
- Can also be directly integrated with other Python-based frameworks, such as `PyTorch` for deep reinforcement learning traffic control
34-
- The main code `uxsim.py` is only about 1200 lines of code. Users may easily understand and customize it
35-
36-
## Simulation Examples
37-
38-
### Large-scale scenario
39-
40-
Below are simulation results where 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.
41-
42-
Visualization of link traffic states (thicker lines mean more vehicles, darker colors mean slower speeds) and some vehicle trajectories:
43-
<p float="left">
44-
<img src="https://github.com/toruseo/UXsim/blob/images/gridnetwork_macro.gif" width="400"/>
45-
<img src="https://github.com/toruseo/UXsim/blob/images/gridnetwork_fancy.gif" width="400"/>
46-
</p>
47-
48-
Vehicle trajectory diagram on a corridor of the above network:
49-
<img src="https://github.com/toruseo/UXsim/blob/images/tsd_traj_links_grid.png" width="600">
50-
51-
### Deep reinforcement learning signal control using PyTorch
52-
53-
A traffic signal controller is trained by deep reinforcement learning (DRL) using [PyTorch](https://pytorch.org/).
54-
The left (or upper) scenario shows no control with fixed signal timing; the traffic demand exceeds the network capacity with the naive signal setting, and a gridlock occurs.
55-
The right (or bottom) scenario shows DRL control, where the traffic signal can be changed by observing queue length; although the demand level is the same, traffic flows smoothly.
56-
A [Jupyter Notebook of this example](https://github.com/toruseo/UXsim/blob/main/demos_and_examples/demo_notebook_03en_pytorch.ipynb) is available.
57-
58-
<p float="left">
59-
<img src="https://github.com/toruseo/UXsim/blob/images/anim_network1_0.22_nocontrol.gif" width="400"/>
60-
<img src="https://github.com/toruseo/UXsim/blob/images/anim_network1_0.22_DQL.gif" width="400"/>
61-
</p>
22+
```bash
23+
pip install uxsim
24+
```
6225

63-
<!--
64-
### Interactive GUI for exploring a simulation result
26+
### Sample code
6527

66-
https://github.com/toruseo/UXsim/assets/34780089/ec780a33-d9ba-4068-a005-0b06127196d9
67-
-->
28+
```python
29+
from uxsim import World
6830

69-
## Install
31+
# Units are standardized to seconds (s) and meters (m)
32+
W = World(name="simple", tmax=2000)
7033

71-
UXsim is available for Python version 3.10 or later.
34+
W.addNode("start", x=0, y=0)
35+
W.addNode("bottleneck", x=5000, y=0, flow_capacity=0.4)
36+
W.addNode("goal", x=7500, y=0)
7237

73-
### Using pip
38+
W.addLink("road1", start_node="start", end_node="bottleneck", length=5000)
39+
W.addLink("road2", start_node="bottleneck", end_node="goal", length=2500)
7440

75-
The simplest way is to use `pip` to install from PyPI:
41+
W.adddemand(orig="start", dest="goal", t_start=0, t_end=600, flow=0.8)
7642

77-
```
78-
pip install uxsim
79-
```
80-
81-
<details>
82-
<summary>Alternative methods for advanced users (click to see)</summary>
83-
84-
### Using conda
85-
86-
You can also install with `conda` from `conda-forge` channel:
43+
W.exec_simulation()
8744

88-
```
89-
conda install uxsim
45+
W.analyzer.network_fancy()
9046
```
9147

92-
For the details, please see [here](https://github.com/conda-forge/uxsim-feedstock?tab=readme-ov-file#installing-uxsim).
48+
### Result
9349

94-
### Using pip with custom configuration
95-
96-
You can also use `pip` to install the GitHub version:
97-
98-
```
99-
pip install -U -e git+https://github.com/toruseo/uxsim@main#egg=uxsim
100-
```
50+
Traffic congestion caused by the bottleneck
10151

102-
Or any other (development) branch on this repo or your own fork:
52+
![anim_network_fancy](https://github.com/user-attachments/assets/ab5e5fac-e2b3-4548-90ac-e4a5d7d302b0)
10353

104-
```
105-
pip install -U -e git+https://github.com/YOUR_FORK/uxsim@YOUR_BRANCH#egg=uxsim
106-
```
54+
## Simulation Examples
10755

108-
109-
### Manual install
56+
### Large-scale scenario
11057

111-
Download the `uxsim` directory from this Github repo or [the latest release](https://github.com/toruseo/UXsim/releases/latest/download/uxsim.zip) and place it in your local directory as follows:
112-
```
113-
your_project_directory/
114-
├── uxsim/ # The uxsim directory
115-
│ ├── uxsim.py # The main code of UXsim. You can customize this as you wish
116-
│ └── ... # Other files and directories in uxsim
117-
├── your_simulation_code.py # Your code if necessary
118-
├── your_simulation_notebook.ipynb # Your Jupyter notebook if necessary
119-
├── ... # Other files if necessary
120-
```
121-
This way, you can flexibly customize UXsim on your own.
58+
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.
59+
In the first animation, thicker lines mean more vehicles and darker colors mean slower speeds.
12260

123-
</details>
61+
<p float="left">
62+
<img src="https://github.com/toruseo/UXsim/blob/images/gridnetwork_macro.gif" width="400"/>
63+
<img src="https://github.com/toruseo/UXsim/blob/images/gridnetwork_fancy.gif" width="400"/>
64+
</p>
12465

125-
## Getting Started
66+
<details>
67+
<summary>Code (click to see)</summary>
12668

127-
As a simple example, the following code will simulate traffic flow in a Y-shaped network.
12869
```python
12970
from uxsim import World
13071

13172
# Define the main simulation
13273
# Units are standardized to seconds (s) and meters (m)
13374
W = World(
134-
name="", # Scenario name
135-
deltan=5, # Simulation aggregation unit delta n
136-
tmax=1200, # Total simulation time (s)
137-
print_mode=1, save_mode=1, show_mode=1, # Various options
138-
random_seed=0 # Set the random seed
75+
name="grid",
76+
deltan=5,
77+
tmax=7200,
78+
print_mode=1, save_mode=1, show_mode=0,
79+
random_seed=0,
13980
)
14081

141-
# Define the scenario
142-
# Create nodes
143-
W.addNode(name="orig1", x=0, y=0) #xy coords are for visualization
144-
W.addNode(name="orig2", x=0, y=2)
145-
W.addNode(name="merge", x=1, y=1)
146-
W.addNode(name="dest", x=2, y=1)
147-
148-
# Create links between nodes
149-
W.addLink(name="link1", start_node="orig1", end_node="merge", length=1000, free_flow_speed=20, number_of_lanes=1)
150-
W.addLink(name="link2", start_node="orig2", end_node="merge", length=1000, free_flow_speed=20, number_of_lanes=1)
151-
W.addLink(name="link3", start_node="merge", end_node="dest", length=1000, free_flow_speed=20, number_of_lanes=1)
152-
153-
# Create OD traffic demand between nodes
154-
W.adddemand(orig="orig1", dest="dest", t_start=0, t_end=1000, flow=0.45)
155-
W.adddemand(orig="orig2", dest="dest", t_start=400, t_end=1000, flow=0.6)
156-
157-
# Run the simulation to the end
82+
# Scenario
83+
# automated network generation, deploy nodes as an imax x jmax grid
84+
imax = 11
85+
jmax = 11
86+
nodes = {}
87+
for i in range(imax):
88+
for j in range(jmax):
89+
nodes[i,j] = W.addNode(f"n{(i,j)}", i, j)
90+
91+
# create links between neighborhood nodes
92+
links = {}
93+
for i in range(imax):
94+
for j in range(jmax):
95+
if i != imax-1:
96+
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)
97+
if i != 0:
98+
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)
99+
if j != jmax-1:
100+
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)
101+
if j != 0:
102+
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)
103+
104+
# generate traffic demand between the boundary nodes
105+
demand_flow = 0.035
106+
demand_duration = 3600
107+
for n1 in [(0,j) for j in range(jmax)]:
108+
for n2 in [(imax-1,j) for j in range(jmax)]:
109+
W.adddemand(nodes[n2], nodes[n1], 0, demand_duration, demand_flow)
110+
W.adddemand(nodes[n1], nodes[n2], 0, demand_duration, demand_flow)
111+
for n1 in [(i,0) for i in range(imax)]:
112+
for n2 in [(i,jmax-1) for i in range(imax)]:
113+
W.adddemand(nodes[n2], nodes[n1], 0, demand_duration, demand_flow)
114+
W.adddemand(nodes[n1], nodes[n2], 0, demand_duration, demand_flow)
115+
116+
# execute simulation
158117
W.exec_simulation()
159118

160-
# Print summary of simulation result
119+
# result
161120
W.analyzer.print_simple_stats()
162-
163-
# Visualize snapshots of network traffic state for several timesteps
164-
W.analyzer.network(t=100, detailed=1, network_font_size=12)
165-
W.analyzer.network(t=600, detailed=1, network_font_size=12)
166-
W.analyzer.network(t=800, detailed=1, network_font_size=12)
121+
W.analyzer.network_anim(animation_speed_inverse=15, detailed=0, network_font_size=0)
122+
W.analyzer.network_fancy()
167123
```
124+
</details>
125+
126+
### AI-based traffic signal control using PyTorch
127+
128+
A traffic signal controller is trained by AI (deep reinforcement learning) using [PyTorch](https://pytorch.org/).
129+
The first result shows no control with fixed signal timing; a gridlock occurs.
130+
The second result shows AI-based control; although the demand level is the same, traffic flows smoothly.
131+
A [Jupyter Notebook of this example](https://github.com/toruseo/UXsim/blob/main/demos_and_examples/demo_notebook_03en_pytorch.ipynb) is available.
168132

169-
It will output text to the terminal and images to the `out` directory like below:
170-
```
171-
simulation setting:
172-
scenario name:
173-
simulation duration: 1200 s
174-
number of vehicles: 810 veh
175-
total road length: 3000 m
176-
time discret. width: 5 s
177-
platoon size: 5 veh
178-
number of timesteps: 240
179-
number of platoons: 162
180-
number of links: 3
181-
number of nodes: 4
182-
setup time: 0.00 s
183-
simulating...
184-
time| # of vehicles| ave speed| computation time
185-
0 s| 0 vehs| 0.0 m/s| 0.00 s
186-
600 s| 130 vehs| 13.7 m/s| 0.03 s
187-
1195 s| 75 vehs| 12.3 m/s| 0.06 s
188-
simulation finished
189-
results:
190-
average speed: 11.6 m/s
191-
number of completed trips: 735 / 810
192-
average travel time of trips: 162.6 s
193-
average delay of trips: 62.6 s
194-
delay ratio: 0.385
195-
```
196133
<p float="left">
197-
<img src="https://github.com/toruseo/UXsim/blob/images/network1_100.png" width="250"/>
198-
<img src="https://github.com/toruseo/UXsim/blob/images/network1_600.png" width="250"/>
199-
<img src="https://github.com/toruseo/UXsim/blob/images/network1_800.png" width="250"/>
134+
<img src="https://github.com/toruseo/UXsim/blob/images/anim_network1_0.22_nocontrol.gif" width="400"/>
135+
<img src="https://github.com/toruseo/UXsim/blob/images/anim_network1_0.22_DQL.gif" width="400"/>
200136
</p>
201137

138+
139+
## Main Features
140+
141+
- Lightweight, dependency-free, and fast mesoscopic simulation
142+
- Simulate large-scale traffic networks with 1 million vehicles in a minute
143+
- Based on theoretically valid models used in transportation research
144+
- Apply traffic control mechanisms such as signals, tolls, and shared mobility
145+
- Fully written in Python (core code ~1200 lines), easy to read and modify
146+
- Supports approximate solvers for Dynamic User Equilibrium and Dynamic System Optimum
147+
- Built-in analysis tool using `matplotlib` and `pandas`
148+
202149
## Further Reading
203150

204151
To learn more about UXsim, please see:
205152

153+
- [UXsim Technical Documentation](https://toruseo.jp/UXsim/docs/index.html): Detailed documents on tutorials, simulation mechanism, and specifications of modules/functions
206154
- [Simple demo in Jupyter Notebook](https://github.com/toruseo/UXsim/blob/main/demos_and_examples/demo_notebook_01en.ipynb) or [Google Colab](http://colab.research.google.com/github/toruseo/UXsim/blob/main/demos_and_examples/demo_notebook_05en_for_google_colab.ipynb): Interactive demonstrations
207155
- [Demos and examples](https://github.com/toruseo/UXsim/tree/main/demos_and_examples): Various examples using Jupyter Notebooks and Python codes
208-
- [UXsim Technical Documentation](https://toruseo.jp/UXsim/docs/index.html): Detailed documents on tutorials, simulation mechanism, and specifications of modules/functions
209-
- [arXiv preprint](https://arxiv.org/abs/2309.17114): Scientific overview
210-
- [JOSS paper](https://doi.org/10.21105/joss.07617): Peer-reviewed article in Journal of Open Source Software
211-
156+
- [Scientific overview](https://doi.org/10.21105/joss.07617): Peer-reviewed article in Journal of Open Source Software
212157

213158
## Terms of Use & License
214159

@@ -217,8 +162,8 @@ UXsim is released under the MIT License. You are free to use it as long as the s
217162
When publishing works based on UXsim, please cite:
218163
- Toru Seo. [UXsim: lightweight mesoscopic traffic flow simulator in pure Python](https://doi.org/10.21105/joss.07617). Journal of Open Source Software, Vol. 10, No. 106, p. 7617, 2025.
219164

220-
```
221-
@Article{seo2025joss,
165+
```bibtex
166+
@Article{seo2025uxsim,
222167
author = {Toru Seo},
223168
journal = {Journal of Open Source Software},
224169
title = {{UXsim}: lightweight mesoscopic traffic flow simulator in pure {Python}},
@@ -231,11 +176,6 @@ When publishing works based on UXsim, please cite:
231176
url = {https://doi.org/10.21105/joss.07617},
232177
}
233178
```
234-
235-
If you need more detailed information, please also cite:
236-
- Toru Seo. [Macroscopic Traffic Flow Simulation: Fundamental Mathematical Theory and Python Implementation](https://toruseo.github.io/misc/MacroTrafficSim_English_summary.pdf). Corona Publishing Co., Ltd., 2023.
237-
- Toru Seo. [UXsim: An open source macroscopic and mesoscopic traffic simulator in Python-a technical overview](http://dx.doi.org/10.48550/arXiv.2309.17114). arXiv preprint arXiv: 2309.17114, 2023.
238-
239179
Works using UXsim are summarized on the [Github Wiki page](https://github.com/toruseo/UXsim/wiki). Please feel free to edit.
240180

241181
## Contributing and Discussion
@@ -245,18 +185,6 @@ Please see the [Contributing Guideline](https://github.com/toruseo/UXsim/blob/ma
245185

246186
If you have any questions or suggestions, please post them to the [Issues](https://github.com/toruseo/UXsim/issues) or [Discussions](https://github.com/toruseo/UXsim/discussions) (in English or Japanese).
247187

248-
I (Toru Seo) work on this project in my spare time. Please understand that my response may be delayed.
249-
250-
## Acknowledgments
251-
252-
UXsim is based on various works in traffic flow theory and related fields. We acknowledge the contributions of the research community in advancing this field.
253-
Specifically, UXsim directly uses the following works:
254-
255-
- [Newell's simplified car-following model](https://doi.org/10.1016/S0191-2615(00)00044-8) and its extension [X-model](https://doi.org/10.1016/j.trb.2013.02.008)
256-
- [Incremental Node Model](https://doi.org/10.1016/j.trb.2011.04.001) and its [mesoscopic version](https://ubiquitypress.com/site/chapters/e/10.5334/baw.50/)
257-
- [Dynamic User Optimum](https://doi.org/10.1016/S0191-2615(00)00005-9)-type Route Choice Model
258-
259-
## Related Links
188+
## Author
260189

261-
- [Toru Seo (Author)](https://toruseo.jp/index_en.html)
262-
- [Seo Laboratory, Institute of Science Tokyo](http://seo.cv.ens.titech.ac.jp/en/)
190+
[Toru Seo, Institute of Science Tokyo](https://toruseo.jp/index.html)

0 commit comments

Comments
 (0)