update documentation on link-based ue

- add use cases on link-based ue in usecases.md and tutorial.ipynb;
- conduct minor cosmetic changes to find_ue() and find_ue_fw();
- update README.md on release date.

Author: jdlph

README.md

@@ -60,7 +60,7 @@ The Python modules are written in **Python 3.x**, which is the minimum requireme
 
 ## How to Cite
 
-Li, P. and Zhou, X. (2025, March 16). *Path4GMNS*. Retrieved from https://github.com/jdlph/Path4GMNS
+Li, P. and Zhou, X. (2025, December 12). *Path4GMNS*. Retrieved from https://github.com/jdlph/Path4GMNS
 
 ## Please Contribute
 

docs/source/usecases.md

@@ -156,8 +156,10 @@ print(f'shortest path (link id) from node 1 to node 2: {sp_tree_link[2]}')
 print(f'shortest path (link id) from node 1 to node 3: {sp_tree_link[3]}')
 ```
 
-## Find Path-Based UE
-The Python column-generation module only implements path-based UE. If you need other assignment modes, e.g., link-based UE or DTA, please use DTALiteClassic(). Note that **column_gen_num** below specifies the maximum number of paths / columns for each OD pair.
+## Find UE
+
+### Path-Based UE
+The column-generation module implements the path-based UE, where **column_gen_num** below specifies the maximum number of paths / columns for each OD pair.
 
 ```python
 import path4gmns as pg
@@ -219,6 +221,36 @@ pg.output_columns(network)
 pg.output_link_performance(network)
 ```
 
+### Link-Based UE
+
+v0.10.0 introduces the link-based UE that adopts the Frank-Wolfe algorithm with line search. Compared to the path-based UE, it does not preserve any paths / columns but only (unique) link flows. Therefore, each iteration runs faster than the path-based procedure with less memory footprint.
+
+```python
+import path4gmns as pg
+
+network = pg.read_network()
+pg.read_demand(network)
+
+pg.find_ue_fw(network)
+pg.output_link_performance(network)
+
+# NOTE that pg.output_columns(network) is NOT available under the link-based UE!
+```
+find_ue_fw() will terminate when it reaches the maximum number of iterations (**max_iter_num**) or the target relative gap (**rel_gap_tolerance**), whichever comes first. The default values are **40** and **1e-04**, respectively. You can specify
+their values toward your own need like below.
+
+```python
+import path4gmns as pg
+
+network = pg.read_network()
+pg.read_demand(network)
+
+pg.find_ue_fw(network, max_iter_num=100, rel_gap_tolerance=1e-6)
+pg.output_link_performance(network)
+
+# NOTE that pg.output_columns(network) is NOT available under the link-based UE!
+```
+
 ### In Case of Special Events
 
 A special event often comes with capacity reduction over affected links, which is supported in v0.8.4 or higher. You can introduce one special event for each demand period in settings.yml as below.

path4gmns/colgen.py

@@ -294,7 +294,7 @@ def update_links_using_columns(network):
     _update_link_travel_time(links)
 
 
-def find_ue(ui, column_gen_num, column_upd_num, rel_gap_tolerance=0.0001):
+def find_ue(ui, column_gen_num, column_upd_num, rel_gap_tolerance=1e-04):
     """ find user equilibrium (UE)
 
     WARNING

path4gmns/fw.py

@@ -171,7 +171,7 @@ def _init_sys_tt(demand_period_count):
         _total_min_sys_travel_time[tau] = 0
 
 
-def find_ue_fw(ui, max_iter = 40, rel_gap_tolerance=1e-04):
+def find_ue_fw(ui, max_iter=40, rel_gap_tolerance=1e-04):
     """ find user equilibrium (UE) with the Frank-Wolfe Algorithm
 
     WARNING

tutorial/tutorial.ipynb

@@ -282,15 +282,21 @@
    "id": "mysterious-diamond",
    "metadata": {},
    "source": [
-    "### 3.3 Perform Path-Based UE Traffic Assignment\n",
+    "### 3.3 Perform UE Traffic Assignment\n",
+    "\n",
+    "#### 3.3.1 Prerequisite on Demand\n",
     "\n",
     "OD demand matrix and zone information is crucial in conducting traffic assignment are essential to perform this functionality. The demand file is presumed to be given and zone information is provided along node.csv. The latter is the current design of GMNS and is endorsed in [OSM2GMNS](https://github.com/jiawlu/OSM2GMNS).\n",
     "\n",
     "The demand will be loaded by default via pg.read_demand(). If demand.csv is missing, pg.read_demand() will automatically conduct the following attempts.\n",
     "1. try to load the synthetic demand (as syn_demand.csv and zones as syn_zone.csv).\n",
     "2. synthesize demand (and zones) if the previous attempt fails.\n",
     "\n",
-    "Then you can conduct traffic assignment via the following lines."
+    "The demand file is specified in settings.yml as demand.csv (see 4.1 Sample setting.yml for details). You can change it to any demand file in your PWD. This design actually allows us to load multiple demand files simultaneously corresponding to different period and agent_type. We will elaborate it in a future release.\n",
+    "\n",
+    "#### 3.3.2 Path-Based UE\n",
+    "\n",
+    "With the required demand file, then you can conduct path-based UE traffic assignment via the following lines."
    ]
   },
   {
@@ -323,8 +329,6 @@
    "id": "c2c1211e",
    "metadata": {},
    "source": [
-    "The demand file is specified in settings.yml as demand.csv (see 4.1 Sample setting.yml for details). You can change it to any demand file in your PWD. This design actually allows us to load multiple demand files simultaneously corresponding to different period and agent_type. We will elaborate it in a future release.\n",
-    "\n",
     "The code snippet below demonstrates how to adaptively the UE convergency directly through rel_gap_tolerance. find_ue() will terminate when either column_upd_num or rel_gap_tolerance is reached."
    ]
   },
@@ -342,8 +346,8 @@
     "column_gen_num = 20\n",
     "column_upd_num = 20\n",
     "\n",
-    "# the default value of rel_gap_tolerance is 0.0001 if not specified\n",
-    "rel_gap = pg.find_ue(network, column_gen_num, column_upd_num, rel_gap_tolerance = 0.001)\n",
+    "# the default value of rel_gap_tolerance is 1e-04 if not specified\n",
+    "rel_gap = pg.find_ue(network, column_gen_num, column_upd_num, rel_gap_tolerance=1e-04)\n",
     "print(f'the final relative UE gap is {rel_gap:.4%}')\n",
     "\n",
     "# if you want to include path geometry info in the output file,\n",
@@ -352,14 +356,65 @@
     "pg.output_link_performance(network)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "14ea3a1a",
+   "metadata": {},
+   "source": [
+    "#### 3.3.3 Link-Based UE\n",
+    "\n",
+    "The link-based UE does not preserve any paths / columns but only (unique) link flows. Thus, pg.output_columns(network) is NOT available."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4fafb09b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "network = pg.read_network()\n",
+    "pg.read_demand(network)\n",
+    "\n",
+    "pg.find_ue_fw(network)\n",
+    "pg.output_link_performance(network)\n",
+    "\n",
+    "# NOTE that pg.output_columns(network) is NOT available under the link-based UE!"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bf333d6c",
+   "metadata": {},
+   "source": [
+    "find_ue_fw() will terminate when it reaches the maximum number of iterations (**max_iter_num**) or the target relative gap (**rel_gap_tolerance**), whichever comes first. The default values are **40** and **1e-04**, respectively. You can adjust\n",
+    "their values toward your own need like below."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8cfb704d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "network = pg.read_network()\n",
+    "pg.read_demand(network)\n",
+    "\n",
+    "pg.find_ue_fw(network, max_iter_num=100, rel_gap_tolerance=1e-6)\n",
+    "pg.output_link_performance(network)\n",
+    "\n",
+    "# NOTE that pg.output_columns(network) is NOT available under the link-based UE!"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "ad91ad31",
    "metadata": {},
    "source": [
     "### 3.4 Conduct Dynamic Traffic Simulation\n",
     "\n",
-    "Traffic simulation requires routing decision for each agent, which comes from the UE traffic assignment."
+    "Traffic simulation requires routing decision for each agent, which comes from the **path-based UE** traffic assignment."
    ]
   },
   {
@@ -610,12 +665,6 @@
     "pg.download_sample_setting_file()"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "id": "e631fbf5",
-   "metadata": {},
-   "source": []
-  },
   {
    "cell_type": "markdown",
    "id": "great-catholic",