Compressed Sparse Row Graph

The class template compressed_sparse_row_graph is
a graph class that uses the compact Compressed Sparse Row (CSR)
format to store directed (and bidirectional) graphs. While CSR graphs have
much less
overhead than many other graph formats (e.g., adjacency_list), they
do not provide any mutability: one cannot add or remove vertices
or edges from a CSR graph. Use this format in high-performance
applications or for very large graphs that you do not need to
change.

The CSR format stores vertices and edges in separate arrays,
with the indices into these arrays corresponding to the identifier
for the vertex or edge, respectively. The edge array is sorted by
the source of each edge, but contains only the targets for the
edges. The vertex array stores offsets into the edge array,
providing the offset of the first edge outgoing from each
vertex. Iteration over the out-edges for the ith
vertex in the graph is achieved by
visiting edge_array[vertex_array[i]],
edge_array[vertex_array[i]+1],
..., edge_array[vertex_array[i+1]]. This format minimizes
memory use to O(n + m), where n and m are the
number of vertices and edges, respectively. The constants
multiplied by n and m are based on the size of the
integers needed to represent indices into the edge and vertex
arrays, respectively, which can be controlled using
the template parameters. The
Directed template parameter controls whether one edge direction
(the default) or both directions are stored. A directed CSR graph has
Directed = directedS and a bidirectional CSR graph (with
a limited set of constructors)
has Directed = bidirectionalS.

Where Defined

Models

The compressed_sparse_row_graph class template models
(i.e., implements the requirements of) many of the
BGL graph concepts, allowing it
to be used with most of the BGL algorithms. In particular, it
models the following specific graph concepts:

Template Parameters

The compressed_sparse_row_graph class has several
template parameters that can customize the layout in memory and
what properties are attached to the graph itself. All
parameters have defaults, so users interested only in the
structure of a graph can use the
type compressed_sparse_row_graph<> and ignore
the parameters.

Parameters

Directed

A selector that determines whether the graph will be directed,
bidirectional or undirected. At this time, the CSR graph type
only supports directed and bidirectional graphs, so this value must
be either boost::directedS or
boost::bidirectionalS.Default: boost::directedS

VertexProperty

A class type that will be
attached to each vertex in the graph. If this value
is void, no properties will be attached to
the vertices of the graph.Default: void

EdgeProperty

A class type that will be attached to each edge in the graph. If
this value is void, no properties will be
attached to the edges of the graph.Default: void

GraphProperty

A nested set
of property templates that describe the
properties of the graph itself. If this value
is no_property, no properties will be attached to
the graph.Default: no_property

Vertex

An unsigned integral type that will be
used as both the index into the array of vertices and as the
vertex descriptor itself. Larger types permit the CSR graph to
store more vertices; smaller types reduce the storage required
per vertex.Default: std::size_t

EdgeIndex

An unsigned integral type that will be used as the index into
the array of edges. As with the Vertex parameter,
larger types permit more edges whereas smaller types reduce
the amount of storage needed per
edge. The EdgeIndex type shall not be smaller
than the Vertex type, but it may be larger. For
instance, Vertex may be a 16-bit integer
(allowing 32,767 vertices in the graph)
whereas EdgeIndex could then be a 32-bit integer
to allow a complete graph to be stored in the CSR format.Default: Vertex

Interior Properties

The compressed_sparse_row_graph allows properties to
be attached to its vertices, edges, or to the graph itself by way
of its template parameters. These
properties may be accessed via
the member
and non-member property
access functions, using the bundled
properties scheme.

The CSR graph provides two kinds of built-in
properties: vertex_index, which maps from vertices to
values in [0, n) and edge_index, which maps
from edges to values in [0, m), where n
and m are the number of vertices and edges in the graph,
respectively.

Constructs a graph with numverts vertices whose
edges are specified by the iterator range [edge_begin,
edge_end). The InputIterator must be a model of
InputIterator
whose value_type is an std::pair of
integer values. These integer values are the source and target
vertices for the edges, and must fall within the range [0,
numverts). The edges in [edge_begin,
edge_end) do not need to be sorted. This constructor uses extra
memory to save the edge information before adding it to the graph,
avoiding the requirement for the iterator to have multi-pass capability.

This constructor constructs a graph with numverts
vertices and the edges provided in the iterator range
[edge_begin, edge_end). Its semantics are identical
to the edge range constructor, except
that edge properties are also initialized. The type
EdgePropertyIterator must be a model of the InputIterator
concept whose value_type is convertible to
EdgeProperty. The iterator range [ep_iter, ep_ter +
m) will be used to initialize the properties on the edges
of the graph, where m is distance from
edge_begin to edge_end. This constructor uses extra
memory to save the edge information before adding it to the graph,
avoiding the requirement for the iterator to have multi-pass capability.

Constructs a graph with numverts vertices whose
edges are specified by the iterator range [edge_begin,
edge_end). The MultiPassInputIterator must be a model of
MultiPassInputIterator
whose value_type is an std::pair of
integer values. These integer values are the source and target
vertices for the edges, and must fall within the range [0,
numverts). The edges in [edge_begin,
edge_end) do not need to be sorted. Multiple passes will be made
over the edge range.

This constructor constructs a graph with numverts
vertices and the edges provided in the iterator range
[edge_begin, edge_end). Its semantics are identical
to the edge range constructor, except
that edge properties are also initialized. The type
EdgePropertyIterator must be a model of the MultiPassInputIterator
concept whose value_type is convertible to
EdgeProperty. The iterator range [ep_iter, ep_ter +
m) will be used to initialize the properties on the edges
of the graph, where m is distance from
edge_begin to edge_end. Multiple passes will be made
over the edge and property ranges.

Constructs a graph with numverts vertices whose
edges are specified by the iterator range [edge_begin,
edge_end). The argument of type edges_are_sorted_t is
a tag used to distinguish this constructor; the value
edges_are_sorted can be used to initialize this parameter.
The InputIterator must be a model of
InputIterator
whose value_type is an std::pair of
integer values. These integer values are the source and target
vertices for the edges, and must fall within the range [0,
numverts). The edges in [edge_begin,
edge_end) must be sorted so that all edges originating
from vertex i preceed any edges originating from all
vertices j where j > i.

The value numedges, if provided, tells how many
edges are in the range [edge_begin, edge_end) and
will be used to preallocate data structures to save both memory
and time during construction.

This constructor constructs a graph with numverts
vertices and the edges provided in the iterator range
[edge_begin, edge_end). Its semantics are identical
to the edge range constructor, except
that edge properties are also initialized. The type
EdgePropertyIterator must be a model of the InputIterator
concept whose value_type is convertible to
EdgeProperty. The iterator range [ep_iter, ep_ter +
m) will be used to initialize the properties on the edges
of the graph, where m is distance from
edge_begin to edge_end.

This constructor constructs a graph with numverts vertices
and the edges provided in the two vectors sources and
targets. The two vectors are mutated in-place to sort them
by source vertex. They are returned with unspecified values, but do not
share storage with the constructed graph (and so are safe to destroy).
The parameter prop, if provided, is used to initialize the
graph property.

This constructor constructs a graph with numverts vertices
and the edges provided in the two vectors sources and
targets. Edge properties are initialized from the vector
edge_props. The three vectors are mutated in-place to sort
them by source vertex. They are returned with unspecified values, but do
not share storage with the constructed graph (and so are safe to
destroy). The parameter prop, if provided, is used to
initialize the graph property.

Edge access

If there exists an edge (u, v) in the graph, returns the
descriptor for that edge and true; otherwise, the
second value in the pair will be false. If multiple
edges exist from u to v, the first edge will
be returned; use out_edges and a
conditional statement
to retrieve all edges to a given target. This function requires linear
time in the
number of edges outgoing from u.

This sets the property value for x to
value. x is either a vertex or edge
descriptor. Value must be convertible to typename
property_traits<property_map<compressed_sparse_row_graph,
PropertyTag>::type&gt::value_type

Add a range of edges (from first to last) to the graph.
The InputIterator must be a model of InputIterator
whose value_type is an std::pair of integer
values. These integer values are the source and target vertices of the
new edges. The edges do not need to be sorted.

Add a range of edges (from first to last) with
corresponding edge properties (from ep_first to
ep_last) to the graph. The InputIterator and
EPIter must be models of InputIterator;
the value_type of InputIterator must be an
std::pair of integer values, and the value_type
of EPIter must be the edge property type of the graph. The
integer values produced by the InputIterator are the source and
target vertices of the new edges. The edges do not need to be sorted.

Add a range of edges (from first to last) to the graph.
The BidirectionalIterator must be a model of BidirectionalIterator
whose value_type is an std::pair of integer
values. These integer values are the source and target vertices of the
new edges. The edges must be sorted in increasing order by source vertex
index.

Add a range of edges (from first to last) to the graph.
The BidirectionalIterator and EPIter must be models of
BidirectionalIterator.
The value_type of the BidirectionalIterator must be
an std::pair of integer
values. These integer values are the source and target vertices of the
new edges.
The value_type of the EPIter must be the edge
property type of the graph.
The edges must be sorted in increasing order by source vertex
index.

Example

We will use the compressed_sparse_row_graph graph
class to store a simple Web graph. In this web graph the vertices
represent web pages and the edges represent links from one web
page to another. With each web page we want to associate a URL, so
we initially create a WebPage class that stores the
URL. Then we can create our graph type by providing
WebPage as a parameter to the
compressed_sparse_row_graph class template.