mirror of
https://github.com/boostorg/graph.git
synced 2026-01-24 18:02:19 +00:00
241 lines
8.5 KiB
HTML
241 lines
8.5 KiB
HTML
<HTML>
|
|
<!--
|
|
-- Copyright (c) Jeremy Siek 2000
|
|
--
|
|
-- Permission to use, copy, modify, distribute and sell this software
|
|
-- and its documentation for any purpose is hereby granted without fee,
|
|
-- provided that the above copyright notice appears in all copies and
|
|
-- that both that copyright notice and this permission notice appear
|
|
-- in supporting documentation. Silicon Graphics makes no
|
|
-- representations about the suitability of this software for any
|
|
-- purpose. It is provided "as is" without express or implied warranty.
|
|
-->
|
|
<Head>
|
|
<Title>Using the BGL Algorithms</Title>
|
|
<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b"
|
|
ALINK="#ff0000">
|
|
<IMG SRC="../../../c++boost.gif"
|
|
ALT="C++ Boost" width="277" height="86">
|
|
|
|
<BR Clear>
|
|
|
|
|
|
<H1>Using the BGL Algorithms</H1>
|
|
|
|
<P>
|
|
All of the BGL algorithms have a lot in common when it comes to the
|
|
appearance of the interface and the setup the user must do in order to
|
|
call them. These common points are discussed here while the details of
|
|
the algorithms are discussed in the reference section for each
|
|
algorithm. We will used <a
|
|
href="./dijkstra_shortest_paths.html">Dijsktra's single-source
|
|
shortest paths</a> algorithm as our first example. The following is
|
|
the declaration of the algorithm.
|
|
|
|
<P>
|
|
<PRE>
|
|
namespace boost {
|
|
template <class VertexListGraph, class Vertex,
|
|
class Distance, class Weight, class Color,
|
|
class ID, class Visitor>
|
|
void dijkstra_shortest_paths(VertexListGraph& G, Vertex s,
|
|
Distance d, Weight w, Color c, ID id,
|
|
Visitor visit);
|
|
}
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
<H2>The Graph Parameter</H2>
|
|
|
|
<P>
|
|
Of course the most important parameter of the function is the graph
|
|
object <TT>G</TT>. The name of the template type
|
|
<TT>VertexListGraph</TT> is used to remind the user that graph classes
|
|
used with Dijkstra's algorithm must model the <a
|
|
href="./VertexListGraph.html">VertexListGraph</a> concept. This
|
|
basically means that the graph class must provide <TT>vertices()</TT>,
|
|
<TT>out_edges()</TT>, and the other functions and associated types
|
|
required by <a href="./VertexListGraph.html">VertexListGraph</a>. Most
|
|
BGL graph classes support these operations, though <TT>edge_list</TT>
|
|
is a notable exception. You can look in the <B>Model Of</B> section of
|
|
the graph class documentation to find out which operations are
|
|
supported by the graph.
|
|
|
|
<P>
|
|
It is also important to note whether the algorithm works on only
|
|
undirected graphs or whether it also applies to directed graphs
|
|
(undirected graphs are a special kind of directed graph). This
|
|
information always appears at the top the algorithm description.
|
|
|
|
<P>
|
|
|
|
<H2>The Vertex Parameter</H2>
|
|
|
|
<P>
|
|
The next parameter, <TT>Vertex s</TT>, is the source vertex from which
|
|
we want to calculate the shortests paths. The object <TT>s</TT> must be
|
|
a vertex desriptor of the graph object. The following code snippet
|
|
shows how one would declare a vertex descriptor object.
|
|
|
|
<P>
|
|
<PRE>
|
|
typedef ... Graph;
|
|
Graph G;
|
|
// fill in G with vertices and edges ...
|
|
|
|
boost::graph_traits<Graph>::vertex_descriptor s;
|
|
</PRE>
|
|
|
|
<P>
|
|
The vertex <TT>s</TT> needs to be initialized so that it points to
|
|
some vertex in the graph. There are several ways to obtain a vertex
|
|
descriptor object from the graph, and which method you use will often
|
|
depend on the situation. The <TT>vertices()</TT> function provides
|
|
access to all the vertices in the graph through iterators, and the
|
|
<TT>source()</TT> and <TT>target()</TT> functions give the vertices
|
|
incident to an edge. Here we will simply grab the vertex at the
|
|
beginning of the graph's vertex set. The <TT>tie()</TT> function
|
|
provides a convenient way to assign the pair of iterators returned by
|
|
<TT>vertices()</TT> to the <TT>viter</TT> and <TT>viter_end</TT>
|
|
variables. The vertex iterator dereferences to give a vertex
|
|
descriptor object.
|
|
|
|
<P>
|
|
<PRE>
|
|
boost::graph_traits<Graph>::vertex_iterator viter, viter_end;
|
|
boost::tie(viter, viter_end) = vertices(G);
|
|
s = *viter;
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
<H2>The Property Map Parameters</H2>
|
|
|
|
<P>
|
|
The next four parameters to Dijkstra's algorithm are property
|
|
maps. Much of the flexibility of BGL comes from property
|
|
maps, so this deserves some discussion. As the name implies, a
|
|
property map provides a mechanism for reading and writing to
|
|
properties that are attached to vertices or edges of a graph.
|
|
<I>Internal</I> properties are stored inside of a graph object
|
|
while <I>external</I> properties are not.
|
|
|
|
<P>
|
|
|
|
<H3><A NAME="SECTION00823100000000000000">
|
|
Internal Properties</A>
|
|
</H3>
|
|
|
|
<P>
|
|
Property maps for internal properties are always obtained via the
|
|
interface defined in <a href="./PropertyGraph.html">PropertyGraph</a>.
|
|
This interface defines a traits class <TT>property_map</TT> and a
|
|
function <TT>get(property, g)</TT> which returns a property map
|
|
object. The traits classes are used to obtain the <I>type</I> of the
|
|
property map given some graph type and a property tag. The
|
|
property tag determines which property will be accessed (more than one
|
|
property can be attached to the vertices or edges of the graph). The
|
|
functions are used to obtain the property map <I>objects</I>.
|
|
The following code snippet shows how to create a property map for
|
|
the distance and weight properties of graph <TT>G</TT>.
|
|
|
|
<P>
|
|
<PRE>
|
|
boost::property_map<Graph, vertex_distance_t>::type
|
|
d = get(vertex_distance, G);
|
|
|
|
boost::property_map<Graph, edge_weight_t>::type
|
|
w = get(edge_weight, G);
|
|
</PRE>
|
|
|
|
<P>
|
|
The BGL graph classes all have <TT>VertexProperty</TT> and
|
|
<TT>EdgeProperty</TT> template parameters that let the user specify
|
|
internal properties. If the graph <TT>G</TT> has properties for all four of
|
|
the properties needed by Dijksta's algorithm, then we could invoke the
|
|
algorithm in the following way.
|
|
|
|
<P>
|
|
<PRE>
|
|
boost::dijkstra_shortest_paths(G, s,
|
|
get(vertex_distance, G),
|
|
get(edge_weight, G),
|
|
get(vertex_color, G),
|
|
get(vertex_index, G),
|
|
null_visitor());
|
|
</PRE>
|
|
|
|
<P>
|
|
Since it is somewhat cumbersome to provide arguments for all of the
|
|
properties needed by an algorithm, BGL also provides variants of the
|
|
algorithm (shortcuts) that assume that some or all of the properties
|
|
are internal to the graph. The following call invokes variant (1) of
|
|
Dijkstra's algorithm.
|
|
|
|
<P>
|
|
<PRE>
|
|
boost::dijkstra_shortest_paths(G, s);
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
<H3>External Properties</H3>
|
|
|
|
<P>
|
|
There are at least two kinds of situations when internal properties
|
|
can not or should not be used, and an external property should be used
|
|
instead. The first situation is when a property is only needed for a
|
|
short time relative to the lifetime of the graph (perhaps only for the
|
|
duration of a single algorithm call). In this case it is more
|
|
efficient to keep the property storage in memory for only the time
|
|
that it is needed. The second situation is when the properties are
|
|
already stored somewhere else due to some pragmatic or historical
|
|
reason (yes, programs can and do have histories!).
|
|
|
|
<P>
|
|
For the most part, it is up to the user to create the appropriate
|
|
property map for their extrnal properties. A typical property
|
|
map class requires only a few lines of code, so this is not
|
|
difficult to do.
|
|
|
|
<P>
|
|
BGL does provide one builtin external property map, the
|
|
<TT>random_access_iterator_property_map</TT>
|
|
which provides a convient way to wrap up a random access iterator for
|
|
use as a property map. This adaptor uses the vertex or edge ID
|
|
property as an index with the random access iterator. Normal builtin
|
|
arrays and pointers to arrays are examples of storage that naturally
|
|
have random access iterators. Many of the BGL examples use arrays for
|
|
property storage because they are fast and convenient.
|
|
|
|
<P>
|
|
For the <TT>adjacency_list</TT> with template parameter
|
|
<TT>VertexList=vecS</TT> the random access iterator adaptor is not
|
|
necessary and the random access iterators can be passed as-is into the
|
|
algorithm. This is because the vertex descriptors of those classes
|
|
<I>are</I> vertex ID's.
|
|
|
|
<P>
|
|
|
|
<H2>The Visitor Parameter</H2>
|
|
|
|
<P>
|
|
The visitor parameter gives the user the oportunity to insert their
|
|
own operations into the graph algorithm, similar to the function
|
|
objects used in the STL. How to use visitors is described in
|
|
Section <A HREF="./visitor_concepts.html">Visitor Concepts</A>.
|
|
|
|
|
|
|
|
<br>
|
|
<HR>
|
|
<TABLE>
|
|
<TR valign=top>
|
|
<TD nowrap>Copyright © 2000</TD><TD>
|
|
<A HREF="../../../people/jeremy_siek.htm">Jeremy Siek</A>, Univ.of Notre Dame (<A HREF="mailto:jsiek@lsc.nd.edu">jsiek@lsc.nd.edu</A>)
|
|
</TD></TR></TABLE>
|
|
|
|
</BODY>
|
|
</HTML>
|