polish docs for release

- restrict benchmark_apsp() to normal nodes in case centroids are
  added to the network.

Author: jdlph

README.md

@@ -38,7 +38,7 @@ $ pip install path4gmns
 > v0.9.10 comes with bug fix on [find_shortest_path()](https://github.com/jdlph/Path4GMNS/issues/58), new functionality on obtaining the shortest path tree, and performance improvement on the UE module. Please **discard all old versions**.
 
 > [!WARNING]
-> The path cost from find_shortest_path() is in travel time rather than distance for v0.9.9.post1 and any earlier versions. See [Issue #58](https://github.com/jdlph/Path4GMNS/issues/58) for details. v0.9.10 offers the correct implementation.
+> find_shortest_path() computes the shortest path per travel time rather than distance for v0.9.9.post1 and any earlier versions. See [Issue #58](https://github.com/jdlph/Path4GMNS/issues/58) for details. v0.9.10 offers the correct implementation with the flexibility to switch between time and distance.
 
 > [!WARNING]
 > Invoking find_shortest_path() and find_ue() in the same code snippet will lead to [OSError: exception: access violation reading ...](https://github.com/jdlph/Path4GMNS/issues/51#issue-2601430024) for v0.9.9 and any version before.

docs/source/usecases.md

@@ -44,7 +44,7 @@ print('\nshortest path (link id) from node 1 to node 2, '
       +network.find_shortest_path(1, 2, seq_type='link'))
 ```
 
-Retrieving the shortest path between any two (different) nodes under a specific mode is now available under v0.7.2 or higher.
+Retrieving the shortest path between any two (different) nodes under a specific mode is available under v0.7.2 or higher.
 ```python
 import path4gmns as pg
 
@@ -91,29 +91,32 @@ import path4gmns as pg
 
 network = pg.read_network()
 
-# get shortest path tree (in node sequences) from node 1 (cost is measured by time (in minutes))
+# get shortest path tree (in node sequences) from node 1
+# cost is measured by time (in minutes)
 sp_tree_node = network.get_shortest_path_tree(1)
 # retrieve the shortest path from the source node (i.e., node 1) to node 2
 print(f'shortest path (node id) from node 1 to node 2: {sp_tree_node[2]}')
 # retrieve the shortest path from the source node (i.e., node 1) to node 3
 print(f'shortest path (node id) from node 1 to node 3: {sp_tree_node[3]}')
 
-# get shortest path tree (in link sequences) from node 1 (cost is measured by time (in minutes))
+# get shortest path tree (in link sequences) from node 1
+# cost is measured by time (in minutes)
 sp_tree_link = network.get_shortest_path_tree(1, seq_type='link')
 # retrieve the shortest path from the source node (i.e., node 1) to node 2
 print(f'shortest path (link id) from node 1 to node 2: {sp_tree_link[2]}')
 # retrieve the shortest path from the source node (i.e., node 1) to node 3
 print(f'shortest path (link id) from node 1 to node 3: {sp_tree_link[3]}')
 ```
 
-Similarly, you can get the distance-based shortest path tree as well. The distance unit is in line with the one passed to read_network(), which is miles by default.
+Similarly, you can get the distance-based shortest path tree as well. The distance unit is in line with the one passed to read_network().
 
 ```python
 import path4gmns as pg
 
 network = pg.read_network()
 
-# get shortest path tree (in node sequences) from node 1 (cost is measured by distance (in miles))
+# get shortest path tree (in node sequences) from node 1
+# cost is measured by distance (in miles)
 sp_tree_node = network.get_shortest_path_tree(1, cost_type='distance')
 # retrieve the shortest path from the source node (i.e., node 1) to node 2
 print(f'shortest path (node id) from node 1 to node 2: {sp_tree_node[2]}')
@@ -135,14 +138,16 @@ import path4gmns as pg
 
 network = pg.read_network()
 
-# get shortest path tree (in node sequences) from node 1 (cost is measured by time) under mode 'w'
+# get shortest path tree (in node sequences) from node 1 under mode 'w'
+# cost is measured by time (in minutes)
 sp_tree_node = network.get_shortest_path_tree(1, mode='w')
 # retrieve the shortest path from the source node (i.e., node 1) to node 2
 print(f'shortest path (node id) from node 1 to node 2: {sp_tree_node[2]}')
 # retrieve the shortest path from the source node (i.e., node 1) to node 3
 print(f'shortest path (node id) from node 1 to node 3: {sp_tree_node[3]}')
 
-# get shortest path tree (in link sequences) from node 1 (cost is measured by distance) under mode 'w'
+# get shortest path tree (in link sequences) from node 1 under mode 'w'
+# cost is measured by distance
 sp_tree_link = network.get_shortest_path_tree(1, mode='w', seq_type='link', cost_type='distance')
 # retrieve the shortest path from the source node (i.e., node 1) to node 2
 print(f'shortest path (link id) from node 1 to node 2: {sp_tree_link[2]}')
@@ -192,7 +197,7 @@ pg.output_columns(network)
 pg.output_link_performance(network)
 ```
 
-v0.9.10 provides users more flexibility to control UE convergency by returning the relative gap and passing the relative gap tolerance (i.e., the target relative gap). find_ue() will terminate when either column_upd_num or rel_gap_tolerance is reached.
+v0.9.10 provides users more flexibility to control UE convergency with the relative gap tolerance (i.e., the target relative gap). find_ue() will terminate when either column_upd_num or rel_gap_tolerance is reached and return the final relative gap.
 ```python
 import path4gmns as pg
 
@@ -215,7 +220,7 @@ pg.output_link_performance(network)
 
 ### In Case of Special Events
 
-A special event often comes with capacity reduction over affected links, which is now supported in v0.8.4 or higher. You can introduce one special event for each demand period in settings.yml as below.
+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.
 
 ```yaml
 demand_periods:

path4gmns/dtaapi.py

@@ -45,8 +45,8 @@ def perform_network_assignment_DTALite(assignment_mode,
     WARNING
     -------
     MAKE SURE TO BACKUP route_assignment.csv and link_performance.csv if you have
-    called perform_network_assignment() before. Otherwise, they will be
-    overwritten by results generated by DTALite.
+    called find_ue() before. Otherwise, they will be overwritten by results
+    generated by DTALite.
 
     Parameters
     ----------
@@ -162,7 +162,7 @@ def run_DTALite():
     Only use the following data set from
     https://github.com/asu-trans-ai-lab/DTALite/tree/feature/multimodal/data.
 
-    Please run the script calling this API using system terminal rather than
+    Please run the script calling this API using your system terminal rather than
     Python console for proper logging.
     """
     _dtalitemm_engine = ctypes.cdll.LoadLibrary(_dtalitemm_dll)

path4gmns/path.py

@@ -246,6 +246,10 @@ def benchmark_apsp(G):
     st = time()
 
     for k in G.map_id_to_no:
+        # do not include centroids
+        if G.map_id_to_no[k] >= G.get_last_thru_node():
+            break
+        
         single_source_shortest_path(G, k)
 
     print(f'processing time of finding all-pairs shortest paths: {time()-st:.4f} s')

tutorial/tutorial.ipynb

@@ -832,7 +832,7 @@
     "\n",
     "Starting from v0.9.6, you could conduct the above tasks using the [Multimodal DTALite](https://github.com/asu-trans-ai-lab/DTALite/tree/feature/multimodal). No parameters are needed. \n",
     "\n",
-    "Note that running it with the current input will lead to *kernel crash* as it requires a **different [settings.yml](https://github.com/asu-trans-ai-lab/DTALite/blob/feature/multimodal/data/01_4_node_network/minimum_input/settings.yml)**! You can test this API with [this data set](https://github.com/asu-trans-ai-lab/DTALite/tree/feature/multimodal/data). "
+    "**Note that** running it with the current input will lead to *kernel crash* as it requires a **different [settings.yml](https://github.com/asu-trans-ai-lab/DTALite/blob/feature/multimodal/data/01_4_node_network/minimum_input/settings.yml)**! You can test this API with [this data set](https://github.com/asu-trans-ai-lab/DTALite/tree/feature/multimodal/data). "
    ]
   },
   {