2. Polymake interaction
  
  
  2.1 Creating Polymake Objects
  
  The  interaction  with  the  polymake  program  is  done  via  files.  So  a
  PolymakeObject  is mainly a pointer to a file and a list of known properties
  of  the  object.  These  properties need not be stored in the file. Whenever
  polymake  is  called,  the  returned  value is read from standard output and
  stored in the PolymakeObject corresponding to the file for which polymake is
  called.
  
  2.1-1 CreateEmptyFile
  
  > CreateEmptyFile( filename ) ________________________________________method
  Returns:  nothing
  
  Creates  an empty file with name filename. Note that filename has to include
  the full path and the directory for the file must exist.
  
  2.1-2 CreatePolymakeObject
  
  > CreatePolymakeObject(  ) ___________________________________________method
  > CreatePolymakeObject( appvertyp ) __________________________________method
  > CreatePolymakeObject( dir ) ________________________________________method
  > CreatePolymakeObject( dir, appvertyp ) _____________________________method
  > CreatePolymakeObject( prefix, dir ) ________________________________method
  > CreatePolymakeObject( prefix, dir, appvertyp ) _____________________method
  Returns:  PolymakeObject
  
  If  called  without  arguments,  this  method generates an empty file in the
  directory  defined by POLYMAKE_DATA_DIR (3.2-2). If a directory dir is given
  (this  directory  must exist), an empty file is generated in this directory.
  If  prefix  is  not  given,  the file is called polyN where N is the current
  runtime.  If  a  file  of  this  name  already  exists, a number is appended
  separated  by  a  dot  (example:  "poly1340" and "poly1340.1"). If prefix is
  given,  the  filename  starts  with this prefix. Optionally, the file can be
  generated  with  a  header  specifying  application, version and type of the
  object.  This  is  done  by  passing  the  triple  of  strings  appvertyp to
  CreatePolymakeObject.           A          valid          triple          is
  ["polytope","2.3","RationalPolytope"].     Validity     is     checked    by
  CheckAppVerTypList (2.1-3).
  
  2.1-3 CheckAppVerTypList
  
  > CheckAppVerTypList( appvertyp ) ____________________________________method
  Returns:  bool
  
  Checks if the triple arppvertyp of strings specifies an application and type
  of  polymake  version  2.3.  More specifically, the first entry has to be an
  application  from  ["polytope","surface","topaz"] and the third entry has to
  be  a  type  corresponding  to the application given in the first entry. The
  second entry is not checked.
  
  2.1-4 CreatePolymakeObjectFromFile
  
  > CreatePolymakeObjectFromFile( filename ) ___________________________method
  > CreatePolymakeObjectFromFile( dir, filename ) ______________________method
  Returns:  PolymakeObject
  
  This method generates a PolymakeObject corresponding to the file filename in
  the  directory dir. If dir is not given, the POLYMAKE_DATA_DIR is used.If no
  file  with name filename exists in dir (or POLYMAKE_DATA_DIR, respectively),
  an  empty  file is created. Note that the contents of the file do not matter
  for  the  generation  of the object. In particular, the object does not know
  any  of  the  properties  that might be encoded in the file. The only way to
  transfer information from files to PolymakeObjects is via Polymake (2.5-1).
  
  
  2.2 Accessing Properties of Polymake Objects
  
  A  PolymakeObject  contains information about the directory of its file, the
  name  of  its  file  and  about  properties  calculated  by calling Polymake
  (2.5-1).  The  properties  returned by the polymake program are stored under
  the  name  polymake  assigns to them (that is, the name of the data block in
  the  corresponding  file).  The  following methods can be used to access the
  information stored in a PolymakeObject. But be careful! All functions return
  the  actual object. No copies are made. So if you change one of the returned
  objects, you change the PolymakeObject itself.
  
  2.2-1 DirectoryOfPolymakeObject
  
  > DirectoryOfPolymakeObject( poly ) __________________________________method
  Returns:  Directory
  
  Returns the directory of the file associated with poly.
  
  2.2-2 FilenameOfPolymakeObject
  
  > FilenameOfPolymakeObject( poly ) ___________________________________method
  Returns:  String
  
  Returns  the  name of the file associated with poly. This does only mean the
  name  of  the  file,  not the full path. For the full path and file name see
  FullFilenameOfPolymakeObject (2.2-3)
  
  2.2-3 FullFilenameOfPolymakeObject
  
  > FullFilenameOfPolymakeObject( poly ) _______________________________method
  Returns:  String
  
  Returns  the  file associated with the PolymakeObject poly with its complete
  path.
  
  2.2-4 NamesKnownPropertiesOfPolymakeObject
  
  > NamesKnownPropertiesOfPolymakeObject( poly ) _______________________method
  Returns:  List of Strings
  
  Returns  a list of the names of all known properties. This does only include
  the  properties  returned  by Polymake (2.5-1), "dir" and "filename" are not
  included. If no properties are known, fail is returned.
  
  2.2-5 KnownPropertiesOfPolymakeObject
  
  > KnownPropertiesOfPolymakeObject( poly ) ____________________________method
  Returns:  Record
  
  Returns the record of all known properties. If no properties are known, fail
  is returned.
  
  2.2-6 PropertyOfPolymakeObject
  
  > PropertyOfPolymakeObject( poly, name ) _____________________________method
  
  Returns  the  value of the property name if it is known. If the value is not
  known, fail is returned. name must be a String.
  
  
  2.3 Example: Creating and Accessing Polymake Objects
  
  Suppose  the file /tmp/threecube.poly contains the three dimensional cube in
  polymake form (as generated by the command line cube /tmp/threecube.poly 3 1
  ). Now generate a PolymakeObject from this file and call Polymake (2.5-1) to
  make the vertices of the cube known to the object.
  
  ---------------------------  Example  ----------------------------
    
    ### suppose we have a polymake file /tmp/threecube.poly
    ### containing a cube in three dimensions
    gap> cube:=CreatePolymakeObjectFromFile(Directory("/tmp"),"threecube.poly");
    <polymake object. No properties known>
    gap> FilenameOfPolymakeObject(cube);
    "threecube.poly"
    gap> FullFilenameOfPolymakeObject(cube);
    "/tmp/threecube.poly"
       #nothing is known about the cube:
    gap> NamesKnownPropertiesOfPolymakeObject(cube);  
    fail
    gap> Polymake(cube,"VERTICES");
    [ [ -1, -1, -1 ], [ 1, -1, -1 ], [ -1, 1, -1 ], [ 1, 1, -1 ], [ -1, -1, 1 ], 
      [ 1, -1, 1 ], [ -1, 1, 1 ], [ 1, 1, 1 ] ]  
       # Now <cube> knows its vertices:
    gap> Print(cube);
    <polymake object threecube.poly. Properties known: [ "VERTICES" ]>
    gap> PropertyOfPolymakeObject(cube,"VERTICES");
    [ [ -1, -1, -1 ], [ 1, -1, -1 ], [ -1, 1, -1 ], [ 1, 1, -1 ], [ -1, -1, 1 ],
      [ 1, -1, 1 ], [ -1, 1, 1 ], [ 1, 1, 1 ] ]
    gap> KnownPropertiesOfPolymakeObject(cube);
    rec(
      VERTICES := [ [ -1, -1, -1 ], [ 1, -1, -1 ], [ -1, 1, -1 ], [ 1, 1, -1 ],
          [ -1, -1, 1 ], [ 1, -1, 1 ], [ -1, 1, 1 ], [ 1, 1, 1 ] ] )
    
  ------------------------------------------------------------------
  
  
  2.4 Writing to Polymake Objects
  
  To  transfer  data  from GAP to polymake, the following methods can be used.
  But bear in mind that none of these functions test if the resulting polymake
  file is still consistent.
  
  2.4-1 AppendToPolymakeObject
  
  > AppendToPolymakeObject( poly, string ) _____________________________method
  Returns:  nothing
  
  This  appends the string string to the file associated to the PolymakeObject
  poly. It is not tested if the string is syntactically correct as a part of a
  polymake  file.  It  is also not tested if the string is compatible with the
  data already contained in the file.
  
  INEQUALITIES, POINTS and VERTICES can be appended to a polymake object using
  the following functions:
  
  2.4-2 AppendPointlistToPolymakeObject
  
  > AppendPointlistToPolymakeObject( poly, pointlist ) _________________method
  Returns:  nothing
  
  Takes  a  list  pointlist  of  vectors  and  converts it into a string which
  represents  a  polymake block labeled "POINTS". This string is then added to
  the  file  associated  with  poly. The "POINTS" block of the file associated
  with  poly  then  contains points with leading ones, as polymake uses affine
  notation.
  
  2.4-3 AppendVertexlistToPolymakeObject
  
  > AppendVertexlistToPolymakeObject( poly, pointlist ) ________________method
  Returns:  nothing
  
  Does  the  same  as  AppendPointlistToPolymakeObject,  but  with  "VERTICES"
  instead of "POINTS".
  
  2.4-4 AppendInequalitiesToPolymakeObject
  
  > AppendInequalitiesToPolymakeObject( poly, ineqlist ) _______________method
  Returns:  nothing
  
  Just appends the inequalities given in ineqlist to the polymake object  poly
  (with  caption  "INEQUALITIES").  Note  that  this  does  not  check  if  an
  "INEQUALITIES" section does already exist in the file associated with poly.
  
  2.4-5 ConvertMatrixToPolymakeString
  
  > ConvertMatrixToPolymakeString( name, matrix ) ______________________method
  Returns:  String
  
  This function takes a matrix matrix and converts it to a string. This string
  can  then  be appended to a polymake file via AppendToPolymakeObject (2.4-1)
  to  form a block of data labeled name. This may be used to write blocks like
  INEQUALITIES or FACETS.
  
  2.4-6 ClearPolymakeObject
  
  > ClearPolymakeObject( poly ) ________________________________________method
  > ClearPolymakeObject( poly, appvertyp ) _____________________________method
  Returns:  nothing
  
  Deletes  all  known  properties  of the PolymakeObject poly and replaces its
  file with an empty one.
  If  the triple of strings appvertyp specifying application, version and type
  (see  CheckAppVerTypList (2.1-3)) is given, the file is replaced with a file
  that  contains only a header specifying application, version and type of the
  polymake object.
  
  There  are  also methods to manipulate the known values without touching the
  file of the PolymakeObject:
  
  2.4-7 WriteKnownPropertyToPolymakeObject
  
  > WriteKnownPropertyToPolymakeObject( poly, name, data ) _____________method
  
  Takes  the  object data and writes it to the known properties section of the
  PolymakeObject poly. The string name is used as the name of the property. If
  a property with that name already exists, it is overwritten. Again, there is
  no check if data is consistent, correct or meaningful.
  
  2.4-8 UnbindKnownPropertyOfPolymakeObject
  
  > UnbindKnownPropertyOfPolymakeObject( poly, name ) __________________method
  
  If  the  PolymakeObject poly has a property with name name, that property is
  unbound. If there is no such property, fail is returned.
  
  
  2.5 Calling Polymake and converting its output
  
  2.5-1 Polymake
  
  > Polymake( poly, option[, :[, PolymakeNolookup]] ) __________________method
  
  This  method  calls the polymake program (see POLYMAKE_COMMAND (3.2-1)) with
  the option option. You may use several keywords such as "DIM VERTICES" as an
  option.  The returned value is cut into blocks starting with keywords (which
  are  taken  from  output  and  not  looked up in option). Each block is then
  interpreted  and translated into GAP readable form. This translation is done
  using  the  functions  given  in ObjectConverters (4.1-4). The first line of
  each  block of polymake output is taken as a keyword and the according entry
  in ObjectConverters (4.1-4) is called to convert the block into GAP readable
  form. If no conversion function is known, an info string is printed and fail
  is  returned. If only one keyword has been given as option, Polymake returns
  the  result  of  the conversion operation. If more than one keyword has been
  given  or the output consists of more than one block, Polymake returns fail.
  In  any  case,  the  calculated  values  for  each block are stored as known
  properties  of  the  PolymakeObject  poly  as  long as they are not fail. If
  Polymake  is  called  with  an  option that corresponds to a name of a known
  property  of poly, the known property is returned. In this case, there is no
  call of the external program. (see below for suppression of this feature).
  
  Note  that  the  command Polymake returns fail if nothing is returned by the
  program  polymake  or  more than one block of data is returned. For example,
  the  returned  value  of  Polymake(poly,"VISUAL")  is always fail. Likewise,
  Polymake(poly,"POINTS  VERTICES")  will  return  fail (but may add new known
  properties  to  poly).  For  a  description of the conversion functions, see
  chapter 4..
  
  If  the  option  PolymakeNolookup  is  set  to anything else than false, the
  polymake  program  is  called even if poly already has a known property with
  name option.
  
  Note  that  whenever  Polymake returns fail, a description of the problem is
  stored  in POLYMAKE_LAST_FAIL_REASON (3.1-2). If you call Polymake with more
  than  one  keyword,  POLYMAKE_LAST_FAIL_REASON  (3.1-2)  is  changed  before
  polymake is called. So any further reason to return fail will overwrite it.
  
  
  2.6 An Example
  
  Let's generate a three dimensional permutahedron.
  
  ---------------------------  Example  ----------------------------
        
        gap> S:=SymmetricGroup(3);
        Sym( [ 1 .. 3 ] )
        gap> v:=[1,2,3];
        [ 1, 2, 3 ]
        gap> points:=Orbit(S,v,Permuted);;
        gap> permutahedron:=CreatePolymakeObject();
        <polymake object. No properties known>
        gap> AppendPointlistToPolymakeObject(permutahedron,points);
        gap> Polymake(permutahedron,"VOLUME");
        3
        gap> Polymake(permutahedron,"N_VERTICES");
        6
              #Now <permutahedron> knows its number of vertices, but not the vertices:
        gap> PropertyOfPolymakeObject(permutahedron,"VERTICES");
        fail
        gap> NamesKnownPropertiesOfPolymakeObject(permutahedron);
        [ "VOLUME", "N_VERTICES" ]
            #Let's look at the object!
        gap> Polymake(permutahedron,"VISUAL");
        #I  There was no or wrong polymake output
        fail
        gap> Polymake(permutahedron,"DIM");
        2
        
        
  ------------------------------------------------------------------
  
  
  2.7 Calling Clients
  
  2.7-1 PolymakeClient
  
  > PolymakeClient( clientname[, outobject][, inobjects][, options] ) __method
  > PolymakeClientNC( clientname, outobject, inobjects, options ) ______method
  Returns:  PolymakeObject
  
  Any client program that has a command line syntax like
  clientname outfile infile1 infile2... -option1 -option2...
  can be called using PolymakeClient. Any output of the client to the terminal
  is ignored (but a warning is printed if this happens).
  clientname  must  be  given  as  a string without path. Polymaking looks for
  clients in the directories listed in POLYMAKE_CLIENT_PATHS (3.2-3).
  The  client  program  is  called  and  passed  the file corresponding to the
  PolymakeObject  outobject,  the  files  of  the  PolymakeObjects in the list
  inobjects  and finally the string options. If no PolymakeObject outobject is
  given,  a  new  object is created. PolymakeClient returns the PolymakeObject
  outobject if it was given, otherwise a new PolymakeObject is returned.
  PolymakeClientNC does not perform any checks on the input objects.
  Important:  PolymakeClient  does not change the known properties of outfile.
  This can lead to inconsistencies if you "recycle" files. So if you know that
  a  client will overwrite the output file, consider using ClearPolymakeObject
  (2.4-6) on the output PolymakeObject before calling the client.
  
  ---------------------------  Example  ----------------------------
    
    gap> rand:=PolymakeClient("rand_sphere","3 15");
    <polymake object. No properties known>
    gap> Polymake(rand,"N_VERTICES");
    15
    gap> cube:=PolymakeClient("cube","3");
    gap> Polymake(cube,"N_VERTICES");
    8
    gap> PolymakeClient("pyramid",rand,[cube]);
    <polymake object>
    gap> IsIdenticalObj(last,rand);
    true
    gap> ## the file of <rand> has changed, but polymaking doesn't know about it:
    gap> Polymake(rand,"N_VERTICES");
    15
    gap> Polymake(rand,"N_VERTICES":PolymakeNolookup);
    9
    
  ------------------------------------------------------------------