Add Local Complementation (#1366)

* First implementation and possible impl. ideas as comments

* Enable python interface to local_complement. First tests.

* Only multigraphs and no digraphs
Assure multigraphs are not allowed and local complementation is not defined for digraphs. Self loops are assumed to not exist in the provided grahps. Added test

* redundant docstring sentence removed

* Add method to docs, add release notes, add type annotations, remove digraph_local_complement, add&improve tests

* update release notes

Author: S-Erik

docs/source/api/pygraph_api_functions.rst

@@ -37,6 +37,7 @@ typed API based on the data type.
    rustworkx.graph_transitivity
    rustworkx.graph_core_number
    rustworkx.graph_complement
+   rustworkx.local_complement
    rustworkx.graph_union
    rustworkx.graph_tensor_product
    rustworkx.graph_token_swapper

releasenotes/notes/add-local-complementation-f79b3b05769814cc.yaml

@@ -0,0 +1,18 @@
+---
+features:
+  - |
+    Added a new function, :func:`~rustworkx.local_complement` which
+    performs the local complementation of a node applied to a graph 
+    For example:
+
+    .. jupyter-execute::
+
+        import rustworkx 
+        
+        # Example taken from Figure 1 a) in https://arxiv.org/abs/1910.03969
+        graph = rustworkx.PyGraph(multigraph=False)
+        graph.extend_from_edge_list(
+            [(0, 1), (0, 3), (0, 5), (1, 2), (2, 3), (2, 4), (3, 4), (3, 5)]
+        )
+
+        complement_graph = rustworkx.local_complement(graph, 0)

rustworkx/__init__.pyi

@@ -89,6 +89,7 @@ from .rustworkx import chain_decomposition as chain_decomposition
 from .rustworkx import digraph_find_cycle as digraph_find_cycle
 from .rustworkx import digraph_complement as digraph_complement
 from .rustworkx import graph_complement as graph_complement
+from .rustworkx import local_complement as local_complement
 from .rustworkx import digraph_all_simple_paths as digraph_all_simple_paths
 from .rustworkx import graph_all_simple_paths as graph_all_simple_paths
 from .rustworkx import digraph_all_pairs_all_simple_paths as digraph_all_pairs_all_simple_paths

rustworkx/rustworkx.pyi

@@ -233,6 +233,11 @@ def graph_complement(
     graph: PyGraph[_S, _T],
     /,
 ) -> PyGraph[_S, _T | None]: ...
+def local_complement(
+    graph: PyGraph[_S, _T],
+    node: int,
+    /,
+) -> PyGraph[_S, _T | None]: ...
 def digraph_all_simple_paths(
     graph: PyDiGraph,
     origin: int,

src/connectivity/mod.rs

@@ -21,6 +21,7 @@ use super::{
 };
 
 use hashbrown::{HashMap, HashSet};
+use indexmap::IndexSet;
 use petgraph::algo;
 use petgraph::algo::condensation;
 use petgraph::graph::DiGraph;
@@ -561,6 +562,64 @@ pub fn digraph_complement(py: Python, graph: &digraph::PyDiGraph) -> PyResult<di
     Ok(complement_graph)
 }
 
+/// Local complementation of a node applied to an undirected graph.
+///
+/// :param PyGraph graph: The graph to be used.
+/// :param int node: A node in the graph.
+///
+/// :returns: The locally complemented graph.
+/// :rtype: PyGraph
+///
+/// .. note::
+///
+///     This function assumes that there are no self loops
+///     in the provided graph.
+///     Returns an error if the :attr:`~rustworkx.PyGraph.multigraph`
+///     attribute is set to ``True``.
+#[pyfunction]
+#[pyo3(text_signature = "(graph, node, /)")]
+pub fn local_complement(
+    py: Python,
+    graph: &graph::PyGraph,
+    node: usize,
+) -> PyResult<graph::PyGraph> {
+    if graph.multigraph {
+        return Err(PyValueError::new_err(
+            "Local complementation not defined for multigraphs!",
+        ));
+    }
+
+    let mut complement_graph = graph.clone(); // keep same node indices
+
+    let node = NodeIndex::new(node);
+    if !graph.graph.contains_node(node) {
+        return Err(InvalidNode::new_err(
+            "The input index for 'node' is not a valid node index",
+        ));
+    }
+
+    // Local complementation
+    let node_neighbors: IndexSet<NodeIndex> = graph.graph.neighbors(node).collect();
+    let node_neighbors_vec: Vec<&NodeIndex> = node_neighbors.iter().collect();
+    for (i, neighbor_i) in node_neighbors_vec.iter().enumerate() {
+        // Ensure checking pairs of neighbors is only done once
+        let (_, nodes_tail) = node_neighbors_vec.split_at(i + 1);
+        for neighbor_j in nodes_tail.iter() {
+            let res = complement_graph.remove_edge(neighbor_i.index(), neighbor_j.index());
+            match res {
+                Ok(_) => (),
+                Err(_) => {
+                    let _ = complement_graph
+                        .graph
+                        .add_edge(**neighbor_i, **neighbor_j, py.None());
+                }
+            }
+        }
+    }
+
+    Ok(complement_graph)
+}
+
 /// Return all simple paths between 2 nodes in a PyGraph object
 ///
 /// A simple path is a path with no repeated nodes.

src/lib.rs

@@ -585,6 +585,7 @@ fn rustworkx(py: Python<'_>, m: &Bound<PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(digraph_core_number))?;
     m.add_wrapped(wrap_pyfunction!(graph_complement))?;
     m.add_wrapped(wrap_pyfunction!(digraph_complement))?;
+    m.add_wrapped(wrap_pyfunction!(local_complement))?;
     m.add_wrapped(wrap_pyfunction!(graph_random_layout))?;
     m.add_wrapped(wrap_pyfunction!(digraph_random_layout))?;
     m.add_wrapped(wrap_pyfunction!(graph_bipartite_layout))?;

tests/graph/test_local_complement.py

@@ -0,0 +1,80 @@
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+import unittest
+
+import rustworkx
+
+
+class TestLocalComplement(unittest.TestCase):
+    def test_multigraph(self):
+        graph = rustworkx.PyGraph(multigraph=True)
+        node = graph.add_node("")
+        with self.assertRaises(ValueError):
+            rustworkx.local_complement(graph, node)
+
+    def test_invalid_node(self):
+        graph = rustworkx.PyGraph(multigraph=False)
+        node = graph.add_node("")
+        with self.assertRaises(rustworkx.InvalidNode):
+            rustworkx.local_complement(graph, node + 1)
+
+    def test_clique(self):
+        N = 5
+        graph = rustworkx.generators.complete_graph(N, multigraph=False)
+
+        for node in range(0, N):
+            expected_graph = rustworkx.PyGraph(multigraph=False)
+            expected_graph.extend_from_edge_list([(i, node) for i in range(0, N) if i != node])
+
+            complement_graph = rustworkx.local_complement(graph, node)
+
+            self.assertTrue(
+                rustworkx.is_isomorphic(
+                    expected_graph,
+                    complement_graph,
+                )
+            )
+
+    def test_empty(self):
+        N = 5
+        graph = rustworkx.generators.empty_graph(N, multigraph=False)
+
+        expected_graph = rustworkx.generators.empty_graph(N, multigraph=False)
+
+        complement_graph = rustworkx.local_complement(graph, 0)
+        self.assertTrue(
+            rustworkx.is_isomorphic(
+                expected_graph,
+                complement_graph,
+            )
+        )
+
+    def test_local_complement(self):
+        # Example took from https://arxiv.org/abs/1910.03969, figure 1
+        graph = rustworkx.PyGraph(multigraph=False)
+        graph.extend_from_edge_list(
+            [(0, 1), (0, 3), (0, 5), (1, 2), (2, 3), (2, 4), (3, 4), (3, 5)]
+        )
+
+        expected_graph = rustworkx.PyGraph(multigraph=False)
+        expected_graph.extend_from_edge_list(
+            [(0, 1), (0, 3), (0, 5), (1, 2), (1, 3), (1, 5), (2, 3), (2, 4), (3, 4)]
+        )
+
+        complement_graph = rustworkx.local_complement(graph, 0)
+        self.assertTrue(
+            rustworkx.is_isomorphic(
+                expected_graph,
+                complement_graph,
+            )
+        )