Welcome to JanuX. Routing starts here.

Janus, the Roman god of beginnings, transitions and duality, is known for his two faces. In Roman mythology, he symbolizes direction, beginnings, ends and contrasts.

---

JanuX is not a Roman god, but it is a robust yet simple tool for generating a set of path options in directed NetworkX graphs. It is designed for efficient routing or creating path options for custom requirements.

---

Installation

JanuX works with Python 3.6+.

• Install from PyPI:

pip install janux

• Or install from source:

git clone https://github.com/COeXISTENCE-PROJECT/JanuX.git
cd JanuX
pip install -r requirements.txt
pip install -e .

---

Repository Layout

JanuX/
|-- janux/                         
|   |-- graph_builders/            build directed graphs from SUMO network files
|   |-- path_generators/           path generators, wrappers, and helper utilities
|   |-- visualizers/               plotting and animation tools
|   |-- utils.py                   shared helpers
|-- examples/
|   |-- network_files/             sample SUMO networks and OD data for Cologne, Csomor, and Ingolstadt
|   |-- path_generation_examples/  runnable path-generation scripts
|   |-- visualization_examples/    runnable plotting and animation scripts
|-- graphics/                      docs assets
|-- pyproject.toml                 package metadata and build configuration
|-- requirements.txt               dependency list for source installs
|-- CITATION.cff                   citation metadata
|-- LICENSE.txt                    MIT license
|-- README.md                      project overview, installation, and usage notes

---

Path Generators

The janux/path_generators package includes four route-generation strategies:

Generator	Best for	What it adds
basic_generator	getting started with candidate route sampling	logit-style probabilistic path generation
extended_generator	adding more control to sampled routes	loop handling, path-length limits, and adaptive parameter shifting
heuristic_generator	choosing route sets with custom criteria	scores sampled route sets with user-defined heuristics and weights
clustering_generator	building structurally distinct alternatives	avoids repeated road segments and junction revisits, and can favor less similar routes

All generators share a similar interface and can return either raw route sets or DataFrame outputs, with optional free-flow travel times.

---

Usage

Here is a minimal example using extended_generator:

import janux as jx

network = jx.build_digraph(
    "path/to/network.con.xml",
    "path/to/network.edg.xml",
    "path/to/network.rou.xml",
)

origins = ["origin_edge_id"]
destinations = ["destination_edge_id"]

routes = jx.extended_generator(
    network,
    origins,
    destinations,
    as_df=True,
    calc_free_flow=True,
    number_of_paths=3,
    num_samples=300,
    beta=-3,
    adaptive=True,
)

print(routes[["origins", "destinations", "path"]].head())

This returns a pandas DataFrame with origins, destinations, path, and optionally free_flow_time. Set as_df=False if you prefer the raw route dictionary instead. For a fuller runnable example using the bundled sample networks, see extended_example.py.

---

Examples

Two small scripts are a good starting point:

Path generation:

python examples/path_generation_examples/basic_example.py

• Builds a sample network, generates multiple candidate paths for each origin-destination pair, saves the routes as CSV, and can also write route plots to examples/figures/.

Visualization:

python examples/visualization_examples/single_route_visualization.py

• Draws one route on top of a sample network and saves the figure to examples/figures/.

Both scripts use the sample files in examples/network_files/, so they should run directly after installing the package.

Gallery

---

---

JanuX appears in

    

JanuX supports RouteRL and URB, with accompanying papers in SoftwareX and NeurIPS.

---

Citation

If you use this repository, please cite it using the following BibTeX:

@software{JanuX,
  author = {Akman, Ahmet Onur and Torbus, Błażej},
  title = {{JanuX}},
  doi = {https://doi.org/10.5281/zenodo.17422816},
  url = {https://github.com/COeXISTENCE-PROJECT/JanuX},
  version = {1.1.0},
  month = may,
  year = {2026}
}