#############################################################################
##
#W  semigraph.xml
#Y  Copyright (C) 2014                                  James D. Mitchell
##
##  Licensing information can be found in the README file of this package.
##
#############################################################################
##

<#GAPDoc Label="GraphInverseSemigroup">
<ManSection>
  <Oper Name="GraphInverseSemigroup" Arg="E"/>
  <Returns>A graph inverse semigroup.</Returns>
  <Description>
    If <A>E</A> is a digraph (i.e. it satisfies <Ref Prop="IsDigraph"
      BookName="Digraphs"/>), then <C>GraphInverseSemigroup</C> returns the
    graph inverse semigroup <M>G(<A>E</A>)</M> where, roughly speaking, elements
    correspond to paths in the graph <A>E</A>. <P/>

    Let us describe <A>E</A> as a digraph
    <M><A>E</A> = (E ^ 0, E ^ 1, r, s)</M>, where <M>E^0</M> is the set of
    vertices, <M>E^1</M> is the set of edges, and <M>r</M> and <M>s</M> are
    functions <M>E^1 \to E^0</M> giving the <E>range</E> and <E>source</E> of an
    edge, respectively.
    The <E>graph inverse semigroup <M>G(<A>E</A>)</M> of <M>E</M></E> is the
    semigroup-with-zero generated by the sets <M><A>E</A> ^ 0</M> and
    <M><A>E</A> ^ 1</M>, together with a set of variables
    <M>\{e ^ {-1} \mid e \in <A>E</A> ^ 1\}</M>, satisfying the following
    relations for all <M>v, w \in <A>E</A> ^ 0</M> and
    <M>e, f \in <A>E</A> ^ 1</M>:

    <List>
      <Mark>(V)</Mark>
      <Item><M>vw = \delta_{v,w} \cdot v</M>,</Item>

      <Mark>(E1)</Mark>
      <Item><M>s(e) \cdot e=e \cdot r(e)=e</M>,</Item>

      <Mark>(E2)</Mark>
      <Item><M>r(e) \cdot e^{-1} = e^{-1} \cdot s(e) =e^{-1}</M>,</Item>

      <Mark>(CK1)</Mark>
      <Item><M>e^{-1} \cdot f = \delta_{e,f} \cdot r(e)</M>.</Item>
    </List>

    (Here <M>\delta</M> is the Kronecker delta.) We define <M>v^{-1}=v</M> for
    each <M>v \in E^0</M>, and for any path <M>y=e_1\dots e_n</M> (<M>e_1\dots
    e_n \in E^1</M>) we let <M>y^{-1} = e_n^{-1} \dots e_1^{-1}</M>. With this
    notation, every nonzero element of <M>G(E)</M> can be written uniquely as
    <M>xy^{-1}</M> for some paths <M>x, y</M> in <M>E</M>, by the CK1 relation.
    <P/>

    For a more complete description, see <Cite Key = "Mesyan2016"/>. <P/>

    <Example><![CDATA[
gap> gr := Digraph([[2, 5, 8, 10], [2, 3, 4, 5, 6, 8, 9, 10], [1],
>                   [3, 5, 7, 8, 10], [2, 5, 7], [3, 6, 7, 9, 10],
>                   [1, 4], [1, 5, 9], [1, 2, 7, 8], [3, 5]]);
<immutable digraph with 10 vertices, 37 edges>
gap> S := GraphInverseSemigroup(gr);
<infinite graph inverse semigroup with 10 vertices, 37 edges>
gap> GeneratorsOfInverseSemigroup(S);
[ e_1, e_2, e_3, e_4, e_5, e_6, e_7, e_8, e_9, e_10, e_11, e_12,
  e_13, e_14, e_15, e_16, e_17, e_18, e_19, e_20, e_21, e_22, e_23,
  e_24, e_25, e_26, e_27, e_28, e_29, e_30, e_31, e_32, e_33, e_34,
  e_35, e_36, e_37, v_1, v_2, v_3, v_4, v_5, v_6, v_7, v_8, v_9, v_10
 ]
gap> AssignGeneratorVariables(S);
gap> e_1 * e_1 ^ -1;
e_1e_1^-1
gap> e_1 ^ -1 * e_1 ^ -1;
0
gap> e_1 ^ -1 * e_1;
v_2]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="RangeSourceGraphInverseSemigroupElement">
<ManSection>
  <Attr Name="Range" Arg="x" Label="for a graph inverse semigroup element"/>
  <Attr Name="Source" Arg="x" Label="for a graph inverse semigroup element"/>
  <Returns>A graph inverse semigroup element.</Returns>
  <Description>
    If <A>x</A> is an element of a graph inverse semigroup
    (i.e. it satisfies <Ref Filt = "IsGraphInverseSemigroupElement"/>), then
    <C>Range</C> and <C>Source</C> give, respectively, the start and end
    vertices of <A>x</A> when viewed as a path in the digraph over which the
    semigroup is defined. <P/>

    For a fuller description, see <Ref Oper="GraphInverseSemigroup"/>. <P/>

    <Example><![CDATA[
gap> gr := Digraph([[], [1], [3]]);;
gap> S := GraphInverseSemigroup(gr);;
gap> e := S.1;
e_1
gap> Source(e);
v_2
gap> Range(e);
v_1
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsVertex">
<ManSection>
  <Oper Name="IsVertex" Arg="x" Label="for a graph inverse semigroup element"/>
  <Returns><K>true</K> or <K>false</K>.</Returns>
  <Description>
    If <A>x</A> is an element of a graph inverse semigroup (i.e. it satisfies
    <Ref Filt = "IsGraphInverseSemigroupElement"/>), then this attribute returns
    <K>true</K> if <A>x</A> corresponds to a vertex in the digraph over which
    the semigroup is defined, and <K>false</K> otherwise.
    <P/>

    For a fuller description, see <Ref Oper="GraphInverseSemigroup"/>. <P/>

    <Example><![CDATA[
gap> gr := Digraph([[], [1], [3]]);;
gap> S := GraphInverseSemigroup(gr);;
gap> e := S.1;
e_1
gap> IsVertex(e);
false
gap> v := S.3;
v_1
gap> IsVertex(v);
true
gap> z := v * e;
0
gap> IsVertex(z);
false
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsGraphInverseSemigroup">
<ManSection>
  <Filt Name="IsGraphInverseSemigroup" Arg="x"/>
  <Filt Name="IsGraphInverseSemigroupElement" Arg="x"/>
  <Returns><K>true</K> or <K>false</K>.</Returns>
  <Description>
    The category <C>IsGraphInverseSemigroup</C> contains any semigroup defined
    over a digraph using the <Ref Oper="GraphInverseSemigroup"/> operation.
    The category <C>IsGraphInverseSemigroupElement</C> contains any element
    contained in such a semigroup. <P/>

    <Example><![CDATA[
gap> gr := Digraph([[], [1], [3]]);;
gap> S := GraphInverseSemigroup(gr);
<infinite graph inverse semigroup with 3 vertices, 2 edges>
gap> IsGraphInverseSemigroup(S);
true
gap> x := GeneratorsOfSemigroup(S)[1];
e_1
gap> IsGraphInverseSemigroupElement(x);
true
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="GraphOfGraphInverseSemigroup">
<ManSection>
  <Attr Name="GraphOfGraphInverseSemigroup" Arg="S"/>
  <Returns>A digraph.</Returns>
  <Description>
    If <A>S</A> is a graph inverse semigroup (i.e. it satisfies
    <Ref Filt="IsGraphInverseSemigroup"/>), then this attribute returns the
    original digraph over which <A>S</A> was defined (most likely the argument
    given to <Ref Oper="GraphInverseSemigroup"/> to create <A>S</A>). <P/>

    <Example><![CDATA[
gap> gr := Digraph([[], [1], [3]]);
<immutable digraph with 3 vertices, 2 edges>
gap> S := GraphInverseSemigroup(gr);;
gap> GraphOfGraphInverseSemigroup(S);
<immutable digraph with 3 vertices, 2 edges>
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsGraphInverseSemigroupElementCollection">
  <ManSection>
    <Filt Name="IsGraphInverseSemigroupElementCollection"  Type="Category"/>
    <Description>
      Every collection of elements of a graph inverse semigroup belongs to the
      category <C>IsGraphInverseSemigroupElementCollection</C>. For example,
      every graph inverse semigroup belongs to
      <C>IsGraphInverseSemigroupElementCollection</C>.
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsGraphInverseSubsemigroup">
<ManSection>
    <Filt Name = "IsGraphInverseSubsemigroup"/>
    <Description>
      <C>IsGraphInverseSubsemigroup</C> is a synonym for
      <C>IsSemigroup</C> and <C>IsInverseSemigroup</C> and
      <C>IsGraphInverseSemigroupElementCollection</C>. <P/>

      See <Ref Filt = "IsGraphInverseSemigroupElementCollection"/> and
      <Ref Prop = "IsInverseSemigroup" BookName = "ref"/>.

<Example><![CDATA[
gap> gr := Digraph([[], [1], [2]]);
<immutable digraph with 3 vertices, 2 edges>
gap> S := GraphInverseSemigroup(gr);
<finite graph inverse semigroup with 3 vertices, 2 edges>
gap> Elements(S);
[ e_2^-1, e_1^-1, e_1^-1e_2^-1, 0, e_1, e_1e_1^-1, e_1e_1^-1e_2^-1,
  e_2, e_2e_2^-1, e_2e_1, e_2e_1e_1^-1, e_2e_1e_1^-1e_2^-1, v_1, v_2,
  v_3 ]
gap> T := InverseSemigroup(Elements(S){[3, 5]});;
gap> IsGraphInverseSubsemigroup(T);
true]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>


<#GAPDoc Label="VerticesOfGraphInverseSemigroup">
<ManSection>
  <Attr Name="VerticesOfGraphInverseSemigroup" Arg="S"/>
  <Returns>A list.</Returns>
  <Description>
    If <A>S</A> is a graph inverse semigroup (i.e. it satisfies
    <Ref Filt="IsGraphInverseSemigroup"/>), then this attribute returns the
    list of vertices of <A>S</A>.

    <Example><![CDATA[
gap> D := Digraph([[3, 4], [3, 4], [4], []]);
<immutable digraph with 4 vertices, 5 edges>
gap> S := GraphInverseSemigroup(D);
<finite graph inverse semigroup with 4 vertices, 5 edges>
gap> VerticesOfGraphInverseSemigroup(S);
[ v_1, v_2, v_3, v_4 ]
gap> D := ChainDigraph(12);
<immutable chain digraph with 12 vertices>
gap> S := GraphInverseSemigroup(D);
<finite graph inverse semigroup with 12 vertices, 11 edges>
gap> VerticesOfGraphInverseSemigroup(S);
[ v_1, v_2, v_3, v_4, v_5, v_6, v_7, v_8, v_9, v_10, v_11, v_12 ]
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="IndexOfVertexOfGraphInverseSemigroup">
<ManSection>
  <Attr Name="IndexOfVertexOfGraphInverseSemigroup" Arg="v"/>
  <Returns>A positive integer.</Returns>
  <Description>
    If <A>v</A> is a vertex of a graph inverse semigroup (i.e. it satisfies
    <Ref Filt="IsGraphInverseSemigroup"/>), then this attribute returns the
    index of this vertex in <A>S</A>.<P/>

    <Example><![CDATA[
gap> D := Digraph([[3, 4], [3, 4], [4], []]);
<immutable digraph with 4 vertices, 5 edges>
gap> S := GraphInverseSemigroup(D);
<finite graph inverse semigroup with 4 vertices, 5 edges>
gap> IndexOfVertexOfGraphInverseSemigroup(v_1);
1
gap> IndexOfVertexOfGraphInverseSemigroup(v_3);
3]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>