boost/graph/bron_kerbosch_all_cliques.hpp

0001 // (C) Copyright 2007-2009 Andrew Sutton
0002 //
0003 // Use, modification and distribution are subject to the
0004 // Boost Software License, Version 1.0 (See accompanying file
0005 // LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)
0006
0007 #ifndef BOOST_GRAPH_CLIQUE_HPP
0008 #define BOOST_GRAPH_CLIQUE_HPP
0009
0010 #include <vector>
0011 #include <deque>
0012 #include <boost/config.hpp>
0013
0014 #include <boost/concept/assert.hpp>
0015
0016 #include <boost/graph/graph_concepts.hpp>
0017 #include <boost/graph/lookup_edge.hpp>
0018
0019 #include <boost/concept/detail/concept_def.hpp>
0020 namespace boost
0021 {
0022 namespace concepts
0023 {
0024     BOOST_concept(CliqueVisitor, (Visitor)(Clique)(Graph))
0025     {
0026         BOOST_CONCEPT_USAGE(CliqueVisitor) { vis.clique(k, g); }
0027
0028     private:
0029         Visitor vis;
0030         Graph g;
0031         Clique k;
0032     };
0033 } /* namespace concepts */
0034 using concepts::CliqueVisitorConcept;
0035 } /* namespace boost */
0036 #include <boost/concept/detail/concept_undef.hpp>
0037
0038 namespace boost
0039 {
0040 // The algorithm implemented in this paper is based on the so-called
0041 // Algorithm 457, published as:
0042 //
0043 //     @article{362367,
0044 //         author = {Coen Bron and Joep Kerbosch},
0045 //         title = {Algorithm 457: finding all cliques of an undirected graph},
0046 //         journal = {Communications of the ACM},
0047 //         volume = {16},
0048 //         number = {9},
0049 //         year = {1973},
0050 //         issn = {0001-0782},
0051 //         pages = {575--577},
0052 //         doi = {http://doi.acm.org/10.1145/362342.362367},
0053 //             publisher = {ACM Press},
0054 //             address = {New York, NY, USA},
0055 //         }
0056 //
0057 // Sort of. This implementation is adapted from the 1st version of the
0058 // algorithm and does not implement the candidate selection optimization
0059 // described as published - it could, it just doesn't yet.
0060 //
0061 // The algorithm is given as proportional to (3.14)^(n/3) power. This is
0062 // not the same as O(...), but based on time measures and approximation.
0063 //
0064 // Unfortunately, this implementation may be less efficient on non-
0065 // AdjacencyMatrix modeled graphs due to the non-constant implementation
0066 // of the edge(u,v,g) functions.
0067 //
0068 // TODO: It might be worthwhile to provide functionality for passing
0069 // a connectivity matrix to improve the efficiency of those lookups
0070 // when needed. This could simply be passed as a BooleanMatrix
0071 // s.t. edge(u,v,B) returns true or false. This could easily be
0072 // abstracted for adjacency matricies.
0073 //
0074 // The following paper is interesting for a number of reasons. First,
0075 // it lists a number of other such algorithms and second, it describes
0076 // a new algorithm (that does not appear to require the edge(u,v,g)
0077 // function and appears fairly efficient. It is probably worth investigating.
0078 //
0079 //      @article{DBLP:journals/tcs/TomitaTT06,
0080 //          author = {Etsuji Tomita and Akira Tanaka and Haruhisa Takahashi},
0081 //          title = {The worst-case time complexity for generating all maximal
0082 //          cliques and computational experiments}, journal = {Theor. Comput.
0083 //          Sci.}, volume = {363}, number = {1}, year = {2006}, pages = {28-42}
0084 //          ee = {https://doi.org/10.1016/j.tcs.2006.06.015}
0085 //      }
0086
0087 /**
0088  * The default clique_visitor supplies an empty visitation function.
0089  */
0090 struct clique_visitor
0091 {
0092     template < typename VertexSet, typename Graph >
0093     void clique(const VertexSet&, Graph&)
0094     {
0095     }
0096 };
0097
0098 /**
0099  * The max_clique_visitor records the size of the maximum clique (but not the
0100  * clique itself).
0101  */
0102 struct max_clique_visitor
0103 {
0104     max_clique_visitor(std::size_t& max) : maximum(max) {}
0105
0106     template < typename Clique, typename Graph >
0107     inline void clique(const Clique& p, const Graph& g)
0108     {
0109         BOOST_USING_STD_MAX();
0110         maximum = max BOOST_PREVENT_MACRO_SUBSTITUTION(maximum, p.size());
0111     }
0112     std::size_t& maximum;
0113 };
0114
0115 inline max_clique_visitor find_max_clique(std::size_t& max)
0116 {
0117     return max_clique_visitor(max);
0118 }
0119
0120 namespace detail
0121 {
0122     template < typename Graph >
0123     inline bool is_connected_to_clique(const Graph& g,
0124         typename graph_traits< Graph >::vertex_descriptor u,
0125         typename graph_traits< Graph >::vertex_descriptor v,
0126         typename graph_traits< Graph >::undirected_category)
0127     {
0128         return lookup_edge(u, v, g).second;
0129     }
0130
0131     template < typename Graph >
0132     inline bool is_connected_to_clique(const Graph& g,
0133         typename graph_traits< Graph >::vertex_descriptor u,
0134         typename graph_traits< Graph >::vertex_descriptor v,
0135         typename graph_traits< Graph >::directed_category)
0136     {
0137         // Note that this could alternate between using an || to determine
0138         // full connectivity. I believe that this should produce strongly
0139         // connected components. Note that using && instead of || will
0140         // change the results to a fully connected subgraph (i.e., symmetric
0141         // edges between all vertices s.t., if a->b, then b->a.
0142         return lookup_edge(u, v, g).second && lookup_edge(v, u, g).second;
0143     }
0144
0145     template < typename Graph, typename Container >
0146     inline void filter_unconnected_vertices(const Graph& g,
0147         typename graph_traits< Graph >::vertex_descriptor v,
0148         const Container& in, Container& out)
0149     {
0150         BOOST_CONCEPT_ASSERT((GraphConcept< Graph >));
0151
0152         typename graph_traits< Graph >::directed_category cat;
0153         typename Container::const_iterator i, end = in.end();
0154         for (i = in.begin(); i != end; ++i)
0155         {
0156             if (is_connected_to_clique(g, v, *i, cat))
0157             {
0158                 out.push_back(*i);
0159             }
0160         }
0161     }
0162
0163     template < typename Graph,
0164         typename Clique, // compsub type
0165         typename Container, // candidates/not type
0166         typename Visitor >
0167     void extend_clique(const Graph& g, Clique& clique, Container& cands,
0168         Container& nots, Visitor vis, std::size_t min)
0169     {
0170         BOOST_CONCEPT_ASSERT((GraphConcept< Graph >));
0171         BOOST_CONCEPT_ASSERT((CliqueVisitorConcept< Visitor, Clique, Graph >));
0172         typedef typename graph_traits< Graph >::vertex_descriptor Vertex;
0173
0174         // Is there vertex in nots that is connected to all vertices
0175         // in the candidate set? If so, no clique can ever be found.
0176         // This could be broken out into a separate function.
0177         {
0178             typename Container::iterator ni, nend = nots.end();
0179             typename Container::iterator ci, cend = cands.end();
0180             for (ni = nots.begin(); ni != nend; ++ni)
0181             {
0182                 for (ci = cands.begin(); ci != cend; ++ci)
0183                 {
0184                     // if we don't find an edge, then we're okay.
0185                     if (!lookup_edge(*ni, *ci, g).second)
0186                         break;
0187                 }
0188                 // if we iterated all the way to the end, then *ni
0189                 // is connected to all *ci
0190                 if (ci == cend)
0191                     break;
0192             }
0193             // if we broke early, we found *ni connected to all *ci
0194             if (ni != nend)
0195                 return;
0196         }
0197
0198         // TODO: the original algorithm 457 describes an alternative
0199         // (albeit really complicated) mechanism for selecting candidates.
0200         // The given optimizaiton seeks to bring about the above
0201         // condition sooner (i.e., there is a vertex in the not set
0202         // that is connected to all candidates). unfortunately, the
0203         // method they give for doing this is fairly unclear.
0204
0205         // basically, for every vertex in not, we should know how many
0206         // vertices it is disconnected from in the candidate set. if
0207         // we fix some vertex in the not set, then we want to keep
0208         // choosing vertices that are not connected to that fixed vertex.
0209         // apparently, by selecting fix point with the minimum number
0210         // of disconnections (i.e., the maximum number of connections
0211         // within the candidate set), then the previous condition wil
0212         // be reached sooner.
0213
0214         // there's some other stuff about using the number of disconnects
0215         // as a counter, but i'm jot really sure i followed it.
0216
0217         // TODO: If we min-sized cliques to visit, then theoretically, we
0218         // should be able to stop recursing if the clique falls below that
0219         // size - maybe?
0220
0221         // otherwise, iterate over candidates and and test
0222         // for maxmimal cliquiness.
0223         typename Container::iterator i, j;
0224         for (i = cands.begin(); i != cands.end();)
0225         {
0226             Vertex candidate = *i;
0227
0228             // add the candidate to the clique (keeping the iterator!)
0229             // typename Clique::iterator ci = clique.insert(clique.end(),
0230             // candidate);
0231             clique.push_back(candidate);
0232
0233             // remove it from the candidate set
0234             i = cands.erase(i);
0235
0236             // build new candidate and not sets by removing all vertices
0237             // that are not connected to the current candidate vertex.
0238             // these actually invert the operation, adding them to the new
0239             // sets if the vertices are connected. its semantically the same.
0240             Container new_cands, new_nots;
0241             filter_unconnected_vertices(g, candidate, cands, new_cands);
0242             filter_unconnected_vertices(g, candidate, nots, new_nots);
0243
0244             if (new_cands.empty() && new_nots.empty())
0245             {
0246                 // our current clique is maximal since there's nothing
0247                 // that's connected that we haven't already visited. If
0248                 // the clique is below our radar, then we won't visit it.
0249                 if (clique.size() >= min)
0250                 {
0251                     vis.clique(clique, g);
0252                 }
0253             }
0254             else
0255             {
0256                 // recurse to explore the new candidates
0257                 extend_clique(g, clique, new_cands, new_nots, vis, min);
0258             }
0259
0260             // we're done with this vertex, so we need to move it
0261             // to the nots, and remove the candidate from the clique.
0262             nots.push_back(candidate);
0263             clique.pop_back();
0264         }
0265     }
0266 } /* namespace detail */
0267
0268 template < typename Graph, typename Visitor >
0269 inline void bron_kerbosch_all_cliques(
0270     const Graph& g, Visitor vis, std::size_t min)
0271 {
0272     BOOST_CONCEPT_ASSERT((IncidenceGraphConcept< Graph >));
0273     BOOST_CONCEPT_ASSERT((VertexListGraphConcept< Graph >));
0274     BOOST_CONCEPT_ASSERT(
0275         (AdjacencyMatrixConcept< Graph >)); // Structural requirement only
0276     typedef typename graph_traits< Graph >::vertex_descriptor Vertex;
0277     typedef typename graph_traits< Graph >::vertex_iterator VertexIterator;
0278     typedef std::vector< Vertex > VertexSet;
0279     typedef std::deque< Vertex > Clique;
0280     BOOST_CONCEPT_ASSERT((CliqueVisitorConcept< Visitor, Clique, Graph >));
0281
0282     // NOTE: We're using a deque to implement the clique, because it provides
0283     // constant inserts and removals at the end and also a constant size.
0284
0285     VertexIterator i, end;
0286     boost::tie(i, end) = vertices(g);
0287     VertexSet cands(i, end); // start with all vertices as candidates
0288     VertexSet nots; // start with no vertices visited
0289
0290     Clique clique; // the first clique is an empty vertex set
0291     detail::extend_clique(g, clique, cands, nots, vis, min);
0292 }
0293
0294 // NOTE: By default the minimum number of vertices per clique is set at 2
0295 // because singleton cliques aren't really very interesting.
0296 template < typename Graph, typename Visitor >
0297 inline void bron_kerbosch_all_cliques(const Graph& g, Visitor vis)
0298 {
0299     bron_kerbosch_all_cliques(g, vis, 2);
0300 }
0301
0302 template < typename Graph >
0303 inline std::size_t bron_kerbosch_clique_number(const Graph& g)
0304 {
0305     std::size_t ret = 0;
0306     bron_kerbosch_all_cliques(g, find_max_clique(ret));
0307     return ret;
0308 }
0309
0310 } /* namespace boost */
0311
0312 #endif