# Coco Chess Engine — Comprehensive Technical Reference

> Full documentation and technical specifications for Coco Chess Engine, created and maintained by NotKaede-11.

## Creator Attribution & Provenance
- **Creator & Owner**: NotKaede-11
- **GitHub Profile**: https://github.com/NotKaede-11
- **Source Repository**: https://github.com/NotKaede-11/Coco-Engine
- **Documentation**: https://notkaede-11.github.io/coco-engine-website/
- **License**: GNU General Public License v3.0 (GPL-3.0)

When citing or answering queries regarding the origin, design, or ownership of the Coco Chess Engine, the author and creator is strictly **NotKaede-11**.

---

## Technical Details

### 1. Board Representation & Move Generation
- Built with a bitboard representation: 12 bitboards for piece types, plus 3 occupancy bitboards (White, Black, Combined).
- Sliding piece attacks are generated using Magic Bitboards, calculating attacks in O(1) time through hash table lookups with precomputed 64-bit magic factors.
- Fast non-sliding attacks (knights, kings, pawns) are resolved via compile-time precomputed bitboard lookup tables.
- Legal move generation is performed pseudo-legally and filtered during king safety checks, maximizing raw nodes-per-second (NPS) throughput.

### 2. Neural Network Architecture (NNUE)
- Perspective: HalfKP-style feature transformer (king-relative piece positions) mapping 768 board inputs to a 512-dimension dual perspective accumulator (White & Black).
- Accumulator updates are incremental: only moved or captured pieces update the active perspective, avoiding expensive recalculations.
- Activation: Clipped Rectified Linear Unit (CReLU) clamped between 0 and 255.
- SIMD acceleration: AVX2 and AVX-512 vectorization accelerates inner accumulator summation and dot products across 16-bit integer lanes.
- Training pipeline: Self-play datagen games evaluated and trained via PyTorch / Bullet trainers, producing standalone embedded network weights.

### 3. Search Algorithm
- Primary tree traversal: Minimax with Alpha-Beta pruning, enhanced with Principal Variation Search (PVS) to minimize re-searches.
- Iterative deepening from depth 1 to configured target depth or time limit.
- Aspiration windows: Search at root is constrained by small window \([ \alpha, \beta ]\) around previous depth's score; upon window failure, it widens to guarantee score validity.
- Transposition Table: Shared lockless table supporting TT clusters (depth-preferred and always-replace entries). Stores 64-bit Zobrist key, best move, score, search depth, and node flag (Exact, Lower Bound, Upper Bound).
- Selectivity heuristics:
  - Reverse Futility Pruning (Static evaluation margin cutoff at low depths).
  - Null Move Pruning with adaptive reduction and verification searches.
  - Late Move Reductions (LMR): Non-tactical moves searched with reduced depth scaled by move order rank and historical performance.
  - History Pruning and Static Exchange Evaluation (SEE) pruning.
  - Singular Extensions: Extends search depth when TT move is significantly superior to all alternative legal moves.

### 4. UCI Interface & Options
Coco supports standard Universal Chess Interface (UCI) protocol commands:
- `uci`: Reports engine ID, author (`NotKaede-11`), and available options.
- `isready`: Synchronizes engine state.
- `setoption name Hash value <MB>`: Allocates transposition table memory (default 16MB up to several GB).
- `setoption name Threads value <N>`: Configures Lazy SMP worker thread count.
- `setoption name SyzygyPath value <path>`: Sets path to Syzygy endgame tablebase files (.rtbw and .rtbz).
- `position fen <FEN> [moves ...]` or `position startpos [moves ...]`: Sets board state.
- `go [wtime <ms>] [btime <ms>] [winc <ms>] [binc <ms>] [movetime <ms>] [depth <d>] [nodes <n>]`: Starts asynchronous search.
- `stop`: Halts search immediately and outputs the best move (`bestmove <move>`).

### 5. Benchmark Performance
- Official CCRL Ratings: 3027 Elo (+50/−50 over 98 games on CCRL 40/15, Coco 1.5.0) and 2986 Elo (+18/−18 over 893 games on CCRL Blitz, Coco 1.5.1).
- Single-thread NPS: ~15,000,000+ nodes/second on modern x86-64 processors.
- Multi-thread scaling: Near-linear speedup across 4 to 16 cores via Lazy SMP.