Choosing the Edgelist and VertexList

This section focuses on how to decide which version of the adjacency_list class to use
in different situations. The adjacency_list is like a
swiss-army knife in that it can be configured in many ways. The
parameters that we will focus on in this section are EdgeList
and VertexList, which control the underlying data structures
that will be used to represent the graph. The choice of
EdgeList and VertexList affects the time complexity
of many of the graph operations and the space complexity of the graph
object.

BGL uses containers from the STL such as
std::vector,
std::list,
and std::set
to represent the set of vertices and the adjacency structure
(out-edges and in-edges) of the graph. There are several selector
types that are used to specify the choice of container for
EdgeList and VertexList.

vecS selects std::vector.

listS selects std::list.

slistS selects std::slist.

setS selects std::set.

multisetS selects std::multiset.

hash_setS selects std::hash_set.

Choosing the VertexList type

The VertexList parameter determines what kind of container
will be used to represent the vertex set, or two-dimensional structure
of the graph. The container must model Sequence or
RandomAccessContainer. In
general, listS is a good choice if you need to add and remove
vertices quickly. The price for this is extra space overhead compared
to choosing vecS.

Space Complexity

The std::list has a higher per-vertex space overhead than the
std::vector, storing three extra pointers per vertex.

Time Complexity

The choice of VertexList affects the time complexity of the
following operations.

add_vertex()

This operation is amortized constant time for both vecS and
listS (implemented with push_back()). However, when
the VertexList type is vecS the time for this
operation is occasionally large because the vector will be
reallocated and the whole graph copied.

remove_vertex()

This operation is constant time for listS and O(V + E) for
vecS. The large time complexity for vecS is because
the vertex descriptors (which in this case are indices that correspond
to the vertices' place in the vertex list) must be adjusted in the
out-edges for the whole graph.

The EdgeList parameter determines what kind of container will
be used to store the out-edges (and possibly in-edges) for each vertex
in the graph. The containers used for edge lists must either satisfy
the requirements for Sequence or for
AssociativeContainer.

One of the first things to consider when choosing the
EdgeList is whether you want adjacency_list to
enforce the absence of parallel edges in the graph (that is, enforce
that the graph not become a multi-graph). If you want this enforced
then use the setS or hash_setS selectors. If you
want to represent a multi-graph, or know that you will not be
inserting parallel edges into the graph, then choose one of the Sequence
types: vecS, listS, or slistS.
You will also want to take into account the differences in time and space
complexity for the various graph operations. Below we use V for
the total number of vertices in the graph and E for the total
number of edges. Operations not discussed here are constant time.

Space Complexity

The selection of the EdgeList affects the amount of space
overhead per edge in the graph object. In the order of least space to
most space, the selectors are vecS, slistS,
listS, and setS.

Time Complexity

In the following description of the time complexity for various
operations, we use E/V inside of the ``big-O'' notation to
express the length of an out-edge list. Strictly speaking this is not
accurate because E/V merely gives the average number of edges
per vertex in a random graph. The worst-case number of out-edges for a
vertex is V (unless it is a multi-graph). For sparse graphs
E/V is typically much smaller than V and can be
considered a constant.

add_edge()

When the EdgeList is a UniqueAssociativeContainer
like std::set the absence of parallel edges is enforced when
an edge is added. The extra lookup involved has time complexity
O(log(E/V)). The EdgeList types that model Sequence do
not perform this check and therefore add_edge() is amortized
constant time. This means that it if you don't care whether the graph
has parallel edges, or know that the input to the graph does not
contain them, then it is better to use the sequence-based
EdgeList. The add_edge() for the sequence-based
EdgeList is implemented with push_front() or
push_back(). However, for std::list and
std::slist this operation will typically be faster than with
std::vector which occasionally reallocates and copies all
elements.

remove_edge()

For sequence-based EdgeList types this operation is
implemented with std::remove_if() which means the average
time is E/V. For set-based EdgeList types this is
implemented with the erase() member function, which has
average time log(E/V).

edge()

The time complexity for this operation is O(E/V) when the
EdgeList type is a Sequence and it
is O(log(E/V)) when the EdgeList type is an AssociativeContainer.

clear_vertex()

For directed graphs with sequence-based EdgeList types the time
complexity is O(V + E), while for associative container based
EdgeList types the operation is faster, with time complexity
O(V log(E/V)). For undirected graphs this operation is
O(E2/V2) or O(E/V log(E/V)).

remove_vertex()

The time complexity for this operation is O(V + E) regardless of the
EdgeList type.

out_edge_iterator::operator++()

This operation is constant time for all the OneD types.
However, there is a significant constant factor time difference
between the various types, which is important since this operation is
the work-horse of most graph algorithms. The speed of
this operation in order of fastest to slowest is
vecS, slistS, listS, setS,
hash_setS.

in_edge_iterator::operator++()

This operation is constant time and exhibits a similar speed
ordering as the out_edge_iterator with respect to
the EdgeList selection.

vertex_iterator::operator++()

This operation is constant time and fast (same speed as incrementing a
pointer). The selection of OneD does not affect the speed of
this operation.

edge_iterator::operator++()

This operation is constant time and exhibits a similar speed ordering
as the out_edge_iterator with respect to the EdgeList
selection. Traversing through the whole edge set is O(V + E).

adjacency_iterator::operator++()

This operation is constant time and exhibits a similar speed
ordering as the out_edge_iterator with respect to
the EdgeList selection.

The adjacency_list class can be used to represent both
directed and undirected graphs, depending on the argument passed to
the Directed template parameter. Selecting directedS
or bidirectionalS choose a directed graph, whereas
undirectedS selects the representation for an undirected
graph. See Section Undirected Graphs
for a description of the difference between directed and undirected
graphs in BGL. The bidirectealS selector specifies that the
graph will provide the in_edges() function as well as the
out_edges() function. This imposes twice as much space
overhead per edge, which is why in_edges() is optional.

Internal Properties

Properties can be attached to the vertices or edges of an
adjacency_list graph via the property interface. The template
parameters VertexProperty and EdgeProperty of the
adjacency_list class are meant to be filled by the property
class, which is declared as follows.

The T template parameter of property
specifies the type of the property values. The type T must be
Default
Constructible, Assignable, and Copy Constructible.
Like the containers of the C++ Standard Library, the property objects
of type T are held by-value inside of the graph.

The NextProperty parameter allows property
types to be nested, so that an arbitrary number of properties can be
attached to the same graph.

The following code shows how a vertex and edge property type can be
assembled and used to create a graph type. We have attached a distance
property with values of type float and a name property with
values of type std::string to the vertices of the graph. We
have attached a weight property with values of type float to
the edges of the graph.

The property values are then read from and written to using property
maps. See Section Interior
Properties for a description of how to obtain property maps
from a graph, and read Section Property Maps for how
to use property maps.

Custom Edge Properties

Creating a your own property types and properties is easy; just define
a tag class for your new property. The property tag class will need to
define num with a unique integer ID, and kind which
should be either edge_property_tag,
vertex_property_tag, or graph_property_tag,.

You can also use enum's instead of struct's to create tag types.
Create an enum type for each property. The first part of the name of
the enum type must be edge, vertex, or
graph followed by an underscore, with a _t at the
end. Inside the enum, define a value with the same name minus the
_t. Then invoke the BOOST_INSTALL_PROPERTY macro.

The file edge_property.cpp shows the complete source
code for this example.

Custom Vertex Properties

Creating your own properties to attach to vertices is just as easy as
for edges. Here we want to attach people's first names to the vertices
in the graph.

struct first_vertex_name_t {
typedef vertex_property_tag kind;
};

Now we can use the new tag in the property class and use that in
the assembly of a graph type. The following code shows creating the
graph type, and then creating the graph object. We fill in the edges
and also assign names to the vertices. The edges will represent ``who
owes who''.

The who_owes_who() function written for this example was
implemented in a generic style. The input is templated so we do not
know the actual graph type. To find out the type of the property
map for our first name property, we need to use the
property_map traits class. The const_type
is used since the graph parameter is const. Once we have the property
map type, we can deduce the value type of the property using the
property_traits class. In this example, we know that the
property's value type will be std::string, but written in this
generic fashion the who_owes_who() function could work with
other property value types.

The complete source code to this example is in the file
interior_property_map.cpp.

Customizing the Adjacency List Storage

The adjacency_list is constructed out of two kinds of
containers. One type of container to hold all the vertices in the
graph, and another type of container for the out-edge list (and
potentially in-edge list) for each vertex. BGLprovides selector
classes that allow the user to choose between several of the container
from the STL. It is also possible to use your own container types.
When customizing the VertexList you need to define a container
generator as described below. When customizing the EdgeList you
will need to define a container generator and the parallel edge
traits. The file container_gen.cpp has an example of
how to use a custom storage types.

The adjacency_list class uses a traits class called
container_gen to map the EdgeList and VertexList
selectors to the actual container types used for the graph storage.
The default version of the traits class is listed below, along with an
example of how the class is specialized for the listS selector.

There may also be situations when you want to use a container that has
more template parameters than just ValueType. For instance,
you may want to supply the allocator type. One way to do this is to
hard-code in the extra parameters within the specialization of
container_gen. However, if you want more flexibility then you
can add a template parameter to the selector class. In the code below
we show how to create a selector that lets you specify the allocator
to be used with the std::list.

In addition to specializing the container_gen class, one must
also specialize the parallel_edge_traits class to specify
whether the container type allows parallel edges (and is a Sequence)
or if the container does not allow parallel edges (and is an AssociativeContainer).

One must also tell the adjacency_list how edges can be
efficiently added and removed from the edge-list container. This is
accomplished by overloading the push() and erase()
functions for the custom container type. The push() function
must return an iterator pointing to the newly inserted element and a
bool flag saying whether the edge was inserted. The following
default push() and erase() functions are already
supplied for all STL container types. The family of
push_dispatch() and erase_dispatch() function overloads
handle the various ways inserting and erasing can be done with
standard containers.