Scurry.Astar (Scurry v3.0.0)

View Source

Implementation of A-star search algorithm to find the shortest path in graphs or 2D polygon maps.

Basic usage is;

# Define function for the heuristic cost between two nodes
def heur_fun(node_a, node_b) do
  ... returns the cost of node a to node b
end

# Define a graph
graph = %{
  node_1 => [
    {node_2, cost_1_to_2}, {node_3, cost_1_to_3},
  ],
  node_2 => [
    {node_3, cost_2_to_3}, {node_4, cost_2_to_4},
  ],
  ...
}

# Do A-star search
state = Astar.search(graph, node_1, node_z, &heur_fun/2)

# Extract path from the state
path = Astar.path(state)
[node1, ..., node_z]

See Quickstart for a concrete end-to-end example of defining a world and holes/obstacles, then using PolygonMap and Astar modules to do path finding within this.

Summary

Types

The cost of a traversel between two nodes is a numeric value

Function that given two gnode/0 graph nodes, computes the cost. Eg. a euclidian 2D vector function like Scurry.Vector.distance/2. (gnode, gnode -> cost)

A graph node (spelled gnode since node is reserved) is any type that can be used as a key in a map/0 For instance a t:vector/0.

A graph is a map from gnode/0 to a list of gnode/0 and the traversal cost/0, %{gnode => [{gnode, cost}, ...]}

The internal state of the A-star algorithm. Use path/1 to extract the result.

Functions

Get the path from the state returned by search/4.

Find shortest path in graph from start to stop.

Types

cost()

@type cost() :: number()

The cost of a traversel between two nodes is a numeric value

cost_fun()

@type cost_fun() :: (gnode(), gnode() -> cost())

Function that given two gnode/0 graph nodes, computes the cost. Eg. a euclidian 2D vector function like Scurry.Vector.distance/2. (gnode, gnode -> cost)

gnode()

@type gnode() :: any()

A graph node (spelled gnode since node is reserved) is any type that can be used as a key in a map/0 For instance a t:vector/0.

graph()

@type graph() :: %{required(gnode()) => {gnode(), cost()}}

A graph is a map from gnode/0 to a list of gnode/0 and the traversal cost/0, %{gnode => [{gnode, cost}, ...]}

state()

@opaque state()

The internal state of the A-star algorithm. Use path/1 to extract the result.

Functions

path(state)

@spec path(state()) :: [gnode()]

Get the path from the state returned by search/4.

Params

  • state the a-star state returned by search/4

Returns

The path as a list of nodes. The type of the node is the same as in the graph/0 used in the call to search/4.

search(graph, start, stop, heur_fun)

@spec search(graph(), gnode(), gnode(), cost_fun()) :: state()

Find shortest path in graph from start to stop.

Params

  • graph a map of node to a list of nodes and cost tuples.
  • start the node from which to start
  • stop the node at which to end
  • heur_fun the heuristic function used to estimate cost from a node in graph to stop. It takes two nodes and returns a cost that should be comparable with itself for ordering. node, node :: term.

Returns

The algorithms internal state which can be passed to path/1 to obtain the actual path.