test: filling gaps in MAS and SW

Author: Becheler

test/mas_sw_maxflow_oracle.hpp

@@ -0,0 +1,124 @@
+// Copyright Arnaud Becheler 2026.
+// Distributed under the Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt or the copy at
+// http://www.boost.org/LICENSE_1_0.txt)
+
+// Shared max-flow oracle helpers for
+// maximum_adjacency_search and stoer_wagner_min_cut characterization tests. 
+// push_relabel_max_flow serves as an independent reference
+// expected values are recomputed on each random graph rather than hardcoded.
+
+#ifndef BOOST_GRAPH_TEST_MAS_SW_MAXFLOW_ORACLE_HPP
+#define BOOST_GRAPH_TEST_MAS_SW_MAXFLOW_ORACLE_HPP
+
+#include <random>
+#include <vector>
+
+#include <boost/graph/adjacency_list.hpp>
+#include <boost/graph/connected_components.hpp>
+#include <boost/graph/push_relabel_max_flow.hpp>
+#include <boost/property_map/property_map.hpp>
+
+namespace mas_sw_oracle
+{
+
+using undirected_graph = boost::adjacency_list<
+    boost::vecS, 
+    boost::vecS,
+    boost::undirectedS, 
+    boost::no_property,
+    boost::property< boost::edge_weight_t, int >
+>;
+
+using weight_map_type = boost::property_map< undirected_graph, boost::edge_weight_t >::type;
+using weight_type = boost::property_traits< weight_map_type >::value_type;
+using vertex_descriptor = boost::graph_traits< undirected_graph >::vertex_descriptor;
+using edge_descriptor = boost::graph_traits< undirected_graph >::edge_descriptor;
+
+// Directed network used only by the max-flow oracle. 
+using flow_traits = boost::adjacency_list_traits< boost::vecS, boost::vecS, boost::directedS >;
+using flow_graph = boost::adjacency_list< boost::vecS, boost::vecS, boost::directedS,
+    boost::no_property,
+    boost::property< boost::edge_capacity_t, weight_type,
+        boost::property< boost::edge_residual_capacity_t, weight_type,
+            boost::property< boost::edge_reverse_t, flow_traits::edge_descriptor > > > >;
+
+// Minimum u-v cut of the undirected graph via max-flow. 
+inline weight_type undirected_min_cut(const undirected_graph& g, vertex_descriptor u, vertex_descriptor v)
+{
+    flow_graph fg(num_vertices(g));
+    auto capacity_map = get(boost::edge_capacity, fg);
+    auto reverse_edge_map = get(boost::edge_reverse, fg);
+    auto weight_map = get(boost::edge_weight, g);
+
+    boost::graph_traits< undirected_graph >::edge_iterator ei, ei_end;
+    for (boost::tie(ei, ei_end) = edges(g); ei != ei_end; ++ei)
+    {
+        // read the undirected edge and its weight
+        const vertex_descriptor a = source(*ei, g);
+        const vertex_descriptor b = target(*ei, g);
+        const weight_type w = get(weight_map, *ei);
+        // arc a to b at capacity w, paired with a zero capacity reverse
+        const auto a_to_b = add_edge(a, b, fg).first;
+        const auto a_to_b_reverse = add_edge(b, a, fg).first;
+        put(capacity_map, a_to_b, w);
+        put(capacity_map, a_to_b_reverse, 0);
+        put(reverse_edge_map, a_to_b, a_to_b_reverse);
+        put(reverse_edge_map, a_to_b_reverse, a_to_b);
+        // opposite arc b to a, its own capacity w and zero capacity reverse
+        const auto b_to_a = add_edge(b, a, fg).first;
+        const auto b_to_a_reverse = add_edge(a, b, fg).first;
+        put(capacity_map, b_to_a, w);
+        put(capacity_map, b_to_a_reverse, 0);
+        put(reverse_edge_map, b_to_a, b_to_a_reverse);
+        put(reverse_edge_map, b_to_a_reverse, b_to_a);
+    }
+    return boost::push_relabel_max_flow(fg, u, v);
+}
+
+inline weight_type weighted_degree(const undirected_graph& g, vertex_descriptor v)
+{
+    auto weight_map = get(boost::edge_weight, g);
+    weight_type sum = 0;
+    boost::graph_traits< undirected_graph >::out_edge_iterator oi, oi_end;
+    for (boost::tie(oi, oi_end) = out_edges(v, g); oi != oi_end; ++oi) sum += get(weight_map, *oi);
+    return sum;
+}
+
+// Random connected undirected weighted multigraph.
+inline undirected_graph make_random_connected_graph(std::size_t n, std::size_t extra_edges, std::mt19937& rng)
+{
+    undirected_graph g(n);
+    std::uniform_int_distribution< weight_type > weight_dist(1, 10);
+    std::uniform_int_distribution< std::size_t > vertex_dist(0, n - 1);
+    auto weight_map = get(boost::edge_weight, g);
+
+    // spanning path 0,1,...,n-1 makes the graph connected
+    for (std::size_t i = 1; i < n; ++i)
+    {
+        const auto e = add_edge(i - 1, i, g).first;
+        put(weight_map, e, weight_dist(rng));
+    }
+
+    // random extra edges, skipping self loops
+    for (std::size_t k = 0; k < extra_edges; ++k)
+    {
+        const std::size_t u = vertex_dist(rng);
+        const std::size_t v = vertex_dist(rng);
+        if (u == v) continue;
+        const auto e = add_edge(u, v, g).first;
+        put(weight_map, e, weight_dist(rng));
+    }
+    return g;
+}
+
+inline bool is_connected(const undirected_graph& g)
+{
+    std::vector< std::size_t > component(num_vertices(g));
+    auto components_map = boost::make_iterator_property_map(component.begin(), get(boost::vertex_index, g));
+    return boost::connected_components(g, components_map) == 1U;
+}
+
+} // namespace mas_sw_oracle
+
+#endif // BOOST_GRAPH_TEST_MAS_SW_MAXFLOW_ORACLE_HPP

test/mas_test.cpp

@@ -4,9 +4,12 @@
 //   (See accompanying file LICENSE_1_0.txt or the copy at
 //         http://www.boost.org/LICENSE_1_0.txt)
 
+#include <algorithm>
 #include <fstream>
 #include <iostream>
 #include <map>
+#include <random>
+#include <stdexcept>
 #include <vector>
 #include <string>
 #include <boost/array.hpp>
@@ -27,12 +30,13 @@
 
 #include <boost/graph/iteration_macros.hpp>
 
-typedef boost::adjacency_list< boost::vecS, boost::vecS, boost::undirectedS,
-    boost::no_property, boost::property< boost::edge_weight_t, int > >
-    undirected_graph;
-typedef boost::property_map< undirected_graph, boost::edge_weight_t >::type
-    weight_map_type;
-typedef boost::property_traits< weight_map_type >::value_type weight_type;
+#include "mas_sw_maxflow_oracle.hpp"
+
+using mas_sw_oracle::undirected_graph;
+using mas_sw_oracle::weight_map_type;
+using mas_sw_oracle::weight_type;
+using mas_sw_oracle::vertex_descriptor;
+using mas_sw_oracle::edge_descriptor;
 
 typedef boost::adjacency_list< boost::vecS, boost::vecS, boost::undirectedS >
     undirected_unweighted_graph;
@@ -570,6 +574,169 @@ void test9_weights_start_vertex() {
     );
 }
 
+using cv_distances_map_type = boost::shared_array_property_map< weight_type,
+    boost::property_map< undirected_graph, boost::vertex_index_t >::const_type >;
+using cv_index_in_heap_type = std::vector< vertex_descriptor >::size_type;
+using cv_indices_map_type = boost::shared_array_property_map< cv_index_in_heap_type,
+    boost::property_map< undirected_graph, boost::vertex_index_t >::const_type >;
+using cv_maxheap_type = boost::d_ary_heap_indirect< vertex_descriptor, 4, cv_indices_map_type,
+    cv_distances_map_type, std::greater< weight_type > >;
+
+// Build the keyed max priority queue MAS runs on: reach counts plus heap positions.
+cv_maxheap_type make_weighted_maxheap(const undirected_graph& g)
+{
+    auto distances_map = boost::make_shared_array_property_map(num_vertices(g), weight_type(0), get(boost::vertex_index, g));
+    auto indices_map = boost::make_shared_array_property_map(num_vertices(g), cv_index_in_heap_type(-1), get(boost::vertex_index, g));
+    return cv_maxheap_type(distances_map, indices_map);
+}
+
+// Check invariants on a MAS run
+void check_visit_order_invariants(
+    const undirected_graph& g,
+    const std::vector< vertex_descriptor >& order, 
+    const std::vector< weight_type >& reach)
+{
+    const std::size_t n = num_vertices(g);
+
+    // 1) the order is a permutation of all vertices
+    std::vector< vertex_descriptor > sorted = order;
+    std::sort(sorted.begin(), sorted.end());
+    for (std::size_t i = 0; i < sorted.size(); ++i)
+        BOOST_TEST_EQ(sorted[i], static_cast< vertex_descriptor >(i));
+
+    // 2) MAS adds n+1 to the start vertex key to force it first, so its recorded reach is n+1
+    BOOST_TEST_EQ(reach[0], static_cast< weight_type >(n + 1));
+
+    // only the start vertex is visited before the loop
+    std::vector< bool > visited(n, false);
+    visited[order[0]] = true;
+    auto weight_map = get(boost::edge_weight, g);
+
+    // 3) recompute each later vertex reach independently and check MAS agrees
+    for (std::size_t i = 1; i < order.size(); ++i)
+    {
+        const vertex_descriptor u = order[i];
+        // sum the weights of u's edges that lead back into the visited set
+        weight_type expected = 0;
+        boost::graph_traits< undirected_graph >::out_edge_iterator oi, oi_end;
+        for (boost::tie(oi, oi_end) = out_edges(u, g); oi != oi_end; ++oi)
+            if (visited[target(*oi, g)]) 
+                expected += get(weight_map, *oi);
+        
+        BOOST_TEST_EQ(reach[i], expected);
+        visited[u] = true;
+    }
+}
+
+// Records every visitor event. 
+class recording_visitor : public boost::default_mas_visitor
+{
+public:
+    recording_visitor(
+        std::size_t& initialize_count, 
+        std::size_t& examine_count,
+        std::vector< vertex_descriptor >& start_order, 
+        std::vector< vertex_descriptor >& finish_order
+    )
+    :
+    initialize_count_(initialize_count), 
+    examine_count_(examine_count),
+    start_order_(start_order), 
+    finish_order_(finish_order)
+    {}
+
+    void initialize_vertex(vertex_descriptor, const undirected_graph&) { ++initialize_count_; }
+    void start_vertex(vertex_descriptor u, const undirected_graph&) { start_order_.push_back(u); }
+    void examine_edge(edge_descriptor, const undirected_graph&) { ++examine_count_; }
+    void finish_vertex(vertex_descriptor u, const undirected_graph&) { finish_order_.push_back(u); }
+
+private:
+    std::size_t& initialize_count_;
+    std::size_t& examine_count_;
+    std::vector< vertex_descriptor >& start_order_;
+    std::vector< vertex_descriptor >& finish_order_;
+};
+
+// Cross-validation against the max-flow oracle
+// for the last two visited vertices s (second-last) and t (last), 
+// the reach count of t equals its weighted degree and equals the min s-t cut.
+void test_maxflow_crossvalidation()
+{
+    // sweep a few graph sizes and several seeds
+    const std::size_t sizes[] = { 6, 8, 10, 12, 50 };
+    for (std::size_t si = 0; si < sizeof(sizes) / sizeof(sizes[0]); ++si)
+    {
+        const std::size_t n = sizes[si];
+        for (std::size_t seed = 1; seed <= 25; ++seed)
+        {
+            // build a deterministic random connected graph
+            std::mt19937 rng(static_cast< std::mt19937::result_type >(seed));
+            const undirected_graph g = mas_sw_oracle::make_random_connected_graph(n, n, rng);
+            BOOST_TEST(mas_sw_oracle::is_connected(g));
+
+            // run MAS, recording visit order and reach counts
+            cv_maxheap_type pq = make_weighted_maxheap(g);
+            mas_test_visitor< undirected_graph, cv_maxheap_type > vis(pq);
+            boost::maximum_adjacency_search(g, boost::weight_map(get(boost::edge_weight, g)).visitor(vis).max_priority_queue(pq));
+
+            const std::vector< vertex_descriptor >& order = vis.vertex_visit_order();
+            const std::vector< weight_type >& reach = vis.vertex_weights_when_visited();
+            BOOST_TEST_EQ(order.size(), n);
+
+            // take the last two visited vertices s and t
+            const std::size_t last = order.size() - 1;
+            const vertex_descriptor s = order[last - 1];
+            const vertex_descriptor t = order[last];
+            const weight_type reach_of_t = reach[last];
+
+            // t's reach must equal its weighted degree and the min s-t cut
+            BOOST_TEST_EQ(reach_of_t, mas_sw_oracle::weighted_degree(g, t));
+            BOOST_TEST_EQ(reach_of_t, mas_sw_oracle::undirected_min_cut(g, s, t));
+
+            // and the whole order must be a valid maximum adjacency ordering
+            check_visit_order_invariants(g, order, reach);
+        }
+    }
+}
+
+// Every visitor event fires the expected number of times
+void test_visitor_events()
+{
+    std::mt19937 rng(7);
+    const undirected_graph g = mas_sw_oracle::make_random_connected_graph(8, 8, rng);
+
+    cv_maxheap_type pq = make_weighted_maxheap(g);
+    std::size_t initialize_count = 0;
+    std::size_t examine_count = 0;
+    std::vector< vertex_descriptor > start_order;
+    std::vector< vertex_descriptor > finish_order;
+    recording_visitor vis(initialize_count, examine_count, start_order, finish_order);
+
+    boost::maximum_adjacency_search(g, boost::weight_map(get(boost::edge_weight, g)).visitor(vis).max_priority_queue(pq));
+
+    BOOST_TEST_EQ(initialize_count, static_cast< std::size_t >(num_vertices(g)));
+    BOOST_TEST_EQ(examine_count, static_cast< std::size_t >(2 * num_edges(g)));
+    BOOST_TEST_EQ(start_order.size(), static_cast< std::size_t >(num_vertices(g)));
+    BOOST_TEST_EQ(finish_order.size(), static_cast< std::size_t >(num_vertices(g)));
+    BOOST_TEST_ALL_EQ(start_order.begin(), start_order.end(), finish_order.begin(), finish_order.end());
+}
+
+// Precondition violations throw.
+void test_exceptions()
+{
+    // a graph with fewer than two vertices is rejected
+    undirected_graph too_small;
+    add_vertex(too_small);
+    BOOST_TEST_THROWS(boost::maximum_adjacency_search(too_small, boost::weight_map(get(boost::edge_weight, too_small))), boost::bad_graph);
+
+    // a non-empty priority queue is rejected
+    std::mt19937 rng(3);
+    const undirected_graph g = mas_sw_oracle::make_random_connected_graph(4, 4, rng);
+    cv_maxheap_type pq = make_weighted_maxheap(g);
+    pq.push(0);
+    BOOST_TEST_THROWS(boost::maximum_adjacency_search(g, boost::weight_map(get(boost::edge_weight, g)).max_priority_queue(pq)), std::invalid_argument);
+}
+
 #include <boost/graph/iteration_macros_undef.hpp>
 
 int main(int argc, char* argv[])
@@ -586,6 +753,9 @@ int main(int argc, char* argv[])
         test7_weights();
         test8_weights();
         test9_weights_start_vertex();
+        test_maxflow_crossvalidation();
+        test_visitor_events();
+        test_exceptions();
     }
     return boost::report_errors();
 }