<Section><Heading>Calling Polymake and converting its output</Heading>

   <ManSection>
   <Meth Name="Polymake" Arg="poly option [: [PolymakeNolookup]]"/>
    <Description>
    
     This method calls the polymake program (see <Ref
     Var="POLYMAKE_COMMAND"/>) with the option
     <A>option</A>. You may use several keywords such as
     <C>"DIM VERTICES"</C> as an option. The returned value is cut into blocks
     starting with keywords (which are taken from output and not 
     looked up in <A>option</A>). Each block is then
     interpreted and translated into &GAP; readable form. This
     translation is done using the functions given in <Ref
     Var="ObjectConverters"/>.

     The first line of each block of polymake output is taken as a
     keyword and the according entry in <Ref Var="ObjectConverters"/>
     is called to convert the block into &GAP; readable form. If no
     conversion function is known, an info string is printed and <K>fail</K> is
     returned.

     If only one keyword has been given as <A>option</A>,
     <C>Polymake</C> returns the result of the conversion operation.
     If more than one keyword has been given or the output consists of
     more than one block, <C>Polymake</C> returns <K>fail</K>.

     In any case, the calculated values for each block are stored as
     known properties of the <K>PolymakeObject</K> <A>poly</A> as long
     as they are not <K>fail</K>.

     If <K>Polymake</K> is called with an option that corresponds to a
     name of a known property of <A>poly</A>, the known property is
     returned. In this case, there is no call of the external program.
     (see below for suppression of this feature).<P/>
     
     Note that the command <K>Polymake</K> returns <K>fail</K> if
     nothing is returned by the program polymake or more than one
     block of data is returned. For example, the returned value of
     <C>Polymake(poly,"VISUAL")</C> is always
     <K>fail</K>. Likewise, <C>Polymake(poly,"POINTS VERTICES")</C>
     will return <K>fail</K> (but may add new known properties to
     <A>poly</A>).

     For a description of the conversion functions, see chapter <Ref
     Chap="Converting"/>.<P/>
     
     If the option <A>PolymakeNolookup</A> is set to anything else
     than false, the polymake program is called even if <A>poly</A>
     already has a known property with name <A>option</A>.
  </Description>
  </ManSection>

  Note that whenever <Ref Meth="Polymake"/> returns <K>fail</K>, a description
  of the problem is stored in  <Ref Var="POLYMAKE_LAST_FAIL_REASON"/>.
  If you call <Ref Meth="Polymake"/> with more than one keyword, 
  <Ref Var="POLYMAKE_LAST_FAIL_REASON"/> is changed before polymake is
  called. So any further reason to return <K>fail</K> will overwrite it.

  </Section>

   <Section><Heading>An Example</Heading>

   Let's generate a three dimensional permutahedron.

    <Example>
    <![CDATA[
    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
    ]]>
    </Example>    

   </Section>

<Section><Heading>Calling Clients</Heading>

<ManSection>
<Meth Name="PolymakeClient" Arg="clientname [,outobject] [,inobjects]
[,options]"/>
<Meth Name="PolymakeClientNC" Arg="clientname ,outobject ,inobjects ,options"/>
   <Returns>PolymakeObject</Returns>   
  <Description>
   Any client program that has a command line syntax like 
   <Br/>
    <C>clientname outfile infile1 infile2... -option1 -option2...</C>
   <Br/>
   can be called using <K>PolymakeClient</K>. Any output of the client to the
   terminal is ignored (but a warning  is printed if this happens).
   <Br/>
   <A>clientname</A> must be given as a string without path. Polymaking looks
   for clients in the directories listed in <Ref
Var="POLYMAKE_CLIENT_PATHS"/>.
<Br/>
   The client program is called and passed the file corresponding to
   the PolymakeObject <A>outobject</A>, the files of the PolymakeObjects in
   the list <A>inobjects</A> and finally the string <A>options</A>.
   If no PolymakeObject <A>outobject</A> is given, a new object is created.
   <K>PolymakeClient</K> returns the PolymakeObject <A>outobject</A> if it was
   given, otherwise a new PolymakeObject is returned.
<Br/>
   <K>PolymakeClientNC</K> does not perform any checks on the input objects.
<Br/>
   <Emph>Important:</Emph> <K>PolymakeClient</K> does not change the known
    properties of  <A>outfile</A>. This can lead to inconsistencies if you
    "recycle" files. So if you know that a client will overwrite the output
    file, consider using <Ref Meth="ClearPolymakeObject"/> on the output
    PolymakeObject before calling the client.
  </Description>
</ManSection>

<Example>
<![CDATA[
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
]]>
</Example>

</Section>