
Guide to using buckygen
=======================

Author: Jan Goedgebeur (jan.goedgebeur@ugent.be)
In collaboration with: Gunnar Brinkmann (gunnar.brinkmann@ugent.be)
                       Brendan McKay (bdm@cs.anu.edu.au)


INTRODUCTION.

  Buckygen is a program for the efficient generation of all nonisomorphic
  fullerenes.  These are triangulations where all vertices have degree
  5 or 6.  Or if the dual representation is used: cubic plane graphs
  where all faces are pentagons or hexagons.  Euler's formula implies
  that a fullerene contains exactly 12 pentagonal faces.

  The program can also be used to generate IPR fullerenes, these are 
  fullerenes which have no adjacent degree 5 vertices.

  Buckygen has been tested on Linux and Mac OS X.


INSTALLING buckygen.

  The latest version of buckygen can be obtained from
     http://caagt.ugent.be/buckygen/

  After extracting the buckygen zipfile, compile buckygen
  using the command "make".  Alternatively you can also
  compile it using:
    cc -O4 buckygen.c -o buckygen

  Important: splay.c must be in the same directory as buckygen.c


RUNNING buckygen.

  An overview of all options can also be found by executing "./buckygen".
  Most parameters are the same as in plantri.  More information about
  plantri can be found here: http://cs.anu.edu.au/~bdm/plantri/

  Usage: ./buckygen [-uagsh -IS#rq -odV -v] n [res/mod] [outfile]

  The only compulsory parameter is the number of vertices n.
  By default the generated fullerenes encoded in planar_code and 
  written to stdout.  The output formats are described below.

  An example of a buckygen run is:  
      ./buckygen 32 fuller_32
  which generates all triangulations with 32 vertices where all 
  vertices have degree 5 or 6 and writes them to a file with
  name "fuller_32".  The number of vertices "32" can also be given 
  as "60d" (the suffix 'd' means 'dual') in which case it is
  converted by adding 4 then dividing by 2: (60+4)/2 = 32.
  This calculation yields the number of faces of the triangulation,
  which is the number of vertices in the dual cubic graph.
  More examples will be given below.

  Apart from the one compulsory parameter, there are three types of optional
  parameters:

  *  SWITCHES are introduced by a '-' character.  If there are more than one
     they can be arbitrarily concatenated or separated.  They can also appear
     anywhere.  For example, these command lines are all equivalent:
        buckygen 32 -S12 -d -u
        buckygen 32 -S12du
        buckygen 32 -udS12
        buckygen -ud 32 -S12
     The meanings of the switches are explained in the next sections.

  *  An OUTPUT FILE can be given, if you want the graphs to be sent somewhere
     other than standard output.  Information other than graphs (such as
     statistics) is written to the standard error stream.

  *  A RES/MOD pair can be given to split the generation in MOD (more or
     less equally big) parts. This pair comprises two integers with
     '/' between, such as 13/100.  The first integer can be from 0 to one
     less than the second number.  In this example part 13 will be executed.
     Splitting the generation causes a small overhead, so the sum of the 
     timings for the small parts will be slightly more than the time needed
     to run the same case without modulo.  But this overhead is usually 
     negligible compared to the total execution time.
     The normal rules for modulo calculation apply.  So '0/2' will give the
     same result as '0/4' and '2/4' combined.

  Parameters and switches may appear in any order with one exception:
  the compulsory parameter (number of vertices) must precede any
  output file or res/mod parameters.


SWITCHES.

  -S#  Output all fullerenes with 'i' vertices (# <= i <= n) instead of 
       only the fullerenes with 'n' vertices.  Since buckygen recursively
       constructs all fullerenes from smaller fullerenes, using switch -S
       only gives a minor overhead.

  -I   Only generate and output the IPR fullerenes.  In this case a
       specialized generator for IPR fullerenes is used, so this 
       is done quite efficiently.

  -d   Causes the dual graph to be written instead of the original graph.
       The dual graph of a triangulation where all vertices have degree
       5 or 6 is a cubic plane graph where all faces are pentagons or 
       hexagons.
       Note that it is applied only at the output stage.  All other switches
       refer to the original graph before the dual is taken.  For example,
       -S12 (start output from 12 vertices) refers to the original graph 
       (so to a triangulation) and not to the dual.

  -r   Tests if the generated fullerenes have spirals starting at a 
       degree 5 or a degree 6 vertex. Fullerenes which do not have a
       spiral starting at a degree 5 vertex are written to a file named
       "No_pentagon_spiral_x". And fullerenes which do not have a spiral
       starting at any vertex of the fullerene are written to a file named
       "No_spiral_x".

  -o   Normally, one member of each isomorphism class is written.  If this
       switch is given, one member of each orientation preserving (O-P) 
       isomorphism class is written.
       Since graph6 and sparse6 formats don't encode the imbedding anyway,
       this switch is ignored for output purposes if you use -g or -s.

  -V   Only output graphs with non-trivial group.  If -o is given, the
       O-P group is used.

  -v   Buckygen will always tell you (by a message to standard error) the
       number of graphs that were produced.  If you specify -v, it might
       tell you some additional statistical information.  For example, if
       you use -o, -v will cause it to also inform you of the number of
       isomorphism classes as well as the number of isomorphism classes
       which are O-P isomorphic to their mirror images.

  -q   Work in 'quiet' mode: does not output any information to the
       standard error stream.


OUTPUT FORMATS.

  Buckygen can write graphs in a variety of different formats.

  PLANAR CODE is the default format.  It is the preferred format if you plan
     to feed the graph into a program that needs the imbedding, and also
     convenient if you don't need the imbedding.  However, it uses characters
     which are not printable so it is not suitable for looking at by eye.

  ASCII CODE is a human-readable version of planar code.  The vertices of
     the graph are named by ASCII characters starting with 'a'.  Example:
        7 bcdefg,agfdc,abd,acbfe,adf,aedbg,afb
     This is a graph with 7 vertices a,b,c,d,e,f,g.  The neighbours of
     'a' in clockwise order are b,c,d,e,f,g; and so on.  Each graph occupies
     one line of output.  Ascii code is convenient if you just want to draw
     a few graphs by hand.
     To select ascii code use -a.

  GRAPH6 is a compact code for the abstract structure of a graph.
     The imbedding is not represented, so this is not a suitable code to
     use if you want the imbedding.  It is also restricted to simple
     graphs.  graph6 is one of the formats supported by Brendan McKay's
     'gtools' package.  Each graph occupies one line.
     To select graph6 code use -g.

  SPARSE6 is a compact code for the abstract structure of a graph which is
     optimized for sparse graphs.  If you don't want the imbedding and are
     dealing with cubic graphs of 20 or more vertices, sparse6 is a good
     choice.  sparse6 is one of the formats supported by Brendan McKay's
     'gtools' package.  Each graph occupies one line.
     To select sparse6 code use -s.

  Each of those formats except for ascii code also has a standard header,
  which is written to the output at the beginning:

      format           header            written by default?
   
    planar code     >>planar_code<<             yes
      graph6        >>graph6<<                  no
     sparse6        >>sparse6<<                 no

  In each case the header is written with no end-of-line characters after
  it (for portability reasons).  To write a header when the default is not
  to, or vice-versa, use -h.

  If you only want to count the graphs and not write them, use -u to 
  select no output.

  Details of these formats is given in Appendices A and B.


EXAMPLES.

  Below are some examples of possible execution parameters.
  
  ./buckygen 65 -S32 -I
  Generates and outputs all IPR fullerenes with at most 65 and at least 32
  vertices and writes them to the standard output stream in planar code.

  ./buckygen 55 -S20d fuller_55_20
  Generates all fullerenes with at most 55 and at least 20 vertices
  and writes their dual graph (i.e. a cubic graph) to a file with name
  "fuller_55_20".

  ./buckygen 52 -ru
  Generates all fullerenes with 52 vertices, but does not output them.
  Also checks if the fullerenes have a spiral starting at a pentagon
  or a hexagon.

  ./buckygen 132 -Ig 10/200
  Splits the generation of all IPR fullerenes with 132 vertices in 200 parts
  and executes part 10 and outputs the fullerenes in graph6 format to
  the standard output stream.


APPENDIX A.  Definition of PLANAR CODE.

  PLANAR CODE is the default output format for buckygen.  The vertices of
  the graph are numbered starting at 1.  PLANAR CODE represents the graph
  by a series of bytes, whose unsigned numerical values (0..255) are
  significant.  The first byte gives the number of vertices n.  Then there
  are n sections, where section v contains the neighbours of vertex v in
  clockwise order followed by a zero byte.   There is no end-of-line
  character appended.

  In addition to the encodings of graphs, a PLANAR CODE file by default
  begins with the 15 characters >>planar_code<< without end-of-line
  characters.


APPENDIX B.  Definition of GRAPH6 and SPARSE6.

  All numbers in this description are in decimal unless obviously in
  binary.  GRAPH6 and SPARSE6 are text formats, and a file containing
  them is a text file.

  Apart from the header, there is one object per line.  Apart from the
  header and the end-of-line characters, all bytes have a value in the
  range 63-126 (which are all printable ASCII characters).

  BIT VECTORS:

  A bit vector x of length k can be represented as follows.  
      Example:  1000101100011100

  (1) Pad on the right with 0 to make the length a multiple of 6.
      Example:  100010110001110000

  (2) Split into groups of 6 bits each.
      Example:  100010 110001 110000

  (3) Add 63 to each group, considering them as bigendian binary numbers.
      Example:  97 112 111

  These values are then stored one per byte.  
  So, the number of bytes required is ceiling(k/6).

  Let R(x) denote this representation of x as a string of bytes.
      
  SMALL NONNEGATIVE INTEGERS:
 
  Let n be an integer in the range 0-262143 (262143 = 2^18-1).

  If 0 <= n <= 62, define N(n) to be the single byte n+63.
  If n >= 63, define N(n) to be the four bytes 126 R(x), where
    x is the bigendian 18-bit binary form of n.

  Examples:  N(30) = 93
             N(12345) = N(000011 000000 111001) = 126 69 63 120


  GRAPH6 format:

  Suppose G has n vertices.  Write the upper triangle of the adjacency
  matrix of G as a bit vector x of length n(n-1)/2, using the ordering
  (0,1),(0,2),(1,2),(0,3),(1,3),(2,3),...,(n-1,n).

  Then the graph is represented as  N(n) R(x).

    Example: Suppose n=5 and G has edges 0-2, 0-4, 1-3 and 3-4.

       x = 0 10 010 1001
    
       Then N(n) = 68 and R(x) = R(010010 100100) = 81 99.
       So, the graph is  68 81 99.

  Note that GRAPH6 format cannot represent loops or parallel edges.

  SPARSE6 format:

  The encoded graph consists of:
     (1) The character ':'.   (This is present to distinguish
                                  the code from GRAPH6 format.)
     (2) The number of vertices.
     (3) A list of edges.
     (4) end-of-line

  Loops and multiple edges are supported, but not directed edges.

  Number of vertices n:  Represented as N(n) like in GRAPH6 format.

  List of edges:

    Let k be the number of bits needed to represent n-1 in binary.
    The remaining bytes encode a sequence R(z) where
      z = b[0] x[0] b[1] x[1] b[2] x[2] ... b[m] x[m] 111...

    Each b[i] occupies 1 bit, and each x[i] occupies k bits, and the number
    of 1's at the end is the least needed to make the total length a 
    multiple of 6.

    The vertices of the graph are 0..n-1.
    The edges encoded by this sequence are determined thus:

       v = 0
       for i from 0 to m do
          if b[i] = 1 then v = v+1 endif;
          if x[i] > v then v = x[i] else output {x[i],v} endif
       endfor

    Example:    :Fa@x^
    ':' indicates sparse6 format.
    Subtract 63 from the other bytes and write them in binary, six bits each.
         000111 100010 000001 111001 011111
    The first byte is not 63, so it is n.  n=7
    n-1 needs 3 bits (k=3).  Write the other bits in groups of 1 and k:
      1 000  1 000  0 001  1 110   0 101  1 111
    This is the b/x sequence  1,0 1,0 0,1 1,6 0,5 1,7.
    The 1,7 at the end is just padding.
    The remaining pairs give the edges 0-1 1-2 5-6.


APPENDIX C.  Fullerene Counts.

  In this section we the counts of the fullerenes which were generated
  with buckygen.

  The column headings in these tables are:

  nv = number of vertices (or faces in the dual)
  nf = number of faces (or vertices in the dual)

   ----------------------------------------------------------------

    nv   nf     fullerenes  IPR fullerenes

    20   12 |            1            0
    22   13 |            0            0
    24   14 |            1            0
    26   15 |            1            0
    28   16 |            2            0
    30   17 |            3            0
    32   18 |            6            0
    34   19 |            6            0
    36   20 |           15            0
    38   21 |           17            0
    40   22 |           40            0
    42   23 |           45            0
    44   24 |           89            0
    46   25 |          116            0
    48   26 |          199            0
    50   27 |          271            0
    52   28 |          437            0
    54   29 |          580            0
    56   30 |          924            0
    58   31 |         1205            0
    60   32 |         1812            1
    62   33 |         2385            0
    64   34 |         3465            0
    66   35 |         4478            0
    68   36 |         6332            0
    70   37 |         8149            1
    72   38 |        11190            1
    74   39 |        14246            1
    76   40 |        19151            2
    78   41 |        24109            5
    80   42 |        31924            7
    82   43 |        39718            9
    84   44 |        51592           24
    86   45 |        63761           19
    88   46 |        81738           35
    90   47 |        99918           46
    92   48 |       126409           86
    94   49 |       153493          134
    96   50 |       191839          187
    98   51 |       231017          259
   100   52 |       285914          450
   102   53 |       341658          616
   104   54 |       419013          823
   106   55 |       497529         1233
   108   56 |       604217         1799
   110   57 |       713319         2355
   112   58 |       860161         3342
   114   59 |      1008444         4468
   116   60 |      1207119         6063
   118   61 |      1408553         8148
   120   62 |      1674171        10774
   122   63 |      1942929        13977
   124   64 |      2295721        18769
   126   65 |      2650866        23589
   128   66 |      3114236        30683
   130   67 |      3580637        39393
   132   68 |      4182071        49878
   134   69 |      4787715        62372
   136   70 |      5566949        79362
   138   71 |      6344698        98541
   140   72 |      7341204       121354
   142   73 |      8339033       151201
   144   74 |      9604411       186611
   146   75 |     10867631       225245
   148   76 |     12469092       277930
   150   77 |     14059174       335569
   152   78 |     16066025       404667
   154   79 |     18060979       489646
   156   80 |     20558767       586264
   158   81 |     23037594       697720
   160   82 |     26142839       836497
   162   83 |     29202543       989495
   164   84 |     33022573      1170157
   166   85 |     36798433      1382953
   168   86 |     41478344      1628029
   170   87 |     46088157      1902265
   172   88 |     51809031      2234133
   174   89 |     57417264      2601868
   176   90 |     64353269      3024383
   178   91 |     71163452      3516365
   180   92 |     79538751      4071832
   182   93 |     87738311      4690880
   184   94 |     97841183      5424777
   186   95 |    107679717      6229550
   188   96 |    119761075      7144091
   190   97 |    131561744      8187581
   192   98 |    145976674      9364975
   194   99 |    159999462     10659863
   196  100 |    177175687     12163298
   198  101 |    193814658     13809901
   200  102 |    214127742     15655672
   202  103 |    233846463     17749388
   204  104 |    257815889     20070486
   206  105 |    281006325     22606939
   208  106 |    309273526     25536557
   210  107 |    336500830     28700677
   212  108 |    369580714     32230861
   214  109 |    401535955     36173081
   216  110 |    440216206     40536922
   218  111 |    477420176     45278722
   220  112 |    522599564     50651799
   222  113 |    565900181     56463948
   224  114 |    618309598     62887775
   226  115 |    668662698     69995887
   228  116 |    729414880     77831323
   230  117 |    787556069     86238206
   232  118 |    857934016     95758929
   234  119 |    925042498    105965373
   236  120 |   1006016526    117166528
   238  121 |   1083451816    129476607
   240  122 |   1176632247    142960479
   242  123 |   1265323971    157402781
   244  124 |   1372440782    173577766
   246  125 |   1474111053    190809628
   248  126 |   1596482232    209715141
   250  127 |   1712934069    230272559
   252  128 |   1852762875    252745513
   254  129 |   1985250572    276599787
   256  130 |   2144943655    303235792
   258  131 |   2295793276    331516984
   260  132 |   2477017558    362302637
   262  133 |   2648697036    395600325
   264  134 |   2854536850    431894257
   266  135 |   3048609900    470256444
   268  136 |   3282202941    512858451
   270  137 |   3501931260    557745670
   272  138 |   3765465341    606668511
   274  139 |   4014007928    659140287
   276  140 |   4311652376    716217922
   278  141 |   4591045471    776165188
   280  142 |   4926987377    842498881
   282  143 |   5241548270    912274540
   284  144 |   5618445787    987874095
   286  145 |   5972426835   1068507788
   288  146 |   6395981131   1156161307
   290  147 |   6791769082   1247686189
   292  148 |   7267283603   1348832364
   294  149 |   7710782991   1454359806
   296  150 |   8241719706   1568768524
   298  151 |   8738236515   1690214836
   300  152 |   9332065811   1821766896
   302  153 |   9884604767   1958581588
   304  154 |  10548218751   2109271290
   306  155 |  11164542762   2266138871
   308  156 |  11902015724   2435848971
   310  157 |  12588998862   2614544391
   312  158 |  13410330482   2808510141
   314  159 |  14171344797   3009120113
   316  160 |  15085164571   3229731630
   318  161 |  15930619304   3458148016
   320  162 |  16942010457   3704939275
   322  163 |  17880232383   3964153268
   324  164 |  19002055537   4244706701
   326  165 |  20037346408   4533465777
   328  166 |  21280571390   4850870260
   330  167 |  22426253115   5178120469
   332  168 |  23796620378   5531727283
   334  169 |  25063227406   5900369830
   336  170 |  26577912084   6299880577
   338  171 |  27970034826   6709574675
   340  172 |  29642262229   7158963073
   342  173 |  31177474996   7620446934
   344  174 |  33014225318   8118481242
   346  175 |  34705254287   8636262789
   348  176 |  36728266430   9196920285
   350  177 |  38580626759   9768511147
   352  178 |  40806395661  10396040696
   354  179 |  42842199753  11037658075
   356  180 |  45278616586  11730538496
   358  181 |  47513679057  12446446419
   360  182 |  50189039868  13221751502
   362  183 |  52628839448  14010515381
   364  184 |  55562506886  14874753568
   366  185 |  58236270451  15754940959
   368  186 |  61437700788  16705334454
   370  187 |  64363670678  17683643273
   372  188 |  67868149215  18744292915
   374  189 |  71052718441  19816289281
   376  190 |  74884539987  20992425825
   378  191 |  78364039771  22186413139
   380  192 |  82532990559  23475079272
   382  193 |  86329680991  24795898388
   384  194 |  90881152117  26227197453
   386  195 |  95001297565  27670862550
   388  196 |  99963147805  29254036711
   390  197 | 104453597992  30852950986
   392  198 | 109837310021  32581366295
   394  199 | 114722988623  34345173894
   396  200 | 120585261143  36259212641
   398  201 | 125873325588  38179777473
   400  202 | 132247999328  40286153024


APPENDIX D.  Version History

Version 1.0:
  Released on May 31, 2012.

