graphs/modular_decomposition: improve docstrings and fix coding style

Author: cyrilbouvier

src/sage/graphs/graph.py

@@ -7264,7 +7264,7 @@ def is_module(self, vertices):
             if v not in self:
                 raise LookupError(f"vertex ({v}) is not a vertex of the graph")
 
-        if len(M) == 0 or len(M) == 1 or len(M) == self.order():
+        if len(M) <= 1 or len(M) == self.order():
             return True
 
         N = None  # will contains the neighborhood of M

src/sage/graphs/graph_decompositions/modular_decomposition.hpp

@@ -1,10 +1,10 @@
 /*
  *      Copyright (C) 2024 Cyril Bouvier <[email protected]>
  *
- *This program is free software: you can redistribute it and/or modify
- *it under the terms of the GNU General Public License as published by
- *the Free Software Foundation, either version 2 of the License, or
- *(at your option) any later version.
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
  *                 https://www.gnu.org/licenses/
  */
 

src/sage/graphs/graph_decompositions/modular_decomposition.pxd

@@ -14,8 +14,11 @@ cdef extern from "modular_decomposition.hpp":
         bool is_parallel() const
         bool is_series() const
         cpplist[md_tree_node *] children
-        # For a leaf, the corresponding vertex, for a internal node, any vertex
-        # corresponding to a any leaf below the node
+        # If is_leaf() is true, the attribute 'vertex' contains the id of the
+        # corresponding vertex. If is_leaf() is false, the attribute 'vertex'
+        # contains the id of a vertex corresponding to any leaf below
+        # the node (i.e., 'vertex' contains the id of a vertex belonging to the
+        # module corresponding to the node).
         int vertex
 
     void dealloc_md_tree_nodes_recursively(md_tree_node *)

src/sage/graphs/graph_decompositions/modular_decomposition.pyx

@@ -55,7 +55,7 @@ def corneil_habib_paul_tedder_algorithm(G):
     OUTPUT: an object of type Node representing the modular decomposition tree
     of the graph G
 
-    This function compute the modular decomposition of the given graph by the
+    This function computes the modular decomposition of the given graph by the
     algorithm of Corneil, Habib, Paul and Tedder [TCHP2008]_. It is a recursive,
     linear-time algorithm that first computes the slice decomposition of the
     graph (via the extended lexBFS algorithm) and then computes the modular
@@ -112,17 +112,16 @@ cdef object _md_tree_node_to_md_tree_inner_rec(const md_tree_node *n,
     cdef md_tree_node *c
     if deref(n).is_leaf():
         return Node.create_leaf(Gb.vertex_label(deref(n).vertex))
-    else:
-        if deref(n).is_series():
-            node = Node(NodeType.SERIES)
-        elif deref(n).is_parallel():
-            node = Node(NodeType.PARALLEL)
-        else:  # is_prime
-            node = Node(NodeType.PRIME)
-        node.children.extend(
-            _md_tree_node_to_md_tree_inner_rec(c, Gb)
-                                                  for c in deref(n).children)
-        return node
+
+    if deref(n).is_series():
+        node = Node(NodeType.SERIES)
+    elif deref(n).is_parallel():
+        node = Node(NodeType.PARALLEL)
+    else:  # is_prime
+        node = Node(NodeType.PRIME)
+    node.children.extend(_md_tree_node_to_md_tree_inner_rec(c, Gb)
+                                                    for c in deref(n).children)
+    return node
 
 
 cdef object md_tree_node_to_md_tree(const md_tree_node *n, CGraphBackend Gb):
@@ -151,8 +150,7 @@ cdef object md_tree_node_to_md_tree(const md_tree_node *n, CGraphBackend Gb):
     """
     if n == NULL:
         return Node(NodeType.EMPTY)
-    else:
-        return _md_tree_node_to_md_tree_inner_rec(n, Gb)
+    return _md_tree_node_to_md_tree_inner_rec(n, Gb)
 
 
 ################################################################################
@@ -321,7 +319,7 @@ class Node:
     @classmethod
     def create_leaf(cls, v):
         """
-        Return Node object that is a leaf corresponding to the vertex ``v``
+        Return Node object that is a leaf corresponding to the vertex ``v``.
 
         INPUT:
 
@@ -621,6 +619,21 @@ def modular_decomposition(G, algorithm=None):
     This function should not be used directly, it should be called via the
     ``modular_decomposition`` method of ``Graph``.
 
+    INPUT:
+
+    - ``G`` -- graph whose modular decomposition tree is to be computed
+
+    - ``algorithm`` -- string (default: ``None``); the algorithm to use among:
+
+      - ``None`` or ``'corneil_habib_paul_tedder'`` -- will use the
+        Corneil-Habib-Paul-Tedder algorithm from [TCHP2008]_, its complexity
+        is linear in the number of vertices and edges.
+
+      - ``'habib_maurer'`` -- will use the Habib-Maurer algorithm from
+        [HM1979]_, its complexity is cubic in the number of vertices.
+
+    OUTPUT: The modular decomposition tree, as an object of type ``Node``.
+
     TESTS::
 
         sage: from sage.graphs.graph_decompositions.modular_decomposition import *
@@ -1472,10 +1485,24 @@ def check_algos_are_equivalent(trials, graph_gen, verbose=False):
     Verify that both algorithms compute the same tree (up to equivalence) for
     random graphs.
 
+    INPUT:
+
+    - ``trials`` -- integer; the number of tests the function will run.
+
+    - ``graph_gen`` -- function; a function that can be called without argument
+      and returns a random graph.
+
+    - ``verbose`` -- boolean (defaul: ``False``); enable printing debug
+      information.
+
+    OUTPUT: ``None``. Raises an ``AssertionError`` on failure.
+
     EXAMPLES::
 
         sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+        sage: check_algos_are_equivalent(3, lambda : graphs.RandomGNP(10, 0.1))
         sage: check_algos_are_equivalent(3, lambda : graphs.RandomGNP(10, 0.5))
+        sage: check_algos_are_equivalent(3, lambda : graphs.RandomGNP(10, 0.9))
     """
     for _ in range(trials):
         graph = graph_gen()