

===============================================================================
                                GENERAL INFORMATION
===============================================================================

This directory contains all code developed during my master's degree project,
"Comparison of Graph Theory invariants in predicting Fullerene stability". The
results of the main computations (the values of the invariants for each isomer)
can be found in the /results directory as follows: there is one directory for
each invariant, and (inside each directory) one .csv file for each (even) value
of N. Generally, the .csv file will have one column for the Isomer ID and another
for the value of the invariant (though there are some exceptions, like the Wiener
Index and Diameter, which are stored in the same files, using three columns).


The source code itself is store in the /source directory. Below is a brief
explanation of each of its subdirectories:

- bin: stores executables;
- bipartite-frustration: stores auxiliary files for the program calculating the
bipartite edge frustration;
- data: stores input and output files;
- fowler-manolopoulos: stores auxiliary files for the program calculating the
Fowler-Manolopoulos Criterion;
- fries-number: stores auxiliary files for the program calculating the Fries
Number;
- graph: stores auxiliary files for ad-hoc Graph classes (using adjacency lists
and adjacency matrices)
- independence-number: stores auxiliary files for the program calculating the
Independence Number;
- kekule-number: stores auxiliary files for the program calculating the Number
of Perfect Matchings (Number of Kekulé Structures);
- lib: empty, but can be used to store static libraries (.a files);
- planar2dual: stores auxiliary files for the program calculating the duals of
fullerene graphs in a given file;
- taylor-number: stores auxiliary files for the program calculating the Taylor
Number;
- test: stores the main files for each program, along with some libraries;
- wiener-diameter: stores auxiliary files for the program calculating both the
Wiener Index and the Diameter;


===============================================================================
                              COMPILATION AND USE
===============================================================================

1) Go to http://hog.grinvin.org/Fullerenes and download the fullerene graphs
you wish to use. Put them into the /data/in directory

2) Navigate to the source/test/invariant-name directory (where invariant-name is
the invariant you wish to compute), and use the make command

3) Go to the source/bin directory and run the executable: ./testInvariantName N1 N2
(where N1 and N2 define the range of N you wish to consider, for example 20 160)


Keep in mind that some invariants require the dual of the fullerene graph as
input. So after step 1 and before step 2 you should compile the planar2Dual
program (going into source/test/planar2dual and using make), and run it for the
same range you will use in step 3 (for example ./testPlanar2Dual 20 160). The duals
will be stored in the source/data/in/dual directory.


===============================================================================
                                LICENSE NOTICE
===============================================================================

The files under source/test/eigen, source/test/glpk-4.54 and source/test/mcqd are
open source libraries not developed by me, and are subject to their own licenses.
The empty directory source/test/blossom5-v2.02.src is where the Blossom library
(by Vladimir Kolmogorov) should be, if you wish to compile the program to compute
the bipartite edge frustration. The directory is empty because public redistribution
of that library is forbidden, and you should contact that author directly if you
wish to obtain a copy.

All other files and directories are subject to the following license:

These programs and files are distributed WITHOUT ANY WARRANTY, and they may be
freely redistributed under the condition that the copyright notices  are not
removed, and no compensation is received. Private, research, and institutional
use is free. Distribution of any of this code as part of a commercial system is
permissible ONLY BY DIRECT ARRANGEMENT WITH THE AUTHOR.


=== References ===
(Mcqd) Janez Konc and Dusanka Janezic. An improved branch and bound algorithm for
the maximum clique problem. MATCH Commun. Math. Comput. Chem., 2007, 58, 569-590.

(Eigen) Gaël Guennebaud and Benoît Jacob and others. http://eigen.tuxfamily.org

(GLPK) GNU Linear Programming Kit, http://www.gnu.org/software/glpk/glpk.html

(BlossomV) Vladimir Kolmogorov. "Blossom V: A new implementation of a minimum
cost perfect matching algorithm." In Mathematical Programming Computation (MPC),
July 2009, 1(1):43-67.



===============================================================================
                              CONTACT INFORMATION
===============================================================================

Thiago Lemos:       thalemos at inf.ufpr.br
Prof. André Guedes: andre    at inf.ufpr.br    (Advisor)











