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

<#GAPDoc Label="Graph">
<ManSection>
  <Oper Name="Graph" Arg="digraph"/>
  <Returns>A &Grape; package graph.</Returns>
  <Description>
    If <A>digraph</A> is a mutable or immutable digraph without multiple edges, then this operation
    returns a &Grape; package graph that is isomorphic to <A>digraph</A>. <P/>

    If <A>digraph</A> is a multidigraph, then since &Grape; does not support
    multiple edges, the multiple edges will be reduced to a single edge in the
    result. In order words, for a multidigraph this operation will return the
    same as <C>Graph(DigraphRemoveAllMultipleEdges(</C><A>digraph</A><C>))</C>.

    <Example><![CDATA[
gap> Petersen := Graph(SymmetricGroup(5), [[1, 2]], OnSets,
> function(x, y) return Intersection(x, y) = []; end);;
gap> Display(Petersen);
rec(
  adjacencies := [ [ 3, 5, 8 ] ],
  group := 
   Group( [ ( 1, 2, 3, 5, 7)( 4, 6, 8, 9,10), ( 2, 4)( 6, 9)( 7,10) 
     ] ),
  isGraph := true,
  names := [ [ 1, 2 ], [ 2, 3 ], [ 3, 4 ], [ 1, 3 ], [ 4, 5 ], 
      [ 2, 4 ], [ 1, 5 ], [ 3, 5 ], [ 1, 4 ], [ 2, 5 ] ],
  order := 10,
  representatives := [ 1 ],
  schreierVector := [ -1, 1, 1, 2, 1, 1, 1, 1, 2, 2 ] )
gap> Digraph(Petersen);
<immutable digraph with 10 vertices, 30 edges>
gap> Graph(last) = Petersen;
true]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="CayleyDigraph">
<ManSection>
  <Oper Name="CayleyDigraph" Arg="G[, gens]"/>
  <Returns>An immutable digraph.</Returns>
  <Description>
    Let <A>G</A> be any group and let <A>gens</A> be a list of elements of
    <A>G</A>. This operation returns an immutable digraph that corresponds to
    the Cayley graph of <A>G</A> with respect to <A>gens</A>. <P/>

    The vertices of the digraph correspond to the elements of <A>G</A>,
    in the order given by <C>AsList(<A>G</A>)</C>.
    There exists an edge from vertex <C>u</C> to vertex <C>v</C>
    if and only if there exists a generator <C>g</C> in <A>gens</A>
    such that <C>AsList(<A>G</A>)[u] * g = AsList(<A>G</A>)[v]</C>. <P/>
      
    The labels of the vertices <C>u</C>, <C>v</C>, and the edge <C>[u, v]</C>
    are the corresponding elements <C>AsList(<A>G</A>)[u]</C>,
    <C>AsList(<A>G</A>)[v]</C>, and generator <C>g</C>, respectively;
    see <Ref Oper="DigraphVertexLabel"/> and <Ref Oper="DigraphEdgeLabel"/>.
    <P/>

    If the optional second argument <A>gens</A> is not present, then the
    generators of <A>G</A> are used by default.<P/>

    The digraph created by this operation belongs to the category <Ref
      Filt="IsCayleyDigraph"/>, the group <A>G</A> can be recovered from the
    digraph using <Ref Attr="GroupOfCayleyDigraph"/>, and the generators
    <A>gens</A> can be obtained using <Ref Attr="GeneratorsOfCayleyDigraph"/>.<P/>

    Note that this function can only return an immutable digraph.

    <Example><![CDATA[
gap> G := DihedralGroup(8);
<pc group of size 8 with 3 generators>
gap> CayleyDigraph(G);
<immutable digraph with 8 vertices, 24 edges>
gap> G := DihedralGroup(IsPermGroup, 8);
Group([ (1,2,3,4), (2,4) ])
gap> CayleyDigraph(G);
<immutable digraph with 8 vertices, 16 edges>
gap> digraph := CayleyDigraph(G, [()]);
<immutable digraph with 8 vertices, 8 edges>
gap> GroupOfCayleyDigraph(digraph) = G;
true
gap> GeneratorsOfCayleyDigraph(digraph);
[ () ]]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="GroupOfCayleyDigraph">
<ManSection>
  <Attr Name="GroupOfCayleyDigraph" Arg="digraph"/>
  <Attr Name="SemigroupOfCayleyDigraph" Arg="digraph"/>
  <Returns>A group or semigroup.</Returns>
  <Description>
    If <A>digraph</A> is an immutable Cayley graph of a group <C>G</C> and
    <A>digraph</A> belongs to the category <Ref Filt="IsCayleyDigraph"/>, then
    <C>GroupOfCayleyDigraph</C> returns <C>G</C>.
    <P/>

    If <A>digraph</A> is a Cayley graph of a semigroup <C>S</C> and
    <A>digraph</A> belongs to the category <Ref Filt="IsCayleyDigraph"/>, then
    <C>SemigroupOfCayleyDigraph</C> returns <C>S</C>.
    <P/>

    See also <Ref Attr="GeneratorsOfCayleyDigraph"/>.
    <Example><![CDATA[
gap> G := DihedralGroup(IsPermGroup, 8);
Group([ (1,2,3,4), (2,4) ])
gap> digraph := CayleyDigraph(G);
<immutable digraph with 8 vertices, 16 edges>
gap> GroupOfCayleyDigraph(digraph) = G;
true
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="GeneratorsOfCayleyDigraph">
<ManSection>
  <Attr Name="GeneratorsOfCayleyDigraph" Arg="digraph"/>
  <Returns>A list of generators.</Returns>
  <Description>
    If <A>digraph</A> is an immutable Cayley graph of a group or semigroup with
    respect to a set of generators <C>gens</C> and <A>digraph</A> belongs to
    the category <Ref Filt="IsCayleyDigraph"/>, then
    <C>GeneratorsOfCayleyDigraph</C> return the list of generators <C>gens</C>
    over which <A>digraph</A> is defined.
    <P/>

    See also <Ref Attr="GroupOfCayleyDigraph"/> 
    or <Ref Attr="SemigroupOfCayleyDigraph"/>.
    <Example><![CDATA[
gap> G := DihedralGroup(IsPermGroup, 8);
Group([ (1,2,3,4), (2,4) ])
gap> digraph := CayleyDigraph(G);
<immutable digraph with 8 vertices, 16 edges>
gap> GeneratorsOfCayleyDigraph(digraph) = GeneratorsOfGroup(G);
true
gap> digraph := CayleyDigraph(G, [()]);
<immutable digraph with 8 vertices, 8 edges>
gap> GeneratorsOfCayleyDigraph(digraph) = [()];
true]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="EdgeOrbitsDigraph">
<ManSection>
  <Oper Name="EdgeOrbitsDigraph" Arg="G, edges[, n]"/>
  <Returns>
    An immutable digraph.
  </Returns>
  <Description>
    If <A>G</A> is a permutation group, <A>edges</A> is an edge or list of
    edges, and <A>n</A> is a non-negative integer such that <A>G</A> fixes
    <C>[1 .. <A>n</A>]</C> setwise, then
    this operation returns an immutable digraph with <A>n</A> vertices and the union
    of the orbits of the edges in <A> edges </A> under the action of the
    permutation group <A>G</A>.  An edge in this context is simply a pair of
    positive integers.
    <P/>

    If the optional third argument <A>n</A> is not present, then the largest
    moved point of the permutation group <A>G</A> is used by default.<P/>

    <Example><![CDATA[
gap> digraph := EdgeOrbitsDigraph(Group((1, 3), (1, 2)(3, 4)),
>                                 [[1, 2], [4, 5]], 5);
<immutable digraph with 5 vertices, 12 edges>
gap> OutNeighbours(digraph);
[ [ 2, 4, 5 ], [ 1, 3, 5 ], [ 2, 4, 5 ], [ 1, 3, 5 ], [  ] ]
gap> RepresentativeOutNeighbours(digraph);
[ [ 2, 4, 5 ], [  ] ]
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="DigraphAddEdgeOrbit">
<ManSection>
  <Oper Name="DigraphAddEdgeOrbit" Arg="digraph, edge"/>
  <Returns>
    A new digraph.
  </Returns>
  <Description>
    This operation returns a new digraph with the same vertices and edges as
    <A>digraph</A> and with additional edges consisting of the orbit of the
    edge <A>edge</A> under the action of the <Ref Attr="DigraphGroup"/> of
    <A>digraph</A>.  If <A>edge</A> is already an edge in <A>digraph</A>, then
    <A>digraph</A> is returned unchanged. The argument <A>digraph</A> must be
    an immutable digraph.
    <P/>

    An edge is simply a pair of vertices of <A>digraph</A>.

    <Example><![CDATA[
gap> gr1 := CayleyDigraph(DihedralGroup(8));
<immutable digraph with 8 vertices, 24 edges>
gap> gr2 := DigraphAddEdgeOrbit(gr1, [1, 8]);
<immutable digraph with 8 vertices, 32 edges>
gap> DigraphEdges(gr1);
[ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ], [ 2, 1 ], [ 2, 5 ], [ 2, 6 ], 
  [ 3, 8 ], [ 3, 4 ], [ 3, 7 ], [ 4, 6 ], [ 4, 7 ], [ 4, 1 ], 
  [ 5, 7 ], [ 5, 6 ], [ 5, 8 ], [ 6, 4 ], [ 6, 8 ], [ 6, 2 ], 
  [ 7, 5 ], [ 7, 1 ], [ 7, 3 ], [ 8, 3 ], [ 8, 2 ], [ 8, 5 ] ]
gap> DigraphEdges(gr2);
[ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ], [ 1, 8 ], [ 2, 1 ], [ 2, 5 ], 
  [ 2, 6 ], [ 2, 7 ], [ 3, 8 ], [ 3, 4 ], [ 3, 7 ], [ 3, 6 ], 
  [ 4, 6 ], [ 4, 7 ], [ 4, 1 ], [ 4, 5 ], [ 5, 7 ], [ 5, 6 ], 
  [ 5, 8 ], [ 5, 4 ], [ 6, 4 ], [ 6, 8 ], [ 6, 2 ], [ 6, 3 ], 
  [ 7, 5 ], [ 7, 1 ], [ 7, 3 ], [ 7, 2 ], [ 8, 3 ], [ 8, 2 ], 
  [ 8, 5 ], [ 8, 1 ] ]
gap> gr3 := DigraphRemoveEdgeOrbit(gr2, [1, 8]);
<immutable digraph with 8 vertices, 24 edges>
gap> gr3 = gr1;
true
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="DigraphRemoveEdgeOrbit">
<ManSection>
  <Oper Name="DigraphRemoveEdgeOrbit" Arg="digraph, edge"/>
  <Returns>
    A new digraph.
  </Returns>
  <Description>
    This operation returns a new digraph with the same vertices as
    <A>digraph</A> and with the orbit of the edge <A>edge</A> (under the action
    of the <Ref Attr="DigraphGroup"/> of <A>digraph</A>) removed.
    If <A>edge</A> is not an edge in <A>digraph</A>, then <A>digraph</A> is
    returned unchanged. The argument <A>digraph</A> must be an immutable
    digraph.
    <P/>

    An edge is simply a pair of vertices of <A>digraph</A>.
    <Example><![CDATA[
gap> gr1 := CayleyDigraph(DihedralGroup(8));
<immutable digraph with 8 vertices, 24 edges>
gap> gr2 := DigraphAddEdgeOrbit(gr1, [1, 8]);
<immutable digraph with 8 vertices, 32 edges>
gap> DigraphEdges(gr1);
[ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ], [ 2, 1 ], [ 2, 5 ], [ 2, 6 ], 
  [ 3, 8 ], [ 3, 4 ], [ 3, 7 ], [ 4, 6 ], [ 4, 7 ], [ 4, 1 ], 
  [ 5, 7 ], [ 5, 6 ], [ 5, 8 ], [ 6, 4 ], [ 6, 8 ], [ 6, 2 ], 
  [ 7, 5 ], [ 7, 1 ], [ 7, 3 ], [ 8, 3 ], [ 8, 2 ], [ 8, 5 ] ]
gap> DigraphEdges(gr2);
[ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ], [ 1, 8 ], [ 2, 1 ], [ 2, 5 ], 
  [ 2, 6 ], [ 2, 7 ], [ 3, 8 ], [ 3, 4 ], [ 3, 7 ], [ 3, 6 ], 
  [ 4, 6 ], [ 4, 7 ], [ 4, 1 ], [ 4, 5 ], [ 5, 7 ], [ 5, 6 ], 
  [ 5, 8 ], [ 5, 4 ], [ 6, 4 ], [ 6, 8 ], [ 6, 2 ], [ 6, 3 ], 
  [ 7, 5 ], [ 7, 1 ], [ 7, 3 ], [ 7, 2 ], [ 8, 3 ], [ 8, 2 ], 
  [ 8, 5 ], [ 8, 1 ] ]
gap> gr3 := DigraphRemoveEdgeOrbit(gr2, [1, 8]);
<immutable digraph with 8 vertices, 24 edges>
gap> gr3 = gr1;
true
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>
