[21] | 1 | /* -*- mode: C++; indent-tabs-mode: nil; -*- |
---|
| 2 | * |
---|
| 3 | * This file is a part of LEMON, a generic C++ optimization library. |
---|
| 4 | * |
---|
| 5 | * Copyright (C) 2003-2009 |
---|
| 6 | * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport |
---|
| 7 | * (Egervary Research Group on Combinatorial Optimization, EGRES). |
---|
| 8 | * |
---|
| 9 | * Permission to use, modify and distribute this software is granted |
---|
| 10 | * provided that this copyright notice appears in all copies. For |
---|
| 11 | * precise terms see the accompanying LICENSE file. |
---|
| 12 | * |
---|
| 13 | * This software is provided "AS IS" with no warranty of any kind, |
---|
| 14 | * express or implied, and with no claim as to its suitability for any |
---|
| 15 | * purpose. |
---|
| 16 | * |
---|
| 17 | */ |
---|
| 18 | |
---|
| 19 | namespace lemon { |
---|
| 20 | /** |
---|
[26] | 21 | [PAGE]sec_basics[PAGE] Basic Concepts |
---|
[21] | 22 | |
---|
[27] | 23 | Throughout the tutorial we are working with the \ref lemon namespace. |
---|
| 24 | To save a lot of typing, we assume that a |
---|
[21] | 25 | |
---|
| 26 | \code |
---|
| 27 | using namespace lemon; |
---|
| 28 | \endcode |
---|
| 29 | |
---|
| 30 | directive is added to the code at the beginning. |
---|
| 31 | |
---|
[26] | 32 | [SEC]sec_digraphs[SEC] Directed Graphs |
---|
[21] | 33 | |
---|
[27] | 34 | This section tells you how to work with a directed graph (\e digraph, |
---|
| 35 | for short) in LEMON. |
---|
| 36 | The library provides various digraph structures for both general and special |
---|
| 37 | purposes. Here we use \c ListDigraph, the most versatile digraph type. |
---|
[21] | 38 | |
---|
[27] | 39 | The nodes and the arcs of a graph are identified by two data types called |
---|
| 40 | \ref concepts::Digraph::Node "ListDigraph::Node" and \ref concepts::Digraph::Arc |
---|
| 41 | "ListDigraph::Arc". You can add new items to the graph using the member |
---|
| 42 | functions \ref ListDigraph::addNode() "addNode()" and |
---|
| 43 | \ref ListDigraph::addArc() "addArc()", like this: |
---|
[21] | 44 | |
---|
| 45 | \code |
---|
| 46 | ListDigraph g; |
---|
| 47 | ListDigraph::Node a = g.addNode(); |
---|
| 48 | ListDigraph::Node b = g.addNode(); |
---|
| 49 | ListDigraph::Node c = g.addNode(); |
---|
| 50 | ListDigraph::Node d = g.addNode(); |
---|
| 51 | |
---|
| 52 | g.addArc(a,b); |
---|
| 53 | g.addArc(b,c); |
---|
| 54 | g.addArc(c,d); |
---|
| 55 | g.addArc(d,a); |
---|
| 56 | \endcode |
---|
| 57 | |
---|
| 58 | Of course, \ref ListDigraph::addArc() "addArc()" also returns the created arc: |
---|
| 59 | |
---|
| 60 | \code |
---|
[27] | 61 | ListDigraph::Arc arc = g.addArc(a,c); |
---|
[21] | 62 | \endcode |
---|
| 63 | |
---|
[27] | 64 | \note Using ListDigraph, you can also remove nodes or arcs with the |
---|
| 65 | \ref ListDigraph::erase() "erase()" function. |
---|
| 66 | However, not all graph structures support the addition and deletion |
---|
| 67 | of graph items. |
---|
[21] | 68 | |
---|
[27] | 69 | Two important member functions of the directed graphs are |
---|
[21] | 70 | \ref concepts::Digraph::source() "source()" |
---|
| 71 | and \ref concepts::Digraph::target() "target()". |
---|
[27] | 72 | They give back the two end nodes of an arc. |
---|
[21] | 73 | |
---|
| 74 | \code |
---|
[27] | 75 | if (g.source(arc) == g.target(arc)) |
---|
[21] | 76 | std::cout << "This is a loop arc" << std::endl; |
---|
| 77 | \endcode |
---|
| 78 | |
---|
[27] | 79 | Each graph item has a unique integer identifier, which can be obtained using |
---|
| 80 | the \ref concepts::Digraph::id() "id()" function of the graph structure. |
---|
| 81 | |
---|
| 82 | \code |
---|
| 83 | std::cout << "Arc " << g.id(arc) << " goes from node " |
---|
| 84 | << g.id(g.source(arc)) << " to node " << g.id(g.target(arc)) << std::endl; |
---|
| 85 | \endcode |
---|
| 86 | |
---|
| 87 | \note In fact, the \c Node and \c Arc types are typically simple wrapper |
---|
| 88 | classes for a single \c int value, which is the identifier of the item. |
---|
| 89 | |
---|
[26] | 90 | |
---|
| 91 | [SEC]sec_digraph_it[SEC] Iterators |
---|
[21] | 92 | |
---|
[27] | 93 | Let us assume you want to list the elements of the graph. For this purpose, |
---|
| 94 | the graph structures provide several iterators. For example, the following |
---|
| 95 | code will count the number of nodes in a graph. |
---|
[21] | 96 | |
---|
| 97 | \code |
---|
| 98 | int cnt = 0; |
---|
[27] | 99 | for (ListDigraph::NodeIt n(g); n != INVALID; ++n) |
---|
[21] | 100 | cnt++; |
---|
| 101 | std::cout << "Number of nodes: " << cnt << std::endl; |
---|
| 102 | \endcode |
---|
| 103 | |
---|
| 104 | Here \ref concepts::Digraph::NodeIt "ListDigraph::NodeIt" |
---|
[27] | 105 | is an iterator class that traverses the |
---|
| 106 | nodes. You must give the graph to the constructor and the iterator will be set |
---|
[21] | 107 | to the first node. The next node is obtained by the prefix ++ |
---|
[27] | 108 | operator. If there are no more nodes in the graph, the iterator will |
---|
[21] | 109 | be set to \ref INVALID. |
---|
| 110 | |
---|
[27] | 111 | \note \ref INVALID is a global constant, which converts to |
---|
| 112 | and compares with each and every iterator in LEMON. |
---|
[21] | 113 | |
---|
[27] | 114 | The iterators convert to the corresponding item types. For example, |
---|
[21] | 115 | to following code will add a full graph to the existing nodes. |
---|
| 116 | |
---|
| 117 | \code |
---|
[27] | 118 | for (ListDigraph::NodeIt u(g); u != INVALID; ++u) |
---|
| 119 | for (ListDigraph::NodeIt v(g); v != INVALID; ++v) |
---|
| 120 | if (u != v) g.addArc(u, v); |
---|
[21] | 121 | \endcode |
---|
| 122 | |
---|
[27] | 123 | \note Contrary to the iterators in the C++ Standard Template Library (STL), |
---|
| 124 | LEMON iterators are convertible to the corresponding |
---|
| 125 | item types without having to use \c %operator*(). This is not confusing, since the |
---|
| 126 | program context always indicates whether we refer to the iterator or to the graph |
---|
| 127 | item (they do not have conflicting functionalities). |
---|
| 128 | |
---|
| 129 | The graph items are also ordered by the 'less than' operator (with respect to |
---|
| 130 | their integer identifiers). For example, this code will add only one of the |
---|
| 131 | opposite arcs. |
---|
[21] | 132 | |
---|
| 133 | \code |
---|
[27] | 134 | for (ListDigraph::NodeIt u(g); u != INVALID; ++u) |
---|
| 135 | for (ListDigraph::NodeIt v(g); v != INVALID; ++v) |
---|
| 136 | if (u < v) g.addArc(u, v); |
---|
[21] | 137 | \endcode |
---|
| 138 | |
---|
[27] | 139 | \warning The order in which the iterators visit the items is |
---|
[21] | 140 | undefined. The only thing you may assume that they will list the items |
---|
| 141 | in the same order until the graph is not changed. |
---|
| 142 | |
---|
| 143 | Similarly, \ref concepts::Digraph::ArcIt "ListDigraph::ArcIt" |
---|
| 144 | lists the arcs. Its usage is the same as of |
---|
| 145 | \ref concepts::Digraph::NodeIt "ListDigraph::NodeIt". |
---|
| 146 | |
---|
| 147 | \code |
---|
| 148 | int cnt = 0; |
---|
[27] | 149 | for (ListDigraph::ArcIt a(g); a != INVALID; ++a) |
---|
[21] | 150 | cnt++; |
---|
| 151 | std::cout << "Number of arcs: " << cnt << std::endl; |
---|
| 152 | \endcode |
---|
| 153 | |
---|
| 154 | Finally, you can also list the arcs starting from or arriving at a |
---|
| 155 | certain node with |
---|
| 156 | \ref concepts::Digraph::OutArcIt "ListDigraph::OutArcIt" |
---|
| 157 | and |
---|
| 158 | \ref concepts::Digraph::InArcIt "ListDigraph::InArcIt". |
---|
[27] | 159 | Their usage is the same, but you must also give the node to the constructor. |
---|
[21] | 160 | |
---|
| 161 | \code |
---|
| 162 | int cnt = 0; |
---|
[27] | 163 | for (ListDigraph::OutArcIt a(g, start); a != INVALID; ++a) |
---|
[21] | 164 | cnt++; |
---|
| 165 | std::cout << "Number of arcs leaving the node 'start': " << cnt << std::endl; |
---|
| 166 | \endcode |
---|
| 167 | |
---|
[26] | 168 | |
---|
| 169 | [SEC]sec_digraph_maps[SEC] Maps |
---|
[21] | 170 | |
---|
[27] | 171 | The concept of "maps" is another fundamental part of LEMON. They allow assigning |
---|
| 172 | values of any type to the nodes or arcs of a graph. The standard maps |
---|
[21] | 173 | provided by the graph structures have a couple of nice properties. |
---|
| 174 | |
---|
[27] | 175 | - \e Fast. Accessing (reading/writing) the values is as fast as a |
---|
| 176 | simple vector reading/writing. |
---|
[21] | 177 | - \e Dynamic. Whenever you need, you |
---|
| 178 | can allocate new maps in your code, just as a local variable. So when you |
---|
| 179 | leave its scope, it will be de-allocated automatically. |
---|
| 180 | - \e Automatic. If you add new nodes or arcs to the graph, the storage of the |
---|
| 181 | existing maps will automatically expanded and the new slots will be |
---|
| 182 | initialized. On the removal of an item, the corresponding values in the maps |
---|
| 183 | are properly destructed. |
---|
| 184 | |
---|
[27] | 185 | \note These maps must not be confused with \c std::map, since they provide |
---|
| 186 | O(1) time acces to the elements instead of O(log n). |
---|
| 187 | |
---|
[21] | 188 | So, if you want to assign \c int values to each node, you have to allocate a |
---|
[27] | 189 | \ref concepts::Digraph::NodeMap "NodeMap<int>". |
---|
[21] | 190 | |
---|
| 191 | \code |
---|
| 192 | ListDigraph::NodeMap<int> map(g); |
---|
| 193 | \endcode |
---|
| 194 | |
---|
| 195 | As you see, the graph you want to assign a map is given to the |
---|
| 196 | constructor. Then you can access its element as if it were a vector. |
---|
| 197 | |
---|
| 198 | \code |
---|
[27] | 199 | map[a] = 2; |
---|
| 200 | map[b] = 3; |
---|
| 201 | map[c] = map[a] + map[b]; |
---|
[21] | 202 | \endcode |
---|
| 203 | |
---|
[27] | 204 | Any kind of data can be assigned to the graph items. |
---|
| 205 | |
---|
| 206 | \code |
---|
| 207 | ListDigraph::NodeMap<std::string> label(g); |
---|
| 208 | label[a] = "Node A"; |
---|
| 209 | label[b] = "Node B"; |
---|
| 210 | \endcode |
---|
| 211 | |
---|
| 212 | For a more complex example, let us create a map that assigns a unique |
---|
[21] | 213 | integer number to each node. |
---|
| 214 | |
---|
| 215 | \code |
---|
| 216 | ListDigraph::NodeMap<int> id(g); |
---|
[27] | 217 | int cnt = 0; |
---|
| 218 | for (ListDigraph::NodeIt n(g); n != INVALID; ++n) |
---|
| 219 | id[n] = cnt++; |
---|
[21] | 220 | \endcode |
---|
| 221 | |
---|
[27] | 222 | When you create a map, you can also give an initial value of the elements |
---|
| 223 | as a second parameter. For example, the following code puts the number |
---|
| 224 | of outgoing arcs for each node in a map. |
---|
[21] | 225 | |
---|
| 226 | \code |
---|
[27] | 227 | ListDigraph::NodeMap<int> out_deg(g, 0); |
---|
[21] | 228 | |
---|
[27] | 229 | for (ListDigraph::ArcIt a(g); a != INVALID; ++a) |
---|
[21] | 230 | out_deg[g.source(a)]++; |
---|
| 231 | \endcode |
---|
| 232 | |
---|
[27] | 233 | \warning The initial value will apply to the currently existing items only. If |
---|
[21] | 234 | you add new nodes/arcs to the graph, then the corresponding values in the |
---|
| 235 | map will be initialized with the default constructor of the |
---|
| 236 | type. |
---|
| 237 | |
---|
| 238 | [TRAILER] |
---|
| 239 | */ |
---|
| 240 | } |
---|