Merge branch 'master' into banana

.codecov.yml

@@ -2,14 +2,22 @@ coverage:
   precision: 2      # Report coverage to 2 decimal places
   round: down       # Round down
   range: "90...100" # Anything below 90% is coloured red (considered bad)
-  status:           # Various customisations that it seems should be off
-    project: off
-    patch: off
-    changes: off
 
-comment:
-  layout: "header, diff, changes, tree"
-  behavior: default
+  status: # GitHub status checks to add to a PR
+    project: # Check all of Digraphs
+      default:
+        informational: true # Don't fail the check if overall coverage decreases
+    patch: # Check only the PR's diff
+      default:
+        target: 100
+        threshold: 0
+        informational: false # Do fail the check if the diff is not 100% covered
+    changes: # Information about changes in coverage outside the diff
+      default:
+        informational: true # Don't fail the check
+
+# Comment to post on PRs
+comment: false
 
 ignore:
  - "extern/"

.github/workflows/ci.yml → .github/workflows/gap.yml

@@ -1,32 +1,12 @@
-name: "CI"
-
-# Trigger the workflow on push or pull request
-on:
-  pull_request:
-  push:
-    branches-ignore:
-      - rc-v[0-9]+.[0-9]+.[0-9]+
+name: "Digraphs tests"
+on: [push, pull_request]
 
 jobs:
-  lint:
-    name: "lint"
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-        name: "Check out the repository"
-      - uses: actions/setup-python@v1
-        name: "Set up Python"
-      - uses: BSFishy/pip-action@v1
-        name: "Install gaplint and cpplint with pip"
-        with:
-          packages: |
-            gaplint
-            cpplint
-      - name: "Run gaplint + cpplint"
-        run: bash etc/lint.sh
   test:
     name: "GAP ${{ matrix.gap-branch }}"
     runs-on: ubuntu-latest
+    # Don't run this twice for PRs from branches in the same repository
+    if: ${{ !(github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository) }}
     strategy:
       fail-fast: false
       matrix:
@@ -43,6 +23,7 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - uses: gap-actions/setup-gap-for-packages@v1
+        name: "Install GAP and clone/compile necessary packages"
         with:
           GAP_PKGS_TO_CLONE: "${{ matrix.pkgs-to-clone }}"
           GAP_PKGS_TO_BUILD: "io orb profiling grape NautyTracesInterface datastructures"
@@ -52,3 +33,4 @@ jobs:
              && curl --retry 5 -L -O "https://digraphs.github.io/Digraphs/${DIGRAPHS_LIB}.tar.gz"
              && tar xf "${DIGRAPHS_LIB}.tar.gz"
       - uses: gap-actions/run-test-for-packages@v1
+        name: "Run tst/testall.g"

.github/workflows/lint.yml

@@ -0,0 +1,25 @@
+name: "linting"
+on: [push, pull_request]
+
+jobs:
+  lint:
+    name: "${{ matrix.linter }}"
+    runs-on: ubuntu-latest
+    # Don't run this twice for PRs from branches in the same repository
+    if: ${{ !(github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository) }}
+    strategy:
+      fail-fast: false
+      matrix:
+        linter:
+          - gaplint
+          - cpplint
+    steps:
+    - name: "Check out the repository"
+      uses: actions/checkout@v2
+    - name: "Set up Python"
+      uses: actions/setup-python@v1
+    - name: "Install ${{ matrix.linter }} with pip"
+      run: pip install ${{ matrix.linter }}
+    - name: "Run ${{ matrix.linter }} on the Digraphs package"
+      run: bash etc/${{ matrix.linter }}.sh
+

Makefile.am

@@ -124,7 +124,8 @@ doc/manual.six: doc/*.xml PackageInfo.g
 	($(GAPROOT)/bin/gap.sh -A makedoc.g)
 
 lint:
-	etc/lint.sh
+	etc/gaplint.sh
+	etc/cpplint.sh
 
 format:
 	clang-format -i src/*.[hc]

PackageInfo.g

@@ -42,6 +42,16 @@ SourceRepository := rec(
 Persons := [
 
   rec(
+    LastName      := "Anagnostopoulou-Merkouri",
+    FirstNames    := "Marina",
+    IsAuthor      := false,
+    IsMaintainer  := false,
+    Email         := "mam49@st-andrews.ac.uk",
+    PostalAddress := _STANDREWSMATHS,
+    Place         := "St Andrews",
+    Institution   := "University of St Andrews"),
+
+ rec(
     LastName      := "De Beule",
     FirstNames    := "Jan",
     IsAuthor      := true,
@@ -89,6 +99,16 @@ Persons := [
     Place         := "St Andrews",
     Institution   := "University of St Andrews"),
 
+rec(
+    LastName      := "Harper",
+    FirstNames    := "Samantha",
+    IsAuthor      := false,
+    IsMaintainer  := false,
+    Email         := "seh25@st-andrews.ac.uk",
+    PostalAddress := _STANDREWSMATHS,
+    Place         := "St Andrews",
+    Institution   := "University of St Andrews"),
+
   rec(
     LastName      := "Horn",
     FirstNames    := "Max",

README.md

@@ -85,12 +85,27 @@ If you installed GAP on several architectures, then you must execute the
 configure/make step for each of the architectures. You can either do this
 immediately after configuring and compiling GAP itself on this architecture, or
 alternatively set the environment variable `CONFIGNAME` to the name of the
-configuration you used when compiling GAPbefore running `./configure`.  Note
+configuration you used when compiling GAP before running `./configure`.  Note
 however that your compiler choice and flags (environment variables `CC` and
 `CFLAGS`) need to be chosen to match the setup of the original GAP compilation.
 For example, you have to specify 32-bit or 64-bit mode correctly!
 
-Digraphs vendors `bliss` and `planarity` libraries in the `extern` directory.
+### Configuration options
+
+In addition to the usual autoconf generated configuration flags, the following
+flags are provided.
+
+Option                        | Meaning
+----------------------------- | ------------------------------------------------
+--enable-code-coverage        | enable code coverage support
+--enable-compile-warnings     | enable compiler warnings
+--enable-debug                | enable debug mode
+--with-external-bliss         | use external `bliss`
+--with-external-planarity     | use external `planarity`
+--with-gaproot                | specify root of GAP installation
+--without-intrinsics          | do not use compiler intrinsics even if available
+
+Digraphs vendors the `bliss` and `planarity` libraries in the `extern` directory.
 If you wish to use your system copy of `bliss` or `planarity`, please use the
 configure options `--with-external-bliss` or `--with-external-planarity`, as
 appropriate.

doc/attr.xml

@@ -83,7 +83,7 @@ gap> DigraphNrVertices(D);
     <P/>
 
     The entries of <C>DigraphEdges(</C><A>digraph</A><C>)</C> are in one-to-one
-    corresponence with the edges of <A>digraph</A>.  Hence
+    correspondence with the edges of <A>digraph</A>.  Hence
     <C>DigraphEdges(</C><A>digraph</A><C>)</C> is duplicate-free if and only if
     <A>digraph</A> contains no multiple edges. <P/>
 
@@ -1956,7 +1956,7 @@ gap> D;
     and the reverse edge <C>[j,i]</C> is an edge of <A>digraph</A>.
     In other words, for every
     symmetric pair of edges <C>[i,j]</C> and <C>[j,i]</C> in <A>digraph</A>, where 
-    <C>i</C> and <C>j</C> are distinct, it discards the the edge
+    <C>i</C> and <C>j</C> are distinct, it discards the edge
     <M>[\max(i,j),\min(i,j)]</M>.
     <P/>
 

doc/cliques.xml

@@ -147,7 +147,7 @@ true]]></Example>
         <C>DigraphMaximalClique</C> greedily enlarge the clique <A>include</A>
         until it cannot continue.  The result is guaranteed to be a maximal
         clique. This may or may not return an answer more quickly than using
-        <Ref Func="DigraphMaximalCliques"/>.  with a limit of 1.
+        <Ref Func="DigraphMaximalCliques"/> with a limit of 1.
       </Item>
       <Mark>Three arguments</Mark>
       <Item>
@@ -348,7 +348,7 @@ gap> DigraphMaximalCliques(D);
         independent set <A>include</A> until it cannot continue.  The result
         is guaranteed to be a maximal independent set. This may or may not
         return an answer more quickly than using <Ref
-          Func="DigraphMaximalIndependentSets"/>.  with a limit of 1.
+          Func="DigraphMaximalIndependentSets"/> with a limit of 1.
       </Item>
       <Mark>Three arguments</Mark>
       <Item>

doc/digraph.xml

@@ -205,7 +205,7 @@
       <Mark>for a binary relation</Mark>
       <Item>
         if <A>obj</A> is a binary relation on the points <C>[1 .. n]</C> for
-        some posititve integer <M>n</M>, then this function returns the digraph
+        some positive integer <M>n</M>, then this function returns the digraph
         defined by <A>obj</A>. Specifically, this function returns a digraph
         which has <M>n</M> vertices, and which has an edge with source <C>i</C>
         and range <C>j</C> if and only if <C>[i,j]</C> is a pair in

doc/digraphs.bib

@@ -99,6 +99,19 @@ @inproceedings{JK07
   Year = {2007},
 }
 
+@article{LT79,
+  Author = {Thomas Lengauer and Robert E. Tarjan},
+  Doi = {https://doi.org/10.1145/357062.357071},
+  Journal = {ACM Transactions on Programming Languages and Systems},
+  Number = {1},
+  Pages = {121--141},
+  Title = {A Fast Algorithm for Finding Dominators in a Flowgraph},
+  Url = {https://doi.org/10.1145/357062.357071},
+  Volume = {1},
+  Year = {1979},
+  Bdsk-Url-1 = {https://www.cs.princeton.edu/courses/archive/spr03/cs423/download/dominators.pdf}
+}
+
 @article{MP14,
   Author = {Brendan D. McKay and Adolfo Piperno},
   Doi = {https://dx.doi.org/10.1016/j.jsc.2013.09.003},

doc/labels.xml

@@ -24,8 +24,8 @@
     <A>i</A>. <P/>
 
     If <A>digraph</A> is a digraph created from a record with a component
-    <C>vertices</C>, then the labels of the vertices are set to the value of
-    this component.<P/>
+    <C>DigraphVertices</C>, then the labels of the vertices are set to
+    the value of this component.<P/>
 
     Induced subdigraphs, and some other operations which create new digraphs from
     old ones, inherit their labels from their parents.
@@ -71,15 +71,23 @@ gap> DigraphVertexLabel(D, 1);
     copy of the labels of the vertices in <A>digraph</A>.
     <C>SetDigraphVertexLabels</C> can be used to set the labels of the vertices
     in <A>digraph</A> to the list of
-    arbitrary &GAP; objects <A>list</A>. <P/>
+    arbitrary &GAP; objects <A>list</A>, which must be of the same length
+    as the number of vertices of <A>digraph</A>. <P/>
+
+    If the list <A>list</A> is immutable, then the vertex labels are set to a
+    mutable copy of <A>list</A>. Otherwise, the labels are set to exactly
+    <A>list</A>. <P/>
 
     The label of a vertex can be changed an arbitrary number of times. If no
     label has been set for the vertex <A>i</A>, then the default value is
     <A>i</A>. <P/>
 
     If <A>digraph</A> is a digraph created from a record with a component
-    <C>vertices</C>, then the labels of the vertices are set to the value of
-    this component.<P/>
+    <C>DigraphVertices</C>, then the labels of the vertices are set to the
+    value of this component. As in the above, if the component is immutable
+    then the digraph's vertex labels are set to a mutable copy of
+    <C>DigraphVertices</C>. Otherwise, they are set to exactly
+    <C>DigraphVertices</C>. <P/>
 
     Induced subdigraphs, and other operations which create new digraphs from
     old ones, inherit their labels from their parents.

doc/oper.xml

@@ -1668,6 +1668,92 @@ gap> DigraphShortestDistance(D, [1, 3], [3, 5]);
 </ManSection>
 <#/GAPDoc>
 
+<#GAPDoc Label="Dominators">
+<ManSection>
+  <Oper Name="Dominators" Arg="digraph, root"/>
+  <Returns>A list of lists.</Returns>
+    <Description>
+    <C>Dominators</C> takes a <A>digraph</A> and a root <A>root</A> and returns
+    the dominators of each vertex with respect to the root. The output is
+    returned as a list of length <C>DigraphNrVertices(<A>Digraph</A>)</C>,
+    whose <A>i</A>th entry is a list with the dominators of vertex <A>i</A> of
+    the <A>digraph</A>. If there is no path from the root to a specific vertex,
+    the output will contain a hole in the corresponding position. The
+    <E>dominators</E> of a vertex <M>u</M> are the vertices that are
+    contained in every path from the <M>root</M> to <M>u</M>, not including
+    <M>u</M> itself.
+
+    The method for this operation is an implementation of an algorithm by
+    Thomas Lengauer and Robert Endre Tarjan <Cite Key="LT79"/>. The complexity
+    of this algorithm is <M>O(mlog n)</M> where <M>m</M> is the number of edges
+    and <M>n</M> is the number of nodes in the subdigraph induced by the nodes
+    in <A>digraph</A> reachable from <A>root</A>.
+    <Example><![CDATA[
+gap> D := Digraph([[2], [3, 6], [2, 4], [1], [], [3]]);
+<immutable digraph with 6 vertices, 7 edges>
+gap> Dominators(D, 1);
+[ , [ 1 ], [ 2, 1 ], [ 3, 2, 1 ],, [ 2, 1 ] ]
+gap> Dominators(D, 2);
+[ [ 4, 3, 2 ],, [ 2 ], [ 3, 2 ],, [ 2 ] ]
+gap> Dominators(D, 3);
+[ [ 4, 3 ], [ 3 ],, [ 3 ],, [ 2, 3 ] ]
+gap> Dominators(D, 4);
+[ [ 4 ], [ 1, 4 ], [ 2, 1, 4 ],,, [ 2, 1, 4 ] ]
+gap> Dominators(D, 5);
+[  ]
+gap> Dominators(D, 6);
+[ [ 4, 3, 6 ], [ 3, 6 ], [ 6 ], [ 3, 6 ] ]
+]]></Example>
+  </Description>
+</ManSection>
+<#/GAPDoc>
+
+<#GAPDoc Label="DominatorTree">
+<ManSection>
+  <Oper Name="DominatorTree" Arg="digraph, root"/>
+  <Returns>A record.</Returns>
+  <Description>
+    <C>DominatorTree</C> takes a <A>digraph</A> and a
+    <A>root</A> vertex and returns a record with the following components: 
+    <List>
+      <Mark>idom</Mark>
+      <Item>
+        the immediate dominators of the vertices with respect
+        to the root.
+      </Item>
+      <Mark>preorder</Mark>
+      <Item>
+        the preorder values of the vertices defined by the depth first search
+        executed on the digraph.
+      </Item>
+    </List>
+    The <E>immediate dominator</E> of a vertex <M>u</M> is the unique dominator
+    of <M>u</M> that is dominated by all other dominators of <M>u</M>. The
+    algorithm is an implementation of the fast algorithm written by Thomas
+    Lengauer and Robert Endre Tarjan <Cite Key="LT79"/>.  The complexity of
+    this algorithm is <M>O(mlog n)</M> where <M>m</M> is the number of edges
+    and <M>n</M> is the number of nodes in the subdigraph induced by the nodes
+    in <A>digraph</A> reachable from <A>root</A>.
+  <Example><![CDATA[
+gap> D := Digraph([[2, 3], [4, 6], [4, 5], [3, 5], [1, 6], [2, 3]]);
+<immutable digraph with 6 vertices, 12 edges>
+gap> DominatorTree(D, 1);
+rec( idom := [ fail, 1, 1, 1, 1, 1 ], 
+  preorder := [ 1, 2, 4, 3, 5, 6 ] )
+gap> DominatorTree(D, 5);
+rec( idom := [ 5, 5, 5, 5, fail, 5 ], 
+  preorder := [ 5, 1, 2, 4, 3, 6 ] )
+gap> D := CompleteDigraph(5);
+<immutable complete digraph with 5 vertices>
+gap> DominatorTree(D, 1);
+rec( idom := [ fail, 1, 1, 1, 1 ], preorder := [ 1, 2, 3, 4, 5 ] )
+gap> DominatorTree(D, 2);
+rec( idom := [ 2, fail, 2, 2, 2 ], preorder := [ 2, 1, 3, 4, 5 ] )
+]]></Example>
+  </Description>
+</ManSection>
+<#/GAPDoc>
+
 <#GAPDoc Label="PartialOrderDigraphMeetOfVertices">
 <ManSection>
   <Oper Name="PartialOrderDigraphMeetOfVertices"