Add shortest-path and related distance & diameter algorithms

.github/workflows/CI.yml

@@ -70,6 +70,7 @@ jobs:
           using Pkg
           Pkg.develop(PackageSpec(path=pwd()))
           Pkg.instantiate()
+          Pkg.add(name="OpenSSL_jll", version="3.0")
       - uses: julia-actions/julia-buildpkg@latest
       - uses: julia-actions/julia-docdeploy@latest
         env:
@@ -78,6 +79,7 @@ jobs:
       - name: Run doctests
         shell: julia --project=docs --color=yes {0}
         run: |
+          using OpenSSL_jll
           using Documenter: DocMeta, doctest
           using SimpleDirectedHypergraphs
           DocMeta.setdocmeta!(SimpleDirectedHypergraphs, :DocTestSetup, :(using SimpleDirectedHypergraphs); recursive=true)

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Evan Walter Clark Spotte-Smith
+Copyright (c) 2025 Evan Walter Clark Spotte-Smith, the Community of Researchers Assessing Chemical Transformations and Exploring Reactivity (CoReACTER), and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Project.toml

@@ -1,32 +1,38 @@
 name = "SimpleDirectedHypergraphs"
 uuid = "a42c6b43-640c-4761-b4a8-4f98c31d02e9"
-authors = ["Evan Walter Clark Spotte-Smith"]
 version = "0.1.0"
+authors = ["Evan Walter Clark Spotte-Smith"]
 
 [deps]
 DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
+GLPK = "60bf3e95-4087-53dc-ae20-288a0d20c6a6"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
+InvertedIndices = "41ab1584-1d38-5bbf-9106-f11c6c58b48f"
 JSON3 = "0f8b85d8-7281-11e9-16c2-39a750bddbf1"
+JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
-SimpleHypergraphs = "aa4a32ff-dd5d-5357-90e3-e7a9512f0501"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+SimpleHypergraphs = "aa4a32ff-dd5d-5357-90e3-e7a9512f0501"
 SimpleTraits = "699a6c99-e7fa-54fc-8d76-47d257e15c1d"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 StructTypes = "856f2bd8-1eba-4b0a-8007-ebc267875bd4"
 
 [compat]
 DataStructures = "^0.18.11"
+GLPK = "1.2.1"
 Graphs = "1.12.0"
+InvertedIndices = "1.3.1"
 JSON3 = "^1.0.1"
+JuMP = "1.29.2"
 LinearAlgebra = "^1.6.7"
+SimpleHypergraphs = "0.3.0"
 SimpleTraits = "^0.9.4"
 StatsBase = "^0.34.0"
 StructTypes = "^1.0.1"
-SimpleHypergraphs = "0.3.0"
 julia = "^1.6.7"
 
 [extras]
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Test"]
+test = ["Test"]

docs/Project.toml

@@ -1,5 +1,8 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
-SimpleHypergraphs = "aa4a32ff-dd5d-5357-90e3-e7a9512f0501"
 SimpleDirectedHypergraphs = "a42c6b43-640c-4761-b4a8-4f98c31d02e9"
+SimpleHypergraphs = "aa4a32ff-dd5d-5357-90e3-e7a9512f0501"
+
+[sources]
+SimpleDirectedHypergraphs = {path = ".."}

docs/make.jl

@@ -15,6 +15,7 @@ makedocs(;
     pages=[
         "Home" => "index.md",
     ],
+    checkdocs=:exports
 )
 
 deploydocs(;

docs/src/reference.md

@@ -121,10 +121,27 @@ Pathfinding
 -----------
 ```@docs
 
-_visit(h::H, v::Int) where {H <: AbstractDirectedHypergraph}
-SimpleHypergraphs.shortest_path(b::BipartiteView{H}, source::Int, target::Int) where {H<:AbstractDirectedHypergraph}
-SimpleHypergraphs.shortest_path(t::TwoSectionView{H}, source::Int, target::Int) where {H<:AbstractDirectedHypergraph}
+SimpleHypergraphs.shortest_path(::BipartiteView{H}, ::Int, ::Int) where {H<:AbstractDirectedHypergraph}
+SimpleHypergraphs.shortest_path(::TwoSectionView{H}, ::Int, ::Int) where {H<:AbstractDirectedHypergraph}
 
+forward_reachable(::H, ::Int) where {H<:AbstractDirectedHypergraph}
+backward_traceable(::H, ::Int) where {H<:AbstractDirectedHypergraph}
+is_reachable(::H, ::Int, ::Int, ::Symbol) where {H<:AbstractDirectedHypergraph}
+
+all_hyperpaths
+
+shortest_hyperpath_kk_heuristic
+
+shortest_hyperpath_kk_ilp
+
+SnodeDistanceKKHeuristic
+SnodeDistanceKKILP
+
+SimpleHypergraphs.distance(::H, ::SnodeDistanceKKHeuristic, ::AbstractVector{T}) where {H<:AbstractDirectedHypergraph, T<:Real}
+SimpleHypergraphs.distance(::H, ::SnodeDistanceKKILP, ::AbstractVector{T}) where {H<:AbstractDirectedHypergraph, T<:Real}
+
+Graphs.diameter(::H, ::SnodeDistanceKKHeuristic) where {H<:AbstractDirectedHypergraph}
+Graphs.diameter(::H, ::SnodeDistanceKKILP) where {H<:AbstractDirectedHypergraph}
 ```
 
 

src/SimpleDirectedHypergraphs.jl

@@ -9,6 +9,9 @@ using JSON3
 using Random
 using LinearAlgebra
 using SimpleTraits
+using InvertedIndices
+import JuMP
+import GLPK
 
 export AbstractDirectedHypergraph
 export DirectedHypergraph, HyperedgeDirection
@@ -20,6 +23,10 @@ export to_undirected
 
 export get_weakly_connected_components, get_strongly_connected_components
 
+export forward_reachable, backward_traceable, is_reachable
+export all_hyperpaths, shortest_hyperpath_kk_heuristic, shortest_hyperpath_kk_ilp
+
+export SnodeDistanceKKHeuristic, SnodeDistanceKKILP
 
 include("abstracttypes.jl")
 include("dihypergraph.jl")
@@ -30,4 +37,7 @@ include("models/twosection.jl")
 include("models/random-models.jl")
 include("models/dual.jl")
 
+include("algorithms/paths.jl")
+include("algorithms/distance.jl")
+
 end # module

src/algorithms/distance.jl

@@ -0,0 +1,192 @@
+"""
+    SnodeDistanceKKHeuristic <: AbstractDistance
+
+Constructor: SnodeDistanceKKHeuristic(sources::Set{Int}, targets::Set{Int}) <: AbstractDistance
+
+Represent a distance between a set of *source* nodes (`sources`) and a set of *target* nodes (`targets`) in a directed
+hypergraph, where a distance in this context is defined as the length of the shortest hyperpath that reaches all
+`t ∈ targets`.
+
+This approach uses the *heuristic* shortest hyperpath algorithm of Krieger & Kececioglu 2022
+(DOI: 10.1186/s13015-022-00217-9). The Krieger & Kececioglu heuristic algorithm commonly (but not always) returns the
+true optimal (shortest) hyperpath; this algorithm can thus be thought of as an upper bound of the true distance between
+the sinks and the source. To calculate the exact (minimal) distance, instead use `SnodeDistanceKKExact`.
+"""
+struct SnodeDistanceKKHeuristic <: AbstractDistance
+    sources::Set{Int}
+    targets::Set{Int}
+end
+
+"""
+    SnodeDistanceKKILP <: AbstractDistance
+
+Constructor: SnodeDistanceKKILP(sources::Set{Int}, targets::Set{Int}) <: AbstractDistance
+
+Represent a distance between a set of *source* nodes (`sources`) and a set of *target* nodes (`targets`) in a directed
+hypergraph, where a distance in this context is defined as the length of the shortest hyperpath that reaches all
+`t ∈ targets`.
+
+This approach uses the *exact* shortest hyperpath algorithm of Krieger & Kececioglu 2023 (DOI: 10.1089/cmb.2023.0242).
+The Krieger & Kececioglu algorithm solves an integer linear programming formalism related to hypergraph cutting.
+
+For a lower-cost heuristic algorithm, see `SnodeDistanceKKHeuristic`.
+"""
+struct SnodeDistanceKKILP <: AbstractDistance
+    sources::Set{Int}
+    targets::Set{Int}
+end
+
+"""
+    distance(
+        hg::H,
+        distance_method::SnodeDistanceKKHeuristic,
+        hyperedge_weights::AbstractVector{T};
+    ) where {H <: AbstractDirectedHypergraph, T <: Real}
+
+    Return the shortest distance between the `distance_method.sources` and the `distance_method.targets`,
+    assuming tha the cost (i.e., distance) between two vertices is the sum of the (nonnegative) `hyperedge_weights`
+    of the hyperedges in the shortest path between the two sets of vertices. If there is no path between the `sources`
+    and `targets`, returns `typemax(T)`.
+
+    Here, the heuristic directed hypergraph pathfinding algorithm of Krieger & Kececioglu (2022),
+    DOI: 10.1186/s13015-022-00217-9 is used to find the shortest path. This algorithm is not guaranteed to find the
+    optimal pathway, but in practice, it produces the optimal pathway approximately 99% of the time.
+"""
+function SimpleHypergraphs.distance(
+    hg::H,
+    distance_method::SnodeDistanceKKHeuristic,
+    hyperedge_weights::AbstractVector{T}
+) where {H<:AbstractDirectedHypergraph,T<:Real}
+
+    path = shortest_hyperpath_kk_heuristic(
+        hg,
+        distance_method.sources,
+        distance_method.targets,
+        hyperedge_weights
+    )
+
+    if length(path) == 0
+        return typemax(T)
+    end
+
+    return sum(
+        hyperedge_weights[e]
+        for e in path
+    )
+end
+
+"""
+    distance(
+        hg::H,
+        distance_method::SnodeDistanceKKILP,
+        hyperedge_weights::AbstractVector{T}
+    ) where {H <: AbstractDirectedHypergraph}
+
+    Return the shortest distance between the `distance_method.sources` and the `distance_method.targets`,
+    assuming tha the cost (i.e., distance) between two vertices is the sum of the (nonnegative) `hyperedge_weights`
+    of the hyperedges in the shortest path between the two sets of vertices. If there is no path between the `sources`
+    and `targets`, returns `typemax(T)`.
+
+    Here, the *exact* shortest hyperpath algorithm of Krieger & Kececioglu 2023 (DOI: 10.1089/cmb.2023.0242) is used.
+    The Krieger & Kececioglu algorithm solves an integer linear programming formalism related to hypergraph cutting.
+
+"""
+function SimpleHypergraphs.distance(
+    hg::H,
+    distance_method::SnodeDistanceKKILP,
+    hyperedge_weights::AbstractVector{T}
+) where {H<:AbstractDirectedHypergraph,T<:Real}
+
+    path = shortest_hyperpath_kk_ilp(
+        hg,
+        distance_method.sources,
+        distance_method.targets,
+        hyperedge_weights
+    )
+
+    if length(path) == 0
+        return typemax(T)
+    end
+
+    return sum(
+        hyperedge_weights[e]
+        for e in path
+    )
+end
+
+"""
+    diameter(
+        hg::H,
+        distance_method::SnodeDistanceKKHeuristic,
+    ) where {H <: AbstractSimpleHypergraph, T <: Real}
+
+    Return the diameter of a hypergraph `hg` (maximum number of hyperedges required to go between any two vertices)
+    based on Krieger & Kececioglu's heuristic algorithm (DOI: 10.1186/s13015-022-00217-9). If there exist some vertices
+    not reachable from other vertices (i.e., if `hg` is not strongly connected), then this will return `Inf`.
+"""
+function Graphs.diameter(
+    hg::H,
+    _::SnodeDistanceKKHeuristic,
+) where {H<:AbstractDirectedHypergraph}
+    if length(get_strongly_connected_components(hg)) != 1
+        return Inf64
+    end
+
+    # Since we're interested in the number of steps, assign each hyperedge a uniform weight of `1`
+    edge_weights = ones(nhe(hg))
+
+    max_dist = 0.0
+    for i in 1:nhv(hg)
+        for j in i+1:nhv(hg)
+            dist = SimpleHypergraphs.distance(
+                hg,
+                SnodeDistanceKKHeuristic(Set{Int}(i), Set{Int}(j)),
+                edge_weights
+            )
+            if dist > max_dist
+                max_dist = dist
+            end
+        end
+    end
+
+    return max_dist
+end
+
+"""
+    diameter(
+        hg::H,
+        distance_method::f,
+    ) where {H <: AbstractSimpleHypergraph, T <: Real}
+
+    Return the diameter of a hypergraph `hg` (maximum number of hyperedges required to go between any two vertices)
+    based on Krieger & Kececioglu's exact integer linear programming algorithm (DOI: 10.1089/cmb.2023.0242). If there
+    exist some vertices not reachable from other vertices (i.e., if `hg` is not strongly connected), then this will
+    return `Inf64`.
+"""
+function Graphs.diameter(
+    hg::H,
+    _::SnodeDistanceKKILP,
+) where {H<:AbstractDirectedHypergraph}
+    if length(get_strongly_connected_components(hg)) != 1
+        return Inf64
+    end
+
+    # Since we're interested in the number of steps, assign each hyperedge a uniform weight of `1`
+    edge_weights = ones(nhe(hg))
+
+    max_dist = 0
+    for i in 1:nhv(hg)
+        for j in i+1:nhv(hg)
+            dist = SimpleHypergraphs.distance(
+                hg,
+                SnodeDistanceKKILP(Set{Int}(i), Set{Int}(j)),
+                edge_weights
+            )
+            if dist > max_dist
+                max_dist = dist
+            end
+        end
+    end
+
+    return max_dist
+end