update usecases and tutorial for release

Author: jdlph

README.md

@@ -88,8 +88,9 @@ DTALite uses arrays rather than STL containers to store columns. These arrays ar
 32. Fully optimize the C++ routing engine (v0.9.1)
 33. Use the UE result as routing decisions for simulation (v0.9.1)
 34. Optimize the column generation module with faster and better UE convergency (v0.9.2)
-35. Resolve the potential issue on traversing the last through node in path engine (v0.9.2)
-36. Fix the bug on loading columns where link path and node paths are not in the proper order (v0.9.2)
+35. Fix the bug on updating the total system travel time (v0.9.2)
+36. Resolve the potential issue on traversing the last through node in path engine (v0.9.2)
+37. Fix the bug on loading columns where link path and node paths are not in the proper order (v0.9.2)
 
 Detailed update information can be found in [Releases](https://github.com/jdlph/Path4GMNS/releases).
 
@@ -103,7 +104,7 @@ You are encouraged to join our [Discord Channel](https://discord.gg/JGFMta7kxZ)
 
 ## How to Cite
 
-Li, P. and Zhou, X. (2023, February 11). *Path4GMNS*. Retrieved from https://github.com/jdlph/Path4GMNS
+Li, P. and Zhou, X. (2023, March 14). *Path4GMNS*. Retrieved from https://github.com/jdlph/Path4GMNS
 
 ## References
 Lu, C. C., Mahmassani, H. S., Zhou, X. (2009). Equivalent gap function-based reformulation and solution algorithm for the dynamic user equilibrium problem. Transportation Research Part B: Methodological, 43, 345-364.

docs/source/usecases.md

@@ -154,11 +154,14 @@ print('shortest path (link id) of agent, '
 pg.output_agent_paths(network)
 ```
 
-v0.7.2 or higher features finding agent paths under a specific mode defined in settings.yaml. The following example demonstrates this new functionality under mode walk (i.e., w).
+v0.7.2 or higher features finding agent paths under a specific mode defined in settings.yml. The following example demonstrates this new functionality under mode walk (i.e., w).
 ```python
 import path4gmns as pg
 
-network = pg.read_network(load_demand=True)
+network = pg.read_network()
+pg.read_zones(network)
+pg.load_demand(network)
+
 network.find_path_for_agents()
 
 # or equivalently network.find_path_for_agents('walk')
@@ -502,7 +505,7 @@ simulation:
   resolution: 6
 ```
 
-perform_column_generation() must be called in the first place to set up path for each agent before simulation.
+perform_column_generation() shall be called in the first place to set up path for each agent before simulation.
 
 ```Python
 import path4gmns as pg
@@ -522,6 +525,26 @@ print('writing agent trajectories')
 pg.output_agent_trajectory(network)
 ```
 
+If you have agent.csv (i.e.columns) from a previous run or DTALite, you can bypass perform_column_generation() and directly load it to conduct simulation.
+
+
+```python
+import path4gmns as pg
+
+network = pg.read_network()
+pg.read_zones(network)
+pg.load_demand(network)
+
+# load existing UE result
+pg.load_columns(network)
+# DTA
+pg.perform_simple_simulation(network)
+print('complete dynamic simulation.\n')
+
+print('writing agent trajectories')
+pg.output_agent_trajectory(network)
+```
+
 The original implementation introduced in v0.9.0 (that each agent follows the shortest path from origin to destination) has been disabled. If you are still interested in traffic simulation using shortest paths, it can be achieved by setting column_gen_num as 1 and column_update_num as 0 illustrated below.
 
 ```Python

tests/demo.py

@@ -220,12 +220,12 @@ def test_loading_synthesized_zones_demand():
 def test_simulation():
     network = pg.read_network(load_demand=True)
 
-    # network.find_path_for_agents()
-
     column_gen_num = 10
     column_update_num = 10
     pg.perform_column_generation(column_gen_num, column_update_num, network)
 
+    # you can bypass the above perform_column_generation() and call
+    # load_columns(network) if you have agent.csv
     # pg.load_columns(network)
     pg.perform_simple_simulation(network, 'uniform')
     print('complete simple simulation.\n')

tests/tutorial.ipynb

@@ -178,6 +178,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "stuffed-roman",
    "metadata": {},
@@ -186,7 +187,7 @@
     "\n",
     "Agents are disaggregated demand using the aggregated travel demand between each OD pair, which is specified in demand.csv. Individual agents will be automatically set up via find_path_for_agents() on its first call.\n",
     "\n",
-    "You will need both **demand.csv** and **zone.csv** to proceed. As our sample data sets **DO NOT have zone.csv**, please go through the following step to synthesize zones and OD demand matrix in the first place. Note that it will overwrite any existing zone.csv and demand.csv if you have them."
+    "You will need both **demand.csv** and **zone.csv** to proceed. As our sample data sets **DO NOT have zone.csv**, please go through the following step to synthesize zones and OD demand matrix in the first place. Note that it will **OVERWRITE** any existing zone.csv and demand.csv if you have them."
    ]
   },
   {
@@ -574,6 +575,39 @@
     "pg.output_agent_trajectory(network)"
    ]
   },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "56045828",
+   "metadata": {},
+   "source": [
+    "If you have agent.csv (i.e., columns) from a previous run or DTALite, you can bypass perform_column_generation() and directly load it to conduct simulation."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2653b889",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "\n",
+    "import path4gmns as pg\n",
+    "\n",
+    "network = pg.read_network()\n",
+    "pg.read_zones(network)\n",
+    "pg.load_demand(network)\n",
+    "\n",
+    "# load existing UE result\n",
+    "pg.load_columns(network)\n",
+    "# DTA\n",
+    "pg.perform_simple_simulation(network)\n",
+    "print('complete dynamic simulation.\\n')\n",
+    "\n",
+    "print('writing agent trajectories')\n",
+    "pg.output_agent_trajectory(network)\n"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "signed-marsh",