212 lines
No EOL
7 KiB
Markdown
212 lines
No EOL
7 KiB
Markdown
# Poker API Core Library
|
|
|
|
## Overview
|
|
|
|
The Poker API Core Library (`poker-api`) is a high-performance poker hand evaluation library based on the Meerkat API algorithm. This library provides lightning-fast poker hand strength evaluation using precomputed lookup tables and perfect hashing.
|
|
|
|
## Recent Updates
|
|
|
|
- **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
|
|
|
|
## Features
|
|
|
|
- **Blazing Fast**: O(1) hand evaluation using perfect hash lookup tables
|
|
- **Memory Efficient**: ~128MB for complete evaluation tables
|
|
- **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 hand evaluation
|
|
- **Comprehensive Testing**: Extensive test suite with millions of verification cases
|
|
|
|
## Architecture
|
|
|
|
### Core Components
|
|
|
|
#### API Module (`src/api/`)
|
|
The main application programming interface providing:
|
|
- **Card Management**: `Card` struct for individual playing cards
|
|
- **Hand Management**: `Hand` struct for collections of cards
|
|
- **Deck Operations**: `Deck` struct for standard 52-card deck management
|
|
- **Player Actions**: `Action` types for betting operations
|
|
- **Game State**: `GameInfo` trait for accessing game information
|
|
- **Bot Interface**: `Player` trait for poker bot implementations
|
|
|
|
#### Hand Evaluator (`src/hand_evaluator.rs`)
|
|
High-performance poker hand evaluation using precomputed lookup tables:
|
|
- **Perfect Hash Algorithm**: Maps card combinations to unique indices
|
|
- **Table-Based Evaluation**: O(1) lookup time after table generation
|
|
- **Multi-Hand Support**: Handles 5, 6, and 7-card evaluations
|
|
- **Memory Management**: Efficient table loading and caching
|
|
|
|
#### Evaluator Generator (`src/evaluator_generator/`)
|
|
Table generation system for poker hand evaluation:
|
|
- **Flushes** (`flushes.rs`): Lookup table for flush hand evaluation
|
|
- **Products** (`products.rs`): Prime product-based hand type detection
|
|
- **Unique** (`unique.rs`): Special hand types (straight flushes, quads, etc.)
|
|
- **Values** (`values.rs`): Standard hand ranking and comparison
|
|
- **Pairs** (`pair.rs`): Two-card combination analysis and lookup
|
|
|
|
#### Supporting Modules
|
|
- **Simple Player** (`src/simple_player.rs`): Basic bot implementation example
|
|
- **TOML Preferences** (`src/toml_preferences.rs`): Configuration management
|
|
- **Texas Hold'em** (`src/texas_holdem/`): Game-specific logic (planned)
|
|
|
|
## Performance Characteristics
|
|
|
|
| Hand Type | Evaluation Time | Combinations Evaluated |
|
|
|-----------|----------------|----------------------|
|
|
| 5-Card | ~10-20ns | Direct lookup |
|
|
| 6-Card | ~50-80ns | 6 combinations |
|
|
| 7-Card | ~150-250ns | 21 combinations |
|
|
|
|
### Memory Usage
|
|
- **Table Generation**: ~2.4MB working memory during generation
|
|
- **Runtime Tables**: ~128MB for complete hand ranking tables
|
|
- **Loading Time**: ~100-200ms from disk (after generation)
|
|
|
|
## Algorithm Overview
|
|
|
|
### Perfect Hash Algorithm
|
|
|
|
The evaluator uses a perfect hash function that maps each possible card combination to a unique index:
|
|
|
|
```
|
|
Hash = f(card₁, card₂, ..., cardₙ)
|
|
Index = Hash % TABLE_SIZE
|
|
Rank = TABLE[Index]
|
|
```
|
|
|
|
### Card Encoding
|
|
|
|
Each card is encoded using multiple techniques:
|
|
- **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
|
|
|
|
### Hand Strength Calculation
|
|
|
|
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
|
|
|
|
## Usage Examples
|
|
|
|
### Basic Hand Evaluation
|
|
|
|
```rust
|
|
use holdem_core::hand_evaluator::LookupHandEvaluator;
|
|
use holdem_core::api::hand::Hand;
|
|
use holdem_core::api::card::Card;
|
|
|
|
// Create evaluator (generates tables on first use)
|
|
let evaluator = LookupHandEvaluator::new().unwrap();
|
|
|
|
// Create a poker hand
|
|
let mut hand = Hand::new();
|
|
hand.add_card(Card::from_string("As").unwrap()).unwrap();
|
|
hand.add_card(Card::from_string("Ks").unwrap()).unwrap();
|
|
hand.add_card(Card::from_string("Qs").unwrap()).unwrap();
|
|
hand.add_card(Card::from_string("Js").unwrap()).unwrap();
|
|
hand.add_card(Card::from_string("Ts").unwrap()).unwrap();
|
|
|
|
// Evaluate hand strength
|
|
let rank = evaluator.rank_hand(&hand);
|
|
println!("Hand rank: {}", rank);
|
|
```
|
|
|
|
### 7-Card Hand Evaluation (Texas Hold'em)
|
|
|
|
```rust
|
|
use holdem_core::hand_evaluator::LookupHandEvaluator;
|
|
use holdem_core::api::card::Card;
|
|
|
|
let evaluator = LookupHandEvaluator::new().unwrap();
|
|
|
|
// Texas Hold'em: 2 hole cards + 5 community cards
|
|
let cards = [
|
|
Card::from_string("As").unwrap(),
|
|
Card::from_string("Ks").unwrap(),
|
|
Card::from_string("Td").unwrap(),
|
|
Card::from_string("Jc").unwrap(),
|
|
Card::from_string("Qh").unwrap(),
|
|
Card::from_string("9s").unwrap(),
|
|
Card::from_string("2d").unwrap(),
|
|
];
|
|
|
|
let rank = evaluator.rank_hand7(&cards);
|
|
println!("Best 5-card hand rank: {}", 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:
|
|
|
|
```bash
|
|
cargo test
|
|
```
|
|
|
|
Run performance benchmarks:
|
|
|
|
```bash
|
|
cargo test --release hand_eval_integration_test -- --nocapture
|
|
```
|
|
|
|
## Development
|
|
|
|
### Building
|
|
|
|
```bash
|
|
# Build library
|
|
cargo build
|
|
|
|
# Build with optimizations
|
|
cargo build --release
|
|
|
|
# Generate documentation
|
|
cargo doc --open
|
|
```
|
|
|
|
### Code Organization
|
|
|
|
- **API Types**: `src/api/` - Core data types and traits
|
|
- **Evaluation**: `src/hand_evaluator.rs` - Main evaluation logic
|
|
- **Table Generation**: `src/evaluator_generator/` - Lookup table creation
|
|
- **Examples**: `src/simple_player.rs` - Basic bot implementation
|
|
- **Configuration**: `src/toml_preferences.rs` - Settings management
|
|
|
|
### Contributing
|
|
|
|
Areas for improvement:
|
|
- Hardware acceleration (SIMD optimizations)
|
|
- Additional poker variants (Omaha, Stud, etc.)
|
|
- Memory-mapped table loading
|
|
- Distributed table generation
|
|
- Advanced benchmarking tools
|
|
|
|
## Integration
|
|
|
|
This core library serves as the foundation for:
|
|
- **Poker Bots**: AI players in `bots/` directory
|
|
- **Simulations**: Game simulation tools in `simulator/` directory
|
|
- **Analysis Tools**: Log analysis and monitoring in `tools/` directory
|
|
- **Online Play**: Networked poker applications in `online/` directory
|
|
|
|
## References
|
|
|
|
- **Meerkat API**: Original Java implementation by Ray Wotton
|
|
- **C Implementation**: Paul Senzee's optimized C version
|
|
- **Perfect Hash**: Kevin Suffecool's hashing algorithm
|
|
- **Poker Standards**: 2+2 Poker hand ranking standards |