fix potential issues of calling DTALite

- move setup of _dtalite_engine and _dtalitemm_engine within their
  callers respectively to avoid the execution of DTALite on the initial
  loading of Path4GMNS and generation of the log files;
- remove input_dir from the arg list of _emit_log() but add log_file
  with its default value as 'log_main.txt', update run_DTALite()
  accordingly;
- update README and docs.

Author: jdlph

README.md

@@ -1,6 +1,6 @@
 # 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.6-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.9.7-brightgreen)](https://img.shields.io/badge/release-v0.8.2-brightgreen) ![Read the Docs](https://img.shields.io/readthedocs/path4gmns)
 
 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,
 
@@ -19,15 +19,16 @@ Path4GMNS also serves as an API to the C++-based [DTALite](https://github.com/jd
 ![Architecture](/docs/source/imgs/architecture.png)
 
 ## Installation
-Path4GMNS has been published on [PyPI](https://pypi.org/project/path4gmns/0.9.6/), and can be installed using
+Path4GMNS has been published on [PyPI](https://pypi.org/project/path4gmns/0.9.7/), and can be installed using
 ```
 $ pip install path4gmns
 ```
 
-v0.9.6 improves the assignment results by eliminating ultra-low-volume paths and computes the final UE convergency after the postprocessing. Please **update to or install the latest version** and **discard all old versions**.
+v0.9.7 serves as a hotfix over v0.9.5 and v0.9.6 on emitting DTALite log and synthesizing zone and demand. Please **update to or install the latest version** and **discard all old versions**.
 
 > [!WARNING]
 > Any versions prior to v0.9.4 will generate INCORRECT simulation results.
+> Calling DTALite and [synthesizing zones and OD demand are not functioning for v0.9.5 and v0.9.6](https://github.com/jdlph/Path4GMNS/issues/41).
 
 ### Dependency
 The Python modules are written in **Python 3.x**, which is the minimum requirement to explore the most of Path4GMNS. Some of its functions require further run-time support, which we will go through along with the corresponding **[Use Cases](https://path4gmns.readthedocs.io/en/latest/)**.
@@ -36,6 +37,14 @@ The Python modules are written in **Python 3.x**, which is the minimum requireme
 
  We highly recommend that you go through this **[Tutorial](https://github.com/jdlph/Path4GMNS/tree/dev/tests/tutorial.ipynb)** written in Jupyter notebook with step-by-step demonstration using the latest version, no matter you are one of the existing users or new to Path4GMNS. Its documentation is available on **[readthedocs](https://path4gmns.readthedocs.io/en/latest/)**.
 
+## Please Contribute
+
+Any contributions are welcomed including advise new applications of Path4GMNS, enhance documentation and [docstrings](https://docs.python-guide.org/writing/documentation/#writing-docstrings) in the source code, refactor and/or optimize the source code, report and/or resolve potential issues/bugs, suggest and/or add new functionalities, etc.
+
+Path4GMNS has a very simple workflow setup, i.e., **master for release (on both GitHub and PyPI)** and **dev for development**. If you would like to work directly on the source code (and probably the documentation), please make sure that **the destination branch of your pull request is dev**, i.e., all potential changes/updates shall go to the dev branch before merging into master for release.
+
+You are encouraged to join our [Discord Channel](https://discord.gg/JGFMta7kxZ) for the latest update and more discussions.
+
 ## Implementation Notes
 
 The column generation scheme in Path4GMNS is an equivalent **single-processing implementation** as its [DTALite](https://github.com/jdlph/DTALite/tree/main/src_cpp) multiprocessing counterpart. **Note that** the results (i.e., column pool and trajectory for each agent) from Path4GMNS and DTALite are comparable but likely not identical as the shortest paths are usually not unique and subjected to implementations. This difference shall be subtle and the link performances shall be consistent if the iterations of column generation and column update are both large enough. You can always compare the results (i.e., link_performance.csv) from Path4GMNS and DTALite given the same network and demand.
@@ -102,20 +111,13 @@ DTALite uses arrays rather than STL containers to store columns. These arrays ar
 48. Eliminate ultra-low-volume columns from assignment (v0.9.6)
 49. Calculate and print out the final UE convergency after the postprocessing (v0.9.6)
 50. Embed and support the latest [DTALite](https://github.com/asu-trans-ai-lab/DTALite) in addition to the existing [classic version](https://github.com/jdlph/DTALite) (v0.9.6)
+51. Complete update 47 introduced in v0.9.5 (v0.9.7)
 
 Detailed update information can be found in [Releases](https://github.com/jdlph/Path4GMNS/releases).
 
-## Please Contribute
-
-Any contributions are welcomed including advise new applications of Path4GMNS, enhance documentation (this guideline and [docstrings](https://docs.python-guide.org/writing/documentation/#writing-docstrings) in the source code), refactor and/or optimize the source code, report and/or resolve potential issues/bugs, suggest and/or add new functionalities, etc.
-
-Path4GMNS has a very simple workflow setup, i.e., **master for release (on both GitHub and PyPI)** and **dev for development**. If you would like to work directly on the source code (and probably the documentation), please make sure that **the destination branch of your pull request is dev**, i.e., all potential changes/updates shall go to the dev branch before merging into master for release.
-
-You are encouraged to join our [Discord Channel](https://discord.gg/JGFMta7kxZ) for the latest update and more discussions.
-
 ## How to Cite
 
-Li, P. and Zhou, X. (2023, September 7). *Path4GMNS*. Retrieved from https://github.com/jdlph/Path4GMNS
+Li, P. and Zhou, X. (2023, September 13). *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](https://www.sciencedirect.com/science/article/abs/pii/S0191261508000829). Transportation Research Part B: Methodological, 43, 345-364.

docs/source/api.rst

@@ -24,6 +24,7 @@ path4gmns.colgen
 path4gmns.dtaapi
 ================
 .. autofunction:: path4gmns.dtaapi.perform_network_assignment_DTALite
+.. autofunction:: path4gmns.dtaapi.run_DTALite
 
 
 path4gmns.simulation

docs/source/conf.py

@@ -26,7 +26,7 @@
 author = 'Dr. Peiheng Li and Dr. Xuesong (Simon) Zhou'
 
 # The full version, including alpha/beta/rc tags
-release = 'v0.9.6'
+release = 'v0.9.7'
 
 
 # -- General configuration ---------------------------------------------------

docs/source/installation.rst

@@ -2,17 +2,17 @@
 Installation
 ============
 
-Path4GMNS has been published on `PyPI <https://pypi.org/project/path4gmns/0.9.6/>`_, and can be installed using
+Path4GMNS has been published on `PyPI <https://pypi.org/project/path4gmns/0.9.7/>`_, and can be installed using
 
 .. code-block:: bash
 
     $ pip install path4gmns
 
-If you need a specific version of Path4GMNS, say, 0.9.6,
+If you need a specific version of Path4GMNS, say, 0.9.7,
 
 .. code-block:: bash
 
-    $ pip install path4gmns==0.9.6
+    $ pip install path4gmns==0.9.7
 
 
 Dependency
@@ -55,7 +55,7 @@ As CMAKE_BUILD_TYPE will be IGNORED for IDE (Integrated Development Environment)
     # from the root directory of PATH4GMNS
     $ python setup.py sdist bdist_wheel
     $ cd dist
-    # or python -m pip install path4gmns-0.9.6.tar.gz
-    $ python -m pip instal pypath4gmns-0.9.6-py3-none-any.whl
+    # or python -m pip install path4gmns-0.9.7.tar.gz
+    $ python -m pip instal pypath4gmns-0.9.7-py3-none-any.whl
 
-Here, 0.9.6 is the version number. Replace it with the one specified in setup.py.
+Here, 0.9.7 is the version number. Replace it with the one specified in setup.py.

docs/source/usecases.md

@@ -160,7 +160,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. 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 now 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:
@@ -407,7 +407,7 @@ Traffic simulation is to capture/mimic the traffic evolution over time through s
 
 The traffic simulation module in Path4GMNS is a mesoscopic simulator using the point queue model and the routing decision of each individual agent (as disaggregated demand). The routing decisions are from the UE traffic assignment.
 
-The demand loading profile with respect to the departure times of all agents is either constant (start time of the selected demand period) or random (within the selected demand period). The future release will introduce a linear or piece-wise linear loading profile. v0.9.0 only supports one demand period, which must be specified in settings.yml and be corresponding to one from the list of demand_periods. The default simulation resolution is 6 seconds. In other words, a simulation interval is 6 seconds.
+The demand loading profile with respect to the departure times of all agents is either constant (start time of the selected demand period) or random (within the selected demand period). The future release will introduce a linear or piece-wise linear loading profile. Path4GMNS only supports one demand period, which must be specified in settings.yml and be corresponding to one from the list of demand_periods. If you need the multi-demand-period support, please use DTALite or [TransOMS](https://github.com/jdlph/TransOMS). The default simulation resolution is 6 seconds. In other words, a simulation interval is 6 seconds.
 
 ```yaml
 agents:

path4gmns/dtaapi.py

@@ -27,17 +27,9 @@
     raise Exception('Please build the shared library compatible to your OS\
                     using source files')
 
-_dtalite_engine = ctypes.cdll.LoadLibrary(_dtalite_dll)
-_dtalitemm_engine = ctypes.cdll.LoadLibrary(_dtalitemm_dll)
 
-
-_dtalite_engine.network_assignment.argtypes = [ctypes.c_int,
-                                               ctypes.c_int,
-                                               ctypes.c_int]
-
-
-def _emit_log(input_dir='.'):
-    with open(input_dir + '/log_DTA.txt', 'r') as fp:
+def _emit_log(log_file='log_main.txt'):
+    with open(log_file, 'r') as fp:
         for line in fp:
             print(line)
 
@@ -97,6 +89,12 @@ def perform_network_assignment_DTALite(assignment_mode,
     assert(column_gen_num>=0)
     assert(column_update_num>=0)
 
+    _dtalite_engine = ctypes.cdll.LoadLibrary(_dtalite_dll)
+    _dtalite_engine.network_assignment.argtypes = [ctypes.c_int,
+                                                   ctypes.c_int,
+                                                   ctypes.c_int]
+
+
     print('\nDTALite run starts\n')
 
     if _os.startswith('Windows'):
@@ -141,8 +139,8 @@ def perform_network_assignment_DTALite(assignment_mode,
 def run_DTALite():
     """ Python interface to call the latest DTALite
 
-    This version of DTALite includes all-new Logbook, enhanced scenarios
-    handling, improved I/O functionality, and so on.
+    This version of DTALite includes all-new Logbook, enhanced scenario handling,
+    improved I/O functionality, and so on.
 
     Its source code can be found at https://github.com/asu-trans-ai-lab/DTALite.
 
@@ -162,10 +160,11 @@ def run_DTALite():
     Run it only with data sets from
     https://github.com/asu-trans-ai-lab/DTALite/tree/main/dataset_v1.
     """
+    _dtalitemm_engine = ctypes.cdll.LoadLibrary(_dtalitemm_dll)
     print('\nDTALite run starts\n')
 
     proc_dta = Process(target=_dtalitemm_engine.DTALiteAPI())
-    proc_print = Process(target=_emit_log)
+    proc_print = Process(target=_emit_log,  args='log_DTA.txt')
 
     proc_dta.start()
     proc_dta.join()