*******************************************************************************
* 1. Introduction                                                             *
*******************************************************************************

Here, we describe the steps that used to create the census of Platonic
tessellations and manifolds. As examples, we show the creation of the
orientable cusped census {3,4,4} with up to 3 octahedra (o344_up_to_3) and the
non-orientable closed census {4,3,5} with up to 5 cubes (n435_up_to_5).
The generation of other census works analogously. The data for the cusped
tetrahedral censuses were taken from the earlier paper ``A census of
tetrahedral manifolds''.

The census was created with SnapPy with features that have been contributed
after 2.3.2 and will be in version 2.4, Regina version 4.96, and Sage 6.7
under Linux. SnapPy was compiled and installed under Sage (see
http://www.math.uic.edu/t3m/SnapPy/installing.html).

*******************************************************************************
* 2. Cusped Platonic Tessellations                                            *
*******************************************************************************

We give as example how to compute orientable cusped octahedral tessellations
and manifolds with up to 3 octahedra (o344_up_to_3).

* Step 0: Compile the code in src/, see instructions in src/COMPILE.

* Step 1: Generate all isomorphism signatures of barycentric subdivisions of
  Platonic tessellations of a given type:

     src/genIsomoSigsOfPlatonicTessellations 3 4 4 3 o > data/o344_up_to_3.txt

  The output is just a list of isomorphism signatures, one per line.

* Step 2: Compute the isometry signature for each isomorphism signature:

     sage -python ../python/computeIsometrySignatures.py o344_up_to_3.txt

  This produces a file isometry_signatures_o344_up_to_3.txt. Each line is a
  pair of an isomorphism signature of the barycentric subdivision of a Platonic
  tessellation and the corresponding isometry signature.

* Step 3: Group by isometry signature and assign names to obtain the
  namedIsometryic_... file:

     python python/groupAndNameIsometricIsomoSigsOfPlatonicTessellations.py \
            oct \
            data/isometry_signatures_o344_up_to_3.txt \
            ooct%02_%05d \
            > data/namedIsometric_o344_up_to_3.txt

  Each line of the output file starts with the name of a Platonic manifold,
  followed by the isomorphism signatures of the corresponding tessellations,
  and the isometry signature of the Platonic manifold.

Step 4 is independent of Step 5-8.

* Step 4: Generate the regina census files. Besides the input and ouput file,
  the label of the root item in the regina file is specified:

     python python/genReginaCensusFile.py \
            data/namedIsometric_o344_up_to_3.txt \
            "Octahedral Orientable Cusped Census" \
            regina/octahedralOrientableCuspedCensus.rga

* Step 5: Find a geometric ideal triangulation for every manifold for SnapPy.
  The following script will remove finite vertices and then randomize until
  a geometric solution can be found:

     python python/findGeometricForCusped.py \
            data/namedIsometric_o344_up_to_3.txt \
            snappy/geometric_o344_up_to_3.txt

  Each line of the output file starts with the name of a Platonic manifold, the
  isomorphism signature of a geometric ideal triangulation, and the isometry
  signature.

  For the tetrahedral census, this step can be skipped.

* Step 6: Generate the snappy census file. Besides the input and output file,
  the name of the SQL table is specified:

     python python/genSnapPyCensusFile.py \
            snappy/geometric_o344_up_to_3.txt \
            octahedral_orientable_cusped_census \
            snappy/octahedralOrientableCuspedCensus.sqlite

* Step 7 (only for octahedral orientable cusped census): Follow the steps in
  AugKTG/LINK_CREATION.txt to add the augmented knotted trivalent graphs to the
  SnapPy file.

* Step 8 (for faster look ups): Add index on "name" column to
  sqlite file:

     CREATE UNIQUE INDEX octahedral_orientable_cusped_census_name_index
                      ON octahedral_orientable_cusped_census (name);

*******************************************************************************
* 3. Closed Platonic Tessellations                                            *
*******************************************************************************

We give as example how to compute closed non-orientable cubical tesselations and
manifolds with 5 cubes (n435_up_to_5).

* Step 0: As in the cusped case.

* Step 1a: As in the cusped case, but add "_unfiltered" to the name of the
  output file in the non-orientable case:

     src/genIsomoSigsOfPlatonicTessellations 4 3 5 5 n \
                                           > data/n435_up_to_5.txt_unfiltered

* Step 1b (only necessary for non-orientable case): Remove the non-manifold
  cases from the output n435_up_to_5.txt_unfiltered:

     python python/filterManifolds.py \
            data/n435_up_to_5.txt_unfiltered \
          > data/n435_up_to_5.txt  

* Step 2: Similar to cusped case, but use instead:

     python python/computeInvariantForClosedManifolds.py data/n435_up_to_5.txt

  The last entry of each output line will be the invariant instead of the
  isometry signature.

* Step 3a: As in the cusped case.
  (with "isometry_signatures" replaced by "special_invariants")

* Step 3b: Check that the invariant (computed in step 2 and used in step 3a)
  was strong enough to separate all manifolds, i.e., for any two tessellations
  that have the same invariant find an isometry. If this were not the case, the
  following program will print "FAIL".

     python python/checkInvariantForClosedManifoldsIsStrongEnough.py \
            data/special_invariants_n435_up_to_5.txt

Step 4 is independent of Step 5-8.

* Step 4: As in the cusped case.

* Step 5: Similarly to cusped case, convert each Platonic manifold (now closed)
  into a description that SnapPy can understand, i.e., as Dehn filling of a
  cusped manifold.
  The following script tries to convert the triangulation with finite vertices
  into a Dehn-filling of a cusped manifold using SnapPy. If this does not
  yield a geometric solution, it retries using regina to randomize the
  triangulation with finite vertices.

     python python/findGeometricForClosed.py \
            data/namedIsometric_n435_up_to_5.txt \
            > snappy/geometric_n435_up_to_5.txt

* Step 6: As in the cusped case, e.g.:

     python python/genSnapPyCensusFile.py \
            snappy/geometric_n435_up_to_5.txt \
            cubical_nonorientable_closed_census \
            snappy/cubicalNonorientableClosedCensus.sqlite

* No step 7.

* Step 8: As in the cusped case.

*******************************************************************************
* 6. Parallelization                                                          *
*******************************************************************************

Step 2 and 5 can be parallelized using the "split" and "cat" command, for
example (also see below remark about "parallel"):

    cd data
    split --additional-suffix .txt -a 4 -l 10 o344_up_to_3.txt o344_up_to_3_part
    parallel sage -python \
               ../python/computeIsometrySignatures {} -- o344_up_to_3_part*txt
    cat isometry_signatures_o344_up_to_3_part*txt \
      > isometry_signatures_o344_up_to_3.txt

Step 6 can be parallelized using the "split" command and "mergeDatabases.py"
script, for example:

    cp data/namedIsometric_n436_up_to_6.txt snappy/
    cd snappy
    split --additional-suffix .txt -a 3 -l 10000 \
           namedIsometric_n436_up_to_6.txt namedIsometric_n436_up_to_6_part
    parallel python ../python/genSnapPyCensusFile.py \
                             {} cubical_nonorientable_cusped_census \
                             {}.sqlite \
                             -- namedIsometric_n436_up_to_6_part*.txt
    python ../python_large/mergeDatabases.py \
           cubical_nonorientable_cusped_census \
           cubicalNonorientableCuspedCensusNew.sqlite \
           namedIsometric_n436_up_to_6_part*.txt.sqlite

Remark: In the infinite wisdom of Debian/Ubuntu Linux, there are three
versions of "parallel", each with a slightly different syntax:

  * The above examples work with the version of "parallel" that comes with
    the "moreutils" package ("sudo apt-get install moreutils") in old Linux
    versions.
  * Add "-i" for the version of "parallel" that comes with the "moreutils"
    package in new Linux versions (Ubuntu 15.10?).
  * There is another version of "parallel" that comes with the "parallel"
    package in new Linux versions. That version curses itself "GNU parallel".
    It requires replacing "--" by ":::" and maybe adding "-i". I have never
    tested it. On purpose, because I do not want to cite "Ole Tange (2011): 
    GNU Parallel..." or pay 10000Euros which you need to when you use it --
    unlike any other GNU program I am aware of.