#############################################################################
##
#W  constructors.xml
#Y  Copyright (C) 2019                                  James D. Mitchell
##                                                      Wilf A. Wilson
##
##  Licensing information can be found in the README file of this package.
##
#############################################################################
##

<#GAPDoc Label="LineDigraph">
<ManSection>
  <Oper Name="LineDigraph" Arg="digraph"/>
  <Oper Name="EdgeDigraph" Arg="digraph"/>
  <Returns>A digraph.</Returns>
  <Description>
    Given a digraph <A>digraph</A>, the operation returns the digraph
    obtained by associating a vertex with each edge of <A>digraph</A>, and
    creating an edge from a vertex <K>v</K> to a vertex <K>u</K> if and only
    if the terminal vertex of the edge associated with <K>v</K> is the start
    vertex of the edge associated with <K>u</K>.<P/>

    Note that the returned digraph is always a new immutable digraph, and the
    argument <A>digraph</A> is never modified.
    <Example><![CDATA[
gap> LineDigraph(CompleteDigraph(3));
<immutable digraph with 6 vertices, 12 edges>
gap> LineDigraph(ChainDigraph(3));
<immutable digraph with 2 vertices, 1 edge>
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="LineUndirectedDigraph">
<ManSection>
  <Oper Name="LineUndirectedDigraph" Arg="digraph"/>
  <Oper Name="EdgeUndirectedDigraph" Arg="digraph"/>
  <Returns>A digraph.</Returns>
  <Description>
    Given a symmetric digraph <A>digraph</A>, the operation returns the
    symmetric digraph obtained by associating a vertex with each edge of
    <A>digraph</A>, ignoring directions and multiplicites, and adding an edge
    between two vertices if and only if the corresponding edges have a vertex in
    common.<P/>

    Note that the returned digraph is always a new immutable digraph, and the
    argument <A>digraph</A> is never modified.
    <Example><![CDATA[
gap> LineUndirectedDigraph(CompleteDigraph(3));
<immutable digraph with 3 vertices, 6 edges>
gap> LineUndirectedDigraph(DigraphSymmetricClosure(ChainDigraph(3)));
<immutable digraph with 2 vertices, 2 edges>
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="BipartiteDoubleDigraph">
<ManSection>
  <Oper Name="BipartiteDoubleDigraph" Arg="digraph"/>
  <Returns>A digraph.</Returns>
  <Description>
    Let <A>digraph</A> be a digraph with vertex set <C>V</C>. This function
    returns the bipartite double digraph of <A>digraph</A>. The vertex set of
    the double digraph is the original vertex set together with a duplicate. The
    edges are <C>[u_1, v_2]</C> and <C>[u_2, v_1]</C> if and only if <C>[u,
      v]</C> is an edge in <A>digraph</A>. The resulting graph is bipartite,
    since the orignal edges are not included in the resulting digraph.<P/>

    If <A>digraph</A> is mutable, then <A>digraph</A> is modified in-place. If
    <A>digraph</A> is immutable, then a new immutable digraph constructed as
    described above is returned.
    <Example><![CDATA[
gap> gamma := Digraph([[2], [3], [1]]);
<immutable digraph with 3 vertices, 3 edges>
gap> BipartiteDoubleDigraph(gamma);
<immutable digraph with 6 vertices, 6 edges>
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="DoubleDigraph">
<ManSection>
  <Oper Name="DoubleDigraph" Arg="digraph"/>
  <Returns>A digraph.</Returns>
  <Description>
    Let <A>digraph</A> be a digraph with vertex set <C>V</C>. This function
    returns the double digraph of <A>digraph</A>. The vertex set of the double
    digraph is the orginal vertex set together with a duplicate. The edges are
    <C>[u_1, v_2]</C> and <C>[u_2, v_1]</C> if and only if <C>[u, v]</C> is an
    edge in <A>digraph</A>, together with the original edges and their
    duplicates.<P/>

    If <A>digraph</A> is mutable, then <A>digraph</A> is modified in-place. If
    <A>digraph</A> is immutable, then a new immutable digraph constructed as
    described above is returned.
    <Example><![CDATA[
gap> gamma := Digraph([[2], [3], [1]]);
<immutable digraph with 3 vertices, 3 edges>
gap> DoubleDigraph(gamma);
<immutable digraph with 6 vertices, 12 edges>
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="DistanceDigraph">
<ManSection>
  <Oper Name="DistanceDigraph" Arg="digraph, i"
        Label="for digraph and int"/>
  <Oper Name="DistanceDigraph" Arg="digraph, list"
        Label="for digraph and list"/>
  <Returns>A digraph.</Returns>
  <Description>
    The first argument is a digraph, the second argument is a non-negative
    integer or a list of positive integers. This operation returns a digraph on
    the same set of vertices as <A>digraph</A>, with two vertices being adjacent
    if and only if the distance between them in <A>digraph</A> equals <A>i</A>
    or is a number in <A>list</A>.  See <Ref Oper="DigraphShortestDistance"
    Label="for a digraph and two vertices"/>. <P/>

    If <A>digraph</A> is mutable, then <A>digraph</A> is modified in-place. If
    <A>digraph</A> is immutable, then a new immutable digraph constructed as
    described above is returned.
    <Example><![CDATA[
gap> digraph := DigraphFromSparse6String(
> ":]n?AL`BC_DEbEF`GIaGHdIJeGKcKL_@McDHfILaBJfHMjKM");
<immutable symmetric digraph with 30 vertices, 90 edges>
gap> DistanceDigraph(digraph, 1);
<immutable digraph with 30 vertices, 90 edges>
gap> DistanceDigraph(digraph, [1, 2]);
<immutable digraph with 30 vertices, 270 edges>
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>
