# Implementation notes

## Sketch

The A* algorithm, stripped of all the code, is fairly simple. There are two sets, OPEN and CLOSED. The OPEN set contains those nodes that are candidates for examining. Initially, the OPEN set contains just one element: the starting position. The CLOSED set contains those nodes that have already been examined. Initially, the CLOSED set is empty. Graphically, the OPEN set is the "frontier" and the CLOSED set is the "interior" of the visited areas. Each node also keeps a pointer to its parent node so that we can determine how it was found.

There is a main loop that repeatedly pulls out the best node `n` in OPEN (the node with the lowest `f` value) and examines it. If `n` is the goal, then we're done. Otherwise, node `n` is removed from OPEN and added to CLOSED. Then, its neighbors `n'` are examined. A neighbor that is in CLOSED has already been seen, so we don't need to look at it (*). A neighbor that is in OPEN is scheduled to be looked at, so we don't need to look at it now (*). Otherwise, we add it to OPEN, with its parent set to `n`. The path cost to `n'`, `g(n')`, will be set to `g(n) + movementcost(n, n')`.

(*) I'm skipping a small detail here. You do need to check to see if the node's `g` value can be lowered, and if so, you re-open it.

    OPEN = priority queue containing START
    CLOSED = empty set
    while lowest rank in OPEN is not the GOAL:
      current = remove lowest rank item from OPEN
      add current to CLOSED
      for neighbors of current:
        cost = g(current) + movementcost(current, neighbor)
        if neighbor in OPEN and cost less than g(neighbor):
          remove neighbor from OPEN, because new path is better
        if neighbor in CLOSED and cost less than g(neighbor): **
          remove neighbor from CLOSED
        if neighbor not in OPEN and neighbor not in CLOSED:
          set g(neighbor) to cost
          add neighbor to OPEN
          set priority queue rank to g(neighbor) + h(neighbor)
          set neighbor's parent to current

    reconstruct reverse path from goal to start
    by following parent pointers

(**) This should never happen if you have an admissible heuristic. However in games we often have inadmissible heuristics.

## Source code

My own (old) C++ A* code is available: path.cpp and path.h, but it's not particularly easy to read. There is also an even older (slower, but easier to understand) version of my code, as well as many other implementations of A*, on Steve Woodcock's Games AI Page.

On the Internet, you can find C, C++, Visual Basic, Java [1] [2], Processing, Flash [1] [2], C# [1] [2], Delphi, Lisp, Python, Perl, and Prolog implementations of A*. Be sure to look at Justin Heyes-Jones's A* implementation in C++.

## Set representation

What's the first thing you'll think of using for the OPEN and CLOSED sets? If you're like me, you probably thought "array". You may have thought "linked list", too. There are many different data structures we can use, but to pick one we should look at what operations are needed.

There are three main operations we perform on the OPEN set: the main loop repeatedly finds the best node and removes it; the neighbor visiting will check whether a node is in the set; and the neighbor visiting will insert new nodes. Insertion and remove-best are operations typical of a priority queue.

The choice of data structure depends not only on the operations but on the number of times each operations runs. The membership test runs once for each neighbor for each node visited. Insertion runs once for each node being considered. Remove-best runs once for each node visited. Most nodes that are considered will be visited; the ones that are not are the fringe of the search space. When evaluating the cost of operations on these data structures, we need to consider the maximum size of the fringe (F).

In addition, there's a fourth operation, which is relatively rare but still needs to be implemented. If the node being examined is already in the OPEN set (which does happen frequently), and if its `f` value is better than the one already in the OPEN set (which is rare), then the value in the OPEN set must be adjusted. The adjustment operation involves removing the node (which is not the best `f`) and re-inserting it. These two steps may be optimized into one that moves the node.

### Unsorted arrays or linked lists

The simplest data structure is an unsorted array or list. Membership test is slow, O(F) to scan the entire structure. Insertion is fast, O(1) to append to the end. Finding the best element is slow, O(F) to scan the entire structure. Removing the best element is O(F) for arrays and O(1) for linked lists. The adjust operation is O(F) to find the node and O(1) to change its value.

### Sorted arrays

To make remove-best fast, we can keep the array sorted. Membership is then O(log F), since we can use binary search. Insertion is slow, O(F) to move all the elements to make space for the new one. Finding the best is fast, O(1) since it's already at the end. And removing the best is O(1) if we make sure the best sorts to the end of the array. The adjust operation is O(log F) to find the node and O(F) to change its value/position.

### Sorted linked lists

With sorted arrays, insertion was slow. If we use a linked list, we can make that fast. Membership in the linked list is slow, O(F) to scan the list. Insertion is fast, O(1) to insert a new link, but it was O(F) to find the right position for it. Finding the best remains fast, O(1) because the best is at the end. Removing the best also is O(1). The adjust operation is O(F) to find the node and O(1) to change its value/position.

### Sorted skip lists

Searching an unsorted linked list is slow. We can make that faster if we use a skip list instead of a linked list. With a skip list, membership is fast if you have the sort key: O(log F). Insertion is O(1) like a linked list if you know where to insert. Finding the best node is fast if the sort key is `f`, O(1), and removing a node is O(1). The adjust operation involves finding a node, removing it, and reinserting it.

If we use skip lists with the map location as the key, membership is O(log F), insertion is O(1) after we've performed the membership test, finding the best node is O(F), and removing a node is O(1). This is better than unsorted linked lists in that membership is faster.

If we use skip lists with the `f` value as the key, membership is O(F), insertion is O(1), finding the best node is O(1), and removing a node is O(1). This is no better than sorted linked lists.

### Indexed arrays

If the set of nodes is finite and reasonably sized, we can use a direct indexing structure, where an index function `i(n)` maps each node `n` to an index into an array. Unlike the unsorted and sorted arrays, which have a size corresponding to the largest size of OPEN, with an indexed array the array size is always `max(i(n))` over all `n`. If your function is dense (i.e., there are no indices unused), then `max(i(n))` will be the number of nodes in your graph. Whenever your map is a grid, it's easy to make the function dense.

Assuming `i(n)` is O(1), membership test is O(1), as we merely have to check whether `Array[i(n)]` contains any data. Insertion is O(1), as we just ste `Array[i(n)]`. Find and remove best is O(numnodes), since we have to search the entire structure. The adjust operation is O(1).

### Hash tables

Indexed arrays take up a lot of memory to store all the nodes that are not in the OPEN set. An alternative is to use a hash table, with a hash function `h(n)` that maps each node `n` into a hash code. Keep the hash table twice as big as N to keep the chance of collisions low. Assuming `h(n)` is O(1), membership test is expected O(1), insertion is expected O(1), and remove best is O(numnodes), since we have to search the entire structure. The adjust operation is O(1).

### Binary heaps

A binary heap (not to be confused with a memory heap) is a tree structure that is stored in an array. Unlike most trees, which use pointers to refer to children, the binary heap uses indexing to find children. C++ STL includes an efficient implementation of heaps, which I use in my own A* code.

In a binary heap, membership is O(F), as you have to scan the entire structure. Insertion is O(log F) and remove-best is O(log F). The adjust operation is tricky, with O(F) to find the node and suprisingly, only O(log F) to adjust it.

A friend of mine (who does research in data structures for shortest-path algorithms) says that binary heaps are good unless you have more than 10,000 elements in your fringe set. Unless your game's map is extremely large, you probably don't need a more complicated data structure (like multi-level buckets). You should probably stay away from Fibonacci heaps, which have good asymptotic performance but have slow implementations unless F is huge.

### Splay trees

Heaps are a tree-based structure with expected O(log F) time operations. However, the problem is that with A*, the common behavior is that you have a low cost node that is removed (causing O(log F) behavior, since values have to move up from the very bottom of the tree) followed by low cost nodes that are added (causing O(log F) behavior, since these values are added at the bottom and bubble up to the very top). The expected case behavior of heaps here is equivalent to the worst case behavior. We may be able to do better if we find a data structure where expected case is better, even if the worst case is no better.

Splay trees are a self adjusting tree structure. Any access to a node in the tree tends to bring that node up to the top. The result is a "caching" effect, where rarely used nodes go to the bottom and don't slow down operations. It doesn't matter how big your splay tree is, because your operations are only as slow as your "cache size". In A*, the low cost nodes are used a lot, and the high cost nodes aren't used for a long time, so those high cost nodes can move to the bottom of the tree.

With splay trees, membership, insertion, remove-best, and adjustment are all expected O(log F), worst case O(F). Typically however, the caching keeps the worst case from occurring. Dijkstra's algorithm and A* with an underestimating heuristic however have some peculiar characteristics that may keep splay trees from being the best. In particular, `f(n') >= f(n)` for nodes `n` and neighboring node `n'`. When this happens, it may be that the insertions all occur on one side of the tree and end up putting it out of balance. I have not tested this.

### HOT queues

There's another good data structure that may be better than heaps. Often, you can restrict the range of values that would be in the priority queue. Given a restricted range, there are often better algorithms. For example, sorting can be done on arbitrary values in O(N log N) time, but when there is a fixed range the bucket or radix sorts can perform sorting in O(N) time.

We can use HOT Queues (Heap On Top queues) to take advantage of `f(n') >= f(n)` where `n'` is a neighbor of `n`. We are removing the node `n` with minimal `f(n)`, and inserting neighbors `n'` with `f(n) <= f(n') <= f(n) + delta` where `delta <= C`. The constant `C` is the maximum change in cost from one point to an adjacent point. Since `f(n)` was the minimal `f` value in the OPEN set, and everything being inserted is `<= f(n) + delta`, we know that all `f` values in the OPEN set are within a range of `0 .. delta`. As in bucket/radix sort, we can keep "buckets" to sort the nodes in the OPEN set.

With K buckets, we reduce any O(N) cost to an average of O(N/K). With HOT queues, the topmost bucket uses a binary heap and all other buckets are unsorted arrays. Thus, its membership test for the top bucket is expected O(F/K), and insertion and remove-best are O(log (F/K)). Membership for the other buckets is O(F/K), insertion is O(1), and remove-best never occurs!. If the top bucket empties, then we need to convert the next bucket, an unsorted array, into a binary heap. It turns out this operation ("heapify") can be run in O(F/K) time. The adjust operation is best treated as a O(F/K) removal followed by an O(log (F/K)) or O(1) insertion.

In A*, many of the nodes we put into OPEN we never actually need. HOT Queues are a big win because the elements that are not needed are inserted in O(1) time. Only elements that are needed get heapified (which is not too expensive). The only operation that is more than O(1) is node deletion from the heap, which is only O(log (F/K)).

In addition, if `C` is small, we can just set K = C, and then we do not even need a heap for the smallest bucket, since all the nodes in a bucket have the same `f` value. Insertion and remove-best are both O(1) time! One person reported that HOT queues are as fast as heaps for at most 800 nodes in the OPEN set, and are 20% faster when there are at most 1500 nodes. I would expect that HOT queues get faster as the number of nodes increases.

A cheap variant of a HOT queue is a two-level queue: put good nodes into one data structure (a heap or an array) and put bad nodes into another data structure (an array or a linked list). Since most nodes put into OPEN are "bad", they are never examined, and there's no harm putting them into the big array.

### Comparison

It is important to keep in mind that we are not merely looking for asymptotic ("big O") behavior. We also want to look for a low constant. To see why, consider an algorithm that is O(log F) and another that is O(F), where F is the number of elements in the heap. It may be that on your machine, an implementation of the first algorithm takes 10,000 * log(F) seconds, while an implementation of the second one takes 2 * F seconds. For F = 256, the first would take 80,000 seconds and the second would take 512 seconds. The "faster" algorithm takes more time in this case, and would only start to be faster when F > 200,000.

You cannot merely compare two algorithms. You should also compare the implementations of those algorithms. You also have to know what size your data might be. In the above example, the first implementation is faster for F > 200,000, but if in your game, F stays under 30,000, then the second implementation would have been better.

None of the basic data structures is entirely satisfactory. Unsorted arrays or lists make insertion very cheap and membership and removal very expensive. Sorted arrays or lists make membership somewhat cheap, removal very cheap and insertion very expensive. Binary heaps make insertion and removal somewhat cheap, but membership is very expensive. Splay trees make everything somewhat cheap. HOT queues make insertions cheap, removals fairly cheap, and membership tests somewhat cheap. Indexed arrays make membership and insertion very cheap, but removals are incredibly expensive, and they can also take up a lot of memory. Hash tables perform similarly to indexed arrays, but they can take up a lot less memory in the common case, and removals are merely expensive instead of extremely expensive.

For a good list of pointers to more advanced priority queue papers and implementations, see Lee Killough's Priority Queues page.

### Hybrid representations

To get the best performance, you will want a hybrid data structure. For my A* code, I used an indexed array for O(1) membership test and a binary heap for O(log F) insertion and O(log F) remove-best. For adjustments, I used the indexed array for an O(1) test whether I really needed to perform the adjustment (by storing the `g` value in the indexed array), and then in those rare cases that I did need an adjustment, I used the O(F) adjustment on the binary heap. You can also use the indexed array to store the location in the heap of each node; this would give you O(log F) for adjustment.

## Interaction with the game loop

Interactive (especially real-time) games introduce requirements that affect your ability to compute the best path. It may be more important to get any answer than to get the best answer. Still, all other things being equal, a shorter path is better than a longer one.

In general, computing the part of the path close to the starting point is more important than the path close to the goal. The principle of immediate start: get the unit moving as soon as possible, even along a suboptimal path, and then compute a better path later. In real-time games, the latency of A* is often more important than its throughput.

Units can be programmed to follow either their instincts (simple movement) or their brains (a precalculated path). Units will follow their instincts unless their brains tell them otherwise. (This approach is used in nature and also in Rodney Brook's robot architecture.) Instead of calculating all the paths at once, limit the game to finding one path every one, two, or three game cycles. Then let the units start walking according to instinct (which could simply be moving in a straight line towards the goal), and come back later to find paths for them. This approach allows you to even out the cost of pathfinding so that it doesn't occur all at once.

### Early exit

It is possible to exit early from the A* main loop and get a partial path. Normally, the loop exits when it finds the goal node. However, at any point before that, it can return a path to the currently best node in OPEN. That node is our best chance of getting to the goal, so it's a reasonable place to go.

Candidates for early exit include having examined some number of nodes, having spent some number of milliseconds in the A* algorithm, or exploring a node some distance away from the starting position. When using path splicing, the spliced path should be given a smaller limit than a full path.

### Interruptible algorithm

If few objects need pathfinding services or if the data structures used to store the OPEN and CLOSED sets are small, it can be feasible to store the state of the algorithm, exit to the game loop, then continue where A* left off.

### Group movement

Path requests do not arrive evenly distributed. A common situation in a real-time strategy game is for the player to select multiple units and order them to move to the same goal. This puts a high load on the pathfinding system.

See Also: Putting paths together is called path splicing in another section of these notes.

In this situation, it is very likely that the path found for one will be useful for other units. One idea is to find a path `P` from the center of the units to the center of the destinations. Then, use most of that path for all the units, but replace the first 10 steps and the last 10 steps by paths that are found for each individual unit. Unit i will receive a path from its starting location to `P[10]`, followed by the shared path `P[10..len(P)-10]`, followed by a path from `P[len(P)-10]` to the destination.

The paths found for each unit are short (approximately 10 steps on average), and the long path is shared. Most of the path is found only once and shared among all the units. However, the user may not be impressed if he sees all the units moving on the same path. To improve the appearance of the system, make the units follow slightly different paths. One way to do this is to alter the paths themselves, by choosing adjacent locations.

Another approach is to make the units aware of each other (perhaps by picking a "leader" unit randomly, or by picking the one with the best sense of what's going on), and only find a path for the leader. Then use a flocking algorithm to make them move in a group.

Yet another approach is to take advantage of A*'s intermediate state. This state can be shared among multiple units traveling to the same goal, as long as those units share the same heuristic and cost functions. When the main loop exits, do not erase the OPEN and CLOSED sets; instead, start the next loop (with the starting position of the next unit) with the OPEN and CLOSED sets from the previous invocation of A*. (This can be considered a generalization of the Interruptible Algorithm and the Early Exit sections.)

### Refinement

If the map contains few obstacles, but instead contains terrain of varying costs, then an initial path can be computed by treating terrain as being cheaper than normal. For instance, if grasslands are cost 1, hills are cost 2, and mountains are cost 3, then A* will consider walking through 3 grasslands to avoid 1 mountain. Instead, compute an initial path by treating grasslands as 1, hills as 1.1, and mountains as 1.2. A* will then spend less time trying to avoid the mountains, and it will find a path quicker. (It approximates the benefits of an exact heuristic.) Once a path is known, the unit can start moving, and the game loop can continue. When spare CPU is available, compute a better path using the real movement costs.