passagemath-graphs 10.6.1rc1__cp310-cp310-musllinux_1_2_aarch64.whl

sage/graphs/graph_decompositions/modular_decomposition.pyx

@@ -0,0 +1,1536 @@
+# sage_setup: distribution = sagemath-graphs
+# distutils: language = c++
+# distutils: extra_compile_args = -std=c++11
+r"""
+Modular Decomposition
+
+This module implements the function for computing the modular decomposition
+of undirected graphs.
+
+AUTHORS:
+
+- Lokesh Jain (2017): first implementation of the linear time algorithm of
+  D. Corneil, M. Habib, C. Paul and M. Tedder [TCHP2008]_
+
+- David Einstein (2018): added the algorithm of M. Habib and M. Maurer [HM1979]_
+
+- Cyril Bouvier (2024): second implementation of the linear time algorithm
+  of D. Corneil, M. Habib, C. Paul and M. Tedder [TCHP2008]_
+"""
+# ****************************************************************************
+#       Copyright (C) 2017 Lokesh Jain <lokeshj1703@gmail.com>
+#                     2018 David Einstein <deinst@gmail.com>
+#                     2024 Cyril Bouvier <cyril.bouvier@lirmm.fr>
+#
+# 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/
+# ****************************************************************************
+from cython.operator cimport dereference as deref
+
+from enum import IntEnum
+
+from sage.graphs.base.c_graph cimport CGraph, CGraphBackend
+from sage.graphs.graph_decompositions.slice_decomposition cimport \
+        extended_lex_BFS
+from sage.misc.random_testing import random_testing
+
+try:
+    from sage.groups.perm_gps.permgroup_element import PermutationGroupElement
+except ImportError:
+    PermutationGroupElement = ()
+
+
+################################################################################
+#                     Corneil-Habib-Paul-Tedder algorithm                      #
+################################################################################
+def corneil_habib_paul_tedder_algorithm(G):
+    r"""
+    Compute the modular decomposition by the algorithm of Corneil, Habib, Paul
+    and Tedder.
+
+    INPUT:
+
+    - ``G`` -- the graph for which modular decomposition tree needs to be
+      computed
+
+    OUTPUT: an object of type Node representing the modular decomposition tree
+    of the graph G
+
+    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
+    decomposition by calling itself recursively on the slices of the previously
+    computed slice decomposition.
+
+    This functions is based on the last version of the paper [TCHP2008]_.
+    Previous versions of the paper and previous implementations were found to
+    contains errors, see [AP2024]_.
+
+    .. SEEALSO::
+
+        * :mod:`~sage.graphs.graph_decompositions.slice_decomposition` --
+          compute a slice decomposition of the simple undirect graph
+
+    This function should not be used directly, it should be called via the
+    ``modular_decomposition`` method of ``Graph`` with the parameter
+    ``algorithm='corneil_habib_paul_tedder'``.
+
+    This functions assumes that ``graph`` is a object of the class ``Graph`` and
+    is a simple graph.
+
+    TESTS::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+        sage: recreate_decomposition(15, corneil_habib_paul_tedder_algorithm,
+        ....:                                                         3, 4, 0.2)
+        sage: recreate_decomposition(10, corneil_habib_paul_tedder_algorithm,
+        ....:                                                         4, 5, 0.2)
+        sage: recreate_decomposition(3, corneil_habib_paul_tedder_algorithm,
+        ....:                                                         6, 5, 0.2)
+
+        sage: H = Graph('Hv|mmjz', format='graph6')
+        sage: H.relabel('abcdefghi')  # counter-exemple graph from [AP2024]_
+        sage: H.modular_decomposition()
+        (SERIES,
+         [(PRIME, ['e', (PARALLEL, ['g', 'h']), 'b', 'c']),
+          (PARALLEL, [(SERIES, ['i', 'd', 'a']), 'f'])])
+    """
+    cdef CGraphBackend Gbackend = <CGraphBackend> G._backend
+    cdef CGraph cg = Gbackend.cg()
+
+    cdef vector[int] sigma
+    cdef vector[vector[int]] lex_label
+    cdef vector[size_t] xslice_len
+
+    # Compute the slice decomposition using the extended lexBFS algorithm
+    extended_lex_BFS(cg, sigma, NULL, -1, NULL, &xslice_len, &lex_label)
+
+    cdef SDData SD
+    SD.set_from_data(0, sigma.data(), xslice_len.data(), lex_label.data())
+
+    MD = corneil_habib_paul_tedder_inner(SD)
+
+    r = md_tree_node_to_md_tree(MD, Gbackend)
+    dealloc_md_tree_nodes_recursively(MD)
+    return r
+
+
+cdef object _md_tree_node_to_md_tree_inner_rec(const md_tree_node *n,
+                                               CGraphBackend Gb):
+    """
+    Utility function for :func:`md_tree_node_to_md_tree`.
+    """
+    cdef md_tree_node *c
+    if deref(n).is_leaf():
+        return Node.create_leaf(Gb.vertex_label(deref(n).vertex))
+
+    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):
+    """
+    This function converts a modular decomposition tree (given as a pointer to a
+    md_tree_node) into an object of the Python class Node (which is then
+    converted into the correct output by :meth:`Graph.modular_decomposition`).
+
+    The graph backend is needed to convert the int stored into the md_tree_node
+    into the corresponding vertex of the Python graph.
+
+    This function deals with the case of an empty tree and then delegates the
+    actual conversion to :func:`_md_tree_node_to_md_tree_inner_rec`.
+
+    TESTS:
+
+    Indirect doctests::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+        sage: corneil_habib_paul_tedder_algorithm(Graph(1))
+        NORMAL [0]
+        sage: corneil_habib_paul_tedder_algorithm(Graph(2))
+        PARALLEL [NORMAL [0], NORMAL [1]]
+        sage: corneil_habib_paul_tedder_algorithm(graphs.CompleteGraph(3))
+        SERIES [NORMAL [1], NORMAL [2], NORMAL [0]]
+    """
+    if n == NULL:
+        return Node(NodeType.EMPTY)
+    return _md_tree_node_to_md_tree_inner_rec(n, Gb)
+
+
+################################################################################
+class NodeType(IntEnum):
+    """
+    NodeType is an enumeration class used to define the various types of nodes
+    in modular decomposition tree.
+
+    The various node types defined are
+
+    - ``PARALLEL`` -- indicates the node is a parallel module
+
+    - ``SERIES`` -- indicates the node is a series module
+
+    - ``PRIME`` -- indicates the node is a prime module
+
+    - ``EMPTY`` -- indicates a empty tree
+
+    - ``NORMAL`` -- indicates the node is normal containing a vertex
+    """
+    PRIME = 0
+    SERIES = 1
+    PARALLEL = 2
+    NORMAL = 3
+    EMPTY = -1
+
+    def __repr__(self) -> str:
+        r"""
+        Return a string representation of a ``NodeType`` object.
+
+        TESTS::
+
+            sage: from sage.graphs.graph_decompositions.modular_decomposition import NodeType
+            sage: repr(NodeType.PARALLEL)
+            'PARALLEL'
+            sage: str(NodeType.PRIME)
+            'PRIME'
+        """
+        return self.name
+
+    __str__ = __repr__
+
+
+class Node:
+    """
+    Node class stores information about the node type.
+
+    Node type can be ``PRIME``, ``SERIES``, ``PARALLEL``, ``NORMAL`` or
+    ``EMPTY``.
+
+    - ``node_type`` -- is of type NodeType and specifies the type of node
+    """
+    def __init__(self, node_type):
+        r"""
+        Create a node with the given node type.
+
+        EXAMPLES::
+
+            sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+            sage: n = Node(NodeType.SERIES); n.node_type
+            SERIES
+            sage: n.children
+            []
+        """
+        self.node_type = node_type
+        self.children = []
+
+    def is_prime(self):
+        r"""
+        Check whether ``self`` is a prime node.
+
+        EXAMPLES::
+
+            sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+            sage: n = Node(NodeType.PRIME)
+            sage: n.children.append(Node.create_leaf(1))
+            sage: n.children.append(Node.create_leaf(2))
+            sage: n.is_prime()
+            True
+            sage: (n.children[0].is_prime(), n.children[1].is_prime())
+            (False, False)
+        """
+        return self.node_type == NodeType.PRIME
+
+    def is_series(self):
+        r"""
+        Check whether ``self`` is a series node.
+
+        EXAMPLES::
+
+            sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+            sage: n = Node(NodeType.SERIES)
+            sage: n.children.append(Node.create_leaf(1))
+            sage: n.children.append(Node.create_leaf(2))
+            sage: n.is_series()
+            True
+            sage: (n.children[0].is_series(), n.children[1].is_series())
+            (False, False)
+        """
+        return self.node_type == NodeType.SERIES
+
+    def is_empty(self):
+        r"""
+        Check whether ``self`` is an empty node.
+
+        EXAMPLES::
+
+            sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+            sage: Node(NodeType.EMPTY).is_empty()
+            True
+            sage: Node.create_leaf(1).is_empty()
+            False
+        """
+        return self.node_type == NodeType.EMPTY
+
+    def is_leaf(self):
+        r"""
+        Check whether ``self`` is a leaf.
+
+        EXAMPLES::
+
+            sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+            sage: n = Node(NodeType.PRIME)
+            sage: n.children.append(Node.create_leaf(1))
+            sage: n.children.append(Node.create_leaf(2))
+            sage: n.is_leaf()
+            False
+            sage: all(c.is_leaf() for c in n.children)
+            True
+        """
+        return self.node_type == NodeType.NORMAL
+
+    def __repr__(self):
+        r"""
+        Return a string representation of the node.
+
+        EXAMPLES::
+
+            sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+            sage: n = Node(NodeType.PRIME)
+            sage: n.children.append(Node.create_leaf(1))
+            sage: n.children.append(Node.create_leaf(2))
+            sage: str(n)
+            'PRIME [NORMAL [1], NORMAL [2]]'
+        """
+        return f"{self.node_type} {self.children}"
+
+    def __eq__(self, other):
+        r"""
+        Compare two nodes for equality.
+
+        EXAMPLES::
+
+            sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+            sage: n1 = Node(NodeType.PRIME)
+            sage: n2 = Node(NodeType.PRIME)
+            sage: n3 = Node(NodeType.SERIES)
+            sage: n1 == n2
+            True
+            sage: n1 == n3
+            False
+        """
+        return (self.node_type == other.node_type and
+                self.children == other.children)
+
+    @classmethod
+    def create_leaf(cls, v):
+        """
+        Return Node object that is a leaf corresponding to the vertex ``v``.
+
+        INPUT:
+
+        - ``vertex`` -- vertex number
+
+        OUTPUT: a node object representing the vertex with ``node_type`` set as
+        ``NodeType.NORMAL``
+
+        EXAMPLES::
+
+            sage: from sage.graphs.graph_decompositions.modular_decomposition import Node
+            sage: node = Node.create_leaf(2)
+            sage: node
+            NORMAL [2]
+        """
+        node = cls(NodeType.NORMAL)
+        node.children.append(v)
+        return node
+
+
+def print_md_tree(root):
+    """
+    Print the modular decomposition tree.
+
+    INPUT:
+
+    - ``root`` -- root of the modular decomposition tree
+
+    EXAMPLES::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+        sage: print_md_tree(habib_maurer_algorithm(graphs.IcosahedralGraph()))
+        PRIME
+         3
+         4
+         7
+         9
+         11
+         1
+         5
+         8
+         0
+         2
+         6
+         10
+    """
+
+    def recursive_print_md_tree(root, level):
+        """
+        Print the modular decomposition tree at root.
+
+        INPUT:
+
+        - ``root`` -- root of the modular decomposition tree
+
+        - ``level`` -- indicates the depth of root in the original modular
+          decomposition tree
+        """
+        if root.node_type != NodeType.NORMAL:
+            print("{}{}".format(level, str(root.node_type)))
+            for tree in root.children:
+                recursive_print_md_tree(tree, level + " ")
+        else:
+            print("{}{}".format(level, str(root.children[0])))
+
+    recursive_print_md_tree(root, "")
+
+
+# =============================================================================
+# Habib Maurer algorithm
+# =============================================================================
+
+def gamma_classes(graph):
+    """
+    Partition the edges of the graph into Gamma classes.
+
+    Two distinct edges are Gamma related if they share a vertex but are not
+    part of a triangle.  A Gamma class of edges is a collection of edges such
+    that any edge in the class can be reached from any other by a chain of
+    Gamma related edges (that are also in the class).
+
+    The two important properties of the Gamma class
+
+    * The vertex set corresponding to a Gamma class is a module
+    * If the graph is not fragile (neither it or its complement is
+      disconnected) then there is exactly one class that visits all the
+      vertices of the graph, and this class consists of just the edges that
+      connect the maximal strong modules of that graph.
+
+    EXAMPLES:
+
+    The gamma_classes of the octahedral graph are the three 4-cycles
+    corresponding to the slices through the center of the octahedron::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import gamma_classes
+        sage: g = graphs.OctahedralGraph()
+        sage: sorted(gamma_classes(g), key=str)
+        [frozenset({0, 1, 4, 5}), frozenset({0, 2, 3, 5}), frozenset({1, 2, 3, 4})]
+
+    TESTS:
+
+    Ensure that the returned vertex sets from some random graphs are modules::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import test_gamma_modules
+        sage: test_gamma_modules(2, 10, 0.5)
+    """
+    from itertools import chain
+    from sage.sets.disjoint_set import DisjointSet
+
+    pieces = DisjointSet(frozenset(e) for e in graph.edge_iterator(labels=False))
+    for v in graph:
+        neighborhood = graph.subgraph(vertices=graph.neighbors(v))
+        for component in neighborhood.complement().connected_components(sort=False):
+            v1 = component[0]
+            e = frozenset([v1, v])
+            for vi in component[1:]:
+                ei = frozenset([vi, v])
+                pieces.union(e, ei)
+    return {frozenset(chain.from_iterable(loe)): loe for loe in pieces}
+
+
+def habib_maurer_algorithm(graph, g_classes=None):
+    """
+    Compute the modular decomposition by the algorithm of Habib and Maurer.
+
+    Compute the modular decomposition of the given graph by the algorithm of
+    Habib and Maurer [HM1979]_ . If the graph is disconnected or its complement
+    is disconnected return a tree with a ``PARALLEL`` or ``SERIES`` node at the
+    root and children being the modular decomposition of the subgraphs induced
+    by the components. Otherwise, the root is ``PRIME`` and the modules are
+    identified by having identical neighborhoods in the gamma class that spans
+    the vertices of the subgraph (exactly one is guaranteed to exist). The gamma
+    classes only need to be computed once, as the algorithm computes the the
+    classes for the current root and each of the submodules. See also [BM1983]_
+    for an equivalent algorithm described in greater detail.
+
+    This function should not be used directly, it should be called via the
+    ``modular_decomposition`` method of ``Graph`` with the parameter
+    ``algorithm='habib_maurer'``.
+
+    This functions assumes that ``graph`` is a object of the class ``Graph``, is
+    a simple graph and has at least 1 vertex.
+
+    INPUT:
+
+    - ``graph`` -- the graph for which modular decomposition tree needs to be
+      computed
+
+    - ``g_classes`` -- dictionary (default: ``None``); a dictionary whose values
+      are the gamma classes of the graph, and whose keys are a frozenset of the
+      vertices corresponding to the class. Used internally.
+
+    OUTPUT: the modular decomposition tree of the graph
+
+    EXAMPLES:
+
+    The Icosahedral graph is Prime::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+        sage: print_md_tree(habib_maurer_algorithm(graphs.IcosahedralGraph()))
+        PRIME
+         3
+         4
+         7
+         9
+         11
+         1
+         5
+         8
+         0
+         2
+         6
+         10
+
+    The Octahedral graph is not Prime::
+
+        sage: print_md_tree(habib_maurer_algorithm(graphs.OctahedralGraph()))
+        SERIES
+         PARALLEL
+          0
+          5
+         PARALLEL
+          1
+          4
+         PARALLEL
+          2
+          3
+
+    Tetrahedral Graph is Series::
+
+        sage: print_md_tree(habib_maurer_algorithm(graphs.TetrahedralGraph()))
+        SERIES
+         0
+         1
+         2
+         3
+
+    Modular Decomposition tree containing both parallel and series modules::
+
+        sage: d = {2:[4,3,5], 1:[4,3,5], 5:[3,2,1,4], 3:[1,2,5], 4:[1,2,5]}
+        sage: g = Graph(d)
+        sage: print_md_tree(habib_maurer_algorithm(g))
+        SERIES
+         PARALLEL
+          1
+          2
+         PARALLEL
+          3
+          4
+         5
+
+    Graph from Marc Tedder implementation of modular decomposition::
+
+        sage: d = {1:[5,4,3,24,6,7,8,9,2,10,11,12,13,14,16,17], 2:[1],
+        ....:       3:[24,9,1], 4:[5,24,9,1], 5:[4,24,9,1], 6:[7,8,9,1],
+        ....:       7:[6,8,9,1], 8:[6,7,9,1], 9:[6,7,8,5,4,3,1], 10:[1],
+        ....:       11:[12,1], 12:[11,1], 13:[14,16,17,1], 14:[13,17,1],
+        ....:       16:[13,17,1], 17:[13,14,16,18,1], 18:[17], 24:[5,4,3,1]}
+        sage: g = Graph(d)
+        sage: test_modular_decomposition(habib_maurer_algorithm(g), g)
+        True
+
+    Tetrahedral Graph is Series::
+
+        sage: print_md_tree(habib_maurer_algorithm(graphs.TetrahedralGraph()))
+        SERIES
+         0
+         1
+         2
+         3
+
+    Modular Decomposition tree containing both parallel and series modules::
+
+        sage: d = {2:[4,3,5], 1:[4,3,5], 5:[3,2,1,4], 3:[1,2,5], 4:[1,2,5]}
+        sage: g = Graph(d)
+        sage: print_md_tree(habib_maurer_algorithm(g))
+        SERIES
+         PARALLEL
+          1
+          2
+         PARALLEL
+          3
+          4
+         5
+
+    TESTS:
+
+    Ensure that a random graph and an isomorphic graph have identical modular
+    decompositions. ::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import permute_decomposition
+        sage: permute_decomposition(2, habib_maurer_algorithm, 20, 0.5)                 # needs sage.groups
+    """
+    if graph.order() == 1:
+        root = Node.create_leaf(next(graph.vertex_iterator()))
+        return root
+
+    elif not graph.is_connected():
+        root = Node(NodeType.PARALLEL)
+        root.children = [habib_maurer_algorithm(graph.subgraph(vertices=sg), g_classes)
+                         for sg in graph.connected_components(sort=False)]
+        return root
+
+    g_comp = graph.complement()
+    if g_comp.is_connected():
+        from collections import defaultdict
+        root = Node(NodeType.PRIME)
+        if g_classes is None:
+            g_classes = gamma_classes(graph)
+        vertex_set = frozenset(graph)
+        edges = [tuple(e) for e in g_classes[vertex_set]]
+        sub = graph.subgraph(edges=edges)
+        d = defaultdict(list)
+        for v in sub:
+            for v1 in sub.neighbor_iterator(v):
+                d[v1].append(v)
+        d1 = defaultdict(list)
+        for k, v in d.items():
+            d1[frozenset(v)].append(k)
+        root.children = [habib_maurer_algorithm(graph.subgraph(vertices=sg), g_classes)
+                         for sg in d1.values()]
+        return root
+
+    root = Node(NodeType.SERIES)
+    root.children = [habib_maurer_algorithm(graph.subgraph(vertices=sg), g_classes)
+                     for sg in g_comp.connected_components(sort=False)]
+    return root
+
+
+################################################################################
+#                   Exported modular_decomposition function                    #
+################################################################################
+def modular_decomposition(G, algorithm=None):
+    r"""
+    Return the modular decomposition of the current graph.
+
+    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 *
+
+        sage: modular_decomposition(Graph())
+        EMPTY []
+
+        sage: modular_decomposition(Graph(1))
+        NORMAL [0]
+
+        sage: check_algos_are_equivalent(5,                                             # needs networkx
+        ....:                   lambda : graphs.RandomProperIntervalGraph(100))
+
+        sage: check_algos_are_equivalent(5, lambda : graphs.RandomGNM(75, 1000))        # needs networkx
+
+        sage: modular_decomposition(DiGraph())
+        Traceback (most recent call last):
+        ...
+        TypeError: the input must be an undirected Sage graph
+
+        sage: modular_decomposition(Graph(5, loops=True))
+        Traceback (most recent call last):
+        ...
+        ValueError: This method is not known to work on graphs with loops...
+
+        sage: modular_decomposition(Graph(5, multiedges=True))
+        Traceback (most recent call last):
+        ...
+        ValueError: This method is not known to work on graphs with multiedges...
+
+        sage: modular_decomposition(Graph(), algorithm='silly walk')
+        Traceback (most recent call last):
+        ...
+        ValueError: unknown algorithm "silly walk"
+    """
+    from sage.graphs.graph import Graph
+    if not isinstance(G, Graph):
+        raise TypeError("the input must be an undirected Sage graph")
+    G._scream_if_not_simple()
+
+    if algorithm is None:
+        algorithm = "corneil_habib_paul_tedder"
+
+    if algorithm not in ("habib_maurer", "corneil_habib_paul_tedder"):
+        raise ValueError(f'unknown algorithm "{algorithm}"')
+
+    if not G.order():
+        return Node(NodeType.EMPTY)
+    if G.order() == 1:
+        D = Node(NodeType.NORMAL)
+        D.children.append(next(G.vertex_iterator()))
+        return D
+    if algorithm == "habib_maurer":
+        return habib_maurer_algorithm(G)
+    return corneil_habib_paul_tedder_algorithm(G)
+
+
+# ============================================================================
+# Below functions are implemented to test the modular decomposition tree
+# ============================================================================
+# Function implemented for testing
+def test_modular_decomposition(tree_root, graph):
+    """
+    Test the input modular decomposition tree using recursion.
+
+    INPUT:
+
+    - ``tree_root`` -- root of the modular decomposition tree to be tested
+
+    - ``graph`` -- graph whose modular decomposition tree needs to be tested
+
+    OUTPUT: ``True`` if input tree is a modular decomposition else ``False``
+
+    EXAMPLES::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+        sage: g = graphs.HexahedralGraph()
+        sage: test_modular_decomposition(modular_decomposition(g), g)
+        True
+    """
+    if tree_root.node_type != NodeType.NORMAL:
+        for module in tree_root.children:
+            if not test_module(module, graph):
+                # test whether modules pass the defining
+                # characteristics of modules
+                return False
+            if not test_modular_decomposition(module,
+                                              graph.subgraph(get_vertices(module))):
+                # recursively test the modular decomposition subtrees
+                return False
+
+        if not test_maximal_modules(tree_root, graph):
+            # test whether the mdoules are maximal in nature
+            return False
+
+    return True
+
+
+# Function implemented for testing
+def test_maximal_modules(tree_root, graph):
+    r"""
+    Test the maximal nature of modules in a modular decomposition tree.
+
+    Suppose the module `M = [M_1, M_2, \cdots, n]` is the input modular
+    decomposition tree. Algorithm forms pairs like `(M_1, M_2), (M_1, M_3),
+    \cdots, (M_1, M_n)`; `(M_2, M_3), (M_2, M_4), \cdots, (M_2, M_n)`; `\cdots`
+    and so on and tries to form a module using the pair. If the module formed
+    has same type as `M` and is of type ``SERIES`` or ``PARALLEL`` then the
+    formed module is not considered maximal. Otherwise it is considered maximal
+    and `M` is not a modular decomposition tree.
+
+    INPUT:
+
+    - ``tree_root`` -- modular decomposition tree whose modules are tested for
+      maximal nature
+
+    - ``graph`` -- graph whose modular decomposition tree is tested
+
+    OUTPUT:
+
+    ``True`` if all modules at first level in the modular decomposition tree
+    are maximal in nature
+
+    EXAMPLES::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+        sage: g = graphs.HexahedralGraph()
+        sage: test_maximal_modules(modular_decomposition(g), g)
+        True
+    """
+    if tree_root.node_type != NodeType.NORMAL:
+        for index, module in enumerate(tree_root.children):
+            for other_index in range(index + 1, len(tree_root.children)):
+
+                # compute the module formed using modules at index and
+                # other_index
+                module_formed = form_module(index, other_index,
+                                            tree_root, graph)
+
+                if module_formed[0]:
+                    # Module formed and the parent of the formed module
+                    # should not both be of type SERIES or PARALLEL
+                    mod_type = get_module_type(graph.subgraph(module_formed[1]))
+                    if (mod_type == tree_root.node_type and
+                            (tree_root.node_type == NodeType.PARALLEL or
+                             tree_root.node_type == NodeType.SERIES)):
+                        continue
+                    return False
+    return True
+
+
+def get_vertices(component_root):
+    """
+    Compute the list of vertices in the (co)component.
+
+    INPUT:
+
+    - ``component_root`` -- root of the (co)component whose vertices need to be
+      returned as a list
+
+    OUTPUT:
+
+    list of vertices in the (co)component
+
+    EXAMPLES::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+        sage: forest = Node(NodeType.PRIME)
+        sage: forest.children = [Node.create_leaf(2), Node.create_leaf(0),
+        ....:                    Node.create_leaf(3), Node.create_leaf(1)]
+        sage: series_node = Node(NodeType.SERIES)
+        sage: series_node.children = [Node.create_leaf(4),
+        ....:                         Node.create_leaf(5)]
+        sage: parallel_node = Node(NodeType.PARALLEL)
+        sage: parallel_node.children = [Node.create_leaf(6),
+        ....:                           Node.create_leaf(7)]
+        sage: forest.children.insert(1, series_node)
+        sage: forest.children.insert(3, parallel_node)
+        sage: get_vertices(forest)
+        [2, 4, 5, 0, 6, 7, 3, 1]
+    """
+    vertices = []
+
+    # inner recursive function to recurse over the elements in the
+    # ``component``
+    def recurse_component(node, vertices):
+        if node.node_type == NodeType.NORMAL:
+            vertices.append(node.children[0])
+            return
+        for child in node.children:
+            recurse_component(child, vertices)
+
+    recurse_component(component_root, vertices)
+    return vertices
+
+
+# Function implemented for testing
+def get_module_type(graph):
+    """
+    Return the module type of the root of the modular decomposition tree of
+    ``graph``.
+
+    INPUT:
+
+    - ``graph`` -- input sage graph
+
+    OUTPUT:
+
+    ``PRIME`` if graph is PRIME, ``PARALLEL`` if graph is PARALLEL and
+    ``SERIES`` if graph is of type SERIES
+
+    EXAMPLES::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import get_module_type
+        sage: g = graphs.HexahedralGraph()
+        sage: get_module_type(g)
+        PRIME
+    """
+    if not graph.is_connected():
+        return NodeType.PARALLEL
+    elif graph.complement().is_connected():
+        return NodeType.PRIME
+    return NodeType.SERIES
+
+
+# Function implemented for testing
+def form_module(index, other_index, tree_root, graph):
+    r"""
+    Forms a module out of the modules in the module pair.
+
+    Let `M_1` and `M_2` be the input modules. Let `V` be the set of vertices in
+    these modules. Suppose `x` is a neighbor of subset of the vertices in `V`
+    but not all the vertices and `x` does not belong to `V`. Then the set of
+    modules also include the module which contains `x`. This process is repeated
+    until a module is formed and the formed module if subset of `V` is returned.
+
+    INPUT:
+
+    - ``index`` -- first module in the module pair
+
+    - ``other_index`` -- second module in the module pair
+
+    - ``tree_root`` -- modular decomposition tree which contains the modules
+      in the module pair
+
+    - ``graph`` -- graph whose modular decomposition tree is created
+
+    OUTPUT:
+
+    ``[module_formed, vertices]`` where ``module_formed`` is ``True`` if
+    module is formed else ``False`` and ``vertices`` is a list of vertices
+    included in the formed module
+
+    EXAMPLES::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+        sage: g = graphs.HexahedralGraph()
+        sage: tree_root = modular_decomposition(g)
+        sage: form_module(0, 2, tree_root, g)
+        [False, {0, 1, 2, 3, 4, 5, 6, 7}]
+    """
+    vertices = set(get_vertices(tree_root.children[index]))
+    vertices.update(get_vertices(tree_root.children[other_index]))
+
+    # stores all neighbors which are common for all vertices in V
+    common_neighbors = set()
+
+    # stores all neighbors of vertices in V which are outside V
+    all_neighbors = set()
+
+    while True:
+        # remove vertices from all_neighbors and common_neighbors
+        all_neighbors.difference_update(vertices)
+        common_neighbors.difference_update(vertices)
+
+        for v in vertices:
+            # stores the neighbors of v which are outside the set of vertices
+            neighbor_list = set(graph.neighbors(v))
+            neighbor_list.difference_update(vertices)
+
+            # update all_neighbors and common_neighbors using the
+            # neighbor_list
+            all_neighbors.update(neighbor_list)
+            common_neighbors.intersection_update(neighbor_list)
+
+        if all_neighbors == common_neighbors:  # indicates a module is formed
+
+            # module formed covers the entire graph
+            if len(vertices) == graph.order():
+                return [False, vertices]
+
+            return [True, vertices]
+
+        # add modules containing uncommon neighbors into the formed module
+        for v in (all_neighbors - common_neighbors):
+            for index in range(len(tree_root.children)):
+                if v in get_vertices(tree_root.children[index]):
+                    vertices.update(get_vertices(tree_root.children[index]))
+                    break
+
+
+# Function implemented for testing
+def test_module(module, graph):
+    """
+    Test whether input module is actually a module.
+
+    INPUT:
+
+    - ``module`` -- module which needs to be tested
+
+    - ``graph`` -- input sage graph which contains the module
+
+    OUTPUT: ``True`` if input module is a module by definition else ``False``
+
+    EXAMPLES::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+        sage: g = graphs.HexahedralGraph()
+        sage: tree_root = modular_decomposition(g)
+        sage: test_module(tree_root, g)
+        True
+        sage: test_module(tree_root.children[0], g)
+        True
+    """
+    # A single vertex is a module
+    if module.node_type == NodeType.NORMAL:
+        return True
+
+    # vertices contained in module
+    vertices_in_module = get_vertices(module)
+
+    # vertices outside module
+    vertices_outside = list(set(graph.vertices(sort=False)) - set(vertices_in_module))
+
+    # Nested module with only one child
+    if module.node_type != NodeType.NORMAL and len(module.children) == 1:
+        return False
+
+    # If children of SERIES module are all SERIES modules
+    if module.node_type == NodeType.SERIES:
+        if children_node_type(module, NodeType.SERIES):
+            return False
+
+    # If children of PARALLEL module are all PARALLEL modules
+    if module.node_type == NodeType.PARALLEL:
+        if children_node_type(module, NodeType.PARALLEL):
+            return False
+
+    # check the module by definition. Vertices in a module should all either
+    # be connected or disconnected to any vertex outside module
+    for v in vertices_outside:
+        if not either_connected_or_not_connected(v, vertices_in_module, graph):
+            return False
+    return True
+
+
+# Function implemented for testing
+def children_node_type(module, node_type):
+    """
+    Check whether the node type of the children of ``module`` is ``node_type``.
+
+    INPUT:
+
+    - ``module`` -- module which is tested
+
+    - ``node_type`` -- input node_type
+
+    EXAMPLES::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+        sage: g = graphs.OctahedralGraph()
+        sage: tree_root = modular_decomposition(g)
+        sage: print_md_tree(tree_root)
+        SERIES
+         PARALLEL
+          2
+          3
+         PARALLEL
+          1
+          4
+         PARALLEL
+          0
+          5
+        sage: children_node_type(tree_root, NodeType.SERIES)
+        False
+        sage: children_node_type(tree_root, NodeType.PARALLEL)
+        True
+    """
+    return all(node.node_type == node_type for node in module.children)
+
+
+# Function implemented for testing
+def either_connected_or_not_connected(v, vertices_in_module, graph):
+    """
+    Check whether ``v`` is connected or disconnected to all vertices in the
+    module.
+
+    INPUT:
+
+    - ``v`` -- vertex tested
+
+    - ``vertices_in_module`` -- list containing vertices in the module
+
+    - ``graph`` -- graph to which the vertices belong
+
+    EXAMPLES::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+        sage: g = graphs.OctahedralGraph()
+        sage: print_md_tree(modular_decomposition(g))
+        SERIES
+         PARALLEL
+          2
+          3
+         PARALLEL
+          1
+          4
+         PARALLEL
+          0
+          5
+        sage: either_connected_or_not_connected(2, [1, 4], g)
+        True
+        sage: either_connected_or_not_connected(2, [3, 4], g)
+        False
+    """
+    # marks whether vertex v is connected to first vertex in the module
+    connected = graph.has_edge(vertices_in_module[0], v)
+
+    # if connected is True then all vertices in module should be connected to
+    # v else all should be disconnected
+    return all(graph.has_edge(u, v) == connected for u in vertices_in_module)
+
+
+def tree_to_nested_tuple(root):
+    r"""
+    Convert a modular decomposition tree to a nested tuple.
+
+    INPUT:
+
+    - ``root`` -- the root of the modular decomposition tree
+
+    OUTPUT:
+
+    A tuple whose first element is the type of the root of the tree and whose
+    subsequent nodes are either vertex labels in the case of leaves or tuples
+    representing the child subtrees.
+
+    EXAMPLES::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+        sage: g = graphs.OctahedralGraph()
+        sage: tree_to_nested_tuple(modular_decomposition(g))
+        (SERIES, [(PARALLEL, [2, 3]), (PARALLEL, [1, 4]), (PARALLEL, [0, 5])])
+    """
+    if root.node_type == NodeType.NORMAL:
+        return root.children[0]
+    else:
+        return (root.node_type, [tree_to_nested_tuple(x) for x in root.children])
+
+
+def nested_tuple_to_tree(nest):
+    r"""
+    Turn a tuple representing the modular decomposition into a tree.
+
+    INPUT:
+
+    - ``nest`` -- a nested tuple of the form returned by
+      :meth:`tree_to_nested_tuple`
+
+    OUTPUT: the root node of a modular decomposition tree
+
+    EXAMPLES::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+        sage: tree = (NodeType.SERIES, 1, 2, (NodeType.PARALLEL, 3, 4))
+        sage: print_md_tree(nested_tuple_to_tree(tree))
+        SERIES
+         1
+         2
+         PARALLEL
+          3
+          4
+    """
+    if not isinstance(nest, tuple):
+        return Node.create_leaf(nest)
+
+    root = Node(nest[0])
+    root.children = [nested_tuple_to_tree(n) for n in nest[1:]]
+    return root
+
+
+def equivalent_trees(root1, root2):
+    r"""
+    Check that two modular decomposition trees are the same.
+
+    Verify that the structure of the trees is the same. Two leaves are
+    equivalent if they represent the same vertex, two internal nodes are
+    equivalent if they have the same nodes type and the same number of children
+    and there is a matching between the children such that each pair of
+    children is a pair of equivalent subtrees.
+
+    EXAMPLES::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+        sage: t1 = nested_tuple_to_tree((NodeType.SERIES, 1, 2,
+        ....:             (NodeType.PARALLEL, 3, 4)))
+        sage: t2 = nested_tuple_to_tree((NodeType.SERIES,
+        ....:             (NodeType.PARALLEL, 4, 3), 2, 1))
+        sage: equivalent_trees(t1, t2)
+        True
+    """
+    # internal definition
+    def node_id(root):
+        return (root.node_type, frozenset(get_vertices(root)))
+
+    if root1.node_type != root2.node_type:
+        return False
+
+    if len(root1.children) != len(root2.children):
+        return False
+
+    if root1.node_type == NodeType.NORMAL:
+        return root1.children[0] == root2.children[0]
+
+    child_map = {}
+    for node in root2.children:
+        child_map[node_id(node)] = node
+
+    for node in root1.children:
+        id = node_id(node)
+        if id not in child_map:
+            return False
+        if not equivalent_trees(node, child_map[id]):
+            return False
+
+    return True
+
+
+def relabel_tree(root, perm):
+    r"""
+    Relabel the leaves of a tree according to a dictionary.
+
+    INPUT:
+
+    - ``root`` -- the root of the tree
+
+    - ``perm`` -- a function, dictionary, list, permutation, or ``None``
+      representing the relabeling. See
+      :meth:`~sage.graphs.generic_graph.GenericGraph.relabel` for description of
+      the permutation input.
+
+    EXAMPLES::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+        sage: tuple_tree = (NodeType.SERIES, 1, 2, (NodeType.PARALLEL, 3, 4))
+        sage: tree = nested_tuple_to_tree(tuple_tree)
+        sage: print_md_tree(relabel_tree(tree, (4,3,2,1)))
+        SERIES
+         4
+         3
+         PARALLEL
+          2
+          1
+    """
+    # If perm is not a dictionary, we build one !
+    if perm is None:
+
+        # vertices() returns a sorted list:
+        # this guarantees consistent relabeling
+        perm = {v: i for i, v in enumerate(get_vertices(root))}
+
+    elif isinstance(perm, dict):
+        from copy import copy
+        # If all vertices do not have a new label, the code will touch the
+        # dictionary. Let us keep the one we received from the user clean !
+        perm = copy(perm)
+
+    elif isinstance(perm, (list, tuple)):
+        perm = dict(zip(sorted(get_vertices(root)), perm))
+
+    elif isinstance(perm, PermutationGroupElement):
+        n = len(get_vertices(root))
+        ddict = {}
+        for i in range(1, n):
+            ddict[i] = perm(i) % n
+        if n > 0:
+            ddict[0] = perm(n) % n
+        perm = ddict
+
+    elif callable(perm):
+        perm = {i: perm(i) for i in get_vertices(root)}
+
+    else:
+        raise TypeError("type of perm is not supported for relabeling")
+
+    if root.node_type == NodeType.NORMAL:
+        return Node.create_leaf(perm[root.children[0]])
+    else:
+        new_root = Node(root.node_type)
+        new_root.children = [relabel_tree(child, perm) for child in root.children]
+        return new_root
+
+
+# =============================================================================
+# Random tests
+# =============================================================================
+
+@random_testing
+def test_gamma_modules(trials, vertices, prob, verbose=False):
+    r"""
+    Verify that the vertices of each gamma class of a random graph are modules
+    of that graph.
+
+    INPUT:
+
+    - ``trials`` -- the number of trials to run
+
+    - ``vertices`` -- the size of the graph to use
+
+    - ``prob`` -- the probability that any given edge is in the graph
+      See :meth:`~sage.graphs.generators.random.RandomGNP` for more details
+
+    - ``verbose`` -- print information on each trial
+
+    EXAMPLES::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+        sage: test_gamma_modules(3, 7, 0.5)
+    """
+    from sage.graphs.generators.random import RandomGNP
+    for _ in range(trials):
+        g = RandomGNP(vertices, prob)
+        if verbose:
+            print(g.graph6_string())
+        g_classes = gamma_classes(g)
+        for module in g_classes.keys():
+            m_list = list(module)
+            for v in g:
+                if v not in module:
+                    assert either_connected_or_not_connected(v, m_list, g)
+        if verbose:
+            print("Passes!")
+
+
+@random_testing
+def permute_decomposition(trials, algorithm, vertices, prob, verbose=False):
+    r"""
+    Check that a graph and its permuted relabeling have the same modular
+    decomposition.
+
+    We generate a ``trials`` random graphs and then generate an isomorphic graph
+    by relabeling the original graph. We then verify
+
+    EXAMPLES::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+        sage: permute_decomposition(30, habib_maurer_algorithm, 10, 0.5)
+    """
+    from sage.graphs.generators.random import RandomGNP
+    from sage.combinat.permutation import Permutations
+    for _ in range(trials):
+        g1 = RandomGNP(vertices, prob)
+        random_perm = Permutations(list(g1)).random_element()
+        g2 = g1.relabel(perm=random_perm, inplace=False)
+        if verbose:
+            print(g1.graph6_string())
+            print(random_perm)
+        t1 = algorithm(g1)
+        t2 = algorithm(g2)
+        assert test_modular_decomposition(t1, g1)
+        assert test_modular_decomposition(t2, g2)
+        t1p = relabel_tree(t1, random_perm)
+        assert equivalent_trees(t1p, t2)
+        if verbose:
+            print("Passes!")
+
+
+def random_md_tree(max_depth, max_fan_out, leaf_probability):
+    r"""
+    Create a random MD tree.
+
+    INPUT:
+
+    - ``max_depth`` -- the maximum depth of the tree
+
+    - ``max_fan_out`` -- the maximum number of children a node can have
+      (must be >=4 as a prime node must have at least 4 vertices)
+
+    - ``leaf_probability`` -- the probability that a subtree is a leaf
+
+    EXAMPLES::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+        sage: set_random_seed(0)
+        sage: tree_to_nested_tuple(random_md_tree(2, 5, 0.5))
+        (PRIME, [0, 1, (PRIME, [2, 3, 4, 5, 6]), 7, (PARALLEL, [8, 9, 10])])
+    """
+
+    from sage.misc.prandom import choice, randint, random
+
+    if max_fan_out < 4:
+        raise ValueError("max_fan_out must be at least 4")
+
+    # Internal function
+    def rand_md_tree(max_depth, parent_type):
+        r"""
+        Create the subtrees of a node.
+
+        A child of a node cannot have the same node type as its parent if its
+        parent's node type is either PARALLEL or SERIES.  Also its ``max_depth``
+        is one less than its parent's.
+        """
+        if random() < leaf_probability or max_depth == 1:
+            root = Node.create_leaf(current_leaf[0])
+            current_leaf[0] += 1
+            return root
+        if parent_type == NodeType.PRIME:
+            node_type = choice([NodeType.PRIME, NodeType.SERIES, NodeType.PARALLEL])
+        elif parent_type == NodeType.SERIES:
+            node_type = choice([NodeType.PRIME, NodeType.PARALLEL])
+        else:
+            node_type = choice([NodeType.PRIME, NodeType.SERIES])
+        if node_type == NodeType.PRIME:
+            num_children = randint(4, max_fan_out)
+        else:
+            num_children = randint(2, max_fan_out)
+        root = Node(node_type)
+        root.children = [rand_md_tree(max_depth - 1, node_type)
+                         for _ in range(num_children)]
+        return root
+
+    # a hack around python2's lack of 'nonlocal'
+    current_leaf = [0]
+    node_type = choice([NodeType.PRIME, NodeType.SERIES, NodeType.PARALLEL])
+    num_children = randint(4, max_fan_out)
+    root = Node(node_type)
+    root.children = [rand_md_tree(max_depth, node_type)
+                     for _ in range(num_children)]
+    return root
+
+
+def md_tree_to_graph(root, prime_node_generator=None):
+    r"""
+    Create a graph having the given MD tree.
+
+    For the prime nodes, the parameter ``prime_node_generator`` is called with
+    the number of vertices as the only argument. If it is ``None``, the path
+    graph is used (it is prime when the length is 4 or more).
+
+    EXAMPLES::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+        sage: from sage.graphs.graph_generators import graphs
+        sage: tup1 = (NodeType.PRIME, 1, (NodeType.SERIES, 2, 3),
+        ....:        (NodeType.PARALLEL, 4, 5), 6)
+        sage: tree1 = nested_tuple_to_tree(tup1)
+        sage: g1 = md_tree_to_graph(tree1)
+        sage: g2 = Graph({1: [2, 3], 2: [1, 3, 4, 5], 3: [1, 2, 4, 5],
+        ....:             4: [2, 3, 6], 5: [2, 3, 6], 6: [4, 5]})
+        sage: g1.is_isomorphic(g2)
+        True
+
+        sage: G = md_tree_to_graph(Node(NodeType.EMPTY))
+        sage: G.is_isomorphic(Graph())
+        True
+
+        sage: tree = Node(NodeType.SERIES)
+        sage: tree.children.extend(Node.create_leaf(i) for i in range(5))
+        sage: G = md_tree_to_graph(tree)
+        sage: G.is_isomorphic(graphs.CompleteGraph(5))
+        True
+
+        sage: tree = Node(NodeType.PRIME)
+        sage: tree.children.extend(Node.create_leaf(i) for i in range(5))
+        sage: png = lambda n: (graphs.PathGraph if n == 4 else graphs.CycleGraph)(n)
+        sage: G = md_tree_to_graph(tree, prime_node_generator=png)
+        sage: G.is_isomorphic(graphs.CycleGraph(5))
+        True
+    """
+    from itertools import product, combinations
+    from sage.graphs.graph import Graph
+
+    if prime_node_generator is None:
+        from sage.graphs.graph_generators import graphs
+        prime_node_generator = graphs.PathGraph
+
+    def tree_to_vertices_and_edges(root):
+        r"""
+        Give the list of vertices and edges of the graph having the given md tree.
+        """
+        if root.is_leaf():
+            return (root.children, [])
+        children_ve = [tree_to_vertices_and_edges(child) for child in root.children]
+        vertices = [v for vs, es in children_ve for v in vs]
+        edges = [e for vs, es in children_ve for e in es]
+        vertex_lists = [vs for vs, es in children_ve]
+        if root.is_prime():
+            G = prime_node_generator(len(vertex_lists))
+            G.relabel(range(len(vertex_lists)))
+            for i1, i2 in G.edge_iterator(labels=False):
+                edges.extend(product(vertex_lists[i1], vertex_lists[i2]))
+        elif root.is_series():
+            for vs1, vs2 in combinations(vertex_lists, 2):
+                edges.extend(product(vs1, vs2))
+        # else: no edge to be created for PARALLEL nodes
+        return (vertices, edges)
+
+    if root.is_empty():
+        return Graph()
+    vs, es = tree_to_vertices_and_edges(root)
+    return Graph([vs, es], format='vertices_and_edges')
+
+
+@random_testing
+def recreate_decomposition(trials, algorithm, max_depth, max_fan_out,
+                           leaf_probability, verbose=False):
+    r"""
+    Verify that we can recreate a random MD tree.
+
+    We create a random MD tree, then create a graph having that decomposition,
+    then find a modular decomposition for that graph, and verify that the two
+    modular decomposition trees are equivalent.
+
+    EXAMPLES::
+
+        sage: from sage.graphs.graph_decompositions.modular_decomposition import *
+        sage: recreate_decomposition(3, habib_maurer_algorithm, 4, 6, 0.5,
+        ....:                         verbose=False)
+    """
+    for _ in range(trials):
+        rand_tree = random_md_tree(max_depth, max_fan_out, leaf_probability)
+        if verbose:
+            print_md_tree(rand_tree)
+        graph = md_tree_to_graph(rand_tree)
+        if verbose:
+            print(graph.graph6_string())
+            print(graph.to_dictionary())
+        reconstruction = algorithm(graph)
+        if verbose:
+            print_md_tree(reconstruction)
+        assert equivalent_trees(rand_tree, reconstruction)
+        if verbose:
+            print("Passes!")
+
+
+@random_testing
+def check_algos_are_equivalent(trials, graph_gen, verbose=False):
+    r"""
+    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()
+        if verbose:
+            print(graph.graph6_string())
+            print(graph.to_dictionary())
+        MD = []
+        for algo in ('habib_maurer', 'corneil_habib_paul_tedder'):
+            md = modular_decomposition(graph, algorithm=algo)
+            MD.append(md)
+            if verbose:
+                print(f'Using {algo}:')
+                print_md_tree(md)
+        assert equivalent_trees(MD[0], MD[1])
+        if verbose:
+            print("Passes!")