poker-bitvaljs 1.1.2 → 1.5.2

package/README.md

@@ -6,11 +6,15 @@ High-performance poker hand evaluator optimized for browser environments, using
 
 ## Features
 
-- **Fast hand evaluation** using bitwise operations
-- **Range vs range equity calculations** with canonical key caching optimization
-- **Web Workers support** for parallel processing across multiple CPU cores (3-7x speedup)
-- **Monte Carlo simulation** for preflop and postflop scenarios
-- **Exhaustive enumeration** for flop/turn scenarios (2 or fewer cards to come)
+- **Fast hand evaluation** using four 13-bit suit lanes and plain 32-bit integers
+  (no BigInt in the hot path) — ~28–70× faster than the previous BigInt engine
+- **Exact range vs range equity** on the flop and turn via evaluate-once with
+  counting (byte-identical to brute force, no approximation)
+- **Exact, instant preflop** via an optional precomputed equity table
+  (`loadPreflopTable`) — replaces Monte Carlo entirely for preflop
+- **Monte Carlo** with confidence-interval early-stop for the remaining sampled
+  case (preflop with dead cards)
+- **Web Workers** for the Monte Carlo path
 - **Progress callbacks** with configurable update intervals
 - **Browser and Node.js compatible**
 
@@ -157,9 +161,9 @@ Simulates a single hand vs hand matchup.
 **Returns:**
 - `{ win, tie, lose }`: Results object
 
-### `compareRange(heroHands, villainHands, boardCards, deadCards, numberOfBoardCards, iterations, optimize, progressCallback, progressInterval, useWorkers)`
+### `compareRange(heroHands, villainHands, boardCards, deadCards, numberOfBoardCards, iterations, optimize, progressCallback, progressInterval, useWorkers, mcTargetPct)`
 
-Compares two ranges of hands with optional optimization and Web Workers parallelization.
+Compares two ranges of hands.
 
 **Parameters:**
 - `heroHands` (Array): Array of hero hand strings (e.g., `['AsAh', 'AsAd']`)
@@ -167,40 +171,57 @@ Compares two ranges of hands with optional optimization and Web Workers parallel
 - `boardCards` (Array): Board cards as strings (default: `[]`)
 - `deadCards` (Array): Dead cards as strings (default: `[]`)
 - `numberOfBoardCards` (Number): Total board cards (default: `5`)
-- `iterations` (Number): Number of simulations per matchup (default: `10000`)
-- `optimize` (Boolean): Use canonical key caching for performance (default: `true`). **Note:** Optimizations may result in a ±0.5% margin of error compared to unoptimized calculations.
+- `iterations` (Number): Monte Carlo samples per matchup (default: `10000`). Ignored on the flop/turn (exhaustive) and preflop-table paths, which are exact.
+- `optimize` (Boolean): Use the optimized path (default: `true`). On the flop/turn this is **exact** (byte-identical to `optimize: false`), just much faster.
 - `progressCallback` (Function): Optional callback `(current, total, message) => {}` (default: `null`)
 - `progressInterval` (Number): Update progress callback every N matchups (default: `100`)
-- `useWorkers` (Boolean): Use Web Workers for parallelization across CPU cores (default: `true`). Automatically falls back to sequential execution if workers are unavailable or workload is too small (< 4 matchups).
+- `useWorkers` (Boolean): Use Web Workers for the Monte Carlo path (default: `true`). The exact flop/turn path runs on the main thread.
+- `mcTargetPct` (Number): Monte Carlo early-stop target — stop sampling a matchup once its 95% confidence-interval half-width is within this many equity percentage points (default: `0.3`). Pass `0` to force the full `iterations`. Only affects the Monte Carlo (preflop) path.
 
 **Returns:**
 - `Promise<{ win, tie, lose }>`: Results object
 
-**Web Workers Notes:**
-- Web Workers provide 3-7x speedup on multi-core systems by parallelizing matchup evaluations
-- Workers are automatically disabled when:
-  - `useWorkers` is `false`
-  - Workers are not supported by the browser
-  - There are fewer than 4 matchups (overhead not worth it)
-- For local testing with `file://` protocol, use a local web server (see [Testing Locally](#testing-locally))
+### `loadPreflopTable(buffer)`
+
+Loads the precomputed exact preflop equity table and enables the preflop fast
+path in `compareRange` (empty board, no dead cards). Accepts an `ArrayBuffer`
+(browser) or Node `Buffer`. Generate the table with `npm run gen:preflop`.
+
+```javascript
+// Browser
+const buf = await (await fetch('./bench/preflop-table.bin')).arrayBuffer();
+bitval.loadPreflopTable(buf);
+
+// Node
+const fs = require('fs');
+bitval.loadPreflopTable(fs.readFileSync('bench/preflop-table.bin'));
+```
+
+Without a table loaded, preflop falls back to Monte Carlo — nothing else changes.
 
 ## Performance
 
-- **Optimized for browser environments** with efficient bitwise operations
-- **Web Workers parallelization** provides 3-7x speedup on multi-core systems
-- Canonical key caching reduces redundant evaluations (may introduce ±0.5% margin of error)
-- Exhaustive enumeration for flop/turn (2 or fewer cards to come)
-- Monte Carlo simulation for preflop and river scenarios
-- Adaptive progress reporting to minimize UI blocking
+- **No BigInt in the hot path** — cards are four 13-bit suit lanes evaluated with
+  plain 32-bit integer ops. ~28–70× faster than the previous BigInt engine.
+- **Flop/turn: exact and fast.** Each unique concrete hand is evaluated once per
+  runout; wide range-vs-range is resolved by counting. No ±0.5% approximation.
+- **Preflop: exact table lookup** (with `loadPreflopTable`) instead of Monte
+  Carlo — effectively instant.
+- **Monte Carlo** (only preflop with dead cards) uses confidence-interval
+  early-stop and Web Workers.
+
+Reproduce the benchmarks with `node bench/pre-vs-post.js` and `npm run bench`;
+correctness with `npm test` (and `npm run test:full` for the exhaustive proofs).
 
 **Test performance and benchmark online:** [https://darraghgeo.github.io/poker-bitvaljs/](https://darraghgeo.github.io/poker-bitvaljs/)
 
 ### Performance Tips
 
-- Enable Web Workers (default) for best performance on multi-core systems
-- Use canonical caching (`optimize: true`) for large range comparisons
-- Adjust `progressInterval` to balance UI responsiveness vs. performance
-- For very small workloads (< 4 matchups), workers are automatically disabled to avoid overhead
+- Call `loadPreflopTable` once at startup for exact, instant preflop equity.
+- Keep `optimize: true` (default) — on the flop/turn it is exact and much faster.
+- Lower `mcTargetPct` (or set `0`) for higher-precision Monte Carlo; raise it for
+  faster, looser preflop-with-dead-cards estimates.
+- Adjust `progressInterval` to balance UI responsiveness vs. performance.
 
 ## Testing Locally
 

package/bitval-worker.js

@@ -36,103 +36,98 @@ function deserializeMatchup(matchupData) {
  * Evaluates a single matchup in the worker context
  * Similar to _evaluateMatchup but without progress callbacks
  */
-async function evaluateMatchupInWorker(heroMask, villainMask, setup, evalCache, cacheInfo, bitval) {
+async function evaluateMatchupInWorker(heroMask, villainMask, setup, bitval) {
   let win = 0, tie = 0, lose = 0;
   const deadMask = heroMask | villainMask | setup.deadCardsMask;
-  const matchupDeadMask = heroMask | villainMask; // Only matchup-level dead cards (excludes setup.deadCardsMask)
-  
+
   // Initialize random number generator for Monte Carlo (not needed for exhaustive)
   if (!setup.isExhaustive) {
     bitval.xorShift = new XorShift32();
   }
   
-  // Prepare for exhaustive enumeration if applicable
-  let comboArray = null;
+  // BigInt-free (Number) hot loop, mirroring BitVal._evaluateMatchup. Cards are
+  // four 13-bit suit rank masks; bitval._eval7 does the evaluation with no BigInt.
   let iterations = setup.iterations;
+  const heroSuits = bitval._suitsFromBigMask(heroMask);
+  const villainSuits = bitval._suitsFromBigMask(villainMask);
+  const boardBaseSuits = bitval._suitsFromBigMask(setup.boardMask);
+  const hs0 = heroSuits[0], hs1 = heroSuits[1], hs2 = heroSuits[2], hs3 = heroSuits[3];
+  const vs0 = villainSuits[0], vs1 = villainSuits[1], vs2 = villainSuits[2], vs3 = villainSuits[3];
+  const bb0 = boardBaseSuits[0], bb1 = boardBaseSuits[1], bb2 = boardBaseSuits[2], bb3 = boardBaseSuits[3];
+
+  let comboSuits = null;              // flat Int32Array, 4 entries per combo
+  let pool = null, poolLen = 0;       // packed Int32Array of available cards
+  const nDeal = setup.numberOfCardsToDeal;
   if (setup.isExhaustive) {
-    // Use comboArray from setup if available, otherwise compute it
-    if (setup.comboArray && setup.comboArray.length > 0) {
-      comboArray = setup.comboArray;
-      iterations = comboArray.length;
-    } else {
-      // Compute comboArray if not provided
-      const availableMasks = bitval._getAvailableCardMasksByLookUp(deadMask);
-      comboArray = bitval._getCombinations(availableMasks, setup.numberOfCardsToDeal);
-      iterations = comboArray.length;
-    }
+    // Use comboArray from setup if available, otherwise compute it.
+    let comboArray = (setup.comboArray && setup.comboArray.length > 0)
+      ? setup.comboArray
+      : bitval._getCombinations(bitval._getAvailableCardMasksByLookUp(deadMask), nDeal);
+    comboSuits = bitval._buildComboSuits(comboArray);
+    iterations = comboSuits.length >> 2;
+  } else {
+    pool = bitval._availableSuitCards(deadMask);
+    poolLen = pool.length;
   }
-  
+
+  // Monte Carlo early-stop (mirrors BitVal._evaluateMatchup).
+  const mcTarget = setup.isExhaustive ? 0 : (setup.mcTarget > 0 ? setup.mcTarget / 100 : 0);
+  const reqIters = iterations;
+  let ran = iterations;
+
   // Main evaluation loop
   for (let i = 0; i < iterations; i++) {
-    // Generate board: use pre-computed combo for exhaustive, or deal randomly
-    const board = setup.isExhaustive 
-      ? setup.boardMask | comboArray[i]
-      : bitval.deal(setup.boardMask, deadMask, setup.numberOfCardsToDeal) | setup.boardMask;
-    
-    // Evaluate both hands
-    let hEval, hKick, vEval, vKick;
-    if (cacheInfo && evalCache) {
-      [hEval, hKick] = bitval._getCachedEvaluation(cacheInfo.heroKey, cacheInfo.heroHand, board, evalCache, matchupDeadMask);
-      [vEval, vKick] = bitval._getCachedEvaluation(cacheInfo.villainKey, cacheInfo.villainHand, board, evalCache, matchupDeadMask);
+    let d0, d1, d2, d3;
+    if (comboSuits) {
+      const b = i << 2;
+      d0 = bb0 | comboSuits[b]; d1 = bb1 | comboSuits[b + 1]; d2 = bb2 | comboSuits[b + 2]; d3 = bb3 | comboSuits[b + 3];
     } else {
-      [hEval, hKick] = bitval.evaluate(heroMask | board);
-      [vEval, vKick] = bitval.evaluate(villainMask | board);
+      d0 = bb0; d1 = bb1; d2 = bb2; d3 = bb3;
+      for (let kk = 0; kk < nDeal; kk++) {
+        const j = kk + bitval.xorShift.next(poolLen - kk);
+        const tmp = pool[kk]; pool[kk] = pool[j]; pool[j] = tmp;
+        const p = pool[kk], bit = p & 0xFFFF, suit = p >> 16;
+        if (suit === 0) d0 |= bit;
+        else if (suit === 1) d1 |= bit;
+        else if (suit === 2) d2 |= bit;
+        else d3 |= bit;
+      }
     }
-    
-    // Compare and accumulate results
-    if (hEval > vEval || (hEval === vEval && hKick > vKick)) {
-      win++;
-    } else if (vEval > hEval || (vEval === hEval && vKick > hKick)) {
-      lose++;
-    } else {
-      tie++;
+    const hE = bitval._eval7(hs0 | d0, hs1 | d1, hs2 | d2, hs3 | d3);
+    const vE = bitval._eval7(vs0 | d0, vs1 | d1, vs2 | d2, vs3 | d3);
+    if (hE > vE) win++;
+    else if (vE > hE) lose++;
+    else tie++;
+
+    if (mcTarget && (i & 4095) === 4095 && i >= 8191) {
+      const n = i + 1, p = (win + tie * 0.5) / n;
+      if (1.96 * Math.sqrt(p * (1 - p) / n) < mcTarget) { ran = n; break; }
     }
   }
-  
+
+  if (ran < reqIters && ran > 0) {
+    const s = reqIters / ran;
+    win = Math.round(win * s); tie = Math.round(tie * s); lose = Math.round(lose * s);
+  }
+
   return { matchupWin: win, matchupTie: tie, matchupLose: lose };
 }
 
-// Worker message handler
+// Reused BitVal instance (holds the lookup tables; cheap to keep around).
+const _bitval = new BitVal();
+
+// Worker message handler. Workers handle the Monte Carlo path only; the
+// exhaustive exact path runs on the main thread (see BitVal._compareRangeOptimized).
 self.onmessage = async function(e) {
   try {
     const { matchups, setupData, workerId } = e.data;
-    
-    // Deserialize setup
     const setup = deserializeSetup(setupData);
-    
-    // Create BitVal instance and cache for this worker (reused for all matchups)
-    const bitval = new BitVal();
-    const evalCache = new FastestAutoClearingCache(16000000);
-    
     const results = [];
-    
-    // Evaluate each matchup in the batch
+
     for (const matchupData of matchups) {
       const matchup = deserializeMatchup(matchupData);
-      
-      // Prepare cache info if available
-      const cacheInfo = matchup.heroKey ? {
-        heroKey: matchup.heroKey,
-        heroHand: matchup.heroHand,
-        villainKey: matchup.villainKey,
-        villainHand: matchup.villainHand
-      } : null;
-      
-      // Evaluate matchup
-      const result = await evaluateMatchupInWorker(
-        matchup.heroMask,
-        matchup.villainMask,
-        setup,
-        evalCache,
-        cacheInfo,
-        bitval
-      );
-      
-      results.push({
-        key: matchup.key,
-        validCount: matchup.validCount,
-        ...result
-      });
+      const result = await evaluateMatchupInWorker(matchup.heroMask, matchup.villainMask, setup, _bitval);
+      results.push({ key: matchup.key, validCount: matchup.validCount, ...result });
     }
     
     // Send results back to main thread