New evaluator that uses only 133 MB of memory and improves performance of 6- and 7-card hand evaluations

README.md

@@ -8,6 +8,9 @@ A comprehensive poker bot testing framework with Java-compatible hand evaluation
 
 ## 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
 - **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
@@ -16,8 +19,9 @@ A comprehensive poker bot testing framework with Java-compatible hand evaluation
 
 - **Java-Compatible**: Full compatibility with Java Meerkat API for seamless tool integration
 - **Bot Testing Framework**: Specifically designed for automated poker bot testing and development
-- **Blazing Fast**: O(1) hand evaluation using perfect hash lookup tables
-- **Memory Efficient**: ~128MB for complete evaluation tables
+- **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
 - **Texas Hold'em Ready**: Optimized for Texas Hold'em bot analysis and testing
@@ -98,28 +102,54 @@ This framework provides specialized capabilities for poker bot testing and devel
 
 ## Algorithm Overview
 
-This library implements the **Java-compatible Meerkat algorithm**, a perfect hash-based approach optimized for poker bot testing:
+This library implements the **Perfect Hash Jump Table algorithm**, a revolutionary memory-optimized approach with advanced suit canonicalization:
 
-1. **Java-Style Card Encoding**: Each card uses Java Meerkat's 8-bit encoding (rrrr-sss format)
-2. **Perfect Hash**: Cards are mapped to unique indices using Java-compatible mathematical functions
-3. **Table Lookup**: Precomputed ranking tables provide instant hand strength values matching Java API
-4. **Best Hand Selection**: For 6-7 card hands, finds optimal 5-card combination using Java logic
+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
+
+### 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
 
 ### Table Generation
 
-The first time an evaluator is created, it generates evaluation tables:
+The first time an evaluator is created, it generates the Perfect Hash Jump Table:
 
 ```rust
-// Tables are generated automatically on first use
+// Jump table is generated automatically on first use
 let evaluator = LookupHandEvaluator::new().unwrap();
-// Output: "Generating state table..." (first run only)
+// Output: "Generating jump table..." (first run only)
 // Output: "Hand evaluation tables saved to math/data/"
 ```
 
-Tables are saved to `math/data/` directory as separate files and reused for subsequent runs:
-- `5_card_table.lut` (~10 MB)
-- `6_card_table.lut` (~80 MB)
-- `7_card_table.lut` (~535 MB)
+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
 
 ## Hand Types
 
@@ -276,9 +306,9 @@ Hand strength is calculated using:
 
 ## References
 
-- **Meerkat API**: Original Java implementation by Ray Wotton (full compatibility maintained)
-- **C Implementation**: Paul Senzee's optimized C version (algorithm foundation)
-- **Perfect Hash**: Kevin Suffecool's hashing algorithm (core mathematical approach)
+- **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)
 - **Poker Testbed**: Framework designed for automated bot testing and analysis
 - **Java Integration**: Compatible with existing Java poker tools and frameworks