Jan-Peter v. Hunnius
09a0777f96
Evaluator overhaul: - Add Supersonic LUT trie evaluator (32M-entry, O(n) hand evaluation) - Add Cactus Kev perfect-hash 5-card evaluator (prime-product hashing) - 3-tier evaluation priority: Supersonic → Cactus Kev → Algorithmic - DashMap-cached 7-card evaluation for lock-free concurrent access - Rewrite JumpTable around CactusKevEvaluator + DashMap cache Bot framework: - Add StrategyBot adapter (Strategy trait → HoldemPlayer) - Add register_bot_type() for plugin-style bot registration - Add strategy module with modular composable strategies Repository split: - Remove holdem_bots from workspace (moved to private super_marvin repo) - Remove holdem_bots dependency from holdem_sim - Update cash_game.toml to use built-in bots only - Clean up .gitignore (remove stale holdem_bots exclusion) - Delete plans/ directory (internal planning artifacts) Documentation: - Add ARCHITECTURE_SUPERSONIC_EVALUATOR.md - Add REFERENCES.md - Update ROADMAP.md and VISION.md - Remove outdated docs (ACHIEVEMENTS, RAKE, TOURNAMENT_RAKE, meerkat-alignment)
68 lines
3 KiB
Markdown
68 lines
3 KiB
Markdown
# Reference Implementations
|
||
|
||
## Java Supersonic Evaluator
|
||
|
||
The Rust Supersonic evaluator is a port of a Java implementation that uses a pre-computed trie for O(7) hand evaluation.
|
||
|
||
### Source Location
|
||
|
||
- **Path**: `/home/jan/Development/poker/old_bot/SNG-Testbed/src/pokerai/pokerbots/common/supersonic/`
|
||
|
||
### Key Files
|
||
|
||
| File | Purpose |
|
||
|------|---------|
|
||
| `LookupHandEvaluator.java` | Runtime evaluator — singleton that loads `HandRanks.dat` and provides 5/6/7-card evaluation via chain lookups |
|
||
| `generator/StateTableGenerator.java` | Offline table generator — builds the 32.5M-entry `hand_ranks` trie using two-pass algorithm |
|
||
| `generator/Flushes.java` | Flush and straight-flush ranking table — pre-computed hand rank values for suited hands |
|
||
| `generator/Unique.java` | Straight and high-card ranking table — pre-computed hand rank values for non-flush unsuited hands |
|
||
| `generator/Products.java` | Sorted unique 5-prime products — used during key normalization for the trie |
|
||
| `generator/Values.java` | Hand rank values by product position — maps sorted prime products to hand rank encodings |
|
||
| `test/CorrectnessTest.java` | Correctness validation — tests 5M random hands against a reference evaluator |
|
||
|
||
### Algorithm Notes
|
||
|
||
- The Java implementation uses `int[]` for the trie (32,487,834 entries)
|
||
- Card encoding: `rank * 4 + suit` (same as Rust's `PackedCard` index)
|
||
- Hand rank encoding: `(category << 12) | sub_rank` (16-bit packed)
|
||
- Root node starts at index 53 (indices 1–52 reserved for initial card offsets)
|
||
- The generator uses the Cactus Kev 5-card evaluator during table population
|
||
|
||
### Porting Considerations
|
||
|
||
- Java `int` is 32-bit signed → Rust `u32` (hand ranks are never negative)
|
||
- Java array initialization to 0 → Rust `vec![0u32; 32_487_834]`
|
||
- Java singleton pattern → Rust `OnceLock` or `Arc<SupersonicEvaluator>`
|
||
- Java `ObjectOutputStream` → Rust custom binary serialization with checksum
|
||
|
||
---
|
||
|
||
## Cactus Kev Algorithm
|
||
|
||
The existing Rust Cactus Kev implementation in [`cactus_kev.rs`](holdem_core/src/evaluator/cactus_kev.rs) was based on the original Cactus Kev algorithm.
|
||
|
||
### Source References
|
||
|
||
- **Original**: http://suffe.coolpage.cash/poker/evaluator.html (archived)
|
||
- **Algorithm**: Uses prime number products to create perfect hashes for 5-card hand equivalence classes
|
||
- **Tables**: 1,287 flush entries + 6,175 unsuited entries = 7,462 total lookup entries
|
||
|
||
### Relationship to Supersonic
|
||
|
||
The Cactus Kev evaluator serves two roles in the Supersonic architecture:
|
||
1. **Build-time dependency**: Used by the table generator to evaluate 5-card hands
|
||
2. **Runtime fallback**: Used when the Supersonic LUT file is not available
|
||
|
||
---
|
||
|
||
## Other References
|
||
|
||
### Meerkat API (Java)
|
||
|
||
- **Purpose**: Reference API for bot interface design
|
||
|
||
### Algorithmic Evaluator
|
||
|
||
- **Location**: [`algorithmic_evaluator.rs`](holdem_core/src/evaluator/algorithmic_evaluator.rs)
|
||
- **Purpose**: Rule-based evaluator used as correctness oracle
|
||
- **Note**: Not ported from Java; implemented directly in Rust from poker hand ranking rules
|