Implement DSO algorithm based on day-to-day dynamics

README.md

@@ -22,14 +22,16 @@ If you are interested, please see:
 ## Main Features
 
 - Simple, lightweight, and easy-to-use Python implementation of modern standard models of dynamic network traffic flow
-- Macroscopic 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
+- 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
 - Dynamic traffic assignment: Traffic flow simulation with a given network and time-dependent OD demand
-- Theoretically valid models commonly used in academic/professional transportation research
-- Implementation of traffic control/management schemes such as taxi/shared-mobility, traffic signals, road pricing, and so on
-- Basic analysis of simulation results and their export to `pandas.DataFrame` and CSV files
-- Visualization of simulation results using `Matplotlib`; interactive GUI is also available
-- Flexible and customizable thanks to pure Python implementation; can also be directly integrated with other Python-based frameworks, such as `PyTorch` for deep reinforcement learning traffic control
-- The main code `uxsim.py` is only about 2300 lines of code. Users may easily understand and customize it
+	- Approximate solvers for Dynamic User Equilibrium and Dynamic System Optimum are also available
+- Theoretically valid models commonly used in academic and professional transportation research
+- Implementation of traffic control and management schemes such as taxi/shared-mobility, traffic signals, road pricing, and so on
+- Flexible and customizable thanks to pure Python implementation
+	- Basic analysis of simulation results and their export to `pandas.DataFrame` and CSV files
+	- Visualization of simulation results using `Matplotlib`; interactive GUI is also available
+	- can also be directly integrated with other Python-based frameworks, such as `PyTorch` for deep reinforcement learning traffic control
+	- The main code `uxsim.py` is only about 1200 lines of code. Users may easily understand and customize it
 
 ## Simulation Examples
 
@@ -58,9 +60,11 @@ A [Jupyter Notebook of this example](https://github.com/toruseo/UXsim/blob/main/
 <img src="https://github.com/toruseo/UXsim/blob/images/anim_network1_0.22_DQL.gif" width="400"/>
 </p>
 
+<!--
 ### Interactive GUI for exploring a simulation result
 
 https://github.com/toruseo/UXsim/assets/34780089/ec780a33-d9ba-4068-a005-0b06127196d9
+-->
 
 ## Install
 
@@ -74,6 +78,9 @@ The simplest way is to use `pip` to install from PyPI:
 pip install uxsim
 ```
 
+<details>
+<summary>Alternative methods for advanced users (click to see)</summary>
+
 ### Using conda
 
 You can also install with `conda` from `conda-forge` channel:
@@ -84,9 +91,6 @@ conda install uxsim
 
 For the details, please see [here](https://github.com/conda-forge/uxsim-feedstock?tab=readme-ov-file#installing-uxsim).
 
-<details>
-<summary>Alternative methods for advanced users (click to see)</summary>
-
 ### Using pip with custom configuration
 
 You can also use `pip` to install the GitHub version:
@@ -204,6 +208,7 @@ To learn more about UXsim, please see:
 - [Demos and examples](https://github.com/toruseo/UXsim/tree/main/demos_and_examples): Various examples using Jupyter Notebooks and Python codes
 - [UXsim Technical Documentation](https://toruseo.jp/UXsim/docs/index.html): Detailed documents on tutorials, simulation mechanism, and specifications of modules/functions
 - [arXiv preprint](https://arxiv.org/abs/2309.17114): Scientific overview
+- [JOSS paper](https://doi.org/10.21105/joss.07617): Peer-reviewed article in Journal of Open Source Software
 
 ## Main Files
 

demos_and_examples/example_26en_dynamic_traffic_assignment_DUO_DUE_DSO.py

@@ -58,16 +58,16 @@ def create_World():
 #################################
 # DUE
 solver_DUE = SolverDUE(create_World)
-solver_DUE.solve(max_iter=20)   # max_iter should be larger (e.g., 100) for a better result. this is just for demonstration
+solver_DUE.solve(max_iter=50)
 W_DUE = solver_DUE.W_sol
 W_DUE.analyzer.print_simple_stats(force_print=True)
 df_DUE = W_DUE.analyzer.basic_to_pandas()
 
 
 #################################
 # DSO
-solver_DSO = SolverDSO_ALNS(create_World)
-solver_DSO.solve(max_iter=100)
+solver_DSO = SolverDSO_D2D(create_World)
+solver_DSO.solve(max_iter=50)
 W_DSO = solver_DSO.W_sol
 W_DSO.analyzer.print_simple_stats(force_print=True)
 df_DSO = W_DSO.analyzer.basic_to_pandas()

tests/test_verification_dta_solvers.py

@@ -61,28 +61,36 @@ def create_World():
 
     #################################
     # DUE
-    solver_DUE = SolverDUE(create_World)
+    solver_DUE = DTAsolvers.SolverDUE(create_World)
     solver_DUE.solve(max_iter=20)   # max_iter should be larger (e.g., 100). this is just for demonstration
     W_DUE = solver_DUE.W_sol
     W_DUE.analyzer.print_simple_stats(force_print=True)
     df_DUE = W_DUE.analyzer.basic_to_pandas()
 
     #################################
-    # DSO by GA
-    solver_DSO_GA = SolverDSO_GA(create_World)
+    # DSO by GA: this is obsolete
+    solver_DSO_GA = DTAsolvers.SolverDSO_GA(create_World)
     solver_DSO_GA.solve(max_iter=20, pop_size=20)   # max_iter should be larger (e.g., 100). this is just for demonstration
     W_DSO_GA = solver_DSO_GA.W_sol
     W_DSO_GA.analyzer.print_simple_stats(force_print=True)
     df_DSO_GA = W_DSO_GA.analyzer.basic_to_pandas()
 
     #################################
-    # DSO by ALNS
-    solver_DSO_ALNS = SolverDSO_ALNS(create_World)
+    # DSO by ALNS: this is obsolete
+    solver_DSO_ALNS = DTAsolvers.SolverDSO_ALNS(create_World)
     solver_DSO_ALNS.solve(max_iter=200)   # max_iter should be larger (e.g., 500). this is just for demonstration
     W_DSO_ALNS = solver_DSO_ALNS.W_sol
     W_DSO_ALNS.analyzer.print_simple_stats(force_print=True)
     df_DSO_ALNS = W_DSO_ALNS.analyzer.basic_to_pandas()
 
+    #################################
+    # DSO by day-to-day: this is recommended
+    solver_DSO_D2D= DTAsolvers.SolverDSO_D2D(create_World)
+    solver_DSO_D2D.solve(max_iter=20)   # max_iter should be larger (e.g., 100). this is just for demonstration
+    W_DSO_D2D = solver_DSO_D2D.W_sol
+    W_DSO_D2D.analyzer.print_simple_stats(force_print=True)
+    df_DSO_D2D = W_DSO_D2D.analyzer.basic_to_pandas()
+
     # stats
     print("DUO")
     print(df_DUO)
@@ -92,6 +100,8 @@ def create_World():
     print(df_DSO_GA)
     print("DSO_ALNS")
     print(df_DSO_ALNS)
+    print("DSO_D2D")
+    print(df_DSO_D2D)
 
     # visualizations
     solver_DUE.plot_convergence()
@@ -103,10 +113,17 @@ def create_World():
     solver_DSO_GA.plot_vehicle_stats(orig="4", dest="7")
 
     solver_DSO_ALNS.plot_convergence()
+    solver_DUE.plot_link_stats()
+    solver_DUE.plot_vehicle_stats(orig="4", dest="7")
 
+    solver_DSO_D2D.plot_convergence()
+    solver_DSO_D2D.plot_link_stats()
+    solver_DSO_D2D.plot_vehicle_stats(orig="4", dest="7")
+
     assert W_DUO.analyzer.total_travel_time > W_DUE.analyzer.total_travel_time
     assert W_DUE.analyzer.total_travel_time > W_DSO_GA.analyzer.total_travel_time
     assert W_DUE.analyzer.total_travel_time > W_DSO_ALNS.analyzer.total_travel_time
+    assert W_DUE.analyzer.total_travel_time > W_DSO_D2D.analyzer.total_travel_time
 
 
 @pytest.mark.flaky(reruns=10)