How akashgupta-26/polarity works
Project Type and Purpose
• Polarity is a standalone, high-performance chess engine written in C/C++.
• It exposes (implicitly) a command-line or library interface (the “engine.cpp” entry point), and supports perft benchmarking (“perftValidate.cpp” + “perftSuite.txt”).
File Structure
Top-level files each map to one logical module:
• engine.cpp – Main driver / search orchestration
• perftValidate.cpp – Perft tester harness
• board.h – Bitboard representation & state management
• constants.h – Global constants (e.g. piece codes, castling flags)
• precalculated_move_tables.h – Lookup tables for knight/king moves & magic-bitboard data
• moves.h – Pseudo-legal move generation logic
• search.h – Search routines (minimax, alpha-beta, quiescence, pruning)
• evaluate.h – Tapered evaluation (PeSTO tables, piece-square tables, king safety)
• random.h – Utility for any randomized testing or hashing
• perftSuite.txt – Perft positions & expected node counts
Extract Architectural Patterns
• Layered pipeline: Board State → Move Generation → Search (with perft & transposition) → Evaluation.
• Data‐driven tables (precalc_move_tables) feed Move Generation & Evaluation.
• Search uses recursive calls (stackful take-back) + transposition hash + ordering heuristics.
Main System Components
A. Interface / Entry Points
• CLI / UCI Handler (in engine.cpp)
• Perft Harness (in perftValidate.cpp)
B. Core Engine Modules
1. Board Manager
– Maintains 12 piece bitboards + occupancy bitboards + castling/en-passant/side flags
2. Move Generator
– Pawn pushes (bit shifts)
– Lookup (knight/king) & magic bitboards (bishop/rook/queen)
– Pseudo-legal moves only (legality deferred)
3. Search Controller
– Minimax with Alpha-Beta
– Iterative Deepening, Quiescence, Aspiration Windows
– Null-move pruning, Late-move reductions
– Move ordering: MVV-LVA, History, Killer, PV
– Transposition Table (hash table stored in memory)
4. Evaluation Engine
– Tapered PeSTO tables (middlegame/endgame weights)
– Piece-square tables
– Pawn structure masks, king safety, mop-up endgame heuristic
C. Data & Utilities
• Precomputed Tables (shared by Move Generator & Evaluation)
• Random / Hashing utilities (for transposition keys)
Relationships & Data Flow
• User input → Engine Entry Point
• Engine → Board Manager (initialize position)
• Board Manager → Move Generator (generate moves)
• Move Generator → Search Controller (branch & recurse)
• Search Controller ↔ Evaluation Engine (leaf evaluation calls)
• Search Controller ↔ Board Manager (makeMove / takeBack interactions)
• Search Controller ↔ Transposition Table (probe & store)
• Engine Entry Point → Perft Harness (on perft command) → Board Manager / Move Generator (benchmark)
Architectural Patterns & Principles
• Single Responsibility: each .h/.cpp pair implements one concern
• Layering: clear separation of state, generation, search, evaluation
• Data locality & performance: bitboards + precalc tables
• Modular design: can swap or extend search / eval heuristics