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