Docs for fomin.py

Author: SebVde

fomin.py

@@ -3,12 +3,33 @@
 
 
 def sort_nodes(node):
+    """
+    Function to sort nodes for consistent ordering.
+
+    Args:
+        node: A node in the graph, which can be of any hashable type.
+
+    Returns:
+        tuple: A tuple where the first element indicates if the node is a tuple,
+               and the second element is the string representation of the node.
+    """
     is_tuple = isinstance(node, tuple)
-    safe_val = str(node)
-    return (is_tuple, safe_val)
+    string_rep = str(node)
+    # False comes before True when sorting so non-tuple nodes are prioritized
+    # If two nodes are of the same type, sort by their string representation
+    return (is_tuple, string_rep)
 
 
 def get_non_trivial_components(G):
+    """
+    Retrieves the connected components of G that contain more than one node.
+
+    Args:
+        G (networkx.Graph): A networkx graph.
+
+    Returns:
+        list: A list of sets reprenting the non-trivial components of G.
+    """
     components = []
     for c in nx.connected_components(G):
         if len(c) > 1:
@@ -18,6 +39,18 @@ def get_non_trivial_components(G):
 
 
 def construct_H(G, F, nb):
+    """
+    Constructs a subgraph H from the neighbors of a given set of nodes and adding edges
+    between nodes that share a common neighbor in F.
+
+    Args:
+        G (networkx.Graph): A networkx graph.
+        F (set): A set of nodes in G.
+        nb (set): A set of neighbors in G.
+
+    Returns:
+        networkx.Graph: The constructed subgraph H.
+    """
     H = nx.subgraph(G, nb).copy()
     for u, v in itertools.combinations(nb, 2):
         if not set(nx.common_neighbors(G, u, v)).isdisjoint(F):
@@ -27,6 +60,17 @@ def construct_H(G, F, nb):
 
 
 def is_foldable(G, v):
+    """
+    Checks if a node v in the graph is foldable. A node is foldable if none of its neighbors
+    form an anti-triangle. An anti-triangle is a set of three nodes with no edges between them.
+
+    Args:
+        G (networkx.Graph): A networkx graph.
+        v: A node in G.
+
+    Returns:
+        bool: True if the node is foldable, False otherwise.
+    """
     nb = sorted(nx.neighbors(G, v), key=sort_nodes)
     for x, y, z in itertools.combinations(nb, 3):
         if not (G.has_edge(x, y) or G.has_edge(y, z) or G.has_edge(z, x)):
@@ -37,6 +81,17 @@ def is_foldable(G, v):
 
 
 def get_anti_edges(G, v):
+    """
+    Finds all anti-edges among the neighbors of a node v. An anti-edge is a pair of
+    nodes that are not connected by an edge.
+
+    Args:
+        G (networkx.Graph): A networkx graph.
+        v: A node in G.
+
+    Returns:
+        set: A set of tuples representing anti-edges.
+    """
     nb = nx.neighbors(G, v)
     anti_edges = set()
     for x, y in itertools.combinations(nb, 2):
@@ -47,25 +102,50 @@ def get_anti_edges(G, v):
 
 
 def fold_graph(G, v, anti_edges):
+    """
+    Folds the graph by contracting anti-edges of a node v and removing its neighbors.
+
+    Args:
+        G (networkx.Graph): A networkx graph.
+        v: A node in G.
+        anti_edges: A set of anti-edges to be contracted.
+
+    Returns:
+        networkx.Graph: The folded graph.
+    """
     nb_v = set(nx.neighbors(G, v))
     folded_G = G.copy()
     added_nodes = set()
 
     for i, j in anti_edges:
+        # Create a new node representing the contraction of i and j
         n = (i, j)
         folded_G.add_node(n)
         added_nodes.add(n)
         for u in set(nx.neighbors(G, i)) | set(nx.neighbors(G, j)):
+            # Add edges between the new node and the neighbors of i and j except v and those in nb_v
+            # (these nodes will be removed later)
             if u != v and u not in nb_v:
                 folded_G.add_edge(n, u)
 
     for a, b in itertools.combinations(added_nodes, 2):
+        # Add edges between each newly created node
         folded_G.add_edge(a, b)
 
     return nx.subgraph(folded_G, set(folded_G.nodes) - nb_v - {v})
 
 
 def get_2_hop_neighbors(G, v):
+    """
+    Finds all nodes that are two hops away from a given node v.
+
+    Args:
+        G (networkx.Graph): A networkx graph.
+        v: A node in G.
+
+    Returns:
+        set: A set of nodes that are two hops away from v.
+    """
     first_neighbors = set(G.neighbors(v))
     second_neighbors = set()
     for u in first_neighbors:
@@ -77,10 +157,31 @@ def get_2_hop_neighbors(G, v):
 
 
 def is_complete(G):
+    """
+    Checks if a graph is complete. A graph is complete if every pair of nodes is connected.
+
+    Args:
+        G (networkx.Graph): A networkx graph.
+
+    Returns:
+        bool: True if the graph is complete, False otherwise.
+    """
     return len(G.edges) == len(G.nodes) * (len(G.nodes) - 1) / 2
 
 
 def get_mirrors(G, v):
+    """
+    Finds all mirror nodes of a given node v. A node u is a mirror of v if their
+    neighborhoods are identical or if the subgraph induced by the difference of their
+    neighborhoods is complete.
+
+    Args:
+        G (networkx.Graph): A networkx graph.
+        v: A node in G.
+
+    Returns:
+        set: A set of mirror nodes of v.
+    """
     mirrors = set()
 
     for u in get_2_hop_neighbors(G, v):
@@ -93,6 +194,15 @@ def get_mirrors(G, v):
 
 
 def get_max_indep_set(G):
+    """
+    Computes the size of the maximum independent set of a graph.
+
+    Args:
+        G (networkx.Graph): A networkx graph.
+
+    Returns:
+        int: The size of the maximum independent set.
+    """
     if len(G.nodes) == 0:
         return 0
 
@@ -128,6 +238,19 @@ def get_max_indep_set(G):
 
 
 def get_generalized_neighbors(G, F, active_v, v):
+    """
+    Finds the generalized neighbors of a node v considering a set of nodes F
+    and an active node.
+
+    Args:
+        G (networkx.Graph): A networkx graph.
+        F: A set of fixed nodes in G.
+        active_v: The active node in G.
+        v: The node for which generalized neighbors are computed.
+
+    Returns:
+        set: A set of generalized neighbors of v.
+    """
     K = {u for u in (F - {active_v}) if G.has_edge(u, v)}
     new_G = G.copy()
 
@@ -139,7 +262,19 @@ def get_generalized_neighbors(G, F, active_v, v):
 
 
 def get_mif_len(G, F, active_v):
+    """
+    Computes the length of a maximum induced forest (MIF) of a graph. This MIF must include all nodes in F.
+
+    Args:
+        G (networkx.Graph): A networkx graph.
+        F: A set of fixed nodes in G.
+        active_v: The active node in G.
+
+    Returns:
+        int: The length of a MIF of G.
+    """
     if nx.number_connected_components(G) > 1:
+        # If G is disconnected, compute MIF length for each component separately
         res = 0
         for c in nx.connected_components(G):
             if nx.is_forest(nx.subgraph(G, c)):
@@ -152,7 +287,7 @@ def get_mif_len(G, F, active_v):
         return res
 
     sg_F = nx.subgraph(G, F)
-    # Verify is F is acyclic
+    # Verify if F is acyclic
     if len(sg_F.nodes) > 0 and not nx.is_forest(sg_F):
         return 0
 
@@ -176,6 +311,7 @@ def get_mif_len(G, F, active_v):
 
             v_T = list(sorted(T, key=sort_nodes))[0]
 
+            # Contract all nodes in T into v_T
             for n in T - {v_T}:
                 new_G = nx.contracted_nodes(new_G, v_T, n, self_loops=False)
 
@@ -194,7 +330,18 @@ def get_mif_len(G, F, active_v):
 
 
 def main_procedure(G, F, active_v):
-
+    """
+    Main procedure for computing the length of a maximum induced forest (MIF) of G.
+    This MIF must include all nodes in F.
+
+    Args:
+        G (networkx.Graph): A networkx graph.
+        F: A set of fixed nodes in G.
+        active_v: The active node in G.
+
+    Returns:
+        int: The length of a MIF in G.
+    """
     if F == set(G.nodes):
         return len(G.nodes)
 
@@ -204,6 +351,8 @@ def main_procedure(G, F, active_v):
         if max_degree < 2:
             return len(G.nodes)
         else:
+            # Choose a node t with degree at least 2
+            # t is either contained in a MIF or not, thus we explore both subproblems
             t = list(sorted([n for n, d in G.degree() if d >= 2], key=sort_nodes))[0]
             new_G = nx.subgraph(G, G.nodes - {t})
             return max(
@@ -215,16 +364,19 @@ def main_procedure(G, F, active_v):
 
     nb = set(nx.neighbors(G, active_v))
     if set(G.nodes) - F == nb:
+        # Get a maximum independent set of the constructed graph H
         return len(F) + get_max_indep_set(construct_H(G, F - {active_v}, nb))
 
     for v in sorted(nb, key=sort_nodes):
         gen_nb = get_generalized_neighbors(G, F, active_v, v)
         if len(gen_nb) < 2:
+            # Include v in the MIF
             return get_mif_len(G, F | {v}, active_v)
 
     for v in sorted(nb, key=sort_nodes):
         gen_nb = get_generalized_neighbors(G, F, active_v, v)
         if len(gen_nb) > 3:
+            # Explore both subproblems of including and excluding v from the MIF
             return max(
                 get_mif_len(G, F | {v}, active_v),
                 get_mif_len(nx.subgraph(G, G.nodes - {v}), F, active_v),
@@ -233,6 +385,7 @@ def main_procedure(G, F, active_v):
     for v in sorted(nb, key=sort_nodes):
         gen_nb = get_generalized_neighbors(G, F, active_v, v)
         if len(gen_nb) == 2:
+            # Either include v in the MIF or exclude v and include its two generalized neighbors in the MIF
             return max(
                 get_mif_len(G, F | {v}, active_v),
                 get_mif_len(
@@ -242,7 +395,8 @@ def main_procedure(G, F, active_v):
                 ),
             )
 
-    # If every v in nb has exactly 3 generalized neighbors, find a v that has at least one generalized neighbor outside nb
+    # If every v in nb has exactly 3 generalized neighbors, find a v that has at least
+    # one generalized neighbor outside nb
     v = None
     good_gen_nb = None
     for n in nb:
@@ -265,6 +419,8 @@ def main_procedure(G, F, active_v):
             else:
                 print("Problem")
 
+        # Either include v in the MIF, or exclude v and include w1 (which is not in the neighborhood of
+        # the active vertex), or exclude v and w1 and include w2 and w3 in the MIF
         return max(
             get_mif_len(G, F | {v}, active_v),
             get_mif_len(
@@ -280,12 +436,21 @@ def main_procedure(G, F, active_v):
         )
 
     else:
+        # Should not happen but for safety
         print("Problem")
         return Exception("No suitable v found")
 
 
 def get_decycling_number_fomin(G):
+    """
+    Computes the decycling number of a graph using Fomin's algorithm.
+
+    Args:
+        G (networkx.Graph): A networkx graph.
+
+    Returns:
+        int: The decycling number of the graph.
+    """
     if nx.is_forest(G):
         return 0
-
     return len(G.nodes) - get_mif_len(G, set(), None)