connected_components.hpp

Go to the documentation of this file.

/// @file spatial/connected_components.hpp
/// @brief Iterative BFS connected-component labelling.
///
/// connected_components(n_sites, in_cluster, neighbors)
///
/// Template parameters:
///   InCluster  callable: bool(int i)        -- true if site i is in the
///   cluster Neighbors  callable: void(int i, F&& f) -- calls f(nb) for each
///   neighbor nb of i
///
/// Returns ClusterResult where id[i] is:
///   -2  = excluded (in_cluster returned false)
///   >=0 = cluster index
///
/// ClusterResult::largest_id and largest_size track the biggest connected
/// component.
#pragma once
 
#include <vector>
 
namespace num {
 
struct ClusterResult {
    std::vector<int> id;    ///< Per-site label: -2 excluded, >=0 cluster index
    std::vector<int> sizes; ///< sizes[c] = number of sites in cluster c
    int              largest_id = -1; ///< Index of largest cluster (-1 if none)
    int              largest_size = 0; ///< Size of largest cluster
};
 
/// BFS connected-component labelling with pre-allocated flat queue (no heap per
/// call).
///
/// @param n_sites   Total number of sites
/// @param in_cluster  bool(int i) -- include site i?
/// @param neighbors   void(int i, auto&& visit) -- call visit(nb) per neighbor
/// of i
template<typename InCluster, typename Neighbors>
ClusterResult connected_components(int         n_sites,
                                   InCluster&& in_cluster,
                                   Neighbors&& neighbors) {
    ClusterResult res;
    res.id.resize(n_sites);
    res.sizes.reserve(64);
 
    for (int i = 0; i < n_sites; ++i)
        res.id[i] = in_cluster(i)
                        ? -1
                        : -2; // -1 = unvisited included, -2 = excluded
 
    std::vector<int> queue(n_sites);
    int              qhead = 0, qtail = 0;
 
    for (int start = 0; start < n_sites; ++start) {
        if (res.id[start] != -1)
            continue;
 
        const int cid = static_cast<int>(res.sizes.size());
        res.sizes.push_back(0);
        res.id[start]  = cid;
        queue[qtail++] = start;
 
        while (qhead < qtail) {
            const int i = queue[qhead++];
            ++res.sizes[cid];
            neighbors(i, [&](int nb) {
                if (res.id[nb] == -1) {
                    res.id[nb]     = cid;
                    queue[qtail++] = nb;
                }
            });
        }
 
        if (res.sizes[cid] > res.largest_size) {
            res.largest_size = res.sizes[cid];
            res.largest_id   = cid;
        }
    }
    return res;
}
 
} // namespace num