Summary

Adds the A (A-Star) pathfinding algorithm* to the Graph algorithms collection. A* is a fundamental pathfinding algorithm that finds the shortest path between nodes using heuristic search, widely used in games, robotics, and navigation systems.

Motivation and Context

A* is a well-established algorithm from reputable academic sources:

• "Artificial Intelligence: A Modern Approach" by Russell and Norvig
• "Introduction to Algorithms" (CLRS)
• Original paper by Hart, Nilsson, and Raphael (1968)

This algorithm was missing from the repository and is essential for:

• Game AI: Character pathfinding in games
• Robotics: Robot navigation and obstacle avoidance
• Route Planning: GPS and map applications
• Network Routing: Optimal packet routing
• Maze Solving: Finding shortest paths in mazes

Implementation Details

Core Features

1. Generic FindPath Method

   • Works with any node type (string, int, custom classes)
   • Custom neighbor function for flexible graph representation
   • Custom heuristic function for domain-specific optimization
   • Returns shortest path or null if no path exists

2. Grid Pathfinding

   • Specialized FindPathInGrid for 2D grid navigation
   • Support for obstacles (walkable/non-walkable cells)
   • Cardinal movement (up, down, left, right)
   • Optional diagonal movement with proper cost (√2)
   • Manhattan distance heuristic for cardinal movement
   • Euclidean distance heuristic for diagonal movement

3. Path Cost Calculation

   • CalculatePathCost utility method
   • Computes total cost of a path
   • Supports variable edge costs

Algorithm Properties

• Time Complexity: O(E log V) with priority queue
• Space Complexity: O(V) for storing scores and paths
• Optimality: Finds optimal path with admissible heuristics
• Completeness: Always finds a path if one exists

Technical Implementation

✅ Uses PriorityQueue<T, double> for efficient node selection

✅ Maintains gScore (cost from start) and fScore (estimated total cost)

✅ Reconstructs path from goal to start using cameFrom dictionary

✅ Proper handling of edge cases (null inputs, out of bounds, obstacles)

✅ Generic type support with notnull constraint

✅ Comprehensive XML documentation

Testing

30 comprehensive test cases (456 lines):

Generic Graph Tests (6 tests)

• Simple linear paths
• Multiple path selection (chooses shortest)
• Disconnected graphs (returns null)
• Start equals goal (single node path)
• Heuristic-guided search
• Null parameter validation

Grid Pathfinding Tests (11 tests)

• Simple 3x3 grids
• Obstacle avoidance
• No path scenarios (blocked by walls)
• Diagonal vs cardinal movement
• Large grids (10x10)
• Complex mazes
• Boundary validation
• Walkable cell validation

Path Cost Tests (4 tests)

• Simple uniform costs
• Variable edge costs
• Single node paths
• Empty paths

Integer Node Tests (1 test)

• Demonstrates flexibility with different node types

Exception Handling (8 tests)

• Null start/goal/grid
• Out of bounds positions
• Non-walkable start/goal

All tests pass successfully ✅

Use Case Examples

Example 1: Simple Graph Pathfinding

IEnumerable<(string, double)> GetNeighbors(string node) => node switch
{
    "A" => new[] { ("B", 1.0), ("C", 4.0) },
    "B" => new[] { ("D", 2.0) },
    "C" => new[] { ("D", 1.0) },
    _ => Array.Empty<(string, double)>(),
};

double Heuristic(string a, string b) => 0; // Dijkstra mode

var path = AStar.FindPath("A", "D", GetNeighbors, Heuristic);
// Result: ["A", "B", "D"] (cost: 3)

Example 2: Grid Pathfinding (Game AI)

var grid = new bool[,]
{
    { true, true, false, true },
    { true, false, true, true },
    { true, true, true, true },
};

var path = AStar.FindPathInGrid(grid, (0, 0), (2, 3), allowDiagonal: true);
// Finds shortest path avoiding obstacles

Files Changed

• Algorithms/Graph/AStar.cs (212 lines)
• Algorithms.Tests/Graph/AStarTests.cs (456 lines)

Total: 668 lines of production-quality code

Checklist

• ✅ I have performed a self-review of my code
• ✅ My code follows the style guidelines of this project
• ✅ I have added tests that prove my feature works
• ✅ New and existing unit tests pass locally with my changes
• ✅ Comments are up to date
• ✅ I have added comments to hard-to-understand areas
• ✅ Comprehensive XML documentation added

Contribution by Gittensor, learn more at https://gittensor.io/