#############################################################################
##
#W  examples.xml
#Y  Copyright (C) 2019                              Murray T. Whyte
##
##  Licensing information can be found in the README file of this package.
##
#############################################################################
##

<#GAPDoc Label="EmptyDigraph">
<ManSection>
  <Oper Name="EmptyDigraph" Arg="[filt, ]n"/>
  <Oper Name="NullDigraph" Arg="[filt, ]n"/>
  <Returns>A digraph.</Returns>
  <Description>
    If <A>n</A> is a non-negative integer, this function returns the
    <E>empty</E> or <E>null</E> digraph with <A>n</A> vertices. An empty
    digraph is one with no edges.
    <P/>
      
    If the optional first argument <A>filt</A> is present, then this should
    specify the category or representation the digraph being created will
    belong to. For example, if <A>filt</A> is <Ref Filt="IsMutableDigraph"/>,
    then the digraph being created will be mutable, if <A>filt</A> is <Ref
    Filt="IsImmutableDigraph"/>, then the digraph will be immutable. 
    If the optional first argument <A>filt</A> is not present, then <Ref
      Filt="IsImmutableDigraph"/> is used by default.<P/>

    <C>NullDigraph</C> is a synonym for <C>EmptyDigraph</C>.

    <Example><![CDATA[
gap> EmptyDigraph(20);
<immutable empty digraph with 20 vertices>
gap> NullDigraph(10);
<immutable empty digraph with 10 vertices>
gap> EmptyDigraph(IsMutableDigraph, 10);
<mutable empty digraph with 10 vertices>]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="CompleteBipartiteDigraph">
<ManSection>
  <Oper Name="CompleteBipartiteDigraph" Arg="[filt, ]m, n"/>
  <Returns>A digraph.</Returns>
  <Description>
    A complete bipartite digraph is a digraph whose vertices
    can be partitioned into two non-empty vertex sets, such there exists
    a unique edge with source <C>i</C> and range <C>j</C> if and only if
    <C>i</C> and <C>j</C> lie in different vertex sets. <P/>

    If <A>m</A> and <A>n</A> are positive integers, this function
    returns the complete bipartite digraph with vertex sets of sizes
    <A>m</A> (containing the vertices <C>[1 .. m]</C>) and
    <A>n</A> (containing the vertices <C>[m + 1 .. m + n]</C>).
    <P/>

    If the optional first argument <A>filt</A> is present, then this should
    specify the category or representation the digraph being created will
    belong to. For example, if <A>filt</A> is <Ref Filt="IsMutableDigraph"/>,
    then the digraph being created will be mutable, if <A>filt</A> is <Ref
    Filt="IsImmutableDigraph"/>, then the digraph will be immutable. 
    If the optional first argument <A>filt</A> is not present, then <Ref
      Filt="IsImmutableDigraph"/> is used by default.

    <Example><![CDATA[
gap> CompleteBipartiteDigraph(2, 3);
<immutable complete bipartite digraph with bicomponent sizes 2 and 3>
gap> CompleteBipartiteDigraph(IsMutableDigraph, 3, 2);
<mutable digraph with 5 vertices, 12 edges>
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="CompleteMultipartiteDigraph">
  <ManSection>
    <Oper Name="CompleteMultipartiteDigraph" Arg = "[filt, ]orders"/>
    <Returns>A digraph.</Returns>
    <Description>
      For a list <A>orders</A> of <C>n</C> positive integers,
      this function returns the digraph containing <C>n</C> independent sets
      of vertices of orders <C>[<A>l</A>[1] .. <A>l</A>[n]]</C>. Moreover,
      each vertex is adjacent to every other not contained in the
      same independent set.
      <P/>

      If the optional first argument <A>filt</A> is present, then this should
      specify the category or representation the digraph being created will
      belong to. For example, if <A>filt</A> is <Ref Filt="IsMutableDigraph"/>,
      then the digraph being created will be mutable, if <A>filt</A> is <Ref
      Filt="IsImmutableDigraph"/>, then the digraph will be immutable. 
      If the optional first argument <A>filt</A> is not present, then <Ref
        Filt="IsImmutableDigraph"/> is used by default.
      <Example><![CDATA[
gap> CompleteMultipartiteDigraph([5, 4, 2]);
<immutable complete multipartite digraph with 11 vertices, 76 edges>
gap> CompleteMultipartiteDigraph(IsMutableDigraph, [5, 4, 2]);
<mutable digraph with 11 vertices, 76 edges>
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="CompleteDigraph">
<ManSection>
  <Oper Name="CompleteDigraph" Arg="[filt, ]n"/>
  <Returns>A digraph.</Returns>
  <Description>
    If <A>n</A> is a non-negative integer, this function returns the complete
    digraph with <A>n</A> vertices. See <Ref Prop="IsCompleteDigraph"/>. <P/>

    If the optional first argument <A>filt</A> is present, then this should
    specify the category or representation the digraph being created will
    belong to. For example, if <A>filt</A> is <Ref Filt="IsMutableDigraph"/>,
    then the digraph being created will be mutable, if <A>filt</A> is <Ref
    Filt="IsImmutableDigraph"/>, then the digraph will be immutable. 
    If the optional first argument <A>filt</A> is not present, then <Ref
      Filt="IsImmutableDigraph"/> is used by default.
    <Example><![CDATA[
gap> CompleteDigraph(20);
<immutable complete digraph with 20 vertices>
gap> CompleteDigraph(IsMutableDigraph, 10);
<mutable digraph with 10 vertices, 90 edges>
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="ChainDigraph">
<ManSection>
  <Oper Name="ChainDigraph" Arg="[filt, ]n"/>
  <Returns>A digraph.</Returns>
  <Description>
    If <A>n</A> is a positive integer, this function returns a chain
    with <A>n</A> vertices and <C><A>n</A> - 1</C> edges.
    Specifically,
    for each vertex <C>i</C> (with <C>i</C> &lt; <C>n</C>), there is a directed
    edge with source <C>i</C> and range <C>i + 1</C>. <P/>

    If the optional first argument <A>filt</A> is present, then this should
    specify the category or representation the digraph being created will
    belong to. For example, if <A>filt</A> is <Ref Filt="IsMutableDigraph"/>,
    then the digraph being created will be mutable, if <A>filt</A> is <Ref
    Filt="IsImmutableDigraph"/>, then the digraph will be immutable. 
    If the optional first argument <A>filt</A> is not present, then <Ref
      Filt="IsImmutableDigraph"/> is used by default.<P/>

    The <Ref Oper="DigraphReflexiveTransitiveClosure"/> of a chain represents a
    total order.
    <Example><![CDATA[
gap> ChainDigraph(42);
<immutable chain digraph with 42 vertices>
gap> ChainDigraph(IsMutableDigraph, 10);
<mutable digraph with 10 vertices, 9 edges>
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="CycleDigraph">
<ManSection>
  <Oper Name="CycleDigraph" Arg="[filt, ]n"/>
  <Returns>A digraph.</Returns>
  <Description>
    If <A>n</A> is a positive integer, this function returns a <E>cycle</E>
    digraph with <A>n</A> vertices and <A>n</A> edges. Specifically,
    for each vertex <C>i</C> (with <C>i</C> &lt; <C>n</C>), there is a directed
    edge with source <C>i</C> and range <C>i + 1</C>. In addition, there is
    an edge with source <C>n</C> and range <C>1</C>. <P/>

    If the optional first argument <A>filt</A> is present, then this should
    specify the category or representation the digraph being created will
    belong to. For example, if <A>filt</A> is <Ref Filt="IsMutableDigraph"/>,
    then the digraph being created will be mutable, if <A>filt</A> is <Ref
    Filt="IsImmutableDigraph"/>, then the digraph will be immutable. 
    If the optional first argument <A>filt</A> is not present, then <Ref
    Filt="IsImmutableDigraph"/> is used by default.
  <Example><![CDATA[
gap> CycleDigraph(1);
<immutable digraph with 1 vertex, 1 edge>
gap> CycleDigraph(123);
<immutable cycle digraph with 123 vertices>
gap> CycleDigraph(IsMutableDigraph, 10);
<mutable digraph with 10 vertices, 10 edges>
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="JohnsonDigraph">
<ManSection>
  <Oper Name="JohnsonDigraph" Arg="[filt, ]n, k"/>
  <Returns>A digraph.</Returns>
  <Description>
    If <A>n</A> and <A>k</A> are non-negative integers, then this operation
    returns a symmetric digraph which corresponds to the undirected <E>Johnson
    graph</E> <M>J(n, k)</M>. <P/>

    If the optional first argument <A>filt</A> is present, then this should
    specify the category or representation the digraph being created will
    belong to. For example, if <A>filt</A> is <Ref Filt="IsMutableDigraph"/>,
    then the digraph being created will be mutable, if <A>filt</A> is <Ref
    Filt="IsImmutableDigraph"/>, then the digraph will be immutable. 
    If the optional first argument <A>filt</A> is not present, then <Ref
      Filt="IsImmutableDigraph"/> is used by default.<P/>

    The <E>Johnson graph</E> <M>J(n, k)</M> has vertices given by all the
    <A>k</A>-subsets of the range <C>[1 .. <A>n</A>]</C>, and two vertices are
      connected by an edge iff their intersection has size <M><A>k</A> - 1</M>.

    <Example><![CDATA[
gap> gr := JohnsonDigraph(3, 1);
<immutable symmetric digraph with 3 vertices, 6 edges>
gap> OutNeighbours(gr);
[ [ 2, 3 ], [ 1, 3 ], [ 1, 2 ] ]
gap> gr := JohnsonDigraph(4, 2);
<immutable symmetric digraph with 6 vertices, 24 edges>
gap> OutNeighbours(gr);
[ [ 2, 3, 4, 5 ], [ 1, 3, 4, 6 ], [ 1, 2, 5, 6 ], [ 1, 2, 5, 6 ], 
  [ 1, 3, 4, 6 ], [ 2, 3, 4, 5 ] ]
gap> JohnsonDigraph(1, 0);
<immutable empty digraph with 1 vertex>
gap> JohnsonDigraph(IsMutableDigraph, 1, 0);
<mutable empty digraph with 1 vertex>
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="PetersenGraph">
<ManSection>
  <Oper Name="PetersenGraph" Arg="[filt]"/>
  <Returns>A digraph.</Returns>
  <Description>

    From <URL>https://en.wikipedia.org/wiki/Petersen_graph</URL>:<P/>

    <Q>The Petersen graph is an undirected graph with 10 vertices and 15 edges.
    It is a small graph that serves as a useful example and counterexample for
    many problems in graph theory. The Petersen graph is named after Julius
    Petersen, who in 1898 constructed it to be the smallest bridgeless cubic
    graph with no three-edge-coloring.</Q><P/>
    
    If the optional first argument <A>filt</A> is present, then this should
    specify the category or representation the digraph being created will
    belong to. For example, if <A>filt</A> is <Ref Filt="IsMutableDigraph"/>,
    then the digraph being created will be mutable, if <A>filt</A> is <Ref
    Filt="IsImmutableDigraph"/>, then the digraph will be immutable. 
    If the optional first argument <A>filt</A> is not present, then <Ref
      Filt="IsImmutableDigraph"/> is used by default.<P/>

    See also <Ref Oper="GeneralisedPetersenGraph"/>.

<Example><![CDATA[
gap> ChromaticNumber(PetersenGraph());
3
gap> PetersenGraph(IsMutableDigraph);
<mutable digraph with 10 vertices, 30 edges>
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="GeneralisedPetersenGraph">
<ManSection>
  <Oper Name="GeneralisedPetersenGraph" Arg="[filt, ]n, k"/>
  <Returns>A digraph.</Returns>
  <Description>
    If <A>n</A> is a positive integer and <A>k</A> is a non-negative
    integer less than <C><A>n</A> / 2</C>, then this operation returns
    the <E>generalised Petersen graph</E> <M>GPG(<A>n</A>, k)</M>. <P/>

    From
    <URL>https://en.wikipedia.org/wiki/Generalized_Petersen_graph</URL>:
    <P/>

    <Q>The generalized Petersen graphs are a family of cubic
    graphs formed by connecting the vertices of a regular polygon to the
    corresponding vertices of a star polygon. They include the Petersen graph
    and generalize one of the ways of constructing the Petersen graph. The
    generalized Petersen graph family was introduced in 1950 by H. S. M.
    Coxeter and was given its name in 1969 by Mark Watkins.</Q>
    <P/>

    If the optional first argument <A>filt</A> is present, then this should
    specify the category or representation the digraph being created will
    belong to. For example, if <A>filt</A> is <Ref Filt="IsMutableDigraph"/>,
    then the digraph being created will be mutable, if <A>filt</A> is <Ref
    Filt="IsImmutableDigraph"/>, then the digraph will be immutable. 
    If the optional first argument <A>filt</A> is not present, then <Ref
      Filt="IsImmutableDigraph"/> is used by default.<P/>

    See also <Ref Oper="PetersenGraph"/>.

<Example><![CDATA[
gap> GeneralisedPetersenGraph(7, 2);
<immutable symmetric digraph with 14 vertices, 42 edges>
gap> GeneralisedPetersenGraph(40, 1);
<immutable symmetric digraph with 80 vertices, 240 edges>
gap> D := GeneralisedPetersenGraph(5, 2);
<immutable symmetric digraph with 10 vertices, 30 edges>
gap> IsIsomorphicDigraph(D, PetersenGraph());
true
gap> GeneralisedPetersenGraph(IsMutableDigraph, 9, 4);
<mutable digraph with 18 vertices, 54 edges>
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>
