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/dist/index.d.ts CHANGED
@@ -151,8 +151,8 @@ interface Runouts {
151
151
  /**
152
152
  * The symmetries each stored board still has, as a prefix into
153
153
  * `stabiliserMap`: map ids, identity first. A board with more than the
154
- * identity holds hands that mirror each other on it, whose strategies the
155
- * solver keeps tied together.
154
+ * identity holds hands that mirror each other on it, which the solver
155
+ * stores once per orbit.
156
156
  */
157
157
  readonly stabiliserStart: readonly Int32Array[];
158
158
  readonly stabiliserMap: readonly Int32Array[];
@@ -168,6 +168,8 @@ interface Runouts {
168
168
  /** The board as given. */
169
169
  readonly initial: readonly number[];
170
170
  }
171
+ /** The card map swapping two ranks in every suit. */
172
+ declare function rankSwap(a: number, b: number): Uint8Array;
171
173
  /** A real board, as the solver stores it. */
172
174
  interface ResolvedBoard {
173
175
  readonly round: number;
@@ -341,6 +343,9 @@ interface HandSpace {
341
343
  readonly same: Int32Array;
342
344
  }
343
345
 
346
+ /** Whether this platform runs the WebAssembly SIMD kernels; false means JavaScript throughout. */
347
+ declare function simdAvailable(): boolean;
348
+
344
349
  /**
345
350
  * Vector CFR+ over a fixed board.
346
351
  *
@@ -377,9 +382,13 @@ interface Layout {
377
382
  * Where each decision node's storage starts. Its block on a board is
378
383
  * `actions` rows of the owner's hands live there, in hand-list order —
379
384
  * entry `i` of their active list — so a row is as long as that list and
380
- * blocked hands take no room. See `blockBase`.
385
+ * blocked hands take no room. See `blockBase`. Int32 while every slot
386
+ * fits one, which keeps the traversal's indexing on integers; Float64,
387
+ * exact to 2^53, for a tree past 2^31 slots, where Int32 would wrap.
388
+ * With compact storage, a node of a compact round's offset is into its
389
+ * chunk of the compact arrays instead.
381
390
  */
382
- readonly offset: Int32Array;
391
+ readonly offset: Int32Array | Float64Array;
383
392
  /** For each list slot `(roundBase[r] + board) * 2 + p`: rows before this board's. */
384
393
  readonly rowStart: Int32Array;
385
394
  /** First list index of each round, as `ActiveLists.roundBase`. */
@@ -393,8 +402,66 @@ interface Layout {
393
402
  readonly blockOffset: Int32Array;
394
403
  readonly blocks: number;
395
404
  readonly totalSlots: number;
405
+ /** Slots one iteration walks: `totalSlots`, and with shared storage what it would be unshared. */
406
+ readonly walkedSlots: number;
396
407
  readonly maxActions: number;
397
408
  readonly bytes: number;
409
+ /**
410
+ * Whether some nodes share another's storage (`SpotConfig.shareHistories`):
411
+ * a block may then be visited more than once an iteration.
412
+ */
413
+ readonly shared: boolean;
414
+ /**
415
+ * Per node, 1 where regret updates are weighted by the actor's own reach:
416
+ * nodes whose storage more than one history shares, under
417
+ * `shareHistories`. Null otherwise.
418
+ */
419
+ readonly reachWeighted: Uint8Array | null;
420
+ /**
421
+ * The first round stored compactly (see `CompactStorage`); the round
422
+ * count when none is, so `round >= compactFrom` says whether a node is.
423
+ */
424
+ readonly compactFrom: number;
425
+ /** Slots of compactly stored regrets; 0 without compact storage. */
426
+ readonly compactSlots: number;
427
+ /** Per node of a compact round: where its hands' scales start in its chunk, else -1. */
428
+ readonly handOffset: Float64Array | null;
429
+ readonly compactHands: number;
430
+ /**
431
+ * Compact storage comes in chunks, each its own buffer, because browsers
432
+ * refuse an ArrayBuffer of 2 GiB or more. A node's storage is all in one
433
+ * chunk: per node of a compact round, which (else -1); its `offset` and
434
+ * `handOffset` count from that chunk's start.
435
+ */
436
+ readonly compactChunk: Int32Array | null;
437
+ /** Per chunk: its slots, its hands, and the slots of every chunk before it. */
438
+ readonly chunkSlots: readonly number[];
439
+ readonly chunkHands: readonly number[];
440
+ readonly chunkStart: readonly number[];
441
+ }
442
+ /**
443
+ * Compact storage, for `SpotConfig.compactStorage`: from round `from` on,
444
+ * regrets and (with `sums`) strategy sums as 8-bit integers; without sums,
445
+ * each hand's strategy there is read as the current profile.
446
+ */
447
+ interface CompactPlan {
448
+ /** First round stored compactly, counted from the spot's first. */
449
+ readonly from: number;
450
+ /** Largest magnitude stored: 127 for 8 bits. */
451
+ readonly steps: number;
452
+ /** One power-of-two scale per hand per block, else one float64 per block. */
453
+ readonly perHand: boolean;
454
+ /** Round at random, unbiased, rather than to nearest. */
455
+ readonly stochastic: boolean;
456
+ /** Keep the regrets as float32: only the sums are dropped. */
457
+ readonly float: boolean;
458
+ /** Largest buffer to allocate; compact storage is split in chunks no bigger. */
459
+ readonly chunkBytes: number;
460
+ /**
461
+ * Keep 8-bit strategy sums too, with their own per-hand scale, so these
462
+ * nodes keep the average strategy. Per-hand scale only.
463
+ */
464
+ readonly sums: boolean;
398
465
  }
399
466
  /** Accumulated regrets: float, or 16-bit integers scaled per block. */
400
467
  type RegretStore = Float64Array | Float32Array | Int16Array;
@@ -418,6 +485,27 @@ interface Context {
418
485
  */
419
486
  readonly regretScale: Float64Array | null;
420
487
  readonly sumScale: Float64Array | null;
488
+ /**
489
+ * Compact storage (`Approximations.compactStorage`), else unset: nodes of
490
+ * rounds from `compact.from` on keep only `compactRegret`, one array per
491
+ * chunk (`layout.compactChunk`) laid out by `layout.offset` as other
492
+ * nodes' regrets are, and each hand's scale in
493
+ * `handShift` — a stored integer `q` means `q * 2^(shift - SHIFT_BIAS)`,
494
+ * and a shift of 0 means the hand's regrets are all zero. With a block
495
+ * scale instead, `compactScale` holds it as `regretScale` does for 16-bit
496
+ * storage.
497
+ */
498
+ readonly compact?: CompactPlan | null;
499
+ readonly compactRegret?: readonly (Int8Array | Float32Array)[] | null;
500
+ readonly handShift?: readonly Uint8Array[] | null;
501
+ /**
502
+ * With `compact.sums`: 8-bit strategy sums, laid out as `compactRegret`,
503
+ * and their per-hand scales, as `handShift` is for regrets.
504
+ */
505
+ readonly compactSum?: readonly Uint8Array[] | null;
506
+ readonly sumShift?: readonly Uint8Array[] | null;
507
+ /** Compact storage's per-block scales, when it keeps one per block rather than per hand. */
508
+ readonly compactScale?: Float64Array | null;
421
509
  readonly scratch: TerminalScratch;
422
510
  readonly chipScale: number;
423
511
  /** Which combinations each player can hold on each board. */
@@ -461,6 +549,73 @@ interface Context {
461
549
  expandOrbits: boolean;
462
550
  /** Use the WebAssembly SIMD kernels where the platform has them. */
463
551
  readonly simd: boolean;
552
+ /**
553
+ * Chance sampling with baselines, for `Approximations.chanceSampling`;
554
+ * unset or null for the exact traversal.
555
+ */
556
+ sampling?: Sampling | null;
557
+ /**
558
+ * With shared storage (`Layout.shared`), per block the iteration DCFR
559
+ * last discounted it in. A shared block is visited once per history that
560
+ * reaches it, and only the first visit of an iteration discounts. Unset or
561
+ * null for unshared storage, where every block is visited once.
562
+ */
563
+ discounted?: Int32Array | null;
564
+ }
565
+ /** How chance sampling picks deals; see `Approximations.chanceSampling`. */
566
+ interface SamplingOptions {
567
+ /**
568
+ * Probability of walking each deal on a training iteration, chosen at
569
+ * random per deal and iteration. Default 0.35. Ignored with `every`.
570
+ */
571
+ readonly p?: number;
572
+ /**
573
+ * Walk every deal exactly once every this many iterations, in rotation,
574
+ * instead of at random. Measured, it converges worse than random at the
575
+ * same rate; kept for comparison.
576
+ */
577
+ readonly every?: number;
578
+ /**
579
+ * Betting rounds whose deals are sampled, counted from the spot's first:
580
+ * from a flop, 1 is the turn and 2 the river. Default every round after
581
+ * the first.
582
+ */
583
+ readonly rounds?: readonly number[];
584
+ /**
585
+ * How a walked deal's fresh value meets its baseline: 'unbiased' adds
586
+ * `(v - b) / p` to the baseline, the VR-MCCFR estimator; 'latest' uses
587
+ * `v` itself, the freshest value without the correction.
588
+ */
589
+ readonly estimator?: 'unbiased' | 'latest';
590
+ /** Apply the DCFR discounts a skipped subtree missed when it is next walked. Default true. */
591
+ readonly catchUp?: boolean;
592
+ }
593
+ /** Where sampling keeps what, for a spot; see `makeSampling`. */
594
+ interface SamplingPlan {
595
+ readonly rounds: Uint8Array;
596
+ readonly p: number;
597
+ readonly every: number;
598
+ readonly unbiased: boolean;
599
+ readonly catchUp: boolean;
600
+ /** Per chance node into a sampled round: where its baselines start, else -1. */
601
+ readonly baseOffset: Int32Array;
602
+ /** Per list slot of a sampled round: offset of that board and player's baseline within a node's. */
603
+ readonly boardOffset: Int32Array;
604
+ /** Per chance node: where its last-walk entries start, two per child board. */
605
+ readonly walkOffset: Int32Array;
606
+ /** Baseline values, last-walk entries and blocks the state holds. */
607
+ readonly values: number;
608
+ readonly walks: number;
609
+ readonly blocks: number;
610
+ }
611
+ /** Sampling state: baselines, when each was last walked, when each block was last updated. */
612
+ interface Sampling extends SamplingPlan {
613
+ readonly baseline: Float32Array;
614
+ readonly lastWalk: Int32Array;
615
+ /** Per block: the iteration it was last updated in, for DCFR catch-up. */
616
+ readonly lastUpdate: Int32Array;
617
+ /** Memory the state takes. */
618
+ readonly bytes: number;
464
619
  }
465
620
  /**
466
621
  * Which combinations each player can hold on each board.
@@ -481,15 +636,6 @@ interface ActiveLists {
481
636
  readonly slot: Uint16Array;
482
637
  /** First list index of each round. */
483
638
  readonly roundBase: Int32Array;
484
- /**
485
- * Hands that mirror each other on a board with symmetry left, whose
486
- * accumulators are kept equal, indexed by the same slot as `start`:
487
- * `ties[tieStart[slot]..tieStart[slot + 1]]` is a run of classes, each its
488
- * size then that many positions in the board's hand list. Empty almost
489
- * everywhere.
490
- */
491
- readonly tieStart: Int32Array;
492
- readonly ties: Int32Array;
493
639
  /** Each entry's two cards, beside `list`. */
494
640
  readonly cardA: Uint8Array;
495
641
  readonly cardB: Uint8Array;
@@ -498,13 +644,45 @@ interface ActiveLists {
498
644
  * lists are sorted by it. Zero elsewhere.
499
645
  */
500
646
  readonly strength: Int32Array;
647
+ /**
648
+ * On a board with symmetry left, a list holds one hand per mirror orbit —
649
+ * the lowest combination, see `orbitLeader` — standing for the whole
650
+ * orbit. Mirrored hands play alike, since the board and both ranges look
651
+ * the same after swapping suits, so one hand's strategy, reach and value
652
+ * are all of theirs; storing them once is exact, and shortens every vector
653
+ * there. Whether a list holds any orbit of more than one hand, beside
654
+ * `start`: only those need the weighted deal and terminal kernels.
655
+ */
656
+ readonly packed: Uint8Array;
657
+ /** How many hands each entry stands for, beside `list`: 1 unpacked. */
658
+ readonly multiplicity: Float64Array;
659
+ /**
660
+ * The hands each entry stands for, itself first: `memberCombo` and their
661
+ * cards from `memberStart[e]` to `memberStart[e + 1]`.
662
+ */
663
+ readonly memberStart: Int32Array;
664
+ readonly memberCombo: Uint16Array;
665
+ readonly memberA: Uint8Array;
666
+ readonly memberB: Uint8Array;
501
667
  }
668
+ /**
669
+ * What a traversal plays and does. Train plays the current (regret-matched)
670
+ * profile and updates the traverser's regrets and sums; Current plays that
671
+ * same profile and updates nothing, for reading its values; Average plays the
672
+ * average profile; BestResponse has the traverser best-respond to it.
673
+ */
502
674
  declare const Mode: {
503
675
  readonly Train: 0;
504
676
  readonly BestResponse: 1;
505
677
  readonly Average: 2;
678
+ readonly Current: 3;
506
679
  };
507
680
  type Mode = (typeof Mode)[keyof typeof Mode];
681
+ /** See `Solver.rootValues`. */
682
+ interface RootValues {
683
+ readonly totals: readonly [number, number];
684
+ readonly values: readonly [Float64Array, Float64Array];
685
+ }
508
686
  /** A whole-tree traversal, returning the root value vector. */
509
687
  type RootTraversal = (mode: Mode, traverser: 0 | 1, iterWeight: number) => Float64Array;
510
688
  /** A prepared solver. */
@@ -528,6 +706,20 @@ interface Solver {
528
706
  readonly rootCount: number;
529
707
  iterate(count: number, from: number): void;
530
708
  expectedValue(): [number, number];
709
+ /**
710
+ * One root pass per player under the average profile (`Mode.Average`) or
711
+ * the current one (`Mode.Current`): each player's chips per hand, as
712
+ * `expectedValue` gives them for the average, and a copy of their root
713
+ * counterfactual values, one per hand of their root active list.
714
+ */
715
+ rootValues(mode: typeof Mode.Average | typeof Mode.Current): RootValues;
716
+ /**
717
+ * Root EV in chips for each combination, indexed like `COMBO_CARDS`, from
718
+ * root counterfactual values `rootValues` returned for `player`: each
719
+ * hand's value over the opponent mass it can be dealt against. Zero for a
720
+ * combination off the root list or with no opponent hand to face.
721
+ */
722
+ handEvs(player: 0 | 1, values: Float64Array): Float64Array;
531
723
  exploitability(): number;
532
724
  averageStrategyAt(node: number, board: number): {
533
725
  actions: number;
@@ -538,6 +730,11 @@ interface Solver {
538
730
  * reach vectors the caller supplies. Returns a fresh copy.
539
731
  */
540
732
  valuesAt(node: number, board: number, traverser: 0 | 1, reachMe: Float64Array, reachOpp: Float64Array, live: Uint16Array, liveCount: number): Float64Array;
733
+ /**
734
+ * The whole-tree traversal `iterate` and the other passes run now: this
735
+ * thread's own, or what `useRoot` routed them to. For wrapping it.
736
+ */
737
+ readonly root: RootTraversal;
541
738
  /**
542
739
  * Counterfactual values under the average strategy from any node against
543
740
  * each of `hands` alone, at the reach given for it: the same as `valuesAt`
@@ -547,6 +744,50 @@ interface Solver {
547
744
  pairValuesAt(node: number, board: number, traverser: 0 | 1, hands: Uint16Array, handReach: Float64Array, live: Uint16Array, liveCount: number): Float64Array;
548
745
  }
549
746
 
747
+ /**
748
+ * Node platform.
749
+ *
750
+ * Purpose: the one place the solver touches Node-only APIs. A browser build
751
+ * swaps this module for `browser.ts`, which has the same exports; see
752
+ * `scripts/browser-platform.ts`.
753
+ */
754
+
755
+ /** Which build this is. */
756
+ declare const PLATFORM = "node";
757
+
758
+ /**
759
+ * The WebAssembly traversal engine, set up.
760
+ *
761
+ * Purpose: lay a prepared spot out in one WebAssembly memory for
762
+ * `assembly/engine.ts`, and give the solver its storage and a root traversal.
763
+ *
764
+ * The engine keeps the accumulators in its own memory as 32-bit floats; the
765
+ * solver's `regret` and `strategySum` are views onto them, so everything that
766
+ * reads storage from JavaScript — strategy queries, warm starts, `valuesAt` —
767
+ * sees the very same numbers. It runs where WebAssembly SIMD is available,
768
+ * on one thread or several; otherwise the JavaScript traversal in cfr.ts
769
+ * runs. A second build, which only `poker-flopsolve/wasm-storage` carries,
770
+ * keeps 16-bit and compact storage the same way (`EngineInput.storage`).
771
+ *
772
+ * WebAssembly memory is one buffer, but Chromium lets it reach wasm32's full
773
+ * 4 GiB, plain or shared, made at that size or grown to it, where it refuses
774
+ * any ArrayBuffer over 2 GiB less 2 MiB (measured in Chromium 153 by
775
+ * bin/memory-ceiling.ts; issue #84). So compact storage needs no chunks of
776
+ * its own in the engine: its chunks are regions of the one memory, laid out
777
+ * as the JavaScript engine's buffers are.
778
+ */
779
+
780
+ /**
781
+ * The engine with 16-bit and compact storage (issue #84), as base64 for plain
782
+ * and shared memory. Only `poker-flopsolve/wasm-storage` holds the bytes, so
783
+ * a build that never imports it carries none of them; a solve opts in by
784
+ * passing it as `SolveOptions.wasmStorage`.
785
+ */
786
+ interface WasmStorage {
787
+ readonly plain: string;
788
+ readonly shared: string;
789
+ }
790
+
550
791
  /**
551
792
  * Warm starts.
552
793
  *
@@ -569,6 +810,10 @@ interface Solver {
569
810
  * their real cards, so two spots may store different runouts (one folding
570
811
  * mirrored deals, the other not); hands match by combination, so a range may
571
812
  * have grown or shrunk.
813
+ *
814
+ * A solve of another board can seed this one through a card relabelling — a
815
+ * permutation of the deck taking one board onto the other, a rank swap for a
816
+ * nearby flop — through which its runouts and hands are read.
572
817
  */
573
818
 
574
819
  /** What a warm start carried over. */
@@ -586,6 +831,79 @@ interface WarmStartReport {
586
831
  readonly averages: boolean;
587
832
  }
588
833
 
834
+ /**
835
+ * A stopping rule for solves that never reach an exploitability target: stop
836
+ * once the root play stops moving (issue #100).
837
+ *
838
+ * Purpose: a blueprint with `shareHistories` plateaus several percent of the
839
+ * pot from equilibrium, so `targetPercent` cannot end it, yet its first
840
+ * decisions go on settling and are what a caller reads (issue #85). This
841
+ * reads them cheaply: the average strategy at two nodes, with no
842
+ * best-response pass, so a check costs a tiny fraction of an iteration.
843
+ *
844
+ * The root play is the decision opening the spot (out of position) and, after
845
+ * a check there, in position's: neither player has acted before them, so each
846
+ * decision is played by the whole range and is weighted by it. Its movement
847
+ * between two strategies is, per decision, the total variation of each hand's
848
+ * action mix (half the summed absolute change), averaged over the range by
849
+ * weight; the larger of the two decisions counts. 0.01 means the range's
850
+ * play moved by 1% of its mass. #85 called the root play still once both
851
+ * decisions moved under 1% between checks 20 iterations apart.
852
+ */
853
+
854
+ /** See `SolveOptions.settle`. */
855
+ interface SettleOptions {
856
+ /** Iterations between checks. Default 20. */
857
+ readonly every?: number;
858
+ /**
859
+ * Movement between consecutive checks, as a share of the range, under
860
+ * which the root play counts as still: see `rootPlayMovement`. Default
861
+ * 0.01.
862
+ */
863
+ readonly tolerance?: number;
864
+ /** Consecutive still checks before stopping. Default 2. */
865
+ readonly patience?: number;
866
+ /** Iterations before which no check counts toward `patience`. Default 0. */
867
+ readonly minIterations?: number;
868
+ }
869
+ /** The strategies `rootPlayMovement` compares; see `rootPlay`. */
870
+ interface RootPlay {
871
+ /** The root, then in position's decision after a check there, when there is one. */
872
+ readonly views: readonly StrategyView[];
873
+ /** Range weight per combination of each view's player, indexed like `COMBO_CARDS`. */
874
+ readonly weights: readonly Float64Array[];
875
+ }
876
+ /** The decisions that make up the root play of a solved spot. */
877
+ declare function rootPlayNodes(solution: Solution): number[];
878
+ /**
879
+ * The root play of a solution as it stands: the average strategy at the
880
+ * root and at in position's decision after a check. Cheap: two strategy
881
+ * reads, no best-response pass.
882
+ */
883
+ declare function rootPlay(solution: Solution): RootPlay;
884
+ /**
885
+ * How far the root play moved from `before` to `after`, two readings of the
886
+ * same spot: per decision, the range-weighted mean of each hand's total
887
+ * variation, and the larger over the decisions. 0 is unmoved, 1 is every
888
+ * hand switching to actions it never took.
889
+ */
890
+ declare function rootPlayMovement(before: RootPlay, after: RootPlay): number;
891
+ /**
892
+ * A running settle check for a caller that steps a run itself. Feed it a
893
+ * snapshot after each `every` iterations; it says when the root play has
894
+ * stayed still for `patience` checks in a row.
895
+ */
896
+ interface SettleTracker {
897
+ /** Record a snapshot taken after `iterations` in all; true once settled. */
898
+ check(solution: Solution, iterations: number): boolean;
899
+ /** Movement at the last check, or NaN before the second. */
900
+ readonly movement: number;
901
+ /** Whether the last check settled it. */
902
+ readonly settled: boolean;
903
+ }
904
+ /** Start a settle check; see `SettleTracker`. */
905
+ declare function trackSettle(options?: SettleOptions): SettleTracker;
906
+
589
907
  /**
590
908
  * Five-to-seven card hand evaluation.
591
909
  *
@@ -683,19 +1001,449 @@ declare function activeCombos(weights: Float64Array): number[];
683
1001
  /** Total weight, i.e. combinations counted with their weight. */
684
1002
  declare function rangeWeight(weights: Float64Array): number;
685
1003
 
686
- /** Whether this platform runs the WebAssembly SIMD kernels; false means JavaScript throughout. */
687
- declare function simdAvailable(): boolean;
1004
+ /**
1005
+ * Nested subgame re-solving (issue #47).
1006
+ *
1007
+ * Purpose: refine one player's strategy below a node of a solved spot — a
1008
+ * blueprint whose later streets were simplified to fit — by solving that
1009
+ * subgame again with a richer tree. Opt-in: nothing else in the solver calls
1010
+ * this.
1011
+ *
1012
+ * `Solution.subgameAt` already builds the subgame; this solves it with the
1013
+ * ranges the blueprint brings to the node held fixed (unsafe re-solving), and
1014
+ * can measure what each opponent hand gets against the result next to what it
1015
+ * had against the blueprint.
1016
+ *
1017
+ * Nested: a re-solved subgame is a `Solution` like any other, so a node below
1018
+ * it can be re-solved from it in turn.
1019
+ *
1020
+ * Measured (issue #47; Ks 9s 4s, a flop blueprint with three flop sizes and
1021
+ * one turn/river size, its turns re-solved at three sizes with raises,
1022
+ * against a full-tree reference): an opponent's best response under the
1023
+ * reference's ranges gained, weighted by how often each turn is reached,
1024
+ * about 3.5–4% of the subgame's pot against plain re-solving, and more
1025
+ * against every safe gadget tried (4.2–6.2%: Burch, Johanson & Bowling's
1026
+ * re-solve gadget and Moravčík et al.'s and Brown & Sandholm's maxmargin
1027
+ * ones). Most of what is left is the refined player's own range at the node,
1028
+ * which comes from the blueprint and which no gadget changes, so the gadgets
1029
+ * were removed before 0.5.0 (issue #125). To make re-solves from a shared
1030
+ * blueprint trustworthy, keep the busiest lines unshared
1031
+ * (`ShareHistories.keepLines` with `linesWithin`).
1032
+ */
688
1033
 
1034
+ /** Settings for {@link resolveSubgame}. */
1035
+ interface ResolveOptions {
1036
+ /** The player whose strategy is refined. */
1037
+ readonly player: 0 | 1;
1038
+ /** The subgame's betting; unset, the blueprint's carries over. */
1039
+ readonly betting?: SubgameBetting;
1040
+ /** Iterations to run. Default 200. */
1041
+ readonly iterations?: number;
1042
+ /**
1043
+ * Also report `alternative` and `entered`, at the cost of a best-response
1044
+ * pass over the blueprint below the node and one over the subgame.
1045
+ */
1046
+ readonly measure?: boolean;
1047
+ /** Solver settings for the subgame; `iterations` and warm starts are this function's. */
1048
+ readonly solve?: Pick<SolveOptions, 'workers' | 'precision' | 'algorithm' | 'engine' | 'simd' | 'wasmStorage'>;
1049
+ }
1050
+ /** A re-solved subgame. */
1051
+ interface ResolvedSubgame {
1052
+ /**
1053
+ * The subgame's solution. Its ranges are the ones the blueprint brings to
1054
+ * the node; read the refined player's strategy from it.
1055
+ */
1056
+ readonly solution: Solution;
1057
+ readonly player: 0 | 1;
1058
+ /**
1059
+ * Each opponent hand's best-response value at the node against the
1060
+ * blueprint, in chips, indexed like `COMBO_CARDS`; NaN off its range.
1061
+ * Null unless `measure`.
1062
+ */
1063
+ readonly alternative: Float64Array | null;
1064
+ /**
1065
+ * Each opponent hand's best-response value in the re-solved subgame
1066
+ * against the refined strategy, in chips; NaN off its range. Where it
1067
+ * exceeds `alternative` the re-solve gave that hand more than the
1068
+ * blueprint did. Null unless `measure`.
1069
+ */
1070
+ readonly entered: Float64Array | null;
1071
+ readonly iterations: number;
1072
+ }
689
1073
  /**
690
- * Node platform.
1074
+ * Re-solve the subgame at a node of `blueprint` for one player.
691
1075
  *
692
- * Purpose: the one place the solver touches Node-only APIs. A browser build
693
- * swaps this module for `browser.ts`, which has the same exports; see
694
- * `scripts/browser-platform.ts`.
1076
+ * @param blueprint a solved spot
1077
+ * @param node a decision opening a betting round (see `Solution.subgameAt`)
1078
+ * @param board the board index at that node's round
695
1079
  */
1080
+ declare function resolveSubgame(blueprint: Solution, node: number, board: number, options: ResolveOptions): ResolvedSubgame;
696
1081
 
697
- /** Which build this is. */
698
- declare const PLATFORM = "node";
1082
+ /**
1083
+ * Hybrid history sharing (issue #101): share later-street storage between
1084
+ * histories except along the lines most often played.
1085
+ *
1086
+ * Purpose: a solve with `shareHistories` keeps its flop play, but the ranges
1087
+ * it brings to a turn are trained against river values that several
1088
+ * histories share, so a turn re-solved from it starts from distorted ranges.
1089
+ * `ShareHistories.keepLines` gives named lines storage of their own, and
1090
+ * `turnLineReach` ranks the flop lines by how often they are reached, and
1091
+ * `linesWithin` picks the most-reached ones a storage budget allows.
1092
+ */
1093
+
1094
+ /** A flop line opening the turn, and its share of the root's hand pairs. */
1095
+ interface LineReach {
1096
+ /** The turn's first decision, as `Solution.path` names it, e.g. `"check check /"`. */
1097
+ readonly line: string;
1098
+ /** The turn's first decision node. */
1099
+ readonly node: number;
1100
+ /** Weighted hand pairs reaching the turn by this line over those at the root, 0 to 1. */
1101
+ readonly share: number;
1102
+ }
1103
+ /**
1104
+ * Every line from the spot's first round into the next, most reached first.
1105
+ * Reach comes from the average strategy, so take it from a solve that has
1106
+ * run a while; the order settles long before the strategy does.
1107
+ */
1108
+ declare function turnLineReach(solution: Solution): LineReach[];
1109
+ /**
1110
+ * The most-reached lines of `solution` (`turnLineReach`) that
1111
+ * `ShareHistories.keepLines` can keep in `options.config` with its storage
1112
+ * at `options.precision` (compact storage included) at most `maxBytes`: the
1113
+ * longest prefix of the ranking that fits, with any lines the config already
1114
+ * keeps. Throws if the spot is over budget keeping only those. Keeping a line never shrinks storage, so the
1115
+ * prefix is found by bisection.
1116
+ *
1117
+ * The spot the lines are for, `options.config`, defaults to the one
1118
+ * `solution` solved. The ranking can come from a cheaper spot with the same first
1119
+ * round: the reach of a flop line is the flop play alone, so a solve with
1120
+ * the river checked down ranks the lines much as the real one does, in a
1121
+ * fraction of its memory (see `ShareHistories.keepLines`).
1122
+ */
1123
+ declare function linesWithin(solution: Solution, maxBytes: number, options?: LinesWithinOptions): string[];
1124
+ /** Settings for {@link linesWithin}. */
1125
+ interface LinesWithinOptions {
1126
+ /** The spot the lines are kept in; unset, the one the ranking solution solved. */
1127
+ readonly config?: SpotConfig;
1128
+ /** The precision the spot will be solved at, which the budget is for; default 'f32'. */
1129
+ readonly precision?: Precision;
1130
+ }
1131
+
1132
+ /**
1133
+ * What a preset changed (issue #115).
1134
+ *
1135
+ * Purpose: `solveLite` and `largeTree` take any caller betting and turn it
1136
+ * into a cheaper game. Nothing they do may be silent, so each hands back a
1137
+ * `PresetChanges`: the bet, raise and shove sizes its tree no longer offers,
1138
+ * found by walking the caller's betting tree beside the preset's, the rounds
1139
+ * that lost any, and every other setting it set or dropped, each with a
1140
+ * sentence a page can show as it is.
1141
+ */
1142
+
1143
+ /** A betting round by name. */
1144
+ type Street = 'flop' | 'turn' | 'river';
1145
+ /** Sizes one player's decisions of one kind lost on one round. */
1146
+ interface SizesCut {
1147
+ readonly street: Street;
1148
+ readonly player: 'oop' | 'ip';
1149
+ /** 'bet' opens the round's betting; 'raise' answers a bet. */
1150
+ readonly facing: 'bet' | 'raise';
1151
+ /**
1152
+ * The sizes cut, ascending: each a fraction of the pot after a call, to
1153
+ * two places, as `betSizes` and `raiseSizes` give them, or 'allin'.
1154
+ * Where the caller's sizes resolve to different chips at different pots,
1155
+ * one caller size can show as neighbouring fractions.
1156
+ */
1157
+ readonly sizes: readonly (number | 'allin')[];
1158
+ /** The caller's decisions of this kind that lost at least one size. */
1159
+ readonly decisions: number;
1160
+ /**
1161
+ * The caller's decisions of this kind, offering any size, that the
1162
+ * preset's tree still reaches: those below a cut action are gone with
1163
+ * it and counted in neither number.
1164
+ */
1165
+ readonly of: number;
1166
+ }
1167
+ /** A setting a preset set, changed or dropped. */
1168
+ interface SettingChange {
1169
+ /** The setting's name: a `SpotConfig` field, or a `SolveOptions` one (`approximations.chanceSampling`, `precision`, ...). */
1170
+ readonly setting: string;
1171
+ /** The caller's value; undefined where it was unset. */
1172
+ readonly from: unknown;
1173
+ /** The preset's value; undefined where it dropped it. */
1174
+ readonly to: unknown;
1175
+ }
1176
+ /** Everything a preset changed against the caller's spot. */
1177
+ interface PresetChanges {
1178
+ /** Sizes the preset's tree no longer offers, by street, player and kind. */
1179
+ readonly sizesCut: readonly SizesCut[];
1180
+ /** Streets whose betting lost any size: the rounds simplified. */
1181
+ readonly roundsSimplified: readonly Street[];
1182
+ /** Every other setting set, changed or dropped, the approximations included. */
1183
+ readonly settings: readonly SettingChange[];
1184
+ /** One sentence per change, sizes first, in plain words. */
1185
+ readonly notes: readonly string[];
1186
+ }
1187
+
1188
+ /**
1189
+ * Lite mode (issue #100): one opt-in that turns the caller's betting into the
1190
+ * phone/laptop blueprint issue #85 measured, solves it until its root play
1191
+ * settles, and re-solves later streets at the caller's full betting on demand.
1192
+ *
1193
+ * Purpose: the recipe needs a dozen settings — the flop betting kept, one
1194
+ * size on the turn and river, `shareHistories`, `runoutBuckets`,
1195
+ * `chanceSampling`, a stop on the root play rather than on exploitability —
1196
+ * and callers should not have to assemble it. Nothing else in the package
1197
+ * calls this; unused, it changes nothing.
1198
+ *
1199
+ * What is measured, and what each default costs, is in `solveLite`'s notes.
1200
+ */
1201
+
1202
+ /** How `liteConfig` simplifies the caller's betting. */
1203
+ interface LiteOptions {
1204
+ /**
1205
+ * The turn and river keep one bet size: the caller's pot-fraction size
1206
+ * nearest this. Default 0.75.
1207
+ */
1208
+ readonly laterSize?: number;
1209
+ /**
1210
+ * Keep one raise on the turn and river, of the caller's raise size
1211
+ * nearest `laterSize`. Default false: a bet and no raise, as issue #85
1212
+ * measured. A raise nearly doubles the tree: on issue #47's rainbow
1213
+ * betting 707 MiB unshared became 1375 (173 shared became 261), an
1214
+ * iteration cost 1.74 times as much and Node peaked at 546 MiB.
1215
+ */
1216
+ readonly laterRaise?: boolean;
1217
+ /**
1218
+ * Cap the flop's aggressions, the opening bet the first. Default: the
1219
+ * caller's. A speed trim, off by default: see `solveLite`'s notes for
1220
+ * what it saved and cost.
1221
+ */
1222
+ readonly flopMaxRaises?: number;
1223
+ /**
1224
+ * Forbid donk bets on the turn and river (`SpotConfig.noDonk`). Default:
1225
+ * the caller's setting. A speed trim, off by default: see `solveLite`'s
1226
+ * notes for what it saved and cost.
1227
+ */
1228
+ readonly noDonk?: boolean;
1229
+ /** `SpotConfig.runoutBuckets` for the blueprint. Default 3. */
1230
+ readonly runoutBuckets?: number;
1231
+ /**
1232
+ * `SpotConfig.shareHistories` for the blueprint. Default true, the river.
1233
+ *
1234
+ * For better turn re-solves, keep the most-reached flop lines unshared
1235
+ * within a memory budget: `SolveLiteOptions.keepBudget` (issue #113),
1236
+ * which picks them with `linesWithin` for you. Lines given here in
1237
+ * `keepLines` are kept besides.
1238
+ */
1239
+ readonly shareHistories?: boolean | ShareHistories;
1240
+ }
1241
+ /** Settings for {@link solveLite}. */
1242
+ interface SolveLiteOptions extends LiteOptions, Pick<SolveOptions, 'workers' | 'precision' | 'wasmStorage' | 'algorithm' | 'onProgress' | 'targetPercent'> {
1243
+ /** Iteration cap. Default 2000; the solve normally settles well before. */
1244
+ readonly iterations?: number;
1245
+ /** The stop on the root play (`SolveOptions.settle`); false to run to `iterations`. Default {}, its own defaults. */
1246
+ readonly settle?: SettleOptions | false;
1247
+ /**
1248
+ * `Approximations.chanceSampling` for the blueprint, or false for none.
1249
+ * Default {}: sampled at p 0.35, on `workers` threads.
1250
+ */
1251
+ readonly sampling?: SamplingOptions | false;
1252
+ /**
1253
+ * Keep the most-reached first-round lines' later streets unshared
1254
+ * (`ShareHistories.keepLines`, issue #101), as many as this many bytes
1255
+ * of storage at `precision` (default 'f32') allow; `keepWithin` picks
1256
+ * them, and the blueprint with them kept is solved from cold. It is for
1257
+ * turn re-solves: on issue #47's flops it cut their gain by a third to a
1258
+ * half at the settle point, more when run longer, root play unchanged.
1259
+ * 150 MiB with `precision: 'i16'` and `wasmStorage` kept 3–19 lines and
1260
+ * peaked at 317–534 MiB in Chromium, re-solve included. Throws if the
1261
+ * shared blueprint alone is over the budget, or if it shares nothing.
1262
+ * Unset, off. Measures are in `solveLite`'s notes.
1263
+ */
1264
+ readonly keepBudget?: number;
1265
+ /** Iterations of the picking solve under `keepBudget`. Default 80, as issue #101 measured. */
1266
+ readonly pickIterations?: number;
1267
+ }
1268
+ /** Settings for `LiteSolution.resolve`. */
1269
+ interface LiteResolveOptions extends Omit<ResolveOptions, 'betting'> {
1270
+ /** Overrides on the caller's own betting for the subgame. */
1271
+ readonly betting?: SubgameBetting;
1272
+ }
1273
+ /** What {@link litePreset} returns: the blueprint spot and the solve's settings, and what they changed. */
1274
+ interface LitePreset {
1275
+ /** The blueprint spot (`liteConfig`'s). */
1276
+ readonly config: SpotConfig;
1277
+ /** The blueprint solve's settings: `iterations`, `settle`, sampling and the solve options given. */
1278
+ readonly options: SolveOptions;
1279
+ /** Everything the preset changed against the caller's spot. */
1280
+ readonly changes: PresetChanges;
1281
+ }
1282
+ /** What {@link solveLite} returns. */
1283
+ interface LiteSolution {
1284
+ /** The blueprint's solution. */
1285
+ readonly solution: Solution;
1286
+ /** The blueprint spot that was solved (`liteConfig`'s, with `keepBudget` its kept lines). */
1287
+ readonly blueprint: SpotConfig;
1288
+ /** The lines kept unshared (`ShareHistories.keepLines`); empty without `keepBudget` or kept lines of the caller's. */
1289
+ readonly kept: readonly string[];
1290
+ /** The caller's spot, full betting. */
1291
+ readonly source: SpotConfig;
1292
+ /**
1293
+ * What the blueprint changed against `source`: the sizes cut on each
1294
+ * street (the flop's own only with `flopMaxRaises`), the streets
1295
+ * simplified, and the sharing, buckets, sampling and stop rule switched
1296
+ * on. `resolve` puts the cut sizes back below the node it re-solves.
1297
+ */
1298
+ readonly changes: PresetChanges;
1299
+ /**
1300
+ * Re-solve the subgame at a node opening the turn or river, at the
1301
+ * caller's full betting for the streets from there, the caller's cuts
1302
+ * below the node included: `resolveSubgame` with 200 iterations
1303
+ * unless `options` say otherwise, with the blueprint's `workers`,
1304
+ * `precision` and `wasmStorage`.
1305
+ */
1306
+ resolve(node: number, board: number, options: LiteResolveOptions): ResolvedSubgame;
1307
+ }
1308
+ /**
1309
+ * The blueprint of `config`: its first round's betting as given, every later
1310
+ * round one bet size (the given size nearest `laterSize`) and, with
1311
+ * `laterRaise`, one raise; no shove offered after the first round; and
1312
+ * `shareHistories` and `runoutBuckets: 3`. Ranges, pot, stacks and everything
1313
+ * else carry over. Per-player betting is simplified side by side.
1314
+ *
1315
+ * Bet and raise cuts (`removeActions`) on the first round carry over, but
1316
+ * for those past `flopMaxRaises`; those below a deal are dropped, as the
1317
+ * later rounds' sizes no longer exist (`LiteSolution.resolve` puts them
1318
+ * back). The caller's own `shareHistories` stands unless `options` give one.
1319
+ */
1320
+ declare function liteConfig(config: SpotConfig, options?: LiteOptions): SpotConfig;
1321
+ /**
1322
+ * Solve `config`'s lite blueprint (`liteConfig`) until its root play settles,
1323
+ * and hand back a re-solver for later streets at the full betting.
1324
+ *
1325
+ * Defaults: `shareHistories` on the river, `runoutBuckets: 3`,
1326
+ * `chanceSampling` at p 0.35, and `settle` with its defaults (every 20
1327
+ * iterations, under 1% of the range moved, twice running).
1328
+ *
1329
+ * Measured (issue #100) on issue #47's betting (0.33 / 0.75 / 1.5 pot, a
1330
+ * 0.75 raise, all-in, three aggressions; pot 55, stack 975, the bench
1331
+ * ranges), so the blueprint plays 0.75 and no raise on the turn and river.
1332
+ * Headless Chromium, `poker-flopsolve/threads`; the clock counts solving
1333
+ * and the settle checks. Root play loss is the EV OOP's root mix and IP's
1334
+ * mix after a check lose at the unshared blueprint's per-action values
1335
+ * (solved to 0.05% of pot), % of pot, with that blueprint's own loss as the
1336
+ * floor; it measures what sharing, sampling and stopping early cost, not
1337
+ * distance to the full game. Re-solve gain is the opponent's best response
1338
+ * against a turn re-solved at the full betting (300 iterations),
1339
+ * under the unshared blueprint's ranges, % of the subgame's pot, weighted
1340
+ * over 3 lines × 3 turns by how often each is reached:
1341
+ *
1342
+ * | flop | settled | Chromium, 1 / 2 / 4 threads | peak RSS | root play loss (floor) | per-hand EV error | re-solve gain (unshared) | re-solve, 1 / 2 / 4 threads |
1343
+ * |---|---|---|---|---|---|---|---|
1344
+ * | As Kh 7d | 400 it | 103 / 59 / 35 s | 511 MiB | 0.023 / 0.014 (0.009 / 0.008) | 0.75 / 0.85 | 3.1 / 2.7 (0.67 / 0.50) | 38 / 22 / 14 s |
1345
+ * | Ts 9s 4h | 320 it | 64 / 38 / 21 s | 426 MiB | 0.118 / 0.076 (0.116 / 0.052) | 0.54 / 0.60 | 4.0 / 3.3 (0.48 / 0.55) | 42 / 23 / 13 s |
1346
+ * | Ks 9s 4s | 360 it | 31 / 19 / 12 s | 253 MiB | 0.059 / 0.037 (0.047 / 0.025) | 1.5 / 1.9 | 3.6 / 3.6 (0.44 / 0.47) | 28 / 17 / 10 s |
1347
+ *
1348
+ * Sampling runs on the threads (issue #99): the same iterations settle the
1349
+ * root on every count, within 0.002% of pot. Unsampled, the rainbow
1350
+ * blueprint took 473 ms an iteration on 4 threads in Node against 251
1351
+ * sampled on one, and settled later. Peak memory counts the page, the
1352
+ * blueprint and a re-solve; it is the most a phone must give. The rainbow root play's loss is
1353
+ * 0.014% of pot over its floor for OOP; `settle: { every: 40, tolerance:
1354
+ * 0.02, patience: 3 }` brings it to 0.009 in 120 s instead of 104 (Node).
1355
+ *
1356
+ * Against exact solves of the full game, which separate what the turn and
1357
+ * river simplification costs:
1358
+ * - issue #51's T₀ on As Kh 7d (0.33 / 0.75 / 1.5 on every street, all-in
1359
+ * raises, two aggressions, solved to 0.22% of pot): OOP's root play lost
1360
+ * 0.072% of pot at T₀'s per-action values, the simplified blueprint
1361
+ * unshared and solved to 0.04% lost 0.057; per-hand root EVs were 3.9 /
1362
+ * 2.9% of pot off, unshared 4.1 / 3.1. Simplifying is the cost; sharing,
1363
+ * sampling and the stop add 0.015. T₀ stores no strategy, so there is no
1364
+ * floor from its own play.
1365
+ * - napkinpoker's postflop-solver solves (issue #87; two flop sizes, 75% on
1366
+ * the turn and river with 3× raises and all-in, weighted BU/CO/SB ranges,
1367
+ * SRP and 3-bet pots, 0.3% of pot), 8 spots across textures, one thread in
1368
+ * Node: root play lost 0.034 / 0.135% of pot on average at the stored
1369
+ * per-action values, where the stored solve's own play lost 0.027 /
1370
+ * 0.131; settled in 38-176 s. Wide single-raised ranges took up to
1371
+ * 452 MiB of storage, near a browser's default `maxBytes` of 512: give it
1372
+ * room, or `compactStorage` with `wasmStorage` (on rainbow, 300 MiB peak
1373
+ * in Node against 411, 27% slower). `minWeight: 0.05` there cut 2-5% of
1374
+ * storage and up to 15% of the time, root play unchanged; it edits the
1375
+ * ranges, so it is the caller's to set.
1376
+ *
1377
+ * `laterRaise`'s cost is on it; the trims `flopMaxRaises` and `noDonk`, and
1378
+ * what was rejected, are in docs/APPROXIMATIONS.md.
1379
+ *
1380
+ * `keepBudget` (issue #113) recovers part of the re-solve gain above. With
1381
+ * `keepBudget: 150 * 2 ** 20, precision: 'i16', wasmStorage` (the recipe
1382
+ * issue #101 measured), the same measures, the pick included in the time:
1383
+ *
1384
+ * | flop | kept, storage | settled | Chromium, 1 / 2 / 4 threads | peak RSS, 1 / 2 / 4 | root play loss | per-hand EV error | re-solve gain |
1385
+ * |---|---|---|---|---|---|---|---|
1386
+ * | As Kh 7d | 3 lines, 150 MiB | 440 it | 123 / 61 / 35 s | 489 / 509 / 534 MiB | 0.026 / 0.011 | 0.58 / 0.70 | 2.54 / 1.72 |
1387
+ * | Ts 9s 4h | 6 lines, 141 MiB | 320 it | 69 / 37 / 22 s | 437 / 463 / 469 MiB | 0.115 / 0.063 | 0.33 / 0.27 | 1.93 / 1.28 |
1388
+ * | Ks 9s 4s | all 19, 97 MiB | 360 it | 32 / 19 / 11 s | 290 / 301 / 317 MiB | 0.056 / 0.036 | 0.82 / 1.02 | 2.61 / 1.91 |
1389
+ *
1390
+ * Root play is as without it; the re-solve gain falls by a third to a half,
1391
+ * but stays well over the unshared blueprint's 0.4–0.7. What holds the rest
1392
+ * is the stop, not the sharing: monotone keeps every line, and at 16 bits
1393
+ * or 32 alike it re-solves at 2.6 / 1.9 when its root play settles, 1.25 /
1394
+ * 0.68 unsampled (220 iterations, 37 s on 4 threads in Node), and 0.99 /
1395
+ * 0.64 run sampled to 800 iterations (20 s). At 800 iterations (`settle:
1396
+ * false, iterations: 800`) As Kh 7d re-solves at 1.33 / 1.14 in 59 s on 4
1397
+ * threads in Chromium, peaking at 533 MiB, and Ts 9s 4h at 1.10 / 0.92 in
1398
+ * 47 s (Node); plain sharing run as long gives 2.23 / 2.41 on As Kh 7d. A
1399
+ * re-solve times as without it.
1400
+ *
1401
+ * Its memory: the picking solve's WebAssembly memory is freed only once the
1402
+ * caller yields to the event loop, so it stays resident beside the
1403
+ * blueprint's. The pick samples the turn but not the checked-down river,
1404
+ * whose baselines would be most of it (182 MiB resident on As Kh 7d sampled
1405
+ * on both, 56 on the turn alone, the same lines kept on all three flops);
1406
+ * sampling both, rainbow peaked at 661 MiB on 4 threads.
1407
+ */
1408
+ declare function solveLite(config: SpotConfig, options?: SolveLiteOptions): LiteSolution;
1409
+ /**
1410
+ * What {@link solveLite} solves, without solving it: `liteConfig`'s
1411
+ * blueprint, the solve's settings (`iterations` 2000, `settle` at its
1412
+ * defaults, `chanceSampling` at p 0.35, and the solve options given), and a
1413
+ * report of everything changed against `config`. With `keepBudget` it
1414
+ * does solve: the short picking solve `keepWithin` ranks lines on, whose
1415
+ * kept lines are in the blueprint and the report. For a page that steps its
1416
+ * own run: `createRun(defineSpot(preset.config), preset.options)`, with
1417
+ * `trackSettle` for the stop, and `resolveSubgame` with `bettingFrom(config,
1418
+ * round)` for the re-solves `LiteSolution.resolve` would make.
1419
+ */
1420
+ declare function litePreset(config: SpotConfig, options?: SolveLiteOptions): LitePreset;
1421
+ /**
1422
+ * `blueprint` keeping the lines `options.keepBudget` allows, picked with
1423
+ * `linesWithin` from `options.pickIterations` of `checkedDown(blueprint)`;
1424
+ * `blueprint` itself without a budget. What `solveLite` solves; exported so
1425
+ * a caller stepping its own run can do the same. The picking solve uses
1426
+ * `options`' `workers`, `precision`, `wasmStorage`, `algorithm` and
1427
+ * `sampling`, the last on every round but the checked-down one.
1428
+ */
1429
+ declare function keepWithin(blueprint: SpotConfig, options?: SolveLiteOptions): SpotConfig;
1430
+ /**
1431
+ * `config` with its last round checked down: no bet or all-in there, and
1432
+ * cuts naming that round's actions dropped. Its first rounds are the same
1433
+ * game tree, so how often each line reaches the next round
1434
+ * (`turnLineReach`) comes out much as the real spot's, at a fraction of its
1435
+ * storage: what `solveLite`'s `keepBudget` ranks lines on (issue #101: on
1436
+ * As Kh 7d the lite blueprint so cut stores 57 MiB, against 173, and ranked
1437
+ * the same top 3). `shareHistories.keepLines` is dropped, as it may name
1438
+ * nodes the cut removes.
1439
+ */
1440
+ declare function checkedDown(config: SpotConfig): SpotConfig;
1441
+ /**
1442
+ * `config`'s tree-shaping betting for a subgame opening round `round`: each
1443
+ * setting given per round loses the rounds before it, as
1444
+ * `Solution.subgameAt` does with the spot's own.
1445
+ */
1446
+ declare function bettingFrom(config: SpotConfig, round: number): SubgameBetting;
699
1447
 
700
1448
  /**
701
1449
  * Postflop Texas Hold'em solver.
@@ -765,6 +1513,42 @@ interface SpotConfig {
765
1513
  * with 0.1, sizes 0.33 and 0.4 become one 0.365. Default 0, none.
766
1514
  */
767
1515
  readonly mergeSizes?: number;
1516
+ /**
1517
+ * Bets, raises and shoves to cut from the tree, with everything below
1518
+ * them: each the readable path of the node the action leads to, exactly as
1519
+ * `Solution.path` writes it — `"check bet 18.15"`, `"bet 41.25 raise
1520
+ * 133.31"`, `"check check / bet 18.15"`, chips being the actor's total
1521
+ * investment after the action and `/` a deal. Only the line named goes; the
1522
+ * same size elsewhere stays. Checks, calls and folds cannot be cut, and a
1523
+ * path that names no such action in the tree is refused.
1524
+ *
1525
+ * For a budgeted tree: keep three sizes where they earn their memory, one
1526
+ * where they do not. A tree's memory is almost all on the river, and each
1527
+ * flop or turn action multiplies the river subtrees below it, so cutting a
1528
+ * line saves what its whole subtree stores. Default none; unset, the tree
1529
+ * is the one the other settings build, unchanged.
1530
+ */
1531
+ readonly removeActions?: readonly string[];
1532
+ /**
1533
+ * Thin the bet sizes to a shape that keeps most of what the full ones are
1534
+ * worth in a fraction of the memory. Every size stays at the root, where
1535
+ * out of position opens the first round. Everywhere else a decision keeps
1536
+ * one bet, raise or shove: the one nearest three quarters of the pot, a
1537
+ * shove where that would be one. Opening the last round after an earlier
1538
+ * round saw a bet, sizes above the pot and the shove stay as well.
1539
+ *
1540
+ * The shape is what growing sizes one at a time by their value per byte
1541
+ * picked on As Kh 7d and Ks 9s 4s (issue #51). Measured on As Kh 7d, pot
1542
+ * 55, stack 975, sizes 0.33 / 0.75 / 1.5 with shove-only raises and two
1543
+ * aggressions: see the #51 entry in docs/APPROXIMATIONS.md for its memory and error.
1544
+ * It is a fixed rule, so it costs nothing to apply. A subgame from
1545
+ * `Solution.subgameAt` gets the full sizes back unless its betting sets
1546
+ * this again, and then it is thinned as a tree of its own: bets on the
1547
+ * streets before it do not count, so a river after a bet on the flop
1548
+ * keeps only the 0.75 size, where the whole tree also kept its big sizes
1549
+ * and shove. Default false; unset, the tree is unchanged.
1550
+ */
1551
+ readonly thinSizes?: boolean;
768
1552
  /** Refuse a range wider than this many combinations. */
769
1553
  readonly maxCombos?: number;
770
1554
  /**
@@ -803,6 +1587,248 @@ interface SpotConfig {
803
1587
  * strategy in the real game, every card dealt. Default false.
804
1588
  */
805
1589
  readonly runoutBuckets?: boolean | number;
1590
+ /**
1591
+ * Share river storage between betting histories that reach the same pot,
1592
+ * a lossy approximation for fitting a spot in memory (issue #49). Off by
1593
+ * default.
1594
+ *
1595
+ * Every earlier line gets its own copy of the streets below it, yet with
1596
+ * pot-fraction sizes many lines meet: check, bet, call and bet, call
1597
+ * reach the same pot, and so does every raise line taken in either order.
1598
+ * Their subtrees are identical, so their nodes keep one set of regrets and
1599
+ * strategy sums. Each history is still walked with its own reach, so an
1600
+ * iteration costs exactly what it did; only storage shrinks. On the
1601
+ * three-size target spot (AsKh7d, pot 55, stack 975, sizes 33/75/150%, a
1602
+ * 75% raise and all-in, three aggressions) 173 river starts collapse to 23
1603
+ * and storage falls 5.9 times: 17.2 GiB to 2.9 at 32 bits, 8.7 to 1.5 at 16.
1604
+ * There, at 16 bits, a Node solve peaked at 1.6 GiB on one thread and 2.0
1605
+ * on four (30 s an iteration), and was 12% of pot exploitable after 150
1606
+ * iterations.
1607
+ *
1608
+ * What is lost is recall: a player plays one strategy for every line that
1609
+ * met, though the ranges each line brings differ. Each history's regret is
1610
+ * weighted by how often the acting hand plays into it, which cut the cost
1611
+ * fourfold against plain CFR's sum. Measured on AsKh7d, pot 55, stack
1612
+ * 975, against the exact solve, 4 threads: with sizes 33/75/150%, an
1613
+ * all-in raise and two aggressions, 5.8 GiB became 1.22 GiB, and after
1614
+ * 400 iterations the strategy was 8.0% of pot exploitable, with
1615
+ * per-combination root EVs 0.72% of pot off on average and 2.5% at worst
1616
+ * (the exact solve: 0.28%). With one 50% size, 4.0% exploitable after
1617
+ * 300 iterations, EVs 0.67% off on average and 6.8% at worst.
1618
+ * Exploitability is measured in the full game, which the strategy covers
1619
+ * node by node, so it is exact. Do not expect it to approach
1620
+ * equilibrium: expect a strategy several percent of the pot from it, in
1621
+ * a spot that otherwise does not fit.
1622
+ *
1623
+ * Two consequences of one block serving several histories, both part of
1624
+ * the approximation: within an iteration, a history visited later plays
1625
+ * the regrets an earlier one has already updated, so the result depends a
1626
+ * little on the order of the tree; and under `algorithm: 'cfr+'` each
1627
+ * history's update is clamped at zero on its own, rather than their sum.
1628
+ * A spot with it can warm-start only from a solve that shares too.
1629
+ *
1630
+ * On issue #47's blueprint (issue #85; T's flop betting, one 0.75 bet on
1631
+ * the turn and river with no raise, `runoutBuckets: 3`) it saves 4.1 times
1632
+ * on rainbow, two-tone and monotone flops alike, because the flop's sizes
1633
+ * and raises still meet at a few turn pots: 196 river decisions keep 44
1634
+ * blocks. On AsKh7d 707 MiB becomes 173 at 32 bits, so the blueprint stays
1635
+ * on the WebAssembly engine; in Chromium on 4 threads the tab peaked at
1636
+ * 327 MiB, against 860 unshared. An iteration costs what an unshared one
1637
+ * does (458 ms there). Exploitability stops falling near 2.7% of pot by
1638
+ * 160 iterations and never reaches 0.3%; the root play goes on settling.
1639
+ * Judged at the unshared blueprint's own per-action values (solved to
1640
+ * 0.045%), after 300 iterations (138 s) its root play lost 0.011% of pot
1641
+ * where the unshared blueprint's lost 0.008%, but at 60 s it was 0.054%:
1642
+ * the unshared one needs 115 s to reach 0.3% itself. Per-hand root EVs
1643
+ * came out 0.4–0.6% of pot from the unshared ones (2–3% at worst), and
1644
+ * turns re-solved from it with T's betting gave the opponent 2.2–3.0% of
1645
+ * their pot under the unshared ranges, against 0.5–0.7% from the unshared
1646
+ * blueprint. `chanceSampling` composes: on one thread 238 ms an iteration,
1647
+ * the root settled in 109 s, 453 MiB; on 4 threads (issue #99) 70 ms, the
1648
+ * root settled in 33 s at the same iteration, 452 MiB. `coarseStart` composes
1649
+ * but finds no coarser copy at a gap of 3. `bench/blueprint-share/` has
1650
+ * the scripts and figures.
1651
+ *
1652
+ * Where a shared solve stops depends on its first few iterations (issue
1653
+ * #105). A shared block plays one strategy for every history meeting in
1654
+ * it, so the game has many stable points, and which one the solve settles
1655
+ * on is decided early, when regret matching plays nearly pure. Any
1656
+ * randomness then picks another: chance sampling, 8-bit stochastic
1657
+ * rounding, even float rounding under CFR+. On #103's turn spot
1658
+ * (exploitability 5.8% of pot), sampling at p 0.9 ended at 0.3–1.6%
1659
+ * over six different sets of draws. On a second turn spot (0.7%) it
1660
+ * changed nothing. On the blueprint above, neither sampling at p 0.9
1661
+ * (2.9%) nor 8-bit stochastic storage (2.5%) moved the plateau beyond
1662
+ * that spread, against 2.6% shared alone. Do not count on noise to
1663
+ * lower it. Of the deterministic changes tried (other regret
1664
+ * weighting, discount start, uniform play mixed into the first
1665
+ * iterations), none was a reliable gain. `bench/share-noise/` has the
1666
+ * measurements.
1667
+ *
1668
+ * `true` shares the river. See `ShareHistories` for the turn and for
1669
+ * lossier buckets.
1670
+ */
1671
+ readonly shareHistories?: boolean | ShareHistories;
1672
+ /**
1673
+ * Store regrets and strategy sums at 8 bits — an approximation, off by
1674
+ * default. See `CompactStorage`. Set here rather than on the solve because it
1675
+ * decides how much memory the spot needs, which `maxBytes` is checked
1676
+ * against when the spot is defined.
1677
+ */
1678
+ readonly compactStorage?: CompactStorage;
1679
+ }
1680
+ /**
1681
+ * Compact storage (issue #50): accumulators as 8-bit integers, each hand on
1682
+ * each board scaled by its own power of two, instead of 32- or 16-bit
1683
+ * values. Regret matching and the average strategy both divide a hand's
1684
+ * values by their own total, so a per-hand scale cancels wherever a strategy
1685
+ * is read and costs only a byte per hand. Rounding is at random, with odds
1686
+ * set by the remainder, so every stored value is right on average; the
1687
+ * randomness is a hash of the slot and iteration, so a solve is deterministic
1688
+ * at any thread count.
1689
+ *
1690
+ * Two modes:
1691
+ *
1692
+ * - With strategy sums (the default): regrets and sums at 8 bits, about 2.75
1693
+ * bytes a slot against 16-bit storage's 4 and 32-bit's 8. Measured, it
1694
+ * converges like the full solve: on the bench flop (AsKh7d, one size) 0.18%
1695
+ * of pot at 80 iterations against 0.18%, 0.058% at 160 against 0.052%; on
1696
+ * the monotone flop with three sizes (Ks9s4s, issue #20's T₀) 1.87% at 160
1697
+ * against 1.85%. Rounding the sums leaves a floor, near 0.03% of pot on the
1698
+ * bench flop and 0.1% on a small, narrow-range spot. On issue #20's T₀
1699
+ * (AsKh7d, three sizes, all-in raise, SPR 18), at 320 iterations it was
1700
+ * 0.81% of pot exploitable where 32-bit storage was 0.69%, per-hand root
1701
+ * EVs 0.23% of pot off a 0.17% reference, every hand's preferred bet size
1702
+ * kept, in 1.75 GiB where 32-bit storage took 5.1 and 16-bit 2.6. T itself
1703
+ * takes 5.9 GiB, 16-bit storage 8.7.
1704
+ * - `sums: false`: no strategy sums, so each node's strategy, wherever one is
1705
+ * read (`strategyAt`, `reachAt`, EVs, exploitability), is the current
1706
+ * profile, the regret-matched strategy the next iteration plays. About 1.4
1707
+ * bytes a slot, 1.03 with `blockScale`: T in 2.2 GiB. Per-hand root EVs stay as close as
1708
+ * the average's, as `currentProfileEv` found, but the strategy is far more
1709
+ * exploitable: 2 times at equal iterations on the bench flop, 5 to 8 times
1710
+ * on deeper or narrower spots (T₀ monotone: 4.0% of pot at 320 iterations
1711
+ * against 0.71%), and the bet size each hand prefers at the root agreed with
1712
+ * the reference for 62-82% of the hands where it was clear, against all of
1713
+ * them for the average. `algorithm: 'cfr+'`, whose current profile swings
1714
+ * less, is the better rule for the strategy; DCFR's current profile gives
1715
+ * the closer EVs (on T₀ monotone 0.55% of pot against the average's 1.19%,
1716
+ * but 4.9% exploitable).
1717
+ *
1718
+ * Rounding regrets to 8 bits costs training almost nothing: with 32-bit
1719
+ * regrets and no sums (`float`) the same runs were no better.
1720
+ *
1721
+ * Training is otherwise the exact solve's; exploitability is measured
1722
+ * exactly, in the full tree. Storage is split in chunks under `chunkBytes`,
1723
+ * because browsers refuse a buffer of 2 GiB. Runs on the JavaScript engine
1724
+ * and its Node worker threads, where an iteration costs about 1.5 times a
1725
+ * 32-bit one, or on the WebAssembly engine, threads included, with
1726
+ * `SolveOptions.wasmStorage` (issue #84). Not with `analysisOnly`, which
1727
+ * loads float32 sums. `precision` sets the rounds before `from`; a warm
1728
+ * start, a coarse start or `runoutBuckets`' measure of the real game reads
1729
+ * and writes compact storage, rounded to nearest; `chanceSampling` applies
1730
+ * its DCFR catch-up to compact nodes too.
1731
+ *
1732
+ * With `shareHistories`, a node sharing another's storage shares its compact
1733
+ * storage too; together they fit issue #20's target T in 0.99 GiB (0.37
1734
+ * without sums). Measured on T₀ at 160 iterations, compact storage did not
1735
+ * add to sharing's own loss: 9.0% of pot exploitable against 9.5%, root EVs
1736
+ * 0.63% of pot off against 0.66%, and all clear bet-size choices kept
1737
+ * against 97%, in a third of the memory.
1738
+ *
1739
+ * What was measured and left out is with the other approximations, in the
1740
+ * comment inside `Approximations`.
1741
+ */
1742
+ interface CompactStorage {
1743
+ /**
1744
+ * Keep 8-bit strategy sums, and with them the average strategy. Default
1745
+ * true; false stores only regrets and plays the current profile.
1746
+ */
1747
+ readonly sums?: boolean;
1748
+ /**
1749
+ * With `sums: false`, one scale per node and board instead of one per
1750
+ * hand: about 1.03 bytes a slot instead of 1.4. Under CFR+ it measured
1751
+ * nearly as accurate (0.077% of pot against 0.064% on the bench flop at
1752
+ * 320 iterations); under DCFR, whose large negative regrets then crowd
1753
+ * the scale, clearly less (0.16% against 0.08%).
1754
+ */
1755
+ readonly blockScale?: boolean;
1756
+ /**
1757
+ * First round stored compactly, from the spot's first (0); earlier rounds
1758
+ * keep 32-bit regrets and sums. Default 0. With `sums: false`, an earlier
1759
+ * round's average above the current profile measured worse than the
1760
+ * current profile throughout (0.053% of pot against 0.035% on the bench
1761
+ * flop): the two come from different iterations.
1762
+ */
1763
+ readonly from?: number;
1764
+ /**
1765
+ * Largest single buffer to allocate, in bytes; storage is split in chunks
1766
+ * no bigger, a node never split. Default 1 GiB: Chromium refuses an
1767
+ * ArrayBuffer of 2 GiB, but gives several smaller ones.
1768
+ */
1769
+ readonly chunkBytes?: number;
1770
+ /** For measurement: the largest regret magnitude stored, at most 127. */
1771
+ readonly steps?: number;
1772
+ /** For measurement: round regrets to nearest instead of at random. */
1773
+ readonly nearest?: boolean;
1774
+ /** For measurement, with `sums: false`: keep 32-bit regrets, dropping only the sums. */
1775
+ readonly float?: boolean;
1776
+ }
1777
+ /** See `SpotConfig.shareHistories`. */
1778
+ interface ShareHistories {
1779
+ /**
1780
+ * Lines whose later streets keep storage of their own, each named as
1781
+ * `Solution.path` names a node (a flop line opening the turn reads like
1782
+ * `"check check /"`). Every node at or below a listed one is left out of
1783
+ * sharing, and so is any round root above one. The rest share as
1784
+ * before. Unset or empty, nothing is kept. A warm start into a spot that
1785
+ * differs only here, keeping at least the lines its source keeps,
1786
+ * carries the average strategy too, as for the same spot.
1787
+ *
1788
+ * What it is for (issue #101): a turn re-solved from a shared blueprint
1789
+ * (`resolveSubgame`) inherits only the ranges the blueprint brings to
1790
+ * it, and sharing distorts those. Its flop play is stored unshared, but
1791
+ * it learns from river values that several histories share. Keeping the
1792
+ * few most-reached flop lines unshared gives the flop exact values
1793
+ * where most of the play is, and that straightens the ranges on the
1794
+ * lines left shared too. Pick them with `linesWithin` (the most-reached
1795
+ * lines, `turnLineReach`, that a storage budget allows) from a short
1796
+ * solve, 80 iterations, of a cheap copy of the spot (below); close that
1797
+ * and solve the hybrid spot from cold. Continuing from the picking solve
1798
+ * instead is worse: its average lingers.
1799
+ *
1800
+ * Measured on issue #47's blueprint (`1size-b3`), 400 iterations, against
1801
+ * the unshared blueprint solved to 0.045% of pot. "Re-solve gain" is the
1802
+ * opponent's best response to an unsafe turn re-solve at the full
1803
+ * three-size betting, under the unshared blueprint's ranges, in % of the
1804
+ * subgame pot, weighted by line reach, refining OOP / IP; the unshared
1805
+ * blueprint's own re-solves give 0.67 / 0.50. On AsKh7d:
1806
+ *
1807
+ * | kept | storage, f32 | re-solve gain | root EV error, mean |
1808
+ * |---|---|---|---|
1809
+ * | none (plain sharing) | 173 MiB | 3.05 / 2.15 | 0.57 / 0.46 |
1810
+ * | top 1 | 201 MiB | 2.48 / 1.58 | 0.46 / 0.53 |
1811
+ * | top 3 | 285 MiB | 1.10 / 0.83 | 0.24 / 0.21 |
1812
+ * | top 6 | 383 MiB | 1.16 / 0.65 | 0.23 / 0.27 |
1813
+ * | all (unshared) | 707 MiB | 0.67 / 0.50 | 0 |
1814
+ *
1815
+ * On Ts9s4h and Ks9s4s plain sharing gives 4.10 / 3.69 and 4.23 /
1816
+ * 2.72 against 0.48 / 0.55 and 0.44 / 0.47 unshared. Kept by a 300 MiB
1817
+ * budget (`linesWithin`), two-tone keeps 6 lines in 282 MiB for 0.61 /
1818
+ * 0.72, and monotone all 19 in 187 MiB. The top 3 alone are not enough
1819
+ * on two-tone (1.82 / 1.96), so budget the storage, not the count.
1820
+ *
1821
+ * In Chromium the picking solve's WebAssembly memory stays resident
1822
+ * until it is collected, so it adds to the peak. Rank on a cheap copy
1823
+ * instead: the blueprint with its river checked down (57 MiB on AsKh7d)
1824
+ * ranked the same top 3 there. Within 512 MiB on AsKh7d, store the
1825
+ * hybrid at 16 bits (`precision: 'i16'` with `wasmStorage`) with a 150
1826
+ * MiB budget at that precision. It keeps the same 3 lines, re-solves at
1827
+ * 1.47 / 0.92, and peaked at 392 MiB on 4 threads, 592 ms an iteration
1828
+ * against 495 shared, its root play settled in 127 s. Two-tone the same
1829
+ * way: 0.88 / 0.85. `bench/blueprint-share/` has the scripts and figures.
1830
+ */
1831
+ readonly keepLines?: readonly string[];
806
1832
  }
807
1833
  /** Projected cost of solving a spot. */
808
1834
  interface Estimate {
@@ -822,6 +1848,8 @@ interface Estimate {
822
1848
  * that does not fit at 32 bits is solved with.
823
1849
  */
824
1850
  readonly compressedBytes: number;
1851
+ /** Storage with `compactStorage`, which `maxBytes` is then checked against; else null. */
1852
+ readonly compactBytes: number | null;
825
1853
  readonly secondsPerThousandIterations: number;
826
1854
  /** Whether the spot fits `maxBytes` at 16 bits or better. */
827
1855
  readonly fits: boolean;
@@ -844,6 +1872,8 @@ interface Spot {
844
1872
  readonly stackUnits: number;
845
1873
  /** The configuration this was built from, so a worker can rebuild it. */
846
1874
  readonly source: SpotConfig;
1875
+ /** Each node's storage owner under `shareHistories`; unset without it. */
1876
+ readonly historyAlias?: Int32Array;
847
1877
  /**
848
1878
  * Find the stored board standing for a real one, and how hands relabel
849
1879
  * onto it. Board indices everywhere else — `strategyAt`, `reachAt`,
@@ -889,6 +1919,24 @@ interface SolveOptions {
889
1919
  * `nextCheck`. Setting this forces a fixed cadence instead.
890
1920
  */
891
1921
  readonly exploitEvery?: number;
1922
+ /**
1923
+ * Stop once the root play stops moving (issue #100): every `every`
1924
+ * iterations (default 20) read the average strategy at the root and at in
1925
+ * position's decision after a check, and stop once it has moved less than
1926
+ * `tolerance` (default 0.01: 1% of the range's mass, total variation
1927
+ * weighted by range) at `patience` checks in a row (default 2).
1928
+ * `stoppedAt` is then 'settled'. `rootPlayMovement` defines the measure.
1929
+ *
1930
+ * For solves that never reach an exploitability target, such as a
1931
+ * blueprint with `shareHistories`, which plateaus several percent of the
1932
+ * pot out while its first decisions go on settling (issue #85). A check
1933
+ * reads two nodes' strategies and no best-response pass, so it costs
1934
+ * almost nothing; with it, `Progress.exploitability` is NaN unless
1935
+ * `targetPercent` is set too, which then measures at every check and
1936
+ * stops on whichever comes first. `exploitEvery` is ignored. Measured
1937
+ * costs are in `solveLite`'s notes. Unset, off.
1938
+ */
1939
+ readonly settle?: SettleOptions;
892
1940
  readonly onProgress?: (info: Progress) => void;
893
1941
  /**
894
1942
  * Accumulator storage. Unset, 'f32' — what the WebAssembly engine runs —
@@ -916,7 +1964,9 @@ interface SolveOptions {
916
1964
  * exploitability, so never the largest error in the answer, but do not
917
1965
  * expect two worker counts to agree bit for bit.
918
1966
  *
919
- * The browser build is single-threaded: any count resolves to 1 there.
1967
+ * The browser build is single-threaded unless `enableThreads` from
1968
+ * `poker-flopsolve/threads` has started its workers; any count above what
1969
+ * is available resolves to what is, with one warning.
920
1970
  */
921
1971
  readonly workers?: number | 'auto';
922
1972
  /**
@@ -955,6 +2005,24 @@ interface SolveOptions {
955
2005
  * instead of 125.
956
2006
  */
957
2007
  readonly warmStart?: Solution | SolveRun;
2008
+ /**
2009
+ * For a `warmStart` from a solve of a different board: each card of this
2010
+ * spot's deck to the card of the old spot's it plays as, a permutation of
2011
+ * the 52 cards taking this board onto the old one. A rank swap (`6` and
2012
+ * `7` in every suit, say) carries a solve of AsKh6d onto AsKh7d with every
2013
+ * hand keeping its role: 66 there is 77 here (`rankSwap` builds that map).
2014
+ * Hands and runouts relabel through it; whatever the old ranges lacked
2015
+ * starts cold. Unset, a warm start must come from the same board. The
2016
+ * average strategy never carries over through it, even for a relabelling
2017
+ * that leaves the game unchanged: only regrets do.
2018
+ *
2019
+ * Measured on the bench flop (AsKh7d, single-threaded, to 0.5% of pot):
2020
+ * 52 iterations cold, 8 warm from a 0.1% solve of AsKh6d, 20 from AsQh7d.
2021
+ * It pays only when the whole old solve is at hand: seeding the flop's
2022
+ * decisions alone, as a downloadable library could, saved at most 15%
2023
+ * (see `Approximations`).
2024
+ */
2025
+ readonly warmCards?: Uint8Array;
958
2026
  /**
959
2027
  * The iteration to carry on counting from, which sets how heavily DCFR
960
2028
  * discounts the inherited regrets and how CFR+ weights the averages. Unset,
@@ -976,13 +2044,144 @@ interface SolveOptions {
976
2044
  readonly simd?: boolean;
977
2045
  /**
978
2046
  * Which traversal runs. Unset, the WebAssembly engine wherever it applies
979
- * — one thread, 32-bit storage, WebAssembly SIMD available — and the
980
- * JavaScript one otherwise. 'js' forces JavaScript, to compare the two.
2047
+ * — 32-bit storage (or 16-bit and compact with `wasmStorage`), WebAssembly
2048
+ * SIMD available — and the JavaScript one otherwise. 'js' forces
2049
+ * JavaScript, to compare the two.
981
2050
  */
982
2051
  readonly engine?: 'js';
2052
+ /**
2053
+ * 16-bit and compact storage on the WebAssembly engine (issue #84): pass
2054
+ * `wasmStorage` from `poker-flopsolve/wasm-storage`. With it, a solve at
2055
+ * `precision: 'i16'` or of a `compactStorage` spot runs on the engine,
2056
+ * threads included, rather than on JavaScript. Its updates are the
2057
+ * JavaScript ones, step for step, worked in 32-bit floats rather than
2058
+ * 64-bit ones, so a stored value differs only where it lies within float32
2059
+ * precision of a rounding boundary; the random rounding hashes the same
2060
+ * slot and iteration, read to 24 bits rather than 32. Compact scales
2061
+ * below 2^-126 (regrets under 10^-35) are taken as 0. Unset, those solves run on
2062
+ * JavaScript as before; 32-bit solves run on the default engine either
2063
+ * way, and `precision: 'f64'` on JavaScript.
2064
+ */
2065
+ readonly wasmStorage?: WasmStorage;
983
2066
  }
984
2067
  /** See `SolveOptions.approximations`. */
985
2068
  interface Approximations {
2069
+ /**
2070
+ * Solve a coarser copy of the spot first and start the real one from its
2071
+ * regrets — coarse to fine, as multigrid methods do. The copy buckets
2072
+ * turn and river cards like `runoutBuckets`, so each of its iterations
2073
+ * is cheaper (a flop stores ~40% fewer runouts at a gap of 3), and its
2074
+ * equilibrium is close enough to the real one's that the real solve picks
2075
+ * up roughly where it left off. The answer is still the real spot's: the
2076
+ * coarse game only chooses where it starts, and exploitability and
2077
+ * `targetPercent` measure the real game. Unset, off.
2078
+ *
2079
+ * Measured on three flop spots in Chromium, one thread, stopped at 15 s,
2080
+ * with 40 coarse iterations (issue #24): root-EV error per combination
2081
+ * against a 0.1%-of-pot reference fell from 1.51% to 0.19% of pot on
2082
+ * AsKh7d (exploitability 0.94% to 0.40%), and 0.26% to 0.06% on the
2083
+ * wider bench flop. A monotone flop, which a cold solve already settles
2084
+ * within 15 s, reached 0.5% error in half the time but ended a little
2085
+ * looser, 0.11% against 0.04%. To an exploitability target in Node it
2086
+ * was faster on all three: 0.1% on the monotone flop in 14.5 s instead of
2087
+ * 15.3, 0.2% on the wide one in 15.5 instead of 19.3, 0.3% on AsKh7d in
2088
+ * 23.8 instead of 31.5. Around 40 iterations suits a flop; far fewer
2089
+ * leave the coarse solve too rough to help, far more spend the time
2090
+ * where the real solve would have spent it better.
2091
+ *
2092
+ * Carrying the coarse average strategy, restarting DCFR's count (a
2093
+ * `warmIteration` of 0 or 10), a bucket gap of 1, or forbidding donk bets
2094
+ * in the coarse spot were measured too, and were all worse.
2095
+ *
2096
+ * The coarse iterations count toward `totalIterations`, not `completed`
2097
+ * or `Solution.iterations`; DCFR carries on counting from them unless
2098
+ * `warmIteration` says otherwise. Both solves are in memory at the
2099
+ * switch, the coarse one about 60% the size of the real one on a flop.
2100
+ * Where bucketing folds no runouts together — a river spot, ranges with no rank symmetry — it does
2101
+ * nothing. Not with `warmStart`, which it already is. The coarse solve
2102
+ * runs inside `createRun`, all at once and without progress reports, so
2103
+ * a caller stepping a run to stay responsive should keep it short; it
2104
+ * must fit in what `maxBytes` leaves beside the real spot, at 16 bits if
2105
+ * not 32, or `createRun` refuses.
2106
+ */
2107
+ readonly coarseStart?: CoarseStart;
2108
+ /**
2109
+ * Report `Solution.ev` and `Solution.handEvs` under the current profile —
2110
+ * the regret-matched strategy the next iteration would play — instead of
2111
+ * the average strategy. Default off. Measured under DCFR, the default
2112
+ * update rule; it applies to CFR+ alike.
2113
+ *
2114
+ * Measured against a solve to 0.045% of pot, after a 15 s single-threaded
2115
+ * browser budget, the current profile's per-hand root EVs had a mean error
2116
+ * of 1.23% of pot where the average's had 2.18% (flop As Kh 7d), 0.11%
2117
+ * against 0.37% (monotone Ks 9s 4s) and 1.40% against 2.02% (wide Qs Jh
2118
+ * 2c). Across those three spots it was the closer one at 62 of 65
2119
+ * checkpoints from 15 s down to 0.1% exploitability, often by 2–4 times.
2120
+ * It costs the same one pass per player as reading the average's EVs.
2121
+ *
2122
+ * Those EVs then belong to a different profile from the strategy
2123
+ * `strategyAt` and `reachAt` show, which stays the average: the average is
2124
+ * what converges to equilibrium and what exploitability measures, while
2125
+ * the current profile's values happen to settle sooner. Read them as the
2126
+ * better estimate of the equilibrium's EVs, not as the EVs of the strategy
2127
+ * on screen. A run with `analysisOnly` has no regrets and cannot use this.
2128
+ */
2129
+ readonly currentProfileEv?: boolean;
2130
+ /**
2131
+ * Chance sampling with baselines (VR-MCCFR; Schmid et al., 2019). Each
2132
+ * training iteration walks each turn and river deal with probability `p`
2133
+ * (default 0.35, both rounds). A deal left out adds the per-hand values it
2134
+ * returned when last walked, its baseline; a walked deal adds
2135
+ * `b + (v - b) / p` and its values become the new baseline. DCFR discounts
2136
+ * a skipped subtree missed are applied when it is next walked. This is
2137
+ * what made sampling pay where the plain 1/p weighting (docs/APPROXIMATIONS.md) did not:
2138
+ * the correction only carries how much a deal's values moved since its
2139
+ * last walk, which is small.
2140
+ *
2141
+ * Iterations get several times cheaper and take 2–5 times as many to a
2142
+ * target, so the net is about 1.2–1.5 times faster to 0.3% of pot, and
2143
+ * per-hand root EVs come out closer to the true ones at the same
2144
+ * exploitability. Measured single-threaded in Node against the exact
2145
+ * solve, time to 0.3% of pot (to 1%): AsKh7d 23.7 s → 15.9 s (13.3 → 9.0),
2146
+ * Ks9s4s 6.0 → 4.3 (3.4 → 2.3), the README's wide flop 13.4 → 9.3
2147
+ * (7.5 → 5.3), and pairs-and-broadway ranges on AsKh7d 16.7 → 12.9 and on
2148
+ * Ks9s4s 5.5 → 4.5. Exploitability is measured exactly, in the full game.
2149
+ *
2150
+ * Costs: one float per hand per stored deal per chance node, 6–31 MB on
2151
+ * those flops (about 12–20% beside their storage), counted against
2152
+ * `maxBytes`. Any storage: 32-, 64- or 16-bit, or `compactStorage`
2153
+ * over 32 or 16 bits (16-bit since issue #102, with the same DCFR
2154
+ * catch-up, in both engines).
2155
+ *
2156
+ * Threads (issue #99): it runs on `workers` threads, in the JavaScript
2157
+ * pool and on the WebAssembly engine's threads alike. Threads split the
2158
+ * runouts as for an exact solve, and the state sampling keeps (baselines,
2159
+ * when each deal was last walked, when each block was last updated for
2160
+ * the catch-up) lives in shared memory, each thread's runouts' entries
2161
+ * its own. There is no per-thread random stream: whether a deal is walked
2162
+ * on an iteration is a hash of its chance node, the deal and the
2163
+ * iteration, in both engines, so every thread count walks the same deals
2164
+ * on the same iterations. A fixed count is then bitwise repeatable, and
2165
+ * different counts differ only as unsampled ones do (see `workers`). A
2166
+ * spot sampling a round above the threads' split, which no flop or turn
2167
+ * spot has, runs on one thread. Measured in Chromium on issue #47's
2168
+ * blueprint, 4 threads ran 3.1–3.2 times faster than 1 on three flops,
2169
+ * and the shared AsKh7d blueprint's root play settled in 33 s against
2170
+ * 105 s (`bench/blueprint-share/README.md`). With `targetPercent`, a sampled solve runs more
2171
+ * iterations, so it makes a few more exploitability checks.
2172
+ * Off, nothing changes; at `p: 1` it is the exact solve, bit for bit.
2173
+ */
2174
+ readonly chanceSampling?: SamplingOptions;
2175
+ }
2176
+ /** See `Approximations.coarseStart`. */
2177
+ interface CoarseStart {
2178
+ /** Iterations of the coarse spot to run before the real one. */
2179
+ readonly iterations: number;
2180
+ /**
2181
+ * The coarse spot's `runoutBuckets`, at least the spot's own. Default 3;
2182
+ * a wider gap folds more runouts only where the ranges allow it.
2183
+ */
2184
+ readonly runoutBuckets?: number;
986
2185
  }
987
2186
  type Algorithm = 'cfr+' | 'dcfr';
988
2187
  type Precision = 'f64' | 'f32' | 'i16';
@@ -994,9 +2193,14 @@ declare const PRECISION_BYTES: {
994
2193
  };
995
2194
  interface Progress {
996
2195
  readonly iteration: number;
2196
+ /** In chips; NaN at a `settle` check made without `targetPercent`. */
997
2197
  readonly exploitability: number;
998
2198
  readonly elapsedMs: number;
2199
+ /** With `settle`: how far the root play moved since the last check (`rootPlayMovement`), NaN at the first. */
2200
+ readonly movement?: number;
999
2201
  }
2202
+ /** Which stopping rule ended a solve: see `Solution.stoppedAt`. */
2203
+ type StopReason = 'target' | 'iterations' | 'settled';
1000
2204
  /** A solved spot. */
1001
2205
  interface Solution {
1002
2206
  readonly spot: Spot;
@@ -1007,15 +2211,30 @@ interface Solution {
1007
2211
  /**
1008
2212
  * Which stopping rule ended the solve. 'iterations' with a `targetPercent`
1009
2213
  * set means the target was NOT reached and the answer is looser than asked
1010
- * for — worth surfacing rather than swallowing.
2214
+ * for — worth surfacing rather than swallowing. 'settled' is
2215
+ * `SolveOptions.settle`'s: the root play stopped moving.
1011
2216
  */
1012
- readonly stoppedAt: 'target' | 'iterations';
2217
+ readonly stoppedAt: StopReason;
1013
2218
  /** Worker threads the solve actually used, which 'auto' does not tell you. */
1014
2219
  readonly workers: number;
1015
2220
  /** The solver behind this solution, for analysis and warm starts. */
1016
2221
  readonly solver: Solver;
1017
- /** Chips per hand for a player, under the average strategy. */
2222
+ /**
2223
+ * Chips per hand for a player, under the average strategy — or under the
2224
+ * current profile with `approximations.currentProfileEv`.
2225
+ */
1018
2226
  ev(player: 0 | 1): number;
2227
+ /**
2228
+ * Root EV in chips for each combination a player can hold, indexed like
2229
+ * `COMBO_CARDS` (as `reachAt` is): what that hand wins on average, over
2230
+ * the opponent hands it can be dealt against. Zero for combinations outside
2231
+ * the range or blocked by the board, and for a hand no opponent hand can be
2232
+ * dealt against, which has no EV to give. Weighted by range weight times
2233
+ * compatible opponent mass, the mean is `ev(player)`, and the same pass
2234
+ * serves both. Under the average strategy, or the current profile with
2235
+ * `approximations.currentProfileEv`. Returns a fresh copy.
2236
+ */
2237
+ handEvs(player: 0 | 1): Float64Array;
1019
2238
  /** Distance from equilibrium, in chips per hand. */
1020
2239
  exploitability(): number;
1021
2240
  /**
@@ -1055,7 +2274,7 @@ interface Solution {
1055
2274
  readonly history: readonly Progress[];
1056
2275
  }
1057
2276
  /** Betting for a subgame; anything unset keeps the original spot's. */
1058
- type SubgameBetting = Partial<Pick<SpotConfig, 'betSizes' | 'raiseSizes' | 'maxRaises' | 'allowAllIn' | 'allInThreshold' | 'noDonk' | 'mergeSizes' | 'maxCombos' | 'maxBytes'>>;
2277
+ type SubgameBetting = Partial<Pick<SpotConfig, 'betSizes' | 'raiseSizes' | 'maxRaises' | 'allowAllIn' | 'allInThreshold' | 'noDonk' | 'mergeSizes' | 'removeActions' | 'thinSizes' | 'maxCombos' | 'maxBytes'>>;
1059
2278
  interface StrategyView {
1060
2279
  readonly node: number;
1061
2280
  readonly board: number;
@@ -1089,7 +2308,7 @@ interface SolveRun {
1089
2308
  */
1090
2309
  trueExploitabilityPercent(): number;
1091
2310
  /** A view of the strategy as it stands; cheap, take a fresh one each time. */
1092
- snapshot(history?: readonly Progress[], stoppedAt?: 'target' | 'iterations'): Solution;
2311
+ snapshot(history?: readonly Progress[], stoppedAt?: StopReason): Solution;
1093
2312
  /** Release worker threads. Snapshots taken before this stay usable. */
1094
2313
  close(): void;
1095
2314
  /** Worker threads actually in use; 1 when single-threaded. */
@@ -1108,6 +2327,8 @@ interface SolveRun {
1108
2327
  * @param options solver setup
1109
2328
  */
1110
2329
  declare function createRun(spot: Spot, options?: SolveOptions): SolveRun;
2330
+ /** Bytes `of` takes stored at `at`, compact storage included. */
2331
+ declare function storageCost(of: Spot, at: Precision): number;
1111
2332
  /** View a buffer as regret storage of the given precision. */
1112
2333
  declare function makeRegretStore(precision: Precision, buffer: ArrayBuffer | SharedArrayBuffer): RegretStore;
1113
2334
  /** View a buffer as strategy-sum storage of the given precision. */
@@ -1135,4 +2356,4 @@ declare function solve(spot: Spot, options?: SolveOptions): Solution;
1135
2356
  */
1136
2357
  declare function predictCrossing(t1: number, e1: number, t2: number, e2: number, target: number): number;
1137
2358
 
1138
- export { ACTION_LABELS, ActionKind, type Algorithm, type Approximations, type BetSize, CATEGORY, CATEGORY_NAMES, COMBOS, COMBO_CARDS, COMBO_LANES, DECK, type Estimate, NodeKind, PLATFORM, PRECISION_BYTES, type PerPlayer, type Precision, type Progress, RANKS, type RaiseSizes, type ResolvedBoard, SUITS, type Solution, type SolveOptions, type SolveRun, type Solver, type Spot, type SpotConfig, SpotTooLargeError, type StrategyView, type SubgameBetting, type WarmStartReport, activeCombos, cardOf, categoryOf, comboIndex, createRun, defineSpot, evaluate, evaluateCards, formatCard, formatCards, formatCombo, makeRegretStore, makeSumStore, parseCard, parseCards, parseRange, predictCrossing, rangeWeight, rankOf, simdAvailable, solve, suitLanes, suitOf };
2359
+ export { ACTION_LABELS, ActionKind, type Algorithm, type Approximations, type BetSize, CATEGORY, CATEGORY_NAMES, COMBOS, COMBO_CARDS, COMBO_LANES, type CoarseStart, type CompactStorage, DECK, type Estimate, type LineReach, type LinesWithinOptions, type LiteOptions, type LitePreset, type LiteResolveOptions, type LiteSolution, NodeKind, PLATFORM, PRECISION_BYTES, type PerPlayer, type Precision, type PresetChanges, type Progress, RANKS, type RaiseSizes, type ResolveOptions, type ResolvedBoard, type ResolvedSubgame, type RootPlay, SUITS, type SamplingOptions, type SettingChange, type SettleOptions, type SettleTracker, type ShareHistories, type SizesCut, type Solution, type SolveLiteOptions, type SolveOptions, type SolveRun, type Solver, type Spot, type SpotConfig, SpotTooLargeError, type StopReason, type StrategyView, type Street, type SubgameBetting, type WarmStartReport, type WasmStorage, activeCombos, bettingFrom, cardOf, categoryOf, checkedDown, comboIndex, createRun, defineSpot, evaluate, evaluateCards, formatCard, formatCards, formatCombo, keepWithin, linesWithin, liteConfig, litePreset, makeRegretStore, makeSumStore, parseCard, parseCards, parseRange, predictCrossing, rangeWeight, rankOf, rankSwap, resolveSubgame, rootPlay, rootPlayMovement, rootPlayNodes, simdAvailable, solve, solveLite, storageCost, suitLanes, suitOf, trackSettle, turnLineReach };