find is the better verb as the path is still an index to the graph

Author: Affie

src/Deprecated.jl

@@ -636,7 +636,7 @@ end
 # the `search` verb can also come ito play, but it is more for knn search type functions.
 
 function findFactorsBetweenNaive(args...)
-    return error("findFactorsBetweenNaive is obsolete, use DFG.getPath[s] instead.")
+    return error("findFactorsBetweenNaive is obsolete, use DFG.findPath[s] instead.")
 end
 
 #TODO deprecate `is` is the correct verb, but rather isHomogeneous(path::Path) the form is isAdjective
@@ -660,7 +660,7 @@ function isPathFactorsHomogeneous(dfg::AbstractDFG, from::Symbol, to::Symbol)
     return (length(utyp) == 1), utyp
 end
 
-# deprecated use filter and path seperately.
+# deprecated use filter and path separately.
 function findShortestPathDijkstra(
     dfg::GraphsDFG,
     from::Symbol,
@@ -675,7 +675,7 @@ function findShortestPathDijkstra(
     initialized::Union{Nothing, Bool} = nothing,
 )
     Base.depwarn(
-        "findShortestPathDijkstra is deprecated, use getPath with `variableLabels`/`factorLabels` kwargs instead.",
+        "findShortestPathDijkstra is deprecated, use findPath with `variableLabels`/`factorLabels` kwargs instead.",
         :findShortestPathDijkstra,
     )
     any_active_filters = any(
@@ -710,8 +710,8 @@ function findShortestPathDijkstra(
             dfg,
             restrict_labels,
         )
-        return getPath(subdfg, from, to).path
+        return findPath(subdfg, from, to).path
     else
-        return getPath(dfg, from, to).path
+        return findPath(dfg, from, to).path
     end
 end

src/DistributedFactorGraphs.jl

@@ -422,8 +422,8 @@ const unstable_functions::Vector{Symbol} = [
     :FactorSummary,
     :listNeighborhood,
     :listNeighbors,
-    :getPath,
-    :getPaths,
+    :findPath,
+    :findPaths,
     :InMemoryBlobstore,
     :exists,
     :compare,

src/GraphsDFG/GraphsDFG.jl

@@ -54,8 +54,8 @@ import ...DistributedFactorGraphs:
     lsf,
     isConnected,
     listNeighbors,
-    getPaths,
-    getPath,
+    findPaths,
+    findPath,
     getSubgraph,
     getBiadjacencyMatrix,
     toDot,

src/GraphsDFG/services/GraphsDFG.jl

@@ -359,15 +359,15 @@ function toDot(dfg::GraphsDFG)
 end
 
 #API design NOTE:
-# Do not create new Verbs or Nouns for metric vs. topological pathfinding. getPaths is the universal router... getPaths(..., metric)
+# Do not create new Verbs or Nouns for metric vs. topological pathfinding. findPaths is the universal router... findPaths(..., metric)
 # for now we only look at topological paths.
 
-function getPaths(::typeof(all_simple_paths), dfg, from::Symbol, to::Symbol; kwargs...)
+function findPaths(::typeof(all_simple_paths), dfg, from::Symbol, to::Symbol; kwargs...)
     gpaths = Graphs.all_simple_paths(dfg.g, dfg.g.labels[from], dfg.g.labels[to]; kwargs...)
     return map(p -> (path = map(i -> dfg.g.labels[i], p), dist = length(p) - 1), gpaths)
 end
 
-function getPaths(
+function findPaths(
     ::typeof(yen_k_shortest_paths),
     dfg::GraphsDFG,
     from::Symbol,
@@ -390,12 +390,11 @@ function getPaths(
 end
 
 # note with default heuristic this is just dijkstra's algorithm
-function getPaths(
+function findPaths(
     ::typeof(a_star),
     dfg::GraphsDFG,
     from::Symbol,
-    to::Symbol,
-    ::Int;
+    to::Symbol;
     distmx::AbstractMatrix{T} = weights(dfg.g),
     heuristic = nothing,
 ) where {T}
@@ -417,13 +416,12 @@ function getPaths(
     return [(path = path, dist = dist)]
 end
 
-#TODO Move getPaths and getPath to AbstractDFG services as default implementations.
-function getPaths(
+#TODO Move findPaths and findPath to AbstractDFG services as default implementations.
+function findPaths(
     dfg::AbstractDFG,
     from::Symbol,
     to::Symbol,
     k::Int;
-    algorithm = k == 1 ? a_star : yen_k_shortest_paths,
     variableLabels::Union{Nothing, Vector{Symbol}} = nothing,
     factorLabels::Union{Nothing, Vector{Symbol}} = nothing,
     kwargs...,
@@ -449,27 +447,29 @@ function getPaths(
         !hasFactor(active_dfg, to) &&
         throw(DFG.LabelNotFoundError(to))
 
-    return getPaths(algorithm, active_dfg, from, to, k; kwargs...)
+    # optimization for k=1 since A* is more efficient than Yen's for single shortest path
+    if k == 1
+        return findPaths(a_star, active_dfg, from, to; kwargs...)
+    else
+        return findPaths(yen_k_shortest_paths, active_dfg, from, to, k; kwargs...)
+    end
 end
 
-function getPath(
+function findPath(
     dfg::AbstractDFG,
     from::Symbol,
     to::Symbol;
     variableLabels::Union{Nothing, Vector{Symbol}} = nothing,
     factorLabels::Union{Nothing, Vector{Symbol}} = nothing,
     kwargs...,
 )
-    paths = getPaths(dfg, from, to, 1; variableLabels, factorLabels, kwargs...)
+    paths = findPaths(dfg, from, to, 1; variableLabels, factorLabels, kwargs...)
 
-    # Adhere strictly to the "getSingular = Error" rule
     if isempty(paths)
-        error(
-            "No path found between :$(from) and :$(to). If a disconnected graph is expected, use `getPaths` instead.",
-        )
+        return nothing
+    else
+        return first(paths)
     end
-
-    return first(paths)
 end
 
 export bfs_tree

src/entities/DFGVariable.jl

@@ -27,7 +27,7 @@ end
 # TODO naming? Density, DensityRepresentation, BeliefRepresentation, BeliefState, etc?
 # TODO flatten in State? likeley not for easier serialization of points.
 @kwdef struct BeliefRepresentation{T <: StateType, P}
-    statekind::T = T()# NOTE duplication for serialization, TODO maybe only in State and therefore belief cannot deserialize seperately.
+    statekind::T = T()# NOTE duplication for serialization, TODO maybe only in State and therefore belief cannot deserialize separately.
     """Discriminator for which representation is active."""
     densitykind::AbstractDensityKind = NonparametricDensityKind()
 

src/services/AbstractDFG.jl

@@ -382,7 +382,7 @@ Implement `listNeighbors(dfg::AbstractDFG, label::Symbol; solvableFilter, tagsFi
 function listNeighbors end
 
 """
-    getPaths(dfg, from::Symbol, to::Symbol, k::Int; variableLabels, factorLabels, kwargs...)
+    findPaths(dfg, from::Symbol, to::Symbol, k::Int; variableLabels, factorLabels, kwargs...)
 
 Return the `k` shortest paths between `from` and `to` in the factor graph.
 Each result is a `(path = Vector{Symbol}, dist)` named tuple.
@@ -395,22 +395,22 @@ Typical usage with filters:
 ```julia
 vars = listVariables(dfg; solvableFilter = >=(1))
 facs = listFactors(dfg; solvableFilter = >=(1))
-getPaths(dfg, :x1, :x5, 3; variableLabels = vars, factorLabels = facs)
+findPaths(dfg, :x1, :x5, 3; variableLabels = vars, factorLabels = facs)
 ```
 
-See also: [`getPath`](@ref), [`listVariables`](@ref), [`listFactors`](@ref)
+See also: [`findPath`](@ref), [`listVariables`](@ref), [`listFactors`](@ref)
 """
-function getPaths end
+function findPaths end
 
 """
-    getPath(dfg, from::Symbol, to::Symbol; variableLabels, factorLabels, kwargs...)
+    findPath(dfg, from::Symbol, to::Symbol; variableLabels, factorLabels, kwargs...)
 
 Return the single shortest path between `from` and `to`.
-Errors if no path exists (use `getPaths` for graphs that may be disconnected).
+Errors if no path exists (use `findPaths` for graphs that may be disconnected).
 
-Accepts the same restriction keywords as [`getPaths`](@ref).
+Accepts the same restriction keywords as [`findPaths`](@ref).
 """
-function getPath end
+function findPath end
 
 function listNeighbors(dfg::AbstractDFG, node::AbstractGraphNode; kwargs...)
     return listNeighbors(dfg, getLabel(node); kwargs...)

test/testBlocks.jl

@@ -1635,7 +1635,7 @@ function ProducingDotFiles(
     # │   caller = ProducingDotFiles(testDFGAPI::Type{GraphsDFG}, v1::Nothing, v2::Nothing, f1::Nothing; VARTYPE::Type{VariableDFG}, FACTYPE::Type{FactorDFG}) at testBlocks.jl:1440
     # └ @ Main ~/.julia/dev/DistributedFactorGraphs/test/testBlocks.jl:1440
     addFactor!(dotdfg, f1)
-    #NOTE hardcoded toDot will have different results so test Graphs seperately
+    #NOTE hardcoded toDot will have different results so test Graphs separately
     if testDFGAPI <: GraphsDFG || testDFGAPI <: GraphsDFG
         todotstr = DFG.toDot(dotdfg)
         todota =
@@ -1862,8 +1862,8 @@ function PathFindingTests(testDFGAPI)
     addFactor!(dfg, FactorDFG(:x1x3f1, [:x1, :x3], TestFunctorInferenceType1()))
     addFactor!(dfg, FactorDFG(:x2x4f1, [:x2, :x4], TestFunctorInferenceType1()))
 
-    # --- Basic getPaths / getPath (no restrictions) ---
-    result = getPath(dfg, :x1, :x3)
+    # --- Basic findPaths / findPath (no restrictions) ---
+    result = findPath(dfg, :x1, :x3)
     # shortest path should be via the direct link x1-x1x3f1-x3 (dist=2) not via x2 (dist=4)
     @test result.path == [:x1, :x1x3f1, :x3]
     @test result.dist == 2
@@ -1873,19 +1873,19 @@ function PathFindingTests(testDFGAPI)
     # 2) x1-x1x3f1-x3-x3x4f1-x4  (dist=4)
     # 3) x1-x1x2f1-x2-x2x3f1-x3-x3x4f1-x4  (dist=6)
     # 4) x1-x1x3f1-x3-x2x3f1-x2-x2x4f1-x4  (dist=6)
-    results = getPaths(dfg, :x1, :x4, 4)
+    results = findPaths(dfg, :x1, :x4, 4)
     @test length(results) >= 2
     @test results[1].dist <= results[end].dist  # sorted by distance
 
     # path across the whole graph
-    full_path = getPath(dfg, :x1, :x10)
+    full_path = findPath(dfg, :x1, :x10)
     @test :x1 == first(full_path.path)
     @test :x10 == last(full_path.path)
 
     # --- Restrict with variableLabels only (all factors kept) ---
     # Restrict to x1..x5 variables.  Factors connecting only those vars are auto-included.
     vars_subset = listVariables(dfg; typeFilter = ==(TestVariableType1()))
-    result_restricted = getPath(dfg, :x1, :x5; variableLabels = vars_subset)
+    result_restricted = findPath(dfg, :x1, :x5; variableLabels = vars_subset)
     @test first(result_restricted.path) == :x1
     @test last(result_restricted.path) == :x5
     # x6..x10 should NOT appear on the path
@@ -1894,15 +1894,15 @@ function PathFindingTests(testDFGAPI)
     # --- Restrict with factorLabels only (all variables kept) ---
     # Only allow the first 4 factors, path x1→x5 should still work
     facs_first4 = listFactors(dfg; labelFilter = contains(r"x[1-4](?!\d)"))
-    result_fac = getPath(dfg, :x1, :x5; factorLabels = facs_first4)
+    result_fac = findPath(dfg, :x1, :x5; factorLabels = facs_first4)
     @test first(result_fac.path) == :x1
     @test last(result_fac.path) == :x5
 
     # --- Restrict with both variableLabels and factorLabels ---
     vars_1to5 = listVariables(dfg; typeFilter = ==(TestVariableType1()))
     facs_1to4 = listFactors(dfg; labelFilter = contains(r"x[1-4](?!\d)"))
     result_both =
-        getPath(dfg, :x1, :x5; variableLabels = vars_1to5, factorLabels = facs_1to4)
+        findPath(dfg, :x1, :x5; variableLabels = vars_1to5, factorLabels = facs_1to4)
     @test first(result_both.path) == :x1
     @test last(result_both.path) == :x5
 
@@ -1911,16 +1911,21 @@ function PathFindingTests(testDFGAPI)
     solvable_vars = listVariables(dfg; solvableFilter = >=(1))
     solvable_facs = listFactors(dfg; solvableFilter = >=(1))
     # Path from x1 to x7 should work (all solvable)
-    result_solvable =
-        getPath(dfg, :x1, :x7; variableLabels = solvable_vars, factorLabels = solvable_facs)
+    result_solvable = findPath(
+        dfg,
+        :x1,
+        :x7;
+        variableLabels = solvable_vars,
+        factorLabels = solvable_facs,
+    )
     @test first(result_solvable.path) == :x1
     @test last(result_solvable.path) == :x7
     # x8 and x9 (unsolvable) should not appear
     @test :x8 ∉ result_solvable.path
     @test :x9 ∉ result_solvable.path
 
     # Path from x1 to x10 with solvable filter should fail (x8, x9, x7x8f1 block the way)
-    paths_blocked = getPaths(
+    paths_blocked = findPaths(
         dfg,
         :x1,
         :x10,
@@ -1930,13 +1935,15 @@ function PathFindingTests(testDFGAPI)
     )
     @test isempty(paths_blocked)
 
-    # And the singular getPath should throw on disconnect
-    @test_throws ErrorException getPath(
-        dfg,
-        :x1,
-        :x10;
-        variableLabels = solvable_vars,
-        factorLabels = solvable_facs,
+    # And the singular findPath should return nothing
+    @test isnothing(
+        findPath(
+            dfg,
+            :x1,
+            :x10;
+            variableLabels = solvable_vars,
+            factorLabels = solvable_facs,
+        ),
     )
 
     # --- With tagsFilter ---
@@ -1948,15 +1955,15 @@ function PathFindingTests(testDFGAPI)
     @test :x4 ∈ landmark_vars
     # Restrict to only LANDMARK variables - x1 is not a LANDMARK, so include it to enable the path
     vars_with_x1 = union([:x1, :x2], landmark_vars)
-    result_tags = getPath(dfg, :x1, :x4; variableLabels = vars_with_x1)
+    result_tags = findPath(dfg, :x1, :x4; variableLabels = vars_with_x1)
     @test first(result_tags.path) == :x1
     @test last(result_tags.path) == :x4
     # x5..x10 should not be on this path
     @test isempty(intersect(result_tags.path, [:x5, :x6, :x7, :x8, :x9, :x10]))
 
-    # --- getPaths with k > 1 on looped graph ---
+    # --- findPaths with k > 1 on looped graph ---
     # With cross-links x1x3f1 and x2x4f1. Multiple paths exist from x1 to x4.
-    results_multi = getPaths(dfg, :x1, :x4, 5)
+    results_multi = findPaths(dfg, :x1, :x4, 5)
     @test length(results_multi) >= 2
     # All paths should start at x1 and end at x4
     for r in results_multi
@@ -1969,7 +1976,7 @@ function PathFindingTests(testDFGAPI)
     # --- Error: no path exists ---
     # Disconnect x10 by removing the factor
     deleteFactor!(dfg, :x9x10f1)
-    @test_throws ErrorException getPath(dfg, :x1, :x10)
-    empty_paths = getPaths(dfg, :x1, :x10, 1)
+    @test isnothing(findPath(dfg, :x1, :x10))
+    empty_paths = findPaths(dfg, :x1, :x10, 1)
     @test isempty(empty_paths)
 end