<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- $Id: drawings.xml,v 0.998 Exp $ -->
<Chapter>
<Heading>
Drawings of semigroups
</Heading>
There are some pictures that may give a lot of information about a semigroup.
This is the case of the egg-box picture of the D-classes,
the right Cayley graph of a finite monoid and the Schutzenberger graphs
of a finite inverse monoid.
<Section>
<Heading>
Drawing the D-class of an element of a semigroup
</Heading>
<ManSection>
<Func Arg="arg" Name="DrawDClassOfElement" />
<Description>
This function takes as arguments a semigroup followed by a transformation which is the element whose D-class will be drawn. Optionally we can then specify n lists of elements and the elements of each list will be drawn in different colours. Finally, we may specify a string name the file that will be used to write the drawing of the class (in PostScript format) and if the last argument is the integer <C>1</C> then the elements will appear as transformations, otherwise they will appear as words. The idempotents will be marked with a * before them.
<P/>
This last optional argument may also be the integer <C>2</C> and in this case
the elements will appear as integers, where <C>i</C> represents the element <C>Elements(S)[i]</C>.
</Description>
</ManSection>
<Example>
gap> DrawDClassOfElement(poi3, Transformation([1,4,3,4]));
gap> DrawDClassOfElement(poi3, Transformation([1,4,3,4]),1);
gap> DrawDClassOfElement(poi3, Transformation([1,4,3,4]),
[Transformation( [ 2, 3, 4, 4 ] )],1);
gap> DrawDClassOfElement(poi3, Transformation([1,4,3,4]),
[Transformation( [ 2, 3, 4, 4 ] ), Transformation( [ 2, 4, 3, 4 ] )],
[Transformation( [ 2, 4, 3, 4 ] )],1);
gap> DrawDClassOfElement(poi3, Transformation([1,4,3,4]),
[Transformation( [ 2, 4, 3, 4 ] )],"Dclass",1);
</Example>
<Alt Only="HTML">
This is the image produced by the first command in the previous example:
<br><br><center><img src="images/dclass1.png"></center><br>
<br><br>
This is the image produced by the fourth command in the previous example:
<br><br><center><img src="images/dclass2.png"></center><br>
<br><br>
This is the image produced by the last command in the previous example:
<br><br><center><img src="images/dclass3.png"></center><br>
<br><br>
</Alt>
</Section>
<Section>
<Heading>
Drawing the D-classes of a semigroup
</Heading>
<ManSection>
<Func Arg="arg" Name="DrawDClasses" />
<Description>
This function is similar to the previous one, except that this one draws all the D-classes of the semigroup given as the first argument. It then takes optionally n lists of elements and the elements of each list will be drawn in different colours. It also accepts a string specifying the name of the file in which the drawing will be written and the last, optional, argument, the integer <C>1</C>, to specify whether the elements will appear as words or as transformations as in the previous function. The idempotents will be marked with a * before them.
<P/>
This last optional argument may also be the integer <C>2</C> and in this case
the elements will appear as integers, where <C>i</C> represents the element <C>Elements(S)[i]</C>.
</Description>
</ManSection>
<Example>
gap> DrawDClasses(poi3,"DClasses");
gap> DrawDClasses(poi3, [Transformation( [ 2, 3, 4, 4 ] ),
Transformation( [ 2, 4, 3, 4 ] )],
[Transformation( [ 2, 4, 3, 4 ] )],1);
</Example>
<Alt Only="HTML">
This is the image produced by the first command in the previous example:
<br><br><center><img src="images/dclasses1.png"></center><br>
<br><br>
This is the image produced by the second command in the previous example:
<br><br><center><img src="images/dclasses2.png"></center><br>
<br><br>
</Alt>
</Section>
<Section>
<Heading>Cayley graphs</Heading>
<ManSection>
<Func Arg="S" Name="DrawRightCayleyGraph" />
<Description>Draws the right Cayley graph of a finite monoid or semigroup <Arg>S</Arg>.
</Description>
</ManSection>
<ManSection>
<Func Arg="S" Name="DrawCayleyGraph" />
<Description>This function is a synonym of
<Ref Func="DrawRightCayleyGraph" />.
</Description>
</ManSection>
For example, the command <C>DrawCayleyGraph(b21);</C> would produce the following image
(where state <C>i</C> represents the element <C>Elements(S)[i]</C>, the neutral element is
colored in "light blue" and all other idempotents are colored in "light coral"):
<Alt Only="HTML">
<br><br><center><img src="images/cgb21.png"></center><br>
</Alt>
</Section>
<Section>
<Heading>Schutzenberger graphs</Heading>
<ManSection>
<Func Arg="S" Name="DrawSchutzenbergerGraphs" />
<Description>Draws the Schutzenberger graphs of the inverse
semigroup <Arg>S</Arg>.</Description>
</ManSection>
For example, <Code>DrawSchutzenbergerGraphs(poi3);</Code> would produce
the following:
<P />
<Alt Only="HTML">
<br><center><img src="images/schutzenberger.gif"></center><br>
</Alt>
</Section>
<Section Label="Drawings_output_formats">
<Heading>Drawings output formats</Heading>
By default, when a drawing is requested, it is outputted in PostScript format.
Since <C>graphviz</C> allows other output formats (see <URL>http://www.graphviz.org/doc/info/output.html</URL>), it is possible to also request a drawing in a format other than PostScript.
<ManSection>
<Var Name="DrawingsListOfExtraFormats" />
<Description>
This is a global variable which holds the valid output formats for a drawing. It currently has the value: <C>["dia", "fig", "gd", "gd2", "gif", "hpgl", "jpg", "mif", "mp", "pcl", "pic", "plain", "plain-ext", "png", "ps", "ps2", "svg", "svgz", "vrml", "vtx", "wbmp", "none"]</C> (see <URL>http://www.graphviz.org/doc/info/output.html</URL> for their description).
</Description>
</ManSection>
<ManSection>
<Var Name="DrawingsExtraFormat" />
<Description>
This is a global variable which holds the alternative output format for a drawing.
By default its value is <C>"none"</C> which indicates that just PostScript will be used
as the output format.
<P/>
If its value becomes one of those in <Ref Var="DrawingsListOfExtraFormats" />, then
besides the PostScript file, it will also be created a file in the alternative format.
<P/>
To change this variable's value, please use <Ref Func="SetDrawingsExtraFormat" />.
</Description>
</ManSection>
<ManSection>
<Func Arg="f" Name="SetDrawingsExtraFormat" />
<Description>
This function is used to set the value of <Ref Var="DrawingsExtraFormat" /> to the
format <A>f</A> which is one of <Ref Var="DrawingsListOfExtraFormats" />.
<Example><![CDATA[
gap> DrawingsExtraFormat;
"none"
gap> SetDrawingsExtraFormat("jpg");
gap> DrawingsExtraFormat;
"jpg"
gap> DrawRightCayleyGraph(poi3);
Displaying file: /tmp/tmp.tpJqvI/cayleygraph.dot.ps
The extra output format file: /tmp/tmp.tpJqvI/cayleygraph.dot.jpg
has also been created.
]]></Example>
</Description>
</ManSection>
</Section>
<Section Label="Drawings_extra_graph_attributes">
<Heading>Drawings extra graph attributes</Heading>
The functions described in this subsection are intended to give the user a finer control
over the final drawing.
They allow to define the graph attributes described in <URL>http://graphviz.org/doc/info/attrs.html</URL>.
(Note that only graph attributes are allowed to be defined, not edge nor node attributes are supported yet.)
<ManSection>
<Var Name="DrawingsExtraGraphAttributes" />
<Description>
This is a global variable which holds a list of strings, each of which defines a <E>dot</E> graph attribute.
This variable is <E>not</E> intended to be modified by the user directly, but can be used to check
which extra attributes are currently defined.
To set the attributes, please use <Ref Func="SetDrawingsExtraGraphAttributes" />.
If <C>DrawingsExtraGraphAttributes</C> holds the value <C>"none"</C> then the default <E>dot</E> settings will be used.
Use <Ref Func="ClearDrawingsExtraGraphAttributes" /> to set it to <C>"none"</C>.
</Description>
</ManSection>
<ManSection>
<Func Arg="L" Name="SetDrawingsExtraGraphAttributes" />
<Description>
This is the function to define the drawing's graph attributes (see <URL>http://graphviz.org/doc/info/attrs.html</URL>
for a list and explanation of them).
the argument <A>L</A> is a list of strings, each of which defines a <E>dot</E> graph attribute.
For example, if we wanted to define the graph size to be 7x9 (in inches), we would call
<C>SetDrawingsExtraGraphAttributes(["size=7,9"]);</C>.
<P />
If we also wanted to define the graph to be displayed in landscape mode we would call
<C>SetDrawingsExtraGraphAttributes(["size=7,9", "rotate=90"]);</C>.
If, in addition we wanted to define the background color to be, for example, pink, we would call
<C>SetDrawingsExtraGraphAttributes(["size=7,9", "rotate=90", "bgcolor=pink"]);</C>.
<P />
After defining the attributes, any command that creates a drawing will use the last defined attributes.
To set them back to the defaults, please use <Ref Func="ClearDrawingsExtraGraphAttributes" />.
<Example><![CDATA[
gap> DrawingsExtraGraphAttributes;
"none"
gap> SetDrawingsExtraGraphAttributes(["size=7,9"]);
gap> DrawingsExtraGraphAttributes;
[ "size=7,9" ]
gap> SetDrawingsExtraGraphAttributes(["size=7,9", "rotate=90"]);
gap> DrawingsExtraGraphAttributes;
[ "size=7,9", "rotate=90" ]
gap> SetDrawingsExtraGraphAttributes(["size=7,9", "rotate=90", "bgcolor=pink"]);
gap> DrawingsExtraGraphAttributes;
[ "size=7,9", "rotate=90", "bgcolor=pink" ]
gap> ClearDrawingsExtraGraphAttributes();
gap> DrawingsExtraGraphAttributes;
"none"
]]></Example>
</Description>
</ManSection>
<ManSection>
<Func Arg="" Name="ClearDrawingsExtraGraphAttributes" />
<Description>
This function sets the graph drawing attributes back to <E>dot</E>'s defaults.
</Description>
</ManSection>
</Section>
</Chapter>
