Add max weight matching function

.github/workflows/main.yml

@@ -84,7 +84,7 @@ jobs:
       - name: Download grcov
         run: curl -L https://github.com/mozilla/grcov/releases/download/v0.6.1/grcov-linux-x86_64.tar.bz2 | tar jxf -
       - name: Install deps
-        run: pip install -U setuptools-rust
+        run: pip install -U setuptools-rust networkx
       - name: Build retworkx
         run: python setup.py develop
         env:

.travis.yml

@@ -12,12 +12,9 @@ before_install:
   - sh tools/install_rust.sh
   - export PATH=~/.cargo/bin:$PATH
   - which python
-  - pip install -U pip virtualenv
-install:
-  - virtualenv test-venv
-  - test-venv/bin/pip install -U .
+  - pip install -U pip virtualenv tox
 script:
-  - cd tests && ../test-venv/bin/python -m unittest discover .
+  - tox -epy
 stages:
   - name: Linux non-x86_64
     if: tag IS blank
@@ -42,7 +39,7 @@ jobs:
         - sh tools/install_rust.sh
         - export PATH=~/.cargo/bin:$PATH
         - which python
-        - pip install -U pip virtualenv
+        - pip install -U pip virtualenv tox
         - rustup default 1.49.0
     - name: Python 3.7 Tests arm64 Linux
       stage: Linux non-x86_64

docs/source/api.rst

@@ -90,6 +90,7 @@ Specific Graph Type Methods
    retworkx.digraph_dfs_edges
    retworkx.digraph_find_cycle
    retworkx.digraph_union
+   retworkx.max_weight_matching
 
 Universal Functions
 '''''''''''''''''''

releasenotes/notes/add-max-weight-matching-089ba67668b3b071.yaml

@@ -0,0 +1,5 @@
+---
+features:
+  - |
+    Add a new function, :func:`~retworkx.max_weight_matching` for computing the
+    maximum-weighted matching for a :class:`~retworkx.PyGraph` object.

src/lib.rs

@@ -19,6 +19,7 @@ mod generators;
 mod graph;
 mod iterators;
 mod k_shortest_path;
+mod max_weight_matching;
 mod union;
 
 use std::cmp::{Ordering, Reverse};
@@ -2492,6 +2493,70 @@ pub fn cycle_basis(
     cycles
 }
 
+/// Compute a maximum-weighted matching for a :class:`~retworkx.PyGraph`
+///
+/// A matching is a subset of edges in which no node occurs more than once.
+/// The weight of a matching is the sum of the weights of its edges.
+/// A maximal matching cannot add more edges and still be a matching.
+/// The cardinality of a matching is the number of matched edges.
+///
+/// This function takes time :math:`O(n^3)` where ``n`` is the number of nodes
+/// in the graph.
+///
+/// This method is based on the "blossom" method for finding augmenting
+/// paths and the "primal-dual" method for finding a matching of maximum
+/// weight, both methods invented by Jack Edmonds [1]_.
+///
+/// :param PyGraph graph: The undirected graph to compute the max weight
+///     matching for. Expects to have no parallel edges (multigraphs are
+///     untested currently).
+/// :param bool max_cardinality: If True, compute the maximum-cardinality
+///     matching with maximum weight among all maximum-cardinality matchings.
+///     Defaults False.
+/// :param callable weight_fn: An optional callable that will be passed a
+///     single argument the edge object for each edge in the graph. It is
+///     expected to return an ``int`` weight for that edge. For example,
+///     if the weights are all integers you can use: ``lambda x: x``. If not
+///     specified the value for ``default_weight`` will be used for all
+///     edge weights.
+/// :param int default_weight: The ``int`` value to use for all edge weights
+///     in the graph if ``weight_fn`` is not specified. Defaults to ``1``.
+/// :param bool verify_optimum: A boolean flag to run a check that the found
+///     solution is optimum. If set to true an exception will be raised if
+///     the found solution is not optimum. This is mostly useful for testing.
+///
+/// :returns: A set of tuples ofthe matching, Note that only a single
+///     direction will be listed in the output, for example:
+///     ``{(0, 1),}``.
+/// :rtype: set
+///
+/// .. [1] "Efficient Algorithms for Finding Maximum Matching in Graphs",
+///     Zvi Galil, ACM Computing Surveys, 1986.
+///
+#[pyfunction(
+    max_cardinality = "false",
+    default_weight = 1,
+    verify_optimum = "false"
+)]
+#[text_signature = "(graph, /, max_cardinality=False, weight_fn=None, default_weight=1, verify_optimum=False)"]
+pub fn max_weight_matching(
+    py: Python,
+    graph: &graph::PyGraph,
+    max_cardinality: bool,
+    weight_fn: Option<PyObject>,
+    default_weight: i128,
+    verify_optimum: bool,
+) -> PyResult<HashSet<(usize, usize)>> {
+    max_weight_matching::max_weight_matching(
+        py,
+        graph,
+        max_cardinality,
+        weight_fn,
+        default_weight,
+        verify_optimum,
+    )
+}
+
 /// Compute the strongly connected components for a directed graph
 ///
 /// This function is implemented using Kosaraju's algorithm
@@ -2661,6 +2726,7 @@ fn retworkx(py: Python<'_>, m: &PyModule) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(digraph_find_cycle))?;
     m.add_wrapped(wrap_pyfunction!(digraph_k_shortest_path_lengths))?;
     m.add_wrapped(wrap_pyfunction!(graph_k_shortest_path_lengths))?;
+    m.add_wrapped(wrap_pyfunction!(max_weight_matching))?;
     m.add_class::<digraph::PyDiGraph>()?;
     m.add_class::<graph::PyGraph>()?;
     m.add_class::<iterators::BFSSuccessors>()?;