docs: clean up documentation - remove obsolete architecture docs, simplify roadmap and vision, update READMEs
- 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:
parent
09a0777f96
commit
14c56485e7
7 changed files with 87 additions and 1492 deletions
160
README.md
160
README.md
|
|
@ -1,16 +1,16 @@
|
|||
# Poker Testbed - Java-Compatible Hand Evaluator for Bot Testing
|
||||
# Poker Simulation Testbed
|
||||
|
||||
[](https://crates.io/crates/holdem_core)
|
||||
[](https://docs.rs/holdem_core)
|
||||
[](LICENSE)
|
||||
|
||||
A comprehensive poker bot testing framework with Java-compatible hand evaluation. This library implements the Meerkat API algorithm with full Java compatibility, specifically designed for automated poker bot testing, development, and integration with existing poker tools.
|
||||
A comprehensive poker simulation testbed and unit test framework for bot development. Features two Rust-native hand evaluators — the **Cactus Kev** perfect-hash evaluator (~100 KB tables) and the **Supersonic** LUT trie evaluator (~124 MB tables) — designed for automated poker bot testing, strategy analysis, and simulation at scale.
|
||||
|
||||
## Recent Updates
|
||||
|
||||
- **🚀 Perfect Hash Jump Table**: Revolutionary 79% memory reduction (625MB → ~130MB) with enhanced performance
|
||||
- **Suit Canonicalization**: Advanced isomorphic hand reduction for optimal memory usage
|
||||
- **Bottom-up Trie Construction**: Cache-optimized memory layout for improved evaluation speed
|
||||
- **Supersonic Evaluator**: New high-throughput LUT trie evaluator (~124 MB) for O(n) hand evaluation
|
||||
- **Dual Evaluator Architecture**: Choose between Cactus Kev (compact) and Supersonic (fast) per use case
|
||||
- **Simulation Testbed**: Run cash games, SNGs, and MTTs with configurable bots via TOML
|
||||
- **Input Validation**: Added comprehensive validation to `Card::new()` ensuring rank (0-12) and suit (0-3) are within valid ranges
|
||||
- **Enhanced Documentation**: All public methods now include working code examples and panic condition documentation
|
||||
- **Error Handling**: Improved error handling throughout the codebase with proper `Result` types
|
||||
|
|
@ -18,30 +18,39 @@ A comprehensive poker bot testing framework with Java-compatible hand evaluation
|
|||
## Features
|
||||
|
||||
- **Bot Testing Framework**: Specifically designed for automated poker bot testing and development
|
||||
- **Blazing Fast**: O(1) hand evaluation using perfect hash jump tables
|
||||
- **Memory Efficient**: ~130MB for complete evaluation tables (79% reduction from 625MB)
|
||||
- **Perfect Hash Jump Tables**: Revolutionary memory optimization with suit canonicalization
|
||||
- **Standards Compliant**: Based on proven poker evaluation algorithms with Java compatibility
|
||||
- **Multi-Hand Support**: Evaluate 5, 6, or 7-card poker hands with Java-compatible results
|
||||
- **Dual Evaluators**: Cactus Kev (compact ~100 KB) and Supersonic LUT trie (~124 MB) hand evaluators
|
||||
- **Blazing Fast**: Sub-microsecond hand evaluation using perfect hash and trie-based lookup
|
||||
- **Memory Efficient**: Choose between compact Cactus Kev tables or high-throughput Supersonic trie
|
||||
- **Standards Compliant**: Based on proven poker evaluation algorithms
|
||||
- **Multi-Hand Support**: Evaluate 5, 6, or 7-card poker hands
|
||||
- **Texas Hold'em Ready**: Optimized for Texas Hold'em bot analysis and testing
|
||||
- **Comprehensive Testing**: Extensive test suite with millions of verification cases
|
||||
- **Deterministic Results**: Consistent hand evaluation for reproducible bot testing
|
||||
- **Tool Integration**: Compatible with existing Java poker tools and frameworks
|
||||
- **Simulation Engine**: Run cash games, SNGs, and MTTs with configurable bots via TOML
|
||||
|
||||
## Performance
|
||||
|
||||
| Hand Type | Evaluation Time | Combinations Evaluated |
|
||||
|-----------|----------------|----------------------|
|
||||
| 5-Card | ~10-20ns | Direct lookup |
|
||||
| 6-Card | ~50-80ns | 6 combinations |
|
||||
| 7-Card | ~150-250ns | 21 combinations |
|
||||
### Cactus Kev Evaluator
|
||||
|
||||
| Hand Type | Evaluation Time | Method |
|
||||
|-----------|----------------|--------|
|
||||
| 5-Card | ~50-100ns | Single prime-product hash → table lookup |
|
||||
| 6-Card | ~300-500ns | Six 5-card lookups |
|
||||
| 7-Card | ~1-2µs | 21 enumeration + HashMap cache |
|
||||
|
||||
### Supersonic Evaluator
|
||||
|
||||
| Hand Type | Evaluation Time | Method |
|
||||
|-----------|----------------|--------|
|
||||
| 5-Card | O(5) array lookups | Direct trie traversal |
|
||||
| 6-Card | O(6) array lookups | Direct trie traversal |
|
||||
| 7-Card | O(7) array lookups | Direct trie traversal |
|
||||
|
||||
## Documentation
|
||||
|
||||
For detailed project information, see:
|
||||
|
||||
- **[VISION.md](docs/VISION.md)** - Project goals and architectural vision
|
||||
- **[ACHIEVEMENTS.md](docs/ACHIEVEMENTS.md)** - Completed milestones and success metrics
|
||||
- **[ROADMAP.md](docs/ROADMAP.md)** - Future development phases and implementation plan
|
||||
|
||||
## Installation
|
||||
|
|
@ -90,16 +99,15 @@ println!("Hand rank: {:?}", hand_value.rank);
|
|||
This framework provides specialized capabilities for poker bot testing and development:
|
||||
|
||||
### Automated Bot Testing
|
||||
- **Standardized Evaluation**: Java-compatible hand evaluation for consistent bot testing
|
||||
- **Standardized Evaluation**: Consistent hand evaluation across both Cactus Kev and Supersonic evaluators
|
||||
- **Performance Benchmarking**: Fast evaluation for large-scale bot performance testing
|
||||
- **Range Analysis**: Efficient hand range evaluation for bot strategy analysis
|
||||
- **Decision Tree Testing**: Quick hand strength calculation for bot decision trees
|
||||
|
||||
### Java Tool Integration
|
||||
- **Cross-Platform Compatibility**: Works seamlessly with existing Java poker tools
|
||||
- **Consistent Results**: Identical hand rankings to Java Meerkat API
|
||||
- **Tool Chain Integration**: Compatible with Java-based poker analysis frameworks
|
||||
- **Bot Framework Support**: Integrates with popular Java poker bot frameworks
|
||||
### Dual Evaluator Support
|
||||
- **Cactus Kev**: Compact ~100 KB tables with prime-product hashing — ideal for memory-constrained environments
|
||||
- **Supersonic**: High-throughput ~124 MB LUT trie with O(n) array lookups — fastest for bulk evaluation
|
||||
- **Algorithmic Fallback**: Rule-based evaluator serves as correctness oracle for validation
|
||||
|
||||
### Bot Development Features
|
||||
- **Hole Card Analysis**: Fast evaluation of starting hand strength for pre-flop bots
|
||||
|
|
@ -109,54 +117,28 @@ This framework provides specialized capabilities for poker bot testing and devel
|
|||
|
||||
## Algorithm Overview
|
||||
|
||||
This library implements the **Perfect Hash Jump Table algorithm**, a revolutionary memory-optimized approach with advanced suit canonicalization:
|
||||
This library provides **two hand evaluators** with different performance/memory tradeoffs:
|
||||
|
||||
1. **Suit Canonicalization**: Cards are mapped to lexicographically smallest suit permutation for isomorphic reduction
|
||||
2. **Perfect Hash Jump Table**: Three-level trie structure (Level 5/6/7) for optimal memory layout and cache performance
|
||||
3. **Bottom-up Construction**: Cache-optimized table construction using streaming algorithms
|
||||
4. **Memory Efficiency**: 79% memory reduction (625MB → ~130MB) while maintaining O(1) lookup performance
|
||||
5. **Best Hand Selection**: For 6-7 card hands, finds optimal 5-card combination using jump table optimization
|
||||
### Cactus Kev Evaluator (compact)
|
||||
Uses prime-product hashing into two small lookup tables (~100 KB total):
|
||||
1. **Prime Product Hashing**: Each rank maps to a unique prime; the product of 5 primes uniquely identifies the hand
|
||||
2. **Dual Lookup Tables**: 1,287 flush entries + 6,175 unsuited entries = 7,462 total (~30 KB)
|
||||
3. **7-card Cache**: C(7,5)=21 enumeration with HashMap cache for amortized O(1) lookups
|
||||
4. **Zero Collisions**: Validated against all 2,598,960 five-card hands
|
||||
|
||||
### Advanced Architecture
|
||||
|
||||
#### Jump Table System
|
||||
The evaluator uses a sophisticated three-level jump table architecture:
|
||||
|
||||
- **Level 5 (Terminal)**: Direct hand values for all canonical 5-card combinations
|
||||
- **Level 6 (Intermediate)**: Jump offsets pointing to best Level 5 combinations
|
||||
- **Level 7 (Root)**: Jump offsets pointing to best Level 6 combinations
|
||||
|
||||
Each level is optimized for memory efficiency and cache performance with sequential access patterns.
|
||||
|
||||
#### Suit Canonicalization Algorithm
|
||||
The canonicalization process reduces isomorphic hand variations:
|
||||
|
||||
1. **Suit Analysis**: Identify unique suits in the hand
|
||||
2. **Permutation Generation**: Generate all possible suit assignments
|
||||
3. **Lexicographic Optimization**: Find lexicographically smallest representation
|
||||
4. **Mapping Creation**: Create bidirectional suit mapping for conversion
|
||||
|
||||
#### Memory Layout Strategy
|
||||
The jump table uses advanced memory optimization:
|
||||
|
||||
- **Target Size**: Exactly ~130MB (32-35 million u32 entries)
|
||||
- **Trie-based Construction**: Bottom-up building for optimal memory usage
|
||||
- **Table Flattening**: Reorganized layout for cache-friendly access
|
||||
- **Streaming Construction**: Handles large datasets without excessive memory allocation
|
||||
### Supersonic Evaluator (high-throughput)
|
||||
Uses a pre-computed LUT trie (~124 MB) for O(n) array lookups:
|
||||
1. **Trie Structure**: 32,487,834 `u32` entries organized in pages of 53 (one per card + base)
|
||||
2. **Direct Lookup**: Follow `hand_ranks[p + card_index + 1]` for each card — no enumeration needed
|
||||
3. **Packed Hand Rank**: 16-bit format (category + equivalency class) for compact result representation
|
||||
4. **Best for Bulk**: Fastest evaluator for large-scale simulations and batch evaluation
|
||||
|
||||
### Table Generation
|
||||
|
||||
The first time an evaluator is created, it generates the Perfect Hash Jump Table:
|
||||
Lookup tables are generated automatically on first use and persisted to disk:
|
||||
|
||||
```rust
|
||||
// Jump table is generated automatically on first use
|
||||
let evaluator = LookupHandEvaluator::new().unwrap();
|
||||
// Output: "Generating jump table..." (first run only)
|
||||
// Output: "Hand evaluation tables saved to math/data/"
|
||||
```
|
||||
|
||||
The jump table is saved to `math/data/` directory as a single optimized file and reused for subsequent runs:
|
||||
- `jump_table.bin` (~130 MB) - Complete evaluation table with 79% memory reduction
|
||||
- **Cactus Kev**: Small tables (~100 KB) generated in-memory from prime products
|
||||
- **Supersonic**: Large LUT trie (~124 MB) loaded from pre-generated binary file
|
||||
|
||||
## Hand Types
|
||||
|
||||
|
|
@ -258,16 +240,6 @@ let best_rank = evaluator.rank_hand7(&all_cards);
|
|||
println!("Bot best hand rank: {}", best_rank);
|
||||
```
|
||||
|
||||
### Custom Table Generation
|
||||
|
||||
```rust
|
||||
use holdem_core::evaluator_generator::state_table_generator::StateTableGenerator;
|
||||
|
||||
let mut generator = StateTableGenerator::new();
|
||||
generator.generate_tables(); // ~1-2 seconds
|
||||
generator.save_tables().unwrap(); // Save to disk
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
Run the comprehensive test suite:
|
||||
|
|
@ -360,41 +332,37 @@ Player Statistics:
|
|||
|
||||
## Mathematical Foundation
|
||||
|
||||
### Perfect Hash Algorithm
|
||||
### Cactus Kev — Perfect Hash Algorithm
|
||||
|
||||
The evaluator uses a perfect hash function that maps each possible card combination to a unique index:
|
||||
The Cactus Kev evaluator uses prime-product hashing:
|
||||
|
||||
```
|
||||
Hash = f(card₁, card₂, ..., cardₙ)
|
||||
Hash = prime(rank₁) × prime(rank₂) × ... × prime(rank₅)
|
||||
Index = Hash % TABLE_SIZE
|
||||
Rank = TABLE[Index]
|
||||
```
|
||||
|
||||
### Card Encoding
|
||||
Each rank maps to a unique prime (2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41), so the product of 5 primes uniquely identifies the hand pattern.
|
||||
|
||||
Each card is encoded using multiple techniques:
|
||||
### Supersonic — LUT Trie Algorithm
|
||||
|
||||
- **Prime Numbers**: Unique primes for rank identification (2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41)
|
||||
- **Bit Patterns**: Suit detection using bit manipulation
|
||||
- **Binary Representation**: Compact 8-bit card encoding
|
||||
The Supersonic evaluator uses a pre-computed trie of 32.5M `u32` entries:
|
||||
|
||||
### Hand Strength Calculation
|
||||
```
|
||||
p = INITIAL_STATE (page 1 base)
|
||||
for each card:
|
||||
p = hand_ranks[p + card_index + 1]
|
||||
rank = p // (for 7-card hands)
|
||||
```
|
||||
|
||||
Hand strength is calculated using:
|
||||
|
||||
1. **Flush Detection**: Bitwise suit comparison
|
||||
2. **Rank Analysis**: Prime product uniqueness
|
||||
3. **Pattern Matching**: Specialized algorithms per hand type
|
||||
4. **Relative Ranking**: Comparison against all possible hands
|
||||
Each step is a single array lookup — no hashing, no enumeration, no branching.
|
||||
|
||||
## References
|
||||
|
||||
- **Perfect Hash Jump Tables**: Revolutionary memory optimization with suit canonicalization
|
||||
- **Suit Canonicalization**: Lexicographically smallest permutation algorithm for isomorphic reduction
|
||||
- **Bottom-up Trie Construction**: Cache-optimized memory layout for modern CPU architectures
|
||||
- **Poker Standards**: 2+2 Poker hand ranking standards (ranking reference)
|
||||
- **Cactus Kev**: Perfect hash algorithm for 5-card poker hand evaluation
|
||||
- **Supersonic**: LUT trie evaluator for high-throughput hand evaluation
|
||||
- **Poker Standards**: Standard poker hand ranking rules
|
||||
- **Poker Testbed**: Framework designed for automated bot testing and analysis
|
||||
- **Java Integration**: Compatible with existing Java poker tools and frameworks
|
||||
|
||||
## License
|
||||
|
||||
|
|
@ -421,4 +389,4 @@ For questions, issues, or contributions, please:
|
|||
|
||||
---
|
||||
|
||||
**Performance Note**: First run includes ~1-2 second table generation. Subsequent runs load precomputed tables in ~100-200ms.
|
||||
**Performance Note**: The Cactus Kev evaluator generates its small lookup tables (~100 KB) in-memory on first use. The Supersonic evaluator requires a pre-generated ~124 MB LUT file loaded at startup.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue