The breadth_first_search() function performs a breadth-first
traversal [49] of a directed
or undirected graph. A breadth-first traversal visits vertices that
are closer to the source before visiting vertices that are further
away. In this context ``distance'' is defined as the number of edges
in the shortest path from the source vertex. The
breadth_first_search() function can be used to compute the
shortest path from the source to all reachable vertices and the
resulting shortest-path distances. For more definitions related to BFS
see section
Breadth-First Search.

BFS uses two data structures to to implement the traversal: a color
marker for each vertex and a queue. White vertices are undiscovered
while gray vertices are discovered but have undiscovered adjacent
vertices. Black vertices are discovered and are adjacent to only other
black or gray vertices. The algorithm proceeds by removing a vertex
u from the queue and examining each out-edge (u,v). If an
adjacent vertex v is not already discovered, it is colored gray and
placed in the queue. After all of the out-edges are examined, vertex
u is colored black and the process is repeated. Pseudo-code for the
BFS algorithm is a listed below.

The breadth_first_search() function can be extended with
user-defined actions that will be called a certain event points. The
actions must be provided in the form of a visitor object, that is, an
object who's type meets the requirements for a BFS Visitor. In the above pseudo-code,
the event points are the labels on the right. Also a description of
each event point is given below. By default, the
breadth_first_search() function does not carry out any
actions, not even recording distances or predecessors. However these
can be easily added using the distance_recorder and predecessor_recorder
event visitors.

Parameters

The source vertex where the search is started.Python: The parameter is named root_vertex.

Named Parameters

IN: visitor(BFSVisitor vis)

A visitor object that is invoked inside the algorithm at the
event-points specified by the BFS
Visitor concept. The visitor object is passed by value [1].Default:bfs_visitor<null_visitor>Python: The parameter should be an object that derives from
the BFSVisitor type of the graph.

UTIL/OUT: color_map(ColorMap color)

This is used by the algorithm to keep track of its progress through
the graph. The user need not initialize the color map before calling
breadth_first_search() since the algorithm initializes the
color of every vertex to white at the start of the algorihtm. If you
need to perform multiple breadth-first searches on a graph (for
example, if there are some disconnected components) then use the breadth_first_visit()
function and do your own color initialization.

The type ColorMap must be a model of Read/Write
Property Map and its key type must be the graph's vertex
descriptor type and the value type of the color map must model
ColorValue.Default: an
iterator_property_map created from a
std::vector of default_color_type of size
num_vertices(g) and using the i_map for the index
map.Python: The color map must be a vertex_color_map for
the graph.

IN: vertex_index_map(VertexIndexMap i_map)

This maps each vertex to an integer in the range [0,
num_vertices(g)). This parameter is only necessary when the
default color property map is used. The type VertexIndexMap
must be a model of Readable Property
Map. The value type of the map must be an integer type. The
vertex descriptor type of the graph needs to be usable as the key
type of the map.Default:get(vertex_index, g).
Note: if you use this default, make sure your graph has
an internal vertex_index property. For example,
adjacenty_list with VertexList=listS does
not have an internal vertex_index property.Python: Unsupported parameter.

UTIL: buffer(Buffer& Q)

The queue used to determine the order in which vertices will be
discovered. If a FIFO queue is used, then the traversal will
be according to the usual BFS ordering. Other types of queues
can be used, but the traversal order will be different.
For example Dijkstra's algorithm can be implemented
using a priority queue. The type Buffer must be a model of
Buffer. The value_type
of the buffer must be the vertex_descriptor type for the graph.Default:boost::queuePython: The buffer must derive from the Buffer type for the graph.

Visitor Event Points

vis.initialize_vertex(v, g) is invoked on every vertex
before the start of the search.

vis.examine_vertex(u, g)r is invoked in each
vertex as it is removed from the queue.

vis.examine_edge(e, g) is invoked on every out-edge
of each vertex immediately after the vertex is removed from the queue.

vis.tree_edge(e, g) is invoked (in addition to
examine_edge()) if the edge is a tree edge. The
target vertex of edge e is discovered at this time.

vis.discover_vertex(u, g) is invoked the first time the
algorithm encounters vertex u. All vertices closer to the
source vertex have been discovered, and vertices further from the
source have not yet been discovered.

vis.non_tree_edge(e, g) is invoked (in addition to
examine_edge()) if the edge is not a tree edge.

vis.gray_target(e, g) is invoked (in addition to
non_tree_edge()) if the target vertex is colored gray at the
time of examination. The color gray indicates that
the vertex is currently in the queue.

vis.black_target(e, g) is invoked (in addition to
non_tree_edge()) if the target vertex is colored black at the
time of examination. The color black indicates that the
vertex is no longer in the queue.

vis.finish_vertex(u, g) is invoked after all of the out
edges of u have been examined and all of the adjacent vertices
have been discovered.

See Also

Notes

[1]
Since the visitor parameter is passed by value, if your visitor
contains state then any changes to the state during the algorithm
will be made to a copy of the visitor object, not the visitor object
passed in. Therefore you may want the visitor to hold this state by
pointer or reference.