digraphx 0.1__py3-none-any.whl

digraphx/__init__.py

@@ -0,0 +1,16 @@
+import sys
+
+if sys.version_info[:2] >= (3, 8):
+    # TODO: Import directly (no need for conditional) when `python_requires = >= 3.9`
+    from importlib.metadata import PackageNotFoundError, version  # pragma: no cover
+else:
+    from importlib_metadata import PackageNotFoundError, version  # pragma: no cover
+
+try:
+    # Change here if project is renamed and does not equal the package name
+    dist_name = __name__
+    __version__ = version(dist_name)
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "unknown"
+finally:
+    del version, PackageNotFoundError

digraphx/max_cycle_ratio.tpy

@@ -0,0 +1,134 @@
+from fractions import Fraction
+from typing import Generic, Mapping, MutableMapping, Tuple, TypeVar
+
+from .neg_cycle_q import Cycle, Domain, Edge, Node
+from .min_parametric_q import MinParametricSolver, MinParametricAPI
+
+Ratio = TypeVar("Ratio", Fraction, float)  # Comparable field
+Graph = Mapping[Node, Mapping[Node, Mapping[str, Domain]]]
+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.
+
+    :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
+    corresponding edge attributes
+    :type digraph: GraphMut
+    :param weight: The `weight` parameter is a string that represents the weight attribute of the edges
+    in the graph
+    :type weight: str
+    :param value: The `value` parameter is the default value that will be set for the specified weight
+    attribute in the graph
+    :type value: Domain
+    """
+    for _, neighbors in digraph.items():
+        for _, e in neighbors.items():
+            if e.get(weight, None) is None:
+                e[weight] = value
+
+
+# The `MaxCycleRatioAPI` class is a parametric API that calculates the ratio of a cycle based on the cost
+# and time of its edges.
+class MaxCycleRatioAPI(MinParametricAPI[Node, MutableMapping[str, Domain], Ratio]):
+    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
+        :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
+        :type result_type: type
+        """
+        self.digraph: Mapping[Node, Mapping[Node, Mapping[str, Domain]]] = digraph
+        self.result_type = result_type
+
+    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
+        :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
+        :type edge: MutableMapping[str, Domain]
+        :return: the result of the expression `self.result_type(edge["cost"]) - ratio * edge["time"]`.
+        """
+        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
+        :type cycle: Cycle
+        :return: a Ratio object.
+        """
+        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 `MaxCycleRatioSolver` class is a solver for the minimum cycle ratio problem in directed graphs.
+class MaxCycleRatioSolver(Generic[Node, Edge, Ratio]):
+    """Minimum Cycle Ratio Solver
+
+    This class solves the following parametric network problem:
+
+        min  r
+        s.t. dist[v] - dist[u] <= cost(u, v) - ratio * time(u, v)
+             for all (u, v) in E
+
+    The maximum cycle ratio (MCR) problem is a fundamental problem in the
+    analysis of directed graphs. Given a directed graph, the MCR problem seeks to
+    find the cycle with the minimum ratio of the sum of edge weights to the
+    number of edges in the cycle. In other words, the MCR problem seeks to find
+    the "tightest" cycle in the graph, where the tightness of a cycle is measured
+    by the ratio of the total weight of the cycle to its length.
+
+    The MCR problem has many applications in the analysis of discrete event
+    systems, such as digital circuits and communication networks. It is closely
+    related to other problems in graph theory, such as the shortest path problem
+    and the maximum flow problem. Efficient algorithms for solving the MCR
+    problem are therefore of great practical importance.
+    """
+
+    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
+        :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.
+
+        :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
+        :type dist: MutableMapping[Node, Domain]
+        :param r0: The parameter `r0` is of type `Ratio` and represents the initial ratio value
+        :type r0: Ratio
+        :return: The function `run` returns a tuple containing the ratio and cycle.
+        """
+        omega = MaxCycleRatioAPI(self.digraph, type(r0))
+        solver = MinParametricSolver(self.digraph, omega)
+        ratio, cycle = solver.run(dist, r0)
+        return ratio, cycle

digraphx/min_cycle_ratio.py

@@ -0,0 +1,174 @@
+"""
+Minimum Cycle Ratio Solver
+
+This code implements a Minimum Cycle Ratio (MCR) Solver for directed graphs. The purpose of this code is to find the cycle in a graph that has the smallest ratio of total edge weights to the number of edges in the cycle. This is useful in analyzing various systems like digital circuits and communication networks.
+
+The main input for this solver is a directed graph, represented as a mapping of nodes to their neighboring nodes and associated edge attributes. The graph is expected to have "cost" and "time" attributes for each edge.
+
+The primary output of this solver is a tuple containing two elements: the minimum cycle ratio (a number) and the cycle itself (a sequence of edges that form the cycle with the minimum ratio).
+
+To achieve its purpose, the code uses a parametric approach. It defines a CycleRatioAPI class that calculates distances between nodes based on a given ratio and edge information. This class also computes the ratio for a given cycle.
+
+The main solver, MinCycleRatioSolver, uses the CycleRatioAPI in combination with a MaxParametricSolver (which is not fully shown in this code snippet) to iteratively find the minimum cycle ratio. It starts with an initial ratio and distance mapping for each node, and then refines these values until it finds the optimal solution.
+
+The algorithm works by repeatedly adjusting the ratio and recalculating distances between nodes. It looks for cycles where the sum of distances around the cycle is negative, which indicates a cycle with a lower ratio than the current best. This process continues until no such cycle can be found, at which point the minimum cycle ratio has been determined.
+
+An important aspect of the code is how it handles different types of numbers. It uses generic types and can work with both fractions and floating-point numbers, allowing for flexibility in how precise the calculations need to be.
+
+The code also includes utility functions like set_default, which ensures that all edges in the graph have a specified weight attribute, setting a default value if it's missing. This helps in preparing the graph data for the main algorithm.
+
+Overall, this code provides a flexible and powerful tool for analyzing directed graphs, particularly useful in scenarios where understanding the most "efficient" or "tightest" cycles in a system is important.
+"""
+
+from fractions import Fraction
+from typing import Generic, Mapping, MutableMapping, Tuple, TypeVar
+
+from .neg_cycle import Cycle, Domain, Edge, Node
+from .parametric import MaxParametricSolver, ParametricAPI
+
+Ratio = TypeVar("Ratio", Fraction, float)
+Graph = Mapping[Node, Mapping[Node, Mapping[str, Domain]]]
+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.
+
+    :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
+        corresponding edge attributes
+
+    :type digraph: GraphMut
+
+    :param weight: The `weight` parameter is a string that represents the weight attribute of the edges in the graph
+
+    :type weight: str
+
+    :param value: The `value` parameter is the default value that will be set for the specified weight attribute in the graph
+
+    :type value: Domain
+    """
+    for _, neighbors in digraph.items():
+        for _, e in neighbors.items():
+            if e.get(weight, None) is 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]):
+    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
+
+        :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
+
+        :type result_type: type
+        """
+        self.digraph: Mapping[Node, Mapping[Node, Mapping[str, Domain]]] = digraph
+        self.result_type = result_type
+
+    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
+
+        :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
+
+        :type edge: MutableMapping[str, Domain]
+
+        :return: the result of the expression `self.result_type(edge["cost"]) - ratio * edge["time"]`.
+        """
+        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
+
+        :type cycle: Cycle
+
+        :return: a Ratio object.
+        """
+        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
+
+    This class solves the following parametric network problem:
+
+    |    max  r
+    |    s.t. dist[v] - dist[u] <= cost(u, v) - ratio * time(u, v)
+    |         for all (u, v) in E
+
+    The minimum cycle ratio (MCR) problem is a fundamental problem in the
+    analysis of directed graphs. Given a directed graph, the MCR problem seeks to
+    find the cycle with the minimum ratio of the sum of edge weights to the
+    number of edges in the cycle. In other words, the MCR problem seeks to find
+    the "tightest" cycle in the graph, where the tightness of a cycle is measured
+    by the ratio of the total weight of the cycle to its length.
+
+    The MCR problem has many applications in the analysis of discrete event
+    systems, such as digital circuits and communication networks. It is closely
+    related to other problems in graph theory, such as the shortest path problem
+    and the maximum flow problem. Efficient algorithms for solving the MCR
+    problem are therefore of great practical importance.
+    """
+
+    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
+
+        :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.
+
+        :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
+
+        :type dist: MutableMapping[Node, Domain]
+
+        :param r0: The parameter `r0` is of type `Ratio` and represents the initial ratio value
+
+        :type r0: Ratio
+
+        :return: The function `run` returns a tuple containing the ratio and cycle.
+        """
+        omega = CycleRatioAPI(self.digraph, type(r0))
+        solver = MaxParametricSolver(self.digraph, omega)
+        ratio, cycle = solver.run(dist, r0)
+        return ratio, cycle

digraphx/min_parmetric_q.py

@@ -0,0 +1,150 @@
+"""
+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