digraphx 0.1__py3-none-any.whl

digraphx/parametric.py

@@ -0,0 +1,135 @@
+"""
+Parametric Network Solver
+
+This code defines a system for solving parametric network problems, which are a type of optimization problem in graph theory. The main purpose of this code is to find the maximum ratio that satisfies certain conditions in a graph, where the distances between nodes depend on this ratio.
+
+The code takes two main inputs: a graph (represented as a mapping of nodes and edges) and an object that defines how to calculate distances based on the ratio. It produces two outputs: the maximum ratio that satisfies the conditions and a cycle in the graph that corresponds to this ratio.
+
+The code achieves its purpose through an iterative algorithm implemented in the run method of the MaxParametricSolver class. This method starts with an initial ratio and repeatedly finds cycles in the graph that could potentially improve this ratio. It uses a negative cycle finder (NCF) to detect these cycles efficiently.
+
+The algorithm works as follows:
+
+1. It starts with an initial ratio and distance estimates for each node.
+2. It uses the NCF to find cycles in the graph where the total distance is negative.
+3. For each negative cycle found, it calculates a new ratio that would make the cycle's total distance zero.
+4. If this new ratio is smaller than the current best ratio, it updates the best ratio and remembers this cycle.
+5. It repeats steps 2-4 until no better ratio can be found.
+
+The main data transformation happening here is the continuous updating of the ratio based on the cycles found in the graph. The algorithm is essentially searching for the highest ratio that doesn't allow any negative cycles in the graph, when distances are calculated using this ratio.
+
+This code is designed to be flexible, using generic types for nodes, edges, and ratios. This allows it to work with different types of graphs and different ways of calculating distances. The ParametricAPI class defines an interface for how distances should be calculated and how to find the ratio that makes a cycle's total distance zero.
+
+Overall, this code provides a framework for solving a specific type of optimization problem on graphs, where the goal is to maximize a ratio while maintaining certain constraints on the distances between nodes in the graph.
+"""
+
+from abc import abstractmethod
+from fractions import Fraction
+from typing import Generic, Mapping, MutableMapping, Tuple, TypeVar
+
+from .neg_cycle import Cycle, Domain, Edge, NegCycleFinder, Node
+
+Ratio = TypeVar("Ratio", Fraction, float)
+
+
+class ParametricAPI(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
+        """
+
+    @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
+        """
+
+
+class MaxParametricSolver(Generic[Node, Edge, Ratio]):
+    """Maximum Parametric Solver
+
+    This class solves the following parametric network problem:
+
+    |    max  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: ParametricAPI[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: ParametricAPI[Node, Edge, Ratio] = omega
+
+    def run(
+        self, dist: MutableMapping[Node, Domain], ratio: Ratio
+    ) -> 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
+
+        :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_min = ratio
+        c_min = []
+        cycle = []
+
+        ncf: NegCycleFinder[Node, Edge, Domain] = NegCycleFinder(self.digraph)
+
+        while True:
+            for ci in ncf.howard(dist, get_weight):
+                ri = self.omega.zero_cancel(ci)
+                if r_min > ri:
+                    r_min = ri
+                    c_min = ci
+            if r_min >= ratio:
+                break
+
+            cycle = c_min
+            ratio = r_min
+        return ratio, cycle

digraphx/skeleton.py

@@ -0,0 +1,149 @@
+"""
+This is a skeleton file that can serve as a starting point for a Python
+console script. To run this script uncomment the following lines in the
+``[options.entry_points]`` section in ``setup.cfg``::
+
+    console_scripts =
+         fibonacci = digraphx.skeleton:run
+
+Then run ``pip install .`` (or ``pip install -e .`` for editable mode)
+which will install the command ``fibonacci`` inside your current environment.
+
+Besides console scripts, the header (i.e. until ``_logger``...) of this file can
+also be used as template for Python modules.
+
+Note:
+    This file can be renamed depending on your needs or safely removed if not needed.
+
+References:
+    - https://setuptools.pypa.io/en/latest/userguide/entry_point.html
+    - https://pip.pypa.io/en/stable/reference/pip_install
+"""
+
+import argparse
+import logging
+import sys
+
+from digraphx import __version__
+
+__author__ = "Wai-Shing Luk"
+__copyright__ = "Wai-Shing Luk"
+__license__ = "MIT"
+
+_logger = logging.getLogger(__name__)
+
+
+# ---- Python API ----
+# The functions defined in this section can be imported by users in their
+# Python scripts/interactive interpreter, e.g. via
+# `from digraphx.skeleton import fib`,
+# when using this Python module as a library.
+
+
+def fib(n):
+    """Fibonacci example function
+
+    Args:
+      n (int): integer
+
+    Returns:
+      int: n-th Fibonacci number
+    """
+    assert n > 0
+    a, b = 1, 1
+    for _i in range(n - 1):
+        a, b = b, a + b
+    return a
+
+
+# ---- CLI ----
+# The functions defined in this section are wrappers around the main Python
+# API allowing them to be called directly from the terminal as a CLI
+# executable/script.
+
+
+def parse_args(args):
+    """Parse command line parameters
+
+    Args:
+      args (List[str]): command line parameters as list of strings
+          (for example  ``["--help"]``).
+
+    Returns:
+      :obj:`argparse.Namespace`: command line parameters namespace
+    """
+    parser = argparse.ArgumentParser(description="Just a Fibonacci demonstration")
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"digraphx {__version__}",
+    )
+    parser.add_argument(dest="n", help="n-th Fibonacci number", type=int, metavar="INT")
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        dest="loglevel",
+        help="set loglevel to INFO",
+        action="store_const",
+        const=logging.INFO,
+    )
+    parser.add_argument(
+        "-vv",
+        "--very-verbose",
+        dest="loglevel",
+        help="set loglevel to DEBUG",
+        action="store_const",
+        const=logging.DEBUG,
+    )
+    return parser.parse_args(args)
+
+
+def setup_logging(loglevel):
+    """Setup basic logging
+
+    Args:
+      loglevel (int): minimum loglevel for emitting messages
+    """
+    logformat = "[%(asctime)s] %(levelname)s:%(name)s:%(message)s"
+    logging.basicConfig(
+        level=loglevel, stream=sys.stdout, format=logformat, datefmt="%Y-%m-%d %H:%M:%S"
+    )
+
+
+def main(args):
+    """Wrapper allowing :func:`fib` to be called with string arguments in a CLI fashion
+
+    Instead of returning the value from :func:`fib`, it prints the result to the
+    ``stdout`` in a nicely formatted message.
+
+    Args:
+      args (List[str]): command line parameters as list of strings
+          (for example  ``["--verbose", "42"]``).
+    """
+    args = parse_args(args)
+    setup_logging(args.loglevel)
+    _logger.debug("Starting crazy calculations...")
+    print(f"The {args.n}-th Fibonacci number is {fib(args.n)}")
+    _logger.info("Script ends here")
+
+
+def run():
+    """Calls :func:`main` passing the CLI arguments extracted from :obj:`sys.argv`
+
+    This function can be used as entry point to create console scripts with setuptools.
+    """
+    main(sys.argv[1:])
+
+
+if __name__ == "__main__":
+    # ^  This is a guard statement that will prevent the following code from
+    #    being executed in the case someone imports this file instead of
+    #    executing it as a script.
+    #    https://docs.python.org/3/library/__main__.html
+
+    # After installing your project with pip, users can also run your Python
+    # modules as scripts via the ``-m`` flag, as defined in PEP 338::
+    #
+    #     python -m digraphx.skeleton 42
+    #
+    run()

digraphx/tiny_digraph.py

@@ -0,0 +1,79 @@
+"""
+TinyDiGraph
+
+This code defines a custom graph data structure called TinyDiGraph, which is designed to be a lightweight and efficient implementation of a directed graph. The purpose of this code is to provide a simple way to create and manipulate directed graphs, particularly for cases where performance and memory efficiency are important.
+
+The main input for this code is the number of nodes in the graph, which is set when initializing the graph using the init_nodes method. The code doesn't directly produce any output, but it provides methods to add edges, count nodes and edges, and iterate through the graph's structure.
+
+TinyDiGraph achieves its purpose by subclassing from DiGraphAdapter, which in turn inherits from NetworkX's DiGraph class. This allows TinyDiGraph to leverage existing graph functionality while customizing certain aspects for efficiency. The key feature of TinyDiGraph is its use of a custom data structure called MapAdapter (likely a list-based dictionary) to store node and edge information.
+
+The code implements several important methods:
+
+1. cheat_node_dict and cheat_adjlist_outer_dict: These methods create MapAdapter objects to store node and edge information efficiently.
+2. init_nodes: This method initializes the graph with a specified number of nodes, setting up the necessary data structures.
+
+The main logic flow of the code is as follows:
+
+1. Define the TinyDiGraph class with custom node and edge storage methods.
+2. Provide a method to initialize the graph with a given number of nodes.
+3. Set up the graph structure using MapAdapter objects for efficient storage and access.
+
+At the end of the file, there's a small example of how to use TinyDiGraph. It creates a graph with 1000 nodes, adds an edge, and then demonstrates how to iterate through the graph and access its properties.
+
+The code also includes a brief demonstration of the MapAdapter data structure, showing how it can be used as an efficient list-like dictionary.
+
+Overall, this code provides a foundation for working with directed graphs in a memory-efficient manner, which could be particularly useful for large graphs or in situations where performance is critical.
+"""
+
+import networkx as nx
+from mywheel.map_adapter import MapAdapter
+
+
+class DiGraphAdapter(nx.DiGraph):
+    def items(self):
+        return self.adjacency()
+
+
+class TinyDiGraph(DiGraphAdapter):
+    num_nodes = 0
+
+    def cheat_node_dict(self):
+        return MapAdapter([dict() for _ in range(self.num_nodes)])
+
+    def cheat_adjlist_outer_dict(self):
+        return MapAdapter([dict() for _ in range(self.num_nodes)])
+
+    node_dict_factory = cheat_node_dict
+    adjlist_outer_dict_factory = cheat_adjlist_outer_dict
+
+    def init_nodes(self, n: int):
+        """
+        The function initializes the number of nodes, a dictionary for nodes, and dictionaries for
+        adjacency and predecessor lists.
+
+        :param n: The parameter `n` represents the number of nodes in the graph
+        :type n: int
+        """
+        self.num_nodes = n
+        self._node = self.cheat_node_dict()
+        self._adj = self.cheat_adjlist_outer_dict()
+        self._pred = self.cheat_adjlist_outer_dict()
+
+
+if __name__ == "__main__":
+    gr = TinyDiGraph()
+    gr.init_nodes(1000)
+    gr.add_edge(2, 1)
+    print(gr.number_of_nodes())
+    print(gr.number_of_edges())
+
+    for utx in gr:
+        for vtx in gr.neighbors(utx):
+            print(f"{utx}, {vtx}")
+
+    a = MapAdapter([0] * 8)
+    for i in a:
+        a[i] = i * i
+    for i, vtx in a.items():
+        print(f"{i}: {vtx}")
+    print(3 in a)

digraphx-0.1.dist-info/METADATA

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: digraphx
+Version: 0.1
+Summary: Network Optimization Python Code
+Home-page: https://github.com/luk036/digraphx
+Author: Wai-Shing Luk
+Author-email: luk036@gmail.com
+License: MIT
+Project-URL: Documentation, https://pyscaffold.org/
+Platform: any
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+License-File: LICENSE.txt
+Requires-Dist: importlib-metadata; python_version < "3.9"
+Requires-Dist: networkx
+Provides-Extra: testing
+Requires-Dist: setuptools; extra == "testing"
+Requires-Dist: pytest; extra == "testing"
+Requires-Dist: pytest-cov; extra == "testing"
+Requires-Dist: networkx; extra == "testing"
+Dynamic: license-file
+
+<!-- These are examples of badges you might want to add to your README:
+     please update the URLs accordingly
+
+[![Built Status](https://api.cirrus-ci.com/github/<USER>/digraphx.svg?branch=main)](https://cirrus-ci.com/github/<USER>/digraphx)
+[![ReadTheDocs](https://readthedocs.org/projects/digraphx/badge/?version=latest)](https://digraphx.readthedocs.io/en/stable/)
+[![Coveralls](https://img.shields.io/coveralls/github/<USER>/digraphx/main.svg)](https://coveralls.io/r/<USER>/digraphx)
+[![PyPI-Server](https://img.shields.io/pypi/v/digraphx.svg)](https://pypi.org/project/digraphx/)
+[![Conda-Forge](https://img.shields.io/conda/vn/conda-forge/digraphx.svg)](https://anaconda.org/conda-forge/digraphx)
+[![Monthly Downloads](https://pepy.tech/badge/digraphx/month)](https://pepy.tech/project/digraphx)
+[![Twitter](https://img.shields.io/twitter/url/http/shields.io.svg?style=social&label=Twitter)](https://twitter.com/digraphx)
+-->
+
+[![Project generated with PyScaffold](https://img.shields.io/badge/-PyScaffold-005CA0?logo=pyscaffold)](https://pyscaffold.org/)
+[![Documentation Status](https://readthedocs.org/projects/digraphx/badge/?version=latest)](https://digraphx.readthedocs.io/en/latest/?badge=latest)
+[![codecov](https://codecov.io/gh/luk036/digraphx/branch/main/graph/badge.svg?token=U7PKg0lceH)](https://codecov.io/gh/luk036/digraphx)
+
+# 🔀 digraphx
+
+> Directed Graph X in Python
+
+A longer description of your project goes here...
+
+## Dependencies
+
+- [luk036/mywheel](https://github.com/luk036/mywheel)
+- networkx
+
+<!-- pyscaffold-notes -->
+
+## 👉 Note
+
+This project has been set up using PyScaffold 4.5. For details and usage
+information on PyScaffold see https://pyscaffold.org/.

digraphx-0.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+digraphx/__init__.py,sha256=ethe4DV1CwbXvO2DSjEzt5SL_7jt2fxQnF4RPgRgTDI,577
+digraphx/max_cycle_ratio.tpy,sha256=e3GWroIm17nNEmVhjJ90ozCeRs5RhpeKkBkyACSwfSc,6623
+digraphx/min_cycle_ratio.py,sha256=L6VzD2mPS7kcKBWQL-THCCEF-Bq39gEzMiccM2qs27g,9200
+digraphx/min_parmetric_q.py,sha256=k-E77T1WB-FkCRadv6dtsBTOc3CzDujsLQI24W5LrPc,7120
+digraphx/neg_cycle.py,sha256=H1IAMjk1M6Z5y92Ct14a_lQsVWzMafR0yPyoYiveK9M,11592
+digraphx/neg_cycle_q.py,sha256=kHinHqeKkeRHVDo0l3B6YJAGt_so1aPHbMwf4isvy64,15876
+digraphx/parametric.py,sha256=3TM9Sppy62b8mkxFEqoS4uUu9FF8V23CP9WOEu2eFYg,6384
+digraphx/skeleton.py,sha256=uQaIAFPqpGOAEfyndv4qjIj1SSJk_P_gP2Rrk4BKGSQ,4219
+digraphx/tiny_digraph.py,sha256=_Y9k58HleY5kso6rgo540ETYkM3hmtDNEPD5DmY64ns,3577
+digraphx-0.1.dist-info/licenses/LICENSE.txt,sha256=MyvlyWiWdJ3ZpAOA4wziXlNa9Hbx8XnEL1Aztt9F7W8,1080
+digraphx-0.1.dist-info/METADATA,sha256=CTlcQ9wPwvM4NN5YhW3kdu87OHT9Evi4voFHigbIbD4,2456
+digraphx-0.1.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+digraphx-0.1.dist-info/top_level.txt,sha256=ZrZmsCjPDRkUco9-v0BMtqpg7GXOF8g5ZCETmPlU5oE,9
+digraphx-0.1.dist-info/RECORD,,

digraphx-0.1.dist-info/WHEEL

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

digraphx-0.1.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Wai-Shing Luk
+
+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.

digraphx-0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+digraphx