path4gmns 0.10.0

An open-source, cross-platform, lightweight, and fast Python path engine for networks encoded in GMNS

Path4GMNS

Path4GMNS is an open-source, cross-platform, lightweight, and fast Python path engine for networks encoded in 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 paths,
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 OD demand.

Path4GMNS also serves as an API to the C++-based DTALite to conduct various multimodal traffic assignments including,

• Link-based UE,
• Path-based UE,
• UE + DTA,
• ODME.

Quick Start

1. Tutorial written in Jupyter notebook with step-by-step demonstration.
2. Documentation on Installation, Use Cases, Public API, and more.
3. OpenDTA on the C++ equivalent.

We highly recommend that you go through the above Tutorial, no matter you are one of the existing users or new to Path4GMNS.

Installation

Path4GMNS has been published on PyPI, and can be installed using

$ pip install path4gmns

[!IMPORTANT] 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. Besides, it fixes potential issues of invoking DTALite. 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 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 ... for v0.9.9 and any version before.

[!CAUTION] Any version prior to v0.9.4 will generate INCORRECT simulation results.

[!CAUTION] Calling DTALite and synthesizing zones and OD demand are not functioning for v0.9.5 and v0.9.6.

[!CAUTION] Zone and demand synthesis is PROBLEMATIC for any version before v0.9.9.

[!NOTE] ODME is available with v0.9.9 and higher.

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.

How to Cite

Li, P. and Zhou, X. (2025, December 15). Path4GMNS. Retrieved from https://github.com/jdlph/Path4GMNS

Please Contribute

Any contributions are welcomed including advise new applications of Path4GMNS, enhance documentation and 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 for the latest update and more discussions.

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.

Jayakrishnan, R., Tsai, W. K., Prashker, J. N., Rajadyaksha, S. (1994). A Faster Path-Based Algorithm for Traffic Assignment (Working Paper UCTC No. 191). The University of California Transportation Center.

Bertsekas, D., Gafni, E. (1983). Projected Newton methods and optimization of multicommodity flows. IEEE Transactions on Automatic Control, 28(12), 1090–1096.