4. Converting Polymake Output
  
  
  4.1 The General Method
  
  When  polymake  is called, its output is read as a string and then processed
  as follows:
  
  (1)   the  lines  containing upper case letters are found. These are treated
        as  lines  containing  the  keywords.  Each  of  those lines marks the
        beginning of a block of data.
  
  (2)   The  string  is  then  cut  into a list of blocks (also strings). Each
        block  starts  with  a  line containing the keyword and continues with
        some lines of data.
  
  (3)   for  each  of the blocks, the appropriate function of ObjectConverters
        is  called.  Here  "appropriate"  just  means, that the keyword of the
        block coincides with the name of the function.
  
  (4)   The  output  of  the  conversion  function  is then added to the known
        properties of the PolymakeObject for which Polymake was called.
  
  
  4.1-1 Converter- Philosopy
  
  The converter functions should take meaningful polymake data into meaningful
  GAP  data.  This  sometimes  means that the (mathematical) representation is
  changed.  Here  is  an  example: polymake writes vectors as augmented affine
  vectors of the form 1 a1 a2 a3... which does not go very well with the usual
  GAP  conventions  of column vectors and multiplying matrices from the right.
  So  polymaking converts such a vector to [a1,a2,a3,...] and the user is left
  with the problem of augmentation and left or right multiplication.
  
  Another  area  where  the  GAP  object  isn't a literal translation from the
  polymake  world  is combinatorics. In Polymake, list elements are enumerated
  starting  from  0.  GAP  enumerates  lists  starting at 1. So the conversion
  process  adds 1 to the numbers corresponding to vertices in facet lists, for
  example.
  
  Call  for  help:  As  of version 0.7.0, most of the converters were assigned
  blindly  to keywords. So some of them might not be suitable. If you find one
  of  those,  please  tell  me  about it. Also, for a lot of keywords and data
  types, there is no converter. Please tell me if you want a new converter.
  
  The conversion process is done by the following methods:
  
  4.1-2 ConvertPolymakeOutputToGapNotation
  
  > ConvertPolymakeOutputToGapNotation( string ) _______________________method
  Returns:  Record  having polymake keywords as entry names and the respective
            converted polymake output as entries.
  
  Given  a  the output of the polymake program as a string string, this method
  first  calls  SplitPolymakeOutputStringIntoBlocks  (4.1-3).  For each of the
  returned  blocks, the name (=first line) of the block is read and the record
  ObjectConverters  (4.1-4)  is looked up for an entry with that name. If such
  an  entry exists, it (being a function!) is called and passed the block. The
  returned  value  is then given the name of the block and added to the record
  returned by ConvertPolymakeOutputToGapNotation.
  
  4.1-3 SplitPolymakeOutputStringIntoBlocks
  
  > SplitPolymakeOutputStringIntoBlocks( string ) ______________________method
  Returns:  List of strings -- "blocks"--
  
  The  string string is cut at the lines starting with an upper case character
  and  consisting  only  of  upper  case  letters,  numbers and underscore (_)
  characters.  The parts are returned as a list of strings. The initial string
  string remains unchanged.
  
  4.1-4 ObjectConverters
  
  > ObjectConverters___________________________________________global variable
  
  The  entries  of  this  record are labeled by polymake keywords. Each of the
  entries  is  a  function which converts a string returned by polymake to GAP
  format.  So  far,  only  a few converters are implemented. To see which, try
  RecNames(ObjectConverters);
  
  You can define new converters using the basic functions described in section
  4.2.
  
  
  4.2 Conversion Functions
  
  The  following  functions  are  used  for  the functions in ObjectConverters
  (4.1-4).
  
  4.2-1 ConvertPolymakeNumber
  
  > ConvertPolymakeNumber( string ) ____________________________________method
  
  The  string  string is converted to a rational number. Unlike Rat, it tests,
  if  the  number represented by string is a floating point number an converts
  it correctly. If this is the case, a waring is issued.
  
  4.2-2 ConvertPolymakeScalarToGAP
  
  > ConvertPolymakeScalarToGAP( list ) _________________________________method
  
  If  list  contains  a  single string, this string is converted into a number
  using ConvertPolymakeNumber (4.2-1).
  
  4.2-3 ConvertPolymakeMatrixOrListOfSetsToGAP
  
  > ConvertPolymakeMatrixOrListOfSetsToGAP( list ) _____________________method
  > ConvertPolymakeMatrixOrListOfSetsToGAPPlusOne( list ) ______________method
  
  Tries to decide if the list list of strings represents a matrix or a list of
  sets   by   testing   if   they   start  with  "{".  It  then  calls  either
  ConvertPolymakeMatrixToGAP    (4.2-4)    or   ConvertPolymakeListOfSetsToGAP
  (4.2-8).  The  "PlusOne" version calls ConvertPolymakeListOfSetsToGAPPlusOne
  (4.2-8) if list represents a list of sets.
  
  4.2-4 ConvertPolymakeMatrixToGAP
  
  > ConvertPolymakeMatrixToGAP( list ) _________________________________method
  > ConvertPolymakeMatrixToGAPKillOnes( list ) _________________________method
  
  The  list  list  of  strings  is  interpreted  as  a list of row vectors and
  converted into a matrix. The "KillOnes" version removes the leading ones.
  
  4.2-5 ConvertPolymakeVectorToGAP
  
  > ConvertPolymakeVectorToGAP( list ) _________________________________method
  > ConvertPolymakeVectorToGAPKillOne( list ) __________________________method
  > ConvertPolymakeIntVectorToGAPPlusOne( list ) _______________________method
  
  As    the    corresponding    "Matrix"    version.    Just    for   vectors.
  ConvertPolymakeIntVectorToGAPPlusOne   requires   the   vector   to  contain
  integers. It also adds 1 to every entry.
  
  4.2-6 ConvertPolymakeBoolToGAP
  
  > ConvertPolymakeBoolToGAP( list ) ___________________________________method
  
  If  list  contains  a single string, which is either 0,false,1, or true this
  function returns false or true, respectively.
  
  4.2-7 ConvertPolymakeSetToGAP
  
  > ConvertPolymakeSetToGAP( list ) ____________________________________method
  
  Let  list  be  a list containing a single string, which is a list of numbers
  separated  by  whitespaces  and  enclosed by { and } . The returned value is
  then a set of rational numbers (in the GAP sense).
  
  4.2-8 ConvertPolymakeListOfSetsToGAP
  
  > ConvertPolymakeListOfSetsToGAP( list ) _____________________________method
  > ConvertPolymakeListOfSetsToGAPPlusOne( list ) ______________________method
  
  Let  list  be a list containing several strings representing sets. Then each
  of  these strings is converted to a set of rational numbers and the returned
  value  is  the list of all those sets. The "PlusOne" version adds 1 to every
  entry.
  
  4.2-9 ConvertPolymakeGraphToGAP
  
  > ConvertPolymakeGraphToGAP( list ) __________________________________method
  
  Let list be a list of strings representing sets (that is, a list of integers
  enclosed  by  {  and }). Then a record is returned containing two sets named
  .vertices and .edges.
  
  4.2-10 ConvertPolymakeHasseDiagramToGAP
  
  > ConvertPolymakeHasseDiagramToGAP( list ) ___________________________method
  Returns:  Record with entries .hasse and .faceindices
  
  Takes  a  list  list  of strings (the HASSE_DIAGRAM returned by polymake and
  split with SplitPolymakeOutputStringIntoBlocks (4.1-3)) and returns a record
  containing  a  list  of  pairs  .hasse  and  a  list  of  lists  of integers
  .faceindices.  Every  pair  in  .hasse is of the form [[vertlist],[upfaces]]
  where  vertlist is a list of vertices (given as integers) and [upfaces] is a
  list  of  integers  encoding  the  faces  in  the next (higher) dimension as
  positions in the list .hasse. If polymake returns special faces representing
  the full object or the empty face, they are also included in .hasse.
  .faceindices  is a list of lists of integers corresponding to the indices of
  faces in each dimension in .hasse(possibly including the extra faces).
  Note  that  the  order  in which the faces are listed in .hasse is the order
  they  are  output  from  polymake.  In particular, the list might start with
  vertices for one object and with facets for another.
  
  ---------------------------  Example  ----------------------------
    
    gap> square:=CreatePolymakeObjectFromFile(Directory("~/tmp/"),"2cube.poly");
    <polymake object. No properties known>
    gap> # "VERTICES" is converted using ConvertPolymakeMatrixToGAPKillOnes
    gap> Polymake(square,"VERTICES");
    [ [ -1, -1 ], [ 1, -1 ], [ -1, 1 ], [ 1, 1 ] ]
    gap> Polymake(square,"HASSE_DIAGRAM");
    rec(
      hasse := [ [ [  ], [ 2, 3, 4, 5 ] ], [ [ 1 ], [ 6, 8 ] ], [ [ 2 ], [ 7, 8 ] ],
          [ [ 3 ], [ 6, 9 ] ], [ [ 4 ], [ 7, 9 ] ], [ [ 1, 3 ], [ 10 ] ],
          [ [ 2, 4 ], [ 10 ] ], [ [ 1, 2 ], [ 10 ] ], [ [ 3, 4 ], [ 10 ] ],
          [ [ 1, 2, 3, 4 ], [  ] ] ],
      faceindices := [ [ 1 ], [ 2, 3, 4, 5 ], [ 6, 7, 8, 9 ], [ 10 ] ] )
    gap> simp:=CreatePolymakeObjectFromFile(Directory("~/tmp/"),"tmp.top");
    <polymake object. No properties known>
    gap> Polymake(simp,"FACETS"); ## a very small simplicial complex
    [ [ 2, 4 ], [ 1, 2, 3 ] ]
    gap> Polymake(simp,"HASSE_DIAGRAM");
    rec( hasse := [ [ [  ], [  ] ], [ [ 1, 2, 3 ], [ 1 ] ], [ [ 2, 4 ], [ 1 ] ],
          [ [ 1, 2 ], [ 2 ] ], [ [ 1, 3 ], [ 2 ] ], [ [ 2, 3 ], [ 2 ] ],
          [ [ 2 ], [ 3, 4, 6 ] ], [ [ 4 ], [ 3 ] ], [ [ 1 ], [ 4, 5 ] ],
          [ [ 3 ], [ 5, 6 ] ], [ [  ], [ 7, 8, 9, 10 ] ] ],
      faceindices := [ [ 1 ], [ 2 ], [ 3, 4, 5, 6 ], [ 7, 8, 9, 10 ], [ 11 ] ] )
    gap> ## ... and this one starts with facets
    
  ------------------------------------------------------------------