# 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