Add files using upload-large-folder tool

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/assortativity/tests/base_test.py

@@ -0,0 +1,81 @@
+import networkx as nx
+
+
+class BaseTestAttributeMixing:
+    @classmethod
+    def setup_class(cls):
+        G = nx.Graph()
+        G.add_nodes_from([0, 1], fish="one")
+        G.add_nodes_from([2, 3], fish="two")
+        G.add_nodes_from([4], fish="red")
+        G.add_nodes_from([5], fish="blue")
+        G.add_edges_from([(0, 1), (2, 3), (0, 4), (2, 5)])
+        cls.G = G
+
+        D = nx.DiGraph()
+        D.add_nodes_from([0, 1], fish="one")
+        D.add_nodes_from([2, 3], fish="two")
+        D.add_nodes_from([4], fish="red")
+        D.add_nodes_from([5], fish="blue")
+        D.add_edges_from([(0, 1), (2, 3), (0, 4), (2, 5)])
+        cls.D = D
+
+        M = nx.MultiGraph()
+        M.add_nodes_from([0, 1], fish="one")
+        M.add_nodes_from([2, 3], fish="two")
+        M.add_nodes_from([4], fish="red")
+        M.add_nodes_from([5], fish="blue")
+        M.add_edges_from([(0, 1), (0, 1), (2, 3)])
+        cls.M = M
+
+        S = nx.Graph()
+        S.add_nodes_from([0, 1], fish="one")
+        S.add_nodes_from([2, 3], fish="two")
+        S.add_nodes_from([4], fish="red")
+        S.add_nodes_from([5], fish="blue")
+        S.add_edge(0, 0)
+        S.add_edge(2, 2)
+        cls.S = S
+
+        N = nx.Graph()
+        N.add_nodes_from([0, 1], margin=-2)
+        N.add_nodes_from([2, 3], margin=-2)
+        N.add_nodes_from([4], margin=-3)
+        N.add_nodes_from([5], margin=-4)
+        N.add_edges_from([(0, 1), (2, 3), (0, 4), (2, 5)])
+        cls.N = N
+
+        F = nx.Graph()
+        F.add_edges_from([(0, 3), (1, 3), (2, 3)], weight=0.5)
+        F.add_edge(0, 2, weight=1)
+        nx.set_node_attributes(F, dict(F.degree(weight="weight")), "margin")
+        cls.F = F
+
+        K = nx.Graph()
+        K.add_nodes_from([1, 2], margin=-1)
+        K.add_nodes_from([3], margin=1)
+        K.add_nodes_from([4], margin=2)
+        K.add_edges_from([(3, 4), (1, 2), (1, 3)])
+        cls.K = K
+
+
+class BaseTestDegreeMixing:
+    @classmethod
+    def setup_class(cls):
+        cls.P4 = nx.path_graph(4)
+        cls.D = nx.DiGraph()
+        cls.D.add_edges_from([(0, 2), (0, 3), (1, 3), (2, 3)])
+        cls.D2 = nx.DiGraph()
+        cls.D2.add_edges_from([(0, 3), (1, 0), (1, 2), (2, 4), (4, 1), (4, 3), (4, 2)])
+        cls.M = nx.MultiGraph()
+        nx.add_path(cls.M, range(4))
+        cls.M.add_edge(0, 1)
+        cls.S = nx.Graph()
+        cls.S.add_edges_from([(0, 0), (1, 1)])
+        cls.W = nx.Graph()
+        cls.W.add_edges_from([(0, 3), (1, 3), (2, 3)], weight=0.5)
+        cls.W.add_edge(0, 2, weight=1)
+        S1 = nx.star_graph(4)
+        S2 = nx.star_graph(4)
+        cls.DS = nx.disjoint_union(S1, S2)
+        cls.DS.add_edge(4, 5)

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/assortativity/tests/test_correlation.py

@@ -0,0 +1,123 @@
+import pytest
+
+np = pytest.importorskip("numpy")
+pytest.importorskip("scipy")
+
+
+import networkx as nx
+from networkx.algorithms.assortativity.correlation import attribute_ac
+
+from .base_test import BaseTestAttributeMixing, BaseTestDegreeMixing
+
+
+class TestDegreeMixingCorrelation(BaseTestDegreeMixing):
+    def test_degree_assortativity_undirected(self):
+        r = nx.degree_assortativity_coefficient(self.P4)
+        np.testing.assert_almost_equal(r, -1.0 / 2, decimal=4)
+
+    def test_degree_assortativity_node_kwargs(self):
+        G = nx.Graph()
+        edges = [(0, 1), (0, 3), (1, 2), (1, 3), (1, 4), (5, 9), (9, 0)]
+        G.add_edges_from(edges)
+        r = nx.degree_assortativity_coefficient(G, nodes=[1, 2, 4])
+        np.testing.assert_almost_equal(r, -1.0, decimal=4)
+
+    def test_degree_assortativity_directed(self):
+        r = nx.degree_assortativity_coefficient(self.D)
+        np.testing.assert_almost_equal(r, -0.57735, decimal=4)
+
+    def test_degree_assortativity_directed2(self):
+        """Test degree assortativity for a directed graph where the set of
+        in/out degree does not equal the total degree."""
+        r = nx.degree_assortativity_coefficient(self.D2)
+        np.testing.assert_almost_equal(r, 0.14852, decimal=4)
+
+    def test_degree_assortativity_multigraph(self):
+        r = nx.degree_assortativity_coefficient(self.M)
+        np.testing.assert_almost_equal(r, -1.0 / 7.0, decimal=4)
+
+    def test_degree_pearson_assortativity_undirected(self):
+        r = nx.degree_pearson_correlation_coefficient(self.P4)
+        np.testing.assert_almost_equal(r, -1.0 / 2, decimal=4)
+
+    def test_degree_pearson_assortativity_directed(self):
+        r = nx.degree_pearson_correlation_coefficient(self.D)
+        np.testing.assert_almost_equal(r, -0.57735, decimal=4)
+
+    def test_degree_pearson_assortativity_directed2(self):
+        """Test degree assortativity with Pearson for a directed graph where
+        the set of in/out degree does not equal the total degree."""
+        r = nx.degree_pearson_correlation_coefficient(self.D2)
+        np.testing.assert_almost_equal(r, 0.14852, decimal=4)
+
+    def test_degree_pearson_assortativity_multigraph(self):
+        r = nx.degree_pearson_correlation_coefficient(self.M)
+        np.testing.assert_almost_equal(r, -1.0 / 7.0, decimal=4)
+
+    def test_degree_assortativity_weighted(self):
+        r = nx.degree_assortativity_coefficient(self.W, weight="weight")
+        np.testing.assert_almost_equal(r, -0.1429, decimal=4)
+
+    def test_degree_assortativity_double_star(self):
+        r = nx.degree_assortativity_coefficient(self.DS)
+        np.testing.assert_almost_equal(r, -0.9339, decimal=4)
+
+
+class TestAttributeMixingCorrelation(BaseTestAttributeMixing):
+    def test_attribute_assortativity_undirected(self):
+        r = nx.attribute_assortativity_coefficient(self.G, "fish")
+        assert r == 6.0 / 22.0
+
+    def test_attribute_assortativity_directed(self):
+        r = nx.attribute_assortativity_coefficient(self.D, "fish")
+        assert r == 1.0 / 3.0
+
+    def test_attribute_assortativity_multigraph(self):
+        r = nx.attribute_assortativity_coefficient(self.M, "fish")
+        assert r == 1.0
+
+    def test_attribute_assortativity_coefficient(self):
+        # from "Mixing patterns in networks"
+        # fmt: off
+        a = np.array([[0.258, 0.016, 0.035, 0.013],
+                      [0.012, 0.157, 0.058, 0.019],
+                      [0.013, 0.023, 0.306, 0.035],
+                      [0.005, 0.007, 0.024, 0.016]])
+        # fmt: on
+        r = attribute_ac(a)
+        np.testing.assert_almost_equal(r, 0.623, decimal=3)
+
+    def test_attribute_assortativity_coefficient2(self):
+        # fmt: off
+        a = np.array([[0.18, 0.02, 0.01, 0.03],
+                      [0.02, 0.20, 0.03, 0.02],
+                      [0.01, 0.03, 0.16, 0.01],
+                      [0.03, 0.02, 0.01, 0.22]])
+        # fmt: on
+        r = attribute_ac(a)
+        np.testing.assert_almost_equal(r, 0.68, decimal=2)
+
+    def test_attribute_assortativity(self):
+        a = np.array([[50, 50, 0], [50, 50, 0], [0, 0, 2]])
+        r = attribute_ac(a)
+        np.testing.assert_almost_equal(r, 0.029, decimal=3)
+
+    def test_attribute_assortativity_negative(self):
+        r = nx.numeric_assortativity_coefficient(self.N, "margin")
+        np.testing.assert_almost_equal(r, -0.2903, decimal=4)
+
+    def test_assortativity_node_kwargs(self):
+        G = nx.Graph()
+        G.add_nodes_from([0, 1], size=2)
+        G.add_nodes_from([2, 3], size=3)
+        G.add_edges_from([(0, 1), (2, 3)])
+        r = nx.numeric_assortativity_coefficient(G, "size", nodes=[0, 3])
+        np.testing.assert_almost_equal(r, 1.0, decimal=4)
+
+    def test_attribute_assortativity_float(self):
+        r = nx.numeric_assortativity_coefficient(self.F, "margin")
+        np.testing.assert_almost_equal(r, -0.1429, decimal=4)
+
+    def test_attribute_assortativity_mixed(self):
+        r = nx.numeric_assortativity_coefficient(self.K, "margin")
+        np.testing.assert_almost_equal(r, 0.4340, decimal=4)

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/assortativity/tests/test_mixing.py

@@ -0,0 +1,176 @@
+import pytest
+
+np = pytest.importorskip("numpy")
+
+
+import networkx as nx
+
+from .base_test import BaseTestAttributeMixing, BaseTestDegreeMixing
+
+
+class TestDegreeMixingDict(BaseTestDegreeMixing):
+    def test_degree_mixing_dict_undirected(self):
+        d = nx.degree_mixing_dict(self.P4)
+        d_result = {1: {2: 2}, 2: {1: 2, 2: 2}}
+        assert d == d_result
+
+    def test_degree_mixing_dict_undirected_normalized(self):
+        d = nx.degree_mixing_dict(self.P4, normalized=True)
+        d_result = {1: {2: 1.0 / 3}, 2: {1: 1.0 / 3, 2: 1.0 / 3}}
+        assert d == d_result
+
+    def test_degree_mixing_dict_directed(self):
+        d = nx.degree_mixing_dict(self.D)
+        print(d)
+        d_result = {1: {3: 2}, 2: {1: 1, 3: 1}, 3: {}}
+        assert d == d_result
+
+    def test_degree_mixing_dict_multigraph(self):
+        d = nx.degree_mixing_dict(self.M)
+        d_result = {1: {2: 1}, 2: {1: 1, 3: 3}, 3: {2: 3}}
+        assert d == d_result
+
+    def test_degree_mixing_dict_weighted(self):
+        d = nx.degree_mixing_dict(self.W, weight="weight")
+        d_result = {0.5: {1.5: 1}, 1.5: {1.5: 6, 0.5: 1}}
+        assert d == d_result
+
+
+class TestDegreeMixingMatrix(BaseTestDegreeMixing):
+    def test_degree_mixing_matrix_undirected(self):
+        # fmt: off
+        a_result = np.array([[0, 2],
+                             [2, 2]]
+                            )
+        # fmt: on
+        a = nx.degree_mixing_matrix(self.P4, normalized=False)
+        np.testing.assert_equal(a, a_result)
+        a = nx.degree_mixing_matrix(self.P4)
+        np.testing.assert_equal(a, a_result / a_result.sum())
+
+    def test_degree_mixing_matrix_directed(self):
+        # fmt: off
+        a_result = np.array([[0, 0, 2],
+                             [1, 0, 1],
+                             [0, 0, 0]]
+                            )
+        # fmt: on
+        a = nx.degree_mixing_matrix(self.D, normalized=False)
+        np.testing.assert_equal(a, a_result)
+        a = nx.degree_mixing_matrix(self.D)
+        np.testing.assert_equal(a, a_result / a_result.sum())
+
+    def test_degree_mixing_matrix_multigraph(self):
+        # fmt: off
+        a_result = np.array([[0, 1, 0],
+                             [1, 0, 3],
+                             [0, 3, 0]]
+                            )
+        # fmt: on
+        a = nx.degree_mixing_matrix(self.M, normalized=False)
+        np.testing.assert_equal(a, a_result)
+        a = nx.degree_mixing_matrix(self.M)
+        np.testing.assert_equal(a, a_result / a_result.sum())
+
+    def test_degree_mixing_matrix_selfloop(self):
+        # fmt: off
+        a_result = np.array([[2]])
+        # fmt: on
+        a = nx.degree_mixing_matrix(self.S, normalized=False)
+        np.testing.assert_equal(a, a_result)
+        a = nx.degree_mixing_matrix(self.S)
+        np.testing.assert_equal(a, a_result / a_result.sum())
+
+    def test_degree_mixing_matrix_weighted(self):
+        a_result = np.array([[0.0, 1.0], [1.0, 6.0]])
+        a = nx.degree_mixing_matrix(self.W, weight="weight", normalized=False)
+        np.testing.assert_equal(a, a_result)
+        a = nx.degree_mixing_matrix(self.W, weight="weight")
+        np.testing.assert_equal(a, a_result / float(a_result.sum()))
+
+    def test_degree_mixing_matrix_mapping(self):
+        a_result = np.array([[6.0, 1.0], [1.0, 0.0]])
+        mapping = {0.5: 1, 1.5: 0}
+        a = nx.degree_mixing_matrix(
+            self.W, weight="weight", normalized=False, mapping=mapping
+        )
+        np.testing.assert_equal(a, a_result)
+
+
+class TestAttributeMixingDict(BaseTestAttributeMixing):
+    def test_attribute_mixing_dict_undirected(self):
+        d = nx.attribute_mixing_dict(self.G, "fish")
+        d_result = {
+            "one": {"one": 2, "red": 1},
+            "two": {"two": 2, "blue": 1},
+            "red": {"one": 1},
+            "blue": {"two": 1},
+        }
+        assert d == d_result
+
+    def test_attribute_mixing_dict_directed(self):
+        d = nx.attribute_mixing_dict(self.D, "fish")
+        d_result = {
+            "one": {"one": 1, "red": 1},
+            "two": {"two": 1, "blue": 1},
+            "red": {},
+            "blue": {},
+        }
+        assert d == d_result
+
+    def test_attribute_mixing_dict_multigraph(self):
+        d = nx.attribute_mixing_dict(self.M, "fish")
+        d_result = {"one": {"one": 4}, "two": {"two": 2}}
+        assert d == d_result
+
+
+class TestAttributeMixingMatrix(BaseTestAttributeMixing):
+    def test_attribute_mixing_matrix_undirected(self):
+        mapping = {"one": 0, "two": 1, "red": 2, "blue": 3}
+        a_result = np.array([[2, 0, 1, 0], [0, 2, 0, 1], [1, 0, 0, 0], [0, 1, 0, 0]])
+        a = nx.attribute_mixing_matrix(
+            self.G, "fish", mapping=mapping, normalized=False
+        )
+        np.testing.assert_equal(a, a_result)
+        a = nx.attribute_mixing_matrix(self.G, "fish", mapping=mapping)
+        np.testing.assert_equal(a, a_result / a_result.sum())
+
+    def test_attribute_mixing_matrix_directed(self):
+        mapping = {"one": 0, "two": 1, "red": 2, "blue": 3}
+        a_result = np.array([[1, 0, 1, 0], [0, 1, 0, 1], [0, 0, 0, 0], [0, 0, 0, 0]])
+        a = nx.attribute_mixing_matrix(
+            self.D, "fish", mapping=mapping, normalized=False
+        )
+        np.testing.assert_equal(a, a_result)
+        a = nx.attribute_mixing_matrix(self.D, "fish", mapping=mapping)
+        np.testing.assert_equal(a, a_result / a_result.sum())
+
+    def test_attribute_mixing_matrix_multigraph(self):
+        mapping = {"one": 0, "two": 1, "red": 2, "blue": 3}
+        a_result = np.array([[4, 0, 0, 0], [0, 2, 0, 0], [0, 0, 0, 0], [0, 0, 0, 0]])
+        a = nx.attribute_mixing_matrix(
+            self.M, "fish", mapping=mapping, normalized=False
+        )
+        np.testing.assert_equal(a, a_result)
+        a = nx.attribute_mixing_matrix(self.M, "fish", mapping=mapping)
+        np.testing.assert_equal(a, a_result / a_result.sum())
+
+    def test_attribute_mixing_matrix_negative(self):
+        mapping = {-2: 0, -3: 1, -4: 2}
+        a_result = np.array([[4.0, 1.0, 1.0], [1.0, 0.0, 0.0], [1.0, 0.0, 0.0]])
+        a = nx.attribute_mixing_matrix(
+            self.N, "margin", mapping=mapping, normalized=False
+        )
+        np.testing.assert_equal(a, a_result)
+        a = nx.attribute_mixing_matrix(self.N, "margin", mapping=mapping)
+        np.testing.assert_equal(a, a_result / float(a_result.sum()))
+
+    def test_attribute_mixing_matrix_float(self):
+        mapping = {0.5: 1, 1.5: 0}
+        a_result = np.array([[6.0, 1.0], [1.0, 0.0]])
+        a = nx.attribute_mixing_matrix(
+            self.F, "margin", mapping=mapping, normalized=False
+        )
+        np.testing.assert_equal(a, a_result)
+        a = nx.attribute_mixing_matrix(self.F, "margin", mapping=mapping)
+        np.testing.assert_equal(a, a_result / a_result.sum())

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/assortativity/tests/test_neighbor_degree.py

@@ -0,0 +1,108 @@
+import pytest
+
+import networkx as nx
+
+
+class TestAverageNeighbor:
+    def test_degree_p4(self):
+        G = nx.path_graph(4)
+        answer = {0: 2, 1: 1.5, 2: 1.5, 3: 2}
+        nd = nx.average_neighbor_degree(G)
+        assert nd == answer
+
+        D = G.to_directed()
+        nd = nx.average_neighbor_degree(D)
+        assert nd == answer
+
+        D = nx.DiGraph(G.edges(data=True))
+        nd = nx.average_neighbor_degree(D)
+        assert nd == {0: 1, 1: 1, 2: 0, 3: 0}
+        nd = nx.average_neighbor_degree(D, "in", "out")
+        assert nd == {0: 0, 1: 1, 2: 1, 3: 1}
+        nd = nx.average_neighbor_degree(D, "out", "in")
+        assert nd == {0: 1, 1: 1, 2: 1, 3: 0}
+        nd = nx.average_neighbor_degree(D, "in", "in")
+        assert nd == {0: 0, 1: 0, 2: 1, 3: 1}
+
+    def test_degree_p4_weighted(self):
+        G = nx.path_graph(4)
+        G[1][2]["weight"] = 4
+        answer = {0: 2, 1: 1.8, 2: 1.8, 3: 2}
+        nd = nx.average_neighbor_degree(G, weight="weight")
+        assert nd == answer
+
+        D = G.to_directed()
+        nd = nx.average_neighbor_degree(D, weight="weight")
+        assert nd == answer
+
+        D = nx.DiGraph(G.edges(data=True))
+        print(D.edges(data=True))
+        nd = nx.average_neighbor_degree(D, weight="weight")
+        assert nd == {0: 1, 1: 1, 2: 0, 3: 0}
+        nd = nx.average_neighbor_degree(D, "out", "out", weight="weight")
+        assert nd == {0: 1, 1: 1, 2: 0, 3: 0}
+        nd = nx.average_neighbor_degree(D, "in", "in", weight="weight")
+        assert nd == {0: 0, 1: 0, 2: 1, 3: 1}
+        nd = nx.average_neighbor_degree(D, "in", "out", weight="weight")
+        assert nd == {0: 0, 1: 1, 2: 1, 3: 1}
+        nd = nx.average_neighbor_degree(D, "out", "in", weight="weight")
+        assert nd == {0: 1, 1: 1, 2: 1, 3: 0}
+        nd = nx.average_neighbor_degree(D, source="in+out", weight="weight")
+        assert nd == {0: 1.0, 1: 1.0, 2: 0.8, 3: 1.0}
+        nd = nx.average_neighbor_degree(D, target="in+out", weight="weight")
+        assert nd == {0: 2.0, 1: 2.0, 2: 1.0, 3: 0.0}
+
+        D = G.to_directed()
+        nd = nx.average_neighbor_degree(D, weight="weight")
+        assert nd == answer
+        nd = nx.average_neighbor_degree(D, source="out", target="out", weight="weight")
+        assert nd == answer
+
+        D = G.to_directed()
+        nd = nx.average_neighbor_degree(D, source="in", target="in", weight="weight")
+        assert nd == answer
+
+    def test_degree_k4(self):
+        G = nx.complete_graph(4)
+        answer = {0: 3, 1: 3, 2: 3, 3: 3}
+        nd = nx.average_neighbor_degree(G)
+        assert nd == answer
+
+        D = G.to_directed()
+        nd = nx.average_neighbor_degree(D)
+        assert nd == answer
+
+        D = G.to_directed()
+        nd = nx.average_neighbor_degree(D)
+        assert nd == answer
+
+        D = G.to_directed()
+        nd = nx.average_neighbor_degree(D, source="in", target="in")
+        assert nd == answer
+
+    def test_degree_k4_nodes(self):
+        G = nx.complete_graph(4)
+        answer = {1: 3.0, 2: 3.0}
+        nd = nx.average_neighbor_degree(G, nodes=[1, 2])
+        assert nd == answer
+
+    def test_degree_barrat(self):
+        G = nx.star_graph(5)
+        G.add_edges_from([(5, 6), (5, 7), (5, 8), (5, 9)])
+        G[0][5]["weight"] = 5
+        nd = nx.average_neighbor_degree(G)[5]
+        assert nd == 1.8
+        nd = nx.average_neighbor_degree(G, weight="weight")[5]
+        assert nd == pytest.approx(3.222222, abs=1e-5)
+
+    def test_error_invalid_source_target(self):
+        G = nx.path_graph(4)
+        with pytest.raises(nx.NetworkXError):
+            nx.average_neighbor_degree(G, "error")
+        with pytest.raises(nx.NetworkXError):
+            nx.average_neighbor_degree(G, "in", "error")
+        G = G.to_directed()
+        with pytest.raises(nx.NetworkXError):
+            nx.average_neighbor_degree(G, "error")
+        with pytest.raises(nx.NetworkXError):
+            nx.average_neighbor_degree(G, "in", "error")

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/centrality/tests/test_current_flow_betweenness_centrality.py

@@ -0,0 +1,197 @@
+import pytest
+
+import networkx as nx
+from networkx import approximate_current_flow_betweenness_centrality as approximate_cfbc
+from networkx import edge_current_flow_betweenness_centrality as edge_current_flow
+
+np = pytest.importorskip("numpy")
+pytest.importorskip("scipy")
+
+
+class TestFlowBetweennessCentrality:
+    def test_K4_normalized(self):
+        """Betweenness centrality: K4"""
+        G = nx.complete_graph(4)
+        b = nx.current_flow_betweenness_centrality(G, normalized=True)
+        b_answer = {0: 0.25, 1: 0.25, 2: 0.25, 3: 0.25}
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-7)
+        G.add_edge(0, 1, weight=0.5, other=0.3)
+        b = nx.current_flow_betweenness_centrality(G, normalized=True, weight=None)
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-7)
+        wb_answer = {0: 0.2222222, 1: 0.2222222, 2: 0.30555555, 3: 0.30555555}
+        b = nx.current_flow_betweenness_centrality(G, normalized=True, weight="weight")
+        for n in sorted(G):
+            assert b[n] == pytest.approx(wb_answer[n], abs=1e-7)
+        wb_answer = {0: 0.2051282, 1: 0.2051282, 2: 0.33974358, 3: 0.33974358}
+        b = nx.current_flow_betweenness_centrality(G, normalized=True, weight="other")
+        for n in sorted(G):
+            assert b[n] == pytest.approx(wb_answer[n], abs=1e-7)
+
+    def test_K4(self):
+        """Betweenness centrality: K4"""
+        G = nx.complete_graph(4)
+        for solver in ["full", "lu", "cg"]:
+            b = nx.current_flow_betweenness_centrality(
+                G, normalized=False, solver=solver
+            )
+            b_answer = {0: 0.75, 1: 0.75, 2: 0.75, 3: 0.75}
+            for n in sorted(G):
+                assert b[n] == pytest.approx(b_answer[n], abs=1e-7)
+
+    def test_P4_normalized(self):
+        """Betweenness centrality: P4 normalized"""
+        G = nx.path_graph(4)
+        b = nx.current_flow_betweenness_centrality(G, normalized=True)
+        b_answer = {0: 0, 1: 2.0 / 3, 2: 2.0 / 3, 3: 0}
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-7)
+
+    def test_P4(self):
+        """Betweenness centrality: P4"""
+        G = nx.path_graph(4)
+        b = nx.current_flow_betweenness_centrality(G, normalized=False)
+        b_answer = {0: 0, 1: 2, 2: 2, 3: 0}
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-7)
+
+    def test_star(self):
+        """Betweenness centrality: star"""
+        G = nx.Graph()
+        nx.add_star(G, ["a", "b", "c", "d"])
+        b = nx.current_flow_betweenness_centrality(G, normalized=True)
+        b_answer = {"a": 1.0, "b": 0.0, "c": 0.0, "d": 0.0}
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-7)
+
+    def test_solvers2(self):
+        """Betweenness centrality: alternate solvers"""
+        G = nx.complete_graph(4)
+        for solver in ["full", "lu", "cg"]:
+            b = nx.current_flow_betweenness_centrality(
+                G, normalized=False, solver=solver
+            )
+            b_answer = {0: 0.75, 1: 0.75, 2: 0.75, 3: 0.75}
+            for n in sorted(G):
+                assert b[n] == pytest.approx(b_answer[n], abs=1e-7)
+
+
+class TestApproximateFlowBetweennessCentrality:
+    def test_K4_normalized(self):
+        "Approximate current-flow betweenness centrality: K4 normalized"
+        G = nx.complete_graph(4)
+        b = nx.current_flow_betweenness_centrality(G, normalized=True)
+        epsilon = 0.1
+        ba = approximate_cfbc(G, normalized=True, epsilon=0.5 * epsilon)
+        for n in sorted(G):
+            np.testing.assert_allclose(b[n], ba[n], atol=epsilon)
+
+    def test_K4(self):
+        "Approximate current-flow betweenness centrality: K4"
+        G = nx.complete_graph(4)
+        b = nx.current_flow_betweenness_centrality(G, normalized=False)
+        epsilon = 0.1
+        ba = approximate_cfbc(G, normalized=False, epsilon=0.5 * epsilon)
+        for n in sorted(G):
+            np.testing.assert_allclose(b[n], ba[n], atol=epsilon * len(G) ** 2)
+
+    def test_star(self):
+        "Approximate current-flow betweenness centrality: star"
+        G = nx.Graph()
+        nx.add_star(G, ["a", "b", "c", "d"])
+        b = nx.current_flow_betweenness_centrality(G, normalized=True)
+        epsilon = 0.1
+        ba = approximate_cfbc(G, normalized=True, epsilon=0.5 * epsilon)
+        for n in sorted(G):
+            np.testing.assert_allclose(b[n], ba[n], atol=epsilon)
+
+    def test_grid(self):
+        "Approximate current-flow betweenness centrality: 2d grid"
+        G = nx.grid_2d_graph(4, 4)
+        b = nx.current_flow_betweenness_centrality(G, normalized=True)
+        epsilon = 0.1
+        ba = approximate_cfbc(G, normalized=True, epsilon=0.5 * epsilon)
+        for n in sorted(G):
+            np.testing.assert_allclose(b[n], ba[n], atol=epsilon)
+
+    def test_seed(self):
+        G = nx.complete_graph(4)
+        b = approximate_cfbc(G, normalized=False, epsilon=0.05, seed=1)
+        b_answer = {0: 0.75, 1: 0.75, 2: 0.75, 3: 0.75}
+        for n in sorted(G):
+            np.testing.assert_allclose(b[n], b_answer[n], atol=0.1)
+
+    def test_solvers(self):
+        "Approximate current-flow betweenness centrality: solvers"
+        G = nx.complete_graph(4)
+        epsilon = 0.1
+        for solver in ["full", "lu", "cg"]:
+            b = approximate_cfbc(
+                G, normalized=False, solver=solver, epsilon=0.5 * epsilon
+            )
+            b_answer = {0: 0.75, 1: 0.75, 2: 0.75, 3: 0.75}
+            for n in sorted(G):
+                np.testing.assert_allclose(b[n], b_answer[n], atol=epsilon)
+
+    def test_lower_kmax(self):
+        G = nx.complete_graph(4)
+        with pytest.raises(nx.NetworkXError, match="Increase kmax or epsilon"):
+            nx.approximate_current_flow_betweenness_centrality(G, kmax=4)
+
+
+class TestWeightedFlowBetweennessCentrality:
+    pass
+
+
+class TestEdgeFlowBetweennessCentrality:
+    def test_K4(self):
+        """Edge flow betweenness centrality: K4"""
+        G = nx.complete_graph(4)
+        b = edge_current_flow(G, normalized=True)
+        b_answer = dict.fromkeys(G.edges(), 0.25)
+        for (s, t), v1 in b_answer.items():
+            v2 = b.get((s, t), b.get((t, s)))
+            assert v1 == pytest.approx(v2, abs=1e-7)
+
+    def test_K4_normalized(self):
+        """Edge flow betweenness centrality: K4"""
+        G = nx.complete_graph(4)
+        b = edge_current_flow(G, normalized=False)
+        b_answer = dict.fromkeys(G.edges(), 0.75)
+        for (s, t), v1 in b_answer.items():
+            v2 = b.get((s, t), b.get((t, s)))
+            assert v1 == pytest.approx(v2, abs=1e-7)
+
+    def test_C4(self):
+        """Edge flow betweenness centrality: C4"""
+        G = nx.cycle_graph(4)
+        b = edge_current_flow(G, normalized=False)
+        b_answer = {(0, 1): 1.25, (0, 3): 1.25, (1, 2): 1.25, (2, 3): 1.25}
+        for (s, t), v1 in b_answer.items():
+            v2 = b.get((s, t), b.get((t, s)))
+            assert v1 == pytest.approx(v2, abs=1e-7)
+
+    def test_P4(self):
+        """Edge betweenness centrality: P4"""
+        G = nx.path_graph(4)
+        b = edge_current_flow(G, normalized=False)
+        b_answer = {(0, 1): 1.5, (1, 2): 2.0, (2, 3): 1.5}
+        for (s, t), v1 in b_answer.items():
+            v2 = b.get((s, t), b.get((t, s)))
+            assert v1 == pytest.approx(v2, abs=1e-7)
+
+
+@pytest.mark.parametrize(
+    "centrality_func",
+    (
+        nx.current_flow_betweenness_centrality,
+        nx.edge_current_flow_betweenness_centrality,
+        nx.approximate_current_flow_betweenness_centrality,
+    ),
+)
+def test_unconnected_graphs_betweenness_centrality(centrality_func):
+    G = nx.Graph([(1, 2), (3, 4)])
+    G.add_node(5)
+    with pytest.raises(nx.NetworkXError, match="Graph not connected"):
+        centrality_func(G)

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/centrality/tests/test_current_flow_betweenness_centrality_subset.py

@@ -0,0 +1,147 @@
+import pytest
+
+pytest.importorskip("numpy")
+pytest.importorskip("scipy")
+
+import networkx as nx
+from networkx import edge_current_flow_betweenness_centrality as edge_current_flow
+from networkx import (
+    edge_current_flow_betweenness_centrality_subset as edge_current_flow_subset,
+)
+
+
+class TestFlowBetweennessCentrality:
+    def test_K4_normalized(self):
+        """Betweenness centrality: K4"""
+        G = nx.complete_graph(4)
+        b = nx.current_flow_betweenness_centrality_subset(
+            G, list(G), list(G), normalized=True
+        )
+        b_answer = nx.current_flow_betweenness_centrality(G, normalized=True)
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-7)
+
+    def test_K4(self):
+        """Betweenness centrality: K4"""
+        G = nx.complete_graph(4)
+        b = nx.current_flow_betweenness_centrality_subset(
+            G, list(G), list(G), normalized=True
+        )
+        b_answer = nx.current_flow_betweenness_centrality(G, normalized=True)
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-7)
+        # test weighted network
+        G.add_edge(0, 1, weight=0.5, other=0.3)
+        b = nx.current_flow_betweenness_centrality_subset(
+            G, list(G), list(G), normalized=True, weight=None
+        )
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-7)
+        b = nx.current_flow_betweenness_centrality_subset(
+            G, list(G), list(G), normalized=True
+        )
+        b_answer = nx.current_flow_betweenness_centrality(G, normalized=True)
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-7)
+        b = nx.current_flow_betweenness_centrality_subset(
+            G, list(G), list(G), normalized=True, weight="other"
+        )
+        b_answer = nx.current_flow_betweenness_centrality(
+            G, normalized=True, weight="other"
+        )
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-7)
+
+    def test_P4_normalized(self):
+        """Betweenness centrality: P4 normalized"""
+        G = nx.path_graph(4)
+        b = nx.current_flow_betweenness_centrality_subset(
+            G, list(G), list(G), normalized=True
+        )
+        b_answer = nx.current_flow_betweenness_centrality(G, normalized=True)
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-7)
+
+    def test_P4(self):
+        """Betweenness centrality: P4"""
+        G = nx.path_graph(4)
+        b = nx.current_flow_betweenness_centrality_subset(
+            G, list(G), list(G), normalized=True
+        )
+        b_answer = nx.current_flow_betweenness_centrality(G, normalized=True)
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-7)
+
+    def test_star(self):
+        """Betweenness centrality: star"""
+        G = nx.Graph()
+        nx.add_star(G, ["a", "b", "c", "d"])
+        b = nx.current_flow_betweenness_centrality_subset(
+            G, list(G), list(G), normalized=True
+        )
+        b_answer = nx.current_flow_betweenness_centrality(G, normalized=True)
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-7)
+
+
+# class TestWeightedFlowBetweennessCentrality():
+#     pass
+
+
+class TestEdgeFlowBetweennessCentrality:
+    def test_K4_normalized(self):
+        """Betweenness centrality: K4"""
+        G = nx.complete_graph(4)
+        b = edge_current_flow_subset(G, list(G), list(G), normalized=True)
+        b_answer = edge_current_flow(G, normalized=True)
+        for (s, t), v1 in b_answer.items():
+            v2 = b.get((s, t), b.get((t, s)))
+            assert v1 == pytest.approx(v2, abs=1e-7)
+
+    def test_K4(self):
+        """Betweenness centrality: K4"""
+        G = nx.complete_graph(4)
+        b = edge_current_flow_subset(G, list(G), list(G), normalized=False)
+        b_answer = edge_current_flow(G, normalized=False)
+        for (s, t), v1 in b_answer.items():
+            v2 = b.get((s, t), b.get((t, s)))
+            assert v1 == pytest.approx(v2, abs=1e-7)
+        # test weighted network
+        G.add_edge(0, 1, weight=0.5, other=0.3)
+        b = edge_current_flow_subset(G, list(G), list(G), normalized=False, weight=None)
+        # weight is None => same as unweighted network
+        for (s, t), v1 in b_answer.items():
+            v2 = b.get((s, t), b.get((t, s)))
+            assert v1 == pytest.approx(v2, abs=1e-7)
+
+        b = edge_current_flow_subset(G, list(G), list(G), normalized=False)
+        b_answer = edge_current_flow(G, normalized=False)
+        for (s, t), v1 in b_answer.items():
+            v2 = b.get((s, t), b.get((t, s)))
+            assert v1 == pytest.approx(v2, abs=1e-7)
+
+        b = edge_current_flow_subset(
+            G, list(G), list(G), normalized=False, weight="other"
+        )
+        b_answer = edge_current_flow(G, normalized=False, weight="other")
+        for (s, t), v1 in b_answer.items():
+            v2 = b.get((s, t), b.get((t, s)))
+            assert v1 == pytest.approx(v2, abs=1e-7)
+
+    def test_C4(self):
+        """Edge betweenness centrality: C4"""
+        G = nx.cycle_graph(4)
+        b = edge_current_flow_subset(G, list(G), list(G), normalized=True)
+        b_answer = edge_current_flow(G, normalized=True)
+        for (s, t), v1 in b_answer.items():
+            v2 = b.get((s, t), b.get((t, s)))
+            assert v1 == pytest.approx(v2, abs=1e-7)
+
+    def test_P4(self):
+        """Edge betweenness centrality: P4"""
+        G = nx.path_graph(4)
+        b = edge_current_flow_subset(G, list(G), list(G), normalized=True)
+        b_answer = edge_current_flow(G, normalized=True)
+        for (s, t), v1 in b_answer.items():
+            v2 = b.get((s, t), b.get((t, s)))
+            assert v1 == pytest.approx(v2, abs=1e-7)

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/centrality/tests/test_degree_centrality.py

@@ -0,0 +1,144 @@
+"""
+    Unit tests for degree centrality.
+"""
+
+import pytest
+
+import networkx as nx
+
+
+class TestDegreeCentrality:
+    def setup_method(self):
+        self.K = nx.krackhardt_kite_graph()
+        self.P3 = nx.path_graph(3)
+        self.K5 = nx.complete_graph(5)
+
+        F = nx.Graph()  # Florentine families
+        F.add_edge("Acciaiuoli", "Medici")
+        F.add_edge("Castellani", "Peruzzi")
+        F.add_edge("Castellani", "Strozzi")
+        F.add_edge("Castellani", "Barbadori")
+        F.add_edge("Medici", "Barbadori")
+        F.add_edge("Medici", "Ridolfi")
+        F.add_edge("Medici", "Tornabuoni")
+        F.add_edge("Medici", "Albizzi")
+        F.add_edge("Medici", "Salviati")
+        F.add_edge("Salviati", "Pazzi")
+        F.add_edge("Peruzzi", "Strozzi")
+        F.add_edge("Peruzzi", "Bischeri")
+        F.add_edge("Strozzi", "Ridolfi")
+        F.add_edge("Strozzi", "Bischeri")
+        F.add_edge("Ridolfi", "Tornabuoni")
+        F.add_edge("Tornabuoni", "Guadagni")
+        F.add_edge("Albizzi", "Ginori")
+        F.add_edge("Albizzi", "Guadagni")
+        F.add_edge("Bischeri", "Guadagni")
+        F.add_edge("Guadagni", "Lamberteschi")
+        self.F = F
+
+        G = nx.DiGraph()
+        G.add_edge(0, 5)
+        G.add_edge(1, 5)
+        G.add_edge(2, 5)
+        G.add_edge(3, 5)
+        G.add_edge(4, 5)
+        G.add_edge(5, 6)
+        G.add_edge(5, 7)
+        G.add_edge(5, 8)
+        self.G = G
+
+    def test_degree_centrality_1(self):
+        d = nx.degree_centrality(self.K5)
+        exact = dict(zip(range(5), [1] * 5))
+        for n, dc in d.items():
+            assert exact[n] == pytest.approx(dc, abs=1e-7)
+
+    def test_degree_centrality_2(self):
+        d = nx.degree_centrality(self.P3)
+        exact = {0: 0.5, 1: 1, 2: 0.5}
+        for n, dc in d.items():
+            assert exact[n] == pytest.approx(dc, abs=1e-7)
+
+    def test_degree_centrality_3(self):
+        d = nx.degree_centrality(self.K)
+        exact = {
+            0: 0.444,
+            1: 0.444,
+            2: 0.333,
+            3: 0.667,
+            4: 0.333,
+            5: 0.556,
+            6: 0.556,
+            7: 0.333,
+            8: 0.222,
+            9: 0.111,
+        }
+        for n, dc in d.items():
+            assert exact[n] == pytest.approx(float(f"{dc:.3f}"), abs=1e-7)
+
+    def test_degree_centrality_4(self):
+        d = nx.degree_centrality(self.F)
+        names = sorted(self.F.nodes())
+        dcs = [
+            0.071,
+            0.214,
+            0.143,
+            0.214,
+            0.214,
+            0.071,
+            0.286,
+            0.071,
+            0.429,
+            0.071,
+            0.214,
+            0.214,
+            0.143,
+            0.286,
+            0.214,
+        ]
+        exact = dict(zip(names, dcs))
+        for n, dc in d.items():
+            assert exact[n] == pytest.approx(float(f"{dc:.3f}"), abs=1e-7)
+
+    def test_indegree_centrality(self):
+        d = nx.in_degree_centrality(self.G)
+        exact = {
+            0: 0.0,
+            1: 0.0,
+            2: 0.0,
+            3: 0.0,
+            4: 0.0,
+            5: 0.625,
+            6: 0.125,
+            7: 0.125,
+            8: 0.125,
+        }
+        for n, dc in d.items():
+            assert exact[n] == pytest.approx(dc, abs=1e-7)
+
+    def test_outdegree_centrality(self):
+        d = nx.out_degree_centrality(self.G)
+        exact = {
+            0: 0.125,
+            1: 0.125,
+            2: 0.125,
+            3: 0.125,
+            4: 0.125,
+            5: 0.375,
+            6: 0.0,
+            7: 0.0,
+            8: 0.0,
+        }
+        for n, dc in d.items():
+            assert exact[n] == pytest.approx(dc, abs=1e-7)
+
+    def test_small_graph_centrality(self):
+        G = nx.empty_graph(create_using=nx.DiGraph)
+        assert {} == nx.degree_centrality(G)
+        assert {} == nx.out_degree_centrality(G)
+        assert {} == nx.in_degree_centrality(G)
+
+        G = nx.empty_graph(1, create_using=nx.DiGraph)
+        assert {0: 1} == nx.degree_centrality(G)
+        assert {0: 1} == nx.out_degree_centrality(G)
+        assert {0: 1} == nx.in_degree_centrality(G)

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/centrality/tests/test_group.py

@@ -0,0 +1,278 @@
+"""
+Tests for Group Centrality Measures
+"""
+
+
+import pytest
+
+import networkx as nx
+
+
+class TestGroupBetweennessCentrality:
+    def test_group_betweenness_single_node(self):
+        """
+        Group betweenness centrality for single node group
+        """
+        G = nx.path_graph(5)
+        C = [1]
+        b = nx.group_betweenness_centrality(
+            G, C, weight=None, normalized=False, endpoints=False
+        )
+        b_answer = 3.0
+        assert b == b_answer
+
+    def test_group_betweenness_with_endpoints(self):
+        """
+        Group betweenness centrality for single node group
+        """
+        G = nx.path_graph(5)
+        C = [1]
+        b = nx.group_betweenness_centrality(
+            G, C, weight=None, normalized=False, endpoints=True
+        )
+        b_answer = 7.0
+        assert b == b_answer
+
+    def test_group_betweenness_normalized(self):
+        """
+        Group betweenness centrality for group with more than
+        1 node and normalized
+        """
+        G = nx.path_graph(5)
+        C = [1, 3]
+        b = nx.group_betweenness_centrality(
+            G, C, weight=None, normalized=True, endpoints=False
+        )
+        b_answer = 1.0
+        assert b == b_answer
+
+    def test_two_group_betweenness_value_zero(self):
+        """
+        Group betweenness centrality value of 0
+        """
+        G = nx.cycle_graph(7)
+        C = [[0, 1, 6], [0, 1, 5]]
+        b = nx.group_betweenness_centrality(G, C, weight=None, normalized=False)
+        b_answer = [0.0, 3.0]
+        assert b == b_answer
+
+    def test_group_betweenness_value_zero(self):
+        """
+        Group betweenness centrality value of 0
+        """
+        G = nx.cycle_graph(6)
+        C = [0, 1, 5]
+        b = nx.group_betweenness_centrality(G, C, weight=None, normalized=False)
+        b_answer = 0.0
+        assert b == b_answer
+
+    def test_group_betweenness_disconnected_graph(self):
+        """
+        Group betweenness centrality in a disconnected graph
+        """
+        G = nx.path_graph(5)
+        G.remove_edge(0, 1)
+        C = [1]
+        b = nx.group_betweenness_centrality(G, C, weight=None, normalized=False)
+        b_answer = 0.0
+        assert b == b_answer
+
+    def test_group_betweenness_node_not_in_graph(self):
+        """
+        Node(s) in C not in graph, raises NodeNotFound exception
+        """
+        with pytest.raises(nx.NodeNotFound):
+            nx.group_betweenness_centrality(nx.path_graph(5), [4, 7, 8])
+
+    def test_group_betweenness_directed_weighted(self):
+        """
+        Group betweenness centrality in a directed and weighted graph
+        """
+        G = nx.DiGraph()
+        G.add_edge(1, 0, weight=1)
+        G.add_edge(0, 2, weight=2)
+        G.add_edge(1, 2, weight=3)
+        G.add_edge(3, 1, weight=4)
+        G.add_edge(2, 3, weight=1)
+        G.add_edge(4, 3, weight=6)
+        G.add_edge(2, 4, weight=7)
+        C = [1, 2]
+        b = nx.group_betweenness_centrality(G, C, weight="weight", normalized=False)
+        b_answer = 5.0
+        assert b == b_answer
+
+
+class TestProminentGroup:
+    np = pytest.importorskip("numpy")
+    pd = pytest.importorskip("pandas")
+
+    def test_prominent_group_single_node(self):
+        """
+        Prominent group for single node
+        """
+        G = nx.path_graph(5)
+        k = 1
+        b, g = nx.prominent_group(G, k, normalized=False, endpoints=False)
+        b_answer, g_answer = 4.0, [2]
+        assert b == b_answer and g == g_answer
+
+    def test_prominent_group_with_c(self):
+        """
+        Prominent group without some nodes
+        """
+        G = nx.path_graph(5)
+        k = 1
+        b, g = nx.prominent_group(G, k, normalized=False, C=[2])
+        b_answer, g_answer = 3.0, [1]
+        assert b == b_answer and g == g_answer
+
+    def test_prominent_group_normalized_endpoints(self):
+        """
+        Prominent group with normalized result, with endpoints
+        """
+        G = nx.cycle_graph(7)
+        k = 2
+        b, g = nx.prominent_group(G, k, normalized=True, endpoints=True)
+        b_answer, g_answer = 1.7, [2, 5]
+        assert b == b_answer and g == g_answer
+
+    def test_prominent_group_disconnected_graph(self):
+        """
+        Prominent group of disconnected graph
+        """
+        G = nx.path_graph(6)
+        G.remove_edge(0, 1)
+        k = 1
+        b, g = nx.prominent_group(G, k, weight=None, normalized=False)
+        b_answer, g_answer = 4.0, [3]
+        assert b == b_answer and g == g_answer
+
+    def test_prominent_group_node_not_in_graph(self):
+        """
+        Node(s) in C not in graph, raises NodeNotFound exception
+        """
+        with pytest.raises(nx.NodeNotFound):
+            nx.prominent_group(nx.path_graph(5), 1, C=[10])
+
+    def test_group_betweenness_directed_weighted(self):
+        """
+        Group betweenness centrality in a directed and weighted graph
+        """
+        G = nx.DiGraph()
+        G.add_edge(1, 0, weight=1)
+        G.add_edge(0, 2, weight=2)
+        G.add_edge(1, 2, weight=3)
+        G.add_edge(3, 1, weight=4)
+        G.add_edge(2, 3, weight=1)
+        G.add_edge(4, 3, weight=6)
+        G.add_edge(2, 4, weight=7)
+        k = 2
+        b, g = nx.prominent_group(G, k, weight="weight", normalized=False)
+        b_answer, g_answer = 5.0, [1, 2]
+        assert b == b_answer and g == g_answer
+
+    def test_prominent_group_greedy_algorithm(self):
+        """
+        Group betweenness centrality in a greedy algorithm
+        """
+        G = nx.cycle_graph(7)
+        k = 2
+        b, g = nx.prominent_group(G, k, normalized=True, endpoints=True, greedy=True)
+        b_answer, g_answer = 1.7, [6, 3]
+        assert b == b_answer and g == g_answer
+
+
+class TestGroupClosenessCentrality:
+    def test_group_closeness_single_node(self):
+        """
+        Group closeness centrality for a single node group
+        """
+        G = nx.path_graph(5)
+        c = nx.group_closeness_centrality(G, [1])
+        c_answer = nx.closeness_centrality(G, 1)
+        assert c == c_answer
+
+    def test_group_closeness_disconnected(self):
+        """
+        Group closeness centrality for a disconnected graph
+        """
+        G = nx.Graph()
+        G.add_nodes_from([1, 2, 3, 4])
+        c = nx.group_closeness_centrality(G, [1, 2])
+        c_answer = 0
+        assert c == c_answer
+
+    def test_group_closeness_multiple_node(self):
+        """
+        Group closeness centrality for a group with more than
+        1 node
+        """
+        G = nx.path_graph(4)
+        c = nx.group_closeness_centrality(G, [1, 2])
+        c_answer = 1
+        assert c == c_answer
+
+    def test_group_closeness_node_not_in_graph(self):
+        """
+        Node(s) in S not in graph, raises NodeNotFound exception
+        """
+        with pytest.raises(nx.NodeNotFound):
+            nx.group_closeness_centrality(nx.path_graph(5), [6, 7, 8])
+
+
+class TestGroupDegreeCentrality:
+    def test_group_degree_centrality_single_node(self):
+        """
+        Group degree centrality for a single node group
+        """
+        G = nx.path_graph(4)
+        d = nx.group_degree_centrality(G, [1])
+        d_answer = nx.degree_centrality(G)[1]
+        assert d == d_answer
+
+    def test_group_degree_centrality_multiple_node(self):
+        """
+        Group degree centrality for group with more than
+        1 node
+        """
+        G = nx.Graph()
+        G.add_nodes_from([1, 2, 3, 4, 5, 6, 7, 8])
+        G.add_edges_from(
+            [(1, 2), (1, 3), (1, 6), (1, 7), (1, 8), (2, 3), (2, 4), (2, 5)]
+        )
+        d = nx.group_degree_centrality(G, [1, 2])
+        d_answer = 1
+        assert d == d_answer
+
+    def test_group_in_degree_centrality(self):
+        """
+        Group in-degree centrality in a DiGraph
+        """
+        G = nx.DiGraph()
+        G.add_nodes_from([1, 2, 3, 4, 5, 6, 7, 8])
+        G.add_edges_from(
+            [(1, 2), (1, 3), (1, 6), (1, 7), (1, 8), (2, 3), (2, 4), (2, 5)]
+        )
+        d = nx.group_in_degree_centrality(G, [1, 2])
+        d_answer = 0
+        assert d == d_answer
+
+    def test_group_out_degree_centrality(self):
+        """
+        Group out-degree centrality in a DiGraph
+        """
+        G = nx.DiGraph()
+        G.add_nodes_from([1, 2, 3, 4, 5, 6, 7, 8])
+        G.add_edges_from(
+            [(1, 2), (1, 3), (1, 6), (1, 7), (1, 8), (2, 3), (2, 4), (2, 5)]
+        )
+        d = nx.group_out_degree_centrality(G, [1, 2])
+        d_answer = 1
+        assert d == d_answer
+
+    def test_group_degree_centrality_node_not_in_graph(self):
+        """
+        Node(s) in S not in graph, raises NetworkXError
+        """
+        with pytest.raises(nx.NetworkXError):
+            nx.group_degree_centrality(nx.path_graph(5), [6, 7, 8])

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/centrality/tests/test_katz_centrality.py

@@ -0,0 +1,345 @@
+import math
+
+import pytest
+
+import networkx as nx
+
+
+class TestKatzCentrality:
+    def test_K5(self):
+        """Katz centrality: K5"""
+        G = nx.complete_graph(5)
+        alpha = 0.1
+        b = nx.katz_centrality(G, alpha)
+        v = math.sqrt(1 / 5.0)
+        b_answer = dict.fromkeys(G, v)
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-7)
+        nstart = {n: 1 for n in G}
+        b = nx.katz_centrality(G, alpha, nstart=nstart)
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-7)
+
+    def test_P3(self):
+        """Katz centrality: P3"""
+        alpha = 0.1
+        G = nx.path_graph(3)
+        b_answer = {0: 0.5598852584152165, 1: 0.6107839182711449, 2: 0.5598852584152162}
+        b = nx.katz_centrality(G, alpha)
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-4)
+
+    def test_maxiter(self):
+        with pytest.raises(nx.PowerIterationFailedConvergence):
+            nx.katz_centrality(nx.path_graph(3), 0.1, max_iter=0)
+
+    def test_beta_as_scalar(self):
+        alpha = 0.1
+        beta = 0.1
+        b_answer = {0: 0.5598852584152165, 1: 0.6107839182711449, 2: 0.5598852584152162}
+        G = nx.path_graph(3)
+        b = nx.katz_centrality(G, alpha, beta)
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-4)
+
+    def test_beta_as_dict(self):
+        alpha = 0.1
+        beta = {0: 1.0, 1: 1.0, 2: 1.0}
+        b_answer = {0: 0.5598852584152165, 1: 0.6107839182711449, 2: 0.5598852584152162}
+        G = nx.path_graph(3)
+        b = nx.katz_centrality(G, alpha, beta)
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-4)
+
+    def test_multiple_alpha(self):
+        alpha_list = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6]
+        for alpha in alpha_list:
+            b_answer = {
+                0.1: {
+                    0: 0.5598852584152165,
+                    1: 0.6107839182711449,
+                    2: 0.5598852584152162,
+                },
+                0.2: {
+                    0: 0.5454545454545454,
+                    1: 0.6363636363636365,
+                    2: 0.5454545454545454,
+                },
+                0.3: {
+                    0: 0.5333964609104419,
+                    1: 0.6564879518897746,
+                    2: 0.5333964609104419,
+                },
+                0.4: {
+                    0: 0.5232045649263551,
+                    1: 0.6726915834767423,
+                    2: 0.5232045649263551,
+                },
+                0.5: {
+                    0: 0.5144957746691622,
+                    1: 0.6859943117075809,
+                    2: 0.5144957746691622,
+                },
+                0.6: {
+                    0: 0.5069794004195823,
+                    1: 0.6970966755769258,
+                    2: 0.5069794004195823,
+                },
+            }
+            G = nx.path_graph(3)
+            b = nx.katz_centrality(G, alpha)
+            for n in sorted(G):
+                assert b[n] == pytest.approx(b_answer[alpha][n], abs=1e-4)
+
+    def test_multigraph(self):
+        with pytest.raises(nx.NetworkXException):
+            nx.katz_centrality(nx.MultiGraph(), 0.1)
+
+    def test_empty(self):
+        e = nx.katz_centrality(nx.Graph(), 0.1)
+        assert e == {}
+
+    def test_bad_beta(self):
+        with pytest.raises(nx.NetworkXException):
+            G = nx.Graph([(0, 1)])
+            beta = {0: 77}
+            nx.katz_centrality(G, 0.1, beta=beta)
+
+    def test_bad_beta_number(self):
+        with pytest.raises(nx.NetworkXException):
+            G = nx.Graph([(0, 1)])
+            nx.katz_centrality(G, 0.1, beta="foo")
+
+
+class TestKatzCentralityNumpy:
+    @classmethod
+    def setup_class(cls):
+        global np
+        np = pytest.importorskip("numpy")
+        pytest.importorskip("scipy")
+
+    def test_K5(self):
+        """Katz centrality: K5"""
+        G = nx.complete_graph(5)
+        alpha = 0.1
+        b = nx.katz_centrality(G, alpha)
+        v = math.sqrt(1 / 5.0)
+        b_answer = dict.fromkeys(G, v)
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-7)
+        b = nx.eigenvector_centrality_numpy(G)
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-3)
+
+    def test_P3(self):
+        """Katz centrality: P3"""
+        alpha = 0.1
+        G = nx.path_graph(3)
+        b_answer = {0: 0.5598852584152165, 1: 0.6107839182711449, 2: 0.5598852584152162}
+        b = nx.katz_centrality_numpy(G, alpha)
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-4)
+
+    def test_beta_as_scalar(self):
+        alpha = 0.1
+        beta = 0.1
+        b_answer = {0: 0.5598852584152165, 1: 0.6107839182711449, 2: 0.5598852584152162}
+        G = nx.path_graph(3)
+        b = nx.katz_centrality_numpy(G, alpha, beta)
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-4)
+
+    def test_beta_as_dict(self):
+        alpha = 0.1
+        beta = {0: 1.0, 1: 1.0, 2: 1.0}
+        b_answer = {0: 0.5598852584152165, 1: 0.6107839182711449, 2: 0.5598852584152162}
+        G = nx.path_graph(3)
+        b = nx.katz_centrality_numpy(G, alpha, beta)
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-4)
+
+    def test_multiple_alpha(self):
+        alpha_list = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6]
+        for alpha in alpha_list:
+            b_answer = {
+                0.1: {
+                    0: 0.5598852584152165,
+                    1: 0.6107839182711449,
+                    2: 0.5598852584152162,
+                },
+                0.2: {
+                    0: 0.5454545454545454,
+                    1: 0.6363636363636365,
+                    2: 0.5454545454545454,
+                },
+                0.3: {
+                    0: 0.5333964609104419,
+                    1: 0.6564879518897746,
+                    2: 0.5333964609104419,
+                },
+                0.4: {
+                    0: 0.5232045649263551,
+                    1: 0.6726915834767423,
+                    2: 0.5232045649263551,
+                },
+                0.5: {
+                    0: 0.5144957746691622,
+                    1: 0.6859943117075809,
+                    2: 0.5144957746691622,
+                },
+                0.6: {
+                    0: 0.5069794004195823,
+                    1: 0.6970966755769258,
+                    2: 0.5069794004195823,
+                },
+            }
+            G = nx.path_graph(3)
+            b = nx.katz_centrality_numpy(G, alpha)
+            for n in sorted(G):
+                assert b[n] == pytest.approx(b_answer[alpha][n], abs=1e-4)
+
+    def test_multigraph(self):
+        with pytest.raises(nx.NetworkXException):
+            nx.katz_centrality(nx.MultiGraph(), 0.1)
+
+    def test_empty(self):
+        e = nx.katz_centrality(nx.Graph(), 0.1)
+        assert e == {}
+
+    def test_bad_beta(self):
+        with pytest.raises(nx.NetworkXException):
+            G = nx.Graph([(0, 1)])
+            beta = {0: 77}
+            nx.katz_centrality_numpy(G, 0.1, beta=beta)
+
+    def test_bad_beta_numbe(self):
+        with pytest.raises(nx.NetworkXException):
+            G = nx.Graph([(0, 1)])
+            nx.katz_centrality_numpy(G, 0.1, beta="foo")
+
+    def test_K5_unweighted(self):
+        """Katz centrality: K5"""
+        G = nx.complete_graph(5)
+        alpha = 0.1
+        b = nx.katz_centrality(G, alpha, weight=None)
+        v = math.sqrt(1 / 5.0)
+        b_answer = dict.fromkeys(G, v)
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-7)
+        b = nx.eigenvector_centrality_numpy(G, weight=None)
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-3)
+
+    def test_P3_unweighted(self):
+        """Katz centrality: P3"""
+        alpha = 0.1
+        G = nx.path_graph(3)
+        b_answer = {0: 0.5598852584152165, 1: 0.6107839182711449, 2: 0.5598852584152162}
+        b = nx.katz_centrality_numpy(G, alpha, weight=None)
+        for n in sorted(G):
+            assert b[n] == pytest.approx(b_answer[n], abs=1e-4)
+
+
+class TestKatzCentralityDirected:
+    @classmethod
+    def setup_class(cls):
+        G = nx.DiGraph()
+        edges = [
+            (1, 2),
+            (1, 3),
+            (2, 4),
+            (3, 2),
+            (3, 5),
+            (4, 2),
+            (4, 5),
+            (4, 6),
+            (5, 6),
+            (5, 7),
+            (5, 8),
+            (6, 8),
+            (7, 1),
+            (7, 5),
+            (7, 8),
+            (8, 6),
+            (8, 7),
+        ]
+        G.add_edges_from(edges, weight=2.0)
+        cls.G = G.reverse()
+        cls.G.alpha = 0.1
+        cls.G.evc = [
+            0.3289589783189635,
+            0.2832077296243516,
+            0.3425906003685471,
+            0.3970420865198392,
+            0.41074871061646284,
+            0.272257430756461,
+            0.4201989685435462,
+            0.34229059218038554,
+        ]
+
+        H = nx.DiGraph(edges)
+        cls.H = G.reverse()
+        cls.H.alpha = 0.1
+        cls.H.evc = [
+            0.3289589783189635,
+            0.2832077296243516,
+            0.3425906003685471,
+            0.3970420865198392,
+            0.41074871061646284,
+            0.272257430756461,
+            0.4201989685435462,
+            0.34229059218038554,
+        ]
+
+    def test_katz_centrality_weighted(self):
+        G = self.G
+        alpha = self.G.alpha
+        p = nx.katz_centrality(G, alpha, weight="weight")
+        for a, b in zip(list(p.values()), self.G.evc):
+            assert a == pytest.approx(b, abs=1e-7)
+
+    def test_katz_centrality_unweighted(self):
+        H = self.H
+        alpha = self.H.alpha
+        p = nx.katz_centrality(H, alpha, weight="weight")
+        for a, b in zip(list(p.values()), self.H.evc):
+            assert a == pytest.approx(b, abs=1e-7)
+
+
+class TestKatzCentralityDirectedNumpy(TestKatzCentralityDirected):
+    @classmethod
+    def setup_class(cls):
+        global np
+        np = pytest.importorskip("numpy")
+        pytest.importorskip("scipy")
+        super().setup_class()
+
+    def test_katz_centrality_weighted(self):
+        G = self.G
+        alpha = self.G.alpha
+        p = nx.katz_centrality_numpy(G, alpha, weight="weight")
+        for a, b in zip(list(p.values()), self.G.evc):
+            assert a == pytest.approx(b, abs=1e-7)
+
+    def test_katz_centrality_unweighted(self):
+        H = self.H
+        alpha = self.H.alpha
+        p = nx.katz_centrality_numpy(H, alpha, weight="weight")
+        for a, b in zip(list(p.values()), self.H.evc):
+            assert a == pytest.approx(b, abs=1e-7)
+
+
+class TestKatzEigenvectorVKatz:
+    @classmethod
+    def setup_class(cls):
+        global np
+        np = pytest.importorskip("numpy")
+        pytest.importorskip("scipy")
+
+    def test_eigenvector_v_katz_random(self):
+        G = nx.gnp_random_graph(10, 0.5, seed=1234)
+        l = max(np.linalg.eigvals(nx.adjacency_matrix(G).todense()))
+        e = nx.eigenvector_centrality_numpy(G)
+        k = nx.katz_centrality_numpy(G, 1.0 / l)
+        for n in G:
+            assert e[n] == pytest.approx(k[n], abs=1e-7)

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/centrality/tests/test_subgraph.py

@@ -0,0 +1,110 @@
+import pytest
+
+pytest.importorskip("numpy")
+pytest.importorskip("scipy")
+
+import networkx as nx
+from networkx.algorithms.centrality.subgraph_alg import (
+    communicability_betweenness_centrality,
+    estrada_index,
+    subgraph_centrality,
+    subgraph_centrality_exp,
+)
+
+
+class TestSubgraph:
+    def test_subgraph_centrality(self):
+        answer = {0: 1.5430806348152433, 1: 1.5430806348152433}
+        result = subgraph_centrality(nx.path_graph(2))
+        for k, v in result.items():
+            assert answer[k] == pytest.approx(v, abs=1e-7)
+
+        answer1 = {
+            "1": 1.6445956054135658,
+            "Albert": 2.4368257358712189,
+            "Aric": 2.4368257358712193,
+            "Dan": 3.1306328496328168,
+            "Franck": 2.3876142275231915,
+        }
+        G1 = nx.Graph(
+            [
+                ("Franck", "Aric"),
+                ("Aric", "Dan"),
+                ("Dan", "Albert"),
+                ("Albert", "Franck"),
+                ("Dan", "1"),
+                ("Franck", "Albert"),
+            ]
+        )
+        result1 = subgraph_centrality(G1)
+        for k, v in result1.items():
+            assert answer1[k] == pytest.approx(v, abs=1e-7)
+        result1 = subgraph_centrality_exp(G1)
+        for k, v in result1.items():
+            assert answer1[k] == pytest.approx(v, abs=1e-7)
+
+    def test_subgraph_centrality_big_graph(self):
+        g199 = nx.complete_graph(199)
+        g200 = nx.complete_graph(200)
+
+        comm199 = nx.subgraph_centrality(g199)
+        comm199_exp = nx.subgraph_centrality_exp(g199)
+
+        comm200 = nx.subgraph_centrality(g200)
+        comm200_exp = nx.subgraph_centrality_exp(g200)
+
+    def test_communicability_betweenness_centrality_small(self):
+        result = communicability_betweenness_centrality(nx.path_graph(2))
+        assert result == {0: 0, 1: 0}
+
+        result = communicability_betweenness_centrality(nx.path_graph(1))
+        assert result == {0: 0}
+
+        result = communicability_betweenness_centrality(nx.path_graph(0))
+        assert result == {}
+
+        answer = {0: 0.1411224421177313, 1: 1.0, 2: 0.1411224421177313}
+        result = communicability_betweenness_centrality(nx.path_graph(3))
+        for k, v in result.items():
+            assert answer[k] == pytest.approx(v, abs=1e-7)
+
+        result = communicability_betweenness_centrality(nx.complete_graph(3))
+        for k, v in result.items():
+            assert 0.49786143366223296 == pytest.approx(v, abs=1e-7)
+
+    def test_communicability_betweenness_centrality(self):
+        answer = {
+            0: 0.07017447951484615,
+            1: 0.71565598701107991,
+            2: 0.71565598701107991,
+            3: 0.07017447951484615,
+        }
+        result = communicability_betweenness_centrality(nx.path_graph(4))
+        for k, v in result.items():
+            assert answer[k] == pytest.approx(v, abs=1e-7)
+
+        answer1 = {
+            "1": 0.060039074193949521,
+            "Albert": 0.315470761661372,
+            "Aric": 0.31547076166137211,
+            "Dan": 0.68297778678316201,
+            "Franck": 0.21977926617449497,
+        }
+        G1 = nx.Graph(
+            [
+                ("Franck", "Aric"),
+                ("Aric", "Dan"),
+                ("Dan", "Albert"),
+                ("Albert", "Franck"),
+                ("Dan", "1"),
+                ("Franck", "Albert"),
+            ]
+        )
+        result1 = communicability_betweenness_centrality(G1)
+        for k, v in result1.items():
+            assert answer1[k] == pytest.approx(v, abs=1e-7)
+
+    def test_estrada_index(self):
+        answer = 1041.2470334195475
+        result = estrada_index(nx.karate_club_graph())
+        assert answer == pytest.approx(result, abs=1e-7)

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/centrality/tests/test_trophic.py

@@ -0,0 +1,302 @@
+"""Test trophic levels, trophic differences and trophic coherence
+"""
+import pytest
+
+np = pytest.importorskip("numpy")
+pytest.importorskip("scipy")
+
+import networkx as nx
+
+
+def test_trophic_levels():
+    """Trivial example"""
+    G = nx.DiGraph()
+    G.add_edge("a", "b")
+    G.add_edge("b", "c")
+
+    d = nx.trophic_levels(G)
+    assert d == {"a": 1, "b": 2, "c": 3}
+
+
+def test_trophic_levels_levine():
+    """Example from Figure 5 in Stephen Levine (1980) J. theor. Biol. 83,
+    195-207
+    """
+    S = nx.DiGraph()
+    S.add_edge(1, 2, weight=1.0)
+    S.add_edge(1, 3, weight=0.2)
+    S.add_edge(1, 4, weight=0.8)
+    S.add_edge(2, 3, weight=0.2)
+    S.add_edge(2, 5, weight=0.3)
+    S.add_edge(4, 3, weight=0.6)
+    S.add_edge(4, 5, weight=0.7)
+    S.add_edge(5, 4, weight=0.2)
+
+    # save copy for later, test intermediate implementation details first
+    S2 = S.copy()
+
+    # drop nodes of in-degree zero
+    z = [nid for nid, d in S.in_degree if d == 0]
+    for nid in z:
+        S.remove_node(nid)
+
+    # find adjacency matrix
+    q = nx.linalg.graphmatrix.adjacency_matrix(S).T
+
+    # fmt: off
+    expected_q = np.array([
+        [0, 0, 0., 0],
+        [0.2, 0, 0.6, 0],
+        [0, 0, 0, 0.2],
+        [0.3, 0, 0.7, 0]
+    ])
+    # fmt: on
+    assert np.array_equal(q.todense(), expected_q)
+
+    # must be square, size of number of nodes
+    assert len(q.shape) == 2
+    assert q.shape[0] == q.shape[1]
+    assert q.shape[0] == len(S)
+
+    nn = q.shape[0]
+
+    i = np.eye(nn)
+    n = np.linalg.inv(i - q)
+    y = np.asarray(n) @ np.ones(nn)
+
+    expected_y = np.array([1, 2.07906977, 1.46511628, 2.3255814])
+    assert np.allclose(y, expected_y)
+
+    expected_d = {1: 1, 2: 2, 3: 3.07906977, 4: 2.46511628, 5: 3.3255814}
+
+    d = nx.trophic_levels(S2)
+
+    for nid, level in d.items():
+        expected_level = expected_d[nid]
+        assert expected_level == pytest.approx(level, abs=1e-7)
+
+
+def test_trophic_levels_simple():
+    matrix_a = np.array([[0, 0], [1, 0]])
+    G = nx.from_numpy_array(matrix_a, create_using=nx.DiGraph)
+    d = nx.trophic_levels(G)
+    assert d[0] == pytest.approx(2, abs=1e-7)
+    assert d[1] == pytest.approx(1, abs=1e-7)
+
+
+def test_trophic_levels_more_complex():
+    # fmt: off
+    matrix = np.array([
+        [0, 1, 0, 0],
+        [0, 0, 1, 0],
+        [0, 0, 0, 1],
+        [0, 0, 0, 0]
+    ])
+    # fmt: on
+    G = nx.from_numpy_array(matrix, create_using=nx.DiGraph)
+    d = nx.trophic_levels(G)
+    expected_result = [1, 2, 3, 4]
+    for ind in range(4):
+        assert d[ind] == pytest.approx(expected_result[ind], abs=1e-7)
+
+    # fmt: off
+    matrix = np.array([
+        [0, 1, 1, 0],
+        [0, 0, 1, 1],
+        [0, 0, 0, 1],
+        [0, 0, 0, 0]
+    ])
+    # fmt: on
+    G = nx.from_numpy_array(matrix, create_using=nx.DiGraph)
+    d = nx.trophic_levels(G)
+
+    expected_result = [1, 2, 2.5, 3.25]
+    print("Calculated result: ", d)
+    print("Expected Result: ", expected_result)
+
+    for ind in range(4):
+        assert d[ind] == pytest.approx(expected_result[ind], abs=1e-7)
+
+
+def test_trophic_levels_even_more_complex():
+    # fmt: off
+    # Another, bigger matrix
+    matrix = np.array([
+        [0, 0, 0, 0, 0],
+        [0, 1, 0, 1, 0],
+        [1, 0, 0, 0, 0],
+        [0, 1, 0, 0, 0],
+        [0, 0, 0, 1, 0]
+    ])
+    # Generated this linear system using pen and paper:
+    K = np.array([
+        [1, 0, -1, 0, 0],
+        [0, 0.5, 0, -0.5, 0],
+        [0, 0, 1, 0, 0],
+        [0, -0.5, 0, 1, -0.5],
+        [0, 0, 0, 0, 1],
+    ])
+    # fmt: on
+    result_1 = np.ravel(np.linalg.inv(K) @ np.ones(5))
+    G = nx.from_numpy_array(matrix, create_using=nx.DiGraph)
+    result_2 = nx.trophic_levels(G)
+
+    for ind in range(5):
+        assert result_1[ind] == pytest.approx(result_2[ind], abs=1e-7)
+
+
+def test_trophic_levels_singular_matrix():
+    """Should raise an error with graphs with only non-basal nodes"""
+    matrix = np.identity(4)
+    G = nx.from_numpy_array(matrix, create_using=nx.DiGraph)
+    with pytest.raises(nx.NetworkXError) as e:
+        nx.trophic_levels(G)
+    msg = (
+        "Trophic levels are only defined for graphs where every node "
+        + "has a path from a basal node (basal nodes are nodes with no "
+        + "incoming edges)."
+    )
+    assert msg in str(e.value)
+
+
+def test_trophic_levels_singular_with_basal():
+    """Should fail to compute if there are any parts of the graph which are not
+    reachable from any basal node (with in-degree zero).
+    """
+    G = nx.DiGraph()
+    # a has in-degree zero
+    G.add_edge("a", "b")
+
+    # b is one level above a, c and d
+    G.add_edge("c", "b")
+    G.add_edge("d", "b")
+
+    # c and d form a loop, neither are reachable from a
+    G.add_edge("c", "d")
+    G.add_edge("d", "c")
+
+    with pytest.raises(nx.NetworkXError) as e:
+        nx.trophic_levels(G)
+    msg = (
+        "Trophic levels are only defined for graphs where every node "
+        + "has a path from a basal node (basal nodes are nodes with no "
+        + "incoming edges)."
+    )
+    assert msg in str(e.value)
+
+    # if self-loops are allowed, smaller example:
+    G = nx.DiGraph()
+    G.add_edge("a", "b")  # a has in-degree zero
+    G.add_edge("c", "b")  # b is one level above a and c
+    G.add_edge("c", "c")  # c has a self-loop
+    with pytest.raises(nx.NetworkXError) as e:
+        nx.trophic_levels(G)
+    msg = (
+        "Trophic levels are only defined for graphs where every node "
+        + "has a path from a basal node (basal nodes are nodes with no "
+        + "incoming edges)."
+    )
+    assert msg in str(e.value)
+
+
+def test_trophic_differences():
+    matrix_a = np.array([[0, 1], [0, 0]])
+    G = nx.from_numpy_array(matrix_a, create_using=nx.DiGraph)
+    diffs = nx.trophic_differences(G)
+    assert diffs[(0, 1)] == pytest.approx(1, abs=1e-7)
+
+    # fmt: off
+    matrix_b = np.array([
+        [0, 1, 1, 0],
+        [0, 0, 1, 1],
+        [0, 0, 0, 1],
+        [0, 0, 0, 0]
+    ])
+    # fmt: on
+    G = nx.from_numpy_array(matrix_b, create_using=nx.DiGraph)
+    diffs = nx.trophic_differences(G)
+
+    assert diffs[(0, 1)] == pytest.approx(1, abs=1e-7)
+    assert diffs[(0, 2)] == pytest.approx(1.5, abs=1e-7)
+    assert diffs[(1, 2)] == pytest.approx(0.5, abs=1e-7)
+    assert diffs[(1, 3)] == pytest.approx(1.25, abs=1e-7)
+    assert diffs[(2, 3)] == pytest.approx(0.75, abs=1e-7)
+
+
+def test_trophic_incoherence_parameter_no_cannibalism():
+    matrix_a = np.array([[0, 1], [0, 0]])
+    G = nx.from_numpy_array(matrix_a, create_using=nx.DiGraph)
+    q = nx.trophic_incoherence_parameter(G, cannibalism=False)
+    assert q == pytest.approx(0, abs=1e-7)
+
+    # fmt: off
+    matrix_b = np.array([
+        [0, 1, 1, 0],
+        [0, 0, 1, 1],
+        [0, 0, 0, 1],
+        [0, 0, 0, 0]
+    ])
+    # fmt: on
+    G = nx.from_numpy_array(matrix_b, create_using=nx.DiGraph)
+    q = nx.trophic_incoherence_parameter(G, cannibalism=False)
+    assert q == pytest.approx(np.std([1, 1.5, 0.5, 0.75, 1.25]), abs=1e-7)
+
+    # fmt: off
+    matrix_c = np.array([
+        [0, 1, 1, 0],
+        [0, 1, 1, 1],
+        [0, 0, 0, 1],
+        [0, 0, 0, 1]
+    ])
+    # fmt: on
+    G = nx.from_numpy_array(matrix_c, create_using=nx.DiGraph)
+    q = nx.trophic_incoherence_parameter(G, cannibalism=False)
+    # Ignore the -link
+    assert q == pytest.approx(np.std([1, 1.5, 0.5, 0.75, 1.25]), abs=1e-7)
+
+    # no self-loops case
+    # fmt: off
+    matrix_d = np.array([
+        [0, 1, 1, 0],
+        [0, 0, 1, 1],
+        [0, 0, 0, 1],
+        [0, 0, 0, 0]
+    ])
+    # fmt: on
+    G = nx.from_numpy_array(matrix_d, create_using=nx.DiGraph)
+    q = nx.trophic_incoherence_parameter(G, cannibalism=False)
+    # Ignore the -link
+    assert q == pytest.approx(np.std([1, 1.5, 0.5, 0.75, 1.25]), abs=1e-7)
+
+
+def test_trophic_incoherence_parameter_cannibalism():
+    matrix_a = np.array([[0, 1], [0, 0]])
+    G = nx.from_numpy_array(matrix_a, create_using=nx.DiGraph)
+    q = nx.trophic_incoherence_parameter(G, cannibalism=True)
+    assert q == pytest.approx(0, abs=1e-7)
+
+    # fmt: off
+    matrix_b = np.array([
+        [0, 0, 0, 0, 0],
+        [0, 1, 0, 1, 0],
+        [1, 0, 0, 0, 0],
+        [0, 1, 0, 0, 0],
+        [0, 0, 0, 1, 0]
+    ])
+    # fmt: on
+    G = nx.from_numpy_array(matrix_b, create_using=nx.DiGraph)
+    q = nx.trophic_incoherence_parameter(G, cannibalism=True)
+    assert q == pytest.approx(2, abs=1e-7)
+
+    # fmt: off
+    matrix_c = np.array([
+        [0, 1, 1, 0],
+        [0, 0, 1, 1],
+        [0, 0, 0, 1],
+        [0, 0, 0, 0]
+    ])
+    # fmt: on
+    G = nx.from_numpy_array(matrix_c, create_using=nx.DiGraph)
+    q = nx.trophic_incoherence_parameter(G, cannibalism=True)
+    # Ignore the -link
+    assert q == pytest.approx(np.std([1, 1.5, 0.5, 0.75, 1.25]), abs=1e-7)

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/connectivity/tests/test_stoer_wagner.py

@@ -0,0 +1,102 @@
+from itertools import chain
+
+import pytest
+
+import networkx as nx
+
+
+def _check_partition(G, cut_value, partition, weight):
+    assert isinstance(partition, tuple)
+    assert len(partition) == 2
+    assert isinstance(partition[0], list)
+    assert isinstance(partition[1], list)
+    assert len(partition[0]) > 0
+    assert len(partition[1]) > 0
+    assert sum(map(len, partition)) == len(G)
+    assert set(chain.from_iterable(partition)) == set(G)
+    partition = tuple(map(set, partition))
+    w = 0
+    for u, v, e in G.edges(data=True):
+        if (u in partition[0]) == (v in partition[1]):
+            w += e.get(weight, 1)
+    assert w == cut_value
+
+
+def _test_stoer_wagner(G, answer, weight="weight"):
+    cut_value, partition = nx.stoer_wagner(G, weight, heap=nx.utils.PairingHeap)
+    assert cut_value == answer
+    _check_partition(G, cut_value, partition, weight)
+    cut_value, partition = nx.stoer_wagner(G, weight, heap=nx.utils.BinaryHeap)
+    assert cut_value == answer
+    _check_partition(G, cut_value, partition, weight)
+
+
+def test_graph1():
+    G = nx.Graph()
+    G.add_edge("x", "a", weight=3)
+    G.add_edge("x", "b", weight=1)
+    G.add_edge("a", "c", weight=3)
+    G.add_edge("b", "c", weight=5)
+    G.add_edge("b", "d", weight=4)
+    G.add_edge("d", "e", weight=2)
+    G.add_edge("c", "y", weight=2)
+    G.add_edge("e", "y", weight=3)
+    _test_stoer_wagner(G, 4)
+
+
+def test_graph2():
+    G = nx.Graph()
+    G.add_edge("x", "a")
+    G.add_edge("x", "b")
+    G.add_edge("a", "c")
+    G.add_edge("b", "c")
+    G.add_edge("b", "d")
+    G.add_edge("d", "e")
+    G.add_edge("c", "y")
+    G.add_edge("e", "y")
+    _test_stoer_wagner(G, 2)
+
+
+def test_graph3():
+    # Source:
+    # Stoer, M. and Wagner, F. (1997). "A simple min-cut algorithm". Journal of
+    # the ACM 44 (4), 585-591.
+    G = nx.Graph()
+    G.add_edge(1, 2, weight=2)
+    G.add_edge(1, 5, weight=3)
+    G.add_edge(2, 3, weight=3)
+    G.add_edge(2, 5, weight=2)
+    G.add_edge(2, 6, weight=2)
+    G.add_edge(3, 4, weight=4)
+    G.add_edge(3, 7, weight=2)
+    G.add_edge(4, 7, weight=2)
+    G.add_edge(4, 8, weight=2)
+    G.add_edge(5, 6, weight=3)
+    G.add_edge(6, 7, weight=1)
+    G.add_edge(7, 8, weight=3)
+    _test_stoer_wagner(G, 4)
+
+
+def test_weight_name():
+    G = nx.Graph()
+    G.add_edge(1, 2, weight=1, cost=8)
+    G.add_edge(1, 3, cost=2)
+    G.add_edge(2, 3, cost=4)
+    _test_stoer_wagner(G, 6, weight="cost")
+
+
+def test_exceptions():
+    G = nx.Graph()
+    pytest.raises(nx.NetworkXError, nx.stoer_wagner, G)
+    G.add_node(1)
+    pytest.raises(nx.NetworkXError, nx.stoer_wagner, G)
+    G.add_node(2)
+    pytest.raises(nx.NetworkXError, nx.stoer_wagner, G)
+    G.add_edge(1, 2, weight=-2)
+    pytest.raises(nx.NetworkXError, nx.stoer_wagner, G)
+    G = nx.DiGraph()
+    pytest.raises(nx.NetworkXNotImplemented, nx.stoer_wagner, G)
+    G = nx.MultiGraph()
+    pytest.raises(nx.NetworkXNotImplemented, nx.stoer_wagner, G)
+    G = nx.MultiDiGraph()
+    pytest.raises(nx.NetworkXNotImplemented, nx.stoer_wagner, G)

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/core.py

@@ -0,0 +1,545 @@
+"""
+Find the k-cores of a graph.
+
+The k-core is found by recursively pruning nodes with degrees less than k.
+
+See the following references for details:
+
+An O(m) Algorithm for Cores Decomposition of Networks
+Vladimir Batagelj and Matjaz Zaversnik, 2003.
+https://arxiv.org/abs/cs.DS/0310049
+
+Generalized Cores
+Vladimir Batagelj and Matjaz Zaversnik, 2002.
+https://arxiv.org/pdf/cs/0202039
+
+For directed graphs a more general notion is that of D-cores which
+looks at (k, l) restrictions on (in, out) degree. The (k, k) D-core
+is the k-core.
+
+D-cores: Measuring Collaboration of Directed Graphs Based on Degeneracy
+Christos Giatsidis, Dimitrios M. Thilikos, Michalis Vazirgiannis, ICDM 2011.
+http://www.graphdegeneracy.org/dcores_ICDM_2011.pdf
+
+Multi-scale structure and topological anomaly detection via a new network \
+statistic: The onion decomposition
+L. Hébert-Dufresne, J. A. Grochow, and A. Allard
+Scientific Reports 6, 31708 (2016)
+http://doi.org/10.1038/srep31708
+
+"""
+import networkx as nx
+from networkx.exception import NetworkXError
+from networkx.utils import not_implemented_for
+
+__all__ = [
+    "core_number",
+    "k_core",
+    "k_shell",
+    "k_crust",
+    "k_corona",
+    "k_truss",
+    "onion_layers",
+]
+
+
+@not_implemented_for("multigraph")
+@nx._dispatch
+def core_number(G):
+    """Returns the core number for each vertex.
+
+    A k-core is a maximal subgraph that contains nodes of degree k or more.
+
+    The core number of a node is the largest value k of a k-core containing
+    that node.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+       A graph or directed graph
+
+    Returns
+    -------
+    core_number : dictionary
+       A dictionary keyed by node to the core number.
+
+    Raises
+    ------
+    NetworkXError
+        The k-core is not implemented for graphs with self loops
+        or parallel edges.
+
+    Notes
+    -----
+    Not implemented for graphs with parallel edges or self loops.
+
+    For directed graphs the node degree is defined to be the
+    in-degree + out-degree.
+
+    References
+    ----------
+    .. [1] An O(m) Algorithm for Cores Decomposition of Networks
+       Vladimir Batagelj and Matjaz Zaversnik, 2003.
+       https://arxiv.org/abs/cs.DS/0310049
+    """
+    if nx.number_of_selfloops(G) > 0:
+        msg = (
+            "Input graph has self loops which is not permitted; "
+            "Consider using G.remove_edges_from(nx.selfloop_edges(G))."
+        )
+        raise NetworkXError(msg)
+    degrees = dict(G.degree())
+    # Sort nodes by degree.
+    nodes = sorted(degrees, key=degrees.get)
+    bin_boundaries = [0]
+    curr_degree = 0
+    for i, v in enumerate(nodes):
+        if degrees[v] > curr_degree:
+            bin_boundaries.extend([i] * (degrees[v] - curr_degree))
+            curr_degree = degrees[v]
+    node_pos = {v: pos for pos, v in enumerate(nodes)}
+    # The initial guess for the core number of a node is its degree.
+    core = degrees
+    nbrs = {v: list(nx.all_neighbors(G, v)) for v in G}
+    for v in nodes:
+        for u in nbrs[v]:
+            if core[u] > core[v]:
+                nbrs[u].remove(v)
+                pos = node_pos[u]
+                bin_start = bin_boundaries[core[u]]
+                node_pos[u] = bin_start
+                node_pos[nodes[bin_start]] = pos
+                nodes[bin_start], nodes[pos] = nodes[pos], nodes[bin_start]
+                bin_boundaries[core[u]] += 1
+                core[u] -= 1
+    return core
+
+
+def _core_subgraph(G, k_filter, k=None, core=None):
+    """Returns the subgraph induced by nodes passing filter `k_filter`.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+       The graph or directed graph to process
+    k_filter : filter function
+       This function filters the nodes chosen. It takes three inputs:
+       A node of G, the filter's cutoff, and the core dict of the graph.
+       The function should return a Boolean value.
+    k : int, optional
+      The order of the core. If not specified use the max core number.
+      This value is used as the cutoff for the filter.
+    core : dict, optional
+      Precomputed core numbers keyed by node for the graph `G`.
+      If not specified, the core numbers will be computed from `G`.
+
+    """
+    if core is None:
+        core = core_number(G)
+    if k is None:
+        k = max(core.values())
+    nodes = (v for v in core if k_filter(v, k, core))
+    return G.subgraph(nodes).copy()
+
+
+@nx._dispatch(preserve_all_attrs=True)
+def k_core(G, k=None, core_number=None):
+    """Returns the k-core of G.
+
+    A k-core is a maximal subgraph that contains nodes of degree k or more.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+      A graph or directed graph
+    k : int, optional
+      The order of the core.  If not specified return the main core.
+    core_number : dictionary, optional
+      Precomputed core numbers for the graph G.
+
+    Returns
+    -------
+    G : NetworkX graph
+      The k-core subgraph
+
+    Raises
+    ------
+    NetworkXError
+      The k-core is not defined for graphs with self loops or parallel edges.
+
+    Notes
+    -----
+    The main core is the core with the largest degree.
+
+    Not implemented for graphs with parallel edges or self loops.
+
+    For directed graphs the node degree is defined to be the
+    in-degree + out-degree.
+
+    Graph, node, and edge attributes are copied to the subgraph.
+
+    See Also
+    --------
+    core_number
+
+    References
+    ----------
+    .. [1] An O(m) Algorithm for Cores Decomposition of Networks
+       Vladimir Batagelj and Matjaz Zaversnik,  2003.
+       https://arxiv.org/abs/cs.DS/0310049
+    """
+
+    def k_filter(v, k, c):
+        return c[v] >= k
+
+    return _core_subgraph(G, k_filter, k, core_number)
+
+
+@nx._dispatch(preserve_all_attrs=True)
+def k_shell(G, k=None, core_number=None):
+    """Returns the k-shell of G.
+
+    The k-shell is the subgraph induced by nodes with core number k.
+    That is, nodes in the k-core that are not in the (k+1)-core.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+      A graph or directed graph.
+    k : int, optional
+      The order of the shell. If not specified return the outer shell.
+    core_number : dictionary, optional
+      Precomputed core numbers for the graph G.
+
+
+    Returns
+    -------
+    G : NetworkX graph
+       The k-shell subgraph
+
+    Raises
+    ------
+    NetworkXError
+        The k-shell is not implemented for graphs with self loops
+        or parallel edges.
+
+    Notes
+    -----
+    This is similar to k_corona but in that case only neighbors in the
+    k-core are considered.
+
+    Not implemented for graphs with parallel edges or self loops.
+
+    For directed graphs the node degree is defined to be the
+    in-degree + out-degree.
+
+    Graph, node, and edge attributes are copied to the subgraph.
+
+    See Also
+    --------
+    core_number
+    k_corona
+
+
+    References
+    ----------
+    .. [1] A model of Internet topology using k-shell decomposition
+       Shai Carmi, Shlomo Havlin, Scott Kirkpatrick, Yuval Shavitt,
+       and Eran Shir, PNAS  July 3, 2007   vol. 104  no. 27  11150-11154
+       http://www.pnas.org/content/104/27/11150.full
+    """
+
+    def k_filter(v, k, c):
+        return c[v] == k
+
+    return _core_subgraph(G, k_filter, k, core_number)
+
+
+@nx._dispatch(preserve_all_attrs=True)
+def k_crust(G, k=None, core_number=None):
+    """Returns the k-crust of G.
+
+    The k-crust is the graph G with the edges of the k-core removed
+    and isolated nodes found after the removal of edges are also removed.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+       A graph or directed graph.
+    k : int, optional
+      The order of the shell.  If not specified return the main crust.
+    core_number : dictionary, optional
+      Precomputed core numbers for the graph G.
+
+    Returns
+    -------
+    G : NetworkX graph
+       The k-crust subgraph
+
+    Raises
+    ------
+    NetworkXError
+        The k-crust is not implemented for graphs with self loops
+        or parallel edges.
+
+    Notes
+    -----
+    This definition of k-crust is different than the definition in [1]_.
+    The k-crust in [1]_ is equivalent to the k+1 crust of this algorithm.
+
+    Not implemented for graphs with parallel edges or self loops.
+
+    For directed graphs the node degree is defined to be the
+    in-degree + out-degree.
+
+    Graph, node, and edge attributes are copied to the subgraph.
+
+    See Also
+    --------
+    core_number
+
+    References
+    ----------
+    .. [1] A model of Internet topology using k-shell decomposition
+       Shai Carmi, Shlomo Havlin, Scott Kirkpatrick, Yuval Shavitt,
+       and Eran Shir, PNAS  July 3, 2007   vol. 104  no. 27  11150-11154
+       http://www.pnas.org/content/104/27/11150.full
+    """
+    # Default for k is one less than in _core_subgraph, so just inline.
+    #    Filter is c[v] <= k
+    if core_number is None:
+        core_number = nx.core_number(G)
+    if k is None:
+        k = max(core_number.values()) - 1
+    nodes = (v for v in core_number if core_number[v] <= k)
+    return G.subgraph(nodes).copy()
+
+
+@nx._dispatch(preserve_all_attrs=True)
+def k_corona(G, k, core_number=None):
+    """Returns the k-corona of G.
+
+    The k-corona is the subgraph of nodes in the k-core which have
+    exactly k neighbours in the k-core.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+       A graph or directed graph
+    k : int
+       The order of the corona.
+    core_number : dictionary, optional
+       Precomputed core numbers for the graph G.
+
+    Returns
+    -------
+    G : NetworkX graph
+       The k-corona subgraph
+
+    Raises
+    ------
+    NetworkXError
+        The k-corona is not defined for graphs with self loops or
+        parallel edges.
+
+    Notes
+    -----
+    Not implemented for graphs with parallel edges or self loops.
+
+    For directed graphs the node degree is defined to be the
+    in-degree + out-degree.
+
+    Graph, node, and edge attributes are copied to the subgraph.
+
+    See Also
+    --------
+    core_number
+
+    References
+    ----------
+    .. [1]  k -core (bootstrap) percolation on complex networks:
+       Critical phenomena and nonlocal effects,
+       A. V. Goltsev, S. N. Dorogovtsev, and J. F. F. Mendes,
+       Phys. Rev. E 73, 056101 (2006)
+       http://link.aps.org/doi/10.1103/PhysRevE.73.056101
+    """
+
+    def func(v, k, c):
+        return c[v] == k and k == sum(1 for w in G[v] if c[w] >= k)
+
+    return _core_subgraph(G, func, k, core_number)
+
+
+@not_implemented_for("directed")
+@not_implemented_for("multigraph")
+@nx._dispatch(preserve_all_attrs=True)
+def k_truss(G, k):
+    """Returns the k-truss of `G`.
+
+    The k-truss is the maximal induced subgraph of `G` which contains at least
+    three vertices where every edge is incident to at least `k-2` triangles.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+      An undirected graph
+    k : int
+      The order of the truss
+
+    Returns
+    -------
+    H : NetworkX graph
+      The k-truss subgraph
+
+    Raises
+    ------
+    NetworkXError
+
+      The k-truss is not defined for graphs with self loops, directed graphs
+      and multigraphs.
+
+    Notes
+    -----
+    A k-clique is a (k-2)-truss and a k-truss is a (k+1)-core.
+
+    Not implemented for digraphs or graphs with parallel edges or self loops.
+
+    Graph, node, and edge attributes are copied to the subgraph.
+
+    K-trusses were originally defined in [2] which states that the k-truss
+    is the maximal induced subgraph where each edge belongs to at least
+    `k-2` triangles. A more recent paper, [1], uses a slightly different
+    definition requiring that each edge belong to at least `k` triangles.
+    This implementation uses the original definition of `k-2` triangles.
+
+    References
+    ----------
+    .. [1] Bounds and Algorithms for k-truss. Paul Burkhardt, Vance Faber,
+       David G. Harris, 2018. https://arxiv.org/abs/1806.05523v2
+    .. [2] Trusses: Cohesive Subgraphs for Social Network Analysis. Jonathan
+       Cohen, 2005.
+    """
+    if nx.number_of_selfloops(G) > 0:
+        msg = (
+            "Input graph has self loops which is not permitted; "
+            "Consider using G.remove_edges_from(nx.selfloop_edges(G))."
+        )
+        raise NetworkXError(msg)
+
+    H = G.copy()
+
+    n_dropped = 1
+    while n_dropped > 0:
+        n_dropped = 0
+        to_drop = []
+        seen = set()
+        for u in H:
+            nbrs_u = set(H[u])
+            seen.add(u)
+            new_nbrs = [v for v in nbrs_u if v not in seen]
+            for v in new_nbrs:
+                if len(nbrs_u & set(H[v])) < (k - 2):
+                    to_drop.append((u, v))
+        H.remove_edges_from(to_drop)
+        n_dropped = len(to_drop)
+        H.remove_nodes_from(list(nx.isolates(H)))
+
+    return H
+
+
+@not_implemented_for("multigraph")
+@not_implemented_for("directed")
+@nx._dispatch
+def onion_layers(G):
+    """Returns the layer of each vertex in an onion decomposition of the graph.
+
+    The onion decomposition refines the k-core decomposition by providing
+    information on the internal organization of each k-shell. It is usually
+    used alongside the `core numbers`.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+        A simple graph without self loops or parallel edges
+
+    Returns
+    -------
+    od_layers : dictionary
+        A dictionary keyed by vertex to the onion layer. The layers are
+        contiguous integers starting at 1.
+
+    Raises
+    ------
+    NetworkXError
+        The onion decomposition is not implemented for graphs with self loops
+        or parallel edges or for directed graphs.
+
+    Notes
+    -----
+    Not implemented for graphs with parallel edges or self loops.
+
+    Not implemented for directed graphs.
+
+    See Also
+    --------
+    core_number
+
+    References
+    ----------
+    .. [1] Multi-scale structure and topological anomaly detection via a new
+       network statistic: The onion decomposition
+       L. Hébert-Dufresne, J. A. Grochow, and A. Allard
+       Scientific Reports 6, 31708 (2016)
+       http://doi.org/10.1038/srep31708
+    .. [2] Percolation and the effective structure of complex networks
+       A. Allard and L. Hébert-Dufresne
+       Physical Review X 9, 011023 (2019)
+       http://doi.org/10.1103/PhysRevX.9.011023
+    """
+    if nx.number_of_selfloops(G) > 0:
+        msg = (
+            "Input graph contains self loops which is not permitted; "
+            "Consider using G.remove_edges_from(nx.selfloop_edges(G))."
+        )
+        raise NetworkXError(msg)
+    # Dictionaries to register the k-core/onion decompositions.
+    od_layers = {}
+    # Adjacency list
+    neighbors = {v: list(nx.all_neighbors(G, v)) for v in G}
+    # Effective degree of nodes.
+    degrees = dict(G.degree())
+    # Performs the onion decomposition.
+    current_core = 1
+    current_layer = 1
+    # Sets vertices of degree 0 to layer 1, if any.
+    isolated_nodes = list(nx.isolates(G))
+    if len(isolated_nodes) > 0:
+        for v in isolated_nodes:
+            od_layers[v] = current_layer
+            degrees.pop(v)
+        current_layer = 2
+    # Finds the layer for the remaining nodes.
+    while len(degrees) > 0:
+        # Sets the order for looking at nodes.
+        nodes = sorted(degrees, key=degrees.get)
+        # Sets properly the current core.
+        min_degree = degrees[nodes[0]]
+        if min_degree > current_core:
+            current_core = min_degree
+        # Identifies vertices in the current layer.
+        this_layer = []
+        for n in nodes:
+            if degrees[n] > current_core:
+                break
+            this_layer.append(n)
+        # Identifies the core/layer of the vertices in the current layer.
+        for v in this_layer:
+            od_layers[v] = current_layer
+            for n in neighbors[v]:
+                neighbors[n].remove(v)
+                degrees[n] = degrees[n] - 1
+            degrees.pop(v)
+        # Updates the layer count.
+        current_layer = current_layer + 1
+    # Returns the dictionaries containing the onion layer of each vertices.
+    return od_layers

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/d_separation.py

@@ -0,0 +1,457 @@
+"""
+Algorithm for testing d-separation in DAGs.
+
+*d-separation* is a test for conditional independence in probability
+distributions that can be factorized using DAGs.  It is a purely
+graphical test that uses the underlying graph and makes no reference
+to the actual distribution parameters.  See [1]_ for a formal
+definition.
+
+The implementation is based on the conceptually simple linear time
+algorithm presented in [2]_.  Refer to [3]_, [4]_ for a couple of
+alternative algorithms.
+
+Here, we provide a brief overview of d-separation and related concepts that
+are relevant for understanding it:
+
+Blocking paths
+--------------
+
+Before we overview, we introduce the following terminology to describe paths:
+
+- "open" path: A path between two nodes that can be traversed
+- "blocked" path: A path between two nodes that cannot be traversed
+
+A **collider** is a triplet of nodes along a path that is like the following:
+``... u -> c <- v ...``), where 'c' is a common successor of ``u`` and ``v``. A path
+through a collider is considered "blocked". When
+a node that is a collider, or a descendant of a collider is included in
+the d-separating set, then the path through that collider node is "open". If the
+path through the collider node is open, then we will call this node an open collider.
+
+The d-separation set blocks the paths between ``u`` and ``v``. If you include colliders,
+or their descendant nodes in the d-separation set, then those colliders will open up,
+enabling a path to be traversed if it is not blocked some other way.
+
+Illustration of D-separation with examples
+------------------------------------------
+
+For a pair of two nodes, ``u`` and ``v``, all paths are considered open if
+there is a path between ``u`` and ``v`` that is not blocked. That means, there is an open
+path between ``u`` and ``v`` that does not encounter a collider, or a variable in the
+d-separating set.
+
+For example, if the d-separating set is the empty set, then the following paths are
+unblocked between ``u`` and ``v``:
+
+- u <- z -> v
+- u -> w -> ... -> z -> v
+
+If for example, 'z' is in the d-separating set, then 'z' blocks those paths
+between ``u`` and ``v``.
+
+Colliders block a path by default if they and their descendants are not included
+in the d-separating set. An example of a path that is blocked when the d-separating
+set is empty is:
+
+- u -> w -> ... -> z <- v
+
+because 'z' is a collider in this path and 'z' is not in the d-separating set. However,
+if 'z' or a descendant of 'z' is included in the d-separating set, then the path through
+the collider at 'z' (... -> z <- ...) is now "open". 
+
+D-separation is concerned with blocking all paths between u and v. Therefore, a
+d-separating set between ``u`` and ``v`` is one where all paths are blocked.
+
+D-separation and its applications in probability
+------------------------------------------------
+
+D-separation is commonly used in probabilistic graphical models. D-separation
+connects the idea of probabilistic "dependence" with separation in a graph. If
+one assumes the causal Markov condition [5]_, then d-separation implies conditional
+independence in probability distributions.
+
+Examples
+--------
+
+>>>
+>>> # HMM graph with five states and observation nodes
+... g = nx.DiGraph()
+>>> g.add_edges_from(
+...     [
+...         ("S1", "S2"),
+...         ("S2", "S3"),
+...         ("S3", "S4"),
+...         ("S4", "S5"),
+...         ("S1", "O1"),
+...         ("S2", "O2"),
+...         ("S3", "O3"),
+...         ("S4", "O4"),
+...         ("S5", "O5"),
+...     ]
+... )
+>>>
+>>> # states/obs before 'S3' are d-separated from states/obs after 'S3'
+... nx.d_separated(g, {"S1", "S2", "O1", "O2"}, {"S4", "S5", "O4", "O5"}, {"S3"})
+True
+
+
+References
+----------
+
+.. [1] Pearl, J.  (2009).  Causality.  Cambridge: Cambridge University Press.
+
+.. [2] Darwiche, A.  (2009).  Modeling and reasoning with Bayesian networks. 
+   Cambridge: Cambridge University Press.
+
+.. [3] Shachter, R.  D.  (1998).
+   Bayes-ball: rational pastime (for determining irrelevance and requisite
+   information in belief networks and influence diagrams).
+   In , Proceedings of the Fourteenth Conference on Uncertainty in Artificial
+   Intelligence (pp.  480–487).
+   San Francisco, CA, USA: Morgan Kaufmann Publishers Inc.
+
+.. [4] Koller, D., & Friedman, N. (2009).
+   Probabilistic graphical models: principles and techniques. The MIT Press.
+
+.. [5] https://en.wikipedia.org/wiki/Causal_Markov_condition
+
+"""
+
+from collections import deque
+
+import networkx as nx
+from networkx.utils import UnionFind, not_implemented_for
+
+__all__ = ["d_separated", "minimal_d_separator", "is_minimal_d_separator"]
+
+
+@not_implemented_for("undirected")
+@nx._dispatch
+def d_separated(G, x, y, z):
+    """
+    Return whether node sets ``x`` and ``y`` are d-separated by ``z``.
+
+    Parameters
+    ----------
+    G : graph
+        A NetworkX DAG.
+
+    x : set
+        First set of nodes in ``G``.
+
+    y : set
+        Second set of nodes in ``G``.
+
+    z : set
+        Set of conditioning nodes in ``G``. Can be empty set.
+
+    Returns
+    -------
+    b : bool
+        A boolean that is true if ``x`` is d-separated from ``y`` given ``z`` in ``G``.
+
+    Raises
+    ------
+    NetworkXError
+        The *d-separation* test is commonly used with directed
+        graphical models which are acyclic.  Accordingly, the algorithm
+        raises a :exc:`NetworkXError` if the input graph is not a DAG.
+
+    NodeNotFound
+        If any of the input nodes are not found in the graph,
+        a :exc:`NodeNotFound` exception is raised.
+
+    Notes
+    -----
+    A d-separating set in a DAG is a set of nodes that
+    blocks all paths between the two sets. Nodes in `z`
+    block a path if they are part of the path and are not a collider,
+    or a descendant of a collider. A collider structure along a path
+    is ``... -> c <- ...`` where ``c`` is the collider node.
+
+    https://en.wikipedia.org/wiki/Bayesian_network#d-separation
+    """
+
+    if not nx.is_directed_acyclic_graph(G):
+        raise nx.NetworkXError("graph should be directed acyclic")
+
+    union_xyz = x.union(y).union(z)
+
+    if any(n not in G.nodes for n in union_xyz):
+        raise nx.NodeNotFound("one or more specified nodes not found in the graph")
+
+    G_copy = G.copy()
+
+    # transform the graph by removing leaves that are not in x | y | z
+    # until no more leaves can be removed.
+    leaves = deque([n for n in G_copy.nodes if G_copy.out_degree[n] == 0])
+    while len(leaves) > 0:
+        leaf = leaves.popleft()
+        if leaf not in union_xyz:
+            for p in G_copy.predecessors(leaf):
+                if G_copy.out_degree[p] == 1:
+                    leaves.append(p)
+            G_copy.remove_node(leaf)
+
+    # transform the graph by removing outgoing edges from the
+    # conditioning set.
+    edges_to_remove = list(G_copy.out_edges(z))
+    G_copy.remove_edges_from(edges_to_remove)
+
+    # use disjoint-set data structure to check if any node in `x`
+    # occurs in the same weakly connected component as a node in `y`.
+    disjoint_set = UnionFind(G_copy.nodes())
+    for component in nx.weakly_connected_components(G_copy):
+        disjoint_set.union(*component)
+    disjoint_set.union(*x)
+    disjoint_set.union(*y)
+
+    if x and y and disjoint_set[next(iter(x))] == disjoint_set[next(iter(y))]:
+        return False
+    else:
+        return True
+
+
+@not_implemented_for("undirected")
+@nx._dispatch
+def minimal_d_separator(G, u, v):
+    """Compute a minimal d-separating set between 'u' and 'v'.
+
+    A d-separating set in a DAG is a set of nodes that blocks all paths
+    between the two nodes, 'u' and 'v'. This function
+    constructs a d-separating set that is "minimal", meaning it is the smallest
+    d-separating set for 'u' and 'v'. This is not necessarily
+    unique. For more details, see Notes.
+
+    Parameters
+    ----------
+    G : graph
+        A networkx DAG.
+    u : node
+        A node in the graph, G.
+    v : node
+        A node in the graph, G.
+
+    Raises
+    ------
+    NetworkXError
+        Raises a :exc:`NetworkXError` if the input graph is not a DAG.
+
+    NodeNotFound
+        If any of the input nodes are not found in the graph,
+        a :exc:`NodeNotFound` exception is raised.
+
+    References
+    ----------
+    .. [1] Tian, J., & Paz, A. (1998). Finding Minimal D-separators.
+
+    Notes
+    -----
+    This function only finds ``a`` minimal d-separator. It does not guarantee
+    uniqueness, since in a DAG there may be more than one minimal d-separator
+    between two nodes. Moreover, this only checks for minimal separators
+    between two nodes, not two sets. Finding minimal d-separators between
+    two sets of nodes is not supported.
+
+    Uses the algorithm presented in [1]_. The complexity of the algorithm
+    is :math:`O(|E_{An}^m|)`, where :math:`|E_{An}^m|` stands for the
+    number of edges in the moralized graph of the sub-graph consisting
+    of only the ancestors of 'u' and 'v'. For full details, see [1]_.
+
+    The algorithm works by constructing the moral graph consisting of just
+    the ancestors of `u` and `v`. Then it constructs a candidate for
+    a separating set  ``Z'`` from the predecessors of `u` and `v`.
+    Then BFS is run starting from `u` and marking nodes
+    found from ``Z'`` and calling those nodes ``Z''``.
+    Then BFS is run again starting from `v` and marking nodes if they are
+    present in ``Z''``. Those marked nodes are the returned minimal
+    d-separating set.
+
+    https://en.wikipedia.org/wiki/Bayesian_network#d-separation
+    """
+    if not nx.is_directed_acyclic_graph(G):
+        raise nx.NetworkXError("graph should be directed acyclic")
+
+    union_uv = {u, v}
+
+    if any(n not in G.nodes for n in union_uv):
+        raise nx.NodeNotFound("one or more specified nodes not found in the graph")
+
+    # first construct the set of ancestors of X and Y
+    x_anc = nx.ancestors(G, u)
+    y_anc = nx.ancestors(G, v)
+    D_anc_xy = x_anc.union(y_anc)
+    D_anc_xy.update((u, v))
+
+    # second, construct the moralization of the subgraph of Anc(X,Y)
+    moral_G = nx.moral_graph(G.subgraph(D_anc_xy))
+
+    # find a separating set Z' in moral_G
+    Z_prime = set(G.predecessors(u)).union(set(G.predecessors(v)))
+
+    # perform BFS on the graph from 'x' to mark
+    Z_dprime = _bfs_with_marks(moral_G, u, Z_prime)
+    Z = _bfs_with_marks(moral_G, v, Z_dprime)
+    return Z
+
+
+@not_implemented_for("undirected")
+@nx._dispatch
+def is_minimal_d_separator(G, u, v, z):
+    """Determine if a d-separating set is minimal.
+
+    A d-separating set, `z`, in a DAG is a set of nodes that blocks
+    all paths between the two nodes, `u` and `v`. This function
+    verifies that a set is "minimal", meaning there is no smaller
+    d-separating set between the two nodes.
+
+    Note: This function checks whether `z` is a d-separator AND is minimal.
+    One can use the function `d_separated` to only check if `z` is a d-separator.
+    See examples below.
+
+    Parameters
+    ----------
+    G : nx.DiGraph
+        The graph.
+    u : node
+        A node in the graph.
+    v : node
+        A node in the graph.
+    z : Set of nodes
+        The set of nodes to check if it is a minimal d-separating set.
+        The function :func:`d_separated` is called inside this function
+        to verify that `z` is in fact a d-separator.
+
+    Returns
+    -------
+    bool
+        Whether or not the set `z` is a d-separator and is also minimal.
+
+    Examples
+    --------
+    >>> G = nx.path_graph([0, 1, 2, 3], create_using=nx.DiGraph)
+    >>> G.add_node(4)
+    >>> nx.is_minimal_d_separator(G, 0, 2, {1})
+    True
+    >>> # since {1} is the minimal d-separator, {1, 3, 4} is not minimal
+    >>> nx.is_minimal_d_separator(G, 0, 2, {1, 3, 4})
+    False
+    >>> # alternatively, if we only want to check that {1, 3, 4} is a d-separator
+    >>> nx.d_separated(G, {0}, {4}, {1, 3, 4})
+    True
+
+    Raises
+    ------
+    NetworkXError
+        Raises a :exc:`NetworkXError` if the input graph is not a DAG.
+
+    NodeNotFound
+        If any of the input nodes are not found in the graph,
+        a :exc:`NodeNotFound` exception is raised.
+
+    References
+    ----------
+    .. [1] Tian, J., & Paz, A. (1998). Finding Minimal D-separators.
+
+    Notes
+    -----
+    This function only works on verifying a d-separating set is minimal
+    between two nodes. To verify that a d-separating set is minimal between
+    two sets of nodes is not supported.
+
+    Uses algorithm 2 presented in [1]_. The complexity of the algorithm
+    is :math:`O(|E_{An}^m|)`, where :math:`|E_{An}^m|` stands for the
+    number of edges in the moralized graph of the sub-graph consisting
+    of only the ancestors of ``u`` and ``v``.
+
+    The algorithm works by constructing the moral graph consisting of just
+    the ancestors of `u` and `v`. First, it performs BFS on the moral graph
+    starting from `u` and marking any nodes it encounters that are part of
+    the separating set, `z`. If a node is marked, then it does not continue
+    along that path. In the second stage, BFS with markings is repeated on the
+    moral graph starting from `v`. If at any stage, any node in `z` is
+    not marked, then `z` is considered not minimal. If the end of the algorithm
+    is reached, then `z` is minimal.
+
+    For full details, see [1]_.
+
+    https://en.wikipedia.org/wiki/Bayesian_network#d-separation
+    """
+    if not nx.d_separated(G, {u}, {v}, z):
+        return False
+
+    x_anc = nx.ancestors(G, u)
+    y_anc = nx.ancestors(G, v)
+    xy_anc = x_anc.union(y_anc)
+
+    # if Z contains any node which is not in ancestors of X or Y
+    # then it is definitely not minimal
+    if any(node not in xy_anc for node in z):
+        return False
+
+    D_anc_xy = x_anc.union(y_anc)
+    D_anc_xy.update((u, v))
+
+    # second, construct the moralization of the subgraph
+    moral_G = nx.moral_graph(G.subgraph(D_anc_xy))
+
+    # start BFS from X
+    marks = _bfs_with_marks(moral_G, u, z)
+
+    # if not all the Z is marked, then the set is not minimal
+    if any(node not in marks for node in z):
+        return False
+
+    # similarly, start BFS from Y and check the marks
+    marks = _bfs_with_marks(moral_G, v, z)
+    # if not all the Z is marked, then the set is not minimal
+    if any(node not in marks for node in z):
+        return False
+
+    return True
+
+
+@not_implemented_for("directed")
+def _bfs_with_marks(G, start_node, check_set):
+    """Breadth-first-search with markings.
+
+    Performs BFS starting from ``start_node`` and whenever a node
+    inside ``check_set`` is met, it is "marked". Once a node is marked,
+    BFS does not continue along that path. The resulting marked nodes
+    are returned.
+
+    Parameters
+    ----------
+    G : nx.Graph
+        An undirected graph.
+    start_node : node
+        The start of the BFS.
+    check_set : set
+        The set of nodes to check against.
+
+    Returns
+    -------
+    marked : set
+        A set of nodes that were marked.
+    """
+    visited = {}
+    marked = set()
+    queue = []
+
+    visited[start_node] = None
+    queue.append(start_node)
+    while queue:
+        m = queue.pop(0)
+
+        for nbr in G.neighbors(m):
+            if nbr not in visited:
+                # memoize where we visited so far
+                visited[nbr] = None
+
+                # mark the node in Z' and do not continue along that path
+                if nbr in check_set:
+                    marked.add(nbr)
+                else:
+                    queue.append(nbr)
+    return marked

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/dominating.py

@@ -0,0 +1,94 @@
+"""Functions for computing dominating sets in a graph."""
+from itertools import chain
+
+import networkx as nx
+from networkx.utils import arbitrary_element
+
+__all__ = ["dominating_set", "is_dominating_set"]
+
+
+@nx._dispatch
+def dominating_set(G, start_with=None):
+    r"""Finds a dominating set for the graph G.
+
+    A *dominating set* for a graph with node set *V* is a subset *D* of
+    *V* such that every node not in *D* is adjacent to at least one
+    member of *D* [1]_.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    start_with : node (default=None)
+        Node to use as a starting point for the algorithm.
+
+    Returns
+    -------
+    D : set
+        A dominating set for G.
+
+    Notes
+    -----
+    This function is an implementation of algorithm 7 in [2]_ which
+    finds some dominating set, not necessarily the smallest one.
+
+    See also
+    --------
+    is_dominating_set
+
+    References
+    ----------
+    .. [1] https://en.wikipedia.org/wiki/Dominating_set
+
+    .. [2] Abdol-Hossein Esfahanian. Connectivity Algorithms.
+        http://www.cse.msu.edu/~cse835/Papers/Graph_connectivity_revised.pdf
+
+    """
+    all_nodes = set(G)
+    if start_with is None:
+        start_with = arbitrary_element(all_nodes)
+    if start_with not in G:
+        raise nx.NetworkXError(f"node {start_with} is not in G")
+    dominating_set = {start_with}
+    dominated_nodes = set(G[start_with])
+    remaining_nodes = all_nodes - dominated_nodes - dominating_set
+    while remaining_nodes:
+        # Choose an arbitrary node and determine its undominated neighbors.
+        v = remaining_nodes.pop()
+        undominated_neighbors = set(G[v]) - dominating_set
+        # Add the node to the dominating set and the neighbors to the
+        # dominated set. Finally, remove all of those nodes from the set
+        # of remaining nodes.
+        dominating_set.add(v)
+        dominated_nodes |= undominated_neighbors
+        remaining_nodes -= undominated_neighbors
+    return dominating_set
+
+
+@nx._dispatch
+def is_dominating_set(G, nbunch):
+    """Checks if `nbunch` is a dominating set for `G`.
+
+    A *dominating set* for a graph with node set *V* is a subset *D* of
+    *V* such that every node not in *D* is adjacent to at least one
+    member of *D* [1]_.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    nbunch : iterable
+        An iterable of nodes in the graph `G`.
+
+    See also
+    --------
+    dominating_set
+
+    References
+    ----------
+    .. [1] https://en.wikipedia.org/wiki/Dominating_set
+
+    """
+    testset = {n for n in nbunch if n in G}
+    nbrs = set(chain.from_iterable(G[n] for n in testset))
+    return len(set(G) - testset - nbrs) == 0

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/efficiency_measures.py

@@ -0,0 +1,168 @@
+"""Provides functions for computing the efficiency of nodes and graphs."""
+
+import networkx as nx
+from networkx.exception import NetworkXNoPath
+
+from ..utils import not_implemented_for
+
+__all__ = ["efficiency", "local_efficiency", "global_efficiency"]
+
+
+@not_implemented_for("directed")
+@nx._dispatch
+def efficiency(G, u, v):
+    """Returns the efficiency of a pair of nodes in a graph.
+
+    The *efficiency* of a pair of nodes is the multiplicative inverse of the
+    shortest path distance between the nodes [1]_. Returns 0 if no path
+    between nodes.
+
+    Parameters
+    ----------
+    G : :class:`networkx.Graph`
+        An undirected graph for which to compute the average local efficiency.
+    u, v : node
+        Nodes in the graph ``G``.
+
+    Returns
+    -------
+    float
+        Multiplicative inverse of the shortest path distance between the nodes.
+
+    Examples
+    --------
+    >>> G = nx.Graph([(0, 1), (0, 2), (0, 3), (1, 2), (1, 3)])
+    >>> nx.efficiency(G, 2, 3)  # this gives efficiency for node 2 and 3
+    0.5
+
+    Notes
+    -----
+    Edge weights are ignored when computing the shortest path distances.
+
+    See also
+    --------
+    local_efficiency
+    global_efficiency
+
+    References
+    ----------
+    .. [1] Latora, Vito, and Massimo Marchiori.
+           "Efficient behavior of small-world networks."
+           *Physical Review Letters* 87.19 (2001): 198701.
+           <https://doi.org/10.1103/PhysRevLett.87.198701>
+
+    """
+    try:
+        eff = 1 / nx.shortest_path_length(G, u, v)
+    except NetworkXNoPath:
+        eff = 0
+    return eff
+
+
+@not_implemented_for("directed")
+@nx._dispatch
+def global_efficiency(G):
+    """Returns the average global efficiency of the graph.
+
+    The *efficiency* of a pair of nodes in a graph is the multiplicative
+    inverse of the shortest path distance between the nodes. The *average
+    global efficiency* of a graph is the average efficiency of all pairs of
+    nodes [1]_.
+
+    Parameters
+    ----------
+    G : :class:`networkx.Graph`
+        An undirected graph for which to compute the average global efficiency.
+
+    Returns
+    -------
+    float
+        The average global efficiency of the graph.
+
+    Examples
+    --------
+    >>> G = nx.Graph([(0, 1), (0, 2), (0, 3), (1, 2), (1, 3)])
+    >>> round(nx.global_efficiency(G), 12)
+    0.916666666667
+
+    Notes
+    -----
+    Edge weights are ignored when computing the shortest path distances.
+
+    See also
+    --------
+    local_efficiency
+
+    References
+    ----------
+    .. [1] Latora, Vito, and Massimo Marchiori.
+           "Efficient behavior of small-world networks."
+           *Physical Review Letters* 87.19 (2001): 198701.
+           <https://doi.org/10.1103/PhysRevLett.87.198701>
+
+    """
+    n = len(G)
+    denom = n * (n - 1)
+    if denom != 0:
+        lengths = nx.all_pairs_shortest_path_length(G)
+        g_eff = 0
+        for source, targets in lengths:
+            for target, distance in targets.items():
+                if distance > 0:
+                    g_eff += 1 / distance
+        g_eff /= denom
+        # g_eff = sum(1 / d for s, tgts in lengths
+        #                   for t, d in tgts.items() if d > 0) / denom
+    else:
+        g_eff = 0
+    # TODO This can be made more efficient by computing all pairs shortest
+    # path lengths in parallel.
+    return g_eff
+
+
+@not_implemented_for("directed")
+@nx._dispatch
+def local_efficiency(G):
+    """Returns the average local efficiency of the graph.
+
+    The *efficiency* of a pair of nodes in a graph is the multiplicative
+    inverse of the shortest path distance between the nodes. The *local
+    efficiency* of a node in the graph is the average global efficiency of the
+    subgraph induced by the neighbors of the node. The *average local
+    efficiency* is the average of the local efficiencies of each node [1]_.
+
+    Parameters
+    ----------
+    G : :class:`networkx.Graph`
+        An undirected graph for which to compute the average local efficiency.
+
+    Returns
+    -------
+    float
+        The average local efficiency of the graph.
+
+    Examples
+    --------
+    >>> G = nx.Graph([(0, 1), (0, 2), (0, 3), (1, 2), (1, 3)])
+    >>> nx.local_efficiency(G)
+    0.9166666666666667
+
+    Notes
+    -----
+    Edge weights are ignored when computing the shortest path distances.
+
+    See also
+    --------
+    global_efficiency
+
+    References
+    ----------
+    .. [1] Latora, Vito, and Massimo Marchiori.
+           "Efficient behavior of small-world networks."
+           *Physical Review Letters* 87.19 (2001): 198701.
+           <https://doi.org/10.1103/PhysRevLett.87.198701>
+
+    """
+    # TODO This summation can be trivially parallelized.
+    efficiency_list = (global_efficiency(G.subgraph(G[v])) for v in G)
+    return sum(efficiency_list) / len(G)

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/euler.py

@@ -0,0 +1,469 @@
+"""
+Eulerian circuits and graphs.
+"""
+from itertools import combinations
+
+import networkx as nx
+
+from ..utils import arbitrary_element, not_implemented_for
+
+__all__ = [
+    "is_eulerian",
+    "eulerian_circuit",
+    "eulerize",
+    "is_semieulerian",
+    "has_eulerian_path",
+    "eulerian_path",
+]
+
+
+@nx._dispatch
+def is_eulerian(G):
+    """Returns True if and only if `G` is Eulerian.
+
+    A graph is *Eulerian* if it has an Eulerian circuit. An *Eulerian
+    circuit* is a closed walk that includes each edge of a graph exactly
+    once.
+
+    Graphs with isolated vertices (i.e. vertices with zero degree) are not
+    considered to have Eulerian circuits. Therefore, if the graph is not
+    connected (or not strongly connected, for directed graphs), this function
+    returns False.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+       A graph, either directed or undirected.
+
+    Examples
+    --------
+    >>> nx.is_eulerian(nx.DiGraph({0: [3], 1: [2], 2: [3], 3: [0, 1]}))
+    True
+    >>> nx.is_eulerian(nx.complete_graph(5))
+    True
+    >>> nx.is_eulerian(nx.petersen_graph())
+    False
+
+    If you prefer to allow graphs with isolated vertices to have Eulerian circuits,
+    you can first remove such vertices and then call `is_eulerian` as below example shows.
+
+    >>> G = nx.Graph([(0, 1), (1, 2), (0, 2)])
+    >>> G.add_node(3)
+    >>> nx.is_eulerian(G)
+    False
+
+    >>> G.remove_nodes_from(list(nx.isolates(G)))
+    >>> nx.is_eulerian(G)
+    True
+
+
+    """
+    if G.is_directed():
+        # Every node must have equal in degree and out degree and the
+        # graph must be strongly connected
+        return all(
+            G.in_degree(n) == G.out_degree(n) for n in G
+        ) and nx.is_strongly_connected(G)
+    # An undirected Eulerian graph has no vertices of odd degree and
+    # must be connected.
+    return all(d % 2 == 0 for v, d in G.degree()) and nx.is_connected(G)
+
+
+@nx._dispatch
+def is_semieulerian(G):
+    """Return True iff `G` is semi-Eulerian.
+
+    G is semi-Eulerian if it has an Eulerian path but no Eulerian circuit.
+
+    See Also
+    --------
+    has_eulerian_path
+    is_eulerian
+    """
+    return has_eulerian_path(G) and not is_eulerian(G)
+
+
+def _find_path_start(G):
+    """Return a suitable starting vertex for an Eulerian path.
+
+    If no path exists, return None.
+    """
+    if not has_eulerian_path(G):
+        return None
+
+    if is_eulerian(G):
+        return arbitrary_element(G)
+
+    if G.is_directed():
+        v1, v2 = (v for v in G if G.in_degree(v) != G.out_degree(v))
+        # Determines which is the 'start' node (as opposed to the 'end')
+        if G.out_degree(v1) > G.in_degree(v1):
+            return v1
+        else:
+            return v2
+
+    else:
+        # In an undirected graph randomly choose one of the possibilities
+        start = [v for v in G if G.degree(v) % 2 != 0][0]
+        return start
+
+
+def _simplegraph_eulerian_circuit(G, source):
+    if G.is_directed():
+        degree = G.out_degree
+        edges = G.out_edges
+    else:
+        degree = G.degree
+        edges = G.edges
+    vertex_stack = [source]
+    last_vertex = None
+    while vertex_stack:
+        current_vertex = vertex_stack[-1]
+        if degree(current_vertex) == 0:
+            if last_vertex is not None:
+                yield (last_vertex, current_vertex)
+            last_vertex = current_vertex
+            vertex_stack.pop()
+        else:
+            _, next_vertex = arbitrary_element(edges(current_vertex))
+            vertex_stack.append(next_vertex)
+            G.remove_edge(current_vertex, next_vertex)
+
+
+def _multigraph_eulerian_circuit(G, source):
+    if G.is_directed():
+        degree = G.out_degree
+        edges = G.out_edges
+    else:
+        degree = G.degree
+        edges = G.edges
+    vertex_stack = [(source, None)]
+    last_vertex = None
+    last_key = None
+    while vertex_stack:
+        current_vertex, current_key = vertex_stack[-1]
+        if degree(current_vertex) == 0:
+            if last_vertex is not None:
+                yield (last_vertex, current_vertex, last_key)
+            last_vertex, last_key = current_vertex, current_key
+            vertex_stack.pop()
+        else:
+            triple = arbitrary_element(edges(current_vertex, keys=True))
+            _, next_vertex, next_key = triple
+            vertex_stack.append((next_vertex, next_key))
+            G.remove_edge(current_vertex, next_vertex, next_key)
+
+
+@nx._dispatch
+def eulerian_circuit(G, source=None, keys=False):
+    """Returns an iterator over the edges of an Eulerian circuit in `G`.
+
+    An *Eulerian circuit* is a closed walk that includes each edge of a
+    graph exactly once.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+       A graph, either directed or undirected.
+
+    source : node, optional
+       Starting node for circuit.
+
+    keys : bool
+       If False, edges generated by this function will be of the form
+       ``(u, v)``. Otherwise, edges will be of the form ``(u, v, k)``.
+       This option is ignored unless `G` is a multigraph.
+
+    Returns
+    -------
+    edges : iterator
+       An iterator over edges in the Eulerian circuit.
+
+    Raises
+    ------
+    NetworkXError
+       If the graph is not Eulerian.
+
+    See Also
+    --------
+    is_eulerian
+
+    Notes
+    -----
+    This is a linear time implementation of an algorithm adapted from [1]_.
+
+    For general information about Euler tours, see [2]_.
+
+    References
+    ----------
+    .. [1] J. Edmonds, E. L. Johnson.
+       Matching, Euler tours and the Chinese postman.
+       Mathematical programming, Volume 5, Issue 1 (1973), 111-114.
+    .. [2] https://en.wikipedia.org/wiki/Eulerian_path
+
+    Examples
+    --------
+    To get an Eulerian circuit in an undirected graph::
+
+        >>> G = nx.complete_graph(3)
+        >>> list(nx.eulerian_circuit(G))
+        [(0, 2), (2, 1), (1, 0)]
+        >>> list(nx.eulerian_circuit(G, source=1))
+        [(1, 2), (2, 0), (0, 1)]
+
+    To get the sequence of vertices in an Eulerian circuit::
+
+        >>> [u for u, v in nx.eulerian_circuit(G)]
+        [0, 2, 1]
+
+    """
+    if not is_eulerian(G):
+        raise nx.NetworkXError("G is not Eulerian.")
+    if G.is_directed():
+        G = G.reverse()
+    else:
+        G = G.copy()
+    if source is None:
+        source = arbitrary_element(G)
+    if G.is_multigraph():
+        for u, v, k in _multigraph_eulerian_circuit(G, source):
+            if keys:
+                yield u, v, k
+            else:
+                yield u, v
+    else:
+        yield from _simplegraph_eulerian_circuit(G, source)
+
+
+@nx._dispatch
+def has_eulerian_path(G, source=None):
+    """Return True iff `G` has an Eulerian path.
+
+    An Eulerian path is a path in a graph which uses each edge of a graph
+    exactly once. If `source` is specified, then this function checks
+    whether an Eulerian path that starts at node `source` exists.
+
+    A directed graph has an Eulerian path iff:
+        - at most one vertex has out_degree - in_degree = 1,
+        - at most one vertex has in_degree - out_degree = 1,
+        - every other vertex has equal in_degree and out_degree,
+        - and all of its vertices belong to a single connected
+          component of the underlying undirected graph.
+
+    If `source` is not None, an Eulerian path starting at `source` exists if no
+    other node has out_degree - in_degree = 1. This is equivalent to either
+    there exists an Eulerian circuit or `source` has out_degree - in_degree = 1
+    and the conditions above hold.
+
+    An undirected graph has an Eulerian path iff:
+        - exactly zero or two vertices have odd degree,
+        - and all of its vertices belong to a single connected component.
+
+    If `source` is not None, an Eulerian path starting at `source` exists if
+    either there exists an Eulerian circuit or `source` has an odd degree and the
+    conditions above hold.
+
+    Graphs with isolated vertices (i.e. vertices with zero degree) are not considered
+    to have an Eulerian path. Therefore, if the graph is not connected (or not strongly
+    connected, for directed graphs), this function returns False.
+
+    Parameters
+    ----------
+    G : NetworkX Graph
+        The graph to find an euler path in.
+
+    source : node, optional
+        Starting node for path.
+
+    Returns
+    -------
+    Bool : True if G has an Eulerian path.
+
+    Examples
+    --------
+    If you prefer to allow graphs with isolated vertices to have Eulerian path,
+    you can first remove such vertices and then call `has_eulerian_path` as below example shows.
+
+    >>> G = nx.Graph([(0, 1), (1, 2), (0, 2)])
+    >>> G.add_node(3)
+    >>> nx.has_eulerian_path(G)
+    False
+
+    >>> G.remove_nodes_from(list(nx.isolates(G)))
+    >>> nx.has_eulerian_path(G)
+    True
+
+    See Also
+    --------
+    is_eulerian
+    eulerian_path
+    """
+    if nx.is_eulerian(G):
+        return True
+
+    if G.is_directed():
+        ins = G.in_degree
+        outs = G.out_degree
+        # Since we know it is not eulerian, outs - ins must be 1 for source
+        if source is not None and outs[source] - ins[source] != 1:
+            return False
+
+        unbalanced_ins = 0
+        unbalanced_outs = 0
+        for v in G:
+            if ins[v] - outs[v] == 1:
+                unbalanced_ins += 1
+            elif outs[v] - ins[v] == 1:
+                unbalanced_outs += 1
+            elif ins[v] != outs[v]:
+                return False
+
+        return (
+            unbalanced_ins <= 1 and unbalanced_outs <= 1 and nx.is_weakly_connected(G)
+        )
+    else:
+        # We know it is not eulerian, so degree of source must be odd.
+        if source is not None and G.degree[source] % 2 != 1:
+            return False
+
+        # Sum is 2 since we know it is not eulerian (which implies sum is 0)
+        return sum(d % 2 == 1 for v, d in G.degree()) == 2 and nx.is_connected(G)
+
+
+@nx._dispatch
+def eulerian_path(G, source=None, keys=False):
+    """Return an iterator over the edges of an Eulerian path in `G`.
+
+    Parameters
+    ----------
+    G : NetworkX Graph
+        The graph in which to look for an eulerian path.
+    source : node or None (default: None)
+        The node at which to start the search. None means search over all
+        starting nodes.
+    keys : Bool (default: False)
+        Indicates whether to yield edge 3-tuples (u, v, edge_key).
+        The default yields edge 2-tuples
+
+    Yields
+    ------
+    Edge tuples along the eulerian path.
+
+    Warning: If `source` provided is not the start node of an Euler path
+    will raise error even if an Euler Path exists.
+    """
+    if not has_eulerian_path(G, source):
+        raise nx.NetworkXError("Graph has no Eulerian paths.")
+    if G.is_directed():
+        G = G.reverse()
+        if source is None or nx.is_eulerian(G) is False:
+            source = _find_path_start(G)
+        if G.is_multigraph():
+            for u, v, k in _multigraph_eulerian_circuit(G, source):
+                if keys:
+                    yield u, v, k
+                else:
+                    yield u, v
+        else:
+            yield from _simplegraph_eulerian_circuit(G, source)
+    else:
+        G = G.copy()
+        if source is None:
+            source = _find_path_start(G)
+        if G.is_multigraph():
+            if keys:
+                yield from reversed(
+                    [(v, u, k) for u, v, k in _multigraph_eulerian_circuit(G, source)]
+                )
+            else:
+                yield from reversed(
+                    [(v, u) for u, v, k in _multigraph_eulerian_circuit(G, source)]
+                )
+        else:
+            yield from reversed(
+                [(v, u) for u, v in _simplegraph_eulerian_circuit(G, source)]
+            )
+
+
+@not_implemented_for("directed")
+@nx._dispatch
+def eulerize(G):
+    """Transforms a graph into an Eulerian graph.
+
+    If `G` is Eulerian the result is `G` as a MultiGraph, otherwise the result is a smallest
+    (in terms of the number of edges) multigraph whose underlying simple graph is `G`.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+       An undirected graph
+
+    Returns
+    -------
+    G : NetworkX multigraph
+
+    Raises
+    ------
+    NetworkXError
+       If the graph is not connected.
+
+    See Also
+    --------
+    is_eulerian
+    eulerian_circuit
+
+    References
+    ----------
+    .. [1] J. Edmonds, E. L. Johnson.
+       Matching, Euler tours and the Chinese postman.
+       Mathematical programming, Volume 5, Issue 1 (1973), 111-114.
+    .. [2] https://en.wikipedia.org/wiki/Eulerian_path
+    .. [3] http://web.math.princeton.edu/math_alive/5/Notes1.pdf
+
+    Examples
+    --------
+        >>> G = nx.complete_graph(10)
+        >>> H = nx.eulerize(G)
+        >>> nx.is_eulerian(H)
+        True
+
+    """
+    if G.order() == 0:
+        raise nx.NetworkXPointlessConcept("Cannot Eulerize null graph")
+    if not nx.is_connected(G):
+        raise nx.NetworkXError("G is not connected")
+    odd_degree_nodes = [n for n, d in G.degree() if d % 2 == 1]
+    G = nx.MultiGraph(G)
+    if len(odd_degree_nodes) == 0:
+        return G
+
+    # get all shortest paths between vertices of odd degree
+    odd_deg_pairs_paths = [
+        (m, {n: nx.shortest_path(G, source=m, target=n)})
+        for m, n in combinations(odd_degree_nodes, 2)
+    ]
+
+    # use the number of vertices in a graph + 1 as an upper bound on
+    # the maximum length of a path in G
+    upper_bound_on_max_path_length = len(G) + 1
+
+    # use "len(G) + 1 - len(P)",
+    # where P is a shortest path between vertices n and m,
+    # as edge-weights in a new graph
+    # store the paths in the graph for easy indexing later
+    Gp = nx.Graph()
+    for n, Ps in odd_deg_pairs_paths:
+        for m, P in Ps.items():
+            if n != m:
+                Gp.add_edge(
+                    m, n, weight=upper_bound_on_max_path_length - len(P), path=P
+                )
+
+    # find the minimum weight matching of edges in the weighted graph
+    best_matching = nx.Graph(list(nx.max_weight_matching(Gp)))
+
+    # duplicate each edge along each path in the set of paths in Gp
+    for m, n in best_matching.edges():
+        path = Gp[m][n]["path"]
+        G.add_edges_from(nx.utils.pairwise(path))
+    return G

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/flow/preflowpush.py

@@ -0,0 +1,429 @@
+"""
+Highest-label preflow-push algorithm for maximum flow problems.
+"""
+
+from collections import deque
+from itertools import islice
+
+import networkx as nx
+
+from ...utils import arbitrary_element
+from .utils import (
+    CurrentEdge,
+    GlobalRelabelThreshold,
+    Level,
+    build_residual_network,
+    detect_unboundedness,
+)
+
+__all__ = ["preflow_push"]
+
+
+def preflow_push_impl(G, s, t, capacity, residual, global_relabel_freq, value_only):
+    """Implementation of the highest-label preflow-push algorithm."""
+    if s not in G:
+        raise nx.NetworkXError(f"node {str(s)} not in graph")
+    if t not in G:
+        raise nx.NetworkXError(f"node {str(t)} not in graph")
+    if s == t:
+        raise nx.NetworkXError("source and sink are the same node")
+
+    if global_relabel_freq is None:
+        global_relabel_freq = 0
+    if global_relabel_freq < 0:
+        raise nx.NetworkXError("global_relabel_freq must be nonnegative.")
+
+    if residual is None:
+        R = build_residual_network(G, capacity)
+    else:
+        R = residual
+
+    detect_unboundedness(R, s, t)
+
+    R_nodes = R.nodes
+    R_pred = R.pred
+    R_succ = R.succ
+
+    # Initialize/reset the residual network.
+    for u in R:
+        R_nodes[u]["excess"] = 0
+        for e in R_succ[u].values():
+            e["flow"] = 0
+
+    def reverse_bfs(src):
+        """Perform a reverse breadth-first search from src in the residual
+        network.
+        """
+        heights = {src: 0}
+        q = deque([(src, 0)])
+        while q:
+            u, height = q.popleft()
+            height += 1
+            for v, attr in R_pred[u].items():
+                if v not in heights and attr["flow"] < attr["capacity"]:
+                    heights[v] = height
+                    q.append((v, height))
+        return heights
+
+    # Initialize heights of the nodes.
+    heights = reverse_bfs(t)
+
+    if s not in heights:
+        # t is not reachable from s in the residual network. The maximum flow
+        # must be zero.
+        R.graph["flow_value"] = 0
+        return R
+
+    n = len(R)
+    # max_height represents the height of the highest level below level n with
+    # at least one active node.
+    max_height = max(heights[u] for u in heights if u != s)
+    heights[s] = n
+
+    grt = GlobalRelabelThreshold(n, R.size(), global_relabel_freq)
+
+    # Initialize heights and 'current edge' data structures of the nodes.
+    for u in R:
+        R_nodes[u]["height"] = heights[u] if u in heights else n + 1
+        R_nodes[u]["curr_edge"] = CurrentEdge(R_succ[u])
+
+    def push(u, v, flow):
+        """Push flow units of flow from u to v."""
+        R_succ[u][v]["flow"] += flow
+        R_succ[v][u]["flow"] -= flow
+        R_nodes[u]["excess"] -= flow
+        R_nodes[v]["excess"] += flow
+
+    # The maximum flow must be nonzero now. Initialize the preflow by
+    # saturating all edges emanating from s.
+    for u, attr in R_succ[s].items():
+        flow = attr["capacity"]
+        if flow > 0:
+            push(s, u, flow)
+
+    # Partition nodes into levels.
+    levels = [Level() for i in range(2 * n)]
+    for u in R:
+        if u != s and u != t:
+            level = levels[R_nodes[u]["height"]]
+            if R_nodes[u]["excess"] > 0:
+                level.active.add(u)
+            else:
+                level.inactive.add(u)
+
+    def activate(v):
+        """Move a node from the inactive set to the active set of its level."""
+        if v != s and v != t:
+            level = levels[R_nodes[v]["height"]]
+            if v in level.inactive:
+                level.inactive.remove(v)
+                level.active.add(v)
+
+    def relabel(u):
+        """Relabel a node to create an admissible edge."""
+        grt.add_work(len(R_succ[u]))
+        return (
+            min(
+                R_nodes[v]["height"]
+                for v, attr in R_succ[u].items()
+                if attr["flow"] < attr["capacity"]
+            )
+            + 1
+        )
+
+    def discharge(u, is_phase1):
+        """Discharge a node until it becomes inactive or, during phase 1 (see
+        below), its height reaches at least n. The node is known to have the
+        largest height among active nodes.
+        """
+        height = R_nodes[u]["height"]
+        curr_edge = R_nodes[u]["curr_edge"]
+        # next_height represents the next height to examine after discharging
+        # the current node. During phase 1, it is capped to below n.
+        next_height = height
+        levels[height].active.remove(u)
+        while True:
+            v, attr = curr_edge.get()
+            if height == R_nodes[v]["height"] + 1 and attr["flow"] < attr["capacity"]:
+                flow = min(R_nodes[u]["excess"], attr["capacity"] - attr["flow"])
+                push(u, v, flow)
+                activate(v)
+                if R_nodes[u]["excess"] == 0:
+                    # The node has become inactive.
+                    levels[height].inactive.add(u)
+                    break
+            try:
+                curr_edge.move_to_next()
+            except StopIteration:
+                # We have run off the end of the adjacency list, and there can
+                # be no more admissible edges. Relabel the node to create one.
+                height = relabel(u)
+                if is_phase1 and height >= n - 1:
+                    # Although the node is still active, with a height at least
+                    # n - 1, it is now known to be on the s side of the minimum
+                    # s-t cut. Stop processing it until phase 2.
+                    levels[height].active.add(u)
+                    break
+                # The first relabel operation after global relabeling may not
+                # increase the height of the node since the 'current edge' data
+                # structure is not rewound. Use height instead of (height - 1)
+                # in case other active nodes at the same level are missed.
+                next_height = height
+        R_nodes[u]["height"] = height
+        return next_height
+
+    def gap_heuristic(height):
+        """Apply the gap heuristic."""
+        # Move all nodes at levels (height + 1) to max_height to level n + 1.
+        for level in islice(levels, height + 1, max_height + 1):
+            for u in level.active:
+                R_nodes[u]["height"] = n + 1
+            for u in level.inactive:
+                R_nodes[u]["height"] = n + 1
+            levels[n + 1].active.update(level.active)
+            level.active.clear()
+            levels[n + 1].inactive.update(level.inactive)
+            level.inactive.clear()
+
+    def global_relabel(from_sink):
+        """Apply the global relabeling heuristic."""
+        src = t if from_sink else s
+        heights = reverse_bfs(src)
+        if not from_sink:
+            # s must be reachable from t. Remove t explicitly.
+            del heights[t]
+        max_height = max(heights.values())
+        if from_sink:
+            # Also mark nodes from which t is unreachable for relabeling. This
+            # serves the same purpose as the gap heuristic.
+            for u in R:
+                if u not in heights and R_nodes[u]["height"] < n:
+                    heights[u] = n + 1
+        else:
+            # Shift the computed heights because the height of s is n.
+            for u in heights:
+                heights[u] += n
+            max_height += n
+        del heights[src]
+        for u, new_height in heights.items():
+            old_height = R_nodes[u]["height"]
+            if new_height != old_height:
+                if u in levels[old_height].active:
+                    levels[old_height].active.remove(u)
+                    levels[new_height].active.add(u)
+                else:
+                    levels[old_height].inactive.remove(u)
+                    levels[new_height].inactive.add(u)
+                R_nodes[u]["height"] = new_height
+        return max_height
+
+    # Phase 1: Find the maximum preflow by pushing as much flow as possible to
+    # t.
+
+    height = max_height
+    while height > 0:
+        # Discharge active nodes in the current level.
+        while True:
+            level = levels[height]
+            if not level.active:
+                # All active nodes in the current level have been discharged.
+                # Move to the next lower level.
+                height -= 1
+                break
+            # Record the old height and level for the gap heuristic.
+            old_height = height
+            old_level = level
+            u = arbitrary_element(level.active)
+            height = discharge(u, True)
+            if grt.is_reached():
+                # Global relabeling heuristic: Recompute the exact heights of
+                # all nodes.
+                height = global_relabel(True)
+                max_height = height
+                grt.clear_work()
+            elif not old_level.active and not old_level.inactive:
+                # Gap heuristic: If the level at old_height is empty (a 'gap'),
+                # a minimum cut has been identified. All nodes with heights
+                # above old_height can have their heights set to n + 1 and not
+                # be further processed before a maximum preflow is found.
+                gap_heuristic(old_height)
+                height = old_height - 1
+                max_height = height
+            else:
+                # Update the height of the highest level with at least one
+                # active node.
+                max_height = max(max_height, height)
+
+    # A maximum preflow has been found. The excess at t is the maximum flow
+    # value.
+    if value_only:
+        R.graph["flow_value"] = R_nodes[t]["excess"]
+        return R
+
+    # Phase 2: Convert the maximum preflow into a maximum flow by returning the
+    # excess to s.
+
+    # Relabel all nodes so that they have accurate heights.
+    height = global_relabel(False)
+    grt.clear_work()
+
+    # Continue to discharge the active nodes.
+    while height > n:
+        # Discharge active nodes in the current level.
+        while True:
+            level = levels[height]
+            if not level.active:
+                # All active nodes in the current level have been discharged.
+                # Move to the next lower level.
+                height -= 1
+                break
+            u = arbitrary_element(level.active)
+            height = discharge(u, False)
+            if grt.is_reached():
+                # Global relabeling heuristic.
+                height = global_relabel(False)
+                grt.clear_work()
+
+    R.graph["flow_value"] = R_nodes[t]["excess"]
+    return R
+
+
+@nx._dispatch(
+    graphs={"G": 0, "residual?": 4},
+    edge_attrs={"capacity": float("inf")},
+    preserve_edge_attrs={"residual": {"capacity": float("inf")}},
+    preserve_graph_attrs={"residual"},
+)
+def preflow_push(
+    G, s, t, capacity="capacity", residual=None, global_relabel_freq=1, value_only=False
+):
+    r"""Find a maximum single-commodity flow using the highest-label
+    preflow-push algorithm.
+
+    This function returns the residual network resulting after computing
+    the maximum flow. See below for details about the conventions
+    NetworkX uses for defining residual networks.
+
+    This algorithm has a running time of $O(n^2 \sqrt{m})$ for $n$ nodes and
+    $m$ edges.
+
+
+    Parameters
+    ----------
+    G : NetworkX graph
+        Edges of the graph are expected to have an attribute called
+        'capacity'. If this attribute is not present, the edge is
+        considered to have infinite capacity.
+
+    s : node
+        Source node for the flow.
+
+    t : node
+        Sink node for the flow.
+
+    capacity : string
+        Edges of the graph G are expected to have an attribute capacity
+        that indicates how much flow the edge can support. If this
+        attribute is not present, the edge is considered to have
+        infinite capacity. Default value: 'capacity'.
+
+    residual : NetworkX graph
+        Residual network on which the algorithm is to be executed. If None, a
+        new residual network is created. Default value: None.
+
+    global_relabel_freq : integer, float
+        Relative frequency of applying the global relabeling heuristic to speed
+        up the algorithm. If it is None, the heuristic is disabled. Default
+        value: 1.
+
+    value_only : bool
+        If False, compute a maximum flow; otherwise, compute a maximum preflow
+        which is enough for computing the maximum flow value. Default value:
+        False.
+
+    Returns
+    -------
+    R : NetworkX DiGraph
+        Residual network after computing the maximum flow.
+
+    Raises
+    ------
+    NetworkXError
+        The algorithm does not support MultiGraph and MultiDiGraph. If
+        the input graph is an instance of one of these two classes, a
+        NetworkXError is raised.
+
+    NetworkXUnbounded
+        If the graph has a path of infinite capacity, the value of a
+        feasible flow on the graph is unbounded above and the function
+        raises a NetworkXUnbounded.
+
+    See also
+    --------
+    :meth:`maximum_flow`
+    :meth:`minimum_cut`
+    :meth:`edmonds_karp`
+    :meth:`shortest_augmenting_path`
+
+    Notes
+    -----
+    The residual network :samp:`R` from an input graph :samp:`G` has the
+    same nodes as :samp:`G`. :samp:`R` is a DiGraph that contains a pair
+    of edges :samp:`(u, v)` and :samp:`(v, u)` iff :samp:`(u, v)` is not a
+    self-loop, and at least one of :samp:`(u, v)` and :samp:`(v, u)` exists
+    in :samp:`G`. For each node :samp:`u` in :samp:`R`,
+    :samp:`R.nodes[u]['excess']` represents the difference between flow into
+    :samp:`u` and flow out of :samp:`u`.
+
+    For each edge :samp:`(u, v)` in :samp:`R`, :samp:`R[u][v]['capacity']`
+    is equal to the capacity of :samp:`(u, v)` in :samp:`G` if it exists
+    in :samp:`G` or zero otherwise. If the capacity is infinite,
+    :samp:`R[u][v]['capacity']` will have a high arbitrary finite value
+    that does not affect the solution of the problem. This value is stored in
+    :samp:`R.graph['inf']`. For each edge :samp:`(u, v)` in :samp:`R`,
+    :samp:`R[u][v]['flow']` represents the flow function of :samp:`(u, v)` and
+    satisfies :samp:`R[u][v]['flow'] == -R[v][u]['flow']`.
+
+    The flow value, defined as the total flow into :samp:`t`, the sink, is
+    stored in :samp:`R.graph['flow_value']`. Reachability to :samp:`t` using
+    only edges :samp:`(u, v)` such that
+    :samp:`R[u][v]['flow'] < R[u][v]['capacity']` induces a minimum
+    :samp:`s`-:samp:`t` cut.
+
+    Examples
+    --------
+    >>> from networkx.algorithms.flow import preflow_push
+
+    The functions that implement flow algorithms and output a residual
+    network, such as this one, are not imported to the base NetworkX
+    namespace, so you have to explicitly import them from the flow package.
+
+    >>> G = nx.DiGraph()
+    >>> G.add_edge("x", "a", capacity=3.0)
+    >>> G.add_edge("x", "b", capacity=1.0)
+    >>> G.add_edge("a", "c", capacity=3.0)
+    >>> G.add_edge("b", "c", capacity=5.0)
+    >>> G.add_edge("b", "d", capacity=4.0)
+    >>> G.add_edge("d", "e", capacity=2.0)
+    >>> G.add_edge("c", "y", capacity=2.0)
+    >>> G.add_edge("e", "y", capacity=3.0)
+    >>> R = preflow_push(G, "x", "y")
+    >>> flow_value = nx.maximum_flow_value(G, "x", "y")
+    >>> flow_value == R.graph["flow_value"]
+    True
+    >>> # preflow_push also stores the maximum flow value
+    >>> # in the excess attribute of the sink node t
+    >>> flow_value == R.nodes["y"]["excess"]
+    True
+    >>> # For some problems, you might only want to compute a
+    >>> # maximum preflow.
+    >>> R = preflow_push(G, "x", "y", value_only=True)
+    >>> flow_value == R.graph["flow_value"]
+    True
+    >>> flow_value == R.nodes["y"]["excess"]
+    True
+
+    """
+    R = preflow_push_impl(G, s, t, capacity, residual, global_relabel_freq, value_only)
+    R.graph["algorithm"] = "preflow_push"
+    return R

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/matching.py

@@ -0,0 +1,1151 @@
+"""Functions for computing and verifying matchings in a graph."""
+from collections import Counter
+from itertools import combinations, repeat
+
+import networkx as nx
+from networkx.utils import not_implemented_for
+
+__all__ = [
+    "is_matching",
+    "is_maximal_matching",
+    "is_perfect_matching",
+    "max_weight_matching",
+    "min_weight_matching",
+    "maximal_matching",
+]
+
+
+@not_implemented_for("multigraph")
+@not_implemented_for("directed")
+@nx._dispatch
+def maximal_matching(G):
+    r"""Find a maximal matching in the graph.
+
+    A matching is a subset of edges in which no node occurs more than once.
+    A maximal matching cannot add more edges and still be a matching.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+        Undirected graph
+
+    Returns
+    -------
+    matching : set
+        A maximal matching of the graph.
+
+    Examples
+    --------
+    >>> G = nx.Graph([(1, 2), (1, 3), (2, 3), (2, 4), (3, 5), (4, 5)])
+    >>> sorted(nx.maximal_matching(G))
+    [(1, 2), (3, 5)]
+
+    Notes
+    -----
+    The algorithm greedily selects a maximal matching M of the graph G
+    (i.e. no superset of M exists). It runs in $O(|E|)$ time.
+    """
+    matching = set()
+    nodes = set()
+    for edge in G.edges():
+        # If the edge isn't covered, add it to the matching
+        # then remove neighborhood of u and v from consideration.
+        u, v = edge
+        if u not in nodes and v not in nodes and u != v:
+            matching.add(edge)
+            nodes.update(edge)
+    return matching
+
+
+def matching_dict_to_set(matching):
+    """Converts matching dict format to matching set format
+
+    Converts a dictionary representing a matching (as returned by
+    :func:`max_weight_matching`) to a set representing a matching (as
+    returned by :func:`maximal_matching`).
+
+    In the definition of maximal matching adopted by NetworkX,
+    self-loops are not allowed, so the provided dictionary is expected
+    to never have any mapping from a key to itself. However, the
+    dictionary is expected to have mirrored key/value pairs, for
+    example, key ``u`` with value ``v`` and key ``v`` with value ``u``.
+
+    """
+    edges = set()
+    for edge in matching.items():
+        u, v = edge
+        if (v, u) in edges or edge in edges:
+            continue
+        if u == v:
+            raise nx.NetworkXError(f"Selfloops cannot appear in matchings {edge}")
+        edges.add(edge)
+    return edges
+
+
+@nx._dispatch
+def is_matching(G, matching):
+    """Return True if ``matching`` is a valid matching of ``G``
+
+    A *matching* in a graph is a set of edges in which no two distinct
+    edges share a common endpoint. Each node is incident to at most one
+    edge in the matching. The edges are said to be independent.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    matching : dict or set
+        A dictionary or set representing a matching. If a dictionary, it
+        must have ``matching[u] == v`` and ``matching[v] == u`` for each
+        edge ``(u, v)`` in the matching. If a set, it must have elements
+        of the form ``(u, v)``, where ``(u, v)`` is an edge in the
+        matching.
+
+    Returns
+    -------
+    bool
+        Whether the given set or dictionary represents a valid matching
+        in the graph.
+
+    Raises
+    ------
+    NetworkXError
+        If the proposed matching has an edge to a node not in G.
+        Or if the matching is not a collection of 2-tuple edges.
+
+    Examples
+    --------
+    >>> G = nx.Graph([(1, 2), (1, 3), (2, 3), (2, 4), (3, 5), (4, 5)])
+    >>> nx.is_maximal_matching(G, {1: 3, 2: 4})  # using dict to represent matching
+    True
+
+    >>> nx.is_matching(G, {(1, 3), (2, 4)})  # using set to represent matching
+    True
+
+    """
+    if isinstance(matching, dict):
+        matching = matching_dict_to_set(matching)
+
+    nodes = set()
+    for edge in matching:
+        if len(edge) != 2:
+            raise nx.NetworkXError(f"matching has non-2-tuple edge {edge}")
+        u, v = edge
+        if u not in G or v not in G:
+            raise nx.NetworkXError(f"matching contains edge {edge} with node not in G")
+        if u == v:
+            return False
+        if not G.has_edge(u, v):
+            return False
+        if u in nodes or v in nodes:
+            return False
+        nodes.update(edge)
+    return True
+
+
+@nx._dispatch
+def is_maximal_matching(G, matching):
+    """Return True if ``matching`` is a maximal matching of ``G``
+
+    A *maximal matching* in a graph is a matching in which adding any
+    edge would cause the set to no longer be a valid matching.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    matching : dict or set
+        A dictionary or set representing a matching. If a dictionary, it
+        must have ``matching[u] == v`` and ``matching[v] == u`` for each
+        edge ``(u, v)`` in the matching. If a set, it must have elements
+        of the form ``(u, v)``, where ``(u, v)`` is an edge in the
+        matching.
+
+    Returns
+    -------
+    bool
+        Whether the given set or dictionary represents a valid maximal
+        matching in the graph.
+
+    Examples
+    --------
+    >>> G = nx.Graph([(1, 2), (1, 3), (2, 3), (3, 4), (3, 5)])
+    >>> nx.is_maximal_matching(G, {(1, 2), (3, 4)})
+    True
+
+    """
+    if isinstance(matching, dict):
+        matching = matching_dict_to_set(matching)
+    # If the given set is not a matching, then it is not a maximal matching.
+    edges = set()
+    nodes = set()
+    for edge in matching:
+        if len(edge) != 2:
+            raise nx.NetworkXError(f"matching has non-2-tuple edge {edge}")
+        u, v = edge
+        if u not in G or v not in G:
+            raise nx.NetworkXError(f"matching contains edge {edge} with node not in G")
+        if u == v:
+            return False
+        if not G.has_edge(u, v):
+            return False
+        if u in nodes or v in nodes:
+            return False
+        nodes.update(edge)
+        edges.add(edge)
+        edges.add((v, u))
+    # A matching is maximal if adding any new edge from G to it
+    # causes the resulting set to match some node twice.
+    # Be careful to check for adding selfloops
+    for u, v in G.edges:
+        if (u, v) not in edges:
+            # could add edge (u, v) to edges and have a bigger matching
+            if u not in nodes and v not in nodes and u != v:
+                return False
+    return True
+
+
+@nx._dispatch
+def is_perfect_matching(G, matching):
+    """Return True if ``matching`` is a perfect matching for ``G``
+
+    A *perfect matching* in a graph is a matching in which exactly one edge
+    is incident upon each vertex.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    matching : dict or set
+        A dictionary or set representing a matching. If a dictionary, it
+        must have ``matching[u] == v`` and ``matching[v] == u`` for each
+        edge ``(u, v)`` in the matching. If a set, it must have elements
+        of the form ``(u, v)``, where ``(u, v)`` is an edge in the
+        matching.
+
+    Returns
+    -------
+    bool
+        Whether the given set or dictionary represents a valid perfect
+        matching in the graph.
+
+    Examples
+    --------
+    >>> G = nx.Graph([(1, 2), (1, 3), (2, 3), (2, 4), (3, 5), (4, 5), (4, 6)])
+    >>> my_match = {1: 2, 3: 5, 4: 6}
+    >>> nx.is_perfect_matching(G, my_match)
+    True
+
+    """
+    if isinstance(matching, dict):
+        matching = matching_dict_to_set(matching)
+
+    nodes = set()
+    for edge in matching:
+        if len(edge) != 2:
+            raise nx.NetworkXError(f"matching has non-2-tuple edge {edge}")
+        u, v = edge
+        if u not in G or v not in G:
+            raise nx.NetworkXError(f"matching contains edge {edge} with node not in G")
+        if u == v:
+            return False
+        if not G.has_edge(u, v):
+            return False
+        if u in nodes or v in nodes:
+            return False
+        nodes.update(edge)
+    return len(nodes) == len(G)
+
+
+@not_implemented_for("multigraph")
+@not_implemented_for("directed")
+@nx._dispatch(edge_attrs="weight")
+def min_weight_matching(G, weight="weight"):
+    """Computing a minimum-weight maximal matching of G.
+
+    Use the maximum-weight algorithm with edge weights subtracted
+    from the maximum weight of all edges.
+
+    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 method replaces the edge weights with 1 plus the maximum edge weight
+    minus the original edge weight.
+
+    new_weight = (max_weight + 1) - edge_weight
+
+    then runs :func:`max_weight_matching` with the new weights.
+    The max weight matching with these new weights corresponds
+    to the min weight matching using the original weights.
+    Adding 1 to the max edge weight keeps all edge weights positive
+    and as integers if they started as integers.
+
+    You might worry that adding 1 to each weight would make the algorithm
+    favor matchings with more edges. But we use the parameter
+    `maxcardinality=True` in `max_weight_matching` to ensure that the
+    number of edges in the competing matchings are the same and thus
+    the optimum does not change due to changes in the number of edges.
+
+    Read the documentation of `max_weight_matching` for more information.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+      Undirected graph
+
+    weight: string, optional (default='weight')
+       Edge data key corresponding to the edge weight.
+       If key not found, uses 1 as weight.
+
+    Returns
+    -------
+    matching : set
+        A minimal weight matching of the graph.
+
+    See Also
+    --------
+    max_weight_matching
+    """
+    if len(G.edges) == 0:
+        return max_weight_matching(G, maxcardinality=True, weight=weight)
+    G_edges = G.edges(data=weight, default=1)
+    max_weight = 1 + max(w for _, _, w in G_edges)
+    InvG = nx.Graph()
+    edges = ((u, v, max_weight - w) for u, v, w in G_edges)
+    InvG.add_weighted_edges_from(edges, weight=weight)
+    return max_weight_matching(InvG, maxcardinality=True, weight=weight)
+
+
+@not_implemented_for("multigraph")
+@not_implemented_for("directed")
+@nx._dispatch(edge_attrs="weight")
+def max_weight_matching(G, maxcardinality=False, weight="weight"):
+    """Compute a maximum-weighted matching of G.
+
+    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.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+      Undirected graph
+
+    maxcardinality: bool, optional (default=False)
+       If maxcardinality is True, compute the maximum-cardinality matching
+       with maximum weight among all maximum-cardinality matchings.
+
+    weight: string, optional (default='weight')
+       Edge data key corresponding to the edge weight.
+       If key not found, uses 1 as weight.
+
+
+    Returns
+    -------
+    matching : set
+        A maximal matching of the graph.
+
+     Examples
+    --------
+    >>> G = nx.Graph()
+    >>> edges = [(1, 2, 6), (1, 3, 2), (2, 3, 1), (2, 4, 7), (3, 5, 9), (4, 5, 3)]
+    >>> G.add_weighted_edges_from(edges)
+    >>> sorted(nx.max_weight_matching(G))
+    [(2, 4), (5, 3)]
+
+    Notes
+    -----
+    If G has edges with weight attributes the edge data are used as
+    weight values else the weights are assumed to be 1.
+
+    This function takes time O(number_of_nodes ** 3).
+
+    If all edge weights are integers, the algorithm uses only integer
+    computations.  If floating point weights are used, the algorithm
+    could return a slightly suboptimal matching due to numeric
+    precision errors.
+
+    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]_.
+
+    Bipartite graphs can also be matched using the functions present in
+    :mod:`networkx.algorithms.bipartite.matching`.
+
+    References
+    ----------
+    .. [1] "Efficient Algorithms for Finding Maximum Matching in Graphs",
+       Zvi Galil, ACM Computing Surveys, 1986.
+    """
+    #
+    # The algorithm is taken from "Efficient Algorithms for Finding Maximum
+    # Matching in Graphs" by Zvi Galil, ACM Computing Surveys, 1986.
+    # It 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.
+    #
+    # A C program for maximum weight matching by Ed Rothberg was used
+    # extensively to validate this new code.
+    #
+    # Many terms used in the code comments are explained in the paper
+    # by Galil. You will probably need the paper to make sense of this code.
+    #
+
+    class NoNode:
+        """Dummy value which is different from any node."""
+
+    class Blossom:
+        """Representation of a non-trivial blossom or sub-blossom."""
+
+        __slots__ = ["childs", "edges", "mybestedges"]
+
+        # b.childs is an ordered list of b's sub-blossoms, starting with
+        # the base and going round the blossom.
+
+        # b.edges is the list of b's connecting edges, such that
+        # b.edges[i] = (v, w) where v is a vertex in b.childs[i]
+        # and w is a vertex in b.childs[wrap(i+1)].
+
+        # If b is a top-level S-blossom,
+        # b.mybestedges is a list of least-slack edges to neighbouring
+        # S-blossoms, or None if no such list has been computed yet.
+        # This is used for efficient computation of delta3.
+
+        # Generate the blossom's leaf vertices.
+        def leaves(self):
+            stack = [*self.childs]
+            while stack:
+                t = stack.pop()
+                if isinstance(t, Blossom):
+                    stack.extend(t.childs)
+                else:
+                    yield t
+
+    # Get a list of vertices.
+    gnodes = list(G)
+    if not gnodes:
+        return set()  # don't bother with empty graphs
+
+    # Find the maximum edge weight.
+    maxweight = 0
+    allinteger = True
+    for i, j, d in G.edges(data=True):
+        wt = d.get(weight, 1)
+        if i != j and wt > maxweight:
+            maxweight = wt
+        allinteger = allinteger and (str(type(wt)).split("'")[1] in ("int", "long"))
+
+    # If v is a matched vertex, mate[v] is its partner vertex.
+    # If v is a single vertex, v does not occur as a key in mate.
+    # Initially all vertices are single; updated during augmentation.
+    mate = {}
+
+    # If b is a top-level blossom,
+    # label.get(b) is None if b is unlabeled (free),
+    #                 1 if b is an S-blossom,
+    #                 2 if b is a T-blossom.
+    # The label of a vertex is found by looking at the label of its top-level
+    # containing blossom.
+    # If v is a vertex inside a T-blossom, label[v] is 2 iff v is reachable
+    # from an S-vertex outside the blossom.
+    # Labels are assigned during a stage and reset after each augmentation.
+    label = {}
+
+    # If b is a labeled top-level blossom,
+    # labeledge[b] = (v, w) is the edge through which b obtained its label
+    # such that w is a vertex in b, or None if b's base vertex is single.
+    # If w is a vertex inside a T-blossom and label[w] == 2,
+    # labeledge[w] = (v, w) is an edge through which w is reachable from
+    # outside the blossom.
+    labeledge = {}
+
+    # If v is a vertex, inblossom[v] is the top-level blossom to which v
+    # belongs.
+    # If v is a top-level vertex, inblossom[v] == v since v is itself
+    # a (trivial) top-level blossom.
+    # Initially all vertices are top-level trivial blossoms.
+    inblossom = dict(zip(gnodes, gnodes))
+
+    # If b is a sub-blossom,
+    # blossomparent[b] is its immediate parent (sub-)blossom.
+    # If b is a top-level blossom, blossomparent[b] is None.
+    blossomparent = dict(zip(gnodes, repeat(None)))
+
+    # If b is a (sub-)blossom,
+    # blossombase[b] is its base VERTEX (i.e. recursive sub-blossom).
+    blossombase = dict(zip(gnodes, gnodes))
+
+    # If w is a free vertex (or an unreached vertex inside a T-blossom),
+    # bestedge[w] = (v, w) is the least-slack edge from an S-vertex,
+    # or None if there is no such edge.
+    # If b is a (possibly trivial) top-level S-blossom,
+    # bestedge[b] = (v, w) is the least-slack edge to a different S-blossom
+    # (v inside b), or None if there is no such edge.
+    # This is used for efficient computation of delta2 and delta3.
+    bestedge = {}
+
+    # If v is a vertex,
+    # dualvar[v] = 2 * u(v) where u(v) is the v's variable in the dual
+    # optimization problem (if all edge weights are integers, multiplication
+    # by two ensures that all values remain integers throughout the algorithm).
+    # Initially, u(v) = maxweight / 2.
+    dualvar = dict(zip(gnodes, repeat(maxweight)))
+
+    # If b is a non-trivial blossom,
+    # blossomdual[b] = z(b) where z(b) is b's variable in the dual
+    # optimization problem.
+    blossomdual = {}
+
+    # If (v, w) in allowedge or (w, v) in allowedg, then the edge
+    # (v, w) is known to have zero slack in the optimization problem;
+    # otherwise the edge may or may not have zero slack.
+    allowedge = {}
+
+    # Queue of newly discovered S-vertices.
+    queue = []
+
+    # Return 2 * slack of edge (v, w) (does not work inside blossoms).
+    def slack(v, w):
+        return dualvar[v] + dualvar[w] - 2 * G[v][w].get(weight, 1)
+
+    # Assign label t to the top-level blossom containing vertex w,
+    # coming through an edge from vertex v.
+    def assignLabel(w, t, v):
+        b = inblossom[w]
+        assert label.get(w) is None and label.get(b) is None
+        label[w] = label[b] = t
+        if v is not None:
+            labeledge[w] = labeledge[b] = (v, w)
+        else:
+            labeledge[w] = labeledge[b] = None
+        bestedge[w] = bestedge[b] = None
+        if t == 1:
+            # b became an S-vertex/blossom; add it(s vertices) to the queue.
+            if isinstance(b, Blossom):
+                queue.extend(b.leaves())
+            else:
+                queue.append(b)
+        elif t == 2:
+            # b became a T-vertex/blossom; assign label S to its mate.
+            # (If b is a non-trivial blossom, its base is the only vertex
+            # with an external mate.)
+            base = blossombase[b]
+            assignLabel(mate[base], 1, base)
+
+    # Trace back from vertices v and w to discover either a new blossom
+    # or an augmenting path. Return the base vertex of the new blossom,
+    # or NoNode if an augmenting path was found.
+    def scanBlossom(v, w):
+        # Trace back from v and w, placing breadcrumbs as we go.
+        path = []
+        base = NoNode
+        while v is not NoNode:
+            # Look for a breadcrumb in v's blossom or put a new breadcrumb.
+            b = inblossom[v]
+            if label[b] & 4:
+                base = blossombase[b]
+                break
+            assert label[b] == 1
+            path.append(b)
+            label[b] = 5
+            # Trace one step back.
+            if labeledge[b] is None:
+                # The base of blossom b is single; stop tracing this path.
+                assert blossombase[b] not in mate
+                v = NoNode
+            else:
+                assert labeledge[b][0] == mate[blossombase[b]]
+                v = labeledge[b][0]
+                b = inblossom[v]
+                assert label[b] == 2
+                # b is a T-blossom; trace one more step back.
+                v = labeledge[b][0]
+            # Swap v and w so that we alternate between both paths.
+            if w is not NoNode:
+                v, w = w, v
+        # Remove breadcrumbs.
+        for b in path:
+            label[b] = 1
+        # Return base vertex, if we found one.
+        return base
+
+    # Construct a new blossom with given base, through S-vertices v and w.
+    # Label the new blossom as S; set its dual variable to zero;
+    # relabel its T-vertices to S and add them to the queue.
+    def addBlossom(base, v, w):
+        bb = inblossom[base]
+        bv = inblossom[v]
+        bw = inblossom[w]
+        # Create blossom.
+        b = Blossom()
+        blossombase[b] = base
+        blossomparent[b] = None
+        blossomparent[bb] = b
+        # Make list of sub-blossoms and their interconnecting edge endpoints.
+        b.childs = path = []
+        b.edges = edgs = [(v, w)]
+        # Trace back from v to base.
+        while bv != bb:
+            # Add bv to the new blossom.
+            blossomparent[bv] = b
+            path.append(bv)
+            edgs.append(labeledge[bv])
+            assert label[bv] == 2 or (
+                label[bv] == 1 and labeledge[bv][0] == mate[blossombase[bv]]
+            )
+            # Trace one step back.
+            v = labeledge[bv][0]
+            bv = inblossom[v]
+        # Add base sub-blossom; reverse lists.
+        path.append(bb)
+        path.reverse()
+        edgs.reverse()
+        # Trace back from w to base.
+        while bw != bb:
+            # Add bw to the new blossom.
+            blossomparent[bw] = b
+            path.append(bw)
+            edgs.append((labeledge[bw][1], labeledge[bw][0]))
+            assert label[bw] == 2 or (
+                label[bw] == 1 and labeledge[bw][0] == mate[blossombase[bw]]
+            )
+            # Trace one step back.
+            w = labeledge[bw][0]
+            bw = inblossom[w]
+        # Set label to S.
+        assert label[bb] == 1
+        label[b] = 1
+        labeledge[b] = labeledge[bb]
+        # Set dual variable to zero.
+        blossomdual[b] = 0
+        # Relabel vertices.
+        for v in b.leaves():
+            if label[inblossom[v]] == 2:
+                # This T-vertex now turns into an S-vertex because it becomes
+                # part of an S-blossom; add it to the queue.
+                queue.append(v)
+            inblossom[v] = b
+        # Compute b.mybestedges.
+        bestedgeto = {}
+        for bv in path:
+            if isinstance(bv, Blossom):
+                if bv.mybestedges is not None:
+                    # Walk this subblossom's least-slack edges.
+                    nblist = bv.mybestedges
+                    # The sub-blossom won't need this data again.
+                    bv.mybestedges = None
+                else:
+                    # This subblossom does not have a list of least-slack
+                    # edges; get the information from the vertices.
+                    nblist = [
+                        (v, w) for v in bv.leaves() for w in G.neighbors(v) if v != w
+                    ]
+            else:
+                nblist = [(bv, w) for w in G.neighbors(bv) if bv != w]
+            for k in nblist:
+                (i, j) = k
+                if inblossom[j] == b:
+                    i, j = j, i
+                bj = inblossom[j]
+                if (
+                    bj != b
+                    and label.get(bj) == 1
+                    and ((bj not in bestedgeto) or slack(i, j) < slack(*bestedgeto[bj]))
+                ):
+                    bestedgeto[bj] = k
+            # Forget about least-slack edge of the subblossom.
+            bestedge[bv] = None
+        b.mybestedges = list(bestedgeto.values())
+        # Select bestedge[b].
+        mybestedge = None
+        bestedge[b] = None
+        for k in b.mybestedges:
+            kslack = slack(*k)
+            if mybestedge is None or kslack < mybestslack:
+                mybestedge = k
+                mybestslack = kslack
+        bestedge[b] = mybestedge
+
+    # Expand the given top-level blossom.
+    def expandBlossom(b, endstage):
+        # This is an obnoxiously complicated recursive function for the sake of
+        # a stack-transformation.  So, we hack around the complexity by using
+        # a trampoline pattern.  By yielding the arguments to each recursive
+        # call, we keep the actual callstack flat.
+
+        def _recurse(b, endstage):
+            # Convert sub-blossoms into top-level blossoms.
+            for s in b.childs:
+                blossomparent[s] = None
+                if isinstance(s, Blossom):
+                    if endstage and blossomdual[s] == 0:
+                        # Recursively expand this sub-blossom.
+                        yield s
+                    else:
+                        for v in s.leaves():
+                            inblossom[v] = s
+                else:
+                    inblossom[s] = s
+            # If we expand a T-blossom during a stage, its sub-blossoms must be
+            # relabeled.
+            if (not endstage) and label.get(b) == 2:
+                # Start at the sub-blossom through which the expanding
+                # blossom obtained its label, and relabel sub-blossoms untili
+                # we reach the base.
+                # Figure out through which sub-blossom the expanding blossom
+                # obtained its label initially.
+                entrychild = inblossom[labeledge[b][1]]
+                # Decide in which direction we will go round the blossom.
+                j = b.childs.index(entrychild)
+                if j & 1:
+                    # Start index is odd; go forward and wrap.
+                    j -= len(b.childs)
+                    jstep = 1
+                else:
+                    # Start index is even; go backward.
+                    jstep = -1
+                # Move along the blossom until we get to the base.
+                v, w = labeledge[b]
+                while j != 0:
+                    # Relabel the T-sub-blossom.
+                    if jstep == 1:
+                        p, q = b.edges[j]
+                    else:
+                        q, p = b.edges[j - 1]
+                    label[w] = None
+                    label[q] = None
+                    assignLabel(w, 2, v)
+                    # Step to the next S-sub-blossom and note its forward edge.
+                    allowedge[(p, q)] = allowedge[(q, p)] = True
+                    j += jstep
+                    if jstep == 1:
+                        v, w = b.edges[j]
+                    else:
+                        w, v = b.edges[j - 1]
+                    # Step to the next T-sub-blossom.
+                    allowedge[(v, w)] = allowedge[(w, v)] = True
+                    j += jstep
+                # Relabel the base T-sub-blossom WITHOUT stepping through to
+                # its mate (so don't call assignLabel).
+                bw = b.childs[j]
+                label[w] = label[bw] = 2
+                labeledge[w] = labeledge[bw] = (v, w)
+                bestedge[bw] = None
+                # Continue along the blossom until we get back to entrychild.
+                j += jstep
+                while b.childs[j] != entrychild:
+                    # Examine the vertices of the sub-blossom to see whether
+                    # it is reachable from a neighbouring S-vertex outside the
+                    # expanding blossom.
+                    bv = b.childs[j]
+                    if label.get(bv) == 1:
+                        # This sub-blossom just got label S through one of its
+                        # neighbours; leave it be.
+                        j += jstep
+                        continue
+                    if isinstance(bv, Blossom):
+                        for v in bv.leaves():
+                            if label.get(v):
+                                break
+                    else:
+                        v = bv
+                    # If the sub-blossom contains a reachable vertex, assign
+                    # label T to the sub-blossom.
+                    if label.get(v):
+                        assert label[v] == 2
+                        assert inblossom[v] == bv
+                        label[v] = None
+                        label[mate[blossombase[bv]]] = None
+                        assignLabel(v, 2, labeledge[v][0])
+                    j += jstep
+            # Remove the expanded blossom entirely.
+            label.pop(b, None)
+            labeledge.pop(b, None)
+            bestedge.pop(b, None)
+            del blossomparent[b]
+            del blossombase[b]
+            del blossomdual[b]
+
+        # Now, we apply the trampoline pattern.  We simulate a recursive
+        # callstack by maintaining a stack of generators, each yielding a
+        # sequence of function arguments.  We grow the stack by appending a call
+        # to _recurse on each argument tuple, and shrink the stack whenever a
+        # generator is exhausted.
+        stack = [_recurse(b, endstage)]
+        while stack:
+            top = stack[-1]
+            for s in top:
+                stack.append(_recurse(s, endstage))
+                break
+            else:
+                stack.pop()
+
+    # Swap matched/unmatched edges over an alternating path through blossom b
+    # between vertex v and the base vertex. Keep blossom bookkeeping
+    # consistent.
+    def augmentBlossom(b, v):
+        # This is an obnoxiously complicated recursive function for the sake of
+        # a stack-transformation.  So, we hack around the complexity by using
+        # a trampoline pattern.  By yielding the arguments to each recursive
+        # call, we keep the actual callstack flat.
+
+        def _recurse(b, v):
+            # Bubble up through the blossom tree from vertex v to an immediate
+            # sub-blossom of b.
+            t = v
+            while blossomparent[t] != b:
+                t = blossomparent[t]
+            # Recursively deal with the first sub-blossom.
+            if isinstance(t, Blossom):
+                yield (t, v)
+            # Decide in which direction we will go round the blossom.
+            i = j = b.childs.index(t)
+            if i & 1:
+                # Start index is odd; go forward and wrap.
+                j -= len(b.childs)
+                jstep = 1
+            else:
+                # Start index is even; go backward.
+                jstep = -1
+            # Move along the blossom until we get to the base.
+            while j != 0:
+                # Step to the next sub-blossom and augment it recursively.
+                j += jstep
+                t = b.childs[j]
+                if jstep == 1:
+                    w, x = b.edges[j]
+                else:
+                    x, w = b.edges[j - 1]
+                if isinstance(t, Blossom):
+                    yield (t, w)
+                # Step to the next sub-blossom and augment it recursively.
+                j += jstep
+                t = b.childs[j]
+                if isinstance(t, Blossom):
+                    yield (t, x)
+                # Match the edge connecting those sub-blossoms.
+                mate[w] = x
+                mate[x] = w
+            # Rotate the list of sub-blossoms to put the new base at the front.
+            b.childs = b.childs[i:] + b.childs[:i]
+            b.edges = b.edges[i:] + b.edges[:i]
+            blossombase[b] = blossombase[b.childs[0]]
+            assert blossombase[b] == v
+
+        # Now, we apply the trampoline pattern.  We simulate a recursive
+        # callstack by maintaining a stack of generators, each yielding a
+        # sequence of function arguments.  We grow the stack by appending a call
+        # to _recurse on each argument tuple, and shrink the stack whenever a
+        # generator is exhausted.
+        stack = [_recurse(b, v)]
+        while stack:
+            top = stack[-1]
+            for args in top:
+                stack.append(_recurse(*args))
+                break
+            else:
+                stack.pop()
+
+    # Swap matched/unmatched edges over an alternating path between two
+    # single vertices. The augmenting path runs through S-vertices v and w.
+    def augmentMatching(v, w):
+        for s, j in ((v, w), (w, v)):
+            # Match vertex s to vertex j. Then trace back from s
+            # until we find a single vertex, swapping matched and unmatched
+            # edges as we go.
+            while 1:
+                bs = inblossom[s]
+                assert label[bs] == 1
+                assert (labeledge[bs] is None and blossombase[bs] not in mate) or (
+                    labeledge[bs][0] == mate[blossombase[bs]]
+                )
+                # Augment through the S-blossom from s to base.
+                if isinstance(bs, Blossom):
+                    augmentBlossom(bs, s)
+                # Update mate[s]
+                mate[s] = j
+                # Trace one step back.
+                if labeledge[bs] is None:
+                    # Reached single vertex; stop.
+                    break
+                t = labeledge[bs][0]
+                bt = inblossom[t]
+                assert label[bt] == 2
+                # Trace one more step back.
+                s, j = labeledge[bt]
+                # Augment through the T-blossom from j to base.
+                assert blossombase[bt] == t
+                if isinstance(bt, Blossom):
+                    augmentBlossom(bt, j)
+                # Update mate[j]
+                mate[j] = s
+
+    # Verify that the optimum solution has been reached.
+    def verifyOptimum():
+        if maxcardinality:
+            # Vertices may have negative dual;
+            # find a constant non-negative number to add to all vertex duals.
+            vdualoffset = max(0, -min(dualvar.values()))
+        else:
+            vdualoffset = 0
+        # 0. all dual variables are non-negative
+        assert min(dualvar.values()) + vdualoffset >= 0
+        assert len(blossomdual) == 0 or min(blossomdual.values()) >= 0
+        # 0. all edges have non-negative slack and
+        # 1. all matched edges have zero slack;
+        for i, j, d in G.edges(data=True):
+            wt = d.get(weight, 1)
+            if i == j:
+                continue  # ignore self-loops
+            s = dualvar[i] + dualvar[j] - 2 * wt
+            iblossoms = [i]
+            jblossoms = [j]
+            while blossomparent[iblossoms[-1]] is not None:
+                iblossoms.append(blossomparent[iblossoms[-1]])
+            while blossomparent[jblossoms[-1]] is not None:
+                jblossoms.append(blossomparent[jblossoms[-1]])
+            iblossoms.reverse()
+            jblossoms.reverse()
+            for bi, bj in zip(iblossoms, jblossoms):
+                if bi != bj:
+                    break
+                s += 2 * blossomdual[bi]
+            assert s >= 0
+            if mate.get(i) == j or mate.get(j) == i:
+                assert mate[i] == j and mate[j] == i
+                assert s == 0
+        # 2. all single vertices have zero dual value;
+        for v in gnodes:
+            assert (v in mate) or dualvar[v] + vdualoffset == 0
+        # 3. all blossoms with positive dual value are full.
+        for b in blossomdual:
+            if blossomdual[b] > 0:
+                assert len(b.edges) % 2 == 1
+                for i, j in b.edges[1::2]:
+                    assert mate[i] == j and mate[j] == i
+        # Ok.
+
+    # Main loop: continue until no further improvement is possible.
+    while 1:
+        # Each iteration of this loop is a "stage".
+        # A stage finds an augmenting path and uses that to improve
+        # the matching.
+
+        # Remove labels from top-level blossoms/vertices.
+        label.clear()
+        labeledge.clear()
+
+        # Forget all about least-slack edges.
+        bestedge.clear()
+        for b in blossomdual:
+            b.mybestedges = None
+
+        # Loss of labeling means that we can not be sure that currently
+        # allowable edges remain allowable throughout this stage.
+        allowedge.clear()
+
+        # Make queue empty.
+        queue[:] = []
+
+        # Label single blossoms/vertices with S and put them in the queue.
+        for v in gnodes:
+            if (v not in mate) and label.get(inblossom[v]) is None:
+                assignLabel(v, 1, None)
+
+        # Loop until we succeed in augmenting the matching.
+        augmented = 0
+        while 1:
+            # Each iteration of this loop is a "substage".
+            # A substage tries to find an augmenting path;
+            # if found, the path is used to improve the matching and
+            # the stage ends. If there is no augmenting path, the
+            # primal-dual method is used to pump some slack out of
+            # the dual variables.
+
+            # Continue labeling until all vertices which are reachable
+            # through an alternating path have got a label.
+            while queue and not augmented:
+                # Take an S vertex from the queue.
+                v = queue.pop()
+                assert label[inblossom[v]] == 1
+
+                # Scan its neighbours:
+                for w in G.neighbors(v):
+                    if w == v:
+                        continue  # ignore self-loops
+                    # w is a neighbour to v
+                    bv = inblossom[v]
+                    bw = inblossom[w]
+                    if bv == bw:
+                        # this edge is internal to a blossom; ignore it
+                        continue
+                    if (v, w) not in allowedge:
+                        kslack = slack(v, w)
+                        if kslack <= 0:
+                            # edge k has zero slack => it is allowable
+                            allowedge[(v, w)] = allowedge[(w, v)] = True
+                    if (v, w) in allowedge:
+                        if label.get(bw) is None:
+                            # (C1) w is a free vertex;
+                            # label w with T and label its mate with S (R12).
+                            assignLabel(w, 2, v)
+                        elif label.get(bw) == 1:
+                            # (C2) w is an S-vertex (not in the same blossom);
+                            # follow back-links to discover either an
+                            # augmenting path or a new blossom.
+                            base = scanBlossom(v, w)
+                            if base is not NoNode:
+                                # Found a new blossom; add it to the blossom
+                                # bookkeeping and turn it into an S-blossom.
+                                addBlossom(base, v, w)
+                            else:
+                                # Found an augmenting path; augment the
+                                # matching and end this stage.
+                                augmentMatching(v, w)
+                                augmented = 1
+                                break
+                        elif label.get(w) is None:
+                            # w is inside a T-blossom, but w itself has not
+                            # yet been reached from outside the blossom;
+                            # mark it as reached (we need this to relabel
+                            # during T-blossom expansion).
+                            assert label[bw] == 2
+                            label[w] = 2
+                            labeledge[w] = (v, w)
+                    elif label.get(bw) == 1:
+                        # keep track of the least-slack non-allowable edge to
+                        # a different S-blossom.
+                        if bestedge.get(bv) is None or kslack < slack(*bestedge[bv]):
+                            bestedge[bv] = (v, w)
+                    elif label.get(w) is None:
+                        # w is a free vertex (or an unreached vertex inside
+                        # a T-blossom) but we can not reach it yet;
+                        # keep track of the least-slack edge that reaches w.
+                        if bestedge.get(w) is None or kslack < slack(*bestedge[w]):
+                            bestedge[w] = (v, w)
+
+            if augmented:
+                break
+
+            # There is no augmenting path under these constraints;
+            # compute delta and reduce slack in the optimization problem.
+            # (Note that our vertex dual variables, edge slacks and delta's
+            # are pre-multiplied by two.)
+            deltatype = -1
+            delta = deltaedge = deltablossom = None
+
+            # Compute delta1: the minimum value of any vertex dual.
+            if not maxcardinality:
+                deltatype = 1
+                delta = min(dualvar.values())
+
+            # Compute delta2: the minimum slack on any edge between
+            # an S-vertex and a free vertex.
+            for v in G.nodes():
+                if label.get(inblossom[v]) is None and bestedge.get(v) is not None:
+                    d = slack(*bestedge[v])
+                    if deltatype == -1 or d < delta:
+                        delta = d
+                        deltatype = 2
+                        deltaedge = bestedge[v]
+
+            # Compute delta3: half the minimum slack on any edge between
+            # a pair of S-blossoms.
+            for b in blossomparent:
+                if (
+                    blossomparent[b] is None
+                    and label.get(b) == 1
+                    and bestedge.get(b) is not None
+                ):
+                    kslack = slack(*bestedge[b])
+                    if allinteger:
+                        assert (kslack % 2) == 0
+                        d = kslack // 2
+                    else:
+                        d = kslack / 2.0
+                    if deltatype == -1 or d < delta:
+                        delta = d
+                        deltatype = 3
+                        deltaedge = bestedge[b]
+
+            # Compute delta4: minimum z variable of any T-blossom.
+            for b in blossomdual:
+                if (
+                    blossomparent[b] is None
+                    and label.get(b) == 2
+                    and (deltatype == -1 or blossomdual[b] < delta)
+                ):
+                    delta = blossomdual[b]
+                    deltatype = 4
+                    deltablossom = b
+
+            if deltatype == -1:
+                # No further improvement possible; max-cardinality optimum
+                # reached. Do a final delta update to make the optimum
+                # verifiable.
+                assert maxcardinality
+                deltatype = 1
+                delta = max(0, min(dualvar.values()))
+
+            # Update dual variables according to delta.
+            for v in gnodes:
+                if label.get(inblossom[v]) == 1:
+                    # S-vertex: 2*u = 2*u - 2*delta
+                    dualvar[v] -= delta
+                elif label.get(inblossom[v]) == 2:
+                    # T-vertex: 2*u = 2*u + 2*delta
+                    dualvar[v] += delta
+            for b in blossomdual:
+                if blossomparent[b] is None:
+                    if label.get(b) == 1:
+                        # top-level S-blossom: z = z + 2*delta
+                        blossomdual[b] += delta
+                    elif label.get(b) == 2:
+                        # top-level T-blossom: z = z - 2*delta
+                        blossomdual[b] -= delta
+
+            # Take action at the point where minimum delta occurred.
+            if deltatype == 1:
+                # No further improvement possible; optimum reached.
+                break
+            elif deltatype == 2:
+                # Use the least-slack edge to continue the search.
+                (v, w) = deltaedge
+                assert label[inblossom[v]] == 1
+                allowedge[(v, w)] = allowedge[(w, v)] = True
+                queue.append(v)
+            elif deltatype == 3:
+                # Use the least-slack edge to continue the search.
+                (v, w) = deltaedge
+                allowedge[(v, w)] = allowedge[(w, v)] = True
+                assert label[inblossom[v]] == 1
+                queue.append(v)
+            elif deltatype == 4:
+                # Expand the least-z blossom.
+                expandBlossom(deltablossom, False)
+
+            # End of a this substage.
+
+        # Paranoia check that the matching is symmetric.
+        for v in mate:
+            assert mate[mate[v]] == v
+
+        # Stop when no more augmenting path can be found.
+        if not augmented:
+            break
+
+        # End of a stage; expand all S-blossoms which have zero dual.
+        for b in list(blossomdual.keys()):
+            if b not in blossomdual:
+                continue  # already expanded
+            if blossomparent[b] is None and label.get(b) == 1 and blossomdual[b] == 0:
+                expandBlossom(b, True)
+
+    # Verify that we reached the optimum solution (only for integer weights).
+    if allinteger:
+        verifyOptimum()
+
+    return matching_dict_to_set(mate)

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/planarity.py

@@ -0,0 +1,1179 @@
+from collections import defaultdict
+
+import networkx as nx
+
+__all__ = ["check_planarity", "is_planar", "PlanarEmbedding"]
+
+
+@nx._dispatch
+def is_planar(G):
+    """Returns True if and only if `G` is planar.
+
+    A graph is *planar* iff it can be drawn in a plane without
+    any edge intersections.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    Returns
+    -------
+    bool
+       Whether the graph is planar.
+
+    Examples
+    --------
+    >>> G = nx.Graph([(0, 1), (0, 2)])
+    >>> nx.is_planar(G)
+    True
+    >>> nx.is_planar(nx.complete_graph(5))
+    False
+
+    See Also
+    --------
+    check_planarity :
+        Check if graph is planar *and* return a `PlanarEmbedding` instance if True.
+    """
+
+    return check_planarity(G, counterexample=False)[0]
+
+
+@nx._dispatch
+def check_planarity(G, counterexample=False):
+    """Check if a graph is planar and return a counterexample or an embedding.
+
+    A graph is planar iff it can be drawn in a plane without
+    any edge intersections.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+    counterexample : bool
+        A Kuratowski subgraph (to proof non planarity) is only returned if set
+        to true.
+
+    Returns
+    -------
+    (is_planar, certificate) : (bool, NetworkX graph) tuple
+        is_planar is true if the graph is planar.
+        If the graph is planar `certificate` is a PlanarEmbedding
+        otherwise it is a Kuratowski subgraph.
+
+    Examples
+    --------
+    >>> G = nx.Graph([(0, 1), (0, 2)])
+    >>> is_planar, P = nx.check_planarity(G)
+    >>> print(is_planar)
+    True
+
+    When `G` is planar, a `PlanarEmbedding` instance is returned:
+
+    >>> P.get_data()
+    {0: [1, 2], 1: [0], 2: [0]}
+
+    Notes
+    -----
+    A (combinatorial) embedding consists of cyclic orderings of the incident
+    edges at each vertex. Given such an embedding there are multiple approaches
+    discussed in literature to drawing the graph (subject to various
+    constraints, e.g. integer coordinates), see e.g. [2].
+
+    The planarity check algorithm and extraction of the combinatorial embedding
+    is based on the Left-Right Planarity Test [1].
+
+    A counterexample is only generated if the corresponding parameter is set,
+    because the complexity of the counterexample generation is higher.
+
+    See also
+    --------
+    is_planar :
+        Check for planarity without creating a `PlanarEmbedding` or counterexample.
+
+    References
+    ----------
+    .. [1] Ulrik Brandes:
+        The Left-Right Planarity Test
+        2009
+        http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.217.9208
+    .. [2] Takao Nishizeki, Md Saidur Rahman:
+        Planar graph drawing
+        Lecture Notes Series on Computing: Volume 12
+        2004
+    """
+
+    planarity_state = LRPlanarity(G)
+    embedding = planarity_state.lr_planarity()
+    if embedding is None:
+        # graph is not planar
+        if counterexample:
+            return False, get_counterexample(G)
+        else:
+            return False, None
+    else:
+        # graph is planar
+        return True, embedding
+
+
+@nx._dispatch
+def check_planarity_recursive(G, counterexample=False):
+    """Recursive version of :meth:`check_planarity`."""
+    planarity_state = LRPlanarity(G)
+    embedding = planarity_state.lr_planarity_recursive()
+    if embedding is None:
+        # graph is not planar
+        if counterexample:
+            return False, get_counterexample_recursive(G)
+        else:
+            return False, None
+    else:
+        # graph is planar
+        return True, embedding
+
+
+@nx._dispatch
+def get_counterexample(G):
+    """Obtains a Kuratowski subgraph.
+
+    Raises nx.NetworkXException if G is planar.
+
+    The function removes edges such that the graph is still not planar.
+    At some point the removal of any edge would make the graph planar.
+    This subgraph must be a Kuratowski subgraph.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    Returns
+    -------
+    subgraph : NetworkX graph
+        A Kuratowski subgraph that proves that G is not planar.
+
+    """
+    # copy graph
+    G = nx.Graph(G)
+
+    if check_planarity(G)[0]:
+        raise nx.NetworkXException("G is planar - no counter example.")
+
+    # find Kuratowski subgraph
+    subgraph = nx.Graph()
+    for u in G:
+        nbrs = list(G[u])
+        for v in nbrs:
+            G.remove_edge(u, v)
+            if check_planarity(G)[0]:
+                G.add_edge(u, v)
+                subgraph.add_edge(u, v)
+
+    return subgraph
+
+
+@nx._dispatch
+def get_counterexample_recursive(G):
+    """Recursive version of :meth:`get_counterexample`."""
+
+    # copy graph
+    G = nx.Graph(G)
+
+    if check_planarity_recursive(G)[0]:
+        raise nx.NetworkXException("G is planar - no counter example.")
+
+    # find Kuratowski subgraph
+    subgraph = nx.Graph()
+    for u in G:
+        nbrs = list(G[u])
+        for v in nbrs:
+            G.remove_edge(u, v)
+            if check_planarity_recursive(G)[0]:
+                G.add_edge(u, v)
+                subgraph.add_edge(u, v)
+
+    return subgraph
+
+
+class Interval:
+    """Represents a set of return edges.
+
+    All return edges in an interval induce a same constraint on the contained
+    edges, which means that all edges must either have a left orientation or
+    all edges must have a right orientation.
+    """
+
+    def __init__(self, low=None, high=None):
+        self.low = low
+        self.high = high
+
+    def empty(self):
+        """Check if the interval is empty"""
+        return self.low is None and self.high is None
+
+    def copy(self):
+        """Returns a copy of this interval"""
+        return Interval(self.low, self.high)
+
+    def conflicting(self, b, planarity_state):
+        """Returns True if interval I conflicts with edge b"""
+        return (
+            not self.empty()
+            and planarity_state.lowpt[self.high] > planarity_state.lowpt[b]
+        )
+
+
+class ConflictPair:
+    """Represents a different constraint between two intervals.
+
+    The edges in the left interval must have a different orientation than
+    the one in the right interval.
+    """
+
+    def __init__(self, left=Interval(), right=Interval()):
+        self.left = left
+        self.right = right
+
+    def swap(self):
+        """Swap left and right intervals"""
+        temp = self.left
+        self.left = self.right
+        self.right = temp
+
+    def lowest(self, planarity_state):
+        """Returns the lowest lowpoint of a conflict pair"""
+        if self.left.empty():
+            return planarity_state.lowpt[self.right.low]
+        if self.right.empty():
+            return planarity_state.lowpt[self.left.low]
+        return min(
+            planarity_state.lowpt[self.left.low], planarity_state.lowpt[self.right.low]
+        )
+
+
+def top_of_stack(l):
+    """Returns the element on top of the stack."""
+    if not l:
+        return None
+    return l[-1]
+
+
+class LRPlanarity:
+    """A class to maintain the state during planarity check."""
+
+    __slots__ = [
+        "G",
+        "roots",
+        "height",
+        "lowpt",
+        "lowpt2",
+        "nesting_depth",
+        "parent_edge",
+        "DG",
+        "adjs",
+        "ordered_adjs",
+        "ref",
+        "side",
+        "S",
+        "stack_bottom",
+        "lowpt_edge",
+        "left_ref",
+        "right_ref",
+        "embedding",
+    ]
+
+    def __init__(self, G):
+        # copy G without adding self-loops
+        self.G = nx.Graph()
+        self.G.add_nodes_from(G.nodes)
+        for e in G.edges:
+            if e[0] != e[1]:
+                self.G.add_edge(e[0], e[1])
+
+        self.roots = []
+
+        # distance from tree root
+        self.height = defaultdict(lambda: None)
+
+        self.lowpt = {}  # height of lowest return point of an edge
+        self.lowpt2 = {}  # height of second lowest return point
+        self.nesting_depth = {}  # for nesting order
+
+        # None -> missing edge
+        self.parent_edge = defaultdict(lambda: None)
+
+        # oriented DFS graph
+        self.DG = nx.DiGraph()
+        self.DG.add_nodes_from(G.nodes)
+
+        self.adjs = {}
+        self.ordered_adjs = {}
+
+        self.ref = defaultdict(lambda: None)
+        self.side = defaultdict(lambda: 1)
+
+        # stack of conflict pairs
+        self.S = []
+        self.stack_bottom = {}
+        self.lowpt_edge = {}
+
+        self.left_ref = {}
+        self.right_ref = {}
+
+        self.embedding = PlanarEmbedding()
+
+    def lr_planarity(self):
+        """Execute the LR planarity test.
+
+        Returns
+        -------
+        embedding : dict
+            If the graph is planar an embedding is returned. Otherwise None.
+        """
+        if self.G.order() > 2 and self.G.size() > 3 * self.G.order() - 6:
+            # graph is not planar
+            return None
+
+        # make adjacency lists for dfs
+        for v in self.G:
+            self.adjs[v] = list(self.G[v])
+
+        # orientation of the graph by depth first search traversal
+        for v in self.G:
+            if self.height[v] is None:
+                self.height[v] = 0
+                self.roots.append(v)
+                self.dfs_orientation(v)
+
+        # Free no longer used variables
+        self.G = None
+        self.lowpt2 = None
+        self.adjs = None
+
+        # testing
+        for v in self.DG:  # sort the adjacency lists by nesting depth
+            # note: this sorting leads to non linear time
+            self.ordered_adjs[v] = sorted(
+                self.DG[v], key=lambda x: self.nesting_depth[(v, x)]
+            )
+        for v in self.roots:
+            if not self.dfs_testing(v):
+                return None
+
+        # Free no longer used variables
+        self.height = None
+        self.lowpt = None
+        self.S = None
+        self.stack_bottom = None
+        self.lowpt_edge = None
+
+        for e in self.DG.edges:
+            self.nesting_depth[e] = self.sign(e) * self.nesting_depth[e]
+
+        self.embedding.add_nodes_from(self.DG.nodes)
+        for v in self.DG:
+            # sort the adjacency lists again
+            self.ordered_adjs[v] = sorted(
+                self.DG[v], key=lambda x: self.nesting_depth[(v, x)]
+            )
+            # initialize the embedding
+            previous_node = None
+            for w in self.ordered_adjs[v]:
+                self.embedding.add_half_edge_cw(v, w, previous_node)
+                previous_node = w
+
+        # Free no longer used variables
+        self.DG = None
+        self.nesting_depth = None
+        self.ref = None
+
+        # compute the complete embedding
+        for v in self.roots:
+            self.dfs_embedding(v)
+
+        # Free no longer used variables
+        self.roots = None
+        self.parent_edge = None
+        self.ordered_adjs = None
+        self.left_ref = None
+        self.right_ref = None
+        self.side = None
+
+        return self.embedding
+
+    def lr_planarity_recursive(self):
+        """Recursive version of :meth:`lr_planarity`."""
+        if self.G.order() > 2 and self.G.size() > 3 * self.G.order() - 6:
+            # graph is not planar
+            return None
+
+        # orientation of the graph by depth first search traversal
+        for v in self.G:
+            if self.height[v] is None:
+                self.height[v] = 0
+                self.roots.append(v)
+                self.dfs_orientation_recursive(v)
+
+        # Free no longer used variable
+        self.G = None
+
+        # testing
+        for v in self.DG:  # sort the adjacency lists by nesting depth
+            # note: this sorting leads to non linear time
+            self.ordered_adjs[v] = sorted(
+                self.DG[v], key=lambda x: self.nesting_depth[(v, x)]
+            )
+        for v in self.roots:
+            if not self.dfs_testing_recursive(v):
+                return None
+
+        for e in self.DG.edges:
+            self.nesting_depth[e] = self.sign_recursive(e) * self.nesting_depth[e]
+
+        self.embedding.add_nodes_from(self.DG.nodes)
+        for v in self.DG:
+            # sort the adjacency lists again
+            self.ordered_adjs[v] = sorted(
+                self.DG[v], key=lambda x: self.nesting_depth[(v, x)]
+            )
+            # initialize the embedding
+            previous_node = None
+            for w in self.ordered_adjs[v]:
+                self.embedding.add_half_edge_cw(v, w, previous_node)
+                previous_node = w
+
+        # compute the complete embedding
+        for v in self.roots:
+            self.dfs_embedding_recursive(v)
+
+        return self.embedding
+
+    def dfs_orientation(self, v):
+        """Orient the graph by DFS, compute lowpoints and nesting order."""
+        # the recursion stack
+        dfs_stack = [v]
+        # index of next edge to handle in adjacency list of each node
+        ind = defaultdict(lambda: 0)
+        # boolean to indicate whether to skip the initial work for an edge
+        skip_init = defaultdict(lambda: False)
+
+        while dfs_stack:
+            v = dfs_stack.pop()
+            e = self.parent_edge[v]
+
+            for w in self.adjs[v][ind[v] :]:
+                vw = (v, w)
+
+                if not skip_init[vw]:
+                    if (v, w) in self.DG.edges or (w, v) in self.DG.edges:
+                        ind[v] += 1
+                        continue  # the edge was already oriented
+
+                    self.DG.add_edge(v, w)  # orient the edge
+
+                    self.lowpt[vw] = self.height[v]
+                    self.lowpt2[vw] = self.height[v]
+                    if self.height[w] is None:  # (v, w) is a tree edge
+                        self.parent_edge[w] = vw
+                        self.height[w] = self.height[v] + 1
+
+                        dfs_stack.append(v)  # revisit v after finishing w
+                        dfs_stack.append(w)  # visit w next
+                        skip_init[vw] = True  # don't redo this block
+                        break  # handle next node in dfs_stack (i.e. w)
+                    else:  # (v, w) is a back edge
+                        self.lowpt[vw] = self.height[w]
+
+                # determine nesting graph
+                self.nesting_depth[vw] = 2 * self.lowpt[vw]
+                if self.lowpt2[vw] < self.height[v]:  # chordal
+                    self.nesting_depth[vw] += 1
+
+                # update lowpoints of parent edge e
+                if e is not None:
+                    if self.lowpt[vw] < self.lowpt[e]:
+                        self.lowpt2[e] = min(self.lowpt[e], self.lowpt2[vw])
+                        self.lowpt[e] = self.lowpt[vw]
+                    elif self.lowpt[vw] > self.lowpt[e]:
+                        self.lowpt2[e] = min(self.lowpt2[e], self.lowpt[vw])
+                    else:
+                        self.lowpt2[e] = min(self.lowpt2[e], self.lowpt2[vw])
+
+                ind[v] += 1
+
+    def dfs_orientation_recursive(self, v):
+        """Recursive version of :meth:`dfs_orientation`."""
+        e = self.parent_edge[v]
+        for w in self.G[v]:
+            if (v, w) in self.DG.edges or (w, v) in self.DG.edges:
+                continue  # the edge was already oriented
+            vw = (v, w)
+            self.DG.add_edge(v, w)  # orient the edge
+
+            self.lowpt[vw] = self.height[v]
+            self.lowpt2[vw] = self.height[v]
+            if self.height[w] is None:  # (v, w) is a tree edge
+                self.parent_edge[w] = vw
+                self.height[w] = self.height[v] + 1
+                self.dfs_orientation_recursive(w)
+            else:  # (v, w) is a back edge
+                self.lowpt[vw] = self.height[w]
+
+            # determine nesting graph
+            self.nesting_depth[vw] = 2 * self.lowpt[vw]
+            if self.lowpt2[vw] < self.height[v]:  # chordal
+                self.nesting_depth[vw] += 1
+
+            # update lowpoints of parent edge e
+            if e is not None:
+                if self.lowpt[vw] < self.lowpt[e]:
+                    self.lowpt2[e] = min(self.lowpt[e], self.lowpt2[vw])
+                    self.lowpt[e] = self.lowpt[vw]
+                elif self.lowpt[vw] > self.lowpt[e]:
+                    self.lowpt2[e] = min(self.lowpt2[e], self.lowpt[vw])
+                else:
+                    self.lowpt2[e] = min(self.lowpt2[e], self.lowpt2[vw])
+
+    def dfs_testing(self, v):
+        """Test for LR partition."""
+        # the recursion stack
+        dfs_stack = [v]
+        # index of next edge to handle in adjacency list of each node
+        ind = defaultdict(lambda: 0)
+        # boolean to indicate whether to skip the initial work for an edge
+        skip_init = defaultdict(lambda: False)
+
+        while dfs_stack:
+            v = dfs_stack.pop()
+            e = self.parent_edge[v]
+            # to indicate whether to skip the final block after the for loop
+            skip_final = False
+
+            for w in self.ordered_adjs[v][ind[v] :]:
+                ei = (v, w)
+
+                if not skip_init[ei]:
+                    self.stack_bottom[ei] = top_of_stack(self.S)
+
+                    if ei == self.parent_edge[w]:  # tree edge
+                        dfs_stack.append(v)  # revisit v after finishing w
+                        dfs_stack.append(w)  # visit w next
+                        skip_init[ei] = True  # don't redo this block
+                        skip_final = True  # skip final work after breaking
+                        break  # handle next node in dfs_stack (i.e. w)
+                    else:  # back edge
+                        self.lowpt_edge[ei] = ei
+                        self.S.append(ConflictPair(right=Interval(ei, ei)))
+
+                # integrate new return edges
+                if self.lowpt[ei] < self.height[v]:
+                    if w == self.ordered_adjs[v][0]:  # e_i has return edge
+                        self.lowpt_edge[e] = self.lowpt_edge[ei]
+                    else:  # add constraints of e_i
+                        if not self.add_constraints(ei, e):
+                            # graph is not planar
+                            return False
+
+                ind[v] += 1
+
+            if not skip_final:
+                # remove back edges returning to parent
+                if e is not None:  # v isn't root
+                    self.remove_back_edges(e)
+
+        return True
+
+    def dfs_testing_recursive(self, v):
+        """Recursive version of :meth:`dfs_testing`."""
+        e = self.parent_edge[v]
+        for w in self.ordered_adjs[v]:
+            ei = (v, w)
+            self.stack_bottom[ei] = top_of_stack(self.S)
+            if ei == self.parent_edge[w]:  # tree edge
+                if not self.dfs_testing_recursive(w):
+                    return False
+            else:  # back edge
+                self.lowpt_edge[ei] = ei
+                self.S.append(ConflictPair(right=Interval(ei, ei)))
+
+            # integrate new return edges
+            if self.lowpt[ei] < self.height[v]:
+                if w == self.ordered_adjs[v][0]:  # e_i has return edge
+                    self.lowpt_edge[e] = self.lowpt_edge[ei]
+                else:  # add constraints of e_i
+                    if not self.add_constraints(ei, e):
+                        # graph is not planar
+                        return False
+
+        # remove back edges returning to parent
+        if e is not None:  # v isn't root
+            self.remove_back_edges(e)
+        return True
+
+    def add_constraints(self, ei, e):
+        P = ConflictPair()
+        # merge return edges of e_i into P.right
+        while True:
+            Q = self.S.pop()
+            if not Q.left.empty():
+                Q.swap()
+            if not Q.left.empty():  # not planar
+                return False
+            if self.lowpt[Q.right.low] > self.lowpt[e]:
+                # merge intervals
+                if P.right.empty():  # topmost interval
+                    P.right = Q.right.copy()
+                else:
+                    self.ref[P.right.low] = Q.right.high
+                P.right.low = Q.right.low
+            else:  # align
+                self.ref[Q.right.low] = self.lowpt_edge[e]
+            if top_of_stack(self.S) == self.stack_bottom[ei]:
+                break
+        # merge conflicting return edges of e_1,...,e_i-1 into P.L
+        while top_of_stack(self.S).left.conflicting(ei, self) or top_of_stack(
+            self.S
+        ).right.conflicting(ei, self):
+            Q = self.S.pop()
+            if Q.right.conflicting(ei, self):
+                Q.swap()
+            if Q.right.conflicting(ei, self):  # not planar
+                return False
+            # merge interval below lowpt(e_i) into P.R
+            self.ref[P.right.low] = Q.right.high
+            if Q.right.low is not None:
+                P.right.low = Q.right.low
+
+            if P.left.empty():  # topmost interval
+                P.left = Q.left.copy()
+            else:
+                self.ref[P.left.low] = Q.left.high
+            P.left.low = Q.left.low
+
+        if not (P.left.empty() and P.right.empty()):
+            self.S.append(P)
+        return True
+
+    def remove_back_edges(self, e):
+        u = e[0]
+        # trim back edges ending at parent u
+        # drop entire conflict pairs
+        while self.S and top_of_stack(self.S).lowest(self) == self.height[u]:
+            P = self.S.pop()
+            if P.left.low is not None:
+                self.side[P.left.low] = -1
+
+        if self.S:  # one more conflict pair to consider
+            P = self.S.pop()
+            # trim left interval
+            while P.left.high is not None and P.left.high[1] == u:
+                P.left.high = self.ref[P.left.high]
+            if P.left.high is None and P.left.low is not None:
+                # just emptied
+                self.ref[P.left.low] = P.right.low
+                self.side[P.left.low] = -1
+                P.left.low = None
+            # trim right interval
+            while P.right.high is not None and P.right.high[1] == u:
+                P.right.high = self.ref[P.right.high]
+            if P.right.high is None and P.right.low is not None:
+                # just emptied
+                self.ref[P.right.low] = P.left.low
+                self.side[P.right.low] = -1
+                P.right.low = None
+            self.S.append(P)
+
+        # side of e is side of a highest return edge
+        if self.lowpt[e] < self.height[u]:  # e has return edge
+            hl = top_of_stack(self.S).left.high
+            hr = top_of_stack(self.S).right.high
+
+            if hl is not None and (hr is None or self.lowpt[hl] > self.lowpt[hr]):
+                self.ref[e] = hl
+            else:
+                self.ref[e] = hr
+
+    def dfs_embedding(self, v):
+        """Completes the embedding."""
+        # the recursion stack
+        dfs_stack = [v]
+        # index of next edge to handle in adjacency list of each node
+        ind = defaultdict(lambda: 0)
+
+        while dfs_stack:
+            v = dfs_stack.pop()
+
+            for w in self.ordered_adjs[v][ind[v] :]:
+                ind[v] += 1
+                ei = (v, w)
+
+                if ei == self.parent_edge[w]:  # tree edge
+                    self.embedding.add_half_edge_first(w, v)
+                    self.left_ref[v] = w
+                    self.right_ref[v] = w
+
+                    dfs_stack.append(v)  # revisit v after finishing w
+                    dfs_stack.append(w)  # visit w next
+                    break  # handle next node in dfs_stack (i.e. w)
+                else:  # back edge
+                    if self.side[ei] == 1:
+                        self.embedding.add_half_edge_cw(w, v, self.right_ref[w])
+                    else:
+                        self.embedding.add_half_edge_ccw(w, v, self.left_ref[w])
+                        self.left_ref[w] = v
+
+    def dfs_embedding_recursive(self, v):
+        """Recursive version of :meth:`dfs_embedding`."""
+        for w in self.ordered_adjs[v]:
+            ei = (v, w)
+            if ei == self.parent_edge[w]:  # tree edge
+                self.embedding.add_half_edge_first(w, v)
+                self.left_ref[v] = w
+                self.right_ref[v] = w
+                self.dfs_embedding_recursive(w)
+            else:  # back edge
+                if self.side[ei] == 1:
+                    # place v directly after right_ref[w] in embed. list of w
+                    self.embedding.add_half_edge_cw(w, v, self.right_ref[w])
+                else:
+                    # place v directly before left_ref[w] in embed. list of w
+                    self.embedding.add_half_edge_ccw(w, v, self.left_ref[w])
+                    self.left_ref[w] = v
+
+    def sign(self, e):
+        """Resolve the relative side of an edge to the absolute side."""
+        # the recursion stack
+        dfs_stack = [e]
+        # dict to remember reference edges
+        old_ref = defaultdict(lambda: None)
+
+        while dfs_stack:
+            e = dfs_stack.pop()
+
+            if self.ref[e] is not None:
+                dfs_stack.append(e)  # revisit e after finishing self.ref[e]
+                dfs_stack.append(self.ref[e])  # visit self.ref[e] next
+                old_ref[e] = self.ref[e]  # remember value of self.ref[e]
+                self.ref[e] = None
+            else:
+                self.side[e] *= self.side[old_ref[e]]
+
+        return self.side[e]
+
+    def sign_recursive(self, e):
+        """Recursive version of :meth:`sign`."""
+        if self.ref[e] is not None:
+            self.side[e] = self.side[e] * self.sign_recursive(self.ref[e])
+            self.ref[e] = None
+        return self.side[e]
+
+
+class PlanarEmbedding(nx.DiGraph):
+    """Represents a planar graph with its planar embedding.
+
+    The planar embedding is given by a `combinatorial embedding
+    <https://en.wikipedia.org/wiki/Graph_embedding#Combinatorial_embedding>`_.
+
+    .. note:: `check_planarity` is the preferred way to check if a graph is planar.
+
+    **Neighbor ordering:**
+
+    In comparison to a usual graph structure, the embedding also stores the
+    order of all neighbors for every vertex.
+    The order of the neighbors can be given in clockwise (cw) direction or
+    counterclockwise (ccw) direction. This order is stored as edge attributes
+    in the underlying directed graph. For the edge (u, v) the edge attribute
+    'cw' is set to the neighbor of u that follows immediately after v in
+    clockwise direction.
+
+    In order for a PlanarEmbedding to be valid it must fulfill multiple
+    conditions. It is possible to check if these conditions are fulfilled with
+    the method :meth:`check_structure`.
+    The conditions are:
+
+    * Edges must go in both directions (because the edge attributes differ)
+    * Every edge must have a 'cw' and 'ccw' attribute which corresponds to a
+      correct planar embedding.
+    * A node with non zero degree must have a node attribute 'first_nbr'.
+
+    As long as a PlanarEmbedding is invalid only the following methods should
+    be called:
+
+    * :meth:`add_half_edge_ccw`
+    * :meth:`add_half_edge_cw`
+    * :meth:`connect_components`
+    * :meth:`add_half_edge_first`
+
+    Even though the graph is a subclass of nx.DiGraph, it can still be used
+    for algorithms that require undirected graphs, because the method
+    :meth:`is_directed` is overridden. This is possible, because a valid
+    PlanarGraph must have edges in both directions.
+
+    **Half edges:**
+
+    In methods like `add_half_edge_ccw` the term "half-edge" is used, which is
+    a term that is used in `doubly connected edge lists
+    <https://en.wikipedia.org/wiki/Doubly_connected_edge_list>`_. It is used
+    to emphasize that the edge is only in one direction and there exists
+    another half-edge in the opposite direction.
+    While conventional edges always have two faces (including outer face) next
+    to them, it is possible to assign each half-edge *exactly one* face.
+    For a half-edge (u, v) that is orientated such that u is below v then the
+    face that belongs to (u, v) is to the right of this half-edge.
+
+    See Also
+    --------
+    is_planar :
+        Preferred way to check if an existing graph is planar.
+
+    check_planarity :
+        A convenient way to create a `PlanarEmbedding`. If not planar,
+        it returns a subgraph that shows this.
+
+    Examples
+    --------
+
+    Create an embedding of a star graph (compare `nx.star_graph(3)`):
+
+    >>> G = nx.PlanarEmbedding()
+    >>> G.add_half_edge_cw(0, 1, None)
+    >>> G.add_half_edge_cw(0, 2, 1)
+    >>> G.add_half_edge_cw(0, 3, 2)
+    >>> G.add_half_edge_cw(1, 0, None)
+    >>> G.add_half_edge_cw(2, 0, None)
+    >>> G.add_half_edge_cw(3, 0, None)
+
+    Alternatively the same embedding can also be defined in counterclockwise
+    orientation. The following results in exactly the same PlanarEmbedding:
+
+    >>> G = nx.PlanarEmbedding()
+    >>> G.add_half_edge_ccw(0, 1, None)
+    >>> G.add_half_edge_ccw(0, 3, 1)
+    >>> G.add_half_edge_ccw(0, 2, 3)
+    >>> G.add_half_edge_ccw(1, 0, None)
+    >>> G.add_half_edge_ccw(2, 0, None)
+    >>> G.add_half_edge_ccw(3, 0, None)
+
+    After creating a graph, it is possible to validate that the PlanarEmbedding
+    object is correct:
+
+    >>> G.check_structure()
+
+    """
+
+    def get_data(self):
+        """Converts the adjacency structure into a better readable structure.
+
+        Returns
+        -------
+        embedding : dict
+            A dict mapping all nodes to a list of neighbors sorted in
+            clockwise order.
+
+        See Also
+        --------
+        set_data
+
+        """
+        embedding = {}
+        for v in self:
+            embedding[v] = list(self.neighbors_cw_order(v))
+        return embedding
+
+    def set_data(self, data):
+        """Inserts edges according to given sorted neighbor list.
+
+        The input format is the same as the output format of get_data().
+
+        Parameters
+        ----------
+        data : dict
+            A dict mapping all nodes to a list of neighbors sorted in
+            clockwise order.
+
+        See Also
+        --------
+        get_data
+
+        """
+        for v in data:
+            for w in reversed(data[v]):
+                self.add_half_edge_first(v, w)
+
+    def neighbors_cw_order(self, v):
+        """Generator for the neighbors of v in clockwise order.
+
+        Parameters
+        ----------
+        v : node
+
+        Yields
+        ------
+        node
+
+        """
+        if len(self[v]) == 0:
+            # v has no neighbors
+            return
+        start_node = self.nodes[v]["first_nbr"]
+        yield start_node
+        current_node = self[v][start_node]["cw"]
+        while start_node != current_node:
+            yield current_node
+            current_node = self[v][current_node]["cw"]
+
+    def check_structure(self):
+        """Runs without exceptions if this object is valid.
+
+        Checks that the following properties are fulfilled:
+
+        * Edges go in both directions (because the edge attributes differ).
+        * Every edge has a 'cw' and 'ccw' attribute which corresponds to a
+          correct planar embedding.
+        * A node with a degree larger than 0 has a node attribute 'first_nbr'.
+
+        Running this method verifies that the underlying Graph must be planar.
+
+        Raises
+        ------
+        NetworkXException
+            This exception is raised with a short explanation if the
+            PlanarEmbedding is invalid.
+        """
+        # Check fundamental structure
+        for v in self:
+            try:
+                sorted_nbrs = set(self.neighbors_cw_order(v))
+            except KeyError as err:
+                msg = f"Bad embedding. Missing orientation for a neighbor of {v}"
+                raise nx.NetworkXException(msg) from err
+
+            unsorted_nbrs = set(self[v])
+            if sorted_nbrs != unsorted_nbrs:
+                msg = "Bad embedding. Edge orientations not set correctly."
+                raise nx.NetworkXException(msg)
+            for w in self[v]:
+                # Check if opposite half-edge exists
+                if not self.has_edge(w, v):
+                    msg = "Bad embedding. Opposite half-edge is missing."
+                    raise nx.NetworkXException(msg)
+
+        # Check planarity
+        counted_half_edges = set()
+        for component in nx.connected_components(self):
+            if len(component) == 1:
+                # Don't need to check single node component
+                continue
+            num_nodes = len(component)
+            num_half_edges = 0
+            num_faces = 0
+            for v in component:
+                for w in self.neighbors_cw_order(v):
+                    num_half_edges += 1
+                    if (v, w) not in counted_half_edges:
+                        # We encountered a new face
+                        num_faces += 1
+                        # Mark all half-edges belonging to this face
+                        self.traverse_face(v, w, counted_half_edges)
+            num_edges = num_half_edges // 2  # num_half_edges is even
+            if num_nodes - num_edges + num_faces != 2:
+                # The result does not match Euler's formula
+                msg = "Bad embedding. The graph does not match Euler's formula"
+                raise nx.NetworkXException(msg)
+
+    def add_half_edge_ccw(self, start_node, end_node, reference_neighbor):
+        """Adds a half-edge from start_node to end_node.
+
+        The half-edge is added counter clockwise next to the existing half-edge
+        (start_node, reference_neighbor).
+
+        Parameters
+        ----------
+        start_node : node
+            Start node of inserted edge.
+        end_node : node
+            End node of inserted edge.
+        reference_neighbor: node
+            End node of reference edge.
+
+        Raises
+        ------
+        NetworkXException
+            If the reference_neighbor does not exist.
+
+        See Also
+        --------
+        add_half_edge_cw
+        connect_components
+        add_half_edge_first
+
+        """
+        if reference_neighbor is None:
+            # The start node has no neighbors
+            self.add_edge(start_node, end_node)  # Add edge to graph
+            self[start_node][end_node]["cw"] = end_node
+            self[start_node][end_node]["ccw"] = end_node
+            self.nodes[start_node]["first_nbr"] = end_node
+        else:
+            ccw_reference = self[start_node][reference_neighbor]["ccw"]
+            self.add_half_edge_cw(start_node, end_node, ccw_reference)
+
+            if reference_neighbor == self.nodes[start_node].get("first_nbr", None):
+                # Update first neighbor
+                self.nodes[start_node]["first_nbr"] = end_node
+
+    def add_half_edge_cw(self, start_node, end_node, reference_neighbor):
+        """Adds a half-edge from start_node to end_node.
+
+        The half-edge is added clockwise next to the existing half-edge
+        (start_node, reference_neighbor).
+
+        Parameters
+        ----------
+        start_node : node
+            Start node of inserted edge.
+        end_node : node
+            End node of inserted edge.
+        reference_neighbor: node
+            End node of reference edge.
+
+        Raises
+        ------
+        NetworkXException
+            If the reference_neighbor does not exist.
+
+        See Also
+        --------
+        add_half_edge_ccw
+        connect_components
+        add_half_edge_first
+        """
+        self.add_edge(start_node, end_node)  # Add edge to graph
+
+        if reference_neighbor is None:
+            # The start node has no neighbors
+            self[start_node][end_node]["cw"] = end_node
+            self[start_node][end_node]["ccw"] = end_node
+            self.nodes[start_node]["first_nbr"] = end_node
+            return
+
+        if reference_neighbor not in self[start_node]:
+            raise nx.NetworkXException(
+                "Cannot add edge. Reference neighbor does not exist"
+            )
+
+        # Get half-edge at the other side
+        cw_reference = self[start_node][reference_neighbor]["cw"]
+        # Alter half-edge data structures
+        self[start_node][reference_neighbor]["cw"] = end_node
+        self[start_node][end_node]["cw"] = cw_reference
+        self[start_node][cw_reference]["ccw"] = end_node
+        self[start_node][end_node]["ccw"] = reference_neighbor
+
+    def connect_components(self, v, w):
+        """Adds half-edges for (v, w) and (w, v) at some position.
+
+        This method should only be called if v and w are in different
+        components, or it might break the embedding.
+        This especially means that if `connect_components(v, w)`
+        is called it is not allowed to call `connect_components(w, v)`
+        afterwards. The neighbor orientations in both directions are
+        all set correctly after the first call.
+
+        Parameters
+        ----------
+        v : node
+        w : node
+
+        See Also
+        --------
+        add_half_edge_ccw
+        add_half_edge_cw
+        add_half_edge_first
+        """
+        self.add_half_edge_first(v, w)
+        self.add_half_edge_first(w, v)
+
+    def add_half_edge_first(self, start_node, end_node):
+        """The added half-edge is inserted at the first position in the order.
+
+        Parameters
+        ----------
+        start_node : node
+        end_node : node
+
+        See Also
+        --------
+        add_half_edge_ccw
+        add_half_edge_cw
+        connect_components
+        """
+        if start_node in self and "first_nbr" in self.nodes[start_node]:
+            reference = self.nodes[start_node]["first_nbr"]
+        else:
+            reference = None
+        self.add_half_edge_ccw(start_node, end_node, reference)
+
+    def next_face_half_edge(self, v, w):
+        """Returns the following half-edge left of a face.
+
+        Parameters
+        ----------
+        v : node
+        w : node
+
+        Returns
+        -------
+        half-edge : tuple
+        """
+        new_node = self[w][v]["ccw"]
+        return w, new_node
+
+    def traverse_face(self, v, w, mark_half_edges=None):
+        """Returns nodes on the face that belong to the half-edge (v, w).
+
+        The face that is traversed lies to the right of the half-edge (in an
+        orientation where v is below w).
+
+        Optionally it is possible to pass a set to which all encountered half
+        edges are added. Before calling this method, this set must not include
+        any half-edges that belong to the face.
+
+        Parameters
+        ----------
+        v : node
+            Start node of half-edge.
+        w : node
+            End node of half-edge.
+        mark_half_edges: set, optional
+            Set to which all encountered half-edges are added.
+
+        Returns
+        -------
+        face : list
+            A list of nodes that lie on this face.
+        """
+        if mark_half_edges is None:
+            mark_half_edges = set()
+
+        face_nodes = [v]
+        mark_half_edges.add((v, w))
+        prev_node = v
+        cur_node = w
+        # Last half-edge is (incoming_node, v)
+        incoming_node = self[v][w]["cw"]
+
+        while cur_node != v or prev_node != incoming_node:
+            face_nodes.append(cur_node)
+            prev_node, cur_node = self.next_face_half_edge(prev_node, cur_node)
+            if (prev_node, cur_node) in mark_half_edges:
+                raise nx.NetworkXException("Bad planar embedding. Impossible face.")
+            mark_half_edges.add((prev_node, cur_node))
+
+        return face_nodes
+
+    def is_directed(self):
+        """A valid PlanarEmbedding is undirected.
+
+        All reverse edges are contained, i.e. for every existing
+        half-edge (v, w) the half-edge in the opposite direction (w, v) is also
+        contained.
+        """
+        return False

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/reciprocity.py

@@ -0,0 +1,97 @@
+"""Algorithms to calculate reciprocity in a directed graph."""
+import networkx as nx
+from networkx import NetworkXError
+
+from ..utils import not_implemented_for
+
+__all__ = ["reciprocity", "overall_reciprocity"]
+
+
+@not_implemented_for("undirected", "multigraph")
+@nx._dispatch
+def reciprocity(G, nodes=None):
+    r"""Compute the reciprocity in a directed graph.
+
+    The reciprocity of a directed graph is defined as the ratio
+    of the number of edges pointing in both directions to the total
+    number of edges in the graph.
+    Formally, $r = |{(u,v) \in G|(v,u) \in G}| / |{(u,v) \in G}|$.
+
+    The reciprocity of a single node u is defined similarly,
+    it is the ratio of the number of edges in both directions to
+    the total number of edges attached to node u.
+
+    Parameters
+    ----------
+    G : graph
+       A networkx directed graph
+    nodes : container of nodes, optional (default=whole graph)
+       Compute reciprocity for nodes in this container.
+
+    Returns
+    -------
+    out : dictionary
+       Reciprocity keyed by node label.
+
+    Notes
+    -----
+    The reciprocity is not defined for isolated nodes.
+    In such cases this function will return None.
+
+    """
+    # If `nodes` is not specified, calculate the reciprocity of the graph.
+    if nodes is None:
+        return overall_reciprocity(G)
+
+    # If `nodes` represents a single node in the graph, return only its
+    # reciprocity.
+    if nodes in G:
+        reciprocity = next(_reciprocity_iter(G, nodes))[1]
+        if reciprocity is None:
+            raise NetworkXError("Not defined for isolated nodes.")
+        else:
+            return reciprocity
+
+    # Otherwise, `nodes` represents an iterable of nodes, so return a
+    # dictionary mapping node to its reciprocity.
+    return dict(_reciprocity_iter(G, nodes))
+
+
+def _reciprocity_iter(G, nodes):
+    """Return an iterator of (node, reciprocity)."""
+    n = G.nbunch_iter(nodes)
+    for node in n:
+        pred = set(G.predecessors(node))
+        succ = set(G.successors(node))
+        overlap = pred & succ
+        n_total = len(pred) + len(succ)
+
+        # Reciprocity is not defined for isolated nodes.
+        # Return None.
+        if n_total == 0:
+            yield (node, None)
+        else:
+            reciprocity = 2 * len(overlap) / n_total
+            yield (node, reciprocity)
+
+
+@not_implemented_for("undirected", "multigraph")
+@nx._dispatch
+def overall_reciprocity(G):
+    """Compute the reciprocity for the whole graph.
+
+    See the doc of reciprocity for the definition.
+
+    Parameters
+    ----------
+    G : graph
+       A networkx graph
+
+    """
+    n_all_edge = G.number_of_edges()
+    n_overlap_edge = (n_all_edge - G.to_undirected().number_of_edges()) * 2
+
+    if n_all_edge == 0:
+        raise NetworkXError("Not defined for empty graphs")
+
+    return n_overlap_edge / n_all_edge

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/regular.py

@@ -0,0 +1,212 @@
+"""Functions for computing and verifying regular graphs."""
+import networkx as nx
+from networkx.utils import not_implemented_for
+
+__all__ = ["is_regular", "is_k_regular", "k_factor"]
+
+
+@nx._dispatch
+def is_regular(G):
+    """Determines whether the graph ``G`` is a regular graph.
+
+    A regular graph is a graph where each vertex has the same degree. A
+    regular digraph is a graph where the indegree and outdegree of each
+    vertex are equal.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    Returns
+    -------
+    bool
+        Whether the given graph or digraph is regular.
+
+    Examples
+    --------
+    >>> G = nx.DiGraph([(1, 2), (2, 3), (3, 4), (4, 1)])
+    >>> nx.is_regular(G)
+    True
+
+    """
+    n1 = nx.utils.arbitrary_element(G)
+    if not G.is_directed():
+        d1 = G.degree(n1)
+        return all(d1 == d for _, d in G.degree)
+    else:
+        d_in = G.in_degree(n1)
+        in_regular = all(d_in == d for _, d in G.in_degree)
+        d_out = G.out_degree(n1)
+        out_regular = all(d_out == d for _, d in G.out_degree)
+        return in_regular and out_regular
+
+
+@not_implemented_for("directed")
+@nx._dispatch
+def is_k_regular(G, k):
+    """Determines whether the graph ``G`` is a k-regular graph.
+
+    A k-regular graph is a graph where each vertex has degree k.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    Returns
+    -------
+    bool
+        Whether the given graph is k-regular.
+
+    Examples
+    --------
+    >>> G = nx.Graph([(1, 2), (2, 3), (3, 4), (4, 1)])
+    >>> nx.is_k_regular(G, k=3)
+    False
+
+    """
+    return all(d == k for n, d in G.degree)
+
+
+@not_implemented_for("directed")
+@not_implemented_for("multigraph")
+@nx._dispatch(edge_attrs="matching_weight")
+def k_factor(G, k, matching_weight="weight"):
+    """Compute a k-factor of G
+
+    A k-factor of a graph is a spanning k-regular subgraph.
+    A spanning k-regular subgraph of G is a subgraph that contains
+    each vertex of G and a subset of the edges of G such that each
+    vertex has degree k.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+      Undirected graph
+
+    matching_weight: string, optional (default='weight')
+       Edge data key corresponding to the edge weight.
+       Used for finding the max-weighted perfect matching.
+       If key not found, uses 1 as weight.
+
+    Returns
+    -------
+    G2 : NetworkX graph
+        A k-factor of G
+
+    Examples
+    --------
+    >>> G = nx.Graph([(1, 2), (2, 3), (3, 4), (4, 1)])
+    >>> G2 = nx.k_factor(G, k=1)
+    >>> G2.edges()
+    EdgeView([(1, 2), (3, 4)])
+
+    References
+    ----------
+    .. [1] "An algorithm for computing simple k-factors.",
+       Meijer, Henk, Yurai Núñez-Rodríguez, and David Rappaport,
+       Information processing letters, 2009.
+    """
+
+    from networkx.algorithms.matching import is_perfect_matching, max_weight_matching
+
+    class LargeKGadget:
+        def __init__(self, k, degree, node, g):
+            self.original = node
+            self.g = g
+            self.k = k
+            self.degree = degree
+
+            self.outer_vertices = [(node, x) for x in range(degree)]
+            self.core_vertices = [(node, x + degree) for x in range(degree - k)]
+
+        def replace_node(self):
+            adj_view = self.g[self.original]
+            neighbors = list(adj_view.keys())
+            edge_attrs = list(adj_view.values())
+            for outer, neighbor, edge_attrs in zip(
+                self.outer_vertices, neighbors, edge_attrs
+            ):
+                self.g.add_edge(outer, neighbor, **edge_attrs)
+            for core in self.core_vertices:
+                for outer in self.outer_vertices:
+                    self.g.add_edge(core, outer)
+            self.g.remove_node(self.original)
+
+        def restore_node(self):
+            self.g.add_node(self.original)
+            for outer in self.outer_vertices:
+                adj_view = self.g[outer]
+                for neighbor, edge_attrs in list(adj_view.items()):
+                    if neighbor not in self.core_vertices:
+                        self.g.add_edge(self.original, neighbor, **edge_attrs)
+                        break
+            g.remove_nodes_from(self.outer_vertices)
+            g.remove_nodes_from(self.core_vertices)
+
+    class SmallKGadget:
+        def __init__(self, k, degree, node, g):
+            self.original = node
+            self.k = k
+            self.degree = degree
+            self.g = g
+
+            self.outer_vertices = [(node, x) for x in range(degree)]
+            self.inner_vertices = [(node, x + degree) for x in range(degree)]
+            self.core_vertices = [(node, x + 2 * degree) for x in range(k)]
+
+        def replace_node(self):
+            adj_view = self.g[self.original]
+            for outer, inner, (neighbor, edge_attrs) in zip(
+                self.outer_vertices, self.inner_vertices, list(adj_view.items())
+            ):
+                self.g.add_edge(outer, inner)
+                self.g.add_edge(outer, neighbor, **edge_attrs)
+            for core in self.core_vertices:
+                for inner in self.inner_vertices:
+                    self.g.add_edge(core, inner)
+            self.g.remove_node(self.original)
+
+        def restore_node(self):
+            self.g.add_node(self.original)
+            for outer in self.outer_vertices:
+                adj_view = self.g[outer]
+                for neighbor, edge_attrs in adj_view.items():
+                    if neighbor not in self.core_vertices:
+                        self.g.add_edge(self.original, neighbor, **edge_attrs)
+                        break
+            self.g.remove_nodes_from(self.outer_vertices)
+            self.g.remove_nodes_from(self.inner_vertices)
+            self.g.remove_nodes_from(self.core_vertices)
+
+    # Step 1
+    if any(d < k for _, d in G.degree):
+        raise nx.NetworkXUnfeasible("Graph contains a vertex with degree less than k")
+    g = G.copy()
+
+    # Step 2
+    gadgets = []
+    for node, degree in list(g.degree):
+        if k < degree / 2.0:
+            gadget = SmallKGadget(k, degree, node, g)
+        else:
+            gadget = LargeKGadget(k, degree, node, g)
+        gadget.replace_node()
+        gadgets.append(gadget)
+
+    # Step 3
+    matching = max_weight_matching(g, maxcardinality=True, weight=matching_weight)
+
+    # Step 4
+    if not is_perfect_matching(g, matching):
+        raise nx.NetworkXUnfeasible(
+            "Cannot find k-factor because no perfect matching exists"
+        )
+
+    for edge in g.edges():
+        if edge not in matching and (edge[1], edge[0]) not in matching:
+            g.remove_edge(edge[0], edge[1])
+
+    for gadget in gadgets:
+        gadget.restore_node()
+
+    return g

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/traversal/breadth_first_search.py

@@ -0,0 +1,581 @@
+"""Basic algorithms for breadth-first searching the nodes of a graph."""
+import math
+from collections import deque
+
+import networkx as nx
+
+__all__ = [
+    "bfs_edges",
+    "bfs_tree",
+    "bfs_predecessors",
+    "bfs_successors",
+    "descendants_at_distance",
+    "bfs_layers",
+    "bfs_labeled_edges",
+    "generic_bfs_edges",
+]
+
+
+@nx._dispatch
+def generic_bfs_edges(G, source, neighbors=None, depth_limit=None, sort_neighbors=None):
+    """Iterate over edges in a breadth-first search.
+
+    The breadth-first search begins at `source` and enqueues the
+    neighbors of newly visited nodes specified by the `neighbors`
+    function.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    source : node
+        Starting node for the breadth-first search; this function
+        iterates over only those edges in the component reachable from
+        this node.
+
+    neighbors : function
+        A function that takes a newly visited node of the graph as input
+        and returns an *iterator* (not just a list) of nodes that are
+        neighbors of that node with custom ordering. If not specified, this is
+        just the``G.neighbors`` method, but in general it can be any function
+        that returns an iterator over some or all of the neighbors of a
+        given node, in any order.
+
+    depth_limit : int, optional(default=len(G))
+        Specify the maximum search depth.
+
+    sort_neighbors : Callable
+
+        .. deprecated:: 3.2
+
+           The sort_neighbors parameter is deprecated and will be removed in
+           version 3.4. A custom (e.g. sorted) ordering of neighbors can be
+           specified with the `neighbors` parameter.
+
+        A function that takes the list of neighbors of a given node as input,
+        and returns an iterator over these neighbors but with a custom
+        ordering.
+
+    Yields
+    ------
+    edge
+        Edges in the breadth-first search starting from `source`.
+
+    Examples
+    --------
+    >>> G = nx.path_graph(3)
+    >>> list(nx.bfs_edges(G, 0))
+    [(0, 1), (1, 2)]
+    >>> list(nx.bfs_edges(G, source=0, depth_limit=1))
+    [(0, 1)]
+
+    Notes
+    -----
+    This implementation is from `PADS`_, which was in the public domain
+    when it was first accessed in July, 2004.  The modifications
+    to allow depth limits are based on the Wikipedia article
+    "`Depth-limited-search`_".
+
+    .. _PADS: http://www.ics.uci.edu/~eppstein/PADS/BFS.py
+    .. _Depth-limited-search: https://en.wikipedia.org/wiki/Depth-limited_search
+    """
+    if neighbors is None:
+        neighbors = G.neighbors
+    if sort_neighbors is not None:
+        import warnings
+
+        warnings.warn(
+            (
+                "The sort_neighbors parameter is deprecated and will be removed\n"
+                "in NetworkX 3.4, use the neighbors parameter instead."
+            ),
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        _neighbors = neighbors
+        neighbors = lambda node: iter(sort_neighbors(_neighbors(node)))
+    if depth_limit is None:
+        depth_limit = len(G)
+
+    seen = {source}
+    n = len(G)
+    depth = 0
+    next_parents_children = [(source, neighbors(source))]
+    while next_parents_children and depth < depth_limit:
+        this_parents_children = next_parents_children
+        next_parents_children = []
+        for parent, children in this_parents_children:
+            for child in children:
+                if child not in seen:
+                    seen.add(child)
+                    next_parents_children.append((child, neighbors(child)))
+                    yield parent, child
+            if len(seen) == n:
+                return
+        depth += 1
+
+
+@nx._dispatch
+def bfs_edges(G, source, reverse=False, depth_limit=None, sort_neighbors=None):
+    """Iterate over edges in a breadth-first-search starting at source.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    source : node
+       Specify starting node for breadth-first search; this function
+       iterates over only those edges in the component reachable from
+       this node.
+
+    reverse : bool, optional
+       If True traverse a directed graph in the reverse direction
+
+    depth_limit : int, optional(default=len(G))
+        Specify the maximum search depth
+
+    sort_neighbors : function
+        A function that takes the list of neighbors of given node as input, and
+        returns an *iterator* over these neighbors but with custom ordering.
+
+    Yields
+    ------
+    edge: 2-tuple of nodes
+       Yields edges resulting from the breadth-first search.
+
+    Examples
+    --------
+    To get the edges in a breadth-first search::
+
+        >>> G = nx.path_graph(3)
+        >>> list(nx.bfs_edges(G, 0))
+        [(0, 1), (1, 2)]
+        >>> list(nx.bfs_edges(G, source=0, depth_limit=1))
+        [(0, 1)]
+
+    To get the nodes in a breadth-first search order::
+
+        >>> G = nx.path_graph(3)
+        >>> root = 2
+        >>> edges = nx.bfs_edges(G, root)
+        >>> nodes = [root] + [v for u, v in edges]
+        >>> nodes
+        [2, 1, 0]
+
+    Notes
+    -----
+    The naming of this function is very similar to
+    :func:`~networkx.algorithms.traversal.edgebfs.edge_bfs`. The difference
+    is that ``edge_bfs`` yields edges even if they extend back to an already
+    explored node while this generator yields the edges of the tree that results
+    from a breadth-first-search (BFS) so no edges are reported if they extend
+    to already explored nodes. That means ``edge_bfs`` reports all edges while
+    ``bfs_edges`` only reports those traversed by a node-based BFS. Yet another
+    description is that ``bfs_edges`` reports the edges traversed during BFS
+    while ``edge_bfs`` reports all edges in the order they are explored.
+
+    Based on the breadth-first search implementation in PADS [1]_
+    by D. Eppstein, July 2004; with modifications to allow depth limits
+    as described in [2]_.
+
+    References
+    ----------
+    .. [1] http://www.ics.uci.edu/~eppstein/PADS/BFS.py.
+    .. [2] https://en.wikipedia.org/wiki/Depth-limited_search
+
+    See Also
+    --------
+    bfs_tree
+    :func:`~networkx.algorithms.traversal.depth_first_search.dfs_edges`
+    :func:`~networkx.algorithms.traversal.edgebfs.edge_bfs`
+
+    """
+    if reverse and G.is_directed():
+        successors = G.predecessors
+    else:
+        successors = G.neighbors
+
+    if callable(sort_neighbors):
+        yield from generic_bfs_edges(
+            G, source, lambda node: iter(sort_neighbors(successors(node))), depth_limit
+        )
+    else:
+        yield from generic_bfs_edges(G, source, successors, depth_limit)
+
+
+@nx._dispatch
+def bfs_tree(G, source, reverse=False, depth_limit=None, sort_neighbors=None):
+    """Returns an oriented tree constructed from of a breadth-first-search
+    starting at source.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    source : node
+       Specify starting node for breadth-first search
+
+    reverse : bool, optional
+       If True traverse a directed graph in the reverse direction
+
+    depth_limit : int, optional(default=len(G))
+        Specify the maximum search depth
+
+    sort_neighbors : function
+        A function that takes the list of neighbors of given node as input, and
+        returns an *iterator* over these neighbors but with custom ordering.
+
+    Returns
+    -------
+    T: NetworkX DiGraph
+       An oriented tree
+
+    Examples
+    --------
+    >>> G = nx.path_graph(3)
+    >>> list(nx.bfs_tree(G, 1).edges())
+    [(1, 0), (1, 2)]
+    >>> H = nx.Graph()
+    >>> nx.add_path(H, [0, 1, 2, 3, 4, 5, 6])
+    >>> nx.add_path(H, [2, 7, 8, 9, 10])
+    >>> sorted(list(nx.bfs_tree(H, source=3, depth_limit=3).edges()))
+    [(1, 0), (2, 1), (2, 7), (3, 2), (3, 4), (4, 5), (5, 6), (7, 8)]
+
+
+    Notes
+    -----
+    Based on http://www.ics.uci.edu/~eppstein/PADS/BFS.py
+    by D. Eppstein, July 2004. The modifications
+    to allow depth limits based on the Wikipedia article
+    "`Depth-limited-search`_".
+
+    .. _Depth-limited-search: https://en.wikipedia.org/wiki/Depth-limited_search
+
+    See Also
+    --------
+    dfs_tree
+    bfs_edges
+    edge_bfs
+    """
+    T = nx.DiGraph()
+    T.add_node(source)
+    edges_gen = bfs_edges(
+        G,
+        source,
+        reverse=reverse,
+        depth_limit=depth_limit,
+        sort_neighbors=sort_neighbors,
+    )
+    T.add_edges_from(edges_gen)
+    return T
+
+
+@nx._dispatch
+def bfs_predecessors(G, source, depth_limit=None, sort_neighbors=None):
+    """Returns an iterator of predecessors in breadth-first-search from source.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    source : node
+       Specify starting node for breadth-first search
+
+    depth_limit : int, optional(default=len(G))
+        Specify the maximum search depth
+
+    sort_neighbors : function
+        A function that takes the list of neighbors of given node as input, and
+        returns an *iterator* over these neighbors but with custom ordering.
+
+    Returns
+    -------
+    pred: iterator
+        (node, predecessor) iterator where `predecessor` is the predecessor of
+        `node` in a breadth first search starting from `source`.
+
+    Examples
+    --------
+    >>> G = nx.path_graph(3)
+    >>> dict(nx.bfs_predecessors(G, 0))
+    {1: 0, 2: 1}
+    >>> H = nx.Graph()
+    >>> H.add_edges_from([(0, 1), (0, 2), (1, 3), (1, 4), (2, 5), (2, 6)])
+    >>> dict(nx.bfs_predecessors(H, 0))
+    {1: 0, 2: 0, 3: 1, 4: 1, 5: 2, 6: 2}
+    >>> M = nx.Graph()
+    >>> nx.add_path(M, [0, 1, 2, 3, 4, 5, 6])
+    >>> nx.add_path(M, [2, 7, 8, 9, 10])
+    >>> sorted(nx.bfs_predecessors(M, source=1, depth_limit=3))
+    [(0, 1), (2, 1), (3, 2), (4, 3), (7, 2), (8, 7)]
+    >>> N = nx.DiGraph()
+    >>> nx.add_path(N, [0, 1, 2, 3, 4, 7])
+    >>> nx.add_path(N, [3, 5, 6, 7])
+    >>> sorted(nx.bfs_predecessors(N, source=2))
+    [(3, 2), (4, 3), (5, 3), (6, 5), (7, 4)]
+
+    Notes
+    -----
+    Based on http://www.ics.uci.edu/~eppstein/PADS/BFS.py
+    by D. Eppstein, July 2004. The modifications
+    to allow depth limits based on the Wikipedia article
+    "`Depth-limited-search`_".
+
+    .. _Depth-limited-search: https://en.wikipedia.org/wiki/Depth-limited_search
+
+    See Also
+    --------
+    bfs_tree
+    bfs_edges
+    edge_bfs
+    """
+    for s, t in bfs_edges(
+        G, source, depth_limit=depth_limit, sort_neighbors=sort_neighbors
+    ):
+        yield (t, s)
+
+
+@nx._dispatch
+def bfs_successors(G, source, depth_limit=None, sort_neighbors=None):
+    """Returns an iterator of successors in breadth-first-search from source.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    source : node
+       Specify starting node for breadth-first search
+
+    depth_limit : int, optional(default=len(G))
+        Specify the maximum search depth
+
+    sort_neighbors : function
+        A function that takes the list of neighbors of given node as input, and
+        returns an *iterator* over these neighbors but with custom ordering.
+
+    Returns
+    -------
+    succ: iterator
+       (node, successors) iterator where `successors` is the non-empty list of
+       successors of `node` in a breadth first search from `source`.
+       To appear in the iterator, `node` must have successors.
+
+    Examples
+    --------
+    >>> G = nx.path_graph(3)
+    >>> dict(nx.bfs_successors(G, 0))
+    {0: [1], 1: [2]}
+    >>> H = nx.Graph()
+    >>> H.add_edges_from([(0, 1), (0, 2), (1, 3), (1, 4), (2, 5), (2, 6)])
+    >>> dict(nx.bfs_successors(H, 0))
+    {0: [1, 2], 1: [3, 4], 2: [5, 6]}
+    >>> G = nx.Graph()
+    >>> nx.add_path(G, [0, 1, 2, 3, 4, 5, 6])
+    >>> nx.add_path(G, [2, 7, 8, 9, 10])
+    >>> dict(nx.bfs_successors(G, source=1, depth_limit=3))
+    {1: [0, 2], 2: [3, 7], 3: [4], 7: [8]}
+    >>> G = nx.DiGraph()
+    >>> nx.add_path(G, [0, 1, 2, 3, 4, 5])
+    >>> dict(nx.bfs_successors(G, source=3))
+    {3: [4], 4: [5]}
+
+    Notes
+    -----
+    Based on http://www.ics.uci.edu/~eppstein/PADS/BFS.py
+    by D. Eppstein, July 2004.The modifications
+    to allow depth limits based on the Wikipedia article
+    "`Depth-limited-search`_".
+
+    .. _Depth-limited-search: https://en.wikipedia.org/wiki/Depth-limited_search
+
+    See Also
+    --------
+    bfs_tree
+    bfs_edges
+    edge_bfs
+    """
+    parent = source
+    children = []
+    for p, c in bfs_edges(
+        G, source, depth_limit=depth_limit, sort_neighbors=sort_neighbors
+    ):
+        if p == parent:
+            children.append(c)
+            continue
+        yield (parent, children)
+        children = [c]
+        parent = p
+    yield (parent, children)
+
+
+@nx._dispatch
+def bfs_layers(G, sources):
+    """Returns an iterator of all the layers in breadth-first search traversal.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+        A graph over which to find the layers using breadth-first search.
+
+    sources : node in `G` or list of nodes in `G`
+        Specify starting nodes for single source or multiple sources breadth-first search
+
+    Yields
+    ------
+    layer: list of nodes
+        Yields list of nodes at the same distance from sources
+
+    Examples
+    --------
+    >>> G = nx.path_graph(5)
+    >>> dict(enumerate(nx.bfs_layers(G, [0, 4])))
+    {0: [0, 4], 1: [1, 3], 2: [2]}
+    >>> H = nx.Graph()
+    >>> H.add_edges_from([(0, 1), (0, 2), (1, 3), (1, 4), (2, 5), (2, 6)])
+    >>> dict(enumerate(nx.bfs_layers(H, [1])))
+    {0: [1], 1: [0, 3, 4], 2: [2], 3: [5, 6]}
+    >>> dict(enumerate(nx.bfs_layers(H, [1, 6])))
+    {0: [1, 6], 1: [0, 3, 4, 2], 2: [5]}
+    """
+    if sources in G:
+        sources = [sources]
+
+    current_layer = list(sources)
+    visited = set(sources)
+
+    for source in current_layer:
+        if source not in G:
+            raise nx.NetworkXError(f"The node {source} is not in the graph.")
+
+    # this is basically BFS, except that the current layer only stores the nodes at
+    # same distance from sources at each iteration
+    while current_layer:
+        yield current_layer
+        next_layer = []
+        for node in current_layer:
+            for child in G[node]:
+                if child not in visited:
+                    visited.add(child)
+                    next_layer.append(child)
+        current_layer = next_layer
+
+
+REVERSE_EDGE = "reverse"
+TREE_EDGE = "tree"
+FORWARD_EDGE = "forward"
+LEVEL_EDGE = "level"
+
+
+@nx._dispatch
+def bfs_labeled_edges(G, sources):
+    """Iterate over edges in a breadth-first search (BFS) labeled by type.
+
+    We generate triple of the form (*u*, *v*, *d*), where (*u*, *v*) is the
+    edge being explored in the breadth-first search and *d* is one of the
+    strings 'tree', 'forward', 'level', or 'reverse'.  A 'tree' edge is one in
+    which *v* is first discovered and placed into the layer below *u*.  A
+    'forward' edge is one in which *u* is on the layer above *v* and *v* has
+    already been discovered.  A 'level' edge is one in which both *u* and *v*
+    occur on the same layer.  A 'reverse' edge is one in which *u* is on a layer
+    below *v*.
+
+    We emit each edge exactly once.  In an undirected graph, 'reverse' edges do
+    not occur, because each is discovered either as a 'tree' or 'forward' edge.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+        A graph over which to find the layers using breadth-first search.
+
+    sources : node in `G` or list of nodes in `G`
+        Starting nodes for single source or multiple sources breadth-first search
+
+    Yields
+    ------
+    edges: generator
+       A generator of triples (*u*, *v*, *d*) where (*u*, *v*) is the edge being
+       explored and *d* is described above.
+
+    Examples
+    --------
+    >>> G = nx.cycle_graph(4, create_using = nx.DiGraph)
+    >>> list(nx.bfs_labeled_edges(G, 0))
+    [(0, 1, 'tree'), (1, 2, 'tree'), (2, 3, 'tree'), (3, 0, 'reverse')]
+    >>> G = nx.complete_graph(3)
+    >>> list(nx.bfs_labeled_edges(G, 0))
+    [(0, 1, 'tree'), (0, 2, 'tree'), (1, 2, 'level')]
+    >>> list(nx.bfs_labeled_edges(G, [0, 1]))
+    [(0, 1, 'level'), (0, 2, 'tree'), (1, 2, 'forward')]
+    """
+    if sources in G:
+        sources = [sources]
+
+    neighbors = G._adj
+    directed = G.is_directed()
+    visited = set()
+    visit = visited.discard if directed else visited.add
+    # We use visited in a negative sense, so the visited set stays empty for the
+    # directed case and level edges are reported on their first occurrence in
+    # the undirected case.  Note our use of visited.discard -- this is built-in
+    # thus somewhat faster than a python-defined def nop(x): pass
+    depth = {s: 0 for s in sources}
+    queue = deque(depth.items())
+    push = queue.append
+    pop = queue.popleft
+    while queue:
+        u, du = pop()
+        for v in neighbors[u]:
+            if v not in depth:
+                depth[v] = dv = du + 1
+                push((v, dv))
+                yield u, v, TREE_EDGE
+            else:
+                dv = depth[v]
+                if du == dv:
+                    if v not in visited:
+                        yield u, v, LEVEL_EDGE
+                elif du < dv:
+                    yield u, v, FORWARD_EDGE
+                elif directed:
+                    yield u, v, REVERSE_EDGE
+        visit(u)
+
+
+@nx._dispatch
+def descendants_at_distance(G, source, distance):
+    """Returns all nodes at a fixed `distance` from `source` in `G`.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+        A graph
+    source : node in `G`
+    distance : the distance of the wanted nodes from `source`
+
+    Returns
+    -------
+    set()
+        The descendants of `source` in `G` at the given `distance` from `source`
+
+    Examples
+    --------
+    >>> G = nx.path_graph(5)
+    >>> nx.descendants_at_distance(G, 2, 2)
+    {0, 4}
+    >>> H = nx.DiGraph()
+    >>> H.add_edges_from([(0, 1), (0, 2), (1, 3), (1, 4), (2, 5), (2, 6)])
+    >>> nx.descendants_at_distance(H, 0, 2)
+    {3, 4, 5, 6}
+    >>> nx.descendants_at_distance(H, 5, 0)
+    {5}
+    >>> nx.descendants_at_distance(H, 5, 1)
+    set()
+    """
+    if source not in G:
+        raise nx.NetworkXError(f"The node {source} is not in the graph.")
+
+    bfs_generator = nx.bfs_layers(G, source)
+    for i, layer in enumerate(bfs_generator):
+        if i == distance:
+            return set(layer)
+    return set()

tuning-competition-baseline/.venv/lib/python3.11/site-packages/networkx/algorithms/traversal/depth_first_search.py

@@ -0,0 +1,469 @@
+"""Basic algorithms for depth-first searching the nodes of a graph."""
+from collections import defaultdict
+
+import networkx as nx
+
+__all__ = [
+    "dfs_edges",
+    "dfs_tree",
+    "dfs_predecessors",
+    "dfs_successors",
+    "dfs_preorder_nodes",
+    "dfs_postorder_nodes",
+    "dfs_labeled_edges",
+]
+
+
+@nx._dispatch
+def dfs_edges(G, source=None, depth_limit=None):
+    """Iterate over edges in a depth-first-search (DFS).
+
+    Perform a depth-first-search over the nodes of `G` and yield
+    the edges in order. This may not generate all edges in `G`
+    (see `~networkx.algorithms.traversal.edgedfs.edge_dfs`).
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    source : node, optional
+       Specify starting node for depth-first search and yield edges in
+       the component reachable from source.
+
+    depth_limit : int, optional (default=len(G))
+       Specify the maximum search depth.
+
+    Yields
+    ------
+    edge: 2-tuple of nodes
+       Yields edges resulting from the depth-first-search.
+
+    Examples
+    --------
+    >>> G = nx.path_graph(5)
+    >>> list(nx.dfs_edges(G, source=0))
+    [(0, 1), (1, 2), (2, 3), (3, 4)]
+    >>> list(nx.dfs_edges(G, source=0, depth_limit=2))
+    [(0, 1), (1, 2)]
+
+    Notes
+    -----
+    If a source is not specified then a source is chosen arbitrarily and
+    repeatedly until all components in the graph are searched.
+
+    The implementation of this function is adapted from David Eppstein's
+    depth-first search function in PADS [1]_, with modifications
+    to allow depth limits based on the Wikipedia article
+    "Depth-limited search" [2]_.
+
+    See Also
+    --------
+    dfs_preorder_nodes
+    dfs_postorder_nodes
+    dfs_labeled_edges
+    :func:`~networkx.algorithms.traversal.edgedfs.edge_dfs`
+    :func:`~networkx.algorithms.traversal.breadth_first_search.bfs_edges`
+
+    References
+    ----------
+    .. [1] http://www.ics.uci.edu/~eppstein/PADS
+    .. [2] https://en.wikipedia.org/wiki/Depth-limited_search
+    """
+    if source is None:
+        # edges for all components
+        nodes = G
+    else:
+        # edges for components with source
+        nodes = [source]
+    if depth_limit is None:
+        depth_limit = len(G)
+
+    visited = set()
+    for start in nodes:
+        if start in visited:
+            continue
+        visited.add(start)
+        stack = [(start, iter(G[start]))]
+        depth_now = 1
+        while stack:
+            parent, children = stack[-1]
+            for child in children:
+                if child not in visited:
+                    yield parent, child
+                    visited.add(child)
+                    if depth_now < depth_limit:
+                        stack.append((child, iter(G[child])))
+                        depth_now += 1
+                        break
+            else:
+                stack.pop()
+                depth_now -= 1
+
+
+@nx._dispatch
+def dfs_tree(G, source=None, depth_limit=None):
+    """Returns oriented tree constructed from a depth-first-search from source.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    source : node, optional
+       Specify starting node for depth-first search.
+
+    depth_limit : int, optional (default=len(G))
+       Specify the maximum search depth.
+
+    Returns
+    -------
+    T : NetworkX DiGraph
+       An oriented tree
+
+    Examples
+    --------
+    >>> G = nx.path_graph(5)
+    >>> T = nx.dfs_tree(G, source=0, depth_limit=2)
+    >>> list(T.edges())
+    [(0, 1), (1, 2)]
+    >>> T = nx.dfs_tree(G, source=0)
+    >>> list(T.edges())
+    [(0, 1), (1, 2), (2, 3), (3, 4)]
+
+    See Also
+    --------
+    dfs_preorder_nodes
+    dfs_postorder_nodes
+    dfs_labeled_edges
+    edge_dfs
+    bfs_tree
+    """
+    T = nx.DiGraph()
+    if source is None:
+        T.add_nodes_from(G)
+    else:
+        T.add_node(source)
+    T.add_edges_from(dfs_edges(G, source, depth_limit))
+    return T
+
+
+@nx._dispatch
+def dfs_predecessors(G, source=None, depth_limit=None):
+    """Returns dictionary of predecessors in depth-first-search from source.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    source : node, optional
+       Specify starting node for depth-first search.
+       Note that you will get predecessors for all nodes in the
+       component containing `source`. This input only specifies
+       where the DFS starts.
+
+    depth_limit : int, optional (default=len(G))
+       Specify the maximum search depth.
+
+    Returns
+    -------
+    pred: dict
+       A dictionary with nodes as keys and predecessor nodes as values.
+
+    Examples
+    --------
+    >>> G = nx.path_graph(4)
+    >>> nx.dfs_predecessors(G, source=0)
+    {1: 0, 2: 1, 3: 2}
+    >>> nx.dfs_predecessors(G, source=0, depth_limit=2)
+    {1: 0, 2: 1}
+
+    Notes
+    -----
+    If a source is not specified then a source is chosen arbitrarily and
+    repeatedly until all components in the graph are searched.
+
+    The implementation of this function is adapted from David Eppstein's
+    depth-first search function in `PADS`_, with modifications
+    to allow depth limits based on the Wikipedia article
+    "`Depth-limited search`_".
+
+    .. _PADS: http://www.ics.uci.edu/~eppstein/PADS
+    .. _Depth-limited search: https://en.wikipedia.org/wiki/Depth-limited_search
+
+    See Also
+    --------
+    dfs_preorder_nodes
+    dfs_postorder_nodes
+    dfs_labeled_edges
+    edge_dfs
+    bfs_tree
+    """
+    return {t: s for s, t in dfs_edges(G, source, depth_limit)}
+
+
+@nx._dispatch
+def dfs_successors(G, source=None, depth_limit=None):
+    """Returns dictionary of successors in depth-first-search from source.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    source : node, optional
+       Specify starting node for depth-first search.
+       Note that you will get successors for all nodes in the
+       component containing `source`. This input only specifies
+       where the DFS starts.
+
+    depth_limit : int, optional (default=len(G))
+       Specify the maximum search depth.
+
+    Returns
+    -------
+    succ: dict
+       A dictionary with nodes as keys and list of successor nodes as values.
+
+    Examples
+    --------
+    >>> G = nx.path_graph(5)
+    >>> nx.dfs_successors(G, source=0)
+    {0: [1], 1: [2], 2: [3], 3: [4]}
+    >>> nx.dfs_successors(G, source=0, depth_limit=2)
+    {0: [1], 1: [2]}
+
+    Notes
+    -----
+    If a source is not specified then a source is chosen arbitrarily and
+    repeatedly until all components in the graph are searched.
+
+    The implementation of this function is adapted from David Eppstein's
+    depth-first search function in `PADS`_, with modifications
+    to allow depth limits based on the Wikipedia article
+    "`Depth-limited search`_".
+
+    .. _PADS: http://www.ics.uci.edu/~eppstein/PADS
+    .. _Depth-limited search: https://en.wikipedia.org/wiki/Depth-limited_search
+
+    See Also
+    --------
+    dfs_preorder_nodes
+    dfs_postorder_nodes
+    dfs_labeled_edges
+    edge_dfs
+    bfs_tree
+    """
+    d = defaultdict(list)
+    for s, t in dfs_edges(G, source=source, depth_limit=depth_limit):
+        d[s].append(t)
+    return dict(d)
+
+
+@nx._dispatch
+def dfs_postorder_nodes(G, source=None, depth_limit=None):
+    """Generate nodes in a depth-first-search post-ordering starting at source.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    source : node, optional
+       Specify starting node for depth-first search.
+
+    depth_limit : int, optional (default=len(G))
+       Specify the maximum search depth.
+
+    Returns
+    -------
+    nodes: generator
+       A generator of nodes in a depth-first-search post-ordering.
+
+    Examples
+    --------
+    >>> G = nx.path_graph(5)
+    >>> list(nx.dfs_postorder_nodes(G, source=0))
+    [4, 3, 2, 1, 0]
+    >>> list(nx.dfs_postorder_nodes(G, source=0, depth_limit=2))
+    [1, 0]
+
+    Notes
+    -----
+    If a source is not specified then a source is chosen arbitrarily and
+    repeatedly until all components in the graph are searched.
+
+    The implementation of this function is adapted from David Eppstein's
+    depth-first search function in `PADS`_, with modifications
+    to allow depth limits based on the Wikipedia article
+    "`Depth-limited search`_".
+
+    .. _PADS: http://www.ics.uci.edu/~eppstein/PADS
+    .. _Depth-limited search: https://en.wikipedia.org/wiki/Depth-limited_search
+
+    See Also
+    --------
+    dfs_edges
+    dfs_preorder_nodes
+    dfs_labeled_edges
+    edge_dfs
+    bfs_tree
+    """
+    edges = nx.dfs_labeled_edges(G, source=source, depth_limit=depth_limit)
+    return (v for u, v, d in edges if d == "reverse")
+
+
+@nx._dispatch
+def dfs_preorder_nodes(G, source=None, depth_limit=None):
+    """Generate nodes in a depth-first-search pre-ordering starting at source.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    source : node, optional
+       Specify starting node for depth-first search and return nodes in
+       the component reachable from source.
+
+    depth_limit : int, optional (default=len(G))
+       Specify the maximum search depth.
+
+    Returns
+    -------
+    nodes: generator
+       A generator of nodes in a depth-first-search pre-ordering.
+
+    Examples
+    --------
+    >>> G = nx.path_graph(5)
+    >>> list(nx.dfs_preorder_nodes(G, source=0))
+    [0, 1, 2, 3, 4]
+    >>> list(nx.dfs_preorder_nodes(G, source=0, depth_limit=2))
+    [0, 1, 2]
+
+    Notes
+    -----
+    If a source is not specified then a source is chosen arbitrarily and
+    repeatedly until all components in the graph are searched.
+
+    The implementation of this function is adapted from David Eppstein's
+    depth-first search function in `PADS`_, with modifications
+    to allow depth limits based on the Wikipedia article
+    "`Depth-limited search`_".
+
+    .. _PADS: http://www.ics.uci.edu/~eppstein/PADS
+    .. _Depth-limited search: https://en.wikipedia.org/wiki/Depth-limited_search
+
+    See Also
+    --------
+    dfs_edges
+    dfs_postorder_nodes
+    dfs_labeled_edges
+    bfs_edges
+    """
+    edges = nx.dfs_labeled_edges(G, source=source, depth_limit=depth_limit)
+    return (v for u, v, d in edges if d == "forward")
+
+
+@nx._dispatch
+def dfs_labeled_edges(G, source=None, depth_limit=None):
+    """Iterate over edges in a depth-first-search (DFS) labeled by type.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+
+    source : node, optional
+       Specify starting node for depth-first search and return edges in
+       the component reachable from source.
+
+    depth_limit : int, optional (default=len(G))
+       Specify the maximum search depth.
+
+    Returns
+    -------
+    edges: generator
+       A generator of triples of the form (*u*, *v*, *d*), where (*u*,
+       *v*) is the edge being explored in the depth-first search and *d*
+       is one of the strings 'forward', 'nontree', 'reverse', or 'reverse-depth_limit'.
+       A 'forward' edge is one in which *u* has been visited but *v* has
+       not. A 'nontree' edge is one in which both *u* and *v* have been
+       visited but the edge is not in the DFS tree. A 'reverse' edge is
+       one in which both *u* and *v* have been visited and the edge is in
+       the DFS tree. When the `depth_limit` is reached via a 'forward' edge,
+       a 'reverse' edge is immediately generated rather than the subtree
+       being explored. To indicate this flavor of 'reverse' edge, the string
+       yielded is 'reverse-depth_limit'.
+
+    Examples
+    --------
+
+    The labels reveal the complete transcript of the depth-first search
+    algorithm in more detail than, for example, :func:`dfs_edges`::
+
+        >>> from pprint import pprint
+        >>>
+        >>> G = nx.DiGraph([(0, 1), (1, 2), (2, 1)])
+        >>> pprint(list(nx.dfs_labeled_edges(G, source=0)))
+        [(0, 0, 'forward'),
+         (0, 1, 'forward'),
+         (1, 2, 'forward'),
+         (2, 1, 'nontree'),
+         (1, 2, 'reverse'),
+         (0, 1, 'reverse'),
+         (0, 0, 'reverse')]
+
+    Notes
+    -----
+    If a source is not specified then a source is chosen arbitrarily and
+    repeatedly until all components in the graph are searched.
+
+    The implementation of this function is adapted from David Eppstein's
+    depth-first search function in `PADS`_, with modifications
+    to allow depth limits based on the Wikipedia article
+    "`Depth-limited search`_".
+
+    .. _PADS: http://www.ics.uci.edu/~eppstein/PADS
+    .. _Depth-limited search: https://en.wikipedia.org/wiki/Depth-limited_search
+
+    See Also
+    --------
+    dfs_edges
+    dfs_preorder_nodes
+    dfs_postorder_nodes
+    """
+    # Based on http://www.ics.uci.edu/~eppstein/PADS/DFS.py
+    # by D. Eppstein, July 2004.
+    if source is None:
+        # edges for all components
+        nodes = G
+    else:
+        # edges for components with source
+        nodes = [source]
+    if depth_limit is None:
+        depth_limit = len(G)
+
+    visited = set()
+    for start in nodes:
+        if start in visited:
+            continue
+        yield start, start, "forward"
+        visited.add(start)
+        stack = [(start, iter(G[start]))]
+        depth_now = 1
+        while stack:
+            parent, children = stack[-1]
+            for child in children:
+                if child in visited:
+                    yield parent, child, "nontree"
+                else:
+                    yield parent, child, "forward"
+                    visited.add(child)
+                    if depth_now < depth_limit:
+                        stack.append((child, iter(G[child])))
+                        depth_now += 1
+                        break
+                    else:
+                        yield parent, child, "reverse-depth_limit"
+            else:
+                stack.pop()
+                depth_now -= 1
+                if stack:
+                    yield stack[-1][0], parent, "reverse"
+        yield start, start, "reverse"