do not include path geometry info by default

- change the default value of output_geometry in output_columns()
  from True to False;
- update the tutorial and use cases accordingly;
- add docstring to find_ue_fw() in fw.py;
- change the version number from v0.9.10 to v0.10.0 in README.md and
  conf.py;
- add find_ue_fw() to the API doc;
- update pytest.yml to install pyyaml before running tests.

Author: jdlph

.github/workflows/pytest.yml

@@ -25,6 +25,7 @@ jobs:
           pip install -e .
           pip install pytest
           pip install requests
+          pip install pyyaml
       - name: Run Pytest
         run: |
           pytest tests/

README.md

@@ -1,16 +1,16 @@
 # Path4GMNS
 [![platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-red)](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-red)
-[![Downloads](https://static.pepy.tech/badge/path4gmns)](https://pepy.tech/project/path4gmns) [![GitHub release](https://img.shields.io/badge/release-v0.9.10-brightgreen)](https://img.shields.io/badge/release-v0.8.2-brightgreen) ![Read the Docs](https://img.shields.io/readthedocs/path4gmns)
+[![Downloads](https://static.pepy.tech/badge/path4gmns)](https://pepy.tech/project/path4gmns) [![GitHub release](https://img.shields.io/badge/release-v0.10.0-brightgreen)](https://img.shields.io/badge/release-v0.8.2-brightgreen) ![Read the Docs](https://img.shields.io/readthedocs/path4gmns)
 [![](https://dcbadge.limes.pink/api/server/https://discord.gg/JGFMta7kxZ?style=flat)](https://discord.gg/JGFMta7kxZ)
 
 Path4GMNS is an open-source, cross-platform, lightweight, and fast Python path engine for networks encoded in [GMNS](https://github.com/zephyr-data-specs/GMNS). Besides finding static shortest paths for simple analyses, its main functionality is to provide an efficient and flexible framework for column-based (path-based) modeling and applications in transportation (e.g., activity-based demand modeling). Path4GMNS supports, in short,
 
 1. finding (static) shortest path between two nodes,
-2. performing path-based User-Equilibrium (UE) traffic assignment,
+2. performing either path-based or link-based User-Equilibrium (UE) traffic assignment,
 3. conducting dynamic traffic assignment (DTA) after UE.
 4. evaluating multimodal accessibility and equity,
 5. making the Origin-Destination (OD) demand matrix estimation (ODME),
-6. synthesizing zones and Origin-Destination (OD) demand.
+6. synthesizing zones and OD demand.
 
 Path4GMNS also serves as an API to the C++-based [DTALite](https://github.com/jdlph/DTALite) to conduct various multimodal traffic assignments including,
    * Link-based UE,
@@ -29,13 +29,13 @@ Path4GMNS also serves as an API to the C++-based [DTALite](https://github.com/jd
 We highly recommend that you go through the above [Tutorial](https://github.com/jdlph/Path4GMNS/blob/master/tutorial/tutorial.ipynb), no matter you are one of the existing users or new to Path4GMNS.
 
 ## Installation
-Path4GMNS has been published on [PyPI](https://pypi.org/project/path4gmns/0.9.10/), and can be installed using
+Path4GMNS has been published on [PyPI](https://pypi.org/project/path4gmns/0.10.0/), and can be installed using
 ```
 $ pip install path4gmns
 ```
 
 > [!IMPORTANT]
-> 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**.
+> v0.10.0 introduces the link-based UE that adopts the Frank-Wolfe algorithm with line search. As it does not preserve any paths, each iteration runs faster than the path-based procedure with less memory footprint. Please **discard all old versions**.
 
 > [!WARNING]
 > 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.

docs/source/api.rst

@@ -31,7 +31,12 @@ path4gmns.conduct_odme
 path4gmns.colgen
 ================
 .. autofunction:: path4gmns.colgen.find_ue
-  
+
+
+path4gmns.fw
+============
+.. autofunction:: path4gmns.fw.find_ue_fw
+
 
 path4gmns.io
 ============

docs/source/conf.py

@@ -28,7 +28,7 @@
 author = 'Dr. Peiheng Li and Dr. Xuesong (Simon) Zhou'
 
 # The full version, including alpha/beta/rc tags
-release = 'v0.9.10.post1'
+release = 'v0.10.0'
 
 
 # -- General configuration ---------------------------------------------------
@@ -76,4 +76,4 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ['_static']

docs/source/index.rst

@@ -15,11 +15,11 @@ applications in transportation (e.g., activity-based demand modeling).
 Path4GMNS supports, in short,
 
 1. finding (static) shortest path between two nodes,
-2. performing path-based User-Equilibrium (UE) traffic assignment,
+2. performing either path-based or link-based User-Equilibrium (UE) traffic assignment,
 3. conducting dynamic traffic assignment (DTA) after UE.
 4. evaluating multimodal accessibility and equity,
 5. making the Origin-Destination (OD) demand matrix estimation (ODME),
-6. synthesizing zones and Origin-Destination (OD) demand.
+6. synthesizing zones and OD demand.
 
 Path4GMNS also serves as an API to the C++-based
 `DTALite <https://github.com/jdlph/DTALite>`_ to conduct various multimodal

docs/source/installation.rst

@@ -2,17 +2,17 @@
 Installation
 ============
 
-Path4GMNS has been published on `PyPI <https://pypi.org/project/path4gmns/0.9.10/>`_, and can be installed using
+Path4GMNS has been published on `PyPI <https://pypi.org/project/path4gmns/0.10.0/>`_, and can be installed using
 
 .. code-block:: bash
 
     $ pip install path4gmns
 
-If you need a specific version of Path4GMNS, say, 0.9.10,
+If you need a specific version of Path4GMNS, say, 0.10.0,
 
 .. code-block:: bash
 
-    $ pip install path4gmns==0.9.10
+    $ pip install path4gmns==0.10.0
 
 
 Dependency

docs/source/usecases.md

@@ -123,7 +123,7 @@ 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 
+# get shortest path tree (in link sequences) from node 1
 # cost is measured by distance (in miles)
 sp_tree_link = network.get_shortest_path_tree(1, seq_type='link', cost_type='distance')
 # retrieve the shortest path from the source node (i.e., node 1) to node 2
@@ -213,8 +213,8 @@ column_upd_num = 20
 rel_gap = pg.find_ue(network, column_gen_num, column_upd_num, rel_gap_tolerance = 0.001)
 print(f'the final relative UE gap is {rel_gap:.4%}')
 
-# if you do not want to include geometry info in the output file,
-# use pg.output_columns(network, False)
+# if you want to include path geometry info in the output file,
+# use pg.output_columns(network, True)
 pg.output_columns(network)
 pg.output_link_performance(network)
 ```

path4gmns/fw.py

@@ -172,6 +172,37 @@ def _init_sys_tt(demand_period_count):
 
 
 def find_ue_fw(ui, max_iter = 40, rel_gap_tolerance=1e-04):
+    """ find user equilibrium (UE) with the Frank-Wolfe Algorithm
+
+    WARNING
+    -------
+    It does not preserve any paths/columns during the assignment process.
+    If you need paths/columns (in route_assignment.csv), please use the
+    path-based UE module: find_ue().
+
+    Parameters
+    ----------
+    ui
+        network object generated by pg.read_network()
+
+    max_iter
+        maximum number of iterations to be performed on finding UE. Default is 40.
+
+    rel_gap_tolerance
+        target relative gap. find_ue_fw() stops when either max_iter or
+        rel_gap_tolerance is reached.
+
+    Returns
+    -------
+    rel_gap
+        relative GAP to measure the UE convergency
+
+    Note
+    ----
+    You will need to call output_link_performance() toget the assignment
+    results, i.e., volumes and other link attributes on each link (in
+    link_performance.csv).
+    """
     # base assignment
     A = ui._base_assignment
     # set up SPNetwork
@@ -181,7 +212,7 @@ def find_ue_fw(ui, max_iter = 40, rel_gap_tolerance=1e-04):
     links = A.get_links()
     demand_period_count = A.get_demand_period_count()
 
-    print('find user equilibrium (UE) using Frank-Wolfe Algorithm\n')
+    print('find user equilibrium (UE) using the Frank-Wolfe Algorithm\n')
     st = time()
 
     # initialization

path4gmns/io.py

@@ -866,7 +866,7 @@ def load_columns(ui, input_dir='.'):
         update_links_using_columns(ui)
 
 
-def output_columns(ui, output_geometry=True, output_dir='.'):
+def output_columns(ui, output_geometry=False, output_dir='.'):
     with open(output_dir+'/route_assignment.csv', 'w',  newline='') as fp:
         base = ui._base_assignment
 

tutorial/tutorial.ipynb

@@ -346,8 +346,8 @@
     "rel_gap = pg.find_ue(network, column_gen_num, column_upd_num, rel_gap_tolerance = 0.001)\n",
     "print(f'the final relative UE gap is {rel_gap:.4%}')\n",
     "\n",
-    "# if you do not want to include geometry info in the output file,\n",
-    "# use pg.output_columns(network, False)\n",
+    "# if you want to include path geometry info in the output file,\n",
+    "# use pg.output_columns(network, True)\n",
     "pg.output_columns(network)\n",
     "pg.output_link_performance(network)"
    ]