pokerfast 0.1.0__tar.gz

pokerfast-0.1.0/.gitattributes

@@ -0,0 +1,4 @@
+* text=auto eol=lf
+*.sh text eol=lf
+*.png binary
+*.exe binary

pokerfast-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[test]"
+
+      - name: Test
+        # The differential tests against pokerkit are the correctness argument.
+        # `[test]` pins pokerkit, so a skip here means something is wrong with
+        # the install rather than with the environment -- treat it as a failure.
+        run: pytest -ra -q
+
+      - name: Fail if the differential tests were skipped
+        shell: bash
+        run: |
+          python - <<'PY'
+          import pokerkit, sys
+          print("pokerkit", pokerkit.__name__, "importable -- differential tests ran")
+          PY

pokerfast-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,61 @@
+name: Publish to PyPI
+
+# Trusted publishing (OIDC): no API token is stored anywhere. PyPI verifies
+# that the request came from this workflow, in this repository, in the `pypi`
+# environment, and mints a short-lived credential for that one upload.
+#
+# Fires on a published GitHub Release, so cutting a release IS the publish.
+# workflow_dispatch is kept for a manual re-run if an upload fails halfway.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build sdist and wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        # No submodules: the wheel is pure Python (src/pokerfast only). OMPEval
+        # is needed to BUILD the optional native equity helper, never to build
+        # the distribution.
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check dist/*
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish
+    needs: build
+    runs-on: ubuntu-latest
+    # This environment must exist in the repository settings, and its name must
+    # match the one registered with the trusted publisher on PyPI, or the
+    # upload is rejected.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pokerfast
+    permissions:
+      id-token: write        # the OIDC token. Without this, publishing fails.
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

pokerfast-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+native/build/
+dist/

pokerfast-0.1.0/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "vendor/OMPEval"]
+	path = vendor/OMPEval
+	url = https://github.com/vkresch/OMPEval.git

pokerfast-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tie.yob
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pokerfast-0.1.0/NOTICE

@@ -0,0 +1,22 @@
+pokerfast bundles no third-party source.
+
+The optional exact-equity helper (`pokerfast.equity`, `native/`) builds against
+OMPEval, which is fetched as a git submodule into vendor/OMPEval and is NOT
+redistributed here.
+
+    OMPEval -- https://github.com/vkresch/OMPEval
+               (a fork of https://github.com/zekyll/OMPEval)
+    pinned at commit 725a819
+    ISC License, Copyright (c) 2016, Timo A.
+
+    OMPEval vendors libdivide, which carries its own licence; see
+    vendor/OMPEval/LICENSE-libdivide.txt after initialising the submodule.
+
+If you distribute a BINARY built by native/build.sh, it links OMPEval and you
+must carry OMPEval's copyright and permission notice with it. The ISC licence
+text travels with the submodule at vendor/OMPEval/LICENSE.txt.
+
+`native/patches/0001-constexpr-urbg.patch` is a two-line change to OMPEval's
+omp/Random.h making min()/max() constexpr, which newer C++ standard libraries
+require of a UniformRandomBitGenerator. It is applied to the submodule working
+tree at build time and is not committed upstream here.

pokerfast-0.1.0/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.5
+Name: pokerfast
+Version: 0.1.0
+Summary: Fast hold'em hand evaluation, a lean 6-max NLHE engine, and runtime accelerators for pokerkit
+Project-URL: Source, https://github.com/wesboyt/pokerfast
+Project-URL: Issues, https://github.com/wesboyt/pokerfast/issues
+License: MIT License
+        
+        Copyright (c) 2026 tie.yob
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+License-File: NOTICE
+Keywords: equity,hand-evaluator,holdem,poker,pokerkit
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Provides-Extra: pokerkit
+Requires-Dist: pokerkit==0.7.3; extra == 'pokerkit'
+Provides-Extra: test
+Requires-Dist: pokerkit==0.7.3; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# pokerfast
+
+Fast Texas hold'em primitives: a table-driven 7-card evaluator, a lean 6-max
+no-limit engine, and runtime accelerators for [pokerkit](https://github.com/uoftcprg/pokerkit).
+
+Three independent pieces. Take whichever you need — none of them requires the
+others.
+
+| you want | use | against pokerkit |
+|---|---|---|
+| compare 7-card hands | `eval7` | **74x** (1 core) → **331x** (4 cores) |
+| play out millions of hands | `FastHand` | **45x** (1 core) → **160x** (4 cores) |
+| keep pokerkit, lose the cost | `pokerfast.patches` | ~2x on the evaluation path |
+| exact multi-way equity | `pokerfast.equity` | C++ (OMPEval), batched |
+
+The speedup **grows with core count**, because the two engines scale in
+opposite directions on a free-threaded build. See [Benchmarks](#benchmarks).
+
+## Install
+
+```bash
+pip install pokerfast                      # core: eval7 + FastHand
+pip install "pokerfast[pokerkit]"          # + the pokerkit patches
+```
+
+## 1. `eval7` — 7-card evaluation
+
+```python
+from pokerfast import eval7
+
+eval7(('As', 'Ks', 'Qs', 'Js', 'Ts', '2c', '3d'))   # royal flush
+```
+
+A rank-histogram evaluator with two precomputed 8192-entry tables. One pass
+over seven cards, a flush test, a straight lookup, a branch on the count
+pattern — no enumeration of the 21 five-card combinations.
+
+**Only the ORDER is defined.** The integer is not a hand rank anyone else's
+code will recognise: compare two of them, don't interpret one. The test suite
+checks the induced order against pokerkit over thousands of random hands, with
+ties counted separately so an evaluator that called everything equal could not
+pass, plus an explicit sweep of every category (random deals almost never
+produce a steel wheel).
+
+## 2. `FastHand` — a 6-max NLHE engine
+
+```python
+from pokerfast import FastHand
+
+h = FastHand()                      # deal 6 players, 100/200 blinds
+while not h.done:
+    space = h.get_action_space()    # {'call': 200, 'fold': 0, 'min_bet': 400, ...}
+    h.call()
+h.state.payoffs
+```
+
+pokerkit is a general, validating framework for dozens of variants, and that
+generality costs per action. This implements exactly one game — 6-max NLHE,
+cash mode, fixed blinds, one runout — where the state is a few integer lists,
+an action is a few additions, and a snapshot is a list copy.
+
+**Why you can trust it:** `tests/test_engine.py` is a differential test. It
+drives this engine and pokerkit through the same random action sequence and
+compares the action space, the exact chip amounts, turn order, pot, board
+length and the per-street action log at *every step*, over hundreds of hands,
+with raises over-sampled at the extremes because the min-raise increment and
+all-in-for-less rules are where engines go wrong.
+
+### Observers
+
+Watch the action stream without re-deriving it:
+
+```python
+class Log:
+    def __init__(self):        self.events = []
+    def action(self, seat, amount): self.events.append((seat, amount))
+    def board(self, street, cards): self.events.append((street, cards))
+    def clone(self):           ...        # called on deepcopy
+
+h = FastHand(observer=Log())
+```
+
+`clone()` matters: a branch must not write history back into the position it
+branched from. Amounts are `-1` for a fold, `0` for a check, chips otherwise.
+
+## 3. `pokerfast.patches` — make pokerkit itself faster
+
+When you need pokerkit's exact semantics but not its cost:
+
+```python
+from pokerfast import patches
+patches.install_all()
+```
+
+Nothing in `site-packages` is modified — these are in-process monkey-patches:
+
+- an identity `__deepcopy__` on pokerkit's frozen dataclasses (copying an
+  immutable object is pure waste), applied only to classes verified to declare
+  no mutable field;
+- memoisation of `Lookup._get_key` and `<HandType>.from_game`;
+- a tuple fast path for `Card.clean`.
+
+**Guarded.** The dangerous failure isn't "the attribute is gone" — that raises,
+and is safe. It's "the attribute is still there and means something else",
+which is silent. So the version is pinned, the signatures of everything patched
+are fingerprinted, and a mismatch disables the patches loudly rather than
+applying one that was never verified. `POKERFAST_STRICT=0` overrides, once
+you've checked it yourself.
+
+## 4. `pokerfast.equity` — exact equity (optional)
+
+Needs a C++ toolchain and CMake. OMPEval is a **git submodule**, not vendored
+source:
+
+```bash
+git submodule update --init --recursive
+bash native/build.sh
+```
+
+```python
+from pokerfast.equity import EquityCalculator
+
+with EquityCalculator() as eq:
+    eq.equity('AhKd', '2c3d4h5s6c')
+    eq.equity_many([('AhKd', '2c3d4h5s6c'), ('7c7d', '')])
+```
+
+The helper keeps **one** process alive and serves queries over stdin/stdout. A
+single-query process spends ~19 ms of its ~26 ms building an 86,547-entry
+lookup table it then throws away, so batching is most of the win. It also
+enumerates exhaustively rather than sampling (with a full board the opponent
+has only C(45,2) = 990 hands, so exact is both cheaper *and* exact) and runs
+single-threaded, because a thread pool costs more than a 990-combination
+problem.
+
+See `NOTICE` for OMPEval's ISC licence and what it requires if you ship a
+binary.
+
+## Environment variables
+
+| variable | default | effect |
+|---|---|---|
+| `POKERFAST_TABLE_EVAL` | `1` | `0` routes showdowns through pokerkit instead |
+| `POKERFAST_STRICT` | `1` | `0` patches pokerkit despite a fingerprint mismatch |
+| `POKERFAST_EVAL_CACHE` | `65536` | `Lookup._get_key` cache size |
+| `POKERFAST_FROMGAME_CACHE` | `32768` | `from_game` cache size |
+| `POKERFAST_OMPEVAL` | — | path to a prebuilt `ompeval_batch` |
+
+## Tests
+
+```bash
+pip install "pokerfast[test]"
+pytest
+```
+
+The differential tests need pokerkit and are the reason to trust any of this;
+they skip without it, which makes the suite much weaker. Don't read a green run
+that skipped them as a pass.
+
+## Benchmarks
+
+```bash
+PYTHON_GIL=0 python benchmarks/benchmark.py --threads 1,2,4 --rounds 5
+```
+
+Paired and interleaved: every round runs both engines back to back, alternating
+which goes first, and reports the **ratio** — which survives a busy machine,
+because contention hits both arms. Each arm gets the same wall budget and
+reports how much it finished, so neither is penalised by a miscalibrated work
+count. The per-round ratios are printed; if they disagree with each other, the
+machine was too noisy and the median means nothing.
+
+CPython 3.14.7 free-threaded, pokerkit 0.7.3, 5 rounds, 3 s per arm:
+
+| threads | full hands played to completion | 7-card evaluation |
+|---|---|---|
+| 1 | **45x** (5,151/s vs 116/s) | **74x** (269k/s vs 3,476/s) |
+| 2 | **76x** (10,029/s vs 135/s) | **122x** (480k/s vs 3,700/s) |
+| 4 | **160x** (11,110/s vs 67/s) | **331x** (558k/s vs 1,610/s) |
+
+### Why the speedup grows with cores
+
+Relative to each engine's *own* single-thread rate:
+
+| threads | pokerfast | pokerkit |
+|---|---|---|
+| 1 | 1.00x | 1.00x |
+| 2 | 1.95x | 1.17x |
+| 4 | 2.16x | **0.58x** |
+
+pokerfast scales sublinearly, as you would expect. pokerkit goes *backwards* —
+at four threads it does less total work than at one. That reproduced across
+three separate runs (0.49x, 0.70x, 0.58x), so it is an effect rather than
+noise, but **the cause is untested**: the likely candidate is reference-count
+contention on shared immutable objects, which a free-threaded build turns into
+cache-line ping-pong between cores. Treat that as a hypothesis, not a finding.
+
+The compounding of those two curves is the whole story: 45x becomes 160x not
+because pokerfast got faster, but because pokerkit got slower.
+
+### What these numbers are not
+
+Measured on one machine — an 8-thread laptop — **with an unrelated GPU training
+job occupying ~1.5 cores throughout**. The paired ratios are protected against
+that; the scaling column compares an engine against itself and is only
+partially protected, and 8 threads was not measured at all because the machine
+was not free. Expect different absolutes elsewhere.
+
+They also describe a *bulk* workload that plays hands to completion. If you
+deal one hand and inspect it, pokerkit's constant factor is irrelevant to you
+and you should use pokerkit — it is a far more general library, and pokerfast
+is only faster because it does much less.
+
+## Licence
+
+MIT — see `LICENSE`. OMPEval is ISC and is not redistributed here; see `NOTICE`.

pokerfast-0.1.0/README.md

@@ -0,0 +1,216 @@
+# pokerfast
+
+Fast Texas hold'em primitives: a table-driven 7-card evaluator, a lean 6-max
+no-limit engine, and runtime accelerators for [pokerkit](https://github.com/uoftcprg/pokerkit).
+
+Three independent pieces. Take whichever you need — none of them requires the
+others.
+
+| you want | use | against pokerkit |
+|---|---|---|
+| compare 7-card hands | `eval7` | **74x** (1 core) → **331x** (4 cores) |
+| play out millions of hands | `FastHand` | **45x** (1 core) → **160x** (4 cores) |
+| keep pokerkit, lose the cost | `pokerfast.patches` | ~2x on the evaluation path |
+| exact multi-way equity | `pokerfast.equity` | C++ (OMPEval), batched |
+
+The speedup **grows with core count**, because the two engines scale in
+opposite directions on a free-threaded build. See [Benchmarks](#benchmarks).
+
+## Install
+
+```bash
+pip install pokerfast                      # core: eval7 + FastHand
+pip install "pokerfast[pokerkit]"          # + the pokerkit patches
+```
+
+## 1. `eval7` — 7-card evaluation
+
+```python
+from pokerfast import eval7
+
+eval7(('As', 'Ks', 'Qs', 'Js', 'Ts', '2c', '3d'))   # royal flush
+```
+
+A rank-histogram evaluator with two precomputed 8192-entry tables. One pass
+over seven cards, a flush test, a straight lookup, a branch on the count
+pattern — no enumeration of the 21 five-card combinations.
+
+**Only the ORDER is defined.** The integer is not a hand rank anyone else's
+code will recognise: compare two of them, don't interpret one. The test suite
+checks the induced order against pokerkit over thousands of random hands, with
+ties counted separately so an evaluator that called everything equal could not
+pass, plus an explicit sweep of every category (random deals almost never
+produce a steel wheel).
+
+## 2. `FastHand` — a 6-max NLHE engine
+
+```python
+from pokerfast import FastHand
+
+h = FastHand()                      # deal 6 players, 100/200 blinds
+while not h.done:
+    space = h.get_action_space()    # {'call': 200, 'fold': 0, 'min_bet': 400, ...}
+    h.call()
+h.state.payoffs
+```
+
+pokerkit is a general, validating framework for dozens of variants, and that
+generality costs per action. This implements exactly one game — 6-max NLHE,
+cash mode, fixed blinds, one runout — where the state is a few integer lists,
+an action is a few additions, and a snapshot is a list copy.
+
+**Why you can trust it:** `tests/test_engine.py` is a differential test. It
+drives this engine and pokerkit through the same random action sequence and
+compares the action space, the exact chip amounts, turn order, pot, board
+length and the per-street action log at *every step*, over hundreds of hands,
+with raises over-sampled at the extremes because the min-raise increment and
+all-in-for-less rules are where engines go wrong.
+
+### Observers
+
+Watch the action stream without re-deriving it:
+
+```python
+class Log:
+    def __init__(self):        self.events = []
+    def action(self, seat, amount): self.events.append((seat, amount))
+    def board(self, street, cards): self.events.append((street, cards))
+    def clone(self):           ...        # called on deepcopy
+
+h = FastHand(observer=Log())
+```
+
+`clone()` matters: a branch must not write history back into the position it
+branched from. Amounts are `-1` for a fold, `0` for a check, chips otherwise.
+
+## 3. `pokerfast.patches` — make pokerkit itself faster
+
+When you need pokerkit's exact semantics but not its cost:
+
+```python
+from pokerfast import patches
+patches.install_all()
+```
+
+Nothing in `site-packages` is modified — these are in-process monkey-patches:
+
+- an identity `__deepcopy__` on pokerkit's frozen dataclasses (copying an
+  immutable object is pure waste), applied only to classes verified to declare
+  no mutable field;
+- memoisation of `Lookup._get_key` and `<HandType>.from_game`;
+- a tuple fast path for `Card.clean`.
+
+**Guarded.** The dangerous failure isn't "the attribute is gone" — that raises,
+and is safe. It's "the attribute is still there and means something else",
+which is silent. So the version is pinned, the signatures of everything patched
+are fingerprinted, and a mismatch disables the patches loudly rather than
+applying one that was never verified. `POKERFAST_STRICT=0` overrides, once
+you've checked it yourself.
+
+## 4. `pokerfast.equity` — exact equity (optional)
+
+Needs a C++ toolchain and CMake. OMPEval is a **git submodule**, not vendored
+source:
+
+```bash
+git submodule update --init --recursive
+bash native/build.sh
+```
+
+```python
+from pokerfast.equity import EquityCalculator
+
+with EquityCalculator() as eq:
+    eq.equity('AhKd', '2c3d4h5s6c')
+    eq.equity_many([('AhKd', '2c3d4h5s6c'), ('7c7d', '')])
+```
+
+The helper keeps **one** process alive and serves queries over stdin/stdout. A
+single-query process spends ~19 ms of its ~26 ms building an 86,547-entry
+lookup table it then throws away, so batching is most of the win. It also
+enumerates exhaustively rather than sampling (with a full board the opponent
+has only C(45,2) = 990 hands, so exact is both cheaper *and* exact) and runs
+single-threaded, because a thread pool costs more than a 990-combination
+problem.
+
+See `NOTICE` for OMPEval's ISC licence and what it requires if you ship a
+binary.
+
+## Environment variables
+
+| variable | default | effect |
+|---|---|---|
+| `POKERFAST_TABLE_EVAL` | `1` | `0` routes showdowns through pokerkit instead |
+| `POKERFAST_STRICT` | `1` | `0` patches pokerkit despite a fingerprint mismatch |
+| `POKERFAST_EVAL_CACHE` | `65536` | `Lookup._get_key` cache size |
+| `POKERFAST_FROMGAME_CACHE` | `32768` | `from_game` cache size |
+| `POKERFAST_OMPEVAL` | — | path to a prebuilt `ompeval_batch` |
+
+## Tests
+
+```bash
+pip install "pokerfast[test]"
+pytest
+```
+
+The differential tests need pokerkit and are the reason to trust any of this;
+they skip without it, which makes the suite much weaker. Don't read a green run
+that skipped them as a pass.
+
+## Benchmarks
+
+```bash
+PYTHON_GIL=0 python benchmarks/benchmark.py --threads 1,2,4 --rounds 5
+```
+
+Paired and interleaved: every round runs both engines back to back, alternating
+which goes first, and reports the **ratio** — which survives a busy machine,
+because contention hits both arms. Each arm gets the same wall budget and
+reports how much it finished, so neither is penalised by a miscalibrated work
+count. The per-round ratios are printed; if they disagree with each other, the
+machine was too noisy and the median means nothing.
+
+CPython 3.14.7 free-threaded, pokerkit 0.7.3, 5 rounds, 3 s per arm:
+
+| threads | full hands played to completion | 7-card evaluation |
+|---|---|---|
+| 1 | **45x** (5,151/s vs 116/s) | **74x** (269k/s vs 3,476/s) |
+| 2 | **76x** (10,029/s vs 135/s) | **122x** (480k/s vs 3,700/s) |
+| 4 | **160x** (11,110/s vs 67/s) | **331x** (558k/s vs 1,610/s) |
+
+### Why the speedup grows with cores
+
+Relative to each engine's *own* single-thread rate:
+
+| threads | pokerfast | pokerkit |
+|---|---|---|
+| 1 | 1.00x | 1.00x |
+| 2 | 1.95x | 1.17x |
+| 4 | 2.16x | **0.58x** |
+
+pokerfast scales sublinearly, as you would expect. pokerkit goes *backwards* —
+at four threads it does less total work than at one. That reproduced across
+three separate runs (0.49x, 0.70x, 0.58x), so it is an effect rather than
+noise, but **the cause is untested**: the likely candidate is reference-count
+contention on shared immutable objects, which a free-threaded build turns into
+cache-line ping-pong between cores. Treat that as a hypothesis, not a finding.
+
+The compounding of those two curves is the whole story: 45x becomes 160x not
+because pokerfast got faster, but because pokerkit got slower.
+
+### What these numbers are not
+
+Measured on one machine — an 8-thread laptop — **with an unrelated GPU training
+job occupying ~1.5 cores throughout**. The paired ratios are protected against
+that; the scaling column compares an engine against itself and is only
+partially protected, and 8 threads was not measured at all because the machine
+was not free. Expect different absolutes elsewhere.
+
+They also describe a *bulk* workload that plays hands to completion. If you
+deal one hand and inspect it, pokerkit's constant factor is irrelevant to you
+and you should use pokerkit — it is a far more general library, and pokerfast
+is only faster because it does much less.
+
+## Licence
+
+MIT — see `LICENSE`. OMPEval is ISC and is not redistributed here; see `NOTICE`.