digraphx 0.1__tar.gz → 0.2__tar.gz

digraphx-0.2/GEMINI.md

@@ -0,0 +1,65 @@
+# Gemini Code Assistant Context
+
+## Project Overview
+
+This project, `digraphx`, is a Python library for network optimization on directed graphs. It provides algorithms for finding minimum cycle ratios, solving parametric network problems, and detecting negative cycles using Howard's algorithm. The library is built on top of `networkx` but includes a custom `TinyDiGraph` data structure for improved memory efficiency with large graphs.
+
+The project is structured as a standard Python library using a `src` layout and is configured with `setup.cfg` and `pyproject.toml`.
+
+### Key Technologies
+
+*   **Language:** Python
+*   **Core Library:** `networkx`
+*   **Testing:** `pytest`, `pytest-cov`, `tox`
+*   **Code Style:** `flake8`, `pre-commit`
+
+### Core Modules
+
+*   `min_cycle_ratio.py`: Implements the Minimum Cycle Ratio (MCR) solver.
+*   `parametric.py` & `min_parmetric_q.py`: Implements solvers for parametric network problems.
+*   `neg_cycle.py` & `neg_cycle_q.py`: Implements negative cycle detection using Howard's algorithm.
+*   `tiny_digraph.py`: Defines a memory-efficient `TinyDiGraph` data structure.
+
+## Building and Running
+
+This is a library, so there is no main application to run. However, you can install it and run tests.
+
+### Installation
+
+To install the project in editable mode, use the following command:
+
+```bash
+pip install -e .
+```
+
+### Running Tests
+
+The project uses `pytest` for testing. To run the tests, use the following command:
+
+```bash
+pytest
+```
+
+You can also use `tox` to run tests in different Python environments:
+
+```bash
+tox
+```
+
+## Development Conventions
+
+### Code Style
+
+The project uses `flake8` for linting and `pre-commit` to enforce code style. Before committing any changes, make sure to run `pre-commit`:
+
+```bash
+pre-commit run --all-files
+```
+
+### Testing
+
+All new features should be accompanied by tests. The tests are located in the `tests` directory and follow the standard `pytest` conventions.
+
+### Contribution Guidelines
+
+The `CONTRIBUTING.md` file provides guidelines for contributing to the project. Please review it before making any contributions.

{digraphx-0.1/src/digraphx.egg-info → digraphx-0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digraphx
-Version: 0.1
+Version: 0.2
 Summary: Network Optimization Python Code
 Home-page: https://github.com/luk036/digraphx
 Author: Wai-Shing Luk

{digraphx-0.1 → digraphx-0.2}/src/digraphx/min_cycle_ratio.py

@@ -26,7 +26,9 @@ from typing import Generic, Mapping, MutableMapping, Tuple, TypeVar
 from .neg_cycle import Cycle, Domain, Edge, Node
 from .parametric import MaxParametricSolver, ParametricAPI
 
+# Define type variables for generic programming
 Ratio = TypeVar("Ratio", Fraction, float)
+# Define graph types for type hints
 Graph = Mapping[Node, Mapping[Node, Mapping[str, Domain]]]
 GraphMut = MutableMapping[Node, MutableMapping[Node, MutableMapping[str, Domain]]]
 
@@ -34,6 +36,8 @@ GraphMut = MutableMapping[Node, MutableMapping[Node, MutableMapping[str, Domain]
 def set_default(digraph: GraphMut, weight: str, value: Domain) -> None:
     """
     This function sets a default value for a specified weight in a graph.
+    It iterates through all edges in the graph and sets the specified weight to the given value
+    if it's not already present in the edge attributes.
 
     :param digraph: The parameter `digraph` is of type `GraphMut`, which is likely a mutable graph data
         structure. It represents a graph where each node has a dictionary of neighbors and their
@@ -55,27 +59,25 @@ def set_default(digraph: GraphMut, weight: str, value: Domain) -> None:
                 e[weight] = value
 
 
-# The `CycleRatioAPI` class is a parametric API that calculates the ratio of a cycle based on the cost
-# and time of its edges.
 class CycleRatioAPI(ParametricAPI[Node, MutableMapping[str, Domain], Ratio]):
+    """
+    This class implements the parametric API for cycle ratio calculations.
+    It provides methods to compute distances based on a given ratio and to calculate
+    the actual ratio for a given cycle.
+    """
+
     def __init__(
         self,
         digraph: Mapping[Node, Mapping[Node, Mapping[str, Domain]]],
         result_type: type,
     ) -> None:
         """
-        This function initializes an object with two parameters, `digraph` and `result_type`, and assigns them to instance
-        variables.
-
-        :param digraph: A mapping of nodes to a mapping of nodes to a mapping of strings to domains. It
-            represents a graph structure where each node is connected to other nodes through edges, and each
-            edge has associated attributes represented by strings and domains
+        Initialize the CycleRatioAPI with a graph and result type.
 
+        :param digraph: The graph structure where nodes map to neighbors and edge attributes
         :type digraph: Mapping[Node, Mapping[Node, Mapping[str, Domain]]]
 
-        :param result_type: The parameter `result_type` is a type. It is used to specify the type of the variable `result_type`. The type
-            can be any valid Python type, such as `int`, `str`, `list`, etc
-
+        :param result_type: The type to use for calculations (Fraction or float)
         :type result_type: type
         """
         self.digraph: Mapping[Node, Mapping[Node, Mapping[str, Domain]]] = digraph
@@ -83,41 +85,36 @@ class CycleRatioAPI(ParametricAPI[Node, MutableMapping[str, Domain], Ratio]):
 
     def distance(self, ratio: Ratio, edge: MutableMapping[str, Domain]) -> Ratio:
         """
-        The function calculates the distance based on the ratio and edge information.
-
-        :param ratio: The ratio parameter is of type Ratio. It is used in the calculation of the return value
+        Calculate the parametric distance for an edge given the current ratio.
+        The distance formula is: cost - ratio * time
 
+        :param ratio: The current ratio value being tested
         :type ratio: Ratio
 
-        :param edge: The `edge` parameter is a mutable mapping (dictionary-like object) that contains
-            information about a specific edge in a graph. It has two keys: "cost" and "time". The value
-            associated with the "cost" key represents the cost of traversing the edge, while the value
-            associated with
-
+        :param edge: The edge with 'cost' and 'time' attributes
         :type edge: MutableMapping[str, Domain]
 
-        :return: the result of the expression `self.result_type(edge["cost"]) - ratio * edge["time"]`.
+        :return: The calculated distance value
+        :rtype: Ratio
         """
         return self.result_type(edge["cost"]) - ratio * edge["time"]
 
     def zero_cancel(self, cycle: Cycle) -> Ratio:
         """
-        The `zero_cancel` function calculates the ratio of the cost to time for a given cycle.
-
-        :param cycle: The `cycle` parameter is of type `Cycle`. It represents a cycle, which is a sequence
-            of edges in a graph that starts and ends at the same vertex. Each edge in the cycle is a dictionary
-            with keys "cost" and "time", representing the cost and time associated with that edge
+        Calculate the actual ratio for a given cycle by summing all costs and times.
+        The ratio is computed as: total_cost / total_time
 
+        :param cycle: A sequence of edges forming a cycle
         :type cycle: Cycle
 
-        :return: a Ratio object.
+        :return: The calculated cycle ratio
+        :rtype: Ratio
         """
         total_cost = sum(edge["cost"] for edge in cycle)
         total_time = sum(edge["time"] for edge in cycle)
         return self.result_type(total_cost) / total_time
 
 
-# The `MinCycleRatioSolver` class is a solver for the minimum cycle ratio problem in directed graphs.
 class MinCycleRatioSolver(Generic[Node, Edge, Ratio]):
     """Minimum Cycle Ratio Solver
 
@@ -143,30 +140,30 @@ class MinCycleRatioSolver(Generic[Node, Edge, Ratio]):
 
     def __init__(self, digraph: Graph) -> None:
         """
-        The function initializes an instance of a class with a graph object.
-
-        :param digraph: The `digraph` parameter is a mapping of nodes to a mapping of nodes to any type of value. It
-            represents a graph where each node is associated with a set of neighboring nodes and their
-            corresponding values
+        Initialize the solver with the graph to analyze.
 
+        :param digraph: The graph structure where nodes map to neighbors and edge attributes
         :type digraph: Graph
         """
         self.digraph: Graph = digraph
 
     def run(self, dist: MutableMapping[Node, Domain], r0: Ratio) -> Tuple[Ratio, Cycle]:
         """
-        This function takes a distance mapping and a ratio as input, and returns a ratio and a cycle.
+        Run the minimum cycle ratio solver algorithm.
 
-        :param dist: A mutable mapping that maps each node in the graph to a ratio value. This represents
-            the initial distribution of ratios for each node
+        The algorithm works by:
+        1. Creating a CycleRatioAPI instance with the graph and ratio type
+        2. Using a MaxParametricSolver to find the optimal ratio
+        3. Returning both the optimal ratio and the corresponding cycle
 
+        :param dist: Initial distance labels for nodes
         :type dist: MutableMapping[Node, Domain]
 
-        :param r0: The parameter `r0` is of type `Ratio` and represents the initial ratio value
-
+        :param r0: Initial ratio value to start the search
         :type r0: Ratio
 
-        :return: The function `run` returns a tuple containing the ratio and cycle.
+        :return: A tuple containing the optimal ratio and the cycle that achieves it
+        :rtype: Tuple[Ratio, Cycle]
         """
         omega = CycleRatioAPI(self.digraph, type(r0))
         solver = MaxParametricSolver(self.digraph, omega)

{digraphx-0.1 → digraphx-0.2}/src/digraphx/min_parmetric_q.py

@@ -1,150 +1,165 @@
-"""
-Min Parametric Solver
-
-This code defines a system for solving a specific type of network optimization problem called a "minimum parametric problem." The purpose of this code is to find the smallest possible value for a parameter (called a ratio) that satisfies certain conditions in a graph-like structure.
-
-The code takes as input a graph (represented as a mapping of nodes and edges), an initial set of distances between nodes, and a starting ratio. It then works to find the smallest ratio that meets the problem's constraints.
-
-The main output of this code is a tuple containing two things: the final (minimum) ratio found, and a cycle in the graph that corresponds to this ratio.
-
-To achieve its purpose, the code uses an algorithm that repeatedly searches for cycles in the graph that could potentially lower the ratio. It does this by using a "negative cycle finder" (NCF) which looks for cycles where the sum of the distances (adjusted by the current ratio) is negative. If such a cycle is found, it means the ratio can be lowered further.
-
-The main logic flow involves a loop that alternates between searching for cycles and updating the ratio. Each time a cycle is found that allows for a lower ratio, the ratio is updated. This process continues until no more improvements can be made - at this point, the minimum ratio has been found.
-
-An important part of the algorithm is the ability to switch between searching for cycles in the forward direction (successor nodes) and the backward direction (predecessor nodes). This helps to explore the graph more thoroughly and find the best possible solution.
-
-The code is designed to be flexible, allowing for different types of numbers (integers, fractions, or floating-point numbers) to be used for distances and ratios. It also includes an abstract base class (MinParametricAPI) that defines the interface for calculating distances and handling cycles, allowing for different implementations of these operations.
-
-Overall, this code provides a framework for solving complex network optimization problems, particularly those where a single parameter needs to be minimized while satisfying constraints across the entire network.
-"""
-
-from abc import abstractmethod
-from fractions import Fraction
-from typing import Generic, Mapping, MutableMapping, Tuple, TypeVar, Callable
-
-from .neg_cycle_q import Cycle, Edge, NegCycleFinder, Node
-
-Domain = TypeVar("Domain", int, Fraction, float)  # Comparable Ring
-Ratio = TypeVar("Ratio", Fraction, float)
-
-
-class MinParametricAPI(Generic[Node, Edge, Ratio]):
-    @abstractmethod
-    def distance(self, ratio: Ratio, edge: Edge) -> Ratio:
-        """
-        The `distance` function calculates the distance between a given ratio and edge.
-
-        :param ratio: The `ratio` parameter is of type `Ratio`. It represents a ratio or proportion
-        :type ratio: Ratio
-        :param edge: The `edge` parameter represents an edge in a graph. It is of type `Edge`
-        :type edge: Edge
-        """
-        pass
-
-    @abstractmethod
-    def zero_cancel(self, cycle: Cycle) -> Ratio:
-        """
-        The `zero_cancel` function takes a `Cycle` object as input and returns a `Ratio` object.
-
-        :param cycle: The `cycle` parameter is of type `Cycle`.
-        :type cycle: Cycle
-        """
-        pass
-
-
-class MinParametricSolver(Generic[Node, Edge, Ratio]):
-    """Minimum Parametric Solver
-
-    This class solves the following parametric network problem:
-
-    |    min  r
-    |    s.t. dist[v] - dist[u] <= distrance(e, r)
-    |         forall e(u, v) in G(V, E)
-
-    A parametric network problem refers to a type of optimization problem that
-    involves finding the optimal solution to a network flow problem as a function
-    of one single parameter.
-    """
-
-    def __init__(
-        self,
-        digraph: Mapping[Node, Mapping[Node, Edge]],
-        omega: MinParametricAPI[Node, Edge, Ratio],
-    ) -> None:
-        """
-        The `__init__` function initializes an object with a graph and an omega parameter.
-
-        :param digraph: digraph is a mapping of nodes to a mapping of nodes to edges. It represents a graph
-            where each node is connected to other nodes through edges. The edges are represented by the
-            mapping of nodes to edges
-
-        :type digraph: Mapping[Node, Mapping[Node, Edge]]
-
-        :param omega: The `omega` parameter is an instance of the `ParametricAPI` class. It represents
-            some kind of parametric API that takes three type parameters: `Node`, `Edge`, and `Ratio`
-
-        :type omega: ParametricAPI[Node, Edge, Ratio]
-        """
-        # self.ncf = NegCycleFinder(digraph)
-        self.digraph = digraph
-        self.omega: MinParametricAPI[Node, Edge, Ratio] = omega
-
-    def run(
-        self,
-        dist: MutableMapping[Node, Domain],
-        ratio: Ratio,
-        update_ok: Callable[[Domain, Domain], bool],
-        pick_one_only=False,
-    ) -> Tuple[Ratio, Cycle]:
-        """
-        The `run` function takes in a distance mapping and a ratio, and iteratively finds the minimum
-        ratio and corresponding cycle until the minimum ratio is greater than or equal to the input
-        ratio.
-
-        :param dist: The `dist` parameter is a mutable mapping where the keys are `Node` objects and the
-            values are `Domain` objects. It represents the distance between nodes in a graph
-
-        :type dist: MutableMapping[Node, Domain]
-
-        :param ratio: The `ratio` parameter is a value that represents a ratio or proportion. It is used
-            as a threshold or target value in the algorithm
-
-        :type ratio: Ratio
-
-        :param update_ok: The `update_ok` parameter is a function that determines whether an update to the
-            distance `dist[vtx_v]` is allowed. It takes two arguments: the current value of `dist[vtx_v]` and
-            the new value `d`. It should return `True` if the update is
-
-        :return: The function `run` returns a tuple containing the updated ratio (`ratio`) and the cycle (`cycle`).
-        """
-        D = type(next(iter(dist.values())))
-
-        def get_weight(e: Edge) -> Domain:
-            return D(self.omega.distance(ratio, e))
-
-        r_max = ratio
-        c_max = []
-        cycle = []
-        reverse: bool = True
-
-        ncf: NegCycleFinder[Node, Edge, Domain] = NegCycleFinder(self.digraph)
-
-        while True:
-            if reverse:
-                cycles = ncf.howard_succ(dist, get_weight, update_ok)
-            else:
-                cycles = ncf.howard_pred(dist, get_weight, update_ok)
-            for c_i in cycles:
-                r_i = self.omega.zero_cancel(c_i)
-                if r_max < r_i:
-                    r_max = r_i
-                    c_max = c_i
-                    if pick_one_only:
-                        break
-            if r_max <= ratio:
-                break
-
-            cycle = c_max
-            ratio = r_max
-            reverse = not reverse
-        return ratio, cycle
+"""
+Min Parametric Solver
+
+This code defines a system for solving a specific type of network optimization problem called a "minimum parametric problem." The purpose of this code is to find the smallest possible value for a parameter (called a ratio) that satisfies certain conditions in a graph-like structure.
+
+The code takes as input a graph (represented as a mapping of nodes and edges), an initial set of distances between nodes, and a starting ratio. It then works to find the smallest ratio that meets the problem's constraints.
+
+The main output of the code is a tuple containing two things: the final (minimum) ratio found, and a cycle in the graph that corresponds to this ratio.
+
+To achieve its purpose, the code uses an algorithm that repeatedly searches for cycles in the graph that could potentially lower the ratio. It does this by using a "negative cycle finder" (NCF) which looks for cycles where the sum of the distances (adjusted by the current ratio) is negative. If such a cycle is found, it means the ratio can be lowered further.
+
+The main logic flow involves a loop that alternates between searching for cycles and updating the ratio. Each time a cycle is found that allows for a lower ratio, the ratio is updated. This process continues until no more improvements can be made - at this point, the minimum ratio has been found.
+
+An important part of the algorithm is the ability to switch between searching for cycles in the forward direction (successor nodes) and the backward direction (predecessor nodes). This helps to explore the graph more thoroughly and find the best possible solution.
+
+The code is designed to be flexible, allowing for different types of numbers (integers, fractions, or floating-point numbers) to be used for distances and ratios. It also includes an abstract base class (MinParametricAPI) that defines the interface for calculating distances and handling cycles, allowing for different implementations of these operations.
+
+Overall, this code provides a framework for solving complex network optimization problems, particularly those where a single parameter needs to be minimized while satisfying constraints across the entire network.
+"""
+
+from abc import abstractmethod
+from fractions import Fraction
+from typing import Callable, Generic, Mapping, MutableMapping, Tuple, TypeVar
+
+from .neg_cycle_q import Cycle, Edge, NegCycleFinder, Node
+
+# Define type variables for domain (numeric types) and ratio (fraction or float)
+Domain = TypeVar("Domain", int, Fraction, float)  # Comparable Ring
+Ratio = TypeVar("Ratio", Fraction, float)
+
+
+class MinParametricAPI(Generic[Node, Edge, Ratio]):
+    @abstractmethod
+    def distance(self, ratio: Ratio, edge: Edge) -> Ratio:
+        """
+        The `distance` function calculates the distance between a given ratio and edge.
+        This is an abstract method that must be implemented by concrete subclasses.
+
+        :param ratio: The `ratio` parameter is of type `Ratio`. It represents a ratio or proportion
+                      that affects the distance calculation.
+        :type ratio: Ratio
+        :param edge: The `edge` parameter represents an edge in a graph. It is of type `Edge`
+        :type edge: Edge
+        :return: The calculated distance based on the given ratio and edge
+        :rtype: Ratio
+        """
+        pass
+
+    @abstractmethod
+    def zero_cancel(self, cycle: Cycle) -> Ratio:
+        """
+        The `zero_cancel` function takes a `Cycle` object as input and returns a `Ratio` object.
+        This calculates the ratio that would make the cycle's total distance sum to zero.
+
+        :param cycle: The `cycle` parameter is of type `Cycle`. It represents a cycle in the graph
+                      that needs to be evaluated.
+        :type cycle: Cycle
+        :return: The ratio that would make the cycle's total distance zero
+        :rtype: Ratio
+        """
+        pass
+
+
+class MinParametricSolver(Generic[Node, Edge, Ratio]):
+    """Minimum Parametric Solver
+
+    This class solves the following parametric network problem:
+
+    |    min  r
+    |    s.t. dist[v] - dist[u] <= distrance(e, r)
+    |         forall e(u, v) in G(V, E)
+
+    A parametric network problem refers to a type of optimization problem that
+    involves finding the optimal solution to a network flow problem as a function
+    of one single parameter.
+    """
+
+    def __init__(
+        self,
+        digraph: Mapping[Node, Mapping[Node, Edge]],
+        omega: MinParametricAPI[Node, Edge, Ratio],
+    ) -> None:
+        """
+        The `__init__` function initializes the solver with a graph and parametric API.
+
+        :param digraph: A mapping representing a directed graph where each node maps to its
+                       neighbors and the edges connecting them. This defines the network structure
+                       that the solver will work with.
+        :type digraph: Mapping[Node, Mapping[Node, Edge]]
+        :param omega: An instance of MinParametricAPI that provides the necessary methods
+                     for distance calculation and cycle analysis. This parameterizes the
+                     solver's behavior.
+        :type omega: MinParametricAPI[Node, Edge, Ratio]
+        """
+        # self.ncf = NegCycleFinder(digraph)
+        self.digraph = digraph
+        self.omega: MinParametricAPI[Node, Edge, Ratio] = omega
+
+    def run(
+        self,
+        dist: MutableMapping[Node, Domain],
+        ratio: Ratio,
+        update_ok: Callable[[Domain, Domain], bool],
+        pick_one_only=False,
+    ) -> Tuple[Ratio, Cycle]:
+        """
+        The `run` function executes the parametric solver algorithm to find the minimum ratio.
+
+        :param dist: A mutable mapping of node distances that will be updated during the algorithm.
+                    Represents the current distance estimates between nodes.
+        :type dist: MutableMapping[Node, Domain]
+        :param ratio: The initial ratio value to start the optimization from.
+        :type ratio: Ratio
+        :param update_ok: A callback function that determines whether a distance update is acceptable.
+                         Takes current and new distance values, returns True if update should proceed.
+        :type update_ok: Callable[[Domain, Domain], bool]
+        :param pick_one_only: If True, stops after finding the first improving cycle. Defaults to False.
+        :type pick_one_only: bool
+        :return: A tuple containing:
+                 - The minimum ratio found (ratio)
+                 - The cycle that corresponds to this ratio (cycle)
+        """
+        # Determine the numeric type used in distance calculations
+        D = type(next(iter(dist.values())))
+
+        # Helper function to calculate edge weights based on current ratio
+        def get_weight(e: Edge) -> Domain:
+            return D(self.omega.distance(ratio, e))
+
+        # Initialize tracking variables for minimum ratio and corresponding cycle
+        r_max = ratio
+        c_max = []
+        cycle = []
+        reverse: bool = True  # Flag to alternate search direction
+
+        # Initialize the negative cycle finder with our graph
+        ncf: NegCycleFinder[Node, Edge, Domain] = NegCycleFinder(self.digraph)
+
+        # Main optimization loop
+        while True:
+            # Search for cycles in either forward or reverse direction
+            if reverse:
+                cycles = ncf.howard_succ(dist, get_weight, update_ok)
+            else:
+                cycles = ncf.howard_pred(dist, get_weight, update_ok)
+
+            # Evaluate all found cycles
+            for c_i in cycles:
+                r_i = self.omega.zero_cancel(c_i)
+                if r_max < r_i:
+                    r_max = r_i
+                    c_max = c_i
+                    if pick_one_only:  # Early exit if we only need one improvement
+                        break
+
+            # Termination condition: no better ratio found
+            if r_max <= ratio:
+                break
+
+            # Update state for next iteration
+            cycle = c_max
+            ratio = r_max
+            reverse = not reverse  # Alternate search direction
+
+        return ratio, cycle