# Sudoku Solver in C++

A comprehensive Sudoku solver implementation in C++ using backtracking algorithm with constraint checking optimizations.

## Features

- **Backtracking Algorithm**: Efficient recursive solving with constraint validation
- **Input Validation**: Comprehensive validation of puzzle inputs
- **Performance Metrics**: Tracks solving time and backtrack count
- **Formatted Output**: Clean, readable grid display
- **Error Handling**: Robust handling of invalid puzzles
- **Multiple Test Cases**: Includes easy and hard puzzle examples

## Project Structure

```
├── SudokuSolver.h      # Header file with class declaration
├── SudokuSolver.cc     # Implementation of the solver class
├── main.cc             # Demo program with example puzzles
├── Makefile_sudoku     # Build configuration
└── README_sudoku.md    # This documentation
```

## Building the Project

### Prerequisites
- C++ compiler with C++11 support (g++, clang++)
- Make utility

### Build Commands

```bash
# Build the project
make -f Makefile_sudoku

# Build and run
make -f Makefile_sudoku run

# Debug build
make -f Makefile_sudoku debug

# Release build (optimized)
make -f Makefile_sudoku release

# Clean build artifacts
make -f Makefile_sudoku clean
```

## Usage

### Running the Demo
```bash
./sudoku_solver
```

The demo program includes:
- Easy level puzzle example
- Hard level puzzle example  
- Invalid puzzle test case
- Performance timing and statistics

### Using the SudokuSolver Class

```cpp
#include "SudokuSolver.h"

// Create solver instance
SudokuSolver solver;

// Load puzzle (0 represents empty cells)
std::vector<std::vector<int>> grid(9, std::vector<int>(9));
// ... populate grid with puzzle data ...

// Solve the puzzle
if (solver.SolvePuzzle(grid)) {
    std::cout << "Solution found!" << std::endl;
    solver.PrintGrid(grid);
    
    // Get performance metrics
    std::cout << "Backtracks: " << solver.GetBacktrackCount() << std::endl;
} else {
    std::cout << "No solution exists." << std::endl;
}
```

## Algorithm Details

### Backtracking Approach
1. **Find Empty Cell**: Locate the next empty cell (value 0)
2. **Try Numbers**: Attempt to place numbers 1-9 in the cell
3. **Validate Constraints**: Check if number violates Sudoku rules:
   - No duplicates in the same row
   - No duplicates in the same column  
   - No duplicates in the same 3x3 subgrid
4. **Recursive Solve**: If valid, recursively solve remaining puzzle
5. **Backtrack**: If no solution found, remove number and try next

### Constraint Checking
- **Row Validation**: Ensures no duplicate numbers in any row
- **Column Validation**: Ensures no duplicate numbers in any column
- **Subgrid Validation**: Ensures no duplicate numbers in any 3x3 box
- **Input Validation**: Verifies puzzle format and initial state validity

## Performance Characteristics

- **Time Complexity**: O(9^(n*n)) worst case, where n=9 for standard Sudoku
- **Space Complexity**: O(n*n) for the grid storage
- **Optimization**: Early constraint checking reduces search space significantly
- **Typical Performance**: Most puzzles solve in microseconds to milliseconds

## Code Style

This implementation follows established C++ coding standards:
- **Naming Conventions**: PascalCase for classes/methods, camelCase with prefixes for members
- **File Organization**: Separate header (.h) and implementation (.cc) files
- **Documentation**: Comprehensive Doxygen-style comments
- **Error Handling**: Robust validation and error reporting
- **Memory Management**: Safe use of STL containers

## Example Output

```
=== Sudoku Solver Demo ===

--- Puzzle 1 (Easy) ---
Original puzzle:

+-------+-------+-------+
| 5 3 . | . 7 . | . . . | 
| 6 . . | 1 9 5 | . . . | 
| . 9 8 | . . . | . 6 . | 
+-------+-------+-------+
| 8 . . | . 6 . | . . 3 | 
| 4 . . | 8 . 3 | . . 1 | 
| 7 . . | . 2 . | . . 6 | 
+-------+-------+-------+
| . 6 . | . . . | 2 8 . | 
| . . . | 4 1 9 | . . 5 | 
| . . . | . 8 . | . 7 9 | 
+-------+-------+-------+

Solution found!

+-------+-------+-------+
| 5 3 4 | 6 7 8 | 9 1 2 | 
| 6 7 2 | 1 9 5 | 3 4 8 | 
| 1 9 8 | 3 4 2 | 5 6 7 | 
+-------+-------+-------+
| 8 5 9 | 7 6 1 | 4 2 3 | 
| 4 2 6 | 8 5 3 | 7 9 1 | 
| 7 1 3 | 9 2 4 | 8 5 6 | 
+-------+-------+-------+
| 9 6 1 | 5 3 7 | 2 8 4 | 
| 2 8 7 | 4 1 9 | 6 3 5 | 
| 3 4 5 | 2 8 6 | 1 7 9 | 
+-------+-------+-------+

Solving time: 245 microseconds
Backtracks: 0
```

## License

This project is licensed under the Apache License 2.0. See the license headers in source files for details.

## Contributing

When contributing to this project, please:
1. Follow the established C++ coding style
2. Add appropriate unit tests for new features
3. Update documentation for any API changes
4. Ensure all existing tests pass