<Chapter Label="chap:GlobalVars"><Heading>Global Variables</Heading>

 <Section Label="chap:InfoClass"><Heading>Getting information about polymake
output</Heading> 
   
    <ManSection>
     <InfoClass Name="InfoPolymaking" />
    <Description>
     If set to at least <M>2</M>, the output of polymake is shown.
     At level <M>1</M>, warnings are shown. This is the default.
     And at level <M>0</M>, the polymake package remains silent.
    </Description>
   </ManSection>

    <ManSection>
     <Var Name="POLYMAKE_LAST_FAIL_REASON"/>
    <Description>
     Contains a string that explains the last occurence of <K>fail</K> as a
     return value of <Ref Meth="Polymake"/>.
    </Description>
    </ManSection>
   </Section>


 <Section Label="variables">
  <Heading>Variables for system interaction</Heading>

  The variables for interaction with the system are contained in the
  file <F>environment.gi</F>. Each of these variables has a function
  to set it, see <Ref Sect="chap:varsetters"/>.  If
  <K>POLYMAKE&uscore;COMMAND</K> or <K>POLYMAKE&uscore;DATA&uscore;DIR</K> are set at
  startup, they are not overwritten. So if you don't want (or don't
  have the rights) to modify <F>environment.gi</F>, you can set the
  variables in your <F>.gaprc</F> file.
    
   <ManSection>
    <Var Name="POLYMAKE_COMMAND"/>
    <Description>
     This variable should contain the name of the polymake program in
     the form as returned by <C>Filename</C> So a probable value is
     <C>Filename(Directory("/usr/local/bin"),"polymake")</C>.
     </Description> 
   </ManSection>


   <ManSection>
    <Var Name="POLYMAKE_DATA_DIR"/>
     <Description>
     In this directory the files for polymake will be created. By
     default, this generates a temporary directory using
     <K>DirectoryTemporary</K>
     </Description>
   </ManSection>

   <ManSection>
    <Var Name="POLYMAKE_CLIENT_PATHS"/>
     <Description>
      A list of directories where polymake's the stand-alone clients live. By
      default, <K>DirectoriesSystemPrograms</K> is used.
     </Description>
   </ManSection>


</Section>

</Chapter>



 <Chapter Label="Converting"><Heading>Converting Polymake Output</Heading>

<Section><Heading>The General Method</Heading>

When polymake is called, its output is read as a string and then
processed as follows: 

<Enum>
 <Item>  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. </Item>
 <Item>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.
 </Item>
<Item>for each of the blocks, the appropriate function of
 <C>ObjectConverters</C> is called. Here "appropriate" just means,
 that the keyword of the block coincides with the name of the
 function.</Item>
<Item>The output of the conversion function is then added to
 the known properties of the <C>PolymakeObject</C> for which
 <C>Polymake</C> was called.</Item>
</Enum>

<Subsection><Heading>Converter- Philosopy</Heading>

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  <Code>1 a1 a2 a3...</Code> which does not go very well
with the usual &GAP; conventions of column vectors and multiplying matrices
from the right. So <Package>polymaking</Package> converts such a vector to
<Code>[a1,a2,a3,...]</Code> and the user is left with the problem of
augmentation and left or right multiplication.
<P/>
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. 
<P/>
<Emph>Call for help:</Emph> 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.
</Subsection>

The conversion process is done by the following methods:


  <ManSection>
  <Meth Name="ConvertPolymakeOutputToGapNotation" Arg="string"/>
   <Returns>Record having polymake keywords as entry names and
   the respective converted polymake output as entries.
   </Returns>
   <Description>

    Given a the output of the polymake program as a string
    <A>string</A>, this method first calls <Ref
    Meth="SplitPolymakeOutputStringIntoBlocks"/>.  For each of the returned
    blocks, the name (=first line) of the block is read and the record
    <Ref Var="ObjectConverters"/> 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
    <C>ConvertPolymakeOutputToGapNotation</C>.

   </Description>
  </ManSection>


<ManSection>
 <Meth Name="SplitPolymakeOutputStringIntoBlocks" Arg="string"/>
  <Returns>List of strings -- "blocks"--</Returns>
  <Description>
    The string <A>string</A> is cut at the lines starting with an upper case
    character and  consisting only of upper case
    letters, numbers and underscore (&uscore;) characters. 
    The parts are returned as a list of
    strings. The initial string <A>string</A> remains unchanged.
  </Description>
</ManSection>


 <ManSection>
  <Var Name="ObjectConverters"/> <Description> 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
     <C>RecNames(ObjectConverters);</C>
     <Par></Par>
      You can define new converters using the basic functions
      described in section <Ref Sect="conversionFunctions"/>.
     </Description>
    </ManSection>


</Section>
 

<Section Label="conversionFunctions"><Heading>Conversion Functions</Heading>

  The following functions are used for the functions in
 <Ref Var="ObjectConverters"></Ref>.

  <ManSection>
  <Meth Name="ConvertPolymakeNumber" Arg="string"/>
   <Description>
    The string <A>string</A> is converted to a rational number. Unlike
    <C>Rat</C>, it tests, if the number represented by <A>string</A>
    is a floating point number an converts it correctly. If this is
    the case, a waring is issued.
   </Description>
  </ManSection>

  <ManSection>
  <Meth Name="ConvertPolymakeScalarToGAP" Arg="list"/>
   <Description>
    If <A>list</A> contains a single string, this string is converted
    into a number using <Ref Meth="ConvertPolymakeNumber" />.
   </Description>
  </ManSection>

  <ManSection>
   <Meth Name="ConvertPolymakeMatrixOrListOfSetsToGAP" Arg="list"/>
   <Meth Name="ConvertPolymakeMatrixOrListOfSetsToGAPPlusOne" Arg="list"/>
    <Description>
     Tries to decide if the list <A>list</A> of strings represents a matrix or
     a list of sets by testing if they start with "{". It then calls either
     <Ref Meth="ConvertPolymakeMatrixToGAP"/> or <Ref
     Meth="ConvertPolymakeListOfSetsToGAP"/>.
     The "PlusOne" version calls <Ref
Meth="ConvertPolymakeListOfSetsToGAPPlusOne"/> if <A>list</A> represents a list
of sets.
    </Description>
  </ManSection>

  <ManSection>
  <Meth Name="ConvertPolymakeMatrixToGAP" Arg="list"/>
  <Meth Name="ConvertPolymakeMatrixToGAPKillOnes" Arg="list"/>
   <Description>
    The list <A>list</A> of strings is interpreted as a list of row
    vectors and converted into a matrix.
    
    The "KillOnes" version removes the leading ones.
   </Description>
  </ManSection>


  <ManSection>
   <Meth Name="ConvertPolymakeVectorToGAP" Arg="list"/>
   <Meth Name="ConvertPolymakeVectorToGAPKillOne" Arg="list"/>
   <Meth Name="ConvertPolymakeIntVectorToGAPPlusOne" Arg="list"/>
     <Description>
      As the corresponding "Matrix" version. Just for vectors.
      <K>ConvertPolymakeIntVectorToGAPPlusOne</K> requires the vector to
      contain integers. It also adds 1 to every entry.
     </Description>
  </ManSection>


  <ManSection>
   <Meth Name="ConvertPolymakeBoolToGAP" Arg="list"/>
     <Description>
      If <A>list</A> contains a single string, which is either
      0,false,1, or true this function returns <K>false</K> or
      <K>true</K>, respectively.
     </Description>
  </ManSection>


  <ManSection>
   <Meth Name="ConvertPolymakeSetToGAP" Arg="list"/>
     <Description>

      Let <A>list</A> be a list containing a single string, which is a
      list of numbers separated by whitespaces and enclosed by
      &obrace; and &cbrace; . The returned value is then a set of
      rational numbers (in the GAP sense).

    </Description> 
  </ManSection>

  <ManSection>
   <Meth Name="ConvertPolymakeListOfSetsToGAP" Arg="list"/>
   <Meth Name="ConvertPolymakeListOfSetsToGAPPlusOne" Arg="list"/>
     <Description>

      Let <A>list</A> 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.

    </Description> 
  </ManSection>


  <ManSection>
   <Meth Name="ConvertPolymakeGraphToGAP" Arg="list"/>
     <Description>
      Let <A>list</A> be a list of strings representing sets (that is,
      a list of integers enclosed by &obrace; and &cbrace;). Then a record is returned
      containing two sets named <C>.vertices</C> and <C>.edges</C>.
    </Description> 
  </ManSection>


  <ManSection>
   <Meth Name="ConvertPolymakeHasseDiagramToGAP" Arg="list"/>
     <Returns>
      <K>Record</K> with entries <C>.hasse</C> and <C>.faceindices</C>
     </Returns>
     <Description>
      Takes a list <A>list</A> of strings (the <C>HASSE_DIAGRAM</C> returned by
      polymake and split with <Ref
      Meth="SplitPolymakeOutputStringIntoBlocks"/>) and returns a record 
      containing a list of pairs <C>.hasse</C> and a list of lists of integers
      <C>.faceindices</C>. Every pair in <C>.hasse</C> is of the form
      <C>[[vertlist],[upfaces]]</C> where vertlist is a list of vertices (given
      as integers)  and <C>[upfaces]</C> is a list of integers encoding the
      faces in the next (higher) dimension as positions in the list
      <C>.hasse</C>. If polymake returns special faces representing the full
      object or the empty face, they are also included in <C>.hasse</C>.
      <Br/>
      
      <C>.faceindices</C> is a list of lists of integers corresponding to the
      indices of faces in each dimension in <C>.hasse</C>(possibly including
      the extra faces). 

      <Br/>
      Note that the order in which the faces are listed in <C>.hasse</C> is the
      order they are output from polymake. In particular, the list might start
      with vertices for one object and with facets for another.
      </Description>
   </ManSection>
    
<Example>
<![CDATA[
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
]]>
</Example>

 </Section>

</Chapter>