From 6251e9f0d969daf321367a1f0aaac8831ddcdf3c Mon Sep 17 00:00:00 2001 From: William-Kenyon <115789274+William-Kenyon@users.noreply.github.com> Date: Wed, 14 Oct 2026 22:06:51 +0100 Subject: [PATCH 1/7] Rename DigraphDijkstra to DigraphShortestPaths --- doc/oper.xml | 22 +++++++++++----------- doc/z-chap4.xml | 1 + gap/oper.gd | 4 ++-- gap/oper.gi | 6 +++--- 4 files changed, 17 insertions(+), 16 deletions(-) diff --git a/doc/oper.xml b/doc/oper.xml index 9213ec1b4..5c5982d06 100644 --- a/doc/oper.xml +++ b/doc/oper.xml @@ -2247,15 +2247,15 @@ false]]> <#/GAPDoc> -<#GAPDoc Label="DigraphDijkstra"> +<#GAPDoc Label="DigraphShortestPaths"> - - + Two lists. If digraph is a digraph and source and target are - vertices of digraph, then DigraphDijkstra calculates the + vertices of digraph, then DigraphShortestPaths calculates the length of the shortest path from source to target and returns two lists. Each element of the first list is the distance of the corresponding element from source. If a vertex was not visited in @@ -2265,22 +2265,22 @@ false]]> second list gives the previous vertex in the shortest path from source to the corresponding vertex. For source and for any vertices that remained unvisited this - will be -1.

+ will be -1.

- If the optional second argument target is not present, then - DigraphDijkstra returns the shortest path from source to - every vertex that is reachable from source. + If the optional second argument target is not present, then + DigraphShortestPaths returns the shortest path from source to + every vertex that is reachable from source. mat := [[0, 1, 1], [0, 0, 1], [0, 0, 0]]; [ [ 0, 1, 1 ], [ 0, 0, 1 ], [ 0, 0, 0 ] ] gap> D := DigraphByAdjacencyMatrix(mat); -gap> DigraphDijkstra(D, 2, 3); +gap> DigraphShortestPaths(D, 2, 3); [ [ infinity, 0, 1 ], [ -1, -1, 2 ] ] -gap> DigraphDijkstra(D, 1, 3); +gap> DigraphShortestPaths(D, 1, 3); [ [ 0, 1, 1 ], [ -1, 1, 1 ] ] -gap> DigraphDijkstra(D, 1, 2); +gap> DigraphShortestPaths(D, 1, 2); [ [ 0, 1, 1 ], [ -1, 1, 1 ] ] ]]> diff --git a/doc/z-chap4.xml b/doc/z-chap4.xml index 4c1ac9304..dcd446926 100644 --- a/doc/z-chap4.xml +++ b/doc/z-chap4.xml @@ -91,6 +91,7 @@ <#Include Label="DigraphDegeneracyOrdering"> <#Include Label="HamiltonianPath"> <#Include Label="NrSpanningTrees"> + <#Include Label="DigraphShortestPaths"> <#Include Label="DigraphDijkstra"> <#Include Label="DigraphVertexConnectivity"> <#Include Label="DigraphEdgeConnectivity"> diff --git a/gap/oper.gd b/gap/oper.gd index ce77dc770..6c3a23bdb 100644 --- a/gap/oper.gd +++ b/gap/oper.gd @@ -129,9 +129,9 @@ DeclareOperation("DigraphKings", [IsDigraph, IsPosInt]); DeclareOperation("DigraphFloydWarshall", [IsDigraph, IsFunction, IsObject, IsObject]); -DeclareOperation("DigraphDijkstra", +DeclareOperation("DigraphShortestPaths", [IsDigraph, IsPosInt]); -DeclareOperation("DigraphDijkstra", +DeclareOperation("DigraphShortestPaths", [IsDigraph, IsPosInt, IsPosInt]); DeclareOperation("DigraphConnectedComponent", [IsDigraph, IsPosInt]); diff --git a/gap/oper.gi b/gap/oper.gi index 638bf5331..589bab234 100644 --- a/gap/oper.gi +++ b/gap/oper.gi @@ -1900,7 +1900,7 @@ function(digraph, source, target) while not IsEmpty(queue) do u := Pop(queue); u := u[2]; - # TODO: this has a small performance impact for DigraphDijkstraS, + # TODO: this has a small performance impact for DigraphShortestPaths, # but do we care? if u = target then return [dist, prev]; @@ -1917,10 +1917,10 @@ function(digraph, source, target) return [dist, prev]; end); -InstallMethod(DigraphDijkstra, "for a digraph, a vertex, and a vertex", +InstallMethod(DigraphShortestPaths, "for a digraph, a vertex, and a vertex", [IsDigraph, IsPosInt, IsPosInt], DIGRAPHS_DijkstraST); -InstallMethod(DigraphDijkstra, "for a digraph, and a vertex", +InstallMethod(DigraphShortestPaths, "for a digraph, and a vertex", [IsDigraph, IsPosInt], {digraph, source} -> DIGRAPHS_DijkstraST(digraph, source, fail)); From bd51e6d719b7820f8bf7dec6d8cd6f544718ff79 Mon Sep 17 00:00:00 2001 From: William-Kenyon <115789274+William-Kenyon@users.noreply.github.com> Date: Wed, 14 Oct 2026 22:07:16 +0100 Subject: [PATCH 2/7] Make DigraphDijkstra an obsolete synonym, testing --- gap/obsolete.gi | 4 +++- tst/standard/oper.tst | 29 +++++++++++++++++++++-------- 2 files changed, 24 insertions(+), 9 deletions(-) diff --git a/gap/obsolete.gi b/gap/obsolete.gi index 84c98088e..279583241 100644 --- a/gap/obsolete.gi +++ b/gap/obsolete.gi @@ -13,4 +13,6 @@ function(oldname, func) Info(InfoWarning, 1, "use \"", NameFunction(func), "\" instead"); return CallFuncList(func, arg); end); -end); \ No newline at end of file +end); + +DIGRAPHS_DeclareObsoleteSynonym("DigraphDijkstra", DigraphShortestPaths); \ No newline at end of file diff --git a/tst/standard/oper.tst b/tst/standard/oper.tst index 1c3872fc6..5e248e5c9 100644 --- a/tst/standard/oper.tst +++ b/tst/standard/oper.tst @@ -2351,18 +2351,18 @@ gap> OutNeighbours(C); [ [ 5, 6, 7 ], [ 7 ], [ 7 ], [ 7 ], [ 1, 6, 7 ], [ 1, 5, 7 ], [ 3, 2, 1, 6, 5, 4 ] ] -# DigraphDijkstra - when there is one path to target +# DigraphShortestPaths - when there is one path to target gap> mat := [[0, 1, 1], [0, 0, 1], [0, 0, 0]]; [ [ 0, 1, 1 ], [ 0, 0, 1 ], [ 0, 0, 0 ] ] gap> gr := DigraphByAdjacencyMatrix(mat); gap> DigraphShortestDistance(gr, 2, 3); 1 -gap> DigraphDijkstra(gr, 2, 3); +gap> DigraphShortestPaths(gr, 2, 3); [ [ infinity, 0, 1 ], [ -1, -1, 2 ] ] -gap> DigraphDijkstra(gr, 1, 3); +gap> DigraphShortestPaths(gr, 1, 3); [ [ 0, 1, 1 ], [ -1, 1, 1 ] ] -gap> DigraphDijkstra(gr, 1, 2); +gap> DigraphShortestPaths(gr, 1, 2); [ [ 0, 1, 1 ], [ -1, 1, 1 ] ] gap> DigraphShortestDistance(gr, 1, 3); 1 @@ -2374,23 +2374,36 @@ gap> gr := DigraphByAdjacencyMatrix(mat); gap> DigraphShortestDistance(gr, 2, 3); fail -gap> DigraphDijkstra(gr, 2, 3); +gap> DigraphShortestPaths(gr, 2, 3); [ [ infinity, 0, infinity ], [ -1, -1, -1 ] ] gap> mat := [[0, 1, 1, 1], [0, 0, 1, 1], [0, 1, 0, 0], [1, 0, 0, 0]]; [ [ 0, 1, 1, 1 ], [ 0, 0, 1, 1 ], [ 0, 1, 0, 0 ], [ 1, 0, 0, 0 ] ] gap> gr := DigraphByAdjacencyMatrix(mat); -gap> DigraphDijkstra(gr, 1, 4); +gap> DigraphShortestPaths(gr, 1, 4); [ [ 0, 1, 1, 1 ], [ -1, 1, 1, 1 ] ] gap> mat := [[0, 1, 1, 1], [0, 0, 1, 1], [0, 1, 0, 0], [1, 0, 0, 0]]; [ [ 0, 1, 1, 1 ], [ 0, 0, 1, 1 ], [ 0, 1, 0, 0 ], [ 1, 0, 0, 0 ] ] gap> gr := DigraphByAdjacencyMatrix(mat); -gap> DigraphDijkstra(gr, 1, 2); +gap> DigraphShortestPaths(gr, 1, 2); [ [ 0, 1, 1, 1 ], [ -1, 1, 1, 1 ] ] -gap> DigraphDijkstra(gr, 1, 3); +gap> DigraphShortestPaths(gr, 1, 3); [ [ 0, 1, 1, 1 ], [ -1, 1, 1, 1 ] ] +# DigraphShortestPaths - called by obsolete synonym DigraphDijkstra +gap> L := InfoLevel(InfoWarning);; +gap> SetInfoLevel(InfoWarning, 1);; +gap> mat := [[0, 1, 1], [0, 0, 1], [0, 0, 0]]; +[ [ 0, 1, 1 ], [ 0, 0, 1 ], [ 0, 0, 0 ] ] +gap> gr := DigraphByAdjacencyMatrix(mat); + +gap> DigraphDijkstra(gr, 2, 3) = DigraphShortestPaths(gr, 2, 3); +#I "DigraphDijkstra" is obsolete and will be removed in a future version; +#I use "DigraphShortestPaths" instead +true +gap> SetInfoLevel(InfoWarning, L);; + # ModularProduct gap> ModularProduct(NullDigraph(0), CompleteDigraph(10)); From 0a4f0e9ad2defd6ada79b10658630a3ac4b16aa6 Mon Sep 17 00:00:00 2001 From: William-Kenyon <115789274+William-Kenyon@users.noreply.github.com> Date: Wed, 14 Oct 2026 22:07:25 +0100 Subject: [PATCH 3/7] Docs --- doc/oper.xml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/doc/oper.xml b/doc/oper.xml index 5c5982d06..14d219026 100644 --- a/doc/oper.xml +++ b/doc/oper.xml @@ -2287,6 +2287,20 @@ gap> DigraphShortestPaths(D, 1, 2); <#/GAPDoc> +<#GAPDoc Label="DigraphDijkstra"> + + + + Two lists. + + This is an obsolete synonym for + and will + be removed in a future version. + + +<#/GAPDoc> + <#GAPDoc Label="ModularProduct"> From 73c4417acf88b56aff47f7cd41f4f21b26cf6d9c Mon Sep 17 00:00:00 2001 From: William-Kenyon <115789274+William-Kenyon@users.noreply.github.com> Date: Sat, 14 Nov 2026 20:16:53 +0000 Subject: [PATCH 4/7] refactor into helper bfs, tests --- gap/oper.gd | 6 +- gap/oper.gi | 150 +++++++++++++++++------------------------- tst/standard/oper.tst | 28 ++++---- 3 files changed, 75 insertions(+), 109 deletions(-) diff --git a/gap/oper.gd b/gap/oper.gd index 6c3a23bdb..1f33c9672 100644 --- a/gap/oper.gd +++ b/gap/oper.gd @@ -129,10 +129,6 @@ DeclareOperation("DigraphKings", [IsDigraph, IsPosInt]); DeclareOperation("DigraphFloydWarshall", [IsDigraph, IsFunction, IsObject, IsObject]); -DeclareOperation("DigraphShortestPaths", - [IsDigraph, IsPosInt]); -DeclareOperation("DigraphShortestPaths", - [IsDigraph, IsPosInt, IsPosInt]); DeclareOperation("DigraphConnectedComponent", [IsDigraph, IsPosInt]); DeclareOperation("DigraphStronglyConnectedComponent", [IsDigraph, IsPosInt]); @@ -151,7 +147,9 @@ DeclareOperation("DigraphDistanceSet", [IsDigraph, IsPosInt, IsList]); DeclareOperation("DigraphShortestDistance", [IsDigraph, IsPosInt, IsPosInt]); DeclareOperation("DigraphShortestDistance", [IsDigraph, IsList, IsList]); DeclareOperation("DigraphShortestDistance", [IsDigraph, IsList]); +DeclareGlobalFunction("DIGRAPHS_ShortestPathsBFS"); DeclareOperation("DigraphShortestPath", [IsDigraph, IsPosInt, IsPosInt]); +DeclareOperation("DigraphShortestPaths", [IsDigraph, IsPosInt]); DeclareOperation("DigraphShortestPathSpanningTree", [IsDigraph, IsPosInt]); DeclareOperation("VerticesReachableFrom", [IsDigraph, IsPosInt]); DeclareOperation("VerticesReachableFrom", [IsDigraph, IsList]); diff --git a/gap/oper.gi b/gap/oper.gi index 589bab234..46df87e6c 100644 --- a/gap/oper.gi +++ b/gap/oper.gi @@ -1806,12 +1806,43 @@ function(D, nodes, edges) return true; end); +# BFS search from source vertex outwards. if target is not 'fail' then stops +# as soon as it is found. returns two lists; for each vertex, the index v is: +# - distance from source vertex +# - previous vertex on shortest path from source +InstallGlobalFunction(DIGRAPHS_ShortestPathsBFS, +function(D, source, target) + local neighbours, dist, previous, queue, i, a, b; + + neighbours := OutNeighbours(D); + dist := ListWithIdenticalEntries(DigraphNrVertices(D), infinity); + previous := ListWithIdenticalEntries(DigraphNrVertices(D), -1); + + dist[source] := 0; + queue := [source]; + i := 1; + while i <= Length(queue) do + a := queue[i]; + i := i + 1; + for b in neighbours[a] do + if dist[b] = infinity then + dist[b] := dist[a] + 1; + previous[b] := a; + if b = target then + return [dist, previous]; + fi; + Add(queue, b); + fi; + od; + od; + return [dist, previous]; +end); + InstallMethod(DigraphShortestPath, -"for a digraph by out-neighbours and two pos ints", -[IsDigraphByOutNeighboursRep, IsPosInt, IsPosInt], +"for a digraph and two vertices", +[IsDigraph, IsPosInt, IsPosInt], function(D, u, v) - local current, next, parent, distance, falselist, verts, nbs, path, edge, - n, a, b, i; + local verts, bfs, previous, vertices, edges, a, b; verts := DigraphVertices(D); if not (u in verts and v in verts) then @@ -1819,6 +1850,10 @@ function(D, u, v) "vertices of the 1st argument ,"); fi; + if u = v then + return fail; + fi; + if IsDigraphEdge(D, u, v) then return [[u, v], [Position(OutNeighboursOfVertex(D, u), v)]]; elif HasIsTransitiveDigraph(D) and IsTransitiveDigraph(D) then @@ -1831,98 +1866,35 @@ function(D, u, v) return fail; fi; - nbs := OutNeighbours(D); - distance := ListWithIdenticalEntries(Length(verts), -1); - - # Setting up objects useful in the function. - parent := []; - current := [u]; - edge := []; - next := BlistList([1 .. Length(verts)], []); - falselist := BlistList([1 .. Length(verts)], []); - - n := 0; - while current <> [] do - n := n + 1; - for a in current do - for i in [1 .. Length(nbs[a])] do - b := nbs[a][i]; - if distance[b] = -1 then - distance[b] := n; - next[b] := true; - parent[b] := a; - edge[b] := i; - fi; - - if b = v then - path := [[], []]; - # Finds the path - for i in [1 .. n] do - Add(path[1], b); - Add(path[2], edge[b]); - b := parent[b]; - od; - Add(path[1], u); # Adds the starting vertex to the list of vertices - return [Reversed(path[1]), Reversed(path[2])]; - fi; - od; - od; - current := ListBlist(verts, next); - IntersectBlist(next, falselist); - od; + bfs := DIGRAPHS_ShortestPathsBFS(D, u, v); + previous := bfs[2]; + if bfs[1][v] = infinity then return fail; -end); - -BindGlobal("DIGRAPHS_DijkstraST", -function(digraph, source, target) - local dist, prev, queue, u, v, alt; - - if not source in DigraphVertices(digraph) then - ErrorNoReturn("the 2nd argument must be a vertex of the ", - "1st argument "); - elif target <> fail and not target in DigraphVertices(digraph) then - ErrorNoReturn("the 3rd argument must be a vertex of the ", - "1st argument "); fi; - dist := []; - prev := []; - queue := BinaryHeap({x, y} -> x[1] < y[1]); - - for v in DigraphVertices(digraph) do - dist[v] := infinity; - prev[v] := -1; - od; - - dist[source] := 0; - Push(queue, [0, source]); - - while not IsEmpty(queue) do - u := Pop(queue); - u := u[2]; - # TODO: this has a small performance impact for DigraphShortestPaths, - # but do we care? - if u = target then - return [dist, prev]; - fi; - for v in OutNeighbours(digraph)[u] do - alt := dist[u] + DigraphEdgeLabel(digraph, u, v); - if alt < dist[v] then - dist[v] := alt; - prev[v] := u; - Push(queue, [dist[v], v]); - fi; - od; + # reconstruct path by walking backwards from v to u + vertices := [v]; + edges := []; + b := v; + while b <> u do + a := previous[b]; + Add(edges, Position(OutNeighbours(D)[a], b)); + Add(vertices, a); + b := a; od; - return [dist, prev]; + return [Reversed(vertices), Reversed(edges)]; end); -InstallMethod(DigraphShortestPaths, "for a digraph, a vertex, and a vertex", -[IsDigraph, IsPosInt, IsPosInt], DIGRAPHS_DijkstraST); - -InstallMethod(DigraphShortestPaths, "for a digraph, and a vertex", +InstallMethod(DigraphShortestPaths, "for a digraph and a vertex", [IsDigraph, IsPosInt], -{digraph, source} -> DIGRAPHS_DijkstraST(digraph, source, fail)); +function(D, source) + if not source in DigraphVertices(D) then + ErrorNoReturn("the 2nd argument must be a vertex of the ", + "1st argument "); + fi; + + return DIGRAPHS_ShortestPathsBFS(D, source, fail); +end); InstallMethod(IteratorOfPaths, "for a digraph by out-neighbours and two pos ints", diff --git a/tst/standard/oper.tst b/tst/standard/oper.tst index 5e248e5c9..f5da3ae2c 100644 --- a/tst/standard/oper.tst +++ b/tst/standard/oper.tst @@ -2014,12 +2014,10 @@ gap> DigraphShortestPath(gr, 1, 6); fail gap> DigraphShortestPath(gr, 2, 5); [ [ 2, 3, 5 ], [ 1, 1 ] ] -gap> DigraphShortestPath(gr, 3, 3); -[ [ 3, 5, 4, 3 ], [ 1, 1, 3 ] ] +gap> DigraphShortestPath(gr, 5, 2); +[ [ 5, 4, 2 ], [ 1, 2 ] ] gap> DigraphShortestPath(gr, 6, 6); fail -gap> DigraphShortestPath(gr, 5, 5); -[ [ 5, 5 ], [ 2 ] ] gap> gr := Digraph([[]]);; gap> DigraphShortestPath(gr, 1, 1); fail @@ -2030,10 +2028,8 @@ gap> gr := Digraph([[2], [1], [3]]);; gap> DigraphShortestPath(gr, 1, 2); [ [ 1, 2 ], [ 1 ] ] gap> gr := CayleyDigraph(SymmetricGroup(7));; -gap> DigraphShortestPath(gr, 12, 5014); -[ [ 12, 878, 158, 1029, 1875, 1881, 2754, 3498, 3522, 3642, 4508, 4388, 68, - 788, 1634, 2505, 3249, 3273, 4146, 5012, 5014 ], - [ 2, 1, 2, 2, 1, 2, 2, 1, 2, 2, 1, 2, 1, 2, 2, 2, 1, 2, 2, 1 ] ] +gap> Length(DigraphShortestPath(gr, 12, 5014)[1]); +21 # IsReachableFrom gap> D := CompleteDigraph(5); @@ -2358,11 +2354,11 @@ gap> gr := DigraphByAdjacencyMatrix(mat); gap> DigraphShortestDistance(gr, 2, 3); 1 -gap> DigraphShortestPaths(gr, 2, 3); +gap> DigraphShortestPaths(gr, 2); [ [ infinity, 0, 1 ], [ -1, -1, 2 ] ] -gap> DigraphShortestPaths(gr, 1, 3); +gap> DigraphShortestPaths(gr, 1); [ [ 0, 1, 1 ], [ -1, 1, 1 ] ] -gap> DigraphShortestPaths(gr, 1, 2); +gap> DigraphShortestPaths(gr, 1); [ [ 0, 1, 1 ], [ -1, 1, 1 ] ] gap> DigraphShortestDistance(gr, 1, 3); 1 @@ -2374,21 +2370,21 @@ gap> gr := DigraphByAdjacencyMatrix(mat); gap> DigraphShortestDistance(gr, 2, 3); fail -gap> DigraphShortestPaths(gr, 2, 3); +gap> DigraphShortestPaths(gr, 2); [ [ infinity, 0, infinity ], [ -1, -1, -1 ] ] gap> mat := [[0, 1, 1, 1], [0, 0, 1, 1], [0, 1, 0, 0], [1, 0, 0, 0]]; [ [ 0, 1, 1, 1 ], [ 0, 0, 1, 1 ], [ 0, 1, 0, 0 ], [ 1, 0, 0, 0 ] ] gap> gr := DigraphByAdjacencyMatrix(mat); -gap> DigraphShortestPaths(gr, 1, 4); +gap> DigraphShortestPaths(gr, 1); [ [ 0, 1, 1, 1 ], [ -1, 1, 1, 1 ] ] gap> mat := [[0, 1, 1, 1], [0, 0, 1, 1], [0, 1, 0, 0], [1, 0, 0, 0]]; [ [ 0, 1, 1, 1 ], [ 0, 0, 1, 1 ], [ 0, 1, 0, 0 ], [ 1, 0, 0, 0 ] ] gap> gr := DigraphByAdjacencyMatrix(mat); -gap> DigraphShortestPaths(gr, 1, 2); +gap> DigraphShortestPaths(gr, 1); [ [ 0, 1, 1, 1 ], [ -1, 1, 1, 1 ] ] -gap> DigraphShortestPaths(gr, 1, 3); +gap> DigraphShortestPaths(gr, 1); [ [ 0, 1, 1, 1 ], [ -1, 1, 1, 1 ] ] # DigraphShortestPaths - called by obsolete synonym DigraphDijkstra @@ -2398,7 +2394,7 @@ gap> mat := [[0, 1, 1], [0, 0, 1], [0, 0, 0]]; [ [ 0, 1, 1 ], [ 0, 0, 1 ], [ 0, 0, 0 ] ] gap> gr := DigraphByAdjacencyMatrix(mat); -gap> DigraphDijkstra(gr, 2, 3) = DigraphShortestPaths(gr, 2, 3); +gap> DigraphDijkstra(gr, 2) = DigraphShortestPaths(gr, 2); #I "DigraphDijkstra" is obsolete and will be removed in a future version; #I use "DigraphShortestPaths" instead true From a89597c3a5c9b5a2357854be3a0d71a78bf271ed Mon Sep 17 00:00:00 2001 From: William-Kenyon <115789274+William-Kenyon@users.noreply.github.com> Date: Sat, 14 Nov 2026 20:23:03 +0000 Subject: [PATCH 5/7] docs new behaviour --- doc/oper.xml | 68 +++++++++++++++++----------------------------------- 1 file changed, 22 insertions(+), 46 deletions(-) diff --git a/doc/oper.xml b/doc/oper.xml index 14d219026..6a8576ceb 100644 --- a/doc/oper.xml +++ b/doc/oper.xml @@ -1617,7 +1617,6 @@ true <#/GAPDoc> - <#GAPDoc Label="DigraphShortestPath"> @@ -1625,29 +1624,22 @@ true Returns a shortest directed path in the digraph digraph from vertex u to vertex v, if such a path exists. If u = - v, then the shortest non-trivial cycle is returned, again, if it - exists. Otherwise, this operation returns fail. See Section - for the definition of a directed - path and a directed cycle. -

- - See for details on the output. + v or no path exists, this operation returns fail. See + Section for the definition of a + directed path.

The method for DigraphShortestPath has worst case complexity of O(m + n) where m is the number of edges and n the - number of vertices in digraph. + number of vertices in digraph.

+ See for details on the output.

D := Digraph([[1, 2], [3], [2, 4], [1], [2, 4]]); +gap> DigraphShortestPath(D, 1, 1); +fail gap> DigraphShortestPath(D, 5, 1); [ [ 5, 4, 1 ], [ 2, 1 ] ] -gap> DigraphShortestPath(D, 3, 3); -[ [ 3, 2, 3 ], [ 1, 1 ] ] -gap> DigraphShortestPath(D, 5, 5); -fail -gap> DigraphShortestPath(D, 1, 1); -[ [ 1, 1 ], [ 1 ] ] ]]> @@ -2249,39 +2241,25 @@ false]]> <#GAPDoc Label="DigraphShortestPaths"> - - + Two lists. - If digraph is a digraph and source and target are - vertices of digraph, then DigraphShortestPaths calculates the - length of the shortest path from source to target and returns - two lists. Each element of the first list is the distance of the - corresponding element from source. If a vertex was not visited in - the process of calculating the shortest distance to target or if - there is no path connecting that vertex with source, then - the corresponding distance is infinity. Each element of the - second list gives the previous vertex in the shortest path - from source to the corresponding vertex. For - source and for any vertices that remained unvisited this - will be -1.

- - If the optional second argument target is not present, then - DigraphShortestPaths returns the shortest path from source to - every vertex that is reachable from source. + If digraph is a digraph and source is a vertex of + digraph, then DigraphShortestPaths returns two lists, + distances and parents, describing the shortest paths from + source to every vertex in digraph. For a vertex v, + distances[v] is the shortest distance to v, and + parents[v] is the final vertex before v on the shortest path + from source to v.

If a vertex is unreachable from + v, then its distance is infinity, and its parent is -1. - mat := [[0, 1, 1], [0, 0, 1], [0, 0, 0]]; -[ [ 0, 1, 1 ], [ 0, 0, 1 ], [ 0, 0, 0 ] ] -gap> D := DigraphByAdjacencyMatrix(mat); + D := Digraph([[2, 3], [3], []]); -gap> DigraphShortestPaths(D, 2, 3); -[ [ infinity, 0, 1 ], [ -1, -1, 2 ] ] -gap> DigraphShortestPaths(D, 1, 3); -[ [ 0, 1, 1 ], [ -1, 1, 1 ] ] -gap> DigraphShortestPaths(D, 1, 2); +gap> DigraphShortestPaths(D, 1); [ [ 0, 1, 1 ], [ -1, 1, 1 ] ] +gap> DigraphShortestPaths(D, 2); +[ [ infinity, 0, 1 ], [ -1, -1, 2 ] ] ]]> @@ -2289,13 +2267,11 @@ gap> DigraphShortestPaths(D, 1, 2); <#GAPDoc Label="DigraphDijkstra"> - Two lists. This is an obsolete synonym for - and will + and will be removed in a future version. From 02f3a7445ae685988cf47c92cfe57860e0a93a9d Mon Sep 17 00:00:00 2001 From: William-Kenyon <115789274+William-Kenyon@users.noreply.github.com> Date: Sat, 14 Nov 2026 20:31:07 +0000 Subject: [PATCH 6/7] mirror edgeweighted docs --- doc/oper.xml | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/doc/oper.xml b/doc/oper.xml index 6a8576ceb..b4378df5e 100644 --- a/doc/oper.xml +++ b/doc/oper.xml @@ -1626,13 +1626,14 @@ true u to vertex v, if such a path exists. If u = v or no path exists, this operation returns fail. See Section for the definition of a - directed path.

+ directed path. See for details on the output.

The method for DigraphShortestPath has worst case complexity of O(m + n) where m is the number of edges and n the number of vertices in digraph.

- See for details on the output.

+ See . See also the + weighted operation . D := Digraph([[1, 2], [3], [2, 4], [1], [2, 4]]); @@ -2252,7 +2253,11 @@ false]]> parents[v] is the final vertex before v on the shortest path from source to v.

If a vertex is unreachable from v, then its distance is infinity, and its parent is -1. +

+ For a simple way of finding the shortest path between two specific vertices, + see . See also the weighted operation + . D := Digraph([[2, 3], [3], []]); From a7684f7c45fac52b00e6a14bea1cb80f12ad2b84 Mon Sep 17 00:00:00 2001 From: William-Kenyon <115789274+William-Kenyon@users.noreply.github.com> Date: Sat, 14 Nov 2026 22:29:10 +0000 Subject: [PATCH 7/7] make shortest path lex-least --- doc/oper.xml | 11 +++++---- gap/oper.gi | 56 +++++++++++++++++++++++++++++-------------- tst/standard/oper.tst | 8 +++++++ 3 files changed, 52 insertions(+), 23 deletions(-) diff --git a/doc/oper.xml b/doc/oper.xml index b4378df5e..f4c5f3ec1 100644 --- a/doc/oper.xml +++ b/doc/oper.xml @@ -1622,11 +1622,12 @@ true A pair of lists, or fail. - Returns a shortest directed path in the digraph digraph from vertex - u to vertex v, if such a path exists. If u = - v or no path exists, this operation returns fail. See - Section for the definition of a - directed path. See for details on the output.

+ Returns the lexicographically least shortest directed path in the digraph + digraph from vertex u to vertex v, if such a path + exists. If u = v or no path exists, this operation + returns fail. See Section + for the definition of a directed path. See for + details on the output.

The method for DigraphShortestPath has worst case complexity of O(m + n) where m is the number of edges and n the diff --git a/gap/oper.gi b/gap/oper.gi index 46df87e6c..fb55e73f6 100644 --- a/gap/oper.gi +++ b/gap/oper.gi @@ -1811,12 +1811,11 @@ end); # - distance from source vertex # - previous vertex on shortest path from source InstallGlobalFunction(DIGRAPHS_ShortestPathsBFS, -function(D, source, target) - local neighbours, dist, previous, queue, i, a, b; +function(neighbours, source, target) + local dist, previous, queue, i, a, b; - neighbours := OutNeighbours(D); - dist := ListWithIdenticalEntries(DigraphNrVertices(D), infinity); - previous := ListWithIdenticalEntries(DigraphNrVertices(D), -1); + dist := ListWithIdenticalEntries(Length(neighbours), infinity); + previous := ListWithIdenticalEntries(Length(neighbours), -1); dist[source] := 0; queue := [source]; @@ -1842,7 +1841,7 @@ InstallMethod(DigraphShortestPath, "for a digraph and two vertices", [IsDigraph, IsPosInt, IsPosInt], function(D, u, v) - local verts, bfs, previous, vertices, edges, a, b; + local verts, reversed, a, distanceto, neighbours, vertices, edges, best, w, i; verts := DigraphVertices(D); if not (u in verts and v in verts) then @@ -1866,23 +1865,44 @@ function(D, u, v) return fail; fi; - bfs := DIGRAPHS_ShortestPathsBFS(D, u, v); - previous := bfs[2]; - if bfs[1][v] = infinity then + # the rest of this method is to guarantee that the returned path is lex-least + # otherwise could generate path by just walking backwards via predecessors + + # want to walk forwards from u to v, which requires knowing the distance to + # v instead of from u, therefore have to call the BFS on the reverse of D + # could use DigraphReverse(), but if D is mutable it gets changed in place, + # so would have to be un-reversed afterwards + neighbours := OutNeighbours(D); + reversed := List([1 .. Length(neighbours)], x -> []); + for a in [1 .. Length(neighbours)] do + for w in neighbours[a] do + Add(reversed[w], a); + od; + od; + distanceto := DIGRAPHS_ShortestPathsBFS(reversed, v, u)[1]; + if distanceto[u] = infinity then return fail; fi; - # reconstruct path by walking backwards from v to u - vertices := [v]; + vertices := [u]; edges := []; - b := v; - while b <> u do - a := previous[b]; - Add(edges, Position(OutNeighbours(D)[a], b)); + a := u; + while a <> v do + best := fail; + # find smallest vertex that brings us one step closer to v + # OutNeighbours aren't necessarily in order, so is slightly more involved + for i in [1 .. Length(neighbours[a])] do + w := neighbours[a][i]; + if distanceto[w] = distanceto[a] - 1 + and (best = fail or w < neighbours[a][best]) then + best := i; + fi; + od; + Add(edges, best); + a := neighbours[a][best]; Add(vertices, a); - b := a; od; - return [Reversed(vertices), Reversed(edges)]; + return [vertices, edges]; end); InstallMethod(DigraphShortestPaths, "for a digraph and a vertex", @@ -1893,7 +1913,7 @@ function(D, source) "1st argument "); fi; - return DIGRAPHS_ShortestPathsBFS(D, source, fail); + return DIGRAPHS_ShortestPathsBFS(OutNeighbours(D), source, fail); end); InstallMethod(IteratorOfPaths, diff --git a/tst/standard/oper.tst b/tst/standard/oper.tst index f5da3ae2c..7a4952a15 100644 --- a/tst/standard/oper.tst +++ b/tst/standard/oper.tst @@ -2031,6 +2031,14 @@ gap> gr := CayleyDigraph(SymmetricGroup(7));; gap> Length(DigraphShortestPath(gr, 12, 5014)[1]); 21 +# DigraphShortestPath - lex-least +gap> D := Digraph([[3, 2], [5], [4], [6], [6], []]); + +gap> OutNeighbours(D)[1]; +[ 3, 2 ] +gap> DigraphShortestPath(D, 1, 6); +[ [ 1, 2, 5, 6 ], [ 2, 1, 1 ] ] + # IsReachableFrom gap> D := CompleteDigraph(5);