COIN-OR::LEMON - Graph Library

source: lemon-0.x/doc/basic_concepts.dox @ 2350:eb371753e814

Last change on this file since 2350:eb371753e814 was 2350:eb371753e814, checked in by Alpar Juttner, 13 years ago

Several doc improvements.

File size: 5.7 KB
Line 
1namespace lemon {
2
3/**
4\page basic_concepts Basic concepts
5
6\section basic_graph The graph classes
7The most important classes in LEMON are the graph classes. An instance of a graph
8class is the representation of the mathematical graph. It holds the topology and
9every structural information of the graph. The structural manipulations are also
10provided by the graph object. There is no universal graph class instead we have
11different classes for different purposes. They can differ in many ways, but all
12have to satisfy one or more \ref concept "graph concepts" which are standardized
13interfaces to work with the rest of the library. The most basic concept is the
14\ref Graph.<br>
15A good example is the \ref ListGraph which we already know from Hello World and
16will be used in our examples as well.
17
18One main advantage of the templates are, that you can write your own graph classes.
19As long as they provide the interface a concept is defining all the LEMON algorithms
20and classes will work with it properly - no representation or implementation is
21written into stone.
22
23
24\subsection basic_node Nodes
25To refer to a node of a graph we need some kind of typed variable. Graph classes
26have the Node public type for this purpose. Stacking by the last example:
27\code lemon::ListGraph::Node \endcode
28
29If the graph fits the ExtendableGraphComponent concept, then you can add new nodes
30to the graph with the addNode() member function. It returns the newly added node
31(as value). So if you need the new node to do something useful with, for example
32create an edge, assign a value to it through \ref map1 maps.
33\code lemon::ListGraph::Node  new_node = graph.addNode(); \endcode
34
35If the graph fits into the ErasableGraphComponent concept you can also remove nodes
36from the graph with the erase() member function.
37\code graph.erase( new_node ); \endcode
38
39You don't have to store every node in a variable, you can access individual nodes
40with node iterators discussed in the next section. But how do you know which
41node is which?<br>
42The graph class has the id( Node n ) member function providing an unique identifier
43assigned to every node.
44
45
46\subsection basic_edge Edges
47An Edge is what you think it is. It goes from one node to another node (they can
48be identical if the edge is a loop). If the graph class is directed, the Edge is directed too. Otherwise
49the edge is considered undirected and called UEdge.
50\code lemon::ListUGraph::UEdge \endcode
51
52The addEdge() member function will create a new edge. It has two arguments, the
53source node and the target node. The graph class must be extendable.
54\code lemon::ListGraph::Edge  new_edge = graph.addEdge( src_node, trg_node ); \endcode
55You can handle edges similar as nodes. The erase() member function has an edge taking
56overload too.
57
58You can ask for the source or target node of the edge by the corresponding member
59functions:
60\code
61graph.source( new_edge );
62lemon::ListGraph::Node  n = graph.target( new_edge ); \endcode
63These functions are always legal even if the graph is undirected. UEdge has a
64default direction.
65
66
67\section basic_iterators Iterators
68Graphs are some kind of containers. And as you expect they have iterator types.
69One for nodes and a couple for edges - and special classes can have additional
70iterators too. An example:
71\code lemon::ListGraph::NodeIt \endcode
72This is a node iterator. Every iterator type starts with a name that refers to
73the iterated object, and ends with 'It'.
74
75LEMON style iterators differ from \c stl or \c boost iterators in a very tasty
76way. A graph has no begin or end - or at least a generic graph class has none.
77If by some topology you could pick a good begin node, it would be misleading and
78incorrect. A LEMON style iterator must be initialized at construction time.
79The constructor takes the needed parameters - by a node iterator it's the graph
80object. And will be compared to the lemon::INVALID to check if it's still valid.
81Every iterator can be compared to INVALID. No \c begin() or \c end() needed.<br>
82Let's see these things working together:
83\code
84for( ListGraph::NodeIt n(graph); n != INVALID; ++n )
85    do_useful_things_with_node(n);
86\endcode
87Note that the function \c do_useful_things_with_node() expects a Node type argument
88ad we just gave him the iterator. LEMON style iterators must provide "on demand
89dereferencing". For example a NodeIt can be used everywhere a Node could. (In some
90graph classes Node is the base class of NodeIt. But in other cases this is implemented
91through typecast operator.)
92
93<b>Very important!</b> The iteration has no defined order. There is absolutely no
94warranty that the next time the iteration will give us the nodes in the same order.
95Don't use this order to identify nodes! Use the \c id() member function of the
96graph class described above. (There is a powerful technique using maps right in
97the next page.)
98
99The \ref EdgeIt works exactly the same - nothing more to say. But there are \ref InEdgeIt
100and \ref OutEdgeIt by directed graphs and \ref IncEdgeIt by undirected graphs.
101They take two arguments. The first is a graph, the second is certain node of the
102graph. InEdgeIt iterates on the incoming edges of that node and OutEdgeIt does it
103on the outgoing edges. The IncEdgeIt of course iterates every edge connecting to
104the given node.
105
106\code
107for( ListGraph::NodeIt n(graph); n != INVALID; ++n ) {
108  int in = 0, out = 0;
109  for( ListGraph::InEdgeIt e(graph,n); e != INVALID; ++e ) ++in;
110  for( ListGraph::OutEdgeIt e(graph,n); e != INVALID; ++e ) ++out;
111
112  std::cout << "#" << graph.id(n) << " node has " << in << " incoming and "
113    << out << "outgoing edges." << std::endl;
114}
115\endcode
116
117
118\section basic_ListGraph ListGraph - a versatile directed graph
119As you see ListGraph satisfies most of the basic concepts and ideal for general
120graph representations. It has an undirected version too: ListUGraph.
121*/
122
123}
Note: See TracBrowser for help on using the repository browser.