{"id":13423657,"url":"https://github.com/torressa/cspy","last_synced_at":"2025-07-03T00:05:07.894Z","repository":{"id":34943814,"uuid":"184283304","full_name":"torressa/cspy","owner":"torressa","description":"A collection of algorithms for the (Resource) Constrained Shortest Path problem in Python / C++ / C#","archived":false,"fork":false,"pushed_at":"2024-06-10T12:47:27.000Z","size":15355,"stargazers_count":86,"open_issues_count":22,"forks_count":26,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-06-27T01:07:22.826Z","etag":null,"topics":["bidirectional-labeling-algorithm","csp-problem","operations-research","optimization","optimization-algorithms","optimization-library","resource-constrained-shortest-path"],"latest_commit_sha":null,"homepage":"https://torressa.github.io/cspy/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/torressa.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-04-30T15:03:43.000Z","updated_at":"2025-06-26T13:19:53.000Z","dependencies_parsed_at":"2022-08-08T03:00:59.230Z","dependency_job_id":"27e1261f-572f-4453-9ae0-a29283da0009","html_url":"https://github.com/torressa/cspy","commit_stats":{"total_commits":382,"total_committers":10,"mean_commits":38.2,"dds":0.4869109947643979,"last_synced_commit":"bfe0b105d91a0eb0247aef98f3105953fff99277"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/torressa/cspy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/torressa%2Fcspy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/torressa%2Fcspy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/torressa%2Fcspy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/torressa%2Fcspy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/torressa","download_url":"https://codeload.github.com/torressa/cspy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/torressa%2Fcspy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262347480,"owners_count":23296895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bidirectional-labeling-algorithm","csp-problem","operations-research","optimization","optimization-algorithms","optimization-library","resource-constrained-shortest-path"],"created_at":"2024-07-31T00:00:39.974Z","updated_at":"2025-07-03T00:05:07.729Z","avatar_url":"https://github.com/torressa.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"| OS     | C++ | Python | Dotnet |\n|:-------|-----|--------|--------|\n| Unix (linux + macos) | [![Status][cpp_unix_svg]][cpp_unix_link] | [![Status][python_unix_svg]][python_unix_link]| [![Status][dotnet_unix_svg]][dotnet_unix_link] |\n| Windows  | [![Status][cpp_win_svg]][cpp_win_link] | [![Status][python_win_svg]][python_win_link] |[![Status][dotnet_win_svg]][dotnet_win_link] |\n\n\n[cpp_unix_svg]: https://github.com/torressa/cspy/workflows/Cpp/badge.svg\n[cpp_unix_link]: https://github.com/torressa/cspy/actions?query=workflow%3A%22Cpp%22\n[python_unix_svg]: https://github.com/torressa/cspy/workflows/Python/badge.svg\n[python_unix_link]: https://github.com/torressa/cspy/actions?query=workflow%3A%22Python%22\n[dotnet_unix_svg]: https://github.com/torressa/cspy/workflows/Dotnet/badge.svg\n[dotnet_unix_link]: https://github.com/torressa/cspy/actions?query=workflow%3A%22Dotnet%22\n\n[cpp_win_svg]: https://github.com/torressa/cspy/workflows/Windows%20Cpp/badge.svg\n[cpp_win_link]: https://github.com/torressa/cspy/actions?query=workflow%3A%22Windows+Cpp%22\n[python_win_svg]: https://github.com/torressa/cspy/workflows/Windows%20Python/badge.svg\n[python_win_link]: https://github.com/torressa/cspy/actions?query=workflow%3A%22Windows+Python%22\n[dotnet_win_svg]: https://github.com/torressa/cspy/workflows/Windows%20Dotnet/badge.svg\n[dotnet_win_link]: https://github.com/torressa/cspy/actions?query=workflow%3A%22Windows+Dotnet%22\n\n[![PyPI version](https://badge.fury.io/py/cspy.svg)](https://badge.fury.io/py/cspy)\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/c28f50e92dae4bcc921f1bd142370608)](https://www.codacy.com/app/torressa/cspy?utm_source=github.com\u0026utm_medium=referral\u0026utm_content=torressa/cspy\u0026utm_campaign=Badge_Grade)\n[![JOSS badge](https://joss.theoj.org/papers/25eda55801a528b982d03a6a61f7730d/status.svg)](https://joss.theoj.org/papers/25eda55801a528b982d03a6a61f7730d)\n\n\n# cspy\n\nA collection of algorithms for the (resource) Constrained Shortest Path (CSP) problem.\n\nDocumentation [here](https://torressa.github.io/cspy/).\n\nThe CSP problem was popularised by [Inrich and Desaulniers (2005)](https://www.researchgate.net/publication/227142556_Shortest_Path_Problems_with_Resource_Constraints). It was initially introduced as a subproblem for the bus driver scheduling problem, and has since then widely studied in a variety of different settings including: the vehicle routing problem with time windows (VRPTW), the technician routing and scheduling problem, the capacitated arc-routing problem, on-demand transportation systems, and, airport ground movement; among others.\n\nMore generally, in the applied column generation framework, particularly in the scheduling related literature, the CSP problem is commonly employed to generate columns.\n\nTherefore, this library is of interest to the operational research community, students and academics alike, that wish to solve an instance of the CSP problem.\n\n## Algorithms\n\nCurrently, the exact and metaheuristic algorithms implemented include:\n\n- [x] Bidirectional labeling algorithm with dynamic halfway point (exact) (also monodirectional) [Tilk et al. (2017)](https://www.sciencedirect.com/science/article/pii/S0377221717302035);\n- [x] Heuristic Tabu search (metaheuristic);\n- [x] Greedy elimination procedure (metaheuristic);\n- [x] Greedy Randomised Adaptive Search Procedure (GRASP) (metaheuristic). Adapted from [Ferone et al. (2019)](https://www.tandfonline.com/doi/full/10.1080/10556788.2018.1548015);\n- [x] Particle Swarm Optimization with combined Local and Global Expanding Neighborhood Topology (PSOLGENT) (metaheuristic) [Marinakis et al. (2017)](https://www.sciencedirect.com/science/article/pii/S0377221717302357).\n\nPlease see the [docs](https://cspy.readthedocs.io/en/latest/index.html) for individual algorithms Python or C++ API documentation, as well as some toy examples and further details.\n\n\n- [Bidirectional and monodirectional algorithms](https://torressa.github.io/cspy/python_api/cspy.BiDirectional.html)\n- [Heuristic Tabu Search](https://torressa.github.io/cspy/python_api/cspy.Tabu.html)\n- [Greedy Elimination Procedure](https://torressa.github.io/cspy/python_api/cspy.GreedyElim.html)\n- [GRASP](https://torressa.github.io/cspy/python_api/cspy.GRASP.html)\n- [PSOLGENT](https://torressa.github.io/cspy/python_api/cspy.PSOLGENT.html)\n\n## Getting Started\n\n### Prerequisites\n\nConceptual background and input formatting is discussed in the [docs](https://torressa.github.io/cspy/how_to.html).\n\nModule dependencies are:\n\n- [NetworkX](https://networkx.github.io/documentation/stable/)\n- [NumPy](https://docs.scipy.org/doc/numpy/reference/)\n\nNote that [requirements.txt](requirements.txt) contains modules for development purposes.\n\n### Installing\n\nInstalling the `cspy` package with `pip` should also install all the required packages. You can do this by running the following command in your terminal\n\n```none\npip install cspy\n```\n\nor\n\n```none\npython3 -m pip install cspy\n```\n\n### Quick start\n\n#### Python\n\n```python\n# Imports\nfrom cspy import BiDirectional\nfrom networkx import DiGraph\nfrom numpy import array\n\nmax_res, min_res = [4, 20], [1, 0]\n# Create a DiGraph\nG = DiGraph(directed=True, n_res=2)\nG.add_edge(\"Source\", \"A\", res_cost=[1, 2], weight=0)\nG.add_edge(\"A\", \"B\", res_cost=[1, 0.3], weight=0)\nG.add_edge(\"A\", \"C\", res_cost=[1, 0.1], weight=0)\nG.add_edge(\"B\", \"C\", res_cost=[1, 3], weight=-10)\nG.add_edge(\"B\", \"Sink\", res_cost=[1, 2], weight=10)\nG.add_edge(\"C\", \"Sink\", res_cost=[1, 10], weight=0)\n\n# init algorithm\nbidirec = BiDirectional(G, max_res, min_res)\n\n# Call and query attributes\nbidirec.run()\nprint(bidirec.path)\nprint(bidirec.total_cost)\nprint(bidirec.consumed_resources)\n```\n\nFor more details see the [Python API](https://cspy.readthedocs.io/en/latest/python_api/cspy.BiDirectional.html)\n\n#### Cpp\n\n```cpp\n#include \"bidirectional.h\"\n\nnamespace bidirectional {\n\nvoid wrap() {\n  // Init\n  const std::vector\u003cdouble\u003e max_res         = {4.0, 20.0};\n  const std::vector\u003cdouble\u003e min_res         = {1.0, 0.0};\n  const int                 number_vertices = 5;\n  const int                 number_edges    = 5;\n  auto                      bidirectional   = std::make_unique\u003cBiDirectional\u003e(\n      number_vertices, number_edges, 0, 4, max_res, min_res);\n\n  // Populate graph\n  bidirectional-\u003eaddNodes({0, 1, 2, 3, 4});\n  bidirectional-\u003eaddEdge(0, 1, 0.0, {1, 2});\n  bidirectional-\u003eaddEdge(1, 2, 0.0, {1, 0.3});\n  bidirectional-\u003eaddEdge(2, 3, -10.0, {1, 3});\n  bidirectional-\u003eaddEdge(2, 4, 10.0, {1, 2});\n  bidirectional-\u003eaddEdge(3, 4, 0.0, {1, 10});\n\n  // Run and query attributes\n  bidirectional-\u003erun();\n\n  auto path = bidirectional-\u003egetPath();\n  auto res  = bidirectional-\u003egetConsumedResources();\n  auto cost = bidirectional-\u003egetTotalCost();\n}\n\n} // namespace bidirectional\n```\n\n#### C#\n\n```csharp\nDoubleVector max_res = new DoubleVector(new List\u003cdouble\u003e() {4.0, 20.0});\nDoubleVector min_res = new DoubleVector(new List\u003cdouble\u003e() {0.0, 0.0});\nint number_vertices = 5;\nint number_edges = 5;\nBiDirectionalCpp alg = new BiDirectionalCpp(number_vertices, number_edges, 0, 4, max_res, min_res);\n\n// Populate graph\nalg.addNodes(new IntVector(new List\u003cint\u003e() {0, 1, 2, 3, 4}));\nalg.addEdge(0, 1, -1.0, new DoubleVector(new List\u003cdouble\u003e() {1, 2}));\nalg.addEdge(1, 2, -1.0, new DoubleVector(new List\u003cdouble\u003e() {1, 0.3}));\nalg.addEdge(2, 3, -10.0, new DoubleVector(new List\u003cdouble\u003e() {1, 3}));\nalg.addEdge(2, 4, 10.0, new DoubleVector(new List\u003cdouble\u003e() {1, 2}));\nalg.addEdge(3, 4, -1.0, new DoubleVector(new List\u003cdouble\u003e() {1, 10}));\nalg.setDirection(\"forward\");\n\n// Run and query attributes\nalg.run();\n\nIntVector path = alg.getPath();\nDoubleVector res = alg.getConsumedResources();\ndouble cost = alg.getTotalCost();\n```\n\n### Examples\n\n- [`vrpy`](https://github.com/Kuifje02/vrpy) : External vehicle routing framework which uses `cspy` to solve different variants of the vehicle routing problem using column generation. Particulatly, see  [`subproblem_cspy.py`](https://github.com/Kuifje02/vrpy/blob/master/vrpy/subproblem_cspy.py).\n- [`jpath`](examples/jpath) : Simple example showing the necessary graph adptations and the use of custom resource extension functions.\n\n\n## Building\n\n### Docker\n\nUsing docker, docker-compose is the easiest way.\n\nTo run the tests first, clone the repository into a path in your machine `~/path/newfolder` by running\n\n```none\ngit clone https://github.com/torressa/cspy.git ~/path/newfolder\n```\n\n#### Running the Cpp tests\n\n```\ncd ~/path/newfolder/tools/dev\n./build\n```\n\n#### Running the Python tests\n\n```\ncd ~/path/newfolder/tools/dev\n./build -c -p\n```\n\n### Locally\n\nRequirements:\n\n- [CMake](https://cmake.org/download/) (\u003e=v3.14)\n- Standard C++ toolchain\n- Python (\u003e=3.6)\n\nThen use the wrapper [`Makefile`](Makefile) e.g. `make` in the root dir runs the unit tests\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details.\n\n## Contributing\n\n### Issues\n\nIf you find a bug or there are some improvements you'd like to see (e.g. more algorithms), please raise a new issue with a clear explanation.\n\n### Contributing to the Software\n\nWhen contributing to this repository, please first discuss the change you wish to make via an issue or email.\nAfter that feel free to send a pull request.\n\n#### Pull Request Process\n\n- If necessary, please perform documentation updates where appropriate (e.g. README.md, docs and [CHANGELOG.md](CHANGELOG.md)).\n- Increase the version numbers and reference the changes appropriately. Note that the versioning scheme used is based on [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n- Wait for approval for merging.\n\n### Seeking Support\n\nIf you have a question or need help, feel free to raise an issue explaining it.\n\nAlternatively, email me at `torressa at tutanota.com`.\n\n## Citing\n\nIf you'd like to cite this package, please use the following bib format:\n\n```none\n@article{torressa2020,\n  doi = {10.21105/joss.01655},\n  url = {https://doi.org/10.21105/joss.01655},\n  year = {2020},\n  publisher = {The Open Journal},\n  volume = {5},\n  number = {49},\n  pages = {1655},\n  author = {{Torres Sanchez}, David},\n  title = {cspy: A Python package with a collection of algorithms for the\n    (Resource) Constrained Shortest Path problem},\n  journal = {Journal of Open Source Software}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftorressa%2Fcspy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftorressa%2Fcspy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftorressa%2Fcspy/lists"}