This documentation is being rewritten. If something looks off, please cross-check with the Boost 1.91.0 Boost.Graph docs and open an issue.

Subgraph

An induced subgraph with a hierarchical parent/child structure.

Defined in: <boost/graph/subgraph.hpp>
Models: VertexMutableGraph, EdgeMutableGraph (plus whatever the underlying graph models: VertexListGraph, EdgeListGraph, BidirectionalGraph, etc.)

The underlying graph type must have both vertex_index and edge_index internal properties. Edge indices are assigned by the subgraph class.

Example

#include <boost/graph/adjacency_list.hpp>
#include <boost/graph/subgraph.hpp>
#include <iostream>

int main() {
    using namespace boost;
    // subgraph requires edge_index_t as an internal property tag
    using Graph = subgraph<adjacency_list<vecS, vecS, directedS,
        no_property, property<edge_index_t, int>>>;

    // Root graph: 5 vertices, 6 edges
    Graph root(5);
    add_edge(0, 1, root);
    add_edge(1, 2, root);
    add_edge(2, 3, root);
    add_edge(3, 4, root);
    add_edge(4, 0, root);
    add_edge(1, 3, root);

    // Create a subgraph containing vertices {1, 2, 3}
    Graph& sub = root.create_subgraph();
    add_vertex(1, sub);  // global vertex 1
    add_vertex(2, sub);  // global vertex 2
    add_vertex(3, sub);  // global vertex 3

    std::cout << "Root: " << num_vertices(root) << " vertices, "
              << num_edges(root) << " edges\n";
    std::cout << "Subgraph: " << num_vertices(sub) << " vertices, "
              << num_edges(sub) << " edges\n\n";

    std::cout << "Subgraph edges (local descriptors):\n";
    for (auto ei = edges(sub).first; ei != edges(sub).second; ++ei) {
        auto s = sub.local_to_global(source(*ei, sub));
        auto t = sub.local_to_global(target(*ei, sub));
        std::cout << "  " << s << " -> " << t << "\n";
    }
}
Root: 5 vertices, 6 edges
Subgraph: 3 vertices, 3 edges

Subgraph edges (local descriptors):
  1 -> 2
  1 -> 3
  2 -> 3

Synopsis

template <typename Graph>
class subgraph;

The subgraph class wraps an adjacency_list and maintains a tree of subgraphs. The root graph owns all vertices and edges. Child subgraphs hold subsets of the root’s vertices, and their edge sets are induced: any edge in the root whose both endpoints are in the child automatically appears in the child.

Each subgraph uses local descriptors (0-based within that subgraph). Use local_to_global() and global_to_local() to convert between local and root descriptors.

Adding an edge to a child subgraph also adds it to all ancestor subgraphs. Adding a vertex to a child subgraph also adds it to all ancestors.

Template Parameters

Parameter Description

Graph

Must model VertexMutableGraph and EdgeMutableGraph. Must have internal vertex_index and edge_index properties. With vecS for the vertex container, vertex_index is automatic. edge_index must always be declared explicitly:

adjacency_list<vecS, vecS, directedS, no_property, property<edge_index_t, int>>

Member Functions

Constructors

subgraph(vertices_size_type n,
         const GraphProperty& p = GraphProperty());

Create a root graph with n vertices and no edges.

Subgraph Creation

subgraph& create_subgraph();

Create an empty child subgraph.


template <typename VertexIterator>
subgraph& create_subgraph(VertexIterator first, VertexIterator last);

Create a child subgraph with the given vertices. Edges are induced from the parent.

Descriptor Conversion

vertex_descriptor local_to_global(vertex_descriptor u_local) const;
vertex_descriptor global_to_local(vertex_descriptor u_global) const;
edge_descriptor local_to_global(edge_descriptor e_local) const;
edge_descriptor global_to_local(edge_descriptor e_global) const;

Convert between local (subgraph-relative) and global (root) descriptors.


std::pair<vertex_descriptor, bool>
find_vertex(vertex_descriptor u_global) const;

Returns (local_descriptor, true) if the global vertex is in this subgraph, (_, false) otherwise.

Hierarchy Navigation

subgraph& root();
bool is_root() const;
subgraph& parent();
std::pair<children_iterator, children_iterator> children() const;

Navigate the subgraph tree. root() returns the top-level graph. parent() returns the direct parent. children() iterates over child subgraphs.

Non-Member Functions

Structure Access

Standard graph functions: vertices(), edges(), out_edges(), in_edges(), adjacent_vertices(), source(), target(), out_degree(), in_degree(), num_vertices(), num_edges(), edge(). All operate on local descriptors.

Structure Modification

remove_vertex() is not implemented (commented out in the source). Calling it will not compile. If you need to hide vertices, use filtered_graph on top of the subgraph.
vertex_descriptor add_vertex(subgraph& g);

Add a new vertex to the subgraph (and all ancestors up to root).


vertex_descriptor add_vertex(vertex_descriptor u_global, subgraph& g);

Add an existing global vertex to this subgraph. The vertex must already exist in the parent.


std::pair<edge_descriptor, bool>
add_edge(vertex_descriptor u, vertex_descriptor v, subgraph& g);

Add an edge between local vertices u and v. The edge is also added to all ancestor subgraphs.


void remove_edge(vertex_descriptor u, vertex_descriptor v, subgraph& g);
void remove_edge(edge_descriptor e, subgraph& g);

Remove an edge from the subgraph.

Property Map Access

Property maps operate on local descriptors. Changes to properties through a subgraph are visible from all other subgraphs and the root, because all subgraphs share the same underlying property storage.

template <typename PropertyTag>
property_map<subgraph, PropertyTag>::type
get(PropertyTag, subgraph& g);

For bundled properties, use the local() and global() wrappers to disambiguate:

auto lvm = get(local(&Node::value), sg);    // local subgraph property
auto gvm = get(global(&Node::value), sg);   // root graph property

Associated Types

Type Description

vertex_descriptor

Local descriptor within this subgraph.

edge_descriptor

Local descriptor within this subgraph.

children_iterator

Iterator for accessing child subgraphs.

All other types

Same as the underlying Graph type.