Goto Chapter: Top 1 2 3 4 Bib Ind
 Top of Book   Previous Chapter   Next Chapter 

2. Polymake interaction
 2.1 Creating Polymake Objects
  2.1-1 CreateEmptyFile

  2.1-2 CreatePolymakeObject

  2.1-3 CreatePolymakeObjectFromFile
 2.2 Accessing Properties of Polymake Objects
  2.2-1 DirectoryOfPolymakeObject

  2.2-2 FilenameOfPolymakeObject

  2.2-3 FullFilenameOfPolymakeObject

  2.2-4 NamesKnownPropertiesOfPolymakeObject

  2.2-5 KnownPropertiesOfPolymakeObject

  2.2-6 PropertyOfPolymakeObject
 2.3 Example: Creating and Accessing Polymake Objects
 2.4 Writing to Polymake Objects
  2.4-1 AppendToPolymakeObject

  2.4-2 AppendPointlistToPolymakeObject

  2.4-3 AppendVertexlistToPolymakeObject

  2.4-4 AppendInequalitiesToPolymakeObject

  2.4-5 ConvertMatrixToPolymakeString

  2.4-6 ClearPolymakeObject

  2.4-7 WriteKnownPropertyToPolymakeObject

  2.4-8 UnbindKnownPropertyOfPolymakeObject
 2.5 Calling Polymake and converting its output
  2.5-1 Polymake
 2.6 An Example

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 )

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( dir )( method )
> CreatePolymakeObject( prefix, dir )( method )

If called without arguments, this method generates an empty file in the directory defined by POLYMAKE_DATA_DIR (3.2-2). It then returns a PolymakeObject. 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 that prefix.

2.1-3 CreatePolymakeObjectFromFile
> CreatePolymakeObjectFromFile( filename )( method )
> CreatePolymakeObjectFromFile( dir, filename )( method )

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 the directory of the file associated with poly.

2.2-2 FilenameOfPolymakeObject
> FilenameOfPolymakeObject( poly )( method )

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 the file associated with the PolymakeObject poly with its complete path.

2.2-4 NamesKnownPropertiesOfPolymakeObject
> NamesKnownPropertiesOfPolymakeObject( poly )( method )

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 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.


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");;  
   # 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 )

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 )

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 )

Does the same as AppendPointlistToPolymakeObject, but with "VERTICES" instead of "POINTS".

2.4-4 AppendInequalitiesToPolymakeObject
> AppendInequalitiesToPolymakeObject( poly, ineqlist )( method )

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 )

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 )

Deletes all known properties of the PolymakeObject poly and replaces its file with an empty one.

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( polyoption[, :[, 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-3). The first line of each block of polymake output is taken as a keyword and the according entry in ObjectConverters (4.1-3) is called to convert the block into GAP readable form. If no such conversion function exists, an error is issued. 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 something else than false, the polymake program is called even if poly already has a known property with name option.

2.6 An Example

Let's generate a three dimensional permutahedron.

    
    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
    
    
 Top of Book   Previous Chapter   Next Chapter 
Goto Chapter: Top 1 2 3 4 Bib Ind

generated by GAPDoc2HTML