weights.xml

#############################################################################
##
#W  weights.xml
#Y  Copyright (C) 2023                               Raiyan Chowdhury
##
##  Licensing information can be found in the README file of this package.
##
#############################################################################
##

<#GAPDoc Label="EdgeWeights">
    <ManSection>
    <Attr Name="EdgeWeights" Arg="digraph"/>
    <Oper Name="EdgeWeightsMutableCopy" Arg="digraph"/>
    <Returns>A list of lists of integers, floats or rationals.</Returns>
    <Description>
     <C>EdgeWeights</C> returns the list of lists of edge weights of
    the edges of the digraph <A>digraph</A>.<P/>

    More specifically, <C>weights[i][j]</C> is the weight given to the <C>j</C>th edge from vertex <C>i</C>, according to the ordering of edges given by <C>OutNeighbours(digraph)[i]</C>.<P/>

    The function <C>EdgeWeights</C> returns an immutable list of immutable
    lists, whereas the function <C>EdgeWeightsMutableCopy</C> returns a copy
    of <C>EdgeWeights</C> which is a mutable list of mutable lists.<P/>

    The edge weights of a digraph cannot be computed and must be set either
    using <C>SetEdgeWeights</C> or <Ref Func="EdgeWeightedDigraph" />.<P/>
    <Example><![CDATA[
gap> gr := EdgeWeightedDigraph([[2], [3], [1]], [[5], [10], [15]]);
<immutable edge-weighted digraph with 3 vertices, 3 edges>
gap> EdgeWeights(gr);
[ [ 5 ], [ 10 ], [ 15 ] ]
gap> a := EdgeWeightsMutableCopy(gr);
[ [ 5 ], [ 10 ], [ 15 ] ]
gap> a[1][1] := 100;
100
gap> a;
[ [ 100 ], [ 10 ], [ 15 ] ]
gap> b := EdgeWeights(gr);
[ [ 5 ], [ 10 ], [ 15 ] ]
gap> b[1][1] := 534;
Error, List Assignment: <list> must be a mutable list
]]></Example>
    </Description>
    </ManSection>
<#/GAPDoc>

<#GAPDoc Label="EdgeWeightedDigraph">
    <ManSection>
    <Func Name="EdgeWeightedDigraph" Arg="digraph, weights"/>
    <Returns>A digraph or <K>fail</K></Returns>
    <Description>
        The argument <A>digraph</A> may be a digraph or a list of lists of integers, floats or rationals.<P/>

        <A>weights</A> must be a list of lists of integers, floats or rationals
         of an equal size and shape to <C>OutNeighbours(digraph)</C>, otherwise it will fail.<P/>

        This will create a digraph and set the EdgeWeights to <A>weights</A>.<P/>

        See <Ref Attr="EdgeWeights"/>.
    <Example><![CDATA[
gap> g := EdgeWeightedDigraph(Digraph([[2], [1]]), [[5], [15]]);
<immutable edge-weighted digraph with 2 vertices, 2 edges>
gap> g := EdgeWeightedDigraph([[2], [1]], [[5], [15]]);
<immutable edge-weighted digraph with 2 vertices, 2 edges>
gap> EdgeWeights(g);
[ [ 5 ], [ 15 ] ]
]]></Example>
    </Description>
    </ManSection>
<#/GAPDoc>

<#GAPDoc Label="EdgeWeightedDigraphTotalWeight">
    <ManSection>
    <Attr Name="EdgeWeightedDigraphTotalWeight" Arg="digraph"/>
    <Returns>An integer, float or rational.</Returns>
    <Description>
        If <A>digraph</A> is a digraph with edge weights, then this attribute
        returns the sum of the weights of its edges.<P/>

        &MUTABLE_RECOMPUTED_ATTR;

        See <Ref Attr="EdgeWeights"/>.
    <Example><![CDATA[
gap> D := EdgeWeightedDigraph([[2], [1], [1, 2]],
>                             [[12], [5], [6, 9]]);
<immutable edge-weighted digraph with 3 vertices, 4 edges>
gap> EdgeWeightedDigraphTotalWeight(D);
32]]></Example>
    </Description>
    </ManSection>
<#/GAPDoc>

<#GAPDoc Label="EdgeWeightedDigraphMinimumSpanningTree">
    <ManSection>
    <Attr Name="EdgeWeightedDigraphMinimumSpanningTree" Arg="digraph"/>
    <Returns>A digraph.</Returns>
    <Description>
        If <A>digraph</A> is a connected digraph with edge weights, then this
        attribute returns a digraph which is a minimum spanning tree of
        <A>digraph</A>.<P/>

        A <E>spanning tree</E> of a digraph is a subdigraph with the same
        vertices but a subset of its edges that form an undirected tree.  It is
        <E>minimum</E> if it has the smallest possible total weight for a
        spanning tree of that digraph.<P/>

        &MUTABLE_RECOMPUTED_ATTR;

        See <Ref Attr="EdgeWeights"/>,
        <Ref Attr="EdgeWeightedDigraphTotalWeight"/> and
        <Ref Prop="IsConnectedDigraph"/>.
    <Example><![CDATA[
gap> D := EdgeWeightedDigraph([[2], [1], [1, 2]],
>                             [[12], [5], [6, 9]]);
<immutable edge-weighted digraph with 3 vertices, 4 edges>
gap> T := EdgeWeightedDigraphMinimumSpanningTree(D);
<immutable edge-weighted digraph with 3 vertices, 2 edges>
gap> EdgeWeights(T);
[ [  ], [ 5 ], [ 6 ] ]]]></Example>
    </Description>
    </ManSection>
<#/GAPDoc>

<#GAPDoc Label="EdgeWeightedDigraphShortestPaths">
<ManSection>
  <Attr Name="EdgeWeightedDigraphShortestPaths" Label="for a digraph" Arg="digraph"/>
  <Oper Name="EdgeWeightedDigraphShortestPaths" Label="for a digraph and a pos int" Arg="digraph, source"/>
  <Returns>A record.</Returns>
  <Description>
    If <A>digraph</A> is an edge-weighted digraph, this attribute returns a
    record describing the paths of lowest total weight (the <E>shortest
    paths</E>) connecting each pair of vertices.  If the optional argument
    <A>source</A> is specified and is a vertex of <A>digraph</A>, then the
    output will only contain information on paths originating from that
    vertex. <P/>

    In the two-argument form, the value returned is a record containing three
    components: <C>distances</C>, <C>parents</C> and <C>edges</C>.  Each of
    these is a list of integers with one entry for each vertex <C>v</C> as
    follows: <P/>
    <List>
      <Item>
        <C>distances[v]</C> is the total weight of the shortest path from
        <A>source</A> to <C>v</C>.
      </Item>
      <Item>
        <C>parents[v]</C> is the final vertex before <C>v</C> on the shortest
        path from <A>source</A> to <C>v</C>.
      </Item>
      <Item>
        <C>edges[v]</C> is the index of the edge of lowest weight going from
        <C>parents[v]</C> to <C>v</C>.
      </Item>
    </List>
    Using these three components together, you can find the shortest edge
    weighted path to all other vertices from a starting vertex. <P/>

    If no path exists from <A>source</A> to <C>v</C>, then <C>parents[v]</C> and
    <C>edges[v]</C> will both be <K>fail</K>.  The distance from <A>source</A>
    to itself is considered to be 0, and so both <C>parents[<A>source</A>]</C> and
    <C>edges[<A>source</A>]</C> are <K>fail</K>.
    Edge weights can have negative values, but there is currently no implemented
    method for this operation if a negative-weighted cycle exists. <P/>

    In the one-argument form, the value returned is also a record containing
    components <C>distances</C>, <C>parents</C> and <C>edges</C>, but each of
    these will instead be a list of lists in which the <C>i</C>th entry is the
    list that corresponds to paths starting at <C>i</C>. <P/>

    For a simple way of finding the shortest path between two specific vertices,
    see <Ref Oper="EdgeWeightedDigraphShortestPath"/>. See also the non-weighted
    operation <Ref Oper="DigraphShortestPath"/>. <P/>

    <Example><![CDATA[
gap> D := EdgeWeightedDigraph([[2, 3], [4], [4], []],
>                             [[5, 1], [6], [11], []]);
<immutable edge-weighted digraph with 4 vertices, 4 edges>
gap> EdgeWeightedDigraphShortestPaths(D, 1);
rec( distances := [ 0, 5, 1, 11 ], edges := [ fail, 1, 2, 1 ], 
  parents := [ fail, 1, 1, 2 ] )
gap> D := EdgeWeightedDigraph([[2], [3], [1]], [[1], [2], [3]]);
<immutable edge-weighted digraph with 3 vertices, 3 edges>
gap> EdgeWeightedDigraphShortestPaths(D);
rec( distances := [ [ 0, 1, 3 ], [ 5, 0, 2 ], [ 3, 4, 0 ] ], 
  edges := [ [ fail, 1, 1 ], [ 1, fail, 1 ], [ 1, 1, fail ] ], 
  parents := [ [ fail, 1, 1 ], [ 2, fail, 2 ], [ 3, 3, fail ] ] )]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="EdgeWeightedDigraphShortestPath">
<ManSection>
  <Oper Name="EdgeWeightedDigraphShortestPath" Arg="digraph, source, dest"/>
  <Returns>A pair of lists, or <K>fail</K>.</Returns>
  <Description>
    If <A>digraph</A> is an edge-weighted digraph with vertices <A>source</A>
    and <A>dest</A>, this operation returns a directed path from <A>source</A>
    to <A>dest</A> with the smallest possible total weight.  The output is a
    pair of lists <C>[v, a]</C> of the form described in <Ref
    Oper="DigraphPath"/>.<P/>

    If <M><A>source</A> = <A>dest</A></M> or no path exists, then <K>fail</K> is
    returned.<P/>

    If <A>digraph</A> contains a negative-weighted cycle, then there is
    currently no applicable method for this attribute. <P/>

    See <Ref Attr="EdgeWeightedDigraphShortestPaths" Label="for a digraph"/>.
    See also the non-weighted operation <Ref Oper="DigraphShortestPath"/>. <P/>
    <Example><![CDATA[
gap> D := EdgeWeightedDigraph([[2, 3], [4], [4], []],
>                             [[5, 1], [6], [11], []]);
<immutable edge-weighted digraph with 4 vertices, 4 edges>
gap> EdgeWeightedDigraphShortestPath(D, 1, 4);
[ [ 1, 2, 4 ], [ 1, 1 ] ]
gap> EdgeWeightedDigraphShortestPath(D, 3, 2);
fail]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="DigraphMaximumFlow">
<ManSection>
  <Attr Name="DigraphMaximumFlow" Arg="digraph, start, destination"/>
  <Returns>A list of lists of integers.</Returns>
  <Description>
    If <A>digraph</A> is an edge-weighted digraph with vertices <A>start</A> and
    <A>destination</A>, this returns a record representing the maximum flow from
    <A>start</A> to <A>destination</A> in the digraph. <P/>

    A <E>flow</E> is a function from the weighted edges of <A>digraph</A> to the
    positive real numbers, such that:
    <List>
      <Item>
        Each edge's flow is no more than its weight;
      </Item>
      <Item>
        For each vertex other than <A>start</A> and <A>destination</A>, the sum
        of flows for all incoming edges is equal to the sum of flows for all
        outgoing edges;
      </Item>
      <Item>
        The sum of flows of edges leaving <A>start</A> is equal to the sum of
        flows of edges entering <A>destination</A> (this sum is denoted
        <M>M</M>).
      </Item>
    </List>
    A <E>maximum flow</E> is a flow that maximises the value of <M>M</M>. <P/>

    The flow is represented as a list of lists where each entry is a number
    representing the flow on the edge in the corresponding position in
    <C>OutNeighbours(<A>digraph</A>)</C>.
    Note that the value <M>M</M> of the flow can be found with
    <C>Sum(DigraphMaximumFlow(<A>digraph</A>, <A>start</A>,
    <A>destination</A>)[<A>start</A>])</C>. <P/>

    This attribute is computed by an implementation of the push–relabel maximum
    flow algorithm, which has time complexity <M>O(v^2 e)</M> where <M>v</M> is
    the number of vertices of the digraph, and <M>e</M> is the number of
    edges. <P/>

    See <Ref Attr="EdgeWeights" Func="EdgeWeightedDigraph"/>.
    <Example><![CDATA[
gap> g := EdgeWeightedDigraph([[2, 2], [3], []], [[3, 2], [1], []]);
<immutable edge-weighted multidigraph with 3 vertices, 3 edges>
gap> flow := DigraphMaximumFlow(g, 1, 3);
[ [ 1, 0 ], [ 1 ], [  ] ]
gap> Sum(flow[1]);
1]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="DigraphEdgeConnectivity">
<ManSection>
  <Attr Name="DigraphEdgeConnectivity" Arg="digraph"/>
  <Returns>An integer</Returns>
  <Description>
    This function returns the edge connectivity of <A>digraph</A>, a symmetric digraph.<P/> Edge Connectivity refers to the size of a minimum cut of the graph, 
    which, for digraphs, refers to set of edges needed to be removed to ensure the graph is no longer Strongly Connected. That is, there exists two 
    vertices, <A>A</A> and <A>B</A>, for which a path from <A>A</A> to <A>B</A> does not exist.

    It makes use of the <C>DigraphMaximumFlow(<A>digraph</A>)</C> function, by constructing an edge-weighted Digraph
    with edge weights of 1, then using the Max-flow min-cut theorem to determine the size of the minimum cut.<P/>
    See also <Ref Attr="DigraphMaximumFlow"/>.
    <Example><![CDATA[
gap> d := Digraph([[4], [4], [4], [1, 2, 3]]);;
gap> DigraphEdgeConnectivity(d);  
1
gap> D := RandomDigraph(1);;
gap> DigraphEdgeConnectivity(D);
0
gap> d := Digraph([[2, 3], [1, 4], [1, 4], [2, 3]]);;
gap> DigraphEdgeConnectivity(d);
2]]></Example>
<#GAPDoc Label="DigraphMinimumCut">
<ManSection>
  <Attr Name="DigraphMinimumCut" Arg="digraph, s, t"/>
  <Returns>A list of lists of integers.</Returns>
  <Description>
    If <A>digraph</A> is an edge-weighted digraph with distinct vertices <A>s</A>
    and <A>t</A>, this function returns a list of two lists representing the
    components of the minimum <M>s</M>-<M>t</M> cut of <A>digraph</A>. <P/>

    An <E><M>s</M>-<M>t</M> cut</E> is a partition of the vertices <M>\{ S, T \}</M>
    such that <A>s</A> is in <M>S</M> and <A>t</A> is in <M>T</M>. The <E>capacity</E>
    of an <M>s</M>-<M>t</M> cut is the sum of the weights of every edge whose source
    is in <M>S</M> and whose range is in <M>T</M>. The minimum <M>s</M>-<M>t</M> cut is
    the <M>s</M>-<M>t</M> cut whose capacity is the smallest possible.<P/>

    This attribute is computed by using <Ref Func="DigraphMaximumFlow"/> and the
    max-cut min-flow theorem.<P/>

    See <Ref Attr="EdgeWeights" Func="EdgeWeightedDigraph"/>.
    <Example><![CDATA[
gap> g := EdgeWeightedDigraph([[2, 2], [3], []], [[3, 2], [1], []]);
<immutable edge-weighted multidigraph with 3 vertices, 3 edges>
gap> DigraphMinimumCut(g, 1, 3);
[ [ 1, 2 ], [3] ]
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="DigraphMinimumCutSet">
<ManSection>
  <Attr Name="DigraphMinimumCutSet" Arg="digraph, s, t"/>
  <Returns>A list of lists integers.</Returns>
  <Description>
    If <A>digraph</A> is an edge-weighted digraph with distinct vertices <A>s</A>
    and <A>t</A>, this function returns a list of lists of integers representing the
    minimum <M>s</M>-<M>t</M> cut of <A>digraph</A>. <P/>

    An <E><M>s</M>-<M>t</M> cut</E> is a partition of the vertices <M>\{ S, T \}</M>
    such that <A>s</A> is in <M>S</M> and <A>t</A> is in <M>T</M>. The <E>cut set</E>
    corresponding to this cut is the set of edges whose source is in <M>S</M> and
    whose range is in <M>T</M>. The minimum <M>s</M>-<M>t</M> cut set is
    the <M>s</M>-<M>t</M> cut set such that the sum of the weights of the edges in
    the cut set is the smallest possible.<P/>

    This attribute is computed by using <Ref Func="DigraphMinimumCut"/>.<P/>

    See <Ref Attr="EdgeWeights" Func="EdgeWeightedDigraph"/>.
    <Example><![CDATA[
gap> g := EdgeWeightedDigraph([[2, 2], [3], []], [[3, 2], [1], []]);
<immutable edge-weighted multidigraph with 3 vertices, 3 edges>
gap> DigraphMinimumCutSet(g, 1, 3);
[ [ 2, 3 ] ]
]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="RandomUniqueEdgeWeightedDigraph">
<ManSection>
  <Oper Name="RandomUniqueEdgeWeightedDigraph" Arg="[filt, ]n[, p]"/>
  <Returns>An edge-weighted digraph.</Returns>
  <Description>
    This operation returns a random edge-weighted digraph.<P/>

    Its behaviour is the same as that of <Ref Oper="RandomDigraph"/> but the
    returned digraph will additionally have the <Ref Attr="EdgeWeights"/>
    attribute populated with random unique weights from the set
    <C>[1 .. m]</C> where <C>m</C> is the number of edges in the digraph.<P/>

    &STANDARD_FILT_TEXT;

    If <A>n</A> is a non-negative integer, then the returned digraph will have
    <A>n</A> vertices.  If the optional second argument <A>p</A> is a float with
    value <M>0 \leq </M> <A> p </A> <M> \leq 1</M>, then an edge will exist
    between each pair of vertices with probability approximately <A>p</A>.  If
    <A>p</A> is not specified, then a random probability will be assumed (chosen
    with uniform probability).<P/>

    For more information on the arguments and behaviour of this operation, see
    <Ref Oper="RandomDigraph"/>.

    <Log><![CDATA[
gap> RandomUniqueEdgeWeightedDigraph(5);
<immutable edge-weighted digraph with 5 vertices, 21 edges>
gap> RandomUniqueEdgeWeightedDigraph(5, 1 / 2);
<immutable edge-weighted digraph with 5 vertices, 14 edges>
gap> RandomUniqueEdgeWeightedDigraph(IsEulerianDigraph, 5, 1 / 3);
<immutable edge-weighted digraph with 5 vertices, 6 edges>]]></Log>
  </Description>
</ManSection>
<#/GAPDoc>

<#GAPDoc Label="DotEdgeWeightedDigraph">
<ManSection>
  <Oper Name="DotEdgeWeightedDigraph" Arg="digraph[, path][, colors]"/>
  <Returns>A string.</Returns>
  <Description>
    This operation produces a graphical representation of the edge-weighted
    digraph <A>digraph</A>, in <E>dot</E> format. Its output will be similar to
    that of <Ref Attr="DotDigraph"/>, but the diagram will also show the weights
    of the digraph's edges. <P/>

    If the optional argument <A>path</A> is specified, it should be a list of
    lists describing a path in <A>digraph</A>, in the format described in <Ref
    Oper="DigraphPath"/>. If specified, the path's edges will be highlighted in
    the diagram, as will its start and end vertices. <P/>

    If the optional argument <A>colors</A> is specified, it should be a record
    containing any of the following components:

    <List>
      <Item>
        <A>vert</A>: the colour of ordinary vertices (default "grey");
      </Item>
      <Item>
        <A>edge</A>: the colour of ordinary edges (default "black");
      </Item>
      <Item>
        <A>highlight</A>: the colour of any edges on <A>path</A>, if any
        (default "blue");
      </Item>
      <Item>
        <A>source</A>: the colour of the first vertex in <A>path</A>, if any
        (default "yellowgreen");
      </Item>
      <Item>
        <A>dest</A>: the colour of the final vertex in <A>path</A>, if any
        (default "lightpink").
      </Item>
    </List>

    Each value in the record should be a string representing a colour understood
    by the <C>GraphViz</C> software. For details about this format, see
    <URL>https://www.graphviz.org</URL>. If any of the above components are not
    specified, or if no <A>colors</A> argument is given, the default value will
    be used. <P/>

    The output of this operation can be passed to <Ref Func="Splash"/> to
    attempt to display it graphically on the computer's screen. <P/>

    <Example><![CDATA[
gap> gr := EdgeWeightedDigraph([[2], [3], []], [[10], [15], []]);
<immutable edge-weighted digraph with 3 vertices, 2 edges>
gap> path := EdgeWeightedDigraphShortestPath(g, 2, 3);
[ [ 2, 3 ], [ 1 ] ]
gap> Print(DotEdgeWeightedDigraph(gr, path));
//dot
digraph hgn{
node [shape=circle]
1[color=gray, style=filled]
2[color=yellowgreen, style=filled]
3[color=lightpink, style=filled]
1 -> 2[color=black, label=10]
2 -> 3[color=blue, label=15]
}]]></Example>
  </Description>
</ManSection>
<#/GAPDoc>