COIN-OR::LEMON - Graph Library

source: lemon-0.x/doc/graph_io.dox @ 1536:308150155bb5

Last change on this file since 1536:308150155bb5 was 1532:aa7428d22aaf, checked in by Balazs Dezso, 15 years ago

Updated but not complete doc for IO.

File size: 12.7 KB
Line 
1namespace lemon {
2/*!
3
4
5\page graph-io-page Graph Input-Output
6
7The standard graph IO enables to store graphs and additional maps
8in a flexible and efficient way.
9
10\section format The general file format
11
12The file contains sections in the following order:
13
14\li nodeset
15\li edgeset
16\li nodes
17\li edges
18\li attributes
19
20The nodeset section starts with the following line:
21
22<tt>\@nodeset</tt>
23
24The next line contains the names of the nodemaps, separated by whitespaces.  Each
25following line describes a node in the graph: it contains the values of the
26maps in the right order. The map named "id" should contain unique values
27because it is regarded as an ID-map. For example:
28
29\code
30@nodeset
31id  x-coord  y-coord  color
323   1.0      4.0      blue
335   2.3      5.7      red
3412  7.8      2.3      green
35\endcode
36
37The edgeset section is very similar to the nodeset section, it has
38the same coloumn oriented structure. It starts with the line
39
40<tt>\@edgeset</tt>
41
42The next line contains the whitespace separated list of names of the maps.
43Each of the next lines describes one edge. The first two elements in the line
44are the IDs of the source and target (or tail and head) node of the edge as they occur in the ID node
45map. You can also have an optional ID map on the edges for later reference.
46
47\code
48@edgeset
49             id    weight   label
503   5        a     4.3      a-edge
515   12       c     2.6      c-edge
523   12       g     3.4      g-edge
53\endcode
54
55The next section contains <em>labeled nodes</em> (i.e. nodes having a special
56label on them). The section starts with
57
58<tt> \@nodes </tt>
59
60Each of the next lines contains a label for a node in the graph
61and then the ID described in the nodeset section.
62
63\code
64@nodes
65source 3
66target 12
67\endcode
68
69The last section describes the <em>labeled edges</em>
70(i.e. edges having a special label on them). It starts with \c \@edges
71and then each line contains the name of the edge and the ID.
72
73\code
74@nodes
75observed c
76\endcode
77
78
79The file may contain empty lines and comment lines. The comment lines
80start with an \c # character.
81
82The attributes section can handle some information about the graph. It
83contains in each line an key and the mapped value to key. The key should
84be a string without whitespace, the value can be from various type.
85
86\code
87@attributes
88title "Four colored plan graph"
89author "Balazs DEZSO"
90copyright "Lemon Library"
91version 12
92\endcode
93
94\code
95@end
96\endcode
97=======
98The file ends with the
99
100<tt> \@end </tt>
101
102line.
103
104
105\section use Using graph input-output
106The graph input and output is based on reading and writing  commands. The user
107adds reading and writing commands to the reader or writer class, then he
108calls the \c run() method that executes all the given commands.
109
110\subsection write Writing a graph
111
112The \c GraphWriter class provides the graph output. To write a graph
113you should first give writing commands to the writer. You can declare
114write command as \c NodeMap or \c EdgeMap writing and labeled Node and
115Edge writing.
116
117\code
118GraphWriter<ListGraph> writer(std::cout, graph);
119\endcode
120
121The \c writeNodeMap() function declares a \c NodeMap writing command in the
122\c GraphWriter. You should give a name of the map and the map
123object as parameters. The NodeMap writing command with name "id" should write a
124unique map because it is regarded as ID map.
125
126\see IdMap, DescriptorMap 
127
128\code
129IdMap<ListGraph, Node> nodeIdMap;
130writer.writeNodeMap("id", nodeIdMap);
131
132writer.writeNodeMap("x-coord", xCoordMap);
133writer.writeNodeMap("y-coord", yCoordMap);
134writer.writeNodeMap("color", colorMap);
135\endcode
136
137With the \c writeEdgeMap() member function you can give an edge map
138writing command similar to the NodeMaps.
139
140\see IdMap, DescriptorMap 
141
142\code
143DescriptorMap<ListGraph, Edge, ListGraph::EdgeMap<int> > edgeDescMap(graph);
144writer.writeEdgeMap("descriptor", edgeDescMap);
145
146writer.writeEdgeMap("weight", weightMap);
147writer.writeEdgeMap("label", labelMap);
148\endcode
149
150With \c writeNode() and \c writeEdge() functions you can designate Nodes and
151Edges in the graph. For example, you can write out the source and target node
152of a maximum flow instance.
153
154\code
155writer.writeNode("source", sourceNode);
156writer.writeNode("target", targetNode);
157
158writer.writeEdge("observed", edge);
159\endcode
160
161With \c writeAttribute() function you can write an attribute to the file.
162
163\code
164writer.writeAttribute("author", "Balazs DEZSO");
165writer.writeAttribute("version", 12);
166\endcode
167
168After you give all write commands you must call the \c run() member
169function, which executes all the writing commands.
170
171\code
172writer.run();
173\endcode
174
175\subsection reading Reading a graph
176
177The given file format may contain several maps and labeled nodes or edges.
178If you read a graph you need not read all the maps and items just those
179that you need. The interface of the \c GraphReader is very similar to
180the GraphWriter but the reading method does not depend on the order of the
181given commands.
182
183The reader object assumes that each not readed value does not contain
184whitespaces, therefore it has some extra possibilities to control how
185it should skip the values when the string representation contains spaces.
186
187\code
188GraphReader<ListGraph> reader(std::cin, graph);
189\endcode
190
191The \c readNodeMap() function reads a map from the \c \@nodeset section.
192If there is a map that you do not want to read from the file and there are
193whitespaces in the string represenation of the values then you should
194call the \c skipNodeMap() template member function with proper parameters.
195
196\see QuotedStringReader
197
198\code
199reader.readNodeMap("x-coord", xCoordMap);
200reader.readNodeMap("y-coord", yCoordMap);
201
202reader.readNodeMap<QuotedStringReader>("label", labelMap);
203reader.skipNodeMap<QuotedStringReader>("description");
204
205reader.readNodeMap("color", colorMap);
206\endcode
207
208With the \c readEdgeMap() member function you can give an edge map
209reading command similar to the NodeMaps.
210
211\code
212reader.readEdgeMap("weight", weightMap);
213reader.readEdgeMap("label", labelMap);
214\endcode
215
216With \c readNode() and \c readEdge() functions you can read labeled Nodes and
217Edges.
218
219\code
220reader.readNode("source", sourceNode);
221reader.readNode("target", targetNode);
222
223reader.readEdge("observed", edge);
224\endcode
225
226With \c readAttribute() function you can read an attribute from the file.
227
228\code
229std::string author;
230writer.readAttribute("author", author);
231int version;
232writer.writeAttribute("version", version);
233\endcode
234
235After you give all read commands you must call the \c run() member
236function, which executes all the commands.
237
238\code
239reader.run();
240\endcode
241
242\section types Background of Reading and Writing
243To read a map (on the nodes or edges)
244the \c GraphReader should know how to read a Value from the given map.
245By the default implementation the input operator reads a value from
246the stream and the type of the readed value is the value type of the given map.
247When the reader should skip a value in the stream, because you do not
248want to store it in a map, the reader skips a character sequence without
249whitespace.
250
251If you want to change the functionality of the reader, you can use
252template parameters to specialize it. When you give a reading
253command for a map you can give a Reader type as template parameter.
254With this template parameter you can control how the Reader reads
255a value from the stream.
256
257The reader has the next structure:
258\code
259struct TypeReader {
260  typedef TypeName Value;
261
262  void read(std::istream& is, Value& value);
263};
264\endcode
265
266For example, the \c "strings" nodemap contains strings and you do not need
267the value of the string just the length. Then you can implement own Reader
268struct.
269
270\code
271struct LengthReader {
272  typedef int Value;
273
274  void read(std::istream& is, Value& value) {
275    std::string tmp;
276    is >> tmp;
277    value = tmp.length();
278  }
279};
280...
281reader.readNodeMap<LengthReader>("strings", lengthMap);
282\endcode 
283
284The global functionality of the reader class can be changed by giving a
285special template parameter to the GraphReader class. By default, the
286template parameter is \c DefaultReaderTraits. A reader traits class
287should provide an inner template class Reader for each type, and an
288DefaultReader for skipping a value.
289
290The specialization of  writing should be very similar to that of reading.
291
292\section undir Undir graphs
293
294In the undir graph format there is an \c undiredgeset section instead of
295the \c edgeset section. The first line of the section describes the
296undirected egdes' names and all next lines describes one undirected edge
297with the the incident nodes and the values of the map.
298
299The format handles the directed edge maps as a syntactical sugar, if there
300is two map which names are the same with a \c '+' and a \c '-' prefix
301then it can be read as an directed map.
302
303\code
304@undiredgeset
305             id    capacity +flow -flow
30632   2       1     4.3      2.0   0.0
30721   21      5     2.6      0.0   2.6
30821   12      8     3.4      0.0   0.0
309\endcode
310
311The \c edges section changed to \c undiredges section. This section
312describes labeled edges and undirected edges. The directed edge label
313should start with a \c '+' and a \c '-' prefix what decide the direction
314of the edge.
315
316\code
317@undiredges
318undiredge 1
319+edge 5
320-back 5
321\endcode
322
323There are similar classes to the \c GraphReader ans \c GraphWriter
324which handle the undirected graphs. These classes are the
325\c UndirGraphReader and \UndirGraphWriter.
326
327The \c readUndirMap() function reads an undirected map and the
328\c readUndirEdge() reads an undirected edge from the file,
329
330\code
331reader.readUndirEdgeMap("capacity", capacityMap);
332reader.readEdgeMap("flow", flowMap);
333...
334reader.readUndirEdge("undir_edge", undir_edge);
335reader.readEdge("edge", edge);
336\endcode
337
338\section advanced Advanced features
339
340The graph reader and writer classes gives an easy way to read and write
341graphs. But sometimes we want more advanced features. This way we can
342use the more general lemon reader and writer interface.
343
344The lemon format is an section oriented file format. It contains one or
345more section, each starts with a line with \c \@ first character.
346The content of the section this way cannot contain line with \c \@ first
347character. The file may contains comment lines with \c # first character.
348
349The \c LemonReader and \c LemonWriter gives a framework to read and
350write sections. There are various section reader and section writer
351classes which can be attached to a \c LemonReader or a \c LemonWriter.
352
353There are default section readers and writers for reading and writing
354item sets, and labeled items in the graph. These reads and writes
355the format described above. Other type of data can be handled with own
356section reader and writer classes which are inherited from the
357\c LemonReader::SectionReader or the \c LemonWriter::SectionWriter classes.
358
359The next example defines a special section reader which reads the
360\c \@description sections into a string:
361
362\code
363class DescriptionReader : LemonReader::SectionReader {
364protected:
365  virtual bool header(const std::string& line) {
366    std::istringstream ls(line);
367    std::string head;
368    ls >> head;
369    return head == "@description";
370  }
371
372  virtual void read(std::istream& is) {
373    std::string line;
374    while (getline(is, line)) {
375      desc += line;
376    }
377  }
378public:
379
380  typedef LemonReader::SectionReader Parent;
381 
382  DescriptionReader(LemonReader& reader) : Parent(reader) {}
383
384  const std::string& description() const {
385    return description;
386  }
387
388private:
389  std::string desc;
390};
391\endcode
392
393The other advanced stuff of the generalized file format is that
394multiple edgesets can be stored to the same nodeset. It can be used
395by example as a network traffic matrix.
396
397In example there is a network with symmetric links and there are assymetric
398traffic request on the network. This construction can be stored in an
399undirected graph and in an directed NewEdgeSetAdaptor class. The example
400shows the input with the LemonReader class:
401
402\code
403UndirListGraph network;
404UndirListGraph::UndirEdgeSet<double> capacity;
405NewEdgeSetAdaptor<UndirListGraph> traffic(network);
406NewEdgeSetAdaptor<UndirListGraph>::EdgeSet<double> request(network);
407
408LemonReader reader(std::cin);
409NodeSetReader nodesetReader(reader, network);
410UndirEdgeSetReader undirEdgesetReader(reader, network, nodesetReader);
411undirEdgesetReader.readEdgeMap("capacity", capacity);
412EdgeSetReader edgesetReader(reader, traffic, nodesetReader);
413edgesetReader.readEdgeMap("request", request);
414
415reader.run();
416\endcode
417
418Because the GraphReader and the UndirGraphReader can be converted
419to LemonReader and it can resolve the ID's of the items, the previous
420result can be achived with the UndirGraphReader class also.
421
422
423\code
424UndirListGraph network;
425UndirListGraph::UndirEdgeSet<double> capacity;
426NewEdgeSetAdaptor<UndirListGraph> traffic(network);
427NewEdgeSetAdaptor<UndirListGraph>::EdgeSet<double> request(network);
428
429UndirGraphReader reader(std::cin, network);
430reader.readEdgeMap("capacity", capacity);
431EdgeSetReader edgesetReader(reader, traffic, reader);
432edgesetReader.readEdgeMap("request", request);
433
434reader.run();
435\endcode
436
437\author Balazs Dezso
438*/
439}
Note: See TracBrowser for help on using the repository browser.