netlistx 0.1__py3-none-any.whl

netlistx/__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

netlistx/cover.py

@@ -0,0 +1,412 @@
+"""
+Cover.py
+
+This code implements several algorithms for solving different types of covering problems in graphs. The main purpose is to find minimal sets of vertices or edges that "cover" certain structures in a graph, such as all edges, cycles, or odd cycles.
+
+The code takes various inputs depending on the specific function being used. Generally, it requires a graph structure (either a regular graph or a hypergraph), a weight mapping for the vertices, and sometimes an optional initial cover set. The graphs are typically represented using the NetworkX library (nx.Graph).
+
+The outputs produced by these functions are usually a tuple containing two elements: a set representing the minimal cover found, and a number representing the total weight or cost of that cover.
+
+The code achieves its purpose through several different algorithms, but they all follow a similar pattern called the primal-dual approximation method. This method iteratively builds a solution by selecting elements that violate certain conditions and adding them to the cover set.
+
+Here's a breakdown of the main functions:
+
+1. pd_cover: This is the core function that implements the primal-dual approximation algorithm. It takes a "violate" function that generates sets of violating elements, a weight mapping, and an initial solution set. It iteratively adds elements to the solution until no violations remain.
+
+2. min_vertex_cover: This function finds a minimum weighted vertex cover in a graph. It uses pd_cover with a violate function that yields edges not covered by the current solution.
+
+3. min_hyper_vertex_cover: Similar to min_vertex_cover, but works on hypergraphs where edges can connect more than two vertices.
+
+4. min_cycle_cover: This function finds a minimum weighted set of vertices that cover all cycles in a graph. It uses a breadth-first search to find cycles and then uses pd_cover to select vertices that break these cycles.
+
+5. min_odd_cycle_cover: Similar to min_cycle_cover, but specifically targets odd cycles in the graph.
+
+The code uses several important data structures and algorithms. Graphs are represented using NetworkX, which provides efficient graph operations. The algorithms make heavy use of sets for storing covers and dictionaries for storing weights and other information. The cycle-finding algorithms use breadth-first search and clever bookkeeping to efficiently detect cycles in the graph.
+
+Overall, this code provides a toolkit for solving various covering problems on graphs, which have applications in many areas of computer science and operations research. The algorithms implemented here provide approximate solutions to these problems, which are often NP-hard and thus difficult to solve exactly for large instances.
+"""
+
+import copy
+from collections import deque
+from typing import (
+    Callable,
+    Deque,
+    Dict,
+    Generator,
+    MutableMapping,
+    Optional,
+    Set,
+    Tuple,
+    Union,
+)
+
+import networkx as nx
+
+
+def pd_cover(
+    violate: Callable, weight: MutableMapping, soln: Set
+) -> Tuple[Set, Union[int, float]]:
+    """
+    The function `pd_cover` implements a primal-dual approximation algorithm for covering problems.
+
+    :param violate: The `violate` parameter is a callable function or oracle that returns a set of
+        violate elements. It is used to generate sets of elements that violate the current solution. Each
+        set represents a potential improvement to the solution
+
+    :type violate: Callable
+
+    :param weight: The `weight` parameter is a dictionary that represents the weight of each element.
+        The keys of the dictionary are the elements, and the values are their corresponding weights
+
+    :type weight: MutableMapping
+
+    :param soln: The `soln` parameter is a set that represents the current solution set. It initially
+        contains no elements, and elements are added to it during the algorithm
+
+    :type soln: Set
+
+    :return: a tuple containing the updated solution set and the total primal cost.
+
+    Examples:
+        >>> def violate_graph() -> Generator:
+        ...     yield [0, 1]
+        ...     yield [0, 2]
+        ...     yield [1, 2]
+        >>> weight = {0: 1, 1: 2, 2: 3}
+        >>> soln = set()
+        >>> pd_cover(violate_graph, weight, soln)
+        ({0, 1}, 4)
+    """
+    total_prml_cost = 0
+    total_dual_cost = 0
+    gap = copy.copy(weight)
+    for S in violate():
+        min_vtx = min(S, key=lambda vtx: gap[vtx])
+        min_val = gap[min_vtx]
+        soln.add(min_vtx)
+        total_prml_cost += weight[min_vtx]
+        total_dual_cost += min_val
+        for vtx in S:
+            gap[vtx] -= min_val
+    assert total_dual_cost <= total_prml_cost
+    return soln, total_prml_cost
+
+
+def min_vertex_cover(
+    ugraph: nx.Graph, weight: MutableMapping, coverset: Optional[Set] = None
+) -> Tuple[Set, Union[int, float]]:
+    r"""
+    The `min_vertex_cover` function performs minimum weighted vertex cover using a primal-dual
+    approximation algorithm (without post-processing).
+
+    :param ugraph: The parameter `ugraph` is a `nx.Graph` object, which represents the input graph. It is an
+        undirected graph where each edge represents a connection between two vertices
+
+    :type ugraph: nx.Graph
+
+    :param weight: The `weight` parameter is a dictionary that assigns a weight to each vertex in the
+        graph. The weights are used to determine the minimum weighted vertex cover
+
+    :type weight: MutableMapping
+
+    :param coverset: The `coverset` parameter is an optional set that represents the current vertex
+        cover solution. It is used to keep track of the vertices that are included in the cover. If no
+        `coverset` is provided, an empty set is used as the initial cover
+
+    :type coverset: Optional[Set]
+
+    :return: The function `min_vertex_cover` returns a tuple containing two elements. The first element
+        is a set representing the minimum weighted vertex cover, and the second element is either an integer
+        or a float representing the weight of the minimum vertex cover.
+
+    .. svgbob::
+       :align: center
+
+        "({b, d, e}, 3)"
+
+        b     c     d     e
+        #-----o-----#-----o
+        |      \   / \
+        |       \ /   \
+        o        #-----o
+        a        e     f
+
+    Examples:
+        >>> ugraph = nx.Graph()
+        >>> ugraph.add_edges_from([(0, 1), (0, 2), (1, 2), (1, 3), (2, 3), (2, 4), (3, 4)])
+        >>> weight = {0: 1, 1: 1, 2: 1, 3: 1, 4: 1}
+        >>> soln = set()
+        >>> min_vertex_cover(ugraph, weight, soln)
+        ({0, 1, 2, 3}, 4)
+    """
+    if coverset is None:
+        coverset = set()
+
+    def violate_graph() -> Generator:
+        for utx, vtx in ugraph.edges():
+            if utx in coverset or vtx in coverset:
+                continue
+            yield [utx, vtx]
+
+    return pd_cover(violate_graph, weight, coverset)
+
+
+def min_hyper_vertex_cover(
+    hyprgraph, weight: MutableMapping, coverset: Optional[Set] = None
+) -> Tuple[Set, Union[int, float]]:
+    """
+    The `min_hyper_vertex_cover` function performs minimum weighted vertex cover using a primal-dual
+    approximation algorithm (without post-processing).
+
+    :param hyprgraph: The `hyprgraph` parameter represents a hypergraph, which is a generalization of a
+        graph where an edge can connect more than two vertices. It is likely represented as a data structure
+        that contains information about the vertices and edges of the hypergraph
+
+    :param weight: The `weight` parameter is a mutable mapping that assigns a weight to each vertex in
+        the hypergraph. It is used to determine the minimum weighted vertex cover
+
+    :type weight: MutableMapping
+
+    :param coverset: The `coverset` parameter is an optional set that represents the current vertex
+        cover. It contains the vertices that have been selected as part of the cover. If no `coverset` is
+        provided, it defaults to an empty set
+
+    :type coverset: Optional[Set]
+
+    :return: The function `min_hyper_vertex_cover` returns a tuple containing two elements. The first
+        element is a set representing the minimum weighted vertex cover, and the second element is either an
+        integer or a float representing the weight of the vertex cover.
+
+    .. svgbob::
+       :align: center
+
+        "({b, d, g, h}, 4)"
+
+        a       b        e       g
+        o-------#-----+--o-------#
+                      |  |
+                   ,--)--'
+                   |  |
+                   |  `--.
+                   |     |
+        o-------#--+-----o-------#
+        c       d        f       h
+
+    """
+    if coverset is None:
+        coverset = set()
+
+    def violate_netlist() -> Generator:
+        for net in hyprgraph.nets:
+            if any(vtx in coverset for vtx in hyprgraph.ugraph[net]):
+                continue
+            yield hyprgraph.ugraph[net]
+
+    return pd_cover(violate_netlist, weight, coverset)
+
+
+def _construct_cycle(info: Dict, parent, child) -> Deque:
+    """
+    The `_construct_cycle` function constructs a cycle by traversing the parent-child relationship in a
+    dictionary.
+
+    :param info: The `info` parameter is a dictionary that contains information about the nodes in a
+        graph. Each key in the dictionary represents a node, and the corresponding value is a tuple
+        containing two elements: the parent node and the depth of the node
+
+    :type info: Dict
+
+    :param parent: The parent parameter represents the parent node in a graph or tree structure
+
+    :param child: The `child` parameter represents a node in a graph that is connected to the `parent`
+        node
+
+    :return: a deque object.
+    """
+    _, depth_now = info[parent]
+    _, depth_child = info[child]
+    if depth_now < depth_child:
+        node_a, depth_a = parent, depth_now
+        node_b, depth_b = child, depth_child
+    else:
+        node_a, depth_a = child, depth_child
+        node_b, depth_b = parent, depth_now
+    S: Deque = deque()
+    while depth_a < depth_b:
+        S.append(node_a)
+        node_a, depth_a = info[node_a]
+    # depth_now == depth
+    while node_a != node_b:
+        S.append(node_a)
+        S.appendleft(node_b)
+        node_a, _ = info[node_a]
+        node_b, _ = info[node_b]
+    S.appendleft(node_b)
+    return S
+
+
+def min_cycle_cover(
+    ugraph: nx.Graph, weight: MutableMapping, coverset: Optional[Set] = None
+) -> Tuple[Set, Union[int, float]]:
+    r"""
+    The `min_cycle_cover` function performs minimum cycle cover using a primal-dual approximation
+        algorithm (without post-processing).
+
+    :param ugraph: The `ugraph` parameter is a `nx.Graph` object representing the input graph. It contains the
+        nodes and edges of the graph
+
+    :type ugraph: nx.Graph
+
+    :param weight: The `weight` parameter is a dictionary that assigns a weight to each node in the
+        graph. The weights are used to determine the minimum cycle cover
+
+    :type weight: MutableMapping
+
+    :param coverset: The `coverset` parameter is an optional set that contains the nodes that are
+        already covered by previous cycles. It is used to keep track of the nodes that have already been
+        included in the minimum cycle cover. If no `coverset` is provided, it is initialized as an empty set
+
+    :type coverset: Optional[Set]
+
+    :return: The function `min_cycle_cover` returns a tuple containing a set and either an integer or a
+        float. The set represents the minimum cycle cover, and the integer or float represents the weight of
+        the minimum cycle cover.
+
+    .. svgbob::
+       :align: center
+
+        "({c, d}, 2)"
+
+        a     b     c
+        o-----o-----#
+         \   / \     \
+          \ /   \     \
+           #-----o-----o
+           d     e     f
+
+    Examples:
+        >>> ugraph = nx.Graph()
+        >>> ugraph.add_edges_from([(0, 1), (0, 2), (1, 2), (1, 3), (2, 3), (2, 4), (3, 4)])
+        >>> weight = {0: 1, 1: 1, 2: 1, 3: 1, 4: 1}
+        >>> soln = set()
+        >>> min_cycle_cover(ugraph, weight, soln)
+        ({0, 1, 2}, 3)
+    """
+    if coverset is None:
+        coverset = set()
+
+    def find_cycle():
+        for info, parent, child in _generic_bfs_cycle(ugraph, coverset):
+            return _construct_cycle(info, parent, child)
+
+    def violate() -> Generator:
+        while True:
+            S = find_cycle()
+            if S is None:
+                break
+            yield S
+
+    return pd_cover(violate, weight, coverset)
+
+
+def _generic_bfs_cycle(ugraph: nx.Graph, coverset: Set) -> Generator:
+    """
+    The function `_generic_bfs_cycle` performs a breadth-first search on a graph to find cycles,
+    excluding nodes in a given `coverset`.
+
+    :param ugraph: The parameter `ugraph` is a graph object that represents a directed graph. It should have a
+        method `neighbors(node)` that returns the neighbors of a given node in the graph. The graph can be
+        represented using any graph library or data structure that supports this method
+
+    :param coverset: The `coverset` parameter is a set of nodes that should be excluded from the BFS
+        traversal. These nodes will not be considered as potential starting points for the BFS algorithm
+    """
+    depth_limit = len(ugraph)
+    neighbors = ugraph.neighbors
+    nodelist = list(ugraph.nodes())
+    for source in nodelist:
+        if source in coverset:
+            continue
+        info = {source: (source, depth_limit)}
+        queue = deque([source])
+        while queue:
+            parent = queue.popleft()
+            succ, depth_now = info[parent]
+            for child in neighbors(parent):
+                if child in coverset:
+                    continue
+                if child not in info:
+                    info[child] = (parent, depth_now - 1)
+                    queue.append(child)
+                    continue
+                if succ == child:
+                    continue
+                # cycle found
+                yield info, parent, child
+
+
+def min_odd_cycle_cover(
+    ugraph: nx.Graph, weight: MutableMapping, coverset: Optional[Set] = None
+) -> Tuple[Set, Union[int, float]]:
+    r"""
+    The `min_odd_cycle_cover` function performs minimum odd cycle cover using a primal-dual
+    approximation algorithm (without post-processing).
+
+    :param ugraph: The `ugraph` parameter is a `nx.Graph` object representing the input graph. It is used to
+        define the graph structure and find cycles in the graph
+
+    :type ugraph: nx.Graph
+
+    :param weight: The `weight` parameter is a dictionary that assigns a weight to each node in the
+        graph
+
+    :type weight: MutableMapping
+
+    :param coverset: The `coverset` parameter is an optional set that represents the initial set of
+        vertices that are covered by the minimum odd cycle cover. This set can be empty if no vertices are
+        initially covered
+
+    :type coverset: Optional[Set]
+
+    :return: The function `min_odd_cycle_cover` returns a tuple containing a set and either an integer
+        or a float. The set represents the minimum odd cycle cover, and the integer or float represents the
+        weight of the cover.
+
+    .. svgbob::
+       :align: center
+
+        "({d}, 1)"
+
+        a     b     c
+        o-----o-----o
+         \   / \     \
+          \ /   \     \
+           #-----o-----o
+           d     e     f
+
+    Examples:
+        >>> ugraph = nx.Graph()
+        >>> ugraph.add_edges_from([(0, 1), (0, 2), (1, 2), (1, 3), (2, 3), (2, 4), (3, 4)])
+        >>> weight = {0: 1, 1: 1, 2: 1, 3: 1, 4: 1}
+        >>> soln = set()
+        >>> min_odd_cycle_cover(ugraph, weight, soln)
+        ({0, 1, 2}, 3)
+    """
+    if coverset is None:
+        coverset = set()
+
+    def find_odd_cycle():
+        for info, parent, child in _generic_bfs_cycle(ugraph, coverset):
+            _, depth_child = info[child]
+            _, depth_parent = info[parent]
+            if (depth_parent - depth_child) % 2 == 0:
+                return _construct_cycle(info, parent, child)
+
+    def violate() -> Generator:
+        while True:
+            S = find_odd_cycle()
+            if S is None:
+                break
+            yield S
+
+    return pd_cover(violate, weight, coverset)

netlistx/graph_algo.py

@@ -0,0 +1,210 @@
+"""
+Graph Algorithms (graph_algo.py)
+
+This code contains two main functions that work with graphs to solve optimization problems. Let's break down what each function does in simple terms.
+
+The first function, min_vertex_cover_fast, finds a minimum weighted vertex cover in a graph. A vertex cover is a set of vertices that includes at least one endpoint of every edge in the graph. The "weighted" part means that each vertex has a weight, and we want to find a cover with the lowest total weight.
+
+This function takes three inputs:
+
+1. A graph (ugraph)
+2. A dictionary of weights for each vertex (weight)
+3. An optional set of vertices to start with (coverset)
+
+It outputs two things:
+
+1. The set of vertices that form the cover
+2. The total weight of this cover
+
+The function works by looking at each edge in the graph. If neither end of the edge is in the cover yet, it adds the end with the higher weight to the cover. It keeps track of the total weight and updates the remaining "gap" for each vertex. This process continues until all edges are covered.
+
+The second function, min_maximal_independant_set, finds a minimum weighted maximal independent set in a graph. An independent set is a set of vertices where no two vertices are connected by an edge. "Maximal" means we can't add any more vertices to the set without breaking this rule. Like before, we want to find such a set with the lowest total weight.
+
+This function takes four inputs:
+
+1. A graph (ugraph)
+2. A dictionary of weights for each vertex (weight)
+3. An optional set to start the independent set (indset)
+4. An optional set of dependent vertices (dep)
+
+It outputs:
+
+1. The independent set of vertices
+2. The total weight of this set
+
+The function works by looking at each vertex in the graph. For each vertex and its neighbors, it chooses the one with the lowest remaining weight to add to the independent set. It then marks this vertex and all its neighbors as "dependent" (they can't be added to the independent set). This process continues until all vertices are either in the independent set or marked as dependent.
+
+Both functions use a technique called a primal-dual algorithm, which is a way of solving optimization problems. They both keep track of a "gap" for each vertex, which helps ensure that the solution is close to optimal.
+
+These functions are useful in various graph theory applications, such as network design, scheduling problems, or resource allocation, where we need to find efficient ways to cover a graph or select non-adjacent elements.
+"""
+
+import copy
+from typing import MutableMapping, Optional, Set, Tuple, Union
+
+
+def min_vertex_cover_fast(
+    ugraph, weight: MutableMapping, coverset: Optional[Set] = None
+) -> Tuple[Set, Union[int, float]]:
+    r"""
+    The `min_vertex_cover_fast` function performs minimum weighted vertex cover using a primal-dual
+    approximation algorithm (without post-processing).
+
+    :param ugraph: ugraph is a NetworkX graph object representing the graph on which the minimum weighted
+        vertex cover algorithm will be performed. It contains the nodes and edges of the graph
+
+    :param weight: The `weight` parameter is a mutable mapping that represents the weight of each vertex
+        in the graph. It is used to determine the minimum weighted vertex cover. The keys of the mapping are
+        the vertices of the graph, and the values are the corresponding weights
+
+    :type weight: MutableMapping
+
+    :param coverset: The `coverset` parameter is an optional set that represents the current vertex
+        cover. It is used to keep track of the vertices that are included in the cover. If no coverset is
+        provided, a new empty set is created
+
+    :type coverset: Optional[Set]
+
+    :return: The function `min_vertex_cover_fast` returns a tuple containing the vertex cover set and
+        the total weight of the vertex cover.
+
+    .. svgbob::
+       :align: center
+
+        "({b, d, e}, 3)"
+
+        b     c     d     e
+        #-----o-----#-----o
+        |      \   / \ 
+        |       \ /   \
+        o        #-----o
+        a        e     f
+
+    Examples:
+        >>> import networkx as nx
+        >>> from netlistx.graph_algo import min_vertex_cover_fast
+        >>> ugraph = nx.Graph()
+        >>> ugraph.add_edges_from([(0, 1), (0, 2), (1, 2), (1, 3), (2, 3), (2, 4), (3, 4)])
+        >>> weight = {0: 1, 1: 1, 2: 1, 3: 1, 4: 1}
+        >>> coverset = set()
+        >>> min_vertex_cover_fast(ugraph, weight, coverset)
+        ({0, 1, 2, 3}, 4)
+    """
+    if coverset is None:
+        coverset = set()
+
+    total_dual_cost = 0  # for assertion
+    total_prml_cost = 0
+    gap = copy.copy(weight)
+
+    for utx, vtx in ugraph.edges():
+        if utx in coverset or vtx in coverset:
+            continue
+        if gap[utx] < gap[vtx]:
+            utx, vtx = vtx, utx  # swap
+        coverset.add(vtx)
+        total_dual_cost += gap[vtx]
+        total_prml_cost += weight[vtx]
+        gap[utx] -= gap[vtx]
+        gap[vtx] = 0
+
+    assert total_dual_cost <= total_prml_cost
+    return coverset, total_prml_cost
+
+
+def min_maximal_independant_set(
+    ugraph,
+    weight: MutableMapping,
+    indset: Optional[Set] = None,
+    dep: Optional[Set] = None,
+) -> Tuple[Set, Union[int, float]]:
+    r"""
+    The `min_maximal_independant_set` function performs minimum weighted maximal independent set using
+    primal-dual algorithm.
+
+    :param ugraph: ugraph is an undirected graph represented using the NetworkX library. It represents the
+        graph structure and contains the vertices and edges of the graph
+
+    :param weight: The `weight` parameter is a dictionary-like object that assigns a weight to each
+        vertex in the graph. The keys of the dictionary represent the vertices, and the values represent
+        their corresponding weights
+
+    :type weight: MutableMapping
+
+    :param indset: The `indset` parameter is a set that represents the current independent set. It is
+        initially set to `None` and is updated during the execution of the `min_maximal_independent_set`
+        function
+
+    :type indset: Optional[Set]
+
+    :param dep: The `dep` parameter is a set that represents the dependent vertices in the graph. These
+        are the vertices that are not included in the independent set and are adjacent to vertices in the
+        independent set. The `coverset` function is used to add a vertex and its adjacent vertices to the
+        dependent set
+
+    :type dep: Optional[Set]
+
+    :return: The function `min_maximal_independant_set` returns a tuple containing the minimum weighted
+        maximal independent set (indset) and the total primal cost (total_prml_cost).
+
+    .. svgbob::
+       :align: center
+
+        "({0, 3}, 2)"
+
+        0     2     4
+        #-----o-----o
+         \   / \   /
+          \ /   \ /
+           o-----#
+           1     3
+
+    Examples:
+        >>> import networkx as nx
+        >>> from netlistx.graph_algo import min_maximal_independant_set
+        >>> ugraph = nx.Graph()
+        >>> ugraph.add_edges_from([(0, 1), (0, 2), (1, 2), (1, 3), (2, 3), (2, 4), (3, 4)])
+        >>> weight = {0: 1, 1: 1, 2: 1, 3: 1, 4: 1}
+        >>> indset = set()
+        >>> dep = set()
+        >>> min_maximal_independant_set(ugraph, weight, indset, dep)
+        ({0, 3}, 2)
+    """
+    if indset is None:
+        indset = set()
+    if dep is None:
+        dep = set()
+
+    def coverset(utx):
+        dep.add(utx)
+        for vtx in ugraph[utx]:
+            dep.add(vtx)
+
+    gap = copy.copy(weight)
+    total_prml_cost = 0
+    total_dual_cost = 0
+    for utx in ugraph:
+        if utx in dep:
+            continue
+        if utx in indset:  # pre-define indepentant
+            # coverset(utx)
+            continue
+        min_val = gap[utx]
+        min_vtx = utx
+        for vtx in ugraph[utx]:
+            if vtx in dep:
+                continue
+            if min_val > gap[vtx]:
+                min_val = gap[vtx]
+                min_vtx = vtx
+        indset.add(min_vtx)
+        coverset(min_vtx)
+        total_prml_cost += weight[min_vtx]
+        total_dual_cost += min_val
+        if min_vtx == utx:
+            continue
+        for vtx in ugraph[utx]:
+            gap[vtx] -= min_val
+
+    assert total_dual_cost <= total_prml_cost
+    return indset, total_prml_cost