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.

GraphViz (DOT)

Read and write graphs in the GraphViz DOT format.

Defined in <boost/graph/graphviz.hpp>
Linking: requires libboost_graph

By default, dynamic_properties throws property_not_found if the file contains an attribute that was not registered. To silently skip unknown attributes, pass ignore_other_properties to the constructor: 
dynamic_properties dp(ignore_other_properties);
// All other attributes in the file are silently ignored

Example

#include <boost/graph/adjacency_list.hpp>
#include <boost/graph/graphviz.hpp>
#include <iostream>
#include <sstream>

struct City { std::string name; };
struct Road { double weight; };

int main() {
    using namespace boost;
    using Graph = adjacency_list<vecS, vecS, directedS, City, Road>;

    // --- Write ---
    Graph g(3);
    g[0].name = "A";
    g[1].name = "B";
    g[2].name = "C";
    add_edge(0, 1, Road{1.5}, g);
    add_edge(1, 2, Road{2.5}, g);
    add_edge(0, 2, Road{4.0}, g);

    dynamic_properties dp;
    dp.property("node_id", get(&City::name, g));
    dp.property("weight", get(&Road::weight, g));

    std::ostringstream dot;
    write_graphviz_dp(dot, g, dp, "node_id");
    std::cout << "=== DOT output ===\n" << dot.str();

    // --- Read back ---
    Graph g2;
    dynamic_properties dp2;
    dp2.property("node_id", get(&City::name, g2));
    dp2.property("weight", get(&Road::weight, g2));

    std::istringstream in(dot.str());
    read_graphviz(in, g2, dp2, "node_id");

    std::cout << "=== Read back ===\n";
    std::cout << num_vertices(g2) << " vertices, "
              << num_edges(g2) << " edges\n";
}
=== DOT output ===
digraph G {
A;
B;
C;
A->B  [weight=1.5];
A->C  [weight=4];
B->C  [weight=2.5];
}
=== Read back ===
3 vertices, 3 edges

read_graphviz

(1) From stream

template <typename MutableGraph>
bool read_graphviz(std::istream& in, MutableGraph& graph,
                   dynamic_properties& dp,
                   const std::string& node_id = "node_id");

(2) From string

template <typename MutableGraph>
bool read_graphviz(const std::string& data, MutableGraph& graph,
                   dynamic_properties& dp,
                   const std::string& node_id = "node_id");

(3) From iterator range

template <typename InputIterator, typename MutableGraph>
bool read_graphviz(InputIterator begin, InputIterator end,
                   MutableGraph& graph, dynamic_properties& dp,
                   const std::string& node_id = "node_id");
Direction Parameter Description

IN

in / data / begin,end

DOT-formatted input (stream, string, or iterator range)

OUT

MutableGraph& graph

Populated graph. Must model MutableGraph. Directionality must match the DOT keyword (digraph vs graph).

IN/OUT

dynamic_properties& dp

Maps attribute names to property maps. Unspecified attributes get default-constructed values.

IN

node_id

Name of the property map used as vertex identifier. Default: "node_id".

Returns true on success.

write_graphviz

(1) With property writers

template <typename Graph>
void write_graphviz(std::ostream& out, const Graph& g);

template <typename Graph, typename VertexWriter>
void write_graphviz(std::ostream& out, const Graph& g,
                    VertexWriter vw);

template <typename Graph, typename VertexWriter, typename EdgeWriter>
void write_graphviz(std::ostream& out, const Graph& g,
                    VertexWriter vw, EdgeWriter ew);

template <typename Graph, typename VertexWriter,
          typename EdgeWriter, typename GraphWriter>
void write_graphviz(std::ostream& out, const Graph& g,
                    VertexWriter vw, EdgeWriter ew,
                    GraphWriter gw);

template <typename Graph, typename VertexWriter,
          typename EdgeWriter, typename GraphWriter, typename VertexID>
void write_graphviz(std::ostream& out, const Graph& g,
                    VertexWriter vw, EdgeWriter ew,
                    GraphWriter gw, VertexID vertex_id);

Each writer is a functor called with (std::ostream&, descriptor) for vertices/edges, or (std::ostream&) for the graph. It should output DOT attribute syntax: [name1=value1, name2=value2].

Use default_writer() to skip a writer. The convenience function make_label_writer(name_map) creates a writer that emits [label="…​"]:

write_graphviz(std::cout, g, make_label_writer(get(vertex_name, g)));
The default overloads use get(vertex_index, g) for vertex IDs. If your graph uses listS for the vertex container (no built-in vertex index), you must pass an explicit vertex_id map using the last overload.

(2) With dynamic_properties

template <typename Graph>
void write_graphviz_dp(std::ostream& out, const Graph& g,
                       const dynamic_properties& dp,
                       const std::string& node_id = "node_id");

template <typename Graph, typename VertexID>
void write_graphviz_dp(std::ostream& out, const Graph& g,
                       const dynamic_properties& dp,
                       const std::string& node_id,
                       VertexID vertex_id);

Emits all properties registered in dp. This is the natural counterpart to read_graphviz: a round-trip preserves all attributes.

The node_id parameter names the property map in dp that stores vertex identifiers. The second overload accepts an explicit vertex_id map for graphs without a built-in vertex index.

Throws

Exception When

bad_graphviz_syntax

The input is not valid DOT

directed_graph_error

DOT says digraph but graph type is undirected

undirected_graph_error

DOT says graph but graph type is directed

bad_parallel_edge

DOT contains a parallel edge but graph type does not allow them (e.g. adjacency_list<setS, …​>)

property_not_found

The DOT file contains an attribute not registered in dynamic_properties (see ignore_other_properties above)

Subgraphs

DOT subgraphs are treated as syntactic sugar. They do not create BGL subgraph objects. They are used to shorten edge definitions and apply shared properties. For example:

digraph { a -> subgraph {b -> c} -> e }

is equivalent to:

digraph { a -> b -> e ; a -> c -> e ; b -> c }

Subgraph IDs refer to subgraphs defined earlier in the file. An undefined subgraph ID is treated as an empty subgraph {}.

Edit this Page