topolib 0.3.0__py3-none-any.whl

elements/link.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from topolib.elements.node import Node
+
+
+class Link:
+
+    """
+    .. :noindex:
+
+    Represents a link between two nodes.
+
+    Parameters
+    ----------
+    id : int
+        Unique identifier for the link.
+    source : :class:`topolib.elements.node.Node`
+        Source node-like object (must have id, name, latitude, longitude).
+    target : :class:`topolib.elements.node.Node`
+        Target node-like object (must have id, name, latitude, longitude).
+    length : float
+        Length of the link (must be non-negative).
+
+    Attributes
+    ----------
+    id : int
+        Unique identifier for the link.
+    source : :class:`topolib.elements.node.Node`
+        Source node of the link.
+    target : :class:`topolib.elements.node.Node`
+        Target node of the link.
+    length : float
+        Length of the link.
+
+    Examples
+    --------
+    >>> link = Link(1, nodeA, nodeB, 10.5)
+    >>> link.length
+    """
+
+    def __init__(self, id: int, source: "Node", target: "Node", length: float):
+        self._id = id
+        self.source = source
+        self.target = target
+        self.length = length
+
+    @property
+    def id(self) -> int:
+        """
+        .. :noindex:
+
+        int: Unique identifier for the link.
+        """
+        return self._id
+
+    @id.setter
+    def id(self, value: int) -> None:
+        """
+        Set the link's unique identifier.
+        """
+        self._id = value
+
+    @property
+    def source(self) -> "Node":
+        """
+        .. :noindex:
+
+        :class:`topolib.elements.node.Node`: Source node of the link.
+        """
+        return self._source
+
+    @source.setter
+    def source(self, value: "Node") -> None:
+        """
+        Set the source node. Must have id, name, latitude, longitude.
+        """
+        required_attrs = ("id", "name", "latitude", "longitude")
+        for attr in required_attrs:
+            if not hasattr(value, attr):
+                raise TypeError(
+                    f"source must behave like a Node (missing {attr})")
+        self._source = value
+
+    @property
+    def target(self) -> "Node":
+        """
+        .. :noindex:
+
+        :class:`topolib.elements.node.Node`: Target node of the link.
+        """
+        return self._target
+
+    @target.setter
+    def target(self, value: "Node") -> None:
+        """
+        Set the target node. Must have id, name, latitude, longitude.
+        """
+        required_attrs = ("id", "name", "latitude", "longitude")
+        for attr in required_attrs:
+            if not hasattr(value, attr):
+                raise TypeError(
+                    f"target must behave like a Node (missing {attr})")
+        self._target = value
+
+    @property
+    def length(self) -> float:
+        """
+        .. :noindex:
+
+        float: Length of the link (non-negative).
+        """
+        return self._length
+
+    @length.setter
+    def length(self, value: float) -> None:
+        """
+        Set the length of the link. Must be a non-negative float.
+        """
+        try:
+            numeric = float(value)
+        except Exception:
+            raise TypeError("length must be a numeric value")
+        if numeric < 0:
+            raise ValueError("length must be non-negative")
+        self._length = numeric
+
+    def endpoints(self):
+        """
+        Return the (source, target) nodes as a tuple.
+
+        Returns
+        -------
+        tuple
+            (source_node, target_node)
+        """
+        return self._source, self._target
+
+    def __repr__(self) -> str:
+        """
+        Return a string representation of the Link.
+        """
+        return f"Link(id={self._id}, source={self._source.id}, target={self._target.id}, length={self._length})"

elements/node.py

@@ -0,0 +1,119 @@
+"""
+Node class for optical network topologies.
+
+This module defines the Node class, representing a network node with geographic coordinates.
+"""
+
+from typing import Tuple
+
+
+class Node:
+    """
+    .. :noindex:
+
+    Represents a node in an optical network topology.
+
+    :param id: Unique identifier for the node.
+    :type id: int
+    :param name: Name of the node.
+    :type name: str
+    :param latitude: Latitude coordinate of the node.
+    :type latitude: float
+    :param longitude: Longitude coordinate of the node.
+    :type longitude: float
+    """
+
+    def __init__(self, id: int, name: str, latitude: float, longitude: float):
+        self._id = id
+        self._name = name
+        self._latitude = latitude
+        self._longitude = longitude
+
+    @property
+    def id(self) -> int:
+        """
+        Get the unique identifier of the node.
+
+        :return: Node ID.
+        :rtype: int
+        """
+        return self._id
+
+    @id.setter
+    def id(self, value: int) -> None:
+        """
+        Set the unique identifier of the node.
+
+        :param value: Node ID.
+        :type value: int
+        """
+        self._id = value
+
+    @property
+    def name(self) -> str:
+        """
+        Get the name of the node.
+
+        :return: Node name.
+        :rtype: str
+        """
+        return self._name
+
+    @name.setter
+    def name(self, value: str) -> None:
+        """
+        Set the name of the node.
+
+        :param value: Node name.
+        :type value: str
+        """
+        self._name = value
+
+    @property
+    def latitude(self) -> float:
+        """
+        Get the latitude coordinate of the node.
+
+        :return: Latitude value.
+        :rtype: float
+        """
+        return self._latitude
+
+    @latitude.setter
+    def latitude(self, value: float) -> None:
+        """
+        Set the latitude coordinate of the node.
+
+        :param value: Latitude value.
+        :type value: float
+        """
+        self._latitude = value
+
+    @property
+    def longitude(self) -> float:
+        """
+        Get the longitude coordinate of the node.
+
+        :return: Longitude value.
+        :rtype: float
+        """
+        return self._longitude
+
+    @longitude.setter
+    def longitude(self, value: float) -> None:
+        """
+        Set the longitude coordinate of the node.
+
+        :param value: Longitude value.
+        :type value: float
+        """
+        self._longitude = value
+
+    def coordinates(self) -> Tuple[float, float]:
+        """
+        Returns the (latitude, longitude) coordinates of the node.
+
+        :return: Tuple containing latitude and longitude.
+        :rtype: Tuple[float, float]
+        """
+        return self._latitude, self._longitude

topolib-0.3.0.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: topolib
+Version: 0.3.0
+Summary: A compact Python library for modeling, analyzing, and visualizing optical network topologies.
+Author-email: Danilo Bórquez-Paredes <danilo.borquez.p@uai.cl>
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.com/DaniloBorquez/topolib
+Project-URL: Documentation, https://topolib.readthedocs.io/
+Project-URL: Source, https://gitlab.com/DaniloBorquez/topolib
+Project-URL: Issues, https://gitlab.com/DaniloBorquez/topolib/-/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: networkx>=2.6
+Dynamic: license-file
+
+# 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)
+
+A compact Python library for working with optical network topologies: nodes, links, metrics and visualization tools. 🌐
+
+## Overview
+
+Topolib models network topologies with three main modules:
+
+- `topolib.elements` — Definitions of elementary building blocks
+  - `Node` — represents a network node with id, name and geographic coordinates
+  - `Link` — connects two `Node` objects and stores link length and id
+
+- `topolib.topology` — High-level topology model
+  - `Topology` — holds nodes and links, provides methods to add/remove nodes and links, compute metrics, export JSON, and compute shortest/disjoint paths
+  - `Path` — represents a path through the topology
+
+- `topolib.analysis` — Metrics and analysis helpers
+  - `Metrics` — functions to compute node degree, link length statistics, connection matrices, etc.
+
+- `topolib.visualization` — Visualization helpers
+  - `MapView` — functions to display topology with OSM or paper-style maps
+
+(These components are derived from the project's class diagram in `diagrams/class_diagram.puml`.)
+
+## Features
+- Modular design: elements, topology, analysis, and visualization
+- Easy-to-use classes for nodes, links, and paths
+- Built-in metrics and analysis helpers
+- JSON import/export and interoperability
+- Ready for Sphinx, Read the Docs, and PyPI
+
+## Quickstart ⚡
+
+Create and activate a virtual environment, install dev dependencies and run tests:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -U pip
+python -m pip install -r dev-requirements.txt
+python -m pytest -q
+```
+
+## Installation
+
+```bash
+pip install topolib
+```
+
+Or for development:
+
+```bash
+git clone https://gitlab.com/DaniloBorquez/topolib.git
+cd topolib
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+pip install -r dev-requirements.txt
+```
+
+## Documentation
+
+Full documentation: [https://topolib.readthedocs.io/](https://topolib.readthedocs.io/)
+
+## Basic usage example
+
+```py
+from topolib.elements.node import Node
+from topolib.topology.topology import Topology
+
+# Create nodes
+n1 = Node(1, 'A', 10.0, 20.0)
+n2 = Node(2, 'B', 11.0, 21.0)
+
+# Build topology
+topo = Topology()
+topo.add_node(n1)
+topo.add_node(n2)
+# add links, compute metrics, visualize
+```
+
+
+## Development 🛠️
+
+See `CONTRIBUTING.md` for development guidelines, commit message rules and pre-commit setup.
+
+
+
+## Class diagram
+
+![](diagrams/class_diagram.puml)
+
+(If you prefer a rendered image of the UML, render the PlantUML file locally or in your CI pipeline.)
+
+## License
+
+See `LICENSE` in the project root.

topolib-0.3.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+analysis/__init__.py,sha256=qvUC9wV_jQNQIlwJXk7LJ-dkTXhH1Ttn0lKWIdwBbrc,52
+analysis/metrics.py,sha256=Di4HGHlz9c2UTCYdfnmjtPjo7w3wwYuyDPeXI7bR0zA,2592
+assets/DT14.json,sha256=eG7Yz7kIMSov3bWAlSBsA9dXpq7MZRN8IZF20OVg2Wc,7543
+assets/DT17.json,sha256=oC-5yxJpONqomYVMxLIeEf39UpPTAxUc3yDH9sVjot4,8505
+assets/FRANCE-43.json,sha256=NCb2NJnQv4dq7PAbjJQfdunE1JJRn3G2xFKEJzkHaMo,21918
+assets/JPN-12.json,sha256=IYGerYCjUsaYie2vSOpDwXR-hwT40fJJ4axeKAhCtBY,5377
+assets/NSFNet.json,sha256=_uiuG3_6RnjafsIZbg0-QoZFMtMmrSLIGQUTI5WaGzY,6888
+assets/PLN-12.json,sha256=zxmWnSONK6cR2SFB_cG92Mgts7lhXQWvx6V_KQkrXsI,5995
+assets/UKNet.json,sha256=TurrVnx6pa3IgpZYJziOUJlXIIPS5RalmMI5DgRX7dQ,11911
+elements/__init__.py,sha256=ZWSd5uwVtppJtMnZ30zrAdzXhUAYIK62RrUaH9rsWu0,180
+elements/link.py,sha256=BwjdCR8peh7dDpKunZodlIsjKcfvwjKxyQ3tmp1obb8,3778
+elements/node.py,sha256=zIzKm1_dlEqOuNQbNc-R3NOWHytk0Tn6jMLWIoV7ENk,2704
+topolib-0.3.0.dist-info/licenses/LICENSE,sha256=kbnIP0XU6f2ualiTjEawdlU81IGPBbwc-_GF3N-1e9E,1081
+topology/__init__.py,sha256=2VRhVm4ZvKBiTDB2T8BDmLZBpwGCVFRF3fvtxxC_d28,86
+topology/path.py,sha256=oUNwmpBcS6LMMAJIxokROm3MVqr7vRR44M3Fh5ADq_w,2057
+topology/topology.py,sha256=5aeIahfPEGAK01chEka21slkhg4D_hb7apMZpRn-VOg,4168
+topolib-0.3.0.dist-info/METADATA,sha256=T8UctAUpqw_jzfwbOkkAuyrxUj3PY8HesdFd6pfyGfw,4294
+topolib-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+topolib-0.3.0.dist-info/top_level.txt,sha256=lyqPH1vGGLmvT7EaqN4in6QtMnjU1WVHMbD3AselI2o,34
+topolib-0.3.0.dist-info/RECORD,,

topolib-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

topolib-0.3.0.dist-info/licenses/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.3.0.dist-info/top_level.txt

@@ -0,0 +1,4 @@
+analysis
+assets
+elements
+topology

topology/__init__.py

@@ -0,0 +1,4 @@
+from .path import Path
+from .topology import Topology
+
+__all__ = ["Path", "Topology"]

topology/path.py

@@ -0,0 +1,84 @@
+"""
+Path class for representing a sequence of nodes and links in a topology.
+"""
+
+from typing import List, Any
+
+
+class Path:
+    """
+    Represents a path through the network topology as an ordered sequence of nodes and links.
+
+    Parameters
+    ----------
+    nodes : list
+        Ordered list of node objects in the path.
+    links : list
+        Ordered list of link objects in the path (len(links) == len(nodes) - 1).
+
+    Raises
+    ------
+    ValueError
+        If the number of nodes and links is inconsistent or empty.
+
+    Attributes
+    ----------
+    nodes : list
+        Ordered list of nodes in the path.
+    links : list
+        Ordered list of links in the path.
+
+    Examples
+    --------
+    >>> nodes = [Node(1), Node(2), Node(3)]
+    >>> links = [Link('a'), Link('b')]
+    >>> path = Path(nodes, links)
+    >>> path.length()
+    2
+    >>> path.endpoints()
+    (Node(1), Node(3))
+    """
+
+    def __init__(self, nodes: List[Any], links: List[Any]):
+        if not nodes or not links:
+            raise ValueError("A path must have at least one node and one link.")
+        if len(nodes) != len(links) + 1:
+            raise ValueError("Number of nodes must be one more than number of links.")
+        self.nodes = nodes
+        self.links = links
+
+    def length(self) -> int:
+        """
+        Return the number of links in the path.
+
+        Returns
+        -------
+        int
+            Number of links in the path.
+        """
+        return len(self.links)
+
+    def hop_count(self) -> int:
+        """
+        Return the number of hops (links) in the path.
+
+        Returns
+        -------
+        int
+            Number of hops (links) in the path.
+        """
+        return self.length()
+
+    def endpoints(self):
+        """
+        Return the source and target nodes of the path as a tuple.
+
+        Returns
+        -------
+        tuple
+            (source_node, target_node)
+        """
+        return (self.nodes[0], self.nodes[-1])
+
+    def __repr__(self):
+        return f"Path(nodes={self.nodes}, links={self.links})"

topology/topology.py

@@ -0,0 +1,126 @@
+"""
+Topology class for optical network topologies.
+
+This module defines the Topology class, representing a network topology with nodes and links,
+and providing an adjacency matrix using numpy.
+
+This file uses NetworkX (BSD 3-Clause License):
+https://github.com/networkx/networkx/blob/main/LICENSE.txt
+"""
+
+from typing import List, Dict, Any
+import numpy as np
+import networkx as nx
+from topolib.elements.node import Node
+from topolib.elements.link import Link
+
+
+class Topology:
+    """
+    Represents a network topology with nodes and links.
+
+    :param nodes: Initial list of nodes (optional).
+    :type nodes: list[topolib.elements.node.Node] or None
+    :param links: Initial list of links (optional).
+    :type links: list[topolib.elements.link.Link] or None
+
+    :ivar nodes: List of nodes in the topology.
+    :vartype nodes: list[Node]
+    :ivar links: List of links in the topology.
+    :vartype links: list[Link]
+
+    **Examples**
+        >>> from topolib.elements.node import Node
+        >>> from topolib.elements.link import Link
+        >>> from topolib.topology import Topology
+        >>> n1 = Node(1, "A", 0.0, 0.0)
+        >>> n2 = Node(2, "B", 1.0, 1.0)
+        >>> l1 = Link(1, n1, n2, 10.0)
+        >>> topo = Topology(nodes=[n1, n2], links=[l1])
+        >>> topo.adjacency_matrix()
+        array([[0, 1],
+               [1, 0]])
+    """
+
+    def __init__(self, nodes: List[Node] = None, links: List[Link] = None):
+        """
+        Initialize a Topology object.
+
+    :param nodes: Initial list of nodes (optional).
+    :type nodes: list[topolib.elements.node.Node] or None
+    :param links: Initial list of links (optional).
+    :type links: list[topolib.elements.link.Link] or None
+        """
+        self.nodes: List[Node] = nodes if nodes is not None else []
+        self.links: List[Link] = links if links is not None else []
+        # Internal NetworkX graph for algorithms and visualization
+        self._graph = nx.Graph()
+        for node in self.nodes:
+            self._graph.add_node(node.id, node=node)
+        for link in self.links:
+            self._graph.add_edge(link.source.id, link.target.id, link=link)
+
+    def add_node(self, node: Node) -> None:
+        """
+        Add a node to the topology.
+
+        :param node: Node to add.
+        :type node: Node
+        """
+        self.nodes.append(node)
+        self._graph.add_node(node.id, node=node)
+
+    def add_link(self, link: Link) -> None:
+        """
+        Add a link to the topology.
+
+        :param link: Link to add.
+        :type link: Link
+        """
+        self.links.append(link)
+        self._graph.add_edge(link.source.id, link.target.id, link=link)
+
+    def remove_node(self, node_id: int) -> None:
+        """
+        Remove a node and all its links by node id.
+
+        :param node_id: ID of the node to remove.
+        :type node_id: int
+        """
+        self.nodes = [n for n in self.nodes if n.id != node_id]
+        self.links = [
+            l for l in self.links if l.source.id != node_id and l.target.id != node_id
+        ]
+        self._graph.remove_node(node_id)
+
+    def remove_link(self, link_id: int) -> None:
+        """
+        Remove a link by its id.
+
+        :param link_id: ID of the link to remove.
+        :type link_id: int
+        """
+        # Find the link and remove from graph
+        link = next((l for l in self.links if l.id == link_id), None)
+        if link:
+            self._graph.remove_edge(link.source.id, link.target.id)
+        self.links = [l for l in self.links if l.id != link_id]
+
+    def adjacency_matrix(self) -> np.ndarray:
+        """
+        Return the adjacency matrix of the topology as a numpy array.
+
+        :return: Adjacency matrix (1 if connected, 0 otherwise).
+        :rtype: numpy.ndarray
+
+        **Example**
+            >>> topo.adjacency_matrix()
+            array([[0, 1],
+                   [1, 0]])
+        """
+        # Usa NetworkX para obtener la matriz de adyacencia
+        if not self.nodes:
+            return np.zeros((0, 0), dtype=int)
+        node_ids = [n.id for n in self.nodes]
+        mat = nx.to_numpy_array(self._graph, nodelist=node_ids, dtype=int)
+        return mat