From 6e021253dadd0b339cdc09a949bb9c84a0d67fd7 Mon Sep 17 00:00:00 2001 From: Split Date: Sun, 8 Feb 2026 09:20:19 -0500 Subject: [PATCH] Add technical resources for equity calculation and range analysis --- RESOURCES.md | 203 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 203 insertions(+) create mode 100644 RESOURCES.md diff --git a/RESOURCES.md b/RESOURCES.md new file mode 100644 index 0000000..dd7b694 --- /dev/null +++ b/RESOURCES.md @@ -0,0 +1,203 @@ +# Poker Training Tool - Technical Resources + +Resources collected for implementing equity calculation, range analysis, and bet sizing in the Kings-Eunuch poker training tool. + +--- + +## Equity Calculation + +### Core Concepts +- **Poker equity**: Percentage chance of winning the hand given current cards +- **Monte Carlo simulation**: Most common approach for computing equity + - Run thousands of randomized board completions + - Count wins/losses to estimate probability + - Trades perfect accuracy for practical speed + +### Academic Resources +- **Columbia University Poker Equity Project (2023)** + - https://www.cs.columbia.edu/~sedwards/classes/2023/4995-fall/proposals/PokerEquity.pdf + - Confirms Monte Carlo as standard approach + - Good overview of the problem space + +### Implementation Examples + +#### C++ Reference Implementations +1. **PokerEquityCalculator by dickreuter** + - https://github.com/dickreuter/PokerEquityCalculator + - Monte Carlo simulation in C++ + - Estimates wins assuming all players stay to river + - Also has Python/NumPy versions (NumPy ~1000x faster than pure Python) + - Good reference for algorithm structure + +2. **OMPEval by zekyll** + - https://github.com/zekyll/OMPEval + - Fast C++ hand evaluator + equity calculator + - **Key features:** + - Both Monte Carlo and full enumeration + - Range syntax similar to EquiLab + - Board cards and dead cards support + - Multi-threading (2-10x faster than EquiLab per thread) + - **API Example:** + ```cpp + omp::EquityCalculator eq; + eq.start({"AK", "QQ"}); + eq.wait(); + auto r = eq.getResults(); + // r.equity[0], r.equity[1] + ``` + - **Performance:** + - 775M evals/sec (sequential, 64-bit) + - Supports periodic callbacks with intermediate results + +#### Stack Overflow Discussion +- https://stackoverflow.com/questions/21015352/monte-carlo-method-for-calculating-poker-equities +- Code examples for Monte Carlo equity calculation +- Discussion of IMAP/SMTP issues and error handling +- Sample code showing deck representation and simulation loops + +### Rust-Specific Considerations +- Fast hand evaluation is critical (you already have this) +- Monte Carlo: use `rand` crate for shuffling/sampling +- Parallelization: `rayon` for multi-threaded simulations +- Consider caching: memoize frequent hand matchups + +--- + +## Range Representation & Parsing + +### Range Notation (EquiLab/PokerStove Standard) +- **Pairs:** `AA`, `KK`, `22` +- **Ranges:** `QQ+` (QQ, KK, AA), `A2s+` (A2s through AKs) +- **Specific combos:** `AcQc` (Ace of clubs, Queen of clubs) +- **Suited:** `AKs`, offsuit: `AKo` +- **Random:** `random` keyword for any two cards + +### Implementation Approach +1. Parse range string into internal representation +2. Generate all hand combinations matching the range +3. Sample from valid combos during Monte Carlo + +### OMPEval Range Example +```cpp +vector ranges{"QQ+,AKs,AcQc", "A2s+", "random"}; +uint64_t board = CardRange::getCardMask("2c4c5h"); +uint64_t dead = CardRange::getCardMask("Jc"); +``` + +### Rust Parsing Strategy +- Use `nom` or `pest` for parsing range syntax +- Represent ranges as bitmasks or Vec for efficiency +- Handle board/dead cards to filter out impossible combos + +--- + +## Range vs Range Equity + +### Concept +- Instead of specific hands, players have **ranges** (sets of possible hands) +- Equity = weighted average of all possible hand combinations +- Example: "What's the equity of `JJ` vs opponent's range `{AA, KK, QQ, AK}`?" + +### Calculation Method +1. Enumerate all valid combos for each player's range +2. For each combo pair: + - Run Monte Carlo simulation (or full enumeration) + - Weight by probability of that combo +3. Aggregate results + +### Performance Notes +- Full enumeration feasible heads-up with narrow ranges +- Monte Carlo required for wide ranges or multiway pots +- OMPEval's "random walk algorithm" avoids collision resampling + +--- + +## Bet Sizing & Pot Odds + +### Pot Odds +- **Formula:** `Pot Odds = Amount to Call / (Pot + Amount to Call)` +- **Example:** $10 to call into $50 pot → Pot odds = 10/60 = 16.7% +- **Decision rule:** Call if equity > pot odds + +### Expected Value (EV) +- **Formula:** `EV = (Probability of Win × Pot) - (Probability of Loss × Bet)` +- Positive EV → profitable long-term +- Negative EV → losing play + +### Minimum Defense Frequency (MDF) +- **Formula:** `MDF = Pot / (Pot + Bet)` +- Prevents opponent from auto-profiting with bluffs +- Example: Opponent bets $50 into $100 → MDF = 100/150 = 66.7% + +### Bet Sizing Strategy +- **Value betting:** Size based on opponent's calling range +- **Bluffing:** Balance bluff frequency with pot odds you're offering +- **Pot geometry:** Plan bet sizes across multiple streets + +### Implementation for Training Tool +1. Display pot odds for given situation +2. Compare user's estimated equity to required equity +3. Calculate EV for different actions (fold, call, raise) +4. Quiz mode: "What size bet gives opponent bad odds to call?" + +--- + +## Additional Tools & Resources + +### Commercial Tools (for reference/comparison) +- **EquiLab** (free version) - range vs range equity calculator +- **PokerStove** - classic equity calculator +- **Flopzilla** - range analysis and equity visualization +- **PioSOLVER** - GTO solver (advanced) + +### Algorithms for Further Study +- **Perfect hashing** for hand evaluation (OMPEval uses this) +- **Suit isomorphism** for preflop/postflop optimization +- **Libdivide** for fast modulo operations (used by OMPEval) + +--- + +## Next Steps for Kings-Eunuch + +### Phase 1: Basic Equity Calculator +1. Implement Monte Carlo simulation +2. Take player hand + opponent hand → estimate equity +3. Benchmark performance (aim for >100k sims/sec) + +### Phase 2: Range Support +1. Build range parser (start simple: `AA`, `AK`, `JJ+`) +2. Generate combinations from range strings +3. Range vs range equity calculation + +### Phase 3: Training Modes +1. **Equity quiz:** Show hand/board, user estimates equity, reveal answer +2. **Pot odds trainer:** Given pot/bet, calculate required equity +3. **Bet sizing:** Given equity and goal, recommend bet size + +### Phase 4: Advanced Features +- Multi-way pot support +- EV calculations across multiple streets +- Save/load training scenarios +- Historical performance tracking + +--- + +## Performance Targets (based on research) + +- **Hand evaluation:** 500M+ evals/sec (you're likely already here) +- **Monte Carlo equity:** 1M+ hands/sec for heads-up (target: OMPEval speed) +- **Range parsing:** < 1ms for typical range string +- **UI responsiveness:** Results in < 100ms for interactive training + +--- + +## Notes +- Monte Carlo is industry standard for equity calculation +- Full enumeration only practical for narrow ranges heads-up +- Multi-threading gives near-linear speedup (OMPEval shows 2-10x) +- Range notation is standardized across most poker tools +- Focus on correctness first, optimize after profiling + +--- + +*Resources compiled: 2026-02-08*