diff --git a/README.md b/README.md index bfdb319..aabd946 100644 --- a/README.md +++ b/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. diff --git a/docs/source/api.rst b/docs/source/api.rst index e5670eb..e4c92a4 100644 --- a/docs/source/api.rst +++ b/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 diff --git a/docs/source/conf.py b/docs/source/conf.py index a74cd0a..08a0067 100644 --- a/docs/source/conf.py +++ b/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 --------------------------------------------------- diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 50a9100..50c3b88 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst @@ -2,17 +2,17 @@ Installation ============ -Path4GMNS has been published on `PyPI `_, and can be installed using +Path4GMNS has been published on `PyPI `_, 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. \ No newline at end of file +Here, 0.9.7 is the version number. Replace it with the one specified in setup.py. \ No newline at end of file diff --git a/docs/source/usecases.md b/docs/source/usecases.md index b1834f0..bc859b2 100644 --- a/docs/source/usecases.md +++ b/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: diff --git a/path4gmns/dtaapi.py b/path4gmns/dtaapi.py index 4863d13..77c1db0 100644 --- a/path4gmns/dtaapi.py +++ b/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()