# source:lemon-0.x/doc/lemon_file_format.dox@2391:14a343be7a5a

Last change on this file since 2391:14a343be7a5a was 2391:14a343be7a5a, checked in by Alpar Juttner, 13 years ago

Happy New Year to all source files!

File size: 8.4 KB
Line
1/* -*- C++ -*-
2 *
3 * This file is a part of LEMON, a generic C++ optimization library
4 *
5 * Copyright (C) 2003-2007
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
19namespace lemon {
20/*!
21
22
23\page lemon_file_format LEMON Graph File Format
24
25The standard graph IO enables one to store graphs and additional maps
26(i.e. functions on the nodes or edges) in a flexible and efficient way.
27Before you read this page you should be familiar with LEMON
28\ref graphs "graphs" and \ref maps-page "maps".
29
30\section format The general file format
31
32The file contains sections in the following order:
33
34\li nodeset
35\li edgeset
36\li nodes
37\li edges
38\li attributes
39
40Some of these sections can be omitted, but you will basicly need the nodeset
41section (unless your graph has no nodes at all) and the edgeset section
42(unless your graph has no edges at all).
43
44The nodeset section describes the nodes of your graph: it identifies the nodes
45and gives the maps defined on them, if any. It starts with the
46following line:
47
48<tt>\@nodeset</tt>
49
50The next line contains the names of the nodemaps, separated by whitespaces.  Each
51following line describes a node in the graph: it contains the values of the
52maps in the right order. The map named "label" should contain unique values
53because it is regarded as a label map. These labels need not be numbers but they
54must identify the nodes uniquely for later reference. For example:
55
56\code
57@nodeset
58label  x-coord  y-coord  color
593   1.0      4.0      blue
605   2.3      5.7      red
6112  7.8      2.3      green
62\endcode
63
64The edgeset section is very similar to the nodeset section, it has
65the same coloumn oriented structure. It starts with the line
66
67<tt>\@edgeset</tt>
68
69The next line contains the whitespace separated list of names of the edge
70maps.  Each of the next lines describes one edge. The first two elements in
71the line are the labels of the source and target (or tail and head) nodes of the
72edge as they occur in the label node map of the nodeset section. You can also
73have an optional label map on the edges for later reference (which has to be
74unique in this case).
75
76\code
77@edgeset
78             label      weight   note
793   5        a          4.3      a-edge
805   12       c          2.6      c-edge
813   12       g          3.4      g-edge
82\endcode
83
84The \e nodes section contains <em>labeled (distinguished) nodes</em>
85(i.e. nodes having a special
86label on them). The section starts with
87
88<tt> \@nodes </tt>
89
90Each of the next lines contains a label for a node in the graph
91and then the label as described in the \e nodeset section.
92
93\code
94@nodes
95source 3
96target 12
97\endcode
98
99The last section describes the <em>labeled (distinguished) edges</em>
100(i.e. edges having a special label on them). It starts with \c \@edges
101and then each line contains the name of the edge and the label.
102
103\code
104@edges
105observed c
106\endcode
107
108
109The file may contain empty lines and comment lines. The comment lines
111
112The attributes section can handle some information about the graph. It
113contains key-value pairs in each line (a key and the mapped value to key). The
114key should be a string without whitespaces, the value can be of various types.
115
116\code
117@attributes
118title "Four colored planar graph"
119author "Balazs DEZSO"
121version 12
122\endcode
123
124Finally, the file should be closed with \c \@end line.
125
126
127\section use Using graph input-output
128
129
130The graph input and output is based on <em> reading and writing
131commands</em>. The user gives reading and writing commands to the reader or
132writer class, then he calls the \c run() method that executes all the given
133commands.
134
135\subsection write Writing a graph
136
137The \ref lemon::GraphWriter "GraphWriter" template class
138provides the graph output. To write a graph
139you should first give writing commands to the writer. You can declare
140writing command as \c NodeMap or \c EdgeMap writing and labeled Node and
141Edge writing.
142
143\code
144GraphWriter<ListGraph> writer(std::cout, graph);
145\endcode
146
147The \ref lemon::GraphWriter::writeNodeMap() "writeNodeMap()"
148function declares a \c NodeMap writing command in the
149\ref lemon::GraphWriter "GraphWriter".
150You should give a name to the map and the map
151object as parameters. The NodeMap writing command with name "label" should write a
152unique map because it will be regarded as a label map.
153
154\see IdMap, DescriptorMap
155
156\code
157IdMap<ListGraph, Node> nodeLabelMap;
158writer.writeNodeMap("label", nodeLabelMap);
159
160writer.writeNodeMap("x-coord", xCoordMap);
161writer.writeNodeMap("y-coord", yCoordMap);
162writer.writeNodeMap("color", colorMap);
163\endcode
164
165With the \ref lemon::GraphWriter::writeEdgeMap() "writeEdgeMap()"
166member function you can give an edge map
167writing command similar to the NodeMaps.
168
169\see IdMap, DescriptorMap
170
171\code
172DescriptorMap<ListGraph, Edge, ListGraph::EdgeMap<int> > edgeDescMap(graph);
173writer.writeEdgeMap("descriptor", edgeDescMap);
174
175writer.writeEdgeMap("weight", weightMap);
176writer.writeEdgeMap("note", noteMap);
177\endcode
178
179With \ref lemon::GraphWriter::writeNode() "writeNode()"
180and \ref lemon::GraphWriter::writeEdge() "writeEdge()"
181functions you can designate Nodes and
182Edges in the graph. For example, you can write out the source and target node
183of a maximum flow instance.
184
185\code
186writer.writeNode("source", sourceNode);
187writer.writeNode("target", targetNode);
188
189writer.writeEdge("observed", edge);
190\endcode
191
192With \ref lemon::GraphWriter::writeAttribute() "writeAttribute()"
193function you can write an attribute to the file.
194
195\code
196writer.writeAttribute("author", "Balazs DEZSO");
197writer.writeAttribute("version", 12);
198\endcode
199
200After you give all write commands you must call the
201\ref lemon::GraphWriter::run() "run()" member
202function, which executes all the writing commands.
203
204\code
205writer.run();
206\endcode
207
209
210The file to be read may contain several maps and labeled nodes or edges.
211If you read a graph you need not read all the maps and items just those
212that you need. The interface of the \ref lemon::GraphReader "GraphReader"
213is very similar to
214the \ref lemon::GraphWriter "GraphWriter"
215but the reading method does not depend on the order of the
216given commands.
217
218The reader object assumes that each not read value does not contain
219whitespaces, therefore it has some extra possibilities to control how
220it should skip the values when the string representation contains spaces.
221
222\code
224\endcode
225
227function reads a map from the \c nodeset section.
228If there is a map that you do not want to read from the file and there are
229whitespaces in the string represenation of the values then you should
230call the \ref lemon::GraphReader::skipNodeMap() "skipNodeMap()"
231template member function with proper parameters.
232
234
235\code
238
241
243\endcode
244
246member function you can give an edge map
247reading command similar to the NodeMaps.
248
249\code
252\endcode
253
256functions you can read labeled Nodes and
257Edges.
258
259\code
262
264\endcode
265
267function you can read an attribute from the file.
268
269\code
270std::string author;
272int version;
273writer.writeAttribute("version", version);
274\endcode
275
276After you give all read commands you must call the
277\ref lemon::GraphReader::run() "run()" member
278function, which executes all the commands.
279
280\code