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

<#GAPDoc Label="AutomorphismGroupDigraph">
<ManSection>
  <Attr Name="AutomorphismGroup" Label="for a digraph" Arg="digraph"/>
  <Oper Name="AutomorphismGroup" Label="for a digraph and a homogeneous list"
    Arg="digraph, colors"/>
  <Returns>A permutation group.</Returns>
  <Description>
    If <A>digraph</A> is a digraph without multiple edges, then this function
    returns the automorphism group of <A>digraph</A>, as a group of
    permutations on the vertices of <A>digraph</A>. <P/>

    If the <A>colors</A> argument is specified, then the group will consist of
    only those automorphisms which respect the given colouring.  The colouring
    <A>colors</A> can be in one of two forms: <P/>

    <List>
      <Item>
        A list of positive integers of size the number of vertices of
        <A>digraph</A>, where <A>colors</A><C>[i]</C> is the colour of vertex
        <C>i</C>.
      </Item>
      <Item>
        A list of lists, such that <A>colors</A><C>[i]</C> is a list of all
        vertices with colour <C>i</C>.
      </Item>
    </List>

    The automorphism group is found using <URL
      Text="bliss">http://www.tcs.tkk.fi/Software/bliss/index.html</URL> by
    Tommi Junttila and Petteri Kaski.

    <Example><![CDATA[
gap> johnson := Digraph([[2, 3, 4, 5], [1, 3, 4, 6], 
> [1, 2, 5, 6], [1, 2, 5, 6], [1, 3, 4, 6], 
> [2, 3, 4, 5]]);
<digraph with 6 vertices, 24 edges>
gap> AutomorphismGroup(johnson);
Group([ (3,4), (2,3)(4,5), (1,2)(5,6) ])
gap> Size(last);
48
gap> cycle := CycleDigraph(9);
<digraph with 9 vertices, 9 edges>
gap> a := AutomorphismGroup(cycle);;
gap> StructureDescription(a);
"C9"
gap> a := AutomorphismGroup(cycle, [1, 2, 3, 1, 2, 3, 1, 2, 3]);;
gap> StructureDescription(a);
"C3"
gap> a := AutomorphismGroup(cycle, [[1, 4, 7], [2, 5, 8], [3, 6, 9]]);;
gap> StructureDescription(a);
"C3"
]]></Example>
    </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="AutomorphismGroupMultiDigraph">
  <ManSection>
    <Attr Name="AutomorphismGroup" Label="for a multidigraph" Arg="digraph"/>
    <Returns>A direct product of permutation groups.</Returns>
    <Description>
    If <A>digraph</A> is a multidigraph, then this function returns the
    automorphism group of <A>digraph</A>, as a group of permutations on the
    vertices and edges of <A>digraph</A>.<P/>

    For convenience, the returned group is the direct product of the group of
    automorphisms of the vertices of <A>digraph</A> with the stabiliser of the
    vertices in the automorphism group of the edges. These two groups can be
    accessed using the <Ref Oper="Projection" BookName="ref"/> with second
    argument <C>1</C> and <C>2</C>, respectively. 
    <P/>

    The permutations in the automorphism group of the edges act on the indices
    of the edges of <A>digraph</A>.<P/>

    The automorphism group is found using <URL
      Text="bliss">http://www.tcs.tkk.fi/Software/bliss/index.html</URL> by
    Tommi Junttila and Petteri Kaski.

    <Example><![CDATA[
gap> gr := DigraphEdgeUnion(CycleDigraph(3), CycleDigraph(3));          
<multidigraph with 3 vertices, 6 edges>
gap> G := AutomorphismGroup(gr);
Group([ (1,2,3), (8,9), (6,7), (4,5) ])
gap> Range(Projection(G, 1));
Group([ (1,2,3) ])
gap> Range(Projection(G, 2));
Group([ (5,6), (3,4), (1,2) ])
gap> Size(G);
24]]></Example>
  </Description>
  </ManSection>
<#/GAPDoc>

<#GAPDoc Label="DigraphCanonicalLabelling">
<ManSection>
  <Attr Name="DigraphCanonicalLabelling" Label="for a digraph" Arg="digraph"/>
  <Oper Name="DigraphCanonicalLabelling" Label="for a digraph and a list"
    Arg="digraph, colors"/>
  <Returns> A permutation.</Returns>
  <Description>
    A function <M>\rho</M> from a digraph to a digraph is a <E>canonical
    representative map</E> if the following two conditions hold:
    <List>
      <Item>
        <M>\rho(G)</M> and <M>G</M> are isomorphic; and 
      </Item>
      <Item>
        <M>\rho(G)=\rho(H)</M> if and only if <M>G</M> and <M>H</M> are isomorphic.
      </Item>
    </List>

    A canonical labelling of a digraph <A>digraph</A> (under <M>\rho</M>) is
    an isomorphism of <A>digraph</A> onto its canonical representative
    <M>\rho(</M><A>digraph</A><M>)</M> given as a permutation of the vertices
    (and the edges in case <A>digraph</A> has multiple edges). <P/>

    If the <A>colors</A> argument is specified, then the canonical labelling
    will respect the given colouring.  The colouring
    <A>colors</A> can be in one of two forms: <P/>

    <List>
      <Item>
        A list of positive integers of size the number of vertices of
        <A>digraph</A>, where <A>colors</A><C>[i]</C> is the colour of vertex
        <C>i</C>.
      </Item>
      <Item>
        A list of lists, such that <A>colors</A><C>[i]</C> is a list of all
        vertices with colour <C>i</C>.
      </Item>
    </List>

    The canonical labelling is found using <URL
      Text="bliss">http://www.tcs.tkk.fi/Software/bliss/index.html</URL> by
    Tommi Junttila and Petteri Kaski.
    <Example><![CDATA[
gap> G := Digraph(10, [1, 1, 3, 4, 4, 5, 8, 8], [6, 3, 3, 9, 10, 9, 4, 10]);
<digraph with 10 vertices, 8 edges>
gap> DigraphCanonicalLabelling(G);
(1,8,5,3,10,6,4,9,7)
gap> DigraphCanonicalLabelling(G, [[1 .. 5], [6 .. 10]]);
(1,3,5,2)(6,7)(8,9,10)
gap> DigraphCanonicalLabelling(G, [1, 1, 1, 1, 2, 3, 1, 3, 2, 1]);
(1,4,5,7)(3,6,9,8,10)
gap> p := (1,2,7,5)(3,9)(6,10,8);;
gap> H := Digraph(
>  10,
>  OnTuples([1, 1, 3, 4, 4, 5, 8, 8], p),
>  OnTuples([6, 3, 3, 9, 10, 9, 4, 10], p)
> );
<digraph with 10 vertices, 8 edges>
gap> G = H;
false
gap> OnDigraphs(G, DigraphCanonicalLabelling(G)) =
>    OnDigraphs(H, DigraphCanonicalLabelling(H));
true
gap> gr := Digraph([[7, 2, 8, 2], [7, 6], [9], [], 
> [], [], [], [2], [6], [4]]);
<multidigraph with 10 vertices, 10 edges>
gap> DigraphCanonicalLabelling(gr);
[ (1,9,7,5)(2,10,3), (1,7,3,8,2,6,10,4,5,9) ]]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsIsomorphicDigraph">
<ManSection>
  <Oper Name="IsIsomorphicDigraph" Label="for digraphs" Arg="digraph1, digraph2"/>
  <Returns><K>true</K> or <K>false</K>.</Returns>
  <Description>
    This operation returns <K>true</K> if the digraph <A>digraph1</A> is
    isomorphic to the digraph <A>digraph2</A>.<P/>
    
    This operation uses the canonical labelling of the digraphs found with <URL
      Text="bliss">http://www.tcs.tkk.fi/Software/bliss/index.html</URL> by
    Tommi Junttila and Petteri Kaski.
    
    <Example><![CDATA[
gap> digraph1 := CycleDigraph(4);
<digraph with 4 vertices, 4 edges>
gap> digraph2 := CycleDigraph(5);
<digraph with 5 vertices, 5 edges>
gap> IsIsomorphicDigraph(digraph1, digraph2);
false
gap> digraph2 := DigraphReverse(digraph1);
<digraph with 4 vertices, 4 edges>
gap> IsIsomorphicDigraph(digraph1, digraph2);
true
gap> digraph1 := Digraph([[], [9, 8, 9], [7], 
> [], [], [5, 3], [8], [6], [4, 5], []]);
<multidigraph with 10 vertices, 10 edges>
gap> digraph2 := Digraph([[], [4], [], [7], [], 
> [4, 5, 10, 5], [], [9], [4, 2], [2]]);
<multidigraph with 10 vertices, 10 edges>
gap> IsIsomorphicDigraph(digraph1, digraph2);
false
gap> digraph1 := Digraph([[3], [], []]);
<digraph with 3 vertices, 1 edge>
gap> digraph2 := Digraph([[], [], [2]]);
<digraph with 3 vertices, 1 edge>
gap> IsIsomorphicDigraph(digraph1, digraph2);
true]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="IsomorphismDigraphs">
<ManSection>
  <Oper Name="IsomorphismDigraphs" Label="for digraphs" Arg="digraph1, digraph2"/>
  <Returns> A permutation or <K>fail</K>.</Returns>
  <Description>
    If <A>digraph1</A> and <A>digraph2</A> are isomorphic digraphs, then this
    operation returns an isomorphism from <A>digraph1</A> to <A>digraphs2</A>. 

    More precisely, 

    <List>
      <Mark>for multidigraphs</Mark>
      <Item>
        this operation returns a pair of permutations <C>P</C> such that 
        <C>OnMultiDigraphs(<A>digraph1</A>, P) = digraph2</C>. The first
        permutation is defined on the vertices of <A>digraph1</A> and the second
        on the edges. 
      </Item>
      <Mark>for digraphs without multiple edges</Mark>
      <Item>
        this operation returns a permutation <C>p</C> such that 
        <C>OnDigraphs(<A>digraph1</A>, p) = digraph2</C>. 
      </Item>
    </List>

    If <A>digraph1</A> and <A>digraph2</A> are not isomorphic, then <K>fail</K>
    is returned. 
    <P/>

    This operation uses the canonical labelling of the digraphs found with <URL
    Text="bliss">http://www.tcs.tkk.fi/Software/bliss/index.html</URL> by
    Tommi Junttila and Petteri Kaski.

    <Example><![CDATA[
gap> digraph1 := CycleDigraph(4);          
<digraph with 4 vertices, 4 edges>
gap> digraph2 := CycleDigraph(5);
<digraph with 5 vertices, 5 edges>
gap> IsomorphismDigraphs(digraph1, digraph2);
fail
gap> gr1 := CompleteBipartiteDigraph(10, 5);
<digraph with 15 vertices, 100 edges>
gap> gr2 := CompleteBipartiteDigraph(5, 10);
<digraph with 15 vertices, 100 edges>
gap> p := IsomorphismDigraphs(gr1, gr2);
(1,6,11)(2,7,12)(3,8,13)(4,9,14)(5,10,15)
gap> OnDigraphs(gr1, p) = gr2;
true
gap> gr1 := Digraph([[3, 6, 3], [], [3], [9, 10], [9], [], 
> [], [10, 4, 10], [], []]);
<multidigraph with 10 vertices, 10 edges>
gap> gr2 := Digraph([[], [], [5], [], [], [], 
> [5, 6], [6, 7, 6], [10, 4, 10], [10]]);
<multidigraph with 10 vertices, 10 edges>
gap> IsomorphismDigraphs(gr1, gr2);
[ (1,9,5,3,10,6,4,7,2), (1,7)(2,8,4,10,6,3,9,5) ]
gap> digraph1 := Digraph([[], [], [], [], [], [], 
> [10, 10], [], [], []]);
<multidigraph with 10 vertices, 2 edges>
gap> digraph2 := Digraph([[], [3, 3], [], [], [], [],
> [], [], [], []]);
<multidigraph with 10 vertices, 2 edges>
gap> IsomorphismDigraphs(digraph1, digraph2);
[ (2,4,6,8,9,10,3,5,7), () ]]]></Example>
</Description>
</ManSection>
<#/GAPDoc>
