  
  [1X2. Polymake interaction[0X
  
  
  [1X2.1 Creating Polymake Objects[0X
  
  The  interaction  with  the  polymake  program  is  done  via  files.  So  a
  [9XPolymakeObject[0X  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 [9XPolymakeObject[0X corresponding to the file for which polymake is
  called.
  
  [1X2.1-1 CreateEmptyFile[0X
  
  [2X> CreateEmptyFile( [0X[3Xfilename[0X[2X ) ________________________________________[0Xmethod
  [6XReturns:[0X  nothing
  
  Creates  an empty file with name [3Xfilename[0X. Note that [3Xfilename[0X has to include
  the full path and the directory for the file must exist.
  
  [1X2.1-2 CreatePolymakeObject[0X
  
  [2X> CreatePolymakeObject( [0X[3X[0X[2X ) ___________________________________________[0Xmethod
  [2X> CreatePolymakeObject( [0X[3Xappvertyp[0X[2X ) __________________________________[0Xmethod
  [2X> CreatePolymakeObject( [0X[3Xdir[0X[2X ) ________________________________________[0Xmethod
  [2X> CreatePolymakeObject( [0X[3Xdir, appvertyp[0X[2X ) _____________________________[0Xmethod
  [2X> CreatePolymakeObject( [0X[3Xprefix, dir[0X[2X ) ________________________________[0Xmethod
  [2X> CreatePolymakeObject( [0X[3Xprefix, dir, appvertyp[0X[2X ) _____________________[0Xmethod
  [6XReturns:[0X  [9XPolymakeObject[0X
  
  If  called  without  arguments,  this  method generates an empty file in the
  directory  defined by [2XPOLYMAKE_DATA_DIR[0X ([14X3.2-2[0X). If a directory [3Xdir[0X is given
  (this  directory  must exist), an empty file is generated in this directory.
  If  [3Xprefix[0X  is  not  given,  the file is called [11XpolyN[0X where [9XN[0X 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 [3Xprefix[0X 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  [3Xappvertyp[0X to
  [2XCreatePolymakeObject[0X.           A          valid          triple          is
  [10X["polytope","2.3","RationalPolytope"][0X.     Validity     is     checked    by
  [2XCheckAppVerTypList[0X ([14X2.1-3[0X).
  
  [1X2.1-3 CheckAppVerTypList[0X
  
  [2X> CheckAppVerTypList( [0X[3Xappvertyp[0X[2X ) ____________________________________[0Xmethod
  [6XReturns:[0X  [9Xbool[0X
  
  Checks if the triple [3Xarppvertyp[0X of strings specifies an application and type
  of  polymake  version  2.3.  More specifically, the first entry has to be an
  application  from  [10X["polytope","surface","topaz"][0X and the third entry has to
  be  a  type  corresponding  to the application given in the first entry. The
  second entry is not checked.
  
  [1X2.1-4 CreatePolymakeObjectFromFile[0X
  
  [2X> CreatePolymakeObjectFromFile( [0X[3Xfilename[0X[2X ) ___________________________[0Xmethod
  [2X> CreatePolymakeObjectFromFile( [0X[3Xdir, filename[0X[2X ) ______________________[0Xmethod
  [6XReturns:[0X  [9XPolymakeObject[0X
  
  This method generates a [9XPolymakeObject[0X corresponding to the file [3Xfilename[0X in
  the  directory [3Xdir[0X. If [3Xdir[0X is not given, the [9XPOLYMAKE_DATA_DIR[0X is used.If no
  file  with name [3Xfilename[0X exists in [3Xdir[0X (or [9XPOLYMAKE_DATA_DIR[0X, 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 [9XPolymakeObject[0Xs is via [2XPolymake[0X ([14X2.5-1[0X).
  
  
  [1X2.2 Accessing Properties of Polymake Objects[0X
  
  A  [9XPolymakeObject[0X  contains information about the directory of its file, the
  name  of  its  file  and  about  properties  calculated  by calling [2XPolymake[0X
  ([14X2.5-1[0X).  The  properties  returned by the [9Xpolymake[0X program are stored under
  the  name  [9Xpolymake[0X  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 [9XPolymakeObject[0X. 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 [9XPolymakeObject[0X itself.
  
  [1X2.2-1 DirectoryOfPolymakeObject[0X
  
  [2X> DirectoryOfPolymakeObject( [0X[3Xpoly[0X[2X ) __________________________________[0Xmethod
  [6XReturns:[0X  Directory
  
  Returns the directory of the file associated with [3Xpoly[0X.
  
  [1X2.2-2 FilenameOfPolymakeObject[0X
  
  [2X> FilenameOfPolymakeObject( [0X[3Xpoly[0X[2X ) ___________________________________[0Xmethod
  [6XReturns:[0X  String
  
  Returns  the  name of the file associated with [3Xpoly[0X. This does only mean the
  name  of  the  [13Xfile[0X,  not the full path. For the full path and file name see
  [2XFullFilenameOfPolymakeObject[0X ([14X2.2-3[0X)
  
  [1X2.2-3 FullFilenameOfPolymakeObject[0X
  
  [2X> FullFilenameOfPolymakeObject( [0X[3Xpoly[0X[2X ) _______________________________[0Xmethod
  [6XReturns:[0X  String
  
  Returns  the  file associated with the [9XPolymakeObject[0X [3Xpoly[0X with its complete
  path.
  
  [1X2.2-4 NamesKnownPropertiesOfPolymakeObject[0X
  
  [2X> NamesKnownPropertiesOfPolymakeObject( [0X[3Xpoly[0X[2X ) _______________________[0Xmethod
  [6XReturns:[0X  List of Strings
  
  Returns  a list of the names of all known properties. This does only include
  the  properties  returned  by [2XPolymake[0X ([14X2.5-1[0X), [10X"dir"[0X and [10X"filename"[0X are not
  included. If no properties are known, [9Xfail[0X is returned.
  
  [1X2.2-5 KnownPropertiesOfPolymakeObject[0X
  
  [2X> KnownPropertiesOfPolymakeObject( [0X[3Xpoly[0X[2X ) ____________________________[0Xmethod
  [6XReturns:[0X  Record
  
  Returns the record of all known properties. If no properties are known, [9Xfail[0X
  is returned.
  
  [1X2.2-6 PropertyOfPolymakeObject[0X
  
  [2X> PropertyOfPolymakeObject( [0X[3Xpoly, name[0X[2X ) _____________________________[0Xmethod
  
  Returns  the  value of the property [3Xname[0X if it is known. If the value is not
  known, [9Xfail[0X is returned. [3Xname[0X must be a [9XString[0X.
  
  
  [1X2.3 Example: Creating and Accessing Polymake Objects[0X
  
  Suppose  the file [11X/tmp/threecube.poly[0X contains the three dimensional cube in
  polymake form (as generated by the command line [10Xcube /tmp/threecube.poly 3 1[0X
  ). Now generate a [9XPolymakeObject[0X from this file and call [2XPolymake[0X ([14X2.5-1[0X) to
  make the vertices of the cube known to the object.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4X### suppose we have a polymake file /tmp/threecube.poly[0X
    [4X### containing a cube in three dimensions[0X
    [4Xgap> cube:=CreatePolymakeObjectFromFile(Directory("/tmp"),"threecube.poly");[0X
    [4X<polymake object. No properties known>[0X
    [4Xgap> FilenameOfPolymakeObject(cube);[0X
    [4X"threecube.poly"[0X
    [4Xgap> FullFilenameOfPolymakeObject(cube);[0X
    [4X"/tmp/threecube.poly"[0X
    [4X   #nothing is known about the cube:[0X
    [4Xgap> NamesKnownPropertiesOfPolymakeObject(cube);  [0X
    [4Xfail[0X
    [4Xgap> Polymake(cube,"VERTICES");[0X
    [4X[ [ -1, -1, -1 ], [ 1, -1, -1 ], [ -1, 1, -1 ], [ 1, 1, -1 ], [ -1, -1, 1 ], [0X
    [4X  [ 1, -1, 1 ], [ -1, 1, 1 ], [ 1, 1, 1 ] ]  [0X
    [4X   # Now <cube> knows its vertices:[0X
    [4Xgap> Print(cube);[0X
    [4X<polymake object threecube.poly. Properties known: [ "VERTICES" ]>[0X
    [4Xgap> PropertyOfPolymakeObject(cube,"VERTICES");[0X
    [4X[ [ -1, -1, -1 ], [ 1, -1, -1 ], [ -1, 1, -1 ], [ 1, 1, -1 ], [ -1, -1, 1 ],[0X
    [4X  [ 1, -1, 1 ], [ -1, 1, 1 ], [ 1, 1, 1 ] ][0X
    [4Xgap> KnownPropertiesOfPolymakeObject(cube);[0X
    [4Xrec([0X
    [4X  VERTICES := [ [ -1, -1, -1 ], [ 1, -1, -1 ], [ -1, 1, -1 ], [ 1, 1, -1 ],[0X
    [4X      [ -1, -1, 1 ], [ 1, -1, 1 ], [ -1, 1, 1 ], [ 1, 1, 1 ] ] )[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X2.4 Writing to Polymake Objects[0X
  
  To  transfer  data  from [5XGAP[0X 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.
  
  [1X2.4-1 AppendToPolymakeObject[0X
  
  [2X> AppendToPolymakeObject( [0X[3Xpoly, string[0X[2X ) _____________________________[0Xmethod
  [6XReturns:[0X  nothing
  
  This  appends the string [3Xstring[0X to the file associated to the [9XPolymakeObject[0X
  [3Xpoly[0X. 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:
  
  [1X2.4-2 AppendPointlistToPolymakeObject[0X
  
  [2X> AppendPointlistToPolymakeObject( [0X[3Xpoly, pointlist[0X[2X ) _________________[0Xmethod
  [6XReturns:[0X  nothing
  
  Takes  a  list  [3Xpointlist[0X  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  [3Xpoly[0X. The "POINTS" block of the file associated
  with  [3Xpoly[0X  then  contains points with leading ones, as polymake uses affine
  notation.
  
  [1X2.4-3 AppendVertexlistToPolymakeObject[0X
  
  [2X> AppendVertexlistToPolymakeObject( [0X[3Xpoly, pointlist[0X[2X ) ________________[0Xmethod
  [6XReturns:[0X  nothing
  
  Does  the  same  as  [10XAppendPointlistToPolymakeObject[0X,  but  with  "VERTICES"
  instead of "POINTS".
  
  [1X2.4-4 AppendInequalitiesToPolymakeObject[0X
  
  [2X> AppendInequalitiesToPolymakeObject( [0X[3Xpoly, ineqlist[0X[2X ) _______________[0Xmethod
  [6XReturns:[0X  nothing
  
  Just appends the inequalities given in [3Xineqlist[0X to the polymake object [3X poly[0X
  (with  caption  "INEQUALITIES").  Note  that  this  does  not  check  if  an
  "INEQUALITIES" section does already exist in the file associated with [3Xpoly[0X.
  
  [1X2.4-5 ConvertMatrixToPolymakeString[0X
  
  [2X> ConvertMatrixToPolymakeString( [0X[3Xname, matrix[0X[2X ) ______________________[0Xmethod
  [6XReturns:[0X  String
  
  This function takes a matrix [3Xmatrix[0X and converts it to a string. This string
  can  then  be appended to a polymake file via [2XAppendToPolymakeObject[0X ([14X2.4-1[0X)
  to  form a block of data labeled [3Xname[0X. This may be used to write blocks like
  INEQUALITIES or FACETS.
  
  [1X2.4-6 ClearPolymakeObject[0X
  
  [2X> ClearPolymakeObject( [0X[3Xpoly[0X[2X ) ________________________________________[0Xmethod
  [2X> ClearPolymakeObject( [0X[3Xpoly, appvertyp[0X[2X ) _____________________________[0Xmethod
  [6XReturns:[0X  nothing
  
  Deletes  all  known  properties  of the [9XPolymakeObject[0X [3Xpoly[0X and replaces its
  file with an empty one.
  If  the triple of strings [3Xappvertyp[0X specifying application, version and type
  (see  [2XCheckAppVerTypList[0X ([14X2.1-3[0X)) 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 [9XPolymakeObject[0X:
  
  [1X2.4-7 WriteKnownPropertyToPolymakeObject[0X
  
  [2X> WriteKnownPropertyToPolymakeObject( [0X[3Xpoly, name, data[0X[2X ) _____________[0Xmethod
  
  Takes  the  object [3Xdata[0X and writes it to the known properties section of the
  [9XPolymakeObject[0X [3Xpoly[0X. The string [3Xname[0X 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 [3Xdata[0X is consistent, correct or meaningful.
  
  [1X2.4-8 UnbindKnownPropertyOfPolymakeObject[0X
  
  [2X> UnbindKnownPropertyOfPolymakeObject( [0X[3Xpoly, name[0X[2X ) __________________[0Xmethod
  
  If  the  [9XPolymakeObject[0X [3Xpoly[0X has a property with name [3Xname[0X, that property is
  unbound. If there is no such property, [9Xfail[0X is returned.
  
  
  [1X2.5 Calling Polymake and converting its output[0X
  
  [1X2.5-1 Polymake[0X
  
  [2X> Polymake( [0X[3Xpoly, option[, :[, PolymakeNolookup]][0X[2X ) __________________[0Xmethod
  
  This  method  calls the polymake program (see [2XPOLYMAKE_COMMAND[0X ([14X3.2-1[0X)) with
  the option [3Xoption[0X. You may use several keywords such as [10X"DIM VERTICES"[0X as an
  option.  The returned value is cut into blocks starting with keywords (which
  are  taken  from  output  and  not  looked up in [3Xoption[0X). Each block is then
  interpreted  and translated into [5XGAP[0X readable form. This translation is done
  using  the  functions  given  in [2XObjectConverters[0X ([14X4.1-4[0X). The first line of
  each  block of polymake output is taken as a keyword and the according entry
  in [2XObjectConverters[0X ([14X4.1-4[0X) is called to convert the block into [5XGAP[0X readable
  form. If no conversion function is known, an info string is printed and [9Xfail[0X
  is  returned. If only one keyword has been given as [3Xoption[0X, [10XPolymake[0X returns
  the  result  of  the conversion operation. If more than one keyword has been
  given  or the output consists of more than one block, [10XPolymake[0X returns [9Xfail[0X.
  In  any  case,  the  calculated  values  for  each block are stored as known
  properties  of  the  [9XPolymakeObject[0X  [3Xpoly[0X  as  long as they are not [9Xfail[0X. If
  [9XPolymake[0X  is  called  with  an  option that corresponds to a name of a known
  property  of [3Xpoly[0X, 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 [9XPolymake[0X returns [9Xfail[0X if nothing is returned by the
  program  polymake  or  more than one block of data is returned. For example,
  the  returned  value  of  [10XPolymake(poly,"VISUAL")[0X  is always [9Xfail[0X. Likewise,
  [10XPolymake(poly,"POINTS  VERTICES")[0X  will  return  [9Xfail[0X (but may add new known
  properties  to  [3Xpoly[0X).  For  a  description of the conversion functions, see
  chapter [14X4.[0X.
  
  If  the  option  [3XPolymakeNolookup[0X  is  set  to anything else than false, the
  polymake  program  is  called even if [3Xpoly[0X already has a known property with
  name [3Xoption[0X.
  
  Note  that  whenever  [2XPolymake[0X returns [9Xfail[0X, a description of the problem is
  stored  in [2XPOLYMAKE_LAST_FAIL_REASON[0X ([14X3.1-2[0X). If you call [2XPolymake[0X with more
  than  one  keyword,  [2XPOLYMAKE_LAST_FAIL_REASON[0X  ([14X3.1-2[0X)  is  changed  before
  polymake is called. So any further reason to return [9Xfail[0X will overwrite it.
  
  
  [1X2.6 An Example[0X
  
  Let's generate a three dimensional permutahedron.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X    [0X
    [4X    gap> S:=SymmetricGroup(3);[0X
    [4X    Sym( [ 1 .. 3 ] )[0X
    [4X    gap> v:=[1,2,3];[0X
    [4X    [ 1, 2, 3 ][0X
    [4X    gap> points:=Orbit(S,v,Permuted);;[0X
    [4X    gap> permutahedron:=CreatePolymakeObject();[0X
    [4X    <polymake object. No properties known>[0X
    [4X    gap> AppendPointlistToPolymakeObject(permutahedron,points);[0X
    [4X    gap> Polymake(permutahedron,"VOLUME");[0X
    [4X    3[0X
    [4X    gap> Polymake(permutahedron,"N_VERTICES");[0X
    [4X    6[0X
    [4X          #Now <permutahedron> knows its number of vertices, but not the vertices:[0X
    [4X    gap> PropertyOfPolymakeObject(permutahedron,"VERTICES");[0X
    [4X    fail[0X
    [4X    gap> NamesKnownPropertiesOfPolymakeObject(permutahedron);[0X
    [4X    [ "VOLUME", "N_VERTICES" ][0X
    [4X        #Let's look at the object![0X
    [4X    gap> Polymake(permutahedron,"VISUAL");[0X
    [4X    #I  There was no or wrong polymake output[0X
    [4X    fail[0X
    [4X    gap> Polymake(permutahedron,"DIM");[0X
    [4X    2[0X
    [4X    [0X
    [4X    [0X
  [4X------------------------------------------------------------------[0X
  
  
  [1X2.7 Calling Clients[0X
  
  [1X2.7-1 PolymakeClient[0X
  
  [2X> PolymakeClient( [0X[3Xclientname[, outobject][, inobjects][, options][0X[2X ) __[0Xmethod
  [2X> PolymakeClientNC( [0X[3Xclientname, outobject, inobjects, options[0X[2X ) ______[0Xmethod
  [6XReturns:[0X  PolymakeObject
  
  Any client program that has a command line syntax like
  [10Xclientname outfile infile1 infile2... -option1 -option2...[0X
  can be called using [9XPolymakeClient[0X. Any output of the client to the terminal
  is ignored (but a warning is printed if this happens).
  [3Xclientname[0X  must  be  given  as  a string without path. Polymaking looks for
  clients in the directories listed in [2XPOLYMAKE_CLIENT_PATHS[0X ([14X3.2-3[0X).
  The  client  program  is  called  and  passed  the file corresponding to the
  PolymakeObject  [3Xoutobject[0X,  the  files  of  the  PolymakeObjects in the list
  [3Xinobjects[0X  and finally the string [3Xoptions[0X. If no PolymakeObject [3Xoutobject[0X is
  given,  a  new  object is created. [9XPolymakeClient[0X returns the PolymakeObject
  [3Xoutobject[0X if it was given, otherwise a new PolymakeObject is returned.
  [9XPolymakeClientNC[0X does not perform any checks on the input objects.
  [13XImportant:[0X  [9XPolymakeClient[0X  does not change the known properties of [3Xoutfile[0X.
  This can lead to inconsistencies if you "recycle" files. So if you know that
  a  client will overwrite the output file, consider using [2XClearPolymakeObject[0X
  ([14X2.4-6[0X) on the output PolymakeObject before calling the client.
  
  [4X---------------------------  Example  ----------------------------[0X
    [4X[0X
    [4Xgap> rand:=PolymakeClient("rand_sphere","3 15");[0X
    [4X<polymake object. No properties known>[0X
    [4Xgap> Polymake(rand,"N_VERTICES");[0X
    [4X15[0X
    [4Xgap> cube:=PolymakeClient("cube","3");[0X
    [4Xgap> Polymake(cube,"N_VERTICES");[0X
    [4X8[0X
    [4Xgap> PolymakeClient("pyramid",rand,[cube]);[0X
    [4X<polymake object>[0X
    [4Xgap> IsIdenticalObj(last,rand);[0X
    [4Xtrue[0X
    [4Xgap> ## the file of <rand> has changed, but polymaking doesn't know about it:[0X
    [4Xgap> Polymake(rand,"N_VERTICES");[0X
    [4X15[0X
    [4Xgap> Polymake(rand,"N_VERTICES":PolymakeNolookup);[0X
    [4X9[0X
    [4X[0X
  [4X------------------------------------------------------------------[0X
  
