/*
 *  tersest_triangulation.h
 *
 *  This data structure -- which is really just a formatting convention for
 *  an array of chars -- compresses the information in a TerseTriangulation
 *  to the maximum extent possible.  It works only for Triangulations of 7
 *  or fewer Tetrahedra.  It is intended for use in storing libraries of
 *  manifolds, such as the 5-, 6- and 7-tetrahedron censuses.
 *
 *  Here's how the information from the TerseTriangulation data structure
 *  is stored.  The description is for a 7-tetrahedron Triangulation.
 *  With fewer Tetrahedra some bits will be unused, but we always use
 *  the same number of bytes.  (The reason we always use the same number
 *  of bytes is so that we can retrieve a manifold from the middle of a long
 *  file without reading the whole file.)  Recall that a TerseTriangulation
 *  for n Tetrahedra has a glues_to_old_tet[] array of length 2n, and
 *  which_old_tet[] and which_gluing[] arrays of length n+1.  So for
 *  7 Tetrahedra, glues_to_old_tet[] has length 14, while which_old_tet[]
 *  and which_gluing[] each have length 8.
 *
 *  num_tetrahedra
 *
 *      is redundant and is not stored at all.  The number of Tetrahedra can
 *      be deduced from the glues_to_old_tet array by keeping track of how
 *      many free faces are available at each stage.
 *
 *  glues_to_old_tet[]
 *
 *      is stored in the first two bytes of the TersestTriangulation string.
 *
 *      glues_to_old_tet[0] is stored in the lowest-order  bit of byte 0,
 *      . . . and so on until . . .
 *      glues_to_old_tet[7] is stored in the highest-order bit of byte 0.
 *
 *      glues_to_old_tet[8] is stored in the lowest-order  bit of byte 1,
 *      . . . and so on until . . .
 *      glues_to_old_tet[13] is stored in the sixth bit of byte 1.
 *
 *      Note that the two highest-order bits in byte 1 remain available for
 *      other purposes.  The highest-order bit tells whether a Chern-Simons
 *      invariant is present (cf. below).
 *
 *  which_old_tet[]
 *  which_gluing[]
 *
 *      which_old_tet[] and which_gluing[] are stored in tandem.
 *
 *      which_old_tet[i] is stored in the three highest-order bits
 *          of byte 2+i.  which_old_tet[i] will always be an integer
 *          in the range [0, 6], so it fits comfortably in three bits.
 *
 *      which_gluing[i] is stored in the five lowest-order bits
 *          of byte 2+i.  Each Permutation is converted to an integer
 *          in the range [0, 23], which fits comfortably in five bits.
 *          The array index_by_permutation[] in tables.c does the conversion.
 *
 *  CS_is_present
 *  CS_value
 *
 *      CS_is_present is stored in the highest-order bit of byte 1.
 *
 *      if (CS_is_present == TRUE)
 *          bytes 10 through 17 hold the CS_value, encoded as follows.
 *          First add a multiple of 1/2, if necessary, so that the CS_value
 *          lies in the range [-1/4, 1/4)  Then mulitply by 2 and add 1/2
 *          so that it lies in the ragne [0, 1).  The CS_value is a
 *          double which on some machines (e.g. the Mac) has an 8-btye
 *          mantissa.  In binary, this is a number like 0.100101000..., with
 *          64 meaningful binary digits after the decimal point (the "binary
 *          point" ?).  The first 8 digits are stored in byte 10 of the
 *          TersestTriangulation string, the next 8 digits are stored in
 *          byte 11, and so on until the final 8 meaningful digits are stored
 *          in byte 17.  On some machines (e.g. on most UNIX workstations)
 *          doubles have only 6-byte mantissas, in which case we just
 *          zero-fill bytes 16 and 17 of the TersestTriangulation string
 *          (in practice this shouldn't occur, because the libraries of
 *          manifolds will be created on the Mac at full accuracy, and then
 *          only read on less accurate platforms).
 *
 *      if (CS_is_present == FALSE)
 *          bytes 10 through 17 are unused.
 */

#ifndef _tersest_triangulation_
#define _tersest_triangulation_

typedef unsigned char TersestTriangulation[18];

#endif