Topolib 🚀

Topolib is a compact, modular Python library for modeling, analyzing, and visualizing optical network topologies.
Goal: Provide researchers and engineers with a simple, extensible toolkit for working with nodes, links, metrics, and map-based visualizations.

🌐 Model | 📊 Analyze | 🗺️ Visualize | 🧩 Extend

📂 Examples

Explore ready-to-run usage examples in the examples/ folder!

• Jupyter Notebook - Complete Example 📓 ⭐ NEW! Interactive example showing all features
• Show topology on a map 🗺️
• Show default topology in map 🗺️
• Show node IDs on map 🔢 ⭐ NEW! Display node IDs for easy identification
• Export topology as PNG 🖼️
• Export topology in paper format 📄
• Work with adjacency matrices 📊
• Export topology to CSV and JSON 📄
• Download topology CSV files directly from the documentation (no Python required) 📥
• Export topology and k-shortest paths for FlexNetSim 🔀
• Generate traffic demand matrices 📊
• Generate homogeneous and heterogeneous multi-period traffic matrices 📈

🧭 Overview

Topolib is organized into four main modules:

• 🧱 Elements: Node, Link — basic building blocks
• 🕸️ Topology: Topology, Path — manage nodes, links, paths, and adjacency
• 📈 Analysis: Metrics, TrafficMatrix — compute node degree, link stats, connection matrices, and traffic demand matrices
• 🖼️ Visualization: MapView — interactive maps with Folium and PyQt6, clean PNG exports

✨ Features

• Modular, extensible design
• Easy-to-use classes for nodes, links, and paths
• Built-in metrics and analysis helpers
• Traffic demand matrix generation with three models (gravitational, MPT, RAM)
• Homogeneous and heterogeneous multi-period traffic growth projections
• Returns NumPy arrays for efficient mathematical operations
• Interactive map visualization with Folium and PyQt6
• Clean PNG export without external dependencies (no Selenium required)
• Paper format export with white background for academic publications
• Resource caching for faster map rendering
• JSON import/export and interoperability
• 60+ built-in topologies available as downloadable CSV files from the Topology Repository (no Python environment required)
• Fully compatible with Jupyter Notebook - Folium maps display inline for interactive analysis
• Ready for Sphinx, Read the Docs, and PyPI

⚡ Quickstart

python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install topolib

📚 Documentation

Full documentation: https://topolib.readthedocs.io/

📝 Basic usage

Creating a topology

from topolib.elements.node import Node
from topolib.topology.topology import Topology

n1 = Node(1, 'A', 10.0, 20.0)
n2 = Node(2, 'B', 11.0, 21.0)
topo = Topology(nodes=[n1, n2])
# Add links, compute metrics, visualize, etc.

Generating traffic matrices

from topolib.topology import Topology
from topolib.analysis import TrafficMatrix

# Load a topology
topo = Topology.load_default_topology("Germany-14nodes")

# Generate traffic matrix using gravitational model
matrix = TrafficMatrix.gravitational(topo, rate=0.015)
# Returns NumPy array: matrix[i, j] = traffic from node i to j (Gbps)

# Export to CSV
TrafficMatrix.to_csv(matrix, topo, "traffic_matrix.csv")

# Export to JSON (list of demands with src, dst, required fields)
TrafficMatrix.to_json(matrix, topo, "traffic_matrix.json")

Multi-period traffic growth

from topolib.analysis import TrafficMatrix

# Homogeneous growth: the whole network uses the same growth distribution
matrices = TrafficMatrix.multiperiod(
    matrix,
    num_periods=10,
    base_growth_rate=0.10,
    random_variation=0.02,
    seed=42,
)

# Heterogeneous growth: selected matrix nodes can use different distributions
heterogeneous = TrafficMatrix.multiperiod_heterogeneous(
    matrix,
    num_periods=10,
    default_growth={"distribution": "fixed", "value": 0.0},
    node_growth={
        2: {"distribution": "normal", "mean": 0.30, "variance": 0.0009},
        5: {"distribution": "fixed", "value": -0.10},
    },
    direction="outgoing",
    seed=42,
)

node_growth keys are matrix indices, not topology IDs. With direction="outgoing", node 2 scales matrix[2, :], affecting traffic from that node to all destinations. Negative growth is allowed; traffic is clipped at zero.

🛠️ Development

See CONTRIBUTING.md for development guidelines, commit message rules, and pre-commit setup.

� Acknowledgments

Topolib builds upon excellent open-source projects:

Core Dependencies:

• NumPy (BSD-3-Clause) — numerical computing
• NetworkX (BSD-3-Clause) — graph analysis
• SciPy (BSD-3-Clause) — scientific computing
• Folium (MIT) — interactive maps
• jsonschema (MIT) — JSON validation

Visualization:

• PyQt6 (GPL-3.0/Commercial) — used optionally for interactive map windows and PNG export
• OpenStreetMap — map tiles © OpenStreetMap contributors, licensed under the Open Database License (ODbL)

All dependencies are compatible with Topolib's MIT license. PyQt6 is used only for optional interactive visualization features and is not required for core topology modeling and analysis functionality.

�📄 License

MIT — see LICENSE for details.