Add A* (A-Star) pathfinding algorithm

[0xsatoshi99]

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/

[codecov]

Codecov Report

❌ Patch coverage is 99.12281% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 96.93%. Comparing base (9cf588d) to head (4bda3f1).

Files with missing lines	Patch %	Lines
Algorithms/Graph/AStar.cs	99.12%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@ Coverage Diff @@ ## master #573 +/- ## ========================================== + Coverage 96.91% 96.93% +0.02%  ========================================== Files 296 297 +1 Lines 12208 12322 +114 Branches 1770 1792 +22 ========================================== + Hits 11831 11944 +113  Misses 239 239 - Partials 138 139 +1 

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[0xsatoshi99]

@siriak Please check this PR, thanks.

[siriak]

It's already implemented here

C-Sharp/Algorithms/Search/AStar/AStar.cs

Line 6 in 9cf588d

public static class AStar