Trac #22559: Matchings in Bipartite Graphs

The Hopcroft-Karp and Eppstein algorithms as implemented in NetworkX
compute matchings for bipartite graphs faster than the algorithms for
general graphs. I've included an override of the matching method in the
bipartite graph class, with parameters that allow for using the old
algorithms if desired.

URL: https://trac.sagemath.org/22559
Reported by: zgershkoff
Ticket author(s): Zachary Gershkoff
Reviewer(s): Julian Rüth, Travis Scrimshaw, David Coudert

Author: Release Manager

src/sage/graphs/bipartite_graph.py

@@ -33,9 +33,11 @@
 #*****************************************************************************
 from __future__ import print_function
 from __future__ import absolute_import
+from six import iteritems
 from six.moves import range
 
 from .graph import Graph
+from sage.rings.integer import Integer
 
 class BipartiteGraph(Graph):
     r"""
@@ -1281,3 +1283,135 @@ def reduced_adjacency_matrix(self, sparse=True):
         # now construct and return the matrix from the dictionary we created
         from sage.matrix.constructor import matrix
         return matrix(len(self.right), len(self.left), D, sparse=sparse)
+
+    def matching(self, value_only=False, algorithm=None,
+                 use_edge_labels=False, solver=None, verbose=0):
+        r"""
+        Return a maximum matching of the graph represented by the list of its
+        edges.
+
+        Given a graph `G` such that each edge `e` has a weight `w_e`, a maximum
+        matching is a subset `S` of the edges of `G` of maximum weight such that
+        no two edges of `S` are incident with each other.
+
+        INPUT:
+
+        - ``value_only`` -- boolean (default: ``False``); when set to ``True``,
+          only the cardinal (or the weight) of the matching is returned
+
+        - ``algorithm`` -- string (default: ``"Hopcroft-Karp"`` if
+          ``use_edge_labels==False``, otherwise ``"Edmonds"``)
+
+          - ``"Hopcroft-Karp"`` selects the default bipartite graph algorithm as
+            implemented in NetworkX
+
+          - ``"Eppstein"`` selects Eppstein's algorithm as implemented in
+            NetworkX
+
+          - ``"Edmonds"`` selects Edmonds' algorithm as implemented in NetworkX
+
+          - ``"LP"`` uses a Linear Program formulation of the matching problem
+
+        - ``use_edge_labels`` -- boolean (default: ``False``)
+
+          - when set to ``True``, computes a weighted matching where each edge
+            is weighted by its label (if an edge has no label, `1` is assumed);
+            only if ``algorithm`` is ``"Edmonds"``, ``"LP"``
+
+          - when set to ``False``, each edge has weight `1`
+
+        - ``solver`` -- (default: ``None``) a specific Linear Program (LP)
+          solver to be used
+
+        - ``verbose`` -- integer (default: ``0``); sets the level of verbosity:
+          set to 0 by default, which means quiet
+
+        .. SEEALSO::
+
+            - :wikipedia:`Matching_(graph_theory)`
+            - :meth:`~Graph.matching`
+
+        EXAMPLES:
+
+        Maximum matching in a cycle graph::
+
+            sage: G = BipartiteGraph(graphs.CycleGraph(10))
+            sage: G.matching()
+            [(0, 1, None), (2, 3, None), (4, 5, None), (6, 7, None), (8, 9, None)]
+
+        The size of a maximum matching in a complete bipartite graph using
+        Eppstein::
+
+            sage: G = BipartiteGraph(graphs.CompleteBipartiteGraph(4,5))
+            sage: G.matching(algorithm="Eppstein", value_only=True)
+            4
+
+        TESTS:
+
+        If ``algorithm`` is not set to one of the supported algorithms, an
+        exception is raised::
+
+            sage: G = BipartiteGraph(graphs.CompleteBipartiteGraph(4,5))
+            sage: G.matching(algorithm="somethingdifferent")
+            Traceback (most recent call last):
+            ...
+            ValueError: algorithm must be "Hopcroft-Karp", "Eppstein", "Edmonds" or "LP"
+
+        Maximum matching in a weighted bipartite graph::
+
+            sage: G = graphs.CycleGraph(4)
+            sage: B = BipartiteGraph([(u,v,2) for u,v in G.edges(labels=0)])
+            sage: B.matching(use_edge_labels=True)
+            [(0, 3, 2), (1, 2, 2)]
+            sage: B.matching(use_edge_labels=True, value_only=True)
+            4
+            sage: B.matching(use_edge_labels=True, value_only=True, algorithm='Edmonds')
+            4
+            sage: B.matching(use_edge_labels=True, value_only=True, algorithm='LP')
+            4.0
+            sage: B.matching(use_edge_labels=True, value_only=True, algorithm='Eppstein')
+            Traceback (most recent call last):
+            ...
+            ValueError: use_edge_labels can not be used with "Hopcroft-Karp" or "Eppstein"
+            sage: B.matching(use_edge_labels=True, value_only=True, algorithm='Hopcroft-Karp')
+            Traceback (most recent call last):
+            ...
+            ValueError: use_edge_labels can not be used with "Hopcroft-Karp" or "Eppstein"
+            sage: B.matching(use_edge_labels=False, value_only=True, algorithm='Hopcroft-Karp')
+            2
+            sage: B.matching(use_edge_labels=False, value_only=True, algorithm='Eppstein')
+            2
+            sage: B.matching(use_edge_labels=False, value_only=True, algorithm='Edmonds')
+            2
+            sage: B.matching(use_edge_labels=False, value_only=True, algorithm='LP')
+            2
+        """
+        self._scream_if_not_simple()
+
+        if algorithm is None:
+            algorithm = "Edmonds" if use_edge_labels else "Hopcroft-Karp"
+
+        if algorithm == "Hopcroft-Karp" or algorithm == "Eppstein":
+            if use_edge_labels:
+                raise ValueError('use_edge_labels can not be used with ' +
+                                 '"Hopcroft-Karp" or "Eppstein"')
+            import networkx
+            #this is necessary to call the methods for bipartite matchings
+            g = self.networkx_graph()
+            if algorithm == "Hopcroft-Karp":
+                d = networkx.bipartite.hopcroft_karp_matching(g)
+            else:
+                d = networkx.bipartite.eppstein_matching(g)
+            if value_only:
+                return Integer(len(d) // 2)
+            else:
+                return [(u, v, self.edge_label(u, v))
+                        for u, v in iteritems(d) if u < v]
+        elif algorithm == "Edmonds" or algorithm == "LP":
+            return Graph.matching(self, value_only=value_only,
+                                  algorithm=algorithm,
+                                  use_edge_labels=use_edge_labels,
+                                  solver=solver, verbose=verbose)
+        else:
+            raise ValueError('algorithm must be "Hopcroft-Karp", ' +
+                             '"Eppstein", "Edmonds" or "LP"')