jan/rusty_marvin
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

docs: clean up documentation - remove obsolete architecture docs, simplify roadmap and vision, update READMEs

Browse source 
- Delete ARCHITECTURE_HAND_LOGGING_TOURNAMENT_IMPROVEMENTS.md (implemented)
- Delete ARCHITECTURE_SUPERSONIC_EVALUATOR.md (implemented)
- Delete REFERENCES.md (no longer needed)
- Simplify ROADMAP.md: remove Phases 4-7 (live server, advanced bots)
- Simplify VISION.md: focus on simulation testbed only
- Update README.md: dual evaluator architecture, fix broken links
- Update holdem_core/README.md: fix title, add Supersonic evaluator docs
This commit is contained in:
Jan-Peter von Hunnius 2026-05-25 12:19:44 +02:00
parent 09a0777f96
commit 14c56485e7
7 changed files with 87 additions and 1492 deletions
Download patch file Download diff file Expand all files Collapse all files

31
holdem_core/README.md
View file

@ -1,11 +1,12 @@
# Math Library - High-Performance Poker Hand Evaluation
# holdem_core - High-Performance Poker Hand Evaluation
A state-of-the-art Rust library for ultra-fast poker hand evaluation using Cactus Kev's perfect hash algorithm. This library provides sub-microsecond hand evaluation for Texas Hold'em poker hands with a tiny memory footprint (~100 KB for lookup tables).
A state-of-the-art Rust library for ultra-fast poker hand evaluation featuring two evaluators: the **Cactus Kev** perfect-hash evaluator (~100 KB tables) and the **Supersonic** LUT trie evaluator (~124 MB tables). Supports 5, 6, and 7-card Texas Hold'em hands.
## 🚀 Features
- **Ultra-Fast Evaluation**: Sub-microsecond hand evaluation using Cactus Kev perfect hashing
- **Memory Efficient**: Only ~100 KB for lookup tables (7,462 entries) — no multi-GB trie
- **Dual Evaluators**: Cactus Kev (compact ~100 KB) and Supersonic LUT trie (~124 MB) hand evaluators
- **Ultra-Fast Evaluation**: Sub-microsecond hand evaluation using perfect hash or O(n) trie lookups
- **Memory Options**: Choose between ~100 KB Cactus Kev tables or ~124 MB Supersonic trie depending on use case
- **Zero Collisions**: Validated against all 2,598,960 five-card hands
- **Thread Safe**: Singleton pattern with lazy initialization for shared resources
- **Mathematically Correct**: Comprehensive property-based testing and validation
@ -26,15 +27,20 @@ A state-of-the-art Rust library for ultra-fast poker hand evaluation using Cactu
## 🏗️ Architecture
The library uses a **Cactus Kev perfect hash** algorithm for 5-card evaluation and a **caching enumeration** strategy for 7-card hands:
The library provides **two hand evaluators** with different performance/memory tradeoffs:
### Cactus Kev Evaluator (compact)
- **5-card evaluation**: O(1) via prime-product hashing into two small tables (7,462 entries total, ~30 KB). Each rank maps to a prime; the product of 5 primes uniquely identifies the hand. Zero collisions, validated against all 2,598,960 hands.
- **7-card evaluation**: Amortized O(1) via C(7,5)=21 enumeration over the 5-card tables, with a `HashMap` cache keyed by the product of 52 distinct card primes.
### Supersonic Evaluator (high-throughput)
- **5/6/7-card evaluation**: O(n) array lookups via a pre-computed LUT trie (~124 MB, 32,487,834 `u32` entries). No enumeration or hashing needed — each card is a single array dereference. Packed 16-bit hand rank format (category + equivalency class).
Key modules:
- [`evaluator`] - Core hand evaluation engine with public `Evaluator` API
- [`evaluator::cactus_kev`] - Cactus Kev perfect-hash 5-card evaluator
- [`evaluator::supersonic`] - Supersonic LUT trie evaluator (5/6/7-card)
- [`evaluator::tables`] - `JumpTable` wrapper around Cactus Kev + 7-card cache
- [`evaluator::algorithmic_evaluator`] - Rule-based evaluator (correctness oracle)
- [`evaluator::singleton`] - Thread-safe singleton pattern for shared evaluator instance
@ -100,20 +106,20 @@ Add this to your `Cargo.toml`:
```toml
[dependencies]
math = { path = "./math" }
holdem_core = { path = "./holdem_core" }
holdem_core = "0.1.0"
```
## 📚 Documentation
### API Documentation
- **[Crate Documentation](https://docs.rs/math)** - Complete API reference
- **[Examples](math/src/evaluator/examples.rs)** - Comprehensive usage examples
- **[Benchmarks](math/src/evaluator/benchmarks.rs)** - Performance characteristics
- **[Crate Documentation](https://docs.rs/holdem_core)** - Complete API reference
- **[Examples](src/evaluator/examples.rs)** - Comprehensive usage examples
- **[Benchmarks](src/evaluator/benchmarks.rs)** - Performance characteristics
### Module Documentation
- **[Evaluator Module](src/evaluator/evaluator.rs)** - Core evaluation engine and public API
- **[Cactus Kev Module](src/evaluator/cactus_kev.rs)** - 5-card perfect hash evaluator
- **[Supersonic Module](src/evaluator/supersonic.rs)** - LUT trie evaluator (5/6/7-card)
- **[Tables Module](src/evaluator/tables.rs)** - JumpTable with Cactus Kev + 7-card cache
- **[File I/O Module](src/evaluator/file_io.rs)** - Persistent storage
- **[Integration Module](src/evaluator/integration.rs)** - holdem_core integration
@ -296,16 +302,17 @@ This project is licensed under the MIT License - see the LICENSE file for detail
## 🙏 Acknowledgments
- **Cactus Kev**: Original perfect hash algorithm implementation
- **Supersonic**: LUT trie evaluator for high-throughput hand evaluation
- **PokerStove**: Inspiration for lookup table approach
- **Rust Community**: Excellent tools and libraries for systems programming
## 🔗 Links
- **[Repository](https://github.com/yourusername/rusty-marvin)**
- **[Documentation](https://docs.rs/math)**
- **[Documentation](https://docs.rs/holdem_core)**
- **[Issues](https://github.com/yourusername/rusty-marvin/issues)**
- **[Discussions](https://github.com/yourusername/rusty-marvin/discussions)**
---
**Built with ❤️ for the poker and Rust communities**
**Built with ❤️ for the poker and Rust communities**