topolib 0.8.0__tar.gz

topolib-0.8.0/LICENSE

@@ -0,0 +1,22 @@
+
+MIT License
+
+Copyright (c) 2025 Danilo Bórquez-Paredes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

topolib-0.8.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: topolib
+Version: 0.8.0
+Summary: A compact Python library for modeling, analyzing, and visualizing optical network topologies.
+License: MIT
+License-File: LICENSE
+Keywords: network,topology,optical,analysis,visualization
+Author: Danilo Bórquez-Paredes
+Author-email: danilo.borquez.p@uai.cl
+Requires-Python: >=3.10
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: PyQt6 (>=6.0)
+Requires-Dist: PyQt6-WebEngine (>=6.0)
+Requires-Dist: folium (>=0.14.0)
+Requires-Dist: jsonschema (>=4.0)
+Requires-Dist: networkx (>=2.6)
+Requires-Dist: numpy (>=1.21)
+Project-URL: Documentation, https://topolib.readthedocs.io/
+Project-URL: Homepage, https://gitlab.com/DaniloBorquez/topolib
+Project-URL: Repository, https://gitlab.com/DaniloBorquez/topolib
+Description-Content-Type: text/markdown
+
+# Topolib 🚀
+
+[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-lightgrey.svg)](LICENSE)
+[![Issues](https://img.shields.io/badge/issues-on%20GitLab-blue.svg)](https://gitlab.com/DaniloBorquez/topolib/-/issues)
+[![Develop coverage](https://gitlab.com/DaniloBorquez/topolib/badges/develop/coverage.svg)](https://gitlab.com/DaniloBorquez/topolib/-/pipelines?ref=develop)
+[![Release coverage](https://gitlab.com/DaniloBorquez/topolib/badges/release/coverage.svg)](https://gitlab.com/DaniloBorquez/topolib/-/pipelines?ref=release)
+[![Documentation Status](https://readthedocs.org/projects/topolib/badge/?version=latest)](https://topolib.readthedocs.io/en/latest/?badge=latest)
+
+> **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/`](examples/) folder!
+
+- [Show topology on a map](examples/show_topology_in_map.py) 🗺️
+- [Show default topology in map](examples/show_default_topology_in_map.py) 🗺️
+- [Export topology as PNG](examples/export_topology_png.py) 🖼️
+- [Export topology to CSV and JSON](examples/export_csv_json.py) 📄
+- [Export topology and k-shortest paths for FlexNetSim](examples/export_flexnetsim.py) 🔀
+- [Generate traffic demand matrices](examples/traffic_matrices.py) 📊
+
+---
+
+## 🧭 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, DC/IXP, distribution probability)
+- Returns NumPy arrays for efficient mathematical operations
+- Interactive map visualization with Folium and PyQt6
+- Clean PNG export without external dependencies (no Selenium required)
+- Resource caching for faster map rendering
+- JSON import/export and interoperability
+- Ready for Sphinx, Read the Docs, and PyPI
+
+---
+
+## ⚡ Quickstart
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install topolib
+```
+
+---
+
+## 📚 Documentation
+
+Full documentation: [https://topolib.readthedocs.io/](https://topolib.readthedocs.io/)
+
+---
+
+## 📝 Basic usage
+
+### Creating a topology
+
+```python
+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
+
+```python
+from topolib.topology import Topology
+from topolib.analysis import TrafficMatrix
+
+# Load a topology
+topo = Topology.load_default_topology("DT-14")
+
+# 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")
+```
+
+---
+
+## 🛠️ Development
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development guidelines, commit message rules, and pre-commit setup.
+
+---
+
+## 📄 License
+
+MIT — see [`LICENSE`](LICENSE) for details.
+

topolib-0.8.0/README.md

@@ -0,0 +1,115 @@
+# Topolib 🚀
+
+[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-lightgrey.svg)](LICENSE)
+[![Issues](https://img.shields.io/badge/issues-on%20GitLab-blue.svg)](https://gitlab.com/DaniloBorquez/topolib/-/issues)
+[![Develop coverage](https://gitlab.com/DaniloBorquez/topolib/badges/develop/coverage.svg)](https://gitlab.com/DaniloBorquez/topolib/-/pipelines?ref=develop)
+[![Release coverage](https://gitlab.com/DaniloBorquez/topolib/badges/release/coverage.svg)](https://gitlab.com/DaniloBorquez/topolib/-/pipelines?ref=release)
+[![Documentation Status](https://readthedocs.org/projects/topolib/badge/?version=latest)](https://topolib.readthedocs.io/en/latest/?badge=latest)
+
+> **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/`](examples/) folder!
+
+- [Show topology on a map](examples/show_topology_in_map.py) 🗺️
+- [Show default topology in map](examples/show_default_topology_in_map.py) 🗺️
+- [Export topology as PNG](examples/export_topology_png.py) 🖼️
+- [Export topology to CSV and JSON](examples/export_csv_json.py) 📄
+- [Export topology and k-shortest paths for FlexNetSim](examples/export_flexnetsim.py) 🔀
+- [Generate traffic demand matrices](examples/traffic_matrices.py) 📊
+
+---
+
+## 🧭 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, DC/IXP, distribution probability)
+- Returns NumPy arrays for efficient mathematical operations
+- Interactive map visualization with Folium and PyQt6
+- Clean PNG export without external dependencies (no Selenium required)
+- Resource caching for faster map rendering
+- JSON import/export and interoperability
+- Ready for Sphinx, Read the Docs, and PyPI
+
+---
+
+## ⚡ Quickstart
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -U pip
+pip install topolib
+```
+
+---
+
+## 📚 Documentation
+
+Full documentation: [https://topolib.readthedocs.io/](https://topolib.readthedocs.io/)
+
+---
+
+## 📝 Basic usage
+
+### Creating a topology
+
+```python
+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
+
+```python
+from topolib.topology import Topology
+from topolib.analysis import TrafficMatrix
+
+# Load a topology
+topo = Topology.load_default_topology("DT-14")
+
+# 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")
+```
+
+---
+
+## 🛠️ Development
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development guidelines, commit message rules, and pre-commit setup.
+
+---
+
+## 📄 License
+
+MIT — see [`LICENSE`](LICENSE) for details.

topolib-0.8.0/pyproject.toml

@@ -0,0 +1,49 @@
+
+[tool.poetry]
+name = "topolib"
+# Poetry requires a version field, but poetry-dynamic-versioning will override it
+version = "0.8.0"
+description = "A compact Python library for modeling, analyzing, and visualizing optical network topologies."
+authors = ["Danilo Bórquez-Paredes <danilo.borquez.p@uai.cl>"]
+license = "MIT"
+readme = "README.md"
+repository = "https://gitlab.com/DaniloBorquez/topolib"
+documentation = "https://topolib.readthedocs.io/"
+homepage = "https://gitlab.com/DaniloBorquez/topolib"
+keywords = ["network", "topology", "optical", "analysis", "visualization"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Topic :: Software Development :: Libraries :: Python Modules"
+]
+packages = [
+    { include = "topolib" }
+]
+
+[tool.poetry.dependencies]
+python = ">=3.10"
+numpy = ">=1.21"
+networkx = ">=2.6"
+folium = ">=0.14.0"
+jsonschema = ">=4.0"
+PyQt6 = ">=6.0"
+PyQt6-WebEngine = ">=6.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "*"
+pytest-cov = "*"
+PyQt6 = ">=6.0"
+PyQt6-WebEngine = ">=6.0"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry-dynamic-versioning]
+enable = false
+vcs = "git"
+style = "pep440"
+pattern = '(?P<base>\d+\.\d+\.\d+)'
+

topolib-0.8.0/topolib/__init__.py

@@ -0,0 +1,4 @@
+try:
+    from ._version import __version__
+except ImportError:
+    __version__ = "unknown"

topolib-0.8.0/topolib/analysis/__init__.py

@@ -0,0 +1,4 @@
+from .metrics import Metrics
+from .traffic_matrix import TrafficMatrix
+
+__all__ = ["Metrics", "TrafficMatrix"]

topolib-0.8.0/topolib/analysis/metrics.py

@@ -0,0 +1,80 @@
+"""
+Metrics module for network topology analysis.
+"""
+
+from typing import List, Dict, Optional
+
+
+from topolib.topology import Topology
+
+
+class Metrics:
+    """
+    Provides static methods for computing metrics on network topologies.
+
+    All methods receive a Topology instance.
+
+    Methods
+    -------
+    node_degree(topology)
+        Calculates the degree of each node.
+    link_length_stats(topology)
+        Calculates statistics (min, max, avg) of link lengths.
+    connection_matrix(topology)
+        Builds the adjacency matrix.
+    """
+
+    @staticmethod
+    def node_degree(topology: "Topology") -> Dict[int, int]:
+        """
+        Calculates the degree of each node in the topology.
+
+        :param topology: Instance of topolib.topology.topology.Topology.
+        :type topology: topolib.topology.topology.Topology
+        :return: Dictionary {node_id: degree}
+        :rtype: dict[int, int]
+        """
+        degree = {n.id: 0 for n in topology.nodes}
+        for link in topology.links:
+            degree[link.source.id] += 1
+            degree[link.target.id] += 1
+        return degree
+
+    @staticmethod
+    def link_length_stats(topology: "Topology") -> Dict[str, Optional[float]]:
+        """
+        Calculates the minimum, maximum, and average link lengths.
+
+        :param topology: Instance of topolib.topology.topology.Topology.
+        :type topology: topolib.topology.topology.Topology
+        :return: Dictionary with keys 'min', 'max', 'avg'.
+        :rtype: dict[str, float | None]
+        """
+        lengths = [l.length for l in topology.links]
+        if not lengths:
+            return {"min": None, "max": None, "avg": None}
+        return {
+            "min": min(lengths),
+            "max": max(lengths),
+            "avg": sum(lengths) / len(lengths),
+        }
+
+    @staticmethod
+    def connection_matrix(topology: "Topology") -> List[List[int]]:
+        """
+        Builds the adjacency matrix of the topology.
+
+        :param topology: Instance of topolib.topology.topology.Topology.
+        :type topology: topolib.topology.topology.Topology
+        :return: Adjacency matrix (1 if connected, 0 otherwise).
+        :rtype: list[list[int]]
+        """
+        id_to_idx = {n.id: i for i, n in enumerate(topology.nodes)}
+        size = len(topology.nodes)
+        matrix = [[0] * size for _ in range(size)]
+        for link in topology.links:
+            i = id_to_idx[link.source.id]
+            j = id_to_idx[link.target.id]
+            matrix[i][j] = 1
+            matrix[j][i] = 1
+        return matrix