poker-flopsolve 0.4.0 → 0.5.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -91,6 +91,11 @@ defineSpot({ ..., betSizes: [[0.5]], raiseSizes: [{ times: 3 }], maxRaises: 2 })
91
91
  // bet 40 into 80, raise to 120
92
92
  ```
93
93
 
94
+ A raise smaller than a full raise is bumped up to the minimum raise. When even that does
95
+ not fit in the stack, the raise is all-in for less: a player facing a bet can always shove
96
+ whatever they have beyond the call (up to `maxRaises`), with or without `allowAllIn`.
97
+ Before 0.4.1 such a shove was dropped, leaving a short stack only fold or call.
98
+
94
99
  ## Betting per round
95
100
 
96
101
  `raiseSizes`, `maxRaises` and `allowAllIn` can each be given once for every round, or one
@@ -150,11 +155,30 @@ Each takes a value per round too. On a turn spot with four sizes, two raises and
150
155
  Raise caps per round (`maxRaises: [1, 2, 1]`) and a checked-down river (an empty
151
156
  `betSizes` row) were already available and trim the same way.
152
157
 
158
+ `removeActions` cuts single lines: each a bet, raise or shove named by the path of the node
159
+ it leads to, as `Solution.path` writes it (`'check bet 18.15'`, `'bet 41.25 call / allin
160
+ 975'`), with everything below it. Only the line named goes; the same size elsewhere stays.
161
+ Use it to keep three sizes where they matter and one elsewhere; `thinSizes` (below) is a
162
+ ready-made shape of that kind.
163
+
153
164
  `minWeight: 0.05` trims the ranges the same way: combinations weighted under 5% are
154
165
  dropped from both, which suits imported ranges full of hands at a percent or two.
155
166
 
156
167
  ## Reading a solved spot
157
168
 
169
+ `solution.handEvs(player)` gives each combination's root EV in chips, indexed like
170
+ `COMBO_CARDS` (0 outside the range, on the board, or with no opponent hand to face). Weighted by range weight times the
171
+ opponent mass each hand can face, it averages to `solution.ev(player)`, and one pass serves
172
+ both.
173
+
174
+ Both read the average strategy by default. With `approximations: { currentProfileEv: true }`
175
+ they read the current (regret-matched) profile instead: the strategy the next iteration would
176
+ play. Its per-hand EVs settle sooner. After 15 s single-threaded in a browser, their mean error
177
+ against a 0.045%-of-pot reference was 1.23% of pot against the average's 2.18% on As Kh 7d,
178
+ 0.11% against 0.37% on Ks 9s 4s, and 1.40% against 2.02% on a wide Qs Jh 2c. The cost is the
179
+ same. `strategyAt` and `reachAt` still show the average, so the EVs then belong to a
180
+ different profile from the strategy you read.
181
+
158
182
  `createRun` returns the solver itself as `run.solver`, for analysis after (or between)
159
183
  iterations, without changing anything:
160
184
 
@@ -198,6 +222,21 @@ resumes a solve exactly. Measured on a river spot to 0.1% of pot:
198
222
  | Stack 120 → 100 | 125 | 75 |
199
223
  | Pot 60 → 72 | 125 | 100 |
200
224
 
225
+ A solve of a nearby flop can seed one too, through a card relabelling that takes its board
226
+ onto this one. A rank swap keeps every hand's role, so a solve of AsKh6d read through
227
+ `rankSwap` of the 6 and the 7 plays 66 as 77:
228
+
229
+ ```ts
230
+ import { rankSwap } from 'poker-flopsolve';
231
+ const six = solve(defineSpot({ ...config, board: 'As Kh 6d' }), { targetPercent: 0.1 });
232
+ const seven = solve(defineSpot({ ...config, board: 'As Kh 7d' }), {
233
+ targetPercent: 0.5, warmStart: six, warmCards: rankSwap(4, 5), // ranks 0 = deuce … 12 = ace
234
+ });
235
+ ```
236
+
237
+ On the bench flop that reaches 0.5% of pot in 8 iterations instead of 52 (from AsQh7d,
238
+ 20). It needs the whole old solve: seeding only the flop's decisions saved at most 15%.
239
+
201
240
  ## Re-solving from a node
202
241
 
203
242
  Solve the whole spot with a coarse tree, then re-solve the street you are looking at
@@ -226,11 +265,87 @@ This is *unsafe* re-solving. The subgame is solved for the ranges that arrive, s
226
265
  strategy can be exploitable in ways the original allowed for. It also does not make the
227
266
  earlier streets any more accurate than their coarse model of the future.
228
267
 
268
+ ### Full flop betting, re-solved turns
269
+
270
+ For a flop whose full tree does not fit, keep the flop's betting as it is and give the turn
271
+ and river one size, then re-solve each turn you look at with the full betting.
272
+ `resolveSubgame` does the re-solve; it is opt-in and tree-shaken away when unused.
273
+
274
+ ```ts
275
+ import { defineSpot, resolveSubgame, solve } from 'poker-flopsolve';
276
+
277
+ const full = { ...spot, betSizes: [[0.33, 0.75, 1.5]], raiseSizes: [[0.75]], maxRaises: 3, allowAllIn: true };
278
+ const blueprint = solve(
279
+ defineSpot({
280
+ ...full,
281
+ betSizes: [[0.33, 0.75, 1.5], [0.75], [0.75]],
282
+ raiseSizes: [[0.75], [0.75], [0.75]],
283
+ maxRaises: [3, 1, 1],
284
+ allowAllIn: [true, false, false],
285
+ runoutBuckets: 3,
286
+ }),
287
+ { targetPercent: 0.3, precision: 'i16' }, // in a browser, add `wasmStorage` (see below)
288
+ );
289
+ const turn = resolveSubgame(blueprint, node, board, {
290
+ player: 0, // whose strategy to refine
291
+ betting: { betSizes: full.betSizes, raiseSizes: full.raiseSizes, maxRaises: 3, allowAllIn: true },
292
+ iterations: 300,
293
+ });
294
+ turn.solution.strategyAt(0, 0);
295
+ ```
296
+
297
+ Measured on Ks 9s 4s (pot 55, stacks 975, the bench ranges) against the full tree solved
298
+ to 0.093% of pot (99 minutes, 2.3 GB at i16 on four threads):
299
+
300
+ | | blueprint, 1 turn/river size | + 3 runout buckets, i16 |
301
+ |---|---|---|
302
+ | storage | 264 MiB | 97 MiB |
303
+ | solve to 0.3%, Node, 4 threads | 27 s | 55 s |
304
+ | root EV error per hand, OOP / IP | 2.3 / 2.2% of pot (max 10.6 / 20.2) | 2.3 / 2.2% (max 10.1 / 19.5) |
305
+ | root size agreement, OOP / IP after a check | 98.6% / 65.4% | 100% / 62.0% |
306
+ | EV the root play loses at the full tree's values, OOP / IP | 0.027 / 0.022% of pot | 0.028 / 0.020% |
307
+
308
+ Size agreement compares which bet size each hand's EVs rank best in the blueprint and in
309
+ the full tree. It is fragile where sizes are near-tied. With the current solver, whose
310
+ average strategy changed while these runs were going, OOP's agreement reads 75%, and the
311
+ root EV error 2.0 / 1.9% of pot. The EV the root play loses held: 0.019 / 0.014% of pot.
312
+ That is the number to go by. IP's low size agreement after a check is near-indifference: only 15% of its betting hands
313
+ prefer one size by 0.5% of pot or more, the blueprint agrees on 89% of those, and its play
314
+ loses 0.02% of pot. The per-action EV errors are largest for the flop shove (11–33% of pot
315
+ for IP), a line neither tree plays. More turn/river sizes did worse here: two sizes
316
+ (0.33, 1.5) gave 4.4 / 5.7% EV error and three gave 4.7 / 6.1%, at 336 and 417 MiB. On the
317
+ rainbow As Kh 7d, which has about 4.5 times the runouts, the same blueprint is estimated at
318
+ 1.2 GiB f32, 363 MiB with buckets at i16.
319
+
320
+ A re-solved turn, over the 15 most-reached turn nodes, took about 12 s in Node on one
321
+ thread and 5–40 MiB. Against it, an opponent playing a best response with the full tree's
322
+ ranges gains, weighted by how often each turn is reached, 3.5–4% of the subgame's pot.
323
+
324
+ `resolveSubgame` re-solves without a safety gadget. Safe gadgets, which keep each opponent
325
+ hand from doing better than it did against the blueprint, were measured and made things
326
+ worse (4.2–6.2% of the pot); see [docs/APPROXIMATIONS.md](docs/APPROXIMATIONS.md). With
327
+ `measure: true` it reports each opponent hand's best-response value against the blueprint
328
+ (`alternative`) and against the re-solve (`entered`). A re-solved subgame is a `Solution`, so
329
+ a river below it can be re-solved from it in turn.
330
+
331
+ In headless Chromium (`poker-flopsolve/threads`, Ks 9s 4s), the blueprint with buckets at
332
+ f32 solved to 0.3% in 84 s on one thread and 25 s on four, and each re-solved turn took
333
+ 21 s and 6.6 s with 40 MiB. At i16 without `wasmStorage` it runs on the JavaScript engine,
334
+ about 190 s however many threads it has; with `wasmStorage` from
335
+ `poker-flopsolve/wasm-storage` it runs on the WebAssembly engine, threads included, which
336
+ is what brings the rainbow blueprint into a tab: see
337
+ [16-bit and compact storage on the WebAssembly engine](#16-bit-and-compact-storage-on-the-webassembly-engine).
338
+ A run holds its engine threads until `close()` (which `solve` calls for you), and
339
+ snapshots stay usable after it, so close the blueprint's run before re-solving.
340
+
341
+ `solveLite` packages this recipe, with sharing, sampling and a stop on the root play: see
342
+ [Lite mode](#lite-mode-solvelite) and [Choosing an approximation](#choosing-an-approximation).
343
+
229
344
  ## In a browser
230
345
 
231
346
  The package also runs in a browser, for the small solves a page wants: river spots and
232
347
  narrow turn spots. Bundlers pick the browser build (`dist/browser.js`) automatically
233
- through the `browser` export condition. It is the same solver, single-threaded:
348
+ through the `browser` export condition. It is the same solver, single-threaded by default:
234
349
 
235
350
  - no worker threads, so `workers` resolves to 1 (asking for more logs one warning);
236
351
  - no `SharedArrayBuffer`, so the page needs no cross-origin isolation headers;
@@ -240,12 +355,177 @@ through the `browser` export condition. It is the same solver, single-threaded:
240
355
  A solve blocks the thread it runs on, so host it in a Web Worker and step it in chunks;
241
356
  [`examples/browser-worker.ts`](examples/browser-worker.ts) does that with progress and a
242
357
  stop message in about sixty lines. Flop spots and wide turn spots belong in Node, where
243
- `workers` splits the runouts across cores.
358
+ `workers` splits the runouts across cores, or in a browser with threads turned on.
359
+
360
+ ### Threads in the browser (opt-in)
361
+
362
+ A page can split a solve across cores as Node does, with no approximation. Import
363
+ `enableThreads` from `poker-flopsolve/threads` and await it once, in the Web Worker that
364
+ solves, before solving:
365
+
366
+ ```ts
367
+ import { createRun, defineSpot } from 'poker-flopsolve';
368
+ import { enableThreads } from 'poker-flopsolve/threads';
369
+
370
+ const threads = await enableThreads(); // navigator.hardwareConcurrency, or 1 if unavailable
371
+ const run = createRun(defineSpot(config), { workers: threads });
372
+ ```
373
+
374
+ It starts `threads − 1` engine workers that share the WebAssembly engine's memory, exactly
375
+ as Node's threads do, so a fixed thread count gives the same answer as Node at that count
376
+ (bit for bit where the browser's V8 agrees with Node's on `Math.pow`, as it did in every
377
+ measurement here). They stay started between solves; a solve borrows them and gives them back on
378
+ `close()`. `enableThreads(1)` stops every thread no open run holds. Only the WebAssembly engine (the default) is
379
+ threaded; `engine: 'js'` or `precision: 'f64'` solve on one thread, and so do
380
+ `precision: 'i16'` and `compactStorage` unless the solve passes `wasmStorage` (below).
381
+
382
+ Threads need:
383
+
384
+ - a **cross-origin isolated** page, which gives `SharedArrayBuffer`. Serve the page
385
+ with these headers, and every script it loads from the same origin or with CORS:
386
+
387
+ ```
388
+ Cross-Origin-Opener-Policy: same-origin
389
+ Cross-Origin-Embedder-Policy: require-corp
390
+ ```
391
+
392
+ - the solve to run in a **Web Worker**, since a page's main thread may not block on
393
+ `Atomics.wait`;
394
+ - `blob:` workers allowed, if the page sets a Content Security Policy (`worker-src blob:`).
244
395
 
245
- `npm test` checks the browser build in headless Chromium against Node (skipped where
246
- Playwright is not installed), and `npm run bench:browser` times it beside Node.
396
+ Where any of these is missing, `enableThreads` resolves to 1 and solves stay on one
397
+ thread; `threadsUnavailable()` says why. Without the import nothing changes: the main
398
+ bundle carries only a lookup for the threads, and a solve gives the same results as
399
+ before. The UI's dev server (`npm run ui`) sends the two headers.
247
400
 
248
- ## Performance
401
+ On a 4-core container, headless Chromium, a flop solve to 0.3% of pot took 24.0 s on one
402
+ thread and 8.7 s on four (`npm run bench:browser:threads`).
403
+
404
+ `npm test` checks the browser build in headless Chromium against Node, single-threaded and
405
+ threaded (skipped where Playwright is not installed). `npm run bench:browser` times it
406
+ beside Node, and `npm run bench:browser:threads` times flop solves at each thread count.
407
+
408
+ ## Performance and approximations
409
+
410
+ A plain `solve` is exact: `exploitabilityPercent()` measures the real game and
411
+ `targetPercent` stops there. Everything that trades accuracy for time or memory is opt-in.
412
+ Pick a goal below, not a dozen options.
413
+
414
+ ### Choosing an approximation
415
+
416
+ | Goal | Use | Rainbow, As Kh 7d | Two-tone, Ts 9s 4h | Monotone, Ks 9s 4s |
417
+ |---|---|---|---|---|
418
+ | Fastest flop answer in a browser | [`solveLite`](#lite-mode-solvelite) | 35 s, 511 MiB; root loss 0.023 / 0.014 | 21 s, 426 MiB; 0.118 / 0.076 | 12 s, 253 MiB; 0.059 / 0.037 |
419
+ | Fits a phone, 512 MiB or less | `solveLite` on a spot with `compactStorage: {}`, solved with `wasmStorage` | 300 MiB, 27% slower (Node) | not measured | not measured |
420
+ | Better turn re-solves, in a tab | `solveLite` with `keepBudget: 150 * 2 ** 20`, `precision: 'i16'`, `wasmStorage` | 35 s, 534 MiB; re-solve gain 2.5 / 1.7 (1.3 / 1.1 at 800 it, 59 s) | 22 s, 469 MiB; 1.9 / 1.3 | 11 s, 317 MiB; 2.6 / 1.9 |
421
+ | The whole tree, in 2 GiB or less | [`largeTree`](#fitting-a-large-tree-largetree) | T: 155 s, 1.97 GiB (1.87 in Chromium); root loss 0.031 / 0.020 | not measured | `thinSizes` alone: 0.64 GiB at 32 bits |
422
+ | Exact | `solve(spot, { targetPercent })` | 9.2 s, 708 MiB (0.2%, Chromium) | 10.3 s (Node) | 5.6 s (Node) |
423
+
424
+ How each row was measured, all on 4 threads:
425
+ - **`solveLite`**: issue #47's betting (0.33 / 0.75 / 1.5 pot, a 0.75 raise, all-in, three aggressions;
426
+ pot 55, stack 975, the bench ranges), headless Chromium. Time is until the root play settles. Peak
427
+ memory includes a turn re-solve. Root loss is what OOP's root play / IP's play after a check give up
428
+ at the unshared blueprint's per-action values, % of pot. The phone row's 300 MiB is Node's peak on
429
+ rainbow. The re-solve row is issue #113's: the same blueprint at 16 bits, keeping the most-reached
430
+ flop lines that 150 MiB holds, the pick included in the time. Its gain is an opponent's best response
431
+ to a re-solved turn, % of the subgame pot: plain lite gives 3.1 / 2.7, 4.0 / 3.3 and 3.6 / 3.6, an
432
+ unshared blueprint 0.4–0.7.
433
+ - **`largeTree`**: T, which is As Kh 7d with issue #47's betting on every street (17.2 GiB at 32 bits), in Node. Time is until
434
+ OOP's root loss comes within 0.02% of pot of its final value. Root loss is measured at the per-action values of
435
+ `thinSizes` alone at 32 bits, solved for 600 iterations, whose own play loses the same: the floor.
436
+ - **Exact**: the bench ranges and betting to 0.3% of pot (two-tone and monotone, Node), and the bench
437
+ `flop` spot to 0.2% in Chromium.
438
+
439
+ Every napkinpoker figure on this page (the goal table's notes and the inventory's costs) is an
440
+ aggregate score against napkinpoker's reference solves, whose fixtures are private (issue #119; see
441
+ [Every option on napkinpoker's reference solves](#every-option-on-napkinpokers-reference-solves)).
442
+
443
+ What the numbers mean:
444
+ - **`solveLite`**: decisions near-exact against an equilibrium opponent. Root play loses 0.072% of pot
445
+ at an exact full-game solve's values (issue #51's T₀, rainbow). On eight napkinpoker spots it lost
446
+ 0.034 / 0.135%, where the stored solves' own play loses 0.027 / 0.131. Per-hand root EVs are 0.5–1.9%
447
+ of pot off the unshared blueprint's and 2.9–3.9% off the full game's (T₀). In its own game,
448
+ exploitability plateaus a few % of pot, because the river is shared. Full-game exploitability is not
449
+ measured. A turn re-solved at your full betting gives a best-responding opponent 2.7–4.0% of the
450
+ subgame pot.
451
+ - **`largeTree`**: decisions near-exact against an equilibrium opponent, except where `thinSizes` cuts
452
+ a size the opponent plays. Against an exact full-tree solve, root play loses 0.04% of pot (T₀). On
453
+ seven napkinpoker spots OOP's root lost 0.04%, as an exact solve's does. IP's play after a check lost
454
+ 0.34% against 0.16%, because its 0.33 flop bet is cut there. Per-hand root EVs are 0.05% of pot off
455
+ the thinned tree's and about 1.5% (5.5% at worst) off the full tree's (T₀). In its own, thinned game,
456
+ exploitability is 0.35% of pot after 1,600 iterations. Full-game exploitability is not measured.
457
+ - **Exact**: exploitability is measured in the full game, every card dealt.
458
+
459
+ #### The presets
460
+
461
+ Both presets take any betting of yours and return what they changed, so nothing is silent:
462
+
463
+ ```ts
464
+ import { createRun, defineSpot, solveLite } from 'poker-flopsolve';
465
+ import { largeTree } from 'poker-flopsolve/wasm-storage';
466
+
467
+ const lite = solveLite(spot, { workers: 4 });
468
+ lite.changes.roundsSimplified; // ['turn', 'river']
469
+ lite.changes.notes; // ['turn: OOP loses the bet sizes 0.33, 1.5, all-in at 17 of the 19 such decisions the preset keeps', ...]
470
+
471
+ const { config, options, changes } = largeTree({ ...spot, maxBytes: 2.5 * 2 ** 30 }, { options: { workers: 4 } });
472
+ changes.sizesCut; // [{ street: 'flop', player: 'ip', facing: 'bet', sizes: [0.33, 1.5, 'allin'], ... }, ...]
473
+ const run = createRun(defineSpot(config), options);
474
+ ```
475
+
476
+ `changes.sizesCut` lists every bet, raise and shove size your tree offers and the preset's does not, by
477
+ street, player and whether it opens the betting or answers a bet. It also counts the decisions that lost
478
+ them. `changes.settings` lists every other setting the preset set or dropped, with your value and its
479
+ own. `changes.notes` says each in a sentence. `litePreset(spot)` returns what `solveLite` would solve
480
+ (`config`, `options` and `changes`) without solving it, for a page that steps its own run.
481
+
482
+ `largeTree` stays in `poker-flopsolve/wasm-storage`, beside the storage engine it needs. It returns
483
+ that engine in its `options`, so moving it to the main entry would mean either carrying the engine's
484
+ 36 KB in every build or loading it with a dynamic `import()`. The first breaks the promise that a build
485
+ without the import is unchanged. The second would make `largeTree` asynchronous, which is a breaking
486
+ change, and the build does not split chunks. `solveLite` needs no second engine and is in the main
487
+ entry.
488
+
489
+ ### Options inventory
490
+
491
+ Every opt-in, by status:
492
+ - **Preset-internal**: a preset sets it for you. Reach for it directly only to tune a preset.
493
+ - **Advanced**: measured and supported, for a caller who knows the trade.
494
+
495
+ Dead ends are removed rather than deprecated; [docs/APPROXIMATIONS.md](docs/APPROXIMATIONS.md) keeps
496
+ their numbers.
497
+
498
+ Costs are from napkinpoker's three 3-bet spots (issue #103) unless a section is named: storage and time
499
+ against the exact solve at equal iterations, root loss OOP / IP in % of pot (the exact solve's is
500
+ 0.059 / 0.054), and true exploitability.
501
+
502
+ | Option | Status | Engines | Refuses | Measured cost |
503
+ |---|---|---|---|---|
504
+ | `solveLite` / `litePreset` | preset | both | — | settled at 2.6× the iterations: 0.22× storage, 0.30× time, root 0.052 / 0.068, turn nodes 0.127, 1.89% exploitable ([Lite mode](#lite-mode-solvelite)) |
505
+ | `largeTree` | preset | WebAssembly | — | at 4× the iterations: 0.38× storage, 0.58× time, root 0.057 / 0.289 (IP's cut 0.33 bet), 0.39% exploitable in its own tree ([Fitting a large tree](#fitting-a-large-tree-largetree)) |
506
+ | `shareHistories` | preset-internal (lite) | both | — | 0.40× storage, 1.00× time, root 0.061 / 0.068, 1.89% exploitable |
507
+ | `keepBudget` (`solveLite`), `shareHistories.keepLines`, `linesWithin` | advanced (a lite option) | both | — | turn re-solve gain within 0.1–0.8% of the subgame pot of an unshared blueprint's, against 3.0–4.2% from plain sharing ([History sharing](#history-sharing)) |
508
+ | `runoutBuckets` | preset-internal (lite) | both | — | folds nothing on napkinpoker's weighted ranges. Bench ranges, gap 3: 0.61× time, true exploitability 0.302 against 0.271 ([Runout buckets](#runout-buckets-and-coarse-start)) |
509
+ | `approximations.chanceSampling` | preset-internal (both) | both, threaded | — | at 4× the iterations: 0.69× time, root 0.057 / 0.056, 0.60% exploitable |
510
+ | `settle` | preset-internal (lite) | both | — | two strategy reads per check, no best-response pass |
511
+ | `thinSizes` | preset-internal (`largeTree`) | both | — | 0.74× storage, 0.66× time, root 0.067 / 0.294 (IP's cut 0.33 bet), 0.22% in its own tree |
512
+ | `precision: 'i16'` with `wasmStorage` | preset-internal (`largeTree`) | WebAssembly with `wasmStorage`, else JavaScript | — | 0.52× storage, 1.16× time, root 0.059 / 0.067, 0.37% exploitable |
513
+ | `compactStorage` | advanced (`largeTree`'s `storage: 'compact'`) | WebAssembly with `wasmStorage`, else JavaScript | `analysisOnly` | 0.37× storage, 1.37× time, root 0.063 / 0.080, 0.63% exploitable |
514
+ | `resolveSubgame` | preset-internal (`LiteSolution.resolve`) | both | — | blueprint plus re-solves: 0.68× time, turn loss 0.053 against 0.031 exact |
515
+ | `approximations.coarseStart` | advanced | both | `warmStart` | does nothing where buckets fold nothing (all of napkinpoker's spots), or beside `runoutBuckets` at its own gap or wider. Bench flops in Chromium at 15 s: root EV error 1.51 → 0.19% of pot ([Runout buckets and coarse start](#runout-buckets-and-coarse-start)) |
516
+ | `approximations.currentProfileEv` | advanced | both | `analysisOnly` | no more than reading EVs; per-hand EVs often 2–4× closer at equal iterations |
517
+ | `analysisOnly` | advanced | both, at 32 bits | `compactStorage`, `currentProfileEv` | loads a saved strategy; keeps no regrets |
518
+ | `warmStart`, `warmCards` | advanced | both | — | see [Warm starts](#warm-starts) |
519
+ | `minWeight` | advanced | both | — | edits the ranges: 2–5% less storage, up to 15% less time on napkinpoker's spots |
520
+ | `engine: 'js'` | advanced | JavaScript | — | the reference engine, about 2.4× slower; `precision: 'f64'` runs on it |
521
+ | `isomorphism: false`, `simd: false`, `algorithm: 'cfr+'` | advanced | both | — | exact; off switches for comparison |
522
+
523
+ `test/combinations.test.ts` solves every pair of `shareHistories`, `compactStorage`, `thinSizes`,
524
+ `runoutBuckets`, `chanceSampling`, `coarseStart`, 16-bit `wasmStorage`, `resolveSubgame`,
525
+ `litePreset` and `largeTree` (45 pairs); none is refused. Every approximation
526
+ tried and left out, with its numbers and issue, is in [docs/APPROXIMATIONS.md](docs/APPROXIMATIONS.md).
527
+
528
+ ### Exact speed
249
529
 
250
530
  Measured on an Apple M2, single threaded:
251
531
 
@@ -268,8 +548,10 @@ warm start and analysis works unchanged. With threads (Node), all of them share
268
548
  WebAssembly memory and split the runouts as below. It runs wherever it can — 32-bit
269
549
  storage, the default, and WebAssembly SIMD, which current Node and browsers have —
270
550
  and `run.engine` says which ran. `engine: 'js'` forces the JavaScript traversal;
271
- `precision: 'f64'` or `'i16'` use it too. Against the JavaScript traversal it is about
272
- 2.4× faster per iteration, and about 3× in Chromium.
551
+ `precision: 'f64'` uses it too, and so do `'i16'` and `compactStorage` unless the solve
552
+ passes `wasmStorage` (see
553
+ [16-bit and compact storage on the WebAssembly engine](#16-bit-and-compact-storage-on-the-webassembly-engine)). Against the JavaScript traversal it is about 2.4× faster per
554
+ iteration, and about 3× in Chromium.
273
555
 
274
556
  ### SIMD kernels
275
557
 
@@ -288,8 +570,21 @@ Chromium, exploitability checks ~8%.
288
570
  When swapping suits leaves the board and both ranges unchanged, a deal in one of those
289
571
  suits is the mirror image of a deal in another, and only one is solved. On a two-tone flop
290
572
  the two absent suits are interchangeable; on a monotone flop, all three. This is exact —
291
- the solver keeps mirrored hands' strategies tied together, so a stored runout stands for
292
- its mirrors with nothing lost — and it is on by default (`isomorphism: false` turns it off).
573
+ mirrored hands play alike, so a stored runout stands for its mirrors with nothing lost —
574
+ and it is on by default (`isomorphism: false` turns it off).
575
+
576
+ The same symmetry is used a second time inside each stored board: hands that mirror each
577
+ other there (on Ks9s4s, AhAd, AhAc and AdAc) are stored once, and every vector, regret and
578
+ strategy sum on that board shrinks with them. Card removal stays exact, because the fold and
579
+ showdown kernels still count each opposing hand's own cards. Measured single-threaded, ms
580
+ per iteration with the same iterations to every target:
581
+
582
+ | Flop | Hands stored on the river | ms per iteration | Memory |
583
+ |---|---|---|---|
584
+ | Ks9s4s, monotone, bench ranges | 245,916 → 171,442 | 78 → 62 | 38 → 27 MB |
585
+ | Ks9s4s, pairs and broadway | 264,184 → 177,944 | 80 → 59 | 41 → 28 MB |
586
+ | Ts9s4h, two-tone | 522,944 → 458,484 | 154 → 143 | 81 → 71 MB |
587
+ | AsKh7d, rainbow | 784,806 → 784,806 | unchanged | unchanged |
293
588
 
294
589
  | Flop, 4 threads | Runouts stored | To 0.3% of pot |
295
590
  |---|---|---|
@@ -302,58 +597,56 @@ runouts. To read a mirrored one, `spot.resolveBoard('Ts9s4h 7c')` gives the stor
302
597
  and how hands relabel onto it. Ranges that differ between suits anywhere — an exact combo,
303
598
  or a partial weight on one suit — have no symmetry to use, and solve as before.
304
599
 
305
- ### Runout buckets (approximate)
306
-
307
- `runoutBuckets: true` solves one turn or river card for several that play alike: two cards
308
- of one suit, neither pairing the board, equally connected to its straights, whose rank
309
- swap maps both ranges onto themselves. The stored card stands for the others with hands
310
- relabelled by the swap. A number instead of `true` is the widest rank gap allowed in a
311
- bucket (`true` is 1, the most cautious).
312
-
313
- It is an approximation — 55 on a 6 river and 66 on a 5 river sit on opposite sides of the
314
- board card, and no relabelling fixes that — so `exploitabilityPercent()` (and
315
- `targetPercent`) measure the bucketed game, and `run.trueExploitabilityPercent()` measures
316
- the strategy in the real one, every card dealt. How much it saves and costs depends on
317
- the ranges; suited connectors keep ranks apart, pocket pairs near the merged ranks cost
318
- accuracy. On AhKdQc, 4 threads, to 0.3% of pot in the bucketed game:
600
+ ### Accuracy targets
319
601
 
320
- | Ranges | Gap | Runouts | Time | True exploitability |
321
- |---|---|---|---|---|
322
- | Bench (wide, connectors) | exact | 2,352 | 13.2 s | 0.271% |
323
- | | 1 | 1,672 | 10.5 s | 0.278% |
324
- | | 3 | 1,348 | 8.0 s | 0.302% |
325
- | Pairs and broadway | exact | 2,352 | 9.3 s | 0.228% |
326
- | | 1 | 1,396 | 4.9 s | 0.482% |
327
- | | 3 | 1,088 | 4.2 s | 0.542% |
602
+ `solve(spot, { targetPercent })` stops as soon as exploitability reaches that percentage of
603
+ the pot, making `iterations` a cap rather than a plan. This is the cheapest way to cut solve
604
+ time, because the last decimal place of accuracy costs most of the run:
328
605
 
329
- ### 16-bit storage
606
+ | Target | Iterations | Time |
607
+ |---|---|---|
608
+ | 2% | 20 | 0.28 s |
609
+ | 1% | 24 | 0.26 s |
610
+ | 0.5% | 39 | 0.29 s |
611
+ | 0.25% | 57 | 0.35 s |
612
+ | 0.1% | 127 | 0.57 s |
613
+ | 0.05% | 200 | 0.73 s |
614
+ | none (500 iterations) | 500 | 1.43 s |
330
615
 
331
- A spot too big for 32-bit storage under `maxBytes` is solved at 16 bits instead
332
- (`precision: 'i16'` forces it). Regrets and strategy sums are stored as 16-bit integers with
333
- one scale per node and board, about halving memory. `estimate.compressedBytes` reports
334
- that size, and a spot is refused only if even that exceeds `maxBytes`. Measured on AsKh7d:
616
+ As a guide, 1% of pot is a sketch, 0.5% is enough to read strategies off, and 0.1% is
617
+ publishable. On the flop preset in the browser UI, a 0.5% target finishes in 2 s against an
618
+ estimated 24 s for the full iteration count.
335
619
 
336
- | Flop | Ranges | 32-bit | 16-bit |
337
- |---|---|---|---|
338
- | 1 size, 1 raise | 198 vs 165 | 150 MB | 85 MB |
339
- | 2 sizes, 1 raise | 198 vs 165 | 824 MB | 425 MB |
340
- | 2 sizes, 1 raise | 309 vs 424 | 1,645 MB | 836 MB |
341
- | 2 sizes, 2 raises | 309 vs 424 | 3,344 MB | 1,689 MB |
620
+ Checking is not free: it is a full best-response pass for both players, about one
621
+ iteration's work, spread across the same threads as the solve. Rather than pick a cadence, the solver predicts when the target will be met — CFR+
622
+ exploitability falls as roughly `C / T^p`, so two measurements pin the crossing — and checks
623
+ just short of it. On a 500-iteration run that is 7 checks and 4% overhead, against 50 checks
624
+ and 23% for a fixed cadence of 10.
342
625
 
343
- The 309 vs 424, two-size flop solved with two threads at a peak RSS of about 1.1 GB, so it
344
- fits a 2 GB machine. It reaches each accuracy target in the same number of iterations as
345
- 32-bit, but each iteration costs about 15–20% more, because every update re-encodes its
346
- block. Strategy sums round up or down at random, weighted by the remainder: rounded to
347
- nearest, small sums lose most of each iteration's contribution and exploitability stalls
348
- near 0.04% of pot. The randomness is a hash of the slot and iteration, so solves stay
349
- deterministic at any thread count.
626
+ `solution.stoppedAt` is `'target'` or `'iterations'`. The second with a target set means the
627
+ target was *not* reached and the answer is looser than asked for, which the CLI and the UI
628
+ both say out loud.
350
629
 
351
630
  ### Algorithm and benchmark
352
631
 
353
632
  The default update rule is Discounted CFR (`algorithm: 'dcfr'`, α 1.5, β 0, γ 3, with
354
633
  positive regret counted from the second iteration so the uniform first iteration is
355
- forgotten). CFR+ is still available as `algorithm: 'cfr+'`. The table below predates the
356
- 0.2.0 schedule, which needs 10–15% fewer iterations on flop and turn spots. `npm run bench` times a fixed river, turn, flop
634
+ forgotten). CFR+ is still available as `algorithm: 'cfr+'`.
635
+
636
+ Under DCFR, each iteration adds its strategy to the average without weighting it by the
637
+ hand's own reach, as postflop-solver does. With own-reach weighting, a hand that equilibrium
638
+ play stops sending to a node averaged out to its near-uniform first iterations there, so
639
+ continuing it off the path (browsing the hand, comparing an engine against the solve) played
640
+ close to random. On a turn spot after 300 iterations, near-uniform play among hands reaching
641
+ a node with under 0.1% of their starting weight fell from 8% to 0.6%. The cost, single-threaded
642
+ on the regression spots: exploitability at a fixed iteration count is up to about 50% higher
643
+ once it is small (turn, 400 iterations: 0.016% → 0.024% of pot), which is 0–14% more
644
+ iterations to 0.3% or 0.1% of pot (turn 79 → 88 and 143 → 163; flop 62 → 69 and 112 → 115)
645
+ and about the same to 1%. CFR+ keeps the own-reach weighting: its iterates oscillate, and
646
+ unweighted they averaged to 2–3× the exploitability.
647
+
648
+ The table below predates both this change and the 0.2.0 schedule, which needs 10–15% fewer
649
+ iterations on flop and turn spots. `npm run bench` times a fixed river, turn, flop
357
650
  and two-tone flop. Measured in a 4-core cloud container, seconds of solving to reach each
358
651
  target (exploitability checks excluded):
359
652
 
@@ -385,39 +678,9 @@ bundled. Measured in a 4-core cloud container, time to 0.3% of pot:
385
678
  | Flop | 4 | 9.1 s | 5.1 s | 1.8× |
386
679
  | Monotone flop | 4 | 2.9 s | 1.4 s | 2.1× |
387
680
 
388
- 0.2.0, still in JavaScript, was 4–6× behind; the WebAssembly engine below is most of
681
+ 0.2.0, still in JavaScript, was 4–6× behind; the WebAssembly engine above is most of
389
682
  the difference.
390
683
 
391
- ### Accuracy targets
392
-
393
- `solve(spot, { targetPercent })` stops as soon as exploitability reaches that percentage of
394
- the pot, making `iterations` a cap rather than a plan. This is the cheapest way to cut solve
395
- time, because the last decimal place of accuracy costs most of the run:
396
-
397
- | Target | Iterations | Time |
398
- |---|---|---|
399
- | 2% | 20 | 0.28 s |
400
- | 1% | 24 | 0.26 s |
401
- | 0.5% | 39 | 0.29 s |
402
- | 0.25% | 57 | 0.35 s |
403
- | 0.1% | 127 | 0.57 s |
404
- | 0.05% | 200 | 0.73 s |
405
- | none (500 iterations) | 500 | 1.43 s |
406
-
407
- As a guide, 1% of pot is a sketch, 0.5% is enough to read strategies off, and 0.1% is
408
- publishable. On the flop preset in the browser UI, a 0.5% target finishes in 2 s against an
409
- estimated 24 s for the full iteration count.
410
-
411
- Checking is not free: it is a full best-response pass for both players, about one
412
- iteration's work, spread across the same threads as the solve. Rather than pick a cadence, the solver predicts when the target will be met — CFR+
413
- exploitability falls as roughly `C / T^p`, so two measurements pin the crossing — and checks
414
- just short of it. On a 500-iteration run that is 7 checks and 4% overhead, against 50 checks
415
- and 23% for a fixed cadence of 10.
416
-
417
- `solution.stoppedAt` is `'target'` or `'iterations'`. The second with a target set means the
418
- target was *not* reached and the answer is looser than asked for, which the CLI and the UI
419
- both say out loud.
420
-
421
684
  ### Workers
422
685
 
423
686
  `solve(spot, { workers })` splits the runouts across threads, the calling thread included:
@@ -440,11 +703,31 @@ Measured on a 133 vs 145 combo spot, 8 cores:
440
703
  a 2-core machine still splits; `workers: 1` stays on one thread. A river spot has a single runout and silently stays single-threaded whatever is
441
704
  asked for.
442
705
 
706
+ A thread that fails mid-iteration fails the solve instead of hanging it: the step throws, as
707
+ does every step after, and the run must be closed and solved again. A thread killed without
708
+ any chance to report it (a Node worker out of heap, a worker the browser kills) is caught by
709
+ a backstop instead: the main thread waits for the others at most 20× its own share of the
710
+ step, and never less than a minute, before it gives up on them.
711
+
443
712
  Results are bitwise deterministic at a fixed worker count, but agree with a different count
444
713
  only to floating point: a worker sums its own slice before the totals are summed across
445
- workers, which associates the same addition differently, and the non-linear CFR+ clamp
446
- compounds that rounding. Measured, the gap sits at 1e-15 through 300 iterations and reaches
447
- 1e-7 by 2,000 — always orders of magnitude below the exploitability at that point.
714
+ workers, which associates the same addition differently. Regret matching then amplifies
715
+ that rounding, as it does any small change: an action's share follows its regret's sign,
716
+ and where hands are close to indifferent the 32-bit gap grows from iteration to iteration.
717
+ Measured on a small turn (`Ah Kd Qc 8s`, half- and full-pot bets, two raises), 1 and 2
718
+ threads agree on the root strategy to 2e-6 after 12 iterations, differ by up to 6e-2 after
719
+ 50 and by about 1e-2 after 300, by which point each is as exploitable as the other (0.02%
720
+ of pot): where the equilibrium is not unique, the two solves settle on different
721
+ strategies that are equally good. The two engines differ from each other the same way.
722
+
723
+ Exact ties are kept out of this (issue #117). Where a hand's actions are worth the same,
724
+ its regrets are analytically zero, but the node value they are measured against is a
725
+ strategy-weighted sum and comes out an ulp off, by a sign that depends on the summation
726
+ order — and one positive ulp plays an action purely where none plays uniformly. So an
727
+ action value within 2^-20 of the hand's node value, relative to the larger of the two,
728
+ adds exactly zero regret, in both engines: tied actions stay uniform whatever the thread
729
+ count. Without it, a tree with many ties (one river size and no all-in) put 1 and 2 threads
730
+ 3% apart after 12 iterations.
448
731
 
449
732
  The single largest cost is the number of runouts: a river board has one, a turn 48, a flop
450
733
  2,352. Tree width matters nearly as much — a second bet size roughly quadruples the work.
@@ -455,6 +738,566 @@ symmetry: measured, a rainbow flop's stabiliser is trivial and gains **1.00×**,
455
738
  of the conclusion in the parameterised solver alongside this one, where the flop itself is
456
739
  enumerated and can be canonicalised for a 12× win.
457
740
 
741
+ ## Appendix: approximations in detail
742
+
743
+ Each option's own measurements, grouped where options overlap. The
744
+ [goal table](#choosing-an-approximation) and the [options inventory](#options-inventory) summarise
745
+ them, and [docs/APPROXIMATIONS.md](docs/APPROXIMATIONS.md) records what was tried and left out.
746
+
747
+ ### Lite mode (`solveLite`)
748
+
749
+ `solveLite` packages that recipe for a phone or laptop. Give it your own betting. It keeps
750
+ the flop's and reduces the turn and river to one bet (your size nearest 0.75 pot, no raise,
751
+ no shove). It shares river storage between lines that meet (`shareHistories`), buckets
752
+ runouts (`runoutBuckets: 3`) and samples deals (`chanceSampling`), and it stops once the
753
+ root play stops moving. It then re-solves any turn or river at your full betting on demand:
754
+
755
+ ```ts
756
+ import { solveLite } from 'poker-flopsolve';
757
+
758
+ const spot = { board: 'As Kh 7d', pot: 55, stack: 975, oop, ip,
759
+ betSizes: [[0.33, 0.75, 1.5]], raiseSizes: [[0.75]], maxRaises: 3, allowAllIn: true };
760
+ const lite = solveLite(spot, { workers: 4 }); // after enableThreads(4) in a browser
761
+ lite.solution.strategyAt(0, 0); // the flop root
762
+ const turn = lite.resolve(node, board, { player: 0, iterations: 300 });
763
+ ```
764
+
765
+ `lite.changes` says what the blueprint cut from your betting and what it switched on (see
766
+ [The presets](#the-presets)). `litePreset(spot)` returns the blueprint spot, the solve settings and
767
+ that report without solving, for a page that steps its own run; `liteConfig(spot)` returns the spot
768
+ alone. `trackSettle()` gives the same stop for such a loop. Lite is a shared blueprint, so it
769
+ never reaches an exploitability target: it plateaus a few percent of the pot from
770
+ equilibrium while its first decisions go on settling (issue #85). `SolveOptions.settle`
771
+ is the stop. Every 20 iterations it reads the average strategy at the root and at in
772
+ position's decision after a check. It stops once both have moved less than 1% of the
773
+ range, by total variation weighted by range, twice in a row. That is two strategy reads,
774
+ with no best-response pass. It works on any solve: `solve(spot, { settle: {} })`.
775
+
776
+ Measured on that spot's betting, in headless Chromium. The time counts solving and the settle
777
+ checks. Root play loss is what OOP's root mix and IP's mix after a check lose at the
778
+ unshared blueprint's per-action values (solved to 0.05% of pot), with that blueprint's
779
+ own loss as the floor. It measures what sharing, sampling and the early stop cost.
780
+ Re-solve gain is an opponent's best response to a turn re-solved at the full betting
781
+ (300 iterations), under the unshared blueprint's ranges, % of the subgame pot, weighted
782
+ by how often each turn is reached:
783
+
784
+ | flop | settled, 1 / 2 / 4 threads | peak memory | root play loss, % pot (floor) | re-solve gain, % (unshared) | a re-solve, 1 / 2 / 4 threads |
785
+ |---|---|---|---|---|---|
786
+ | As Kh 7d | 103 / 59 / 35 s | 511 MiB | 0.023 / 0.014 (0.009 / 0.008) | 3.1 / 2.7 (0.67 / 0.50) | 38 / 22 / 14 s |
787
+ | Ts 9s 4h | 64 / 38 / 21 s | 426 MiB | 0.118 / 0.076 (0.116 / 0.052) | 4.0 / 3.3 (0.48 / 0.55) | 42 / 23 / 13 s |
788
+ | Ks 9s 4s | 31 / 19 / 12 s | 253 MiB | 0.059 / 0.037 (0.047 / 0.025) | 3.6 / 3.6 (0.44 / 0.47) | 28 / 17 / 10 s |
789
+
790
+ Peak memory includes a re-solve. Against exact solves of the full game:
791
+ - **Issue #51's T₀ on As Kh 7d** (three sizes and a shove on every street): OOP's root
792
+ play lost 0.072% of pot at T₀'s values. The same simplified tree, unshared and
793
+ converged, lost 0.057, so most of the cost is the simplification.
794
+ - **Eight of napkinpoker's postflop-solver spots** (real weighted ranges, SRP and 3-bet
795
+ pots): root play lost 0.034 / 0.135% of pot on average, against 0.027 / 0.131 for the
796
+ stored solves' own play, settling in 38–176 s on one thread. Wide single-raised ranges
797
+ needed up to 452 MiB of storage, near a browser's default `maxBytes` of 512. For more
798
+ headroom add `compactStorage` and `wasmStorage`: 300 MiB on rainbow, 27% slower.
799
+
800
+ `laterRaise: true` keeps a turn and river raise: 1.74 times the time and 546 MiB.
801
+ `noDonk` and `flopMaxRaises: 2` save 44% an iteration together, but on Ts 9s 4h they
802
+ quadrupled the re-solve gain. So they are off unless asked for.
803
+
804
+ **Better turn re-solves: `keepBudget`.** It keeps the most-reached flop lines unshared, as
805
+ many as a storage budget allows (issue #113; see [History sharing](#history-sharing)).
806
+ The lines are ranked on a short solve of the blueprint with its river checked down
807
+ (`checkedDown`), and the blueprint is solved with them kept. `litePreset` runs that
808
+ ranking too, and `keepWithin` does it alone:
809
+
810
+ ```ts
811
+ import { wasmStorage } from 'poker-flopsolve/wasm-storage';
812
+
813
+ const lite = solveLite(spot, { workers: 4, keepBudget: 150 * 2 ** 20, precision: 'i16', wasmStorage });
814
+ lite.kept; // ['check check /', 'bet 18.15 call /', 'bet 82.5 call /'] on As Kh 7d
815
+ ```
816
+
817
+ Measured the same way, the ranking included in the time:
818
+
819
+ | flop | kept | settled, 1 / 2 / 4 threads | peak memory, 1 / 2 / 4 | root play loss, % pot | re-solve gain, % |
820
+ |---|---|---|---|---|---|
821
+ | As Kh 7d | 3 lines | 123 / 61 / 35 s | 489 / 509 / 534 MiB | 0.026 / 0.011 | 2.5 / 1.7 |
822
+ | Ts 9s 4h | 6 lines | 69 / 37 / 22 s | 437 / 463 / 469 MiB | 0.115 / 0.063 | 1.9 / 1.3 |
823
+ | Ks 9s 4s | all 19 | 32 / 19 / 11 s | 290 / 301 / 317 MiB | 0.056 / 0.036 | 2.6 / 1.9 |
824
+
825
+ The root play is unchanged, and the re-solve gain falls by a third to a half. The rest is
826
+ the early stop: the root settles before the ranges reaching the turn do. With every line
827
+ kept, monotone still re-solved at 2.6 / 1.9 when it settled, but at 1.0 / 0.6 after 800
828
+ iterations. Run longer with `settle: false, iterations: 800`: As Kh 7d then re-solves at
829
+ 1.3 / 1.1 in 59 s on 4 threads (533 MiB), where plain sharing gives 2.2 / 2.4.
830
+ `bench/lite/` has the scripts and logs.
831
+
832
+ ### Fitting a large tree (`largeTree`)
833
+
834
+ `largeTree` from `poker-flopsolve/wasm-storage` returns the combination of memory levers
835
+ that measured best on the round's target T (As Kh 7d, three sizes, a 0.75 raise and all-in,
836
+ three aggressions, every street; 17.2 GiB at 32 bits): `thinSizes`, 16-bit storage on the
837
+ WebAssembly engine and chance sampling.
838
+
839
+ ```ts
840
+ import { createRun, defineSpot } from 'poker-flopsolve';
841
+ import { largeTree } from 'poker-flopsolve/wasm-storage';
842
+
843
+ const { config, options } = largeTree(
844
+ { ...myConfig, maxBytes: 2.5 * 2 ** 30 }, // the browser build's default, 512 MiB, is too little
845
+ { options: { workers: 4 } }, // solve options of your own, merged; storage: 'compact' for less memory
846
+ );
847
+ const run = createRun(defineSpot(config), options);
848
+ ```
849
+
850
+ Issue #102 measured each combination on T, Node, 4 threads, against `thinSizes` alone at
851
+ 32 bits solved for 600 iterations (0.154% of pot). Loss is what the root play gives up at the
852
+ reference's per-action EVs, OOP at the root / IP after a check, % of pot. The reference's
853
+ own unconverged mix loses 0.032 / 0.019 at its own values, so that is the floor. "Settled"
854
+ is when OOP's loss comes within 0.02% of pot of its final value. EV error is per hand at the
855
+ root, mean.
856
+
857
+ | Combination | Storage | Peak, Node / Chromium | s/iteration, Node / Chromium | Settled | Loss at the end | EV error |
858
+ |---|---|---|---|---|---|---|
859
+ | `thinSizes`, 16-bit | 1.47 GiB | 1.75 / 1.65 GiB | 1.56 / 1.48 | 317 s | 0.031 / 0.020 | 0.04 / 0.02 |
860
+ | `thinSizes`, compact | 1.02 GiB | 1.28 / 1.20 GiB | 1.95 / 1.89 | 396 s | 0.033 / 0.020 | 0.03 / 0.06 |
861
+ | **`thinSizes`, 16-bit, sampling (`largeTree`)** | 1.47 GiB | 1.97 / 1.87 GiB | 0.25 / 0.23 | **155 s** | 0.031 / 0.020 | 0.05 / 0.05 |
862
+ | `thinSizes`, compact, sampling (`storage: 'compact'`) | 1.02 GiB | 1.48 / 1.42 GiB | 0.28 / 0.27 | 168 s | 0.031 / 0.020 | 0.05 / 0.09 |
863
+ | `thinSizes`, 16-bit, sampling, `runoutBuckets: 3` | 0.86 GiB | 1.25 / 1.14 GiB | 0.14 / 0.14 | 87 s | 0.031 / 0.020 | 0.20 / 0.17 |
864
+ | `thinSizes`, 16-bit, `shareHistories` | 0.42 GiB | 0.69 GiB | 1.70 | 525 s | 0.048 / 0.019 | 0.51 / 0.48 |
865
+
866
+ So 16-bit or compact storage and sampling cost the root nothing over the thinned tree, and
867
+ sampling makes it 2.5 times faster. Buckets halve the time again for a per-hand error of
868
+ 0.2% of pot on average and 2.3% at worst. Sharing on top saves memory but loses more and is
869
+ no faster. What `thinSizes` itself costs, against the full tree, was measured on T₀ against
870
+ an exact solve: 0.04% of pot of root play and 1.5% of pot of per-hand EV. On seven of
871
+ napkinpoker's spots (#87), against postflop-solver's EVs, the preset's root play lost as
872
+ little as an exact solve's at OOP's root (0.04% of pot) but 0.34% against 0.16% for IP after
873
+ a check, where `thinSizes` cuts the 0.33 bet. `bench/combos/` has the scripts and every run.
874
+
875
+ #### Thinning bet sizes (`thinSizes`)
876
+
877
+ `thinSizes: true` keeps the configured sizes only where they earn their memory. The root
878
+ keeps every size. Every other decision keeps the one bet, raise or shove nearest 0.75 of
879
+ the pot, or a shove where that size would be one. A river opening bet after an earlier
880
+ street saw a bet also keeps sizes above the pot and the shove. A tree's memory is almost
881
+ all on the river, and each flop or turn size multiplies the river subtrees below it. This
882
+ rule cuts most of them. It is the shape that growing sizes one at a time by value per
883
+ byte arrived at (issue #51), applied as a fixed rule. It costs nothing to build, and
884
+ unset, the tree is unchanged.
885
+
886
+ It changes the game. A thinned tree is a smaller game, solved exactly within itself, and
887
+ its strategy has no answer to the sizes that were cut. Measured on bench ranges, pot 55,
888
+ stack 975, sizes 0.33 / 0.75 / 1.5 with a shove. The reference is the full tree with
889
+ shove-only raises and 2 aggressions (T₀), solved exactly to 0.23% of pot. Root EVs per
890
+ combination, % of pot, OOP / IP:
891
+
892
+ | Tree | Storage, f32 | Root EV error, mean / max | Root size agrees |
893
+ |---|---|---|---|
894
+ | As Kh 7d, T₀ exact | 5.78 GiB | — | — |
895
+ | `thinSizes` | 1.30 GiB | 1.45 / 1.74, max 5.6 / 6.3 | 83% |
896
+ | The issue's rule: 3 sizes on flop and turn opening bets, 1 elsewhere | 1.97 GiB | 1.59 / 1.34, max 13.5 / 5.1 | 76% |
897
+ | One size everywhere (0.75, shove facing a bet) | 0.39 GiB | 4.41 / 6.58, max 29 / 65 | — |
898
+ | Ks 9s 4s, T₀ exact | 1.26 GiB | — | — |
899
+ | `thinSizes` | 0.29 GiB | 2.10 / 1.90, max 6.2 / 5.9 | 96% |
900
+ | 3 sizes on flop opening bets, 1 elsewhere | 0.19 GiB | 1.47 / 1.64, max 4.2 / 5.8 | 70% |
901
+ | The issue's rule | 0.43 GiB | 1.33 / 1.15, max 3.3 / 6.7 | 89% |
902
+ | Ks 9s 4s, T exact (0.75 raise, 3 aggressions) | 3.75 GiB | — | — |
903
+ | `thinSizes` | 0.64 GiB | 1.26 / 1.01, max 4.4 / 2.1 | 100% |
904
+
905
+ "Root size agrees" is the share of OOP's range whose best root bet size by EV is the same
906
+ as in the exact solve. The max is over combinations weighing at least 1%. On As Kh 7d the
907
+ rule is the most accurate per byte measured: two thirds of the issue's rule's memory, and
908
+ less than half its worst error. On Ks 9s 4s, where the flop's in-position sizes matter
909
+ more, three flop sizes alone did better for less. Peak memory in Node is the tree's: 1.41
910
+ GiB for the first, 0.76 GiB for Ks 9s 4s T.
911
+
912
+ In headless Chromium (WebAssembly engine), an iteration of the thinned As Kh 7d T₀ takes
913
+ 1.9 s on one thread and 0.89 s on four; Ks 9s 4s T₀ 0.66 s and 0.30 s; Ks 9s 4s T 1.44 s
914
+ and 0.64 s. Each reached about 0.2% of pot in 331 iterations, so a solve takes about 11, 4
915
+ and 8 minutes on one thread, and 5, 2 and 3.5 on four.
916
+
917
+ The growth itself is not offered. It found the shape, and grown trees were more accurate
918
+ again (1.0 / 1.2% mean, 3.9% max, 90% agreement in 1.7 GiB on As Kh 7d). But each round
919
+ probes candidate sizes in a second tree beside the current one, which took 4.8 to 8.7 GiB
920
+ and 30 to 40 minutes. On Ks 9s 4s, starting from one size, it never added the flop sizes
921
+ it needed and ended worse than the fixed rule.
922
+
923
+ It combines with `shareHistories`, which shares the river storage of lines that meet:
924
+ the target tree of issue #51, As Kh 7d with a 0.75 raise and 3 aggressions (T), is 17.2 GiB
925
+ at 32 bits, 2.9 GiB thinned, and 0.85 GiB thinned and shared (Ks 9s 4s: 3.75, 0.64, 0.19).
926
+ Issue #102 measured the pair. Thinned and shared, As Kh 7d T₀ stalls at about 4.4% of pot
927
+ exploitability, against 0.2% thinned alone; that is sharing's own floor (shared alone, T₀
928
+ sits at 8%), not a bug. The root play barely notices: it loses 0.052% of pot at the exact
929
+ solve's values against 0.038% thinned alone. But once thinned T fits at 16 bits, sharing
930
+ on top buys memory only, at more loss and no speed; see the preset below.
931
+
932
+ ### History sharing
933
+
934
+ `shareHistories: true` keeps one set of river regrets and strategy sums for every betting
935
+ line that reaches the river with the same pot. With pot-fraction sizes many lines meet:
936
+ check, bet, call and bet, call, and every raise line taken in either order. Their river
937
+ subtrees are identical, so their nodes can share storage. Each line is still walked with
938
+ its own reach, so an iteration costs what it did; only storage shrinks. Off by default.
939
+
940
+ It is lossy. A player plays one river strategy for every line that met, though each line
941
+ brings different ranges. The strategy is still one for the whole game, so
942
+ `exploitabilityPercent()` measures it exactly. Each line's regret is weighted by how often
943
+ the hand plays into it, which cost four times less than plain CFR's sum. Bench ranges, As Kh 7d, pot 55, stack 975, 4 threads, root EVs
944
+ against the exact solve:
945
+
946
+ | Tree | Storage, f32 | Exploitability | Root EV error, mean / max | Iterations |
947
+ |---|---|---|---|---|
948
+ | 3 sizes, all-in raise, 2 aggressions (exact: 0.28%) | 5.8 GiB → 1.22 GiB | 8.0% of pot | 0.72% / 2.5% of pot | 400 |
949
+ | 2 sizes, all-in raise, 2 aggressions (exact: 0.25%) | 1.93 GiB → 0.48 GiB | 5.8% of pot | 0.94% / 2.4% of pot | 400 |
950
+ | 1 size, all-in raise, 2 aggressions (exact: 0.25%) | 0.39 GiB → 0.14 GiB | 4.0% of pot | 0.67% / 6.8% of pot | 300 |
951
+
952
+ On the two-size tree, out of position's EV at each root action was off by 1.7% of pot on
953
+ average, and 85% of the range still picked the same bet size as the exact solve (70%
954
+ with plain CFR's sum, which was left 24% of pot exploitable).
955
+
956
+ On the three-size tree with a 75% raise and three aggressions, which does not fit
957
+ otherwise, 173 river starts collapse to 23: 17.2 GiB becomes 2.9 GiB at 32 bits, and
958
+ 8.7 GiB becomes 1.5 GiB at 16. In Node at 16 bits the whole process peaked at 1.6 GiB
959
+ on one thread (about 100 s an iteration) and 2.0 GiB on four (30 s an iteration), and the
960
+ strategy was 27% of pot exploitable after 50 iterations, 15% after 100 and 12% after 150. At 32 bits it runs on the
961
+ WebAssembly engine in 10.4 s an iteration on four threads, peaking at 3.2 GiB. An
962
+ iteration costs what the unshared tree's would, so this makes the spot fit, not fast.
963
+ Expect a strategy several percent of the pot from equilibrium, with EVs about 1% off on
964
+ average, in a spot that would not otherwise fit. Sharing the turn too, and merging subtrees
965
+ by stack-to-pot ratio, were measured and dropped (see [docs/APPROXIMATIONS.md](docs/APPROXIMATIONS.md)).
966
+ A shared spot can warm-start only from another shared solve.
967
+
968
+ **Keeping the busiest lines unshared.** A turn re-solved from a shared blueprint
969
+ (`resolveSubgame`) inherits only the ranges the blueprint brings to it, and sharing
970
+ distorts them. The flop play is stored unshared, but it learns from shared river values.
971
+ `shareHistories: { keepLines }` gives the named lines (as `Solution.path` names their
972
+ first turn decision, e.g. `"check check /"`) storage of their own. `linesWithin` picks the
973
+ most-reached lines that a storage budget allows. Rank them on a cheap copy of the spot,
974
+ with its river checked down, then solve the hybrid from cold:
975
+
976
+ ```ts
977
+ import { createRun, defineSpot, linesWithin } from 'poker-flopsolve';
978
+ import { wasmStorage } from 'poker-flopsolve/wasm-storage';
979
+
980
+ const blueprint = { ...config, shareHistories: true };
981
+ const pick = createRun(defineSpot({ ...blueprint, betSizes: [flopSizes, turnSizes, []] }), { workers: 4 });
982
+ pick.step(80);
983
+ const keepLines = linesWithin(pick.snapshot(), 150 * 2 ** 20, { config: blueprint, precision: 'i16' });
984
+ pick.close();
985
+ const run = createRun(defineSpot({ ...blueprint, shareHistories: { keepLines } }), { workers: 4, precision: 'i16', wasmStorage });
986
+ ```
987
+
988
+ On issue #47's blueprint (one turn and river size, `runoutBuckets: 3`), turns re-solved
989
+ from plain sharing gave a best response 3.0–4.2% of the subgame pot, against 0.4–0.7% from
990
+ the unshared blueprint. With the budget, the gap was 0.1–0.8%. On As Kh 7d, the 150 MiB
991
+ budget at 16 bits kept 3 lines and peaked at 392 MiB in Chromium on 4 threads, with a
992
+ re-solve gain of 1.47 / 0.92% against 0.67 / 0.50% unshared. Figures are in
993
+ `bench/blueprint-share/README.md`.
994
+
995
+ ### Chance sampling
996
+
997
+ `approximations: { chanceSampling: {} }` walks each turn and river deal on only some
998
+ training iterations, with probability `p` (default 0.35). A deal left out stands in with
999
+ the per-hand values it returned the last time it was walked. A walked deal adds
1000
+ `b + (v − b) / p`, its baseline corrected by how far its values moved (VR-MCCFR,
1001
+ Schmid et al. 2019). Iterations get several times cheaper, convergence per iteration
1002
+ loses less than that, and exploitability is still measured exactly in the full game.
1003
+ Single-threaded, Node, time to 0.3% of pot:
1004
+
1005
+ | Flop | Exact | Sampled | Baselines |
1006
+ |---|---|---|---|
1007
+ | AsKh7d, bench ranges, pot 100 | 23.7 s | 15.9 s | 29 MB |
1008
+ | Ks9s4s, bench ranges, pot 100 | 6.0 s | 4.3 s | 6 MB |
1009
+ | AsKh7d, bench ranges, pot 60 (wide) | 13.4 s | 9.3 s | 29 MB |
1010
+ | AsKh7d, pairs and broadway | 16.7 s | 12.9 s | 31 MB |
1011
+ | Ks9s4s, pairs and broadway | 5.5 s | 4.5 s | 7 MB |
1012
+
1013
+ Stopped at 15 s, single-threaded in Chromium, it leaves 0.29% of pot on the first spot
1014
+ where the exact solve leaves 0.69%, 0.11% for 0.20% on the wide flop and 0.17% for
1015
+ 0.28% on pairs and broadway; the range-weighted error of per-hand root EVs against an
1016
+ exact 0.1% solve falls from 1.0–1.1% of pot to 0.12–0.16% on the first, and to about a
1017
+ third on the others. It runs on `workers` threads wherever the engine threads (issue #99:
1018
+ the WebAssembly engine in Node and the browser, the JavaScript engine in Node). Each thread
1019
+ samples the deals of its own runouts, and whether a deal is walked on an iteration is a hash
1020
+ of its chance node, the deal and the iteration, so every thread count walks the same deals
1021
+ and a fixed count is bitwise repeatable. On 4 Chromium threads it ran 3.1–3.2× faster than on
1022
+ one (`bench/blueprint-share/README.md`). The baselines count against `maxBytes`. With `p: 1` it is the exact solve, bit for bit. `rounds: [2]` samples
1023
+ river deals only. It works over any storage: 32 or 16 bits (since issue #102) or compact.
1024
+
1025
+ ### Storage: 16-bit and compact
1026
+
1027
+ Two ways to store regrets and strategy sums in less memory, and the engine that runs both on WebAssembly.
1028
+
1029
+ #### 16-bit storage
1030
+
1031
+ A spot too big for 32-bit storage under `maxBytes` is solved at 16 bits instead
1032
+ (`precision: 'i16'` forces it). Regrets and strategy sums are stored as 16-bit integers with
1033
+ one scale per node and board, about halving memory. `estimate.compressedBytes` reports
1034
+ that size, and a spot is refused only if even that exceeds `maxBytes`. Measured on AsKh7d:
1035
+
1036
+ | Flop | Ranges | 32-bit | 16-bit |
1037
+ |---|---|---|---|
1038
+ | 1 size, 1 raise | 198 vs 165 | 150 MB | 85 MB |
1039
+ | 2 sizes, 1 raise | 198 vs 165 | 824 MB | 425 MB |
1040
+ | 2 sizes, 1 raise | 309 vs 424 | 1,645 MB | 836 MB |
1041
+ | 2 sizes, 2 raises | 309 vs 424 | 3,344 MB | 1,689 MB |
1042
+
1043
+ The 309 vs 424, two-size flop solved with two threads at a peak RSS of about 1.1 GB, so it
1044
+ fits a 2 GB machine. It reaches each accuracy target in the same number of iterations as
1045
+ 32-bit, but each iteration costs about 15–20% more, because every update re-encodes its
1046
+ block. Strategy sums round up or down at random, weighted by the remainder: rounded to
1047
+ nearest, small sums lose most of each iteration's contribution and exploitability stalls
1048
+ near 0.04% of pot. The randomness is a hash of the slot and iteration, so solves stay
1049
+ deterministic at any thread count.
1050
+
1051
+ #### 16-bit and compact storage on the WebAssembly engine
1052
+
1053
+ ```ts
1054
+ import { createRun, defineSpot } from 'poker-flopsolve';
1055
+ import { wasmStorage } from 'poker-flopsolve/wasm-storage';
1056
+
1057
+ const run = createRun(defineSpot(config), { precision: 'i16', wasmStorage, workers: threads });
1058
+ // or a spot with `compactStorage: {}`, with the same `wasmStorage`
1059
+ ```
1060
+
1061
+ A second build of the engine keeps 16-bit storage and every `compactStorage` mode as the
1062
+ JavaScript engine does, update for update: per-block scales, rounding to nearest for 16-bit
1063
+ regrets, the same hash for the random rounding, per-hand power-of-two scales, `sums: false`,
1064
+ `blockScale`, chance sampling's catch-up. It works in 32-bit floats, four hands to a SIMD
1065
+ vector, where JavaScript works in 64-bit, so a stored value differs from JavaScript's only
1066
+ where it lies within float32 precision of a rounding boundary (about 0.5% of 16-bit values
1067
+ an iteration, 0.01% of compact ones); the solves converge alike. Threads share its memory
1068
+ as they do the default engine's. Only `poker-flopsolve/wasm-storage` carries its bytes, so
1069
+ without the import a build is unchanged, and a solve that does not pass it gives the same
1070
+ results as before.
1071
+
1072
+ Issue #47's blueprint (flop betting kept, one turn and river size, `runoutBuckets: 3`) solved
1073
+ to 0.3% of pot in headless Chromium on a 4-core container, which ran the monotone f32 blueprint
1074
+ about 1.3 times slower than the machine above (`bench/nested/wasm-storage.ts`); peak is the
1075
+ tab's resident memory:
1076
+
1077
+ | As Kh 7d | storage | peak | 4 threads | 1 thread | turn re-solve, 4 / 1 threads |
1078
+ |---|---|---|---|---|---|
1079
+ | f32 | 707 MiB | 985 MiB (902) | 106 s, 280 it | 303 s | 8.5 / 29.6 s, 64 MiB |
1080
+ | i16, `wasmStorage` | 363 MiB | 577 MiB (526 on 1 thread) | 86 s, 200 it | 288 s | 10.6 / 36.0 s, 32 MiB |
1081
+ | compact, `wasmStorage` | 272 MiB | 462 MiB (427) | 106 s, 200 it | 435 s | 12.2 / 40.7 s, 21 MiB |
1082
+
1083
+ | Ks 9s 4s | storage | peak | 4 threads | 1 thread | turn re-solve, 4 / 1 threads |
1084
+ |---|---|---|---|---|---|
1085
+ | f32 | 187 MiB | 394 MiB (346) | 32.5 s, 240 it | 104 s | 7.3 / 21.5 s, 40 MiB |
1086
+ | i16, `wasmStorage` | 97 MiB | 264 MiB (236) | 23.8 s, 160 it | 119 s | 7.0 / 23.8 s, 20 MiB |
1087
+ | compact, `wasmStorage` | 73 MiB | 223 MiB (205) | 35.1 s, 200 it | 119 s | 8.6 / 30.0 s, 14 MiB |
1088
+
1089
+ An iteration costs 1.1–1.15 times f32's at 16 bits and 1.3–1.4 times compact, and the
1090
+ quantised solves often reach the target a check sooner, so the rainbow blueprint at i16 is
1091
+ faster than at f32 in 0.58 times its peak memory. The i16 blueprint on the JavaScript engine
1092
+ took 190 s on one thread or four on monotone. On the bench `flop` spot, to 0.2% of pot
1093
+ (peak): f32 28.5 s on one thread and 9.2 s on four (708 MiB), i16 33.3 s and 10.9 s
1094
+ (293 MiB), compact 41.6 s and 12.6 s (265 MiB), and i16 on the JavaScript engine 80 s and
1095
+ 81 s.
1096
+
1097
+ Issue #84's pass mark for a phone, the rainbow blueprint at 512 MiB peak or less in 60 s or
1098
+ less on four threads, is half met: compact peaks at 462 MiB but takes 106 s, and i16 takes
1099
+ 86 s at 577 MiB. Even f32 takes 106 s here; scaled by the 1.3 above, i16 would take about
1100
+ 66 s on the machine #47 measured.
1101
+
1102
+ WebAssembly memory is one buffer, but Chromium lets it reach wasm32's whole 4 GiB, plain or
1103
+ shared, created at that size or grown to it, while it refuses any ArrayBuffer over 2 GiB less
1104
+ 2 MiB (Chromium 153, `bin/memory-ceiling.ts`). So the engine's ceiling is 4 GiB in a tab, as
1105
+ in Node, and compact storage needs no chunks of its own there.
1106
+
1107
+ #### Compact storage
1108
+
1109
+ `compactStorage: {}` in the spot's config stores regrets and strategy sums as 8-bit
1110
+ integers, each hand on each board scaled by its own power of two. Regret matching and the
1111
+ average strategy divide each hand's values by their own total, so the scale cancels
1112
+ wherever a strategy is read, and costs a byte per hand. Values round up or down at random,
1113
+ weighted by the remainder, as 16-bit sums do. It is set on the spot rather than the solve,
1114
+ because `maxBytes` is checked against it when the spot is defined
1115
+ (`estimate.compactBytes`).
1116
+
1117
+ `compactStorage: { sums: false }` keeps no strategy sums. Each node then plays the current
1118
+ profile, the regret-matched strategy the next iteration would play. It is cheaper again but
1119
+ much more exploitable on deep trees. `blockScale: true` takes the per-hand byte away too.
1120
+
1121
+ Storage and peak memory on issue #20's target spots (AsKh7d and Ks9s4s, pot 55, stack 975,
1122
+ three bet sizes, a 75% raise, three aggressions), measured on four threads in Node:
1123
+
1124
+ | Storage | Bytes per slot | T | Monotone T |
1125
+ |---|---|---|---|
1126
+ | 32-bit | 8.0 | 17.2 GiB | 3.75 GiB |
1127
+ | 16-bit | 4.0 | 8.7 GiB | 1.90 GiB |
1128
+ | compact | 2.75 | 5.9 GiB (peak 6.4 GB), 35 s an iteration | 1.29 GiB (peak 1.7 GB) |
1129
+ | compact, `sums: false, blockScale: true` | 1.03 | 2.2 GiB (peak 2.7 GB), 24 s an iteration | 0.48 GiB (peak 0.8 GB) |
1130
+
1131
+ Accuracy at 320 iterations, against reference solves to 0.17% of pot (T₀: AsKh7d, three
1132
+ sizes, all-in as the only raise) and 0.22% (the same tree on Ks9s4s). Exploitability is
1133
+ true, in the full tree; EV error is per combination at the root, range-weighted, in % of pot;
1134
+ "same size" is the share of OOP's hands, among those whose best root bet size beats the
1135
+ next by 0.5% of pot in the reference, that still prefer it:
1136
+
1137
+ | Storage | T₀: exploitability, EV error, same size | Monotone T₀ |
1138
+ |---|---|---|
1139
+ | 32-bit | 0.69% (the reference run itself) | 0.71%, 1.19%, 100% |
1140
+ | compact | 0.81%, 0.23%, 100% | 0.83%, 1.09%, 100% |
1141
+ | compact, `sums: false, blockScale: true`, CFR+ | 4.76%, 0.17%, 78% | 4.08%, 1.28%, 62% |
1142
+
1143
+ It combines with `shareHistories` (one set of storage for betting lines that reach the same
1144
+ pot), and the pair is what brings T under 2 GiB: 0.99 GiB with sums, peaking at 1.5 GB on four
1145
+ threads, and 0.37 GiB with `sums: false, blockScale: true`. Sharing is lossy on its own; on
1146
+ T₀ at 160 iterations it was 9.5% of pot exploitable in 1.06 GiB at 32 bits, with root EVs
1147
+ 0.66% of pot off and 97% of clear bet-size choices kept; with compact storage added, 9.0%,
1148
+ 0.63% and 100%, in 0.36 GiB.
1149
+
1150
+ It runs on the JavaScript engine, like 16-bit storage, on Node worker threads but on one
1151
+ thread in the browser, unless the solve passes `wasmStorage` (see the WebAssembly engine),
1152
+ which runs it on the WebAssembly engine, threads included. It combines with `precision`
1153
+ (for the rounds before `from`), warm starts and coarse starts (read and written compactly,
1154
+ rounded to nearest), `runoutBuckets` and chance sampling; only `analysisOnly` is refused.
1155
+ In headless Chromium on one thread, on the JavaScript engine, monotone T₀ took 10.1 s an
1156
+ iteration compact, 8.1 s at 16 bits and 2.3 s at 32 bits on WebAssembly; T itself, at
1157
+ `sums: false, blockScale: true`, allocated its 2.2 GiB and ran at 95 s an iteration. Storage is split into buffers under 1 GiB, because Chromium refuses
1158
+ an ArrayBuffer of 2 GiB or more. `bench/storage/` has the measurements and the variants
1159
+ that were left out: 4- and 6-bit regrets, a log scale, sparse regrets, and dropping sums on
1160
+ the later streets only.
1161
+
1162
+ ### Runout buckets and coarse start
1163
+
1164
+ Both fold turn and river cards that play alike. `runoutBuckets` solves the folded game. `coarseStart`
1165
+ only starts from it and then solves the real game, so with `runoutBuckets` at its own gap or wider it
1166
+ has nothing left to fold and does nothing. On ranges with no rank symmetry, such as all of napkinpoker's
1167
+ weighted ranges, neither folds anything.
1168
+
1169
+ #### Runout buckets
1170
+
1171
+ `runoutBuckets: true` solves one turn or river card for several that play alike: two cards
1172
+ of one suit, neither pairing the board, equally connected to its straights, whose rank
1173
+ swap maps both ranges onto themselves. The stored card stands for the others with hands
1174
+ relabelled by the swap. A number instead of `true` is the widest rank gap allowed in a
1175
+ bucket (`true` is 1, the most cautious).
1176
+
1177
+ It is an approximation — 55 on a 6 river and 66 on a 5 river sit on opposite sides of the
1178
+ board card, and no relabelling fixes that — so `exploitabilityPercent()` (and
1179
+ `targetPercent`) measure the bucketed game, and `run.trueExploitabilityPercent()` measures
1180
+ the strategy in the real one, every card dealt. How much it saves and costs depends on
1181
+ the ranges; suited connectors keep ranks apart, pocket pairs near the merged ranks cost
1182
+ accuracy. Ranges weighted hand by hand rarely allow any swap: on all 70 of napkinpoker's
1183
+ realistic spots it folds nothing, at any gap (see
1184
+ [Every option on napkinpoker's reference solves](#every-option-on-napkinpokers-reference-solves)). On AhKdQc, 4 threads, to 0.3% of pot in the bucketed game:
1185
+
1186
+ | Ranges | Gap | Runouts | Time | True exploitability |
1187
+ |---|---|---|---|---|
1188
+ | Bench (wide, connectors) | exact | 2,352 | 13.2 s | 0.271% |
1189
+ | | 1 | 1,672 | 10.5 s | 0.278% |
1190
+ | | 3 | 1,348 | 8.0 s | 0.302% |
1191
+ | Pairs and broadway | exact | 2,352 | 9.3 s | 0.228% |
1192
+ | | 1 | 1,396 | 4.9 s | 0.482% |
1193
+ | | 3 | 1,088 | 4.2 s | 0.542% |
1194
+
1195
+ #### Coarse start
1196
+
1197
+ `approximations: { coarseStart: { iterations: 40 } }` first solves a coarse copy of the
1198
+ spot, with runouts bucketed as by `runoutBuckets: 3`, for that many iterations. It then
1199
+ starts the real spot from those regrets. Coarse iterations are cheaper, and the real solve
1200
+ picks up roughly where they left off. The answer is still the real spot's, and
1201
+ exploitability measures the real game. Off by default.
1202
+
1203
+ Measured in Chromium on one thread, stopped at 15 s, 40 coarse iterations, with root-EV
1204
+ error per combination (range-weighted mean, % of pot) against a 0.1% reference:
1205
+
1206
+ | Flop | Cold | Coarse start | Exploitability, cold → coarse start |
1207
+ |---|---|---|---|
1208
+ | AsKh7d, compare ranges, 50% bet | 1.51% | 0.19% | 0.94% → 0.40% |
1209
+ | AsKh7d, bench ranges, 66% bet | 0.26% | 0.06% | 0.24% → 0.15% |
1210
+ | Ks9s4s, monotone | 0.04% | 0.11% | 0.10% → 0.07% |
1211
+
1212
+ The monotone flop reaches 0.5% error in half the time, but a cold solve has already settled
1213
+ it by 15 s. To an exploitability target in Node, coarse start was faster on all three.
1214
+ `bench/coarse-to-fine/` has the harness.
1215
+
1216
+ ### Every option on napkinpoker's reference solves
1217
+
1218
+ `bench/reference/` scores any solution against 70 full-hand solves by postflop-solver
1219
+ (every flop texture, realistic weighted ranges; see its `napkinpoker/README.md`). The fixtures are
1220
+ private and not in this repository (issue #119): `bench/reference/napkinpoker.ts` reads them from
1221
+ `NAPKIN_REFERENCE` or a napkinpoker checkout beside this one. Only aggregate scores are published here. At each
1222
+ stored flop node, and the first turn decision after each stored turn card, it values our
1223
+ strategy at the stored per-action EVs. Those are exact action against action. The EV our
1224
+ play gives up against each hand's best stored action is the regret we leave in that game.
1225
+ It is reach-weighted by the stored range, in % of the node's pot. A flop node is scored
1226
+ when the opponent reaches it at least 3% of the time. A turn node is scored when both
1227
+ players play its flop line at least 3% of the time. The stored strategy's own loss at the same
1228
+ nodes is the floor these numbers can resolve: about 0.03% of pot on the flop and turn,
1229
+ 0.06% at the root.
1230
+
1231
+ **The exact solver against postflop-solver.** Seven spots, solved exactly to 0.3% of pot
1232
+ on four threads at 32 bits. Our regrets on the actions either solver plays differ from
1233
+ the stored ones by 0.014–0.050% of pot on average, and by 0.16% at the worst
1234
+ well-reached node. Our root play loses what the stored strategy does at its own values.
1235
+ Larger differences are confined to actions neither solver plays, chiefly shoves, whose
1236
+ values neither solve trains closely:
1237
+
1238
+ | Spot | Board | Pot | Iterations, time | Played-action regret error, flop / turn (worst node) |
1239
+ |---|---|---|---|---|
1240
+ | f03 | 7c 6s Jc | 3-bet | 140, 61 s | 0.014 / 0.020% (0.064) |
1241
+ | f15 | As Kc 3d | 3-bet | 140, 92 s | 0.041 / 0.021% (0.153) |
1242
+ | f23 | 2d 3h 2c | 3-bet | 160, 79 s | 0.019 / 0.021% (0.062) |
1243
+ | f79 | 4s 7c 4c | 3-bet | 130, 59 s | 0.017 / 0.023% (0.096) |
1244
+ | f85 | 5s Js 6s | single-raised | 390, 249 s | 0.018 / 0.019% (0.055) |
1245
+ | f05 | 5s Ts Ac | single-raised | 410, 555 s | 0.021 / 0.050% (0.158) |
1246
+ | f01 | 7h 5c 7s | single-raised | 440, 698 s | 0.024 / 0.017% (0.059) |
1247
+
1248
+ **Each option.** Measured on three 3-bet pots (f03 two-tone, f15 rainbow, f79 paired), on
1249
+ four threads, at the iterations the exact solve took to 0.3% of pot. That makes each row
1250
+ the option's cost at equal iterations. Losses are in % of the node's pot, means over the
1251
+ spots. Root is OOP at the flop root / IP after a check.
1252
+
1253
+ | Option | Storage | Time | Root loss | Flop nodes | Turn nodes | True exploitability |
1254
+ |---|---|---|---|---|---|---|
1255
+ | exact | 1.00× | 1.00× | 0.059 / 0.054 | 0.030 | 0.031 | 0.27% |
1256
+ | `wasmStorage`, i16 | 0.52× | 1.16× | 0.059 / 0.067 | 0.033 | 0.035 | 0.37% |
1257
+ | `compactStorage` (with `wasmStorage`) | 0.37× | 1.37× | 0.063 / 0.080 | 0.045 | 0.039 | 0.63% |
1258
+ | `shareHistories` | 0.40× | 1.00× | 0.061 / 0.068 | 0.034 | 0.041 | 1.89% |
1259
+ | `shareHistories` + `compactStorage` | 0.15× | 1.40× | 0.067 / 0.083 | 0.041 | 0.047 | 2.08% |
1260
+ | `thinSizes` (15 of 61 nodes cut) | 0.74× | 0.66× | 0.067 / 0.294 | 0.084 | 0.048 | 0.22% in its own tree |
1261
+ | `thinSizes` + `shareHistories` | 0.35× | 0.72× | 0.071 / 0.288 | 0.084 | 0.049 | 2.07% in its own tree |
1262
+ | `chanceSampling` | 1.00× | 0.21× | 0.171 / 0.172 | 0.130 | 0.397 | 8.64% |
1263
+ | the same, 2× the iterations | 1.00× | 0.38× | 0.086 / 0.086 | 0.052 | 0.093 | 2.26% |
1264
+ | the same, 4× the iterations | 1.00× | 0.69× | 0.057 / 0.056 | 0.030 | 0.033 | 0.60% |
1265
+ | `shareHistories` + `chanceSampling` | 0.40× | 0.21× | 0.128 / 0.122 | 0.090 | 0.274 | 8.30% |
1266
+ | blueprint + `resolveSubgame` | 0.59× | 0.68× with the re-solves | 0.062 / 0.073 | 0.057 | 0.107; re-solved 0.053 | — |
1267
+ | `runoutBuckets: 3`, `coarseStart`, and their pairs | as without them | | | | | |
1268
+ | **`solveLite`'s blueprint (`litePreset`)**, to its `settle` stop (2.6× the iterations) | 0.22× | 0.30× | 0.052 / 0.068 | 0.052 | 0.127 | 1.89% |
1269
+ | **`largeTree`**, 4× the iterations | 0.38× | 0.58× | 0.057 / 0.289 | 0.082 | 0.048 | 0.39% in its own tree |
1270
+
1271
+ - **Storage options cost almost nothing at the root.** i16 stays within the noise. Compact
1272
+ storage and sharing add a few hundredths of a percent of pot. Sharing's exploitability
1273
+ plateau (1.9%) lies mostly in lines the stored nodes do not reach.
1274
+ - **`thinSizes`' cost is IP's bet after a check.** Away from the root it keeps one size. On
1275
+ these spots IP's 33% bet after a check is its main play, so the IP root loses 0.29%
1276
+ of pot. Its flop and turn means cover only the nodes its tree still holds. The 15 lines
1277
+ it cut are left out, so those means understate its cost.
1278
+ - **`chanceSampling` wins on time.** On four threads its iterations cost a fifth of exact
1279
+ ones. At equal iterations it is far from settled, but at four times the iterations, in
1280
+ 0.69× the exact solve's time, its root, flop and turn play match the exact solve's, though
1281
+ it is 0.60% of pot exploitable against 0.27%.
1282
+ - **`resolveSubgame`:** the blueprint here keeps the flop's betting and gives the turn and
1283
+ river one 75% bet, with no raise or shove there. Re-solving each stored turn with the
1284
+ full betting (200 iterations) halves the blueprint's turn loss, to 0.053% of pot
1285
+ against 0.031% exact.
1286
+ - **`runoutBuckets` folds nothing on any of the 70 spots, at any gap.** Their weighted
1287
+ ranges give no rank swap that maps both ranges onto themselves. So it, and
1288
+ `coarseStart`, which buckets the same way, leave these solves exactly as they were.
1289
+ - **The presets** (issue #115) cost what their parts do. Lite settles in 0.30× the exact solve's time
1290
+ in 0.22× its storage, with root play as close to the stored play as the exact solve's. Its turn
1291
+ nodes lose 0.127% of pot, because its turn keeps the 75% bet but drops the raise and the all-in the
1292
+ stored solves play, and it plateaus at sharing's 1.9% exploitability. `largeTree` costs `thinSizes`' IP root loss and
1293
+ nothing more, in 0.38× the storage and 0.58× the time.
1294
+
1295
+ `bench/reference/results/` has every number, per spot and per node. `test/combinations.test.ts` solves
1296
+ every pair of the eight opt-ins and the two presets on a small spot. Every pair runs, repeatable
1297
+ on two threads and matching one thread and the JavaScript engine. `test/presets-score.test.ts` scores both presets on f03 against the
1298
+ stored EVs, so a regression in any option they use fails `npm test` wherever the fixtures are
1299
+ checked out; elsewhere it skips.
1300
+
458
1301
  ## Verification
459
1302
 
460
1303
  - **A known answer.** The clairvoyance game — nuts and air against pure bluffcatchers on a
@@ -473,18 +1316,30 @@ enumerated and can be canonicalised for a 12× win.
473
1316
  runout count — invisible on a river board, where that factor is 1.
474
1317
  - Zero-sum to 1e-9, exploitability non-negative and non-increasing, and every strategy a
475
1318
  probability distribution.
1319
+ - **Against an independent solver.** On seven of napkinpoker's postflop-solver references,
1320
+ every texture, exact solves agree with the stored regrets to 0.01–0.05% of pot on the
1321
+ actions either plays (see [Every option on napkinpoker's reference solves](#every-option-on-napkinpokers-reference-solves)).
1322
+ - **Options in pairs.** Every pair of the eight opt-ins and the two presets is solved, repeated, compared across
1323
+ thread counts and engines, and checked to change nothing when one of them is off.
476
1324
 
477
1325
  ```bash
1326
+ npm run lint # conventions: kebab-case file names, tab indents, no focused tests
1327
+ npm run check # types, with unused locals, parameters and imports refused
478
1328
  npm test
479
1329
  ```
480
1330
 
481
1331
  ## Releasing
482
1332
 
483
1333
  `.github/workflows/publish.yml` publishes to npm from `main`. Every push to `main` is
484
- type-checked, tested and built; if the `version` in `package.json` is not on npm yet, it
1334
+ linted, type-checked, tested and built; if the `version` in `package.json` is not on npm yet, it
485
1335
  is published, with provenance. So a release is: bump `version`, merge to `main`. A push
486
1336
  that leaves the version alone publishes nothing.
487
1337
 
1338
+ A prerelease version (`0.5.0-beta.0`) is published under its own dist-tag, the word after the
1339
+ `-` (`beta`), so `npm install poker-flopsolve` keeps getting the latest stable release and the
1340
+ beta is installed by name: `npm install poker-flopsolve@beta`. A plain version is published as
1341
+ `latest`.
1342
+
488
1343
  It publishes by npm trusted publishing: npm trusts this repository's `publish.yml`
489
1344
  (set up under the package's settings on npmjs.com), the job proves who it is with GitHub's
490
1345
  OpenID Connect token, and no npm token is stored anywhere.