The CyMeAlg Software (Release 0.01)
mainpage.h
Go to the documentation of this file.
1 /////////////////////////////////////////////////////////////////////////////
2 ///
3 /// \file
4 ///
5 /// The main page for the source code documentation.
6 ///
7 /////////////////////////////////////////////////////////////////////////////
8 /**
9 
10 \mainpage
11 
12 
13 \section intro Introduction
14 
15 This piece of software contains an implementation of a few graph algorithms,
16 and is mainly focused on demonstrating a new memory efficient version
17 of Karp's algorithm for the computation of minimum mean cycle weight
18 in a directed graph.
19 
20 
21 \section compilation Compilation
22 
23 The compilation of the software should be relatively simple.
24 The GNU C++ compiler should be used.
25 The Boost library collection should be present in the system.
26 Please, edit the file <em>makefile</em>
27 in the directory into which the source code has been unpacked,
28 one run the command <em>make</em>.
29 Although this software uses parts of
30 the <a href="http://chomp.rutgers.edu/software/">CHomP library</a>,
31 all the relevant files have been included in this distribution,
32 so it is not necessary to download or compile it first.
33 
34 In Linux, all the necessary utilities
35 should be present in the system by default
36 (the GNU C++ compiler and the GNU make),
37 but in Windows one should install them first (e.g. from the
38 <a href="http://www.bloodshed.net/dev/devcpp.html">Dev-C++</a>
39 distribution).
40 For convenience, pre-compiled binary programs for some systems
41 may be provided at the project website.
42 
43 
44 \section library Software Library
45 
46 The main part of this software is provided in terms
47 of a C++ library, programmed as templates of classes
48 and functions for optimal flexibility
49 (so-called generic programming technique).
50 All the header files of which the programming library consists
51 are located in the subdirectory <em>cymealg</em>.
52 
53 
54 \section program Test Program
55 
56 A simple command-line driven program is provided for testing purposes.
57 The program displays brief usage information
58 when called without arguments.
59 The program reads data from a file in the text format
60 and displays all the results to the output stream,
61 which is the screen by default,
62 but can also be logged to a file using the "--log filename"
63 command-line argument.
64 
65 
66 \section data Data Format
67 
68 A graph in the text format is stored in an intuitive way.
69 The vertices of the graph are assumed to be labeled
70 by consecutive integers, starting with 0.
71 The number of vertices in the graph is determined automatically
72 if there exists an outgoing edge from the vertex
73 with the higher number; otherwise it must be given explicitly.
74 Arcs are defined by the numbers of vertices
75 separated with an arrow bulit from the dash
76 and the "greater than" character.
77 Weights of each edge are provided in brackets
78 after the definition of each arc.
79 All text that begins with a semicolon is ignored
80 until the end of the line.
81 For example:
82 
83 <pre>
84 ; This is a sample graph.
85 4 vertices
86 0 -> 0 [1.12]
87 0 -> 1 [2.33]
88 1 -> 0 [-1e-6]
89 2 -> 0 [14]
90 </pre>
91 
92 \section examples Examples
93 
94 A selection of sample graphs are included in a separate file,
95 available for download from project's website.
96 Please, be warned that processing some of the larger examples
97 may require considerable resources (memory, CPU time).
98 
99 
100 \section license License
101 
102 This software package is published under the terms
103 of the <a href="http://www.gnu.org/licenses/gpl.html">GNU
104 General Public License, version 3</a>.
105 
106 
107 \section remark Remarks
108 
109 Although many classes and functions already have their descriptions,
110 I am aware of the fact that these descriptions are not as detailed
111 as the user might wish to have. Therefore, this documentation
112 has been generated in such a way that it includes the entire source code
113 which sould be consulted if in doubt. The code has many additional
114 comments which shed light on what it actually does.
115 
116 Therefore, I apologize for any inconvenience caused by the incomplete
117 documentation and I invite to browse the source code instead,
118 or ask me specific questions by email.
119 
120 Pawel Pilarczyk
121 
122 **/