581 lines
21 KiB
Python
581 lines
21 KiB
Python
|
# matching.py - bipartite graph maximum matching algorithms
|
|||
|
|
#
|
|||
|
|
# Copyright 2015 Jeffrey Finkelstein <jeffrey.finkelstein@gmail.com>,
|
|||
|
|
# Copyright 2019 Søren Fuglede Jørgensen
|
|||
|
|
#
|
|||
|
|
# This file is part of NetworkX.
|
|||
|
|
#
|
|||
|
|
# NetworkX is distributed under a BSD license; see LICENSE.txt for more
|
|||
|
|
# information.
|
|||
|
|
#
|
|||
|
|
# This module uses material from the Wikipedia article Hopcroft--Karp algorithm
|
|||
|
|
# <https://en.wikipedia.org/wiki/Hopcroft%E2%80%93Karp_algorithm>, accessed on
|
|||
|
|
# January 3, 2015, which is released under the Creative Commons
|
|||
|
|
# Attribution-Share-Alike License 3.0
|
|||
|
|
# <http://creativecommons.org/licenses/by-sa/3.0/>. That article includes
|
|||
|
|
# pseudocode, which has been translated into the corresponding Python code.
|
|||
|
|
#
|
|||
|
|
# Portions of this module use code from David Eppstein's Python Algorithms and
|
|||
|
|
# Data Structures (PADS) library, which is dedicated to the public domain (for
|
|||
|
|
# proof, see <http://www.ics.uci.edu/~eppstein/PADS/ABOUT-PADS.txt>).
|
|||
|
|
"""Provides functions for computing maximum cardinality matchings and minimum
|
|||
|
|
weight full matchings in a bipartite graph.
|
|||
|
|
|
|||
|
|
If you don't care about the particular implementation of the maximum matching
|
|||
|
|
algorithm, simply use the :func:`maximum_matching`. If you do care, you can
|
|||
|
|
import one of the named maximum matching algorithms directly.
|
|||
|
|
|
|||
|
|
For example, to find a maximum matching in the complete bipartite graph with
|
|||
|
|
two vertices on the left and three vertices on the right:
|
|||
|
|
|
|||
|
|
>>> import networkx as nx
|
|||
|
|
>>> G = nx.complete_bipartite_graph(2, 3)
|
|||
|
|
>>> left, right = nx.bipartite.sets(G)
|
|||
|
|
>>> list(left)
|
|||
|
|
[0, 1]
|
|||
|
|
>>> list(right)
|
|||
|
|
[2, 3, 4]
|
|||
|
|
>>> nx.bipartite.maximum_matching(G)
|
|||
|
|
{0: 2, 1: 3, 2: 0, 3: 1}
|
|||
|
|
|
|||
|
|
The dictionary returned by :func:`maximum_matching` includes a mapping for
|
|||
|
|
vertices in both the left and right vertex sets.
|
|||
|
|
|
|||
|
|
Similarly, :func:`minimum_weight_full_matching` produces, for a complete
|
|||
|
|
weighted bipartite graph, a matching whose cardinality is the cardinality of
|
|||
|
|
the smaller of the two partitions, and for which the sum of the weights of the
|
|||
|
|
edges included in the matching is minimal.
|
|||
|
|
|
|||
|
|
"""
|
|||
|
|
import collections
|
|||
|
|
import itertools
|
|||
|
|
|
|||
|
|
from networkx.algorithms.bipartite.matrix import biadjacency_matrix
|
|||
|
|
from networkx.algorithms.bipartite import sets as bipartite_sets
|
|||
|
|
import networkx as nx
|
|||
|
|
|
|||
|
|
__all__ = ['maximum_matching', 'hopcroft_karp_matching', 'eppstein_matching',
|
|||
|
|
'to_vertex_cover', 'minimum_weight_full_matching']
|
|||
|
|
|
|||
|
|
INFINITY = float('inf')
|
|||
|
|
|
|||
|
|
|
|||
|
|
def hopcroft_karp_matching(G, top_nodes=None):
|
|||
|
|
"""Returns the maximum cardinality matching of the bipartite graph `G`.
|
|||
|
|
|
|||
|
|
Parameters
|
|||
|
|
----------
|
|||
|
|
G : NetworkX graph
|
|||
|
|
|
|||
|
|
Undirected bipartite graph
|
|||
|
|
|
|||
|
|
top_nodes : container
|
|||
|
|
|
|||
|
|
Container with all nodes in one bipartite node set. If not supplied
|
|||
|
|
it will be computed. But if more than one solution exists an exception
|
|||
|
|
will be raised.
|
|||
|
|
|
|||
|
|
Returns
|
|||
|
|
-------
|
|||
|
|
matches : dictionary
|
|||
|
|
|
|||
|
|
The matching is returned as a dictionary, `matches`, such that
|
|||
|
|
``matches[v] == w`` if node `v` is matched to node `w`. Unmatched
|
|||
|
|
nodes do not occur as a key in mate.
|
|||
|
|
|
|||
|
|
Raises
|
|||
|
|
------
|
|||
|
|
AmbiguousSolution : Exception
|
|||
|
|
|
|||
|
|
Raised if the input bipartite graph is disconnected and no container
|
|||
|
|
with all nodes in one bipartite set is provided. When determining
|
|||
|
|
the nodes in each bipartite set more than one valid solution is
|
|||
|
|
possible if the input graph is disconnected.
|
|||
|
|
|
|||
|
|
Notes
|
|||
|
|
-----
|
|||
|
|
This function is implemented with the `Hopcroft--Karp matching algorithm
|
|||
|
|
<https://en.wikipedia.org/wiki/Hopcroft%E2%80%93Karp_algorithm>`_ for
|
|||
|
|
bipartite graphs.
|
|||
|
|
|
|||
|
|
See :mod:`bipartite documentation <networkx.algorithms.bipartite>`
|
|||
|
|
for further details on how bipartite graphs are handled in NetworkX.
|
|||
|
|
|
|||
|
|
See Also
|
|||
|
|
--------
|
|||
|
|
|
|||
|
|
eppstein_matching
|
|||
|
|
|
|||
|
|
References
|
|||
|
|
----------
|
|||
|
|
.. [1] John E. Hopcroft and Richard M. Karp. "An n^{5 / 2} Algorithm for
|
|||
|
|
Maximum Matchings in Bipartite Graphs" In: **SIAM Journal of Computing**
|
|||
|
|
2.4 (1973), pp. 225--231. <https://doi.org/10.1137/0202019>.
|
|||
|
|
|
|||
|
|
"""
|
|||
|
|
# First we define some auxiliary search functions.
|
|||
|
|
#
|
|||
|
|
# If you are a human reading these auxiliary search functions, the "global"
|
|||
|
|
# variables `leftmatches`, `rightmatches`, `distances`, etc. are defined
|
|||
|
|
# below the functions, so that they are initialized close to the initial
|
|||
|
|
# invocation of the search functions.
|
|||
|
|
def breadth_first_search():
|
|||
|
|
for v in left:
|
|||
|
|
if leftmatches[v] is None:
|
|||
|
|
distances[v] = 0
|
|||
|
|
queue.append(v)
|
|||
|
|
else:
|
|||
|
|
distances[v] = INFINITY
|
|||
|
|
distances[None] = INFINITY
|
|||
|
|
while queue:
|
|||
|
|
v = queue.popleft()
|
|||
|
|
if distances[v] < distances[None]:
|
|||
|
|
for u in G[v]:
|
|||
|
|
if distances[rightmatches[u]] is INFINITY:
|
|||
|
|
distances[rightmatches[u]] = distances[v] + 1
|
|||
|
|
queue.append(rightmatches[u])
|
|||
|
|
return distances[None] is not INFINITY
|
|||
|
|
|
|||
|
|
def depth_first_search(v):
|
|||
|
|
if v is not None:
|
|||
|
|
for u in G[v]:
|
|||
|
|
if distances[rightmatches[u]] == distances[v] + 1:
|
|||
|
|
if depth_first_search(rightmatches[u]):
|
|||
|
|
rightmatches[u] = v
|
|||
|
|
leftmatches[v] = u
|
|||
|
|
return True
|
|||
|
|
distances[v] = INFINITY
|
|||
|
|
return False
|
|||
|
|
return True
|
|||
|
|
|
|||
|
|
# Initialize the "global" variables that maintain state during the search.
|
|||
|
|
left, right = bipartite_sets(G, top_nodes)
|
|||
|
|
leftmatches = {v: None for v in left}
|
|||
|
|
rightmatches = {v: None for v in right}
|
|||
|
|
distances = {}
|
|||
|
|
queue = collections.deque()
|
|||
|
|
|
|||
|
|
# Implementation note: this counter is incremented as pairs are matched but
|
|||
|
|
# it is currently not used elsewhere in the computation.
|
|||
|
|
num_matched_pairs = 0
|
|||
|
|
while breadth_first_search():
|
|||
|
|
for v in left:
|
|||
|
|
if leftmatches[v] is None:
|
|||
|
|
if depth_first_search(v):
|
|||
|
|
num_matched_pairs += 1
|
|||
|
|
|
|||
|
|
# Strip the entries matched to `None`.
|
|||
|
|
leftmatches = {k: v for k, v in leftmatches.items() if v is not None}
|
|||
|
|
rightmatches = {k: v for k, v in rightmatches.items() if v is not None}
|
|||
|
|
|
|||
|
|
# At this point, the left matches and the right matches are inverses of one
|
|||
|
|
# another. In other words,
|
|||
|
|
#
|
|||
|
|
# leftmatches == {v, k for k, v in rightmatches.items()}
|
|||
|
|
#
|
|||
|
|
# Finally, we combine both the left matches and right matches.
|
|||
|
|
return dict(itertools.chain(leftmatches.items(), rightmatches.items()))
|
|||
|
|
|
|||
|
|
|
|||
|
|
def eppstein_matching(G, top_nodes=None):
|
|||
|
|
"""Returns the maximum cardinality matching of the bipartite graph `G`.
|
|||
|
|
|
|||
|
|
Parameters
|
|||
|
|
----------
|
|||
|
|
G : NetworkX graph
|
|||
|
|
|
|||
|
|
Undirected bipartite graph
|
|||
|
|
|
|||
|
|
top_nodes : container
|
|||
|
|
|
|||
|
|
Container with all nodes in one bipartite node set. If not supplied
|
|||
|
|
it will be computed. But if more than one solution exists an exception
|
|||
|
|
will be raised.
|
|||
|
|
|
|||
|
|
Returns
|
|||
|
|
-------
|
|||
|
|
matches : dictionary
|
|||
|
|
|
|||
|
|
The matching is returned as a dictionary, `matching`, such that
|
|||
|
|
``matching[v] == w`` if node `v` is matched to node `w`. Unmatched
|
|||
|
|
nodes do not occur as a key in mate.
|
|||
|
|
|
|||
|
|
Raises
|
|||
|
|
------
|
|||
|
|
AmbiguousSolution : Exception
|
|||
|
|
|
|||
|
|
Raised if the input bipartite graph is disconnected and no container
|
|||
|
|
with all nodes in one bipartite set is provided. When determining
|
|||
|
|
the nodes in each bipartite set more than one valid solution is
|
|||
|
|
possible if the input graph is disconnected.
|
|||
|
|
|
|||
|
|
Notes
|
|||
|
|
-----
|
|||
|
|
This function is implemented with David Eppstein's version of the algorithm
|
|||
|
|
Hopcroft--Karp algorithm (see :func:`hopcroft_karp_matching`), which
|
|||
|
|
originally appeared in the `Python Algorithms and Data Structures library
|
|||
|
|
(PADS) <http://www.ics.uci.edu/~eppstein/PADS/ABOUT-PADS.txt>`_.
|
|||
|
|
|
|||
|
|
See :mod:`bipartite documentation <networkx.algorithms.bipartite>`
|
|||
|
|
for further details on how bipartite graphs are handled in NetworkX.
|
|||
|
|
|
|||
|
|
See Also
|
|||
|
|
--------
|
|||
|
|
|
|||
|
|
hopcroft_karp_matching
|
|||
|
|
|
|||
|
|
"""
|
|||
|
|
# Due to its original implementation, a directed graph is needed
|
|||
|
|
# so that the two sets of bipartite nodes can be distinguished
|
|||
|
|
left, right = bipartite_sets(G, top_nodes)
|
|||
|
|
G = nx.DiGraph(G.edges(left))
|
|||
|
|
# initialize greedy matching (redundant, but faster than full search)
|
|||
|
|
matching = {}
|
|||
|
|
for u in G:
|
|||
|
|
for v in G[u]:
|
|||
|
|
if v not in matching:
|
|||
|
|
matching[v] = u
|
|||
|
|
break
|
|||
|
|
while True:
|
|||
|
|
# structure residual graph into layers
|
|||
|
|
# pred[u] gives the neighbor in the previous layer for u in U
|
|||
|
|
# preds[v] gives a list of neighbors in the previous layer for v in V
|
|||
|
|
# unmatched gives a list of unmatched vertices in final layer of V,
|
|||
|
|
# and is also used as a flag value for pred[u] when u is in the first
|
|||
|
|
# layer
|
|||
|
|
preds = {}
|
|||
|
|
unmatched = []
|
|||
|
|
pred = {u: unmatched for u in G}
|
|||
|
|
for v in matching:
|
|||
|
|
del pred[matching[v]]
|
|||
|
|
layer = list(pred)
|
|||
|
|
|
|||
|
|
# repeatedly extend layering structure by another pair of layers
|
|||
|
|
while layer and not unmatched:
|
|||
|
|
newLayer = {}
|
|||
|
|
for u in layer:
|
|||
|
|
for v in G[u]:
|
|||
|
|
if v not in preds:
|
|||
|
|
newLayer.setdefault(v, []).append(u)
|
|||
|
|
layer = []
|
|||
|
|
for v in newLayer:
|
|||
|
|
preds[v] = newLayer[v]
|
|||
|
|
if v in matching:
|
|||
|
|
layer.append(matching[v])
|
|||
|
|
pred[matching[v]] = v
|
|||
|
|
else:
|
|||
|
|
unmatched.append(v)
|
|||
|
|
|
|||
|
|
# did we finish layering without finding any alternating paths?
|
|||
|
|
if not unmatched:
|
|||
|
|
unlayered = {}
|
|||
|
|
for u in G:
|
|||
|
|
# TODO Why is extra inner loop necessary?
|
|||
|
|
for v in G[u]:
|
|||
|
|
if v not in preds:
|
|||
|
|
unlayered[v] = None
|
|||
|
|
# TODO Originally, this function returned a three-tuple:
|
|||
|
|
#
|
|||
|
|
# return (matching, list(pred), list(unlayered))
|
|||
|
|
#
|
|||
|
|
# For some reason, the documentation for this function
|
|||
|
|
# indicated that the second and third elements of the returned
|
|||
|
|
# three-tuple would be the vertices in the left and right vertex
|
|||
|
|
# sets, respectively, that are also in the maximum independent set.
|
|||
|
|
# However, what I think the author meant was that the second
|
|||
|
|
# element is the list of vertices that were unmatched and the third
|
|||
|
|
# element was the list of vertices that were matched. Since that
|
|||
|
|
# seems to be the case, they don't really need to be returned,
|
|||
|
|
# since that information can be inferred from the matching
|
|||
|
|
# dictionary.
|
|||
|
|
|
|||
|
|
# All the matched nodes must be a key in the dictionary
|
|||
|
|
for key in matching.copy():
|
|||
|
|
matching[matching[key]] = key
|
|||
|
|
return matching
|
|||
|
|
|
|||
|
|
# recursively search backward through layers to find alternating paths
|
|||
|
|
# recursion returns true if found path, false otherwise
|
|||
|
|
def recurse(v):
|
|||
|
|
if v in preds:
|
|||
|
|
L = preds.pop(v)
|
|||
|
|
for u in L:
|
|||
|
|
if u in pred:
|
|||
|
|
pu = pred.pop(u)
|
|||
|
|
if pu is unmatched or recurse(pu):
|
|||
|
|
matching[v] = u
|
|||
|
|
return True
|
|||
|
|
return False
|
|||
|
|
|
|||
|
|
for v in unmatched:
|
|||
|
|
recurse(v)
|
|||
|
|
|
|||
|
|
|
|||
|
|
def _is_connected_by_alternating_path(G, v, matched_edges, unmatched_edges,
|
|||
|
|
targets):
|
|||
|
|
"""Returns True if and only if the vertex `v` is connected to one of
|
|||
|
|
the target vertices by an alternating path in `G`.
|
|||
|
|
|
|||
|
|
An *alternating path* is a path in which every other edge is in the
|
|||
|
|
specified maximum matching (and the remaining edges in the path are not in
|
|||
|
|
the matching). An alternating path may have matched edges in the even
|
|||
|
|
positions or in the odd positions, as long as the edges alternate between
|
|||
|
|
'matched' and 'unmatched'.
|
|||
|
|
|
|||
|
|
`G` is an undirected bipartite NetworkX graph.
|
|||
|
|
|
|||
|
|
`v` is a vertex in `G`.
|
|||
|
|
|
|||
|
|
`matched_edges` is a set of edges present in a maximum matching in `G`.
|
|||
|
|
|
|||
|
|
`unmatched_edges` is a set of edges not present in a maximum
|
|||
|
|
matching in `G`.
|
|||
|
|
|
|||
|
|
`targets` is a set of vertices.
|
|||
|
|
|
|||
|
|
"""
|
|||
|
|
def _alternating_dfs(u, along_matched=True):
|
|||
|
|
"""Returns True if and only if `u` is connected to one of the
|
|||
|
|
targets by an alternating path.
|
|||
|
|
|
|||
|
|
`u` is a vertex in the graph `G`.
|
|||
|
|
|
|||
|
|
If `along_matched` is True, this step of the depth-first search
|
|||
|
|
will continue only through edges in the given matching. Otherwise, it
|
|||
|
|
will continue only through edges *not* in the given matching.
|
|||
|
|
|
|||
|
|
"""
|
|||
|
|
if along_matched:
|
|||
|
|
edges = itertools.cycle([matched_edges, unmatched_edges])
|
|||
|
|
else:
|
|||
|
|
edges = itertools.cycle([unmatched_edges, matched_edges])
|
|||
|
|
visited = set()
|
|||
|
|
stack = [(u, iter(G[u]), next(edges))]
|
|||
|
|
while stack:
|
|||
|
|
parent, children, valid_edges = stack[-1]
|
|||
|
|
try:
|
|||
|
|
child = next(children)
|
|||
|
|
if child not in visited:
|
|||
|
|
if ((parent, child) in valid_edges
|
|||
|
|
or (child, parent) in valid_edges):
|
|||
|
|
if child in targets:
|
|||
|
|
return True
|
|||
|
|
visited.add(child)
|
|||
|
|
stack.append((child, iter(G[child]), next(edges)))
|
|||
|
|
except StopIteration:
|
|||
|
|
stack.pop()
|
|||
|
|
return False
|
|||
|
|
|
|||
|
|
# Check for alternating paths starting with edges in the matching, then
|
|||
|
|
# check for alternating paths starting with edges not in the
|
|||
|
|
# matching.
|
|||
|
|
return (_alternating_dfs(v, along_matched=True) or
|
|||
|
|
_alternating_dfs(v, along_matched=False))
|
|||
|
|
|
|||
|
|
|
|||
|
|
def _connected_by_alternating_paths(G, matching, targets):
|
|||
|
|
"""Returns the set of vertices that are connected to one of the target
|
|||
|
|
vertices by an alternating path in `G` or are themselves a target.
|
|||
|
|
|
|||
|
|
An *alternating path* is a path in which every other edge is in the
|
|||
|
|
specified maximum matching (and the remaining edges in the path are not in
|
|||
|
|
the matching). An alternating path may have matched edges in the even
|
|||
|
|
positions or in the odd positions, as long as the edges alternate between
|
|||
|
|
'matched' and 'unmatched'.
|
|||
|
|
|
|||
|
|
`G` is an undirected bipartite NetworkX graph.
|
|||
|
|
|
|||
|
|
`matching` is a dictionary representing a maximum matching in `G`, as
|
|||
|
|
returned by, for example, :func:`maximum_matching`.
|
|||
|
|
|
|||
|
|
`targets` is a set of vertices.
|
|||
|
|
|
|||
|
|
"""
|
|||
|
|
# Get the set of matched edges and the set of unmatched edges. Only include
|
|||
|
|
# one version of each undirected edge (for example, include edge (1, 2) but
|
|||
|
|
# not edge (2, 1)). Using frozensets as an intermediary step we do not
|
|||
|
|
# require nodes to be orderable.
|
|||
|
|
edge_sets = {frozenset((u, v)) for u, v in matching.items()}
|
|||
|
|
matched_edges = {tuple(edge) for edge in edge_sets}
|
|||
|
|
unmatched_edges = {(u, v) for (u, v) in G.edges()
|
|||
|
|
if frozenset((u, v)) not in edge_sets}
|
|||
|
|
|
|||
|
|
return {v for v in G if v in targets or
|
|||
|
|
_is_connected_by_alternating_path(G, v, matched_edges,
|
|||
|
|
unmatched_edges, targets)}
|
|||
|
|
|
|||
|
|
|
|||
|
|
def to_vertex_cover(G, matching, top_nodes=None):
|
|||
|
|
"""Returns the minimum vertex cover corresponding to the given maximum
|
|||
|
|
matching of the bipartite graph `G`.
|
|||
|
|
|
|||
|
|
Parameters
|
|||
|
|
----------
|
|||
|
|
G : NetworkX graph
|
|||
|
|
|
|||
|
|
Undirected bipartite graph
|
|||
|
|
|
|||
|
|
matching : dictionary
|
|||
|
|
|
|||
|
|
A dictionary whose keys are vertices in `G` and whose values are the
|
|||
|
|
distinct neighbors comprising the maximum matching for `G`, as returned
|
|||
|
|
by, for example, :func:`maximum_matching`. The dictionary *must*
|
|||
|
|
represent the maximum matching.
|
|||
|
|
|
|||
|
|
top_nodes : container
|
|||
|
|
|
|||
|
|
Container with all nodes in one bipartite node set. If not supplied
|
|||
|
|
it will be computed. But if more than one solution exists an exception
|
|||
|
|
will be raised.
|
|||
|
|
|
|||
|
|
Returns
|
|||
|
|
-------
|
|||
|
|
vertex_cover : :class:`set`
|
|||
|
|
|
|||
|
|
The minimum vertex cover in `G`.
|
|||
|
|
|
|||
|
|
Raises
|
|||
|
|
------
|
|||
|
|
AmbiguousSolution : Exception
|
|||
|
|
|
|||
|
|
Raised if the input bipartite graph is disconnected and no container
|
|||
|
|
with all nodes in one bipartite set is provided. When determining
|
|||
|
|
the nodes in each bipartite set more than one valid solution is
|
|||
|
|
possible if the input graph is disconnected.
|
|||
|
|
|
|||
|
|
Notes
|
|||
|
|
-----
|
|||
|
|
This function is implemented using the procedure guaranteed by `Konig's
|
|||
|
|
theorem
|
|||
|
|
<https://en.wikipedia.org/wiki/K%C3%B6nig%27s_theorem_%28graph_theory%29>`_,
|
|||
|
|
which proves an equivalence between a maximum matching and a minimum vertex
|
|||
|
|
cover in bipartite graphs.
|
|||
|
|
|
|||
|
|
Since a minimum vertex cover is the complement of a maximum independent set
|
|||
|
|
for any graph, one can compute the maximum independent set of a bipartite
|
|||
|
|
graph this way:
|
|||
|
|
|
|||
|
|
>>> import networkx as nx
|
|||
|
|
>>> G = nx.complete_bipartite_graph(2, 3)
|
|||
|
|
>>> matching = nx.bipartite.maximum_matching(G)
|
|||
|
|
>>> vertex_cover = nx.bipartite.to_vertex_cover(G, matching)
|
|||
|
|
>>> independent_set = set(G) - vertex_cover
|
|||
|
|
>>> print(list(independent_set))
|
|||
|
|
[2, 3, 4]
|
|||
|
|
|
|||
|
|
See :mod:`bipartite documentation <networkx.algorithms.bipartite>`
|
|||
|
|
for further details on how bipartite graphs are handled in NetworkX.
|
|||
|
|
|
|||
|
|
"""
|
|||
|
|
# This is a Python implementation of the algorithm described at
|
|||
|
|
# <https://en.wikipedia.org/wiki/K%C3%B6nig%27s_theorem_%28graph_theory%29#Proof>.
|
|||
|
|
L, R = bipartite_sets(G, top_nodes)
|
|||
|
|
# Let U be the set of unmatched vertices in the left vertex set.
|
|||
|
|
unmatched_vertices = set(G) - set(matching)
|
|||
|
|
U = unmatched_vertices & L
|
|||
|
|
# Let Z be the set of vertices that are either in U or are connected to U
|
|||
|
|
# by alternating paths.
|
|||
|
|
Z = _connected_by_alternating_paths(G, matching, U)
|
|||
|
|
# At this point, every edge either has a right endpoint in Z or a left
|
|||
|
|
# endpoint not in Z. This gives us the vertex cover.
|
|||
|
|
return (L - Z) | (R & Z)
|
|||
|
|
|
|||
|
|
|
|||
|
|
#: Returns the maximum cardinality matching in the given bipartite graph.
|
|||
|
|
#:
|
|||
|
|
#: This function is simply an alias for :func:`hopcroft_karp_matching`.
|
|||
|
|
maximum_matching = hopcroft_karp_matching
|
|||
|
|
|
|||
|
|
|
|||
|
|
def minimum_weight_full_matching(G, top_nodes=None, weight='weight'):
|
|||
|
|
r"""Returns the minimum weight full matching of the bipartite graph `G`.
|
|||
|
|
|
|||
|
|
Let :math:`G = ((U, V), E)` be a complete weighted bipartite graph with
|
|||
|
|
real weights :math:`w : E \to \mathbb{R}`. This function then produces
|
|||
|
|
a maximum matching :math:`M \subseteq E` which, since the graph is
|
|||
|
|
assumed to be complete, has cardinality
|
|||
|
|
|
|||
|
|
.. math::
|
|||
|
|
\lvert M \rvert = \min(\lvert U \rvert, \lvert V \rvert),
|
|||
|
|
|
|||
|
|
and which minimizes the sum of the weights of the edges included in the
|
|||
|
|
matching, :math:`\sum_{e \in M} w(e)`.
|
|||
|
|
|
|||
|
|
When :math:`\lvert U \rvert = \lvert V \rvert`, this is commonly
|
|||
|
|
referred to as a perfect matching; here, since we allow
|
|||
|
|
:math:`\lvert U \rvert` and :math:`\lvert V \rvert` to differ, we
|
|||
|
|
follow Karp [1]_ and refer to the matching as *full*.
|
|||
|
|
|
|||
|
|
Parameters
|
|||
|
|
----------
|
|||
|
|
G : NetworkX graph
|
|||
|
|
|
|||
|
|
Undirected bipartite graph
|
|||
|
|
|
|||
|
|
top_nodes : container
|
|||
|
|
|
|||
|
|
Container with all nodes in one bipartite node set. If not supplied
|
|||
|
|
it will be computed.
|
|||
|
|
|
|||
|
|
weight : string, optional (default='weight')
|
|||
|
|
|
|||
|
|
The edge data key used to provide each value in the matrix.
|
|||
|
|
|
|||
|
|
Returns
|
|||
|
|
-------
|
|||
|
|
matches : dictionary
|
|||
|
|
|
|||
|
|
The matching is returned as a dictionary, `matches`, such that
|
|||
|
|
``matches[v] == w`` if node `v` is matched to node `w`. Unmatched
|
|||
|
|
nodes do not occur as a key in matches.
|
|||
|
|
|
|||
|
|
Raises
|
|||
|
|
------
|
|||
|
|
ValueError : Exception
|
|||
|
|
|
|||
|
|
Raised if the input bipartite graph is not complete.
|
|||
|
|
|
|||
|
|
ImportError : Exception
|
|||
|
|
|
|||
|
|
Raised if SciPy is not available.
|
|||
|
|
|
|||
|
|
Notes
|
|||
|
|
-----
|
|||
|
|
The problem of determining a minimum weight full matching is also known as
|
|||
|
|
the rectangular linear assignment problem. This implementation defers the
|
|||
|
|
calculation of the assignment to SciPy.
|
|||
|
|
|
|||
|
|
References
|
|||
|
|
----------
|
|||
|
|
.. [1] Richard Manning Karp:
|
|||
|
|
An algorithm to Solve the m x n Assignment Problem in Expected Time
|
|||
|
|
O(mn log n).
|
|||
|
|
Networks, 10(2):143–152, 1980.
|
|||
|
|
|
|||
|
|
"""
|
|||
|
|
try:
|
|||
|
|
import scipy.optimize
|
|||
|
|
except ImportError:
|
|||
|
|
raise ImportError('minimum_weight_full_matching requires SciPy: ' +
|
|||
|
|
'https://scipy.org/')
|
|||
|
|
left, right = nx.bipartite.sets(G, top_nodes)
|
|||
|
|
# Ensure that the graph is complete. This is currently a requirement in
|
|||
|
|
# the underlying optimization algorithm from SciPy, but the constraint
|
|||
|
|
# will be removed in SciPy 1.4.0, at which point it can also be removed
|
|||
|
|
# here.
|
|||
|
|
for (u, v) in itertools.product(left, right):
|
|||
|
|
# As the graph is undirected, make sure to check for edges in
|
|||
|
|
# both directions
|
|||
|
|
if (u, v) not in G.edges() and (v, u) not in G.edges():
|
|||
|
|
raise ValueError('The bipartite graph must be complete.')
|
|||
|
|
U = list(left)
|
|||
|
|
V = list(right)
|
|||
|
|
weights = biadjacency_matrix(G, row_order=U,
|
|||
|
|
column_order=V, weight=weight).toarray()
|
|||
|
|
left_matches = scipy.optimize.linear_sum_assignment(weights)
|
|||
|
|
d = {U[u]: V[v] for u, v in zip(*left_matches)}
|
|||
|
|
# d will contain the matching from edges in left to right; we need to
|
|||
|
|
# add the ones from right to left as well.
|
|||
|
|
d.update({v: u for u, v in d.items()})
|
|||
|
|
return d
|