pycgt 0.1.0__tar.gz

pycgt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nehalahmedshaikh
+
+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.

pycgt-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: pycgt
+Version: 0.1.0
+Summary: Combinatorial game theory in pure Python: exact canonical forms, thermography, and game values
+Author: nehalahmedshaikh
+License: MIT
+Project-URL: Homepage, https://github.com/nehalahmedshaikh/pycgt
+Project-URL: Repository, https://github.com/nehalahmedshaikh/pycgt
+Project-URL: Issues, https://github.com/nehalahmedshaikh/pycgt/issues
+Project-URL: Changelog, https://github.com/nehalahmedshaikh/pycgt/blob/main/CHANGELOG.md
+Keywords: combinatorial-game-theory,canonical-form,surreal-numbers,thermography,temperature,domineering,nim,partizan-games,exact-arithmetic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: ruff>=0.3; extra == "dev"
+Dynamic: license-file
+
+# pycgt
+
+**Combinatorial game theory in pure Python — exact canonical forms, thermography, and game values.**
+
+```python
+>>> from pycgt import parse, render, temperature, mean
+>>> from pycgt.rulesets import domineering
+
+>>> render(domineering.rectangle(2, 4))
+'Miny(2)'
+>>> temperature(domineering.rectangle(2, 3))
+Fraction(5, 4)
+>>> render(parse("{1|-1}") + parse("{1|-1}"))
+'0'
+```
+
+`pip install pycgt`. Python 3.11+, **no dependencies**.
+
+---
+
+## The one idea everything rests on
+
+Short games are **exact objects built from the empty game up**. Two values are
+equal, or one is greater, or they are *confused* with each other — there is no
+tolerance to set, no rounding, and no floating point anywhere. Temperatures are
+`Fraction`s found by bisection on an exact dyadic grid.
+
+The operation that makes this usable is **canonical form**. Two games of the
+same value reduce to *identical* canonical forms, so structural equality
+becomes value equality and comparison becomes a dictionary lookup. Every `Game`
+returned by this library is canonical, which is why `==` means what you want.
+
+## Why it exists
+
+[CGSuite](https://www.cgsuite.org/) is the established tool in this field and
+is far more complete than this. But it is a Java desktop application: not
+`pip install`-able, awkward to drive from a script, and unavailable in a
+notebook or in CI. Getting it to answer one batch of questions headlessly took
+a from-source Maven build and a JDK version pin.
+
+`pycgt` is for when you want game values inside ordinary Python. It has no
+dependencies, so it also runs unchanged under Pyodide in a browser.
+
+## What's here
+
+| | |
+|---|---|
+| **Core** | canonical form, the partial order, disjunctive sums, negation, birthdays |
+| **Numbers** | dyadic rationals both ways, Conway's simplicity rule |
+| **Named values** | `*`, `^`, `v`, nimbers, switches, `tiny`, `miny` |
+| **Stops** | left/right stops, confusion intervals, infinitesimality, hot/tepid tests |
+| **Reduced form** | reduced canonical form, and `ish` — the infinitesimal remainder |
+| **Thermography** | heating, overheating, cooling, temperature, mean value |
+| **Notation** | render to readable text, and parse it back |
+| **Rulesets** | Domineering, Cram, Nim, Blue-Red Hackenbush |
+
+Games are only **partially** ordered, so `<=` and `>=` are defined but `<` and
+`>` deliberately are not — `not (G <= H)` does not imply `G > H`. Use
+`compare()` for the four-way answer, which includes *confused*.
+
+```python
+>>> from pycgt import compare, STAR, ZERO
+>>> compare(STAR, ZERO)
+<Relation.CONFUSED: '||'>
+```
+
+## A worked example
+
+[`examples/berlekamp_1988.py`](examples/berlekamp_1988.py) reproduces
+Berlekamp's *Blockbusting and Domineering* (1988) — his Table III sequences,
+their period-5/saltus-1 structure, and the overheating bound from Appendix B.1 —
+and checks the results against the paper.
+
+```console
+$ python examples/berlekamp_1988.py
+  period 5, saltus 1: holds
+  x_1 is the only non-number: 1*
+  ok    G_2 = tiny-2
+  ok    G_3 = +-1 + 2*tiny-2
+```
+
+## Correctness
+
+The interesting values in this field are easy to get subtly wrong, so nothing
+here is trusted because it looks right. The test suite validates against
+**external** sources:
+
+- **CGSuite** — canonical forms, temperatures and means of Domineering 2×n
+  boards, generated by driving CGSuite 2.2 headlessly.
+- **Berlekamp (1988)**, *Blockbusting and Domineering*, Appendix B.1 — his
+  exact values for the 2-wide Domineering rectangles, `G₂ = tiny-2` and
+  `G₃ = ±1 + 2·tiny-2`.
+- **Wolfe**, via Guy's Problem 4 in *Games of No Chance* — the 4×5 board is `1`.
+- **Uiterwijk**, [arXiv:1305.3257](https://arxiv.org/pdf/1305.3257) — the
+  value of the 11×2 board.
+- **Closed forms** — Nim sums follow exclusive-or; Hackenbush strings give the
+  expected dyadic rationals; Cram values are nimbers.
+
+Plus internal laws that catch real bugs: `G + (−G) = 0`, transposing a
+Domineering board negates its value, `ish(G)` is *always* infinitesimal, and
+canonical form is idempotent.
+
+## Provenance
+
+Implemented clean-room from the mathematics — *Winning Ways*, Siegel's
+*Combinatorial Game Theory*, and Berlekamp (1988). CGSuite is GPL; its source
+was consulted **only** for the API needed to run it as a test oracle, and none
+of its implementation was used or ported. This library is MIT.
+
+## Limitations
+
+Honest about scope:
+
+- **Short games only.** No loopy games, stoppers, or `on`/`off`.
+- **No misère theory** and no misère quotients.
+- **Slower than CGSuite**, which is a JVM program with far more optimisation.
+  Expect exact Domineering values up to about 2×16 comfortably.
+- **The number-temperature convention** (a number with denominator `2**k` has
+  temperature `−1/2**k`) is checked against CGSuite for `0` and `1/2` only.
+
+## Licence
+
+MIT.

pycgt-0.1.0/README.md

@@ -0,0 +1,123 @@
+# pycgt
+
+**Combinatorial game theory in pure Python — exact canonical forms, thermography, and game values.**
+
+```python
+>>> from pycgt import parse, render, temperature, mean
+>>> from pycgt.rulesets import domineering
+
+>>> render(domineering.rectangle(2, 4))
+'Miny(2)'
+>>> temperature(domineering.rectangle(2, 3))
+Fraction(5, 4)
+>>> render(parse("{1|-1}") + parse("{1|-1}"))
+'0'
+```
+
+`pip install pycgt`. Python 3.11+, **no dependencies**.
+
+---
+
+## The one idea everything rests on
+
+Short games are **exact objects built from the empty game up**. Two values are
+equal, or one is greater, or they are *confused* with each other — there is no
+tolerance to set, no rounding, and no floating point anywhere. Temperatures are
+`Fraction`s found by bisection on an exact dyadic grid.
+
+The operation that makes this usable is **canonical form**. Two games of the
+same value reduce to *identical* canonical forms, so structural equality
+becomes value equality and comparison becomes a dictionary lookup. Every `Game`
+returned by this library is canonical, which is why `==` means what you want.
+
+## Why it exists
+
+[CGSuite](https://www.cgsuite.org/) is the established tool in this field and
+is far more complete than this. But it is a Java desktop application: not
+`pip install`-able, awkward to drive from a script, and unavailable in a
+notebook or in CI. Getting it to answer one batch of questions headlessly took
+a from-source Maven build and a JDK version pin.
+
+`pycgt` is for when you want game values inside ordinary Python. It has no
+dependencies, so it also runs unchanged under Pyodide in a browser.
+
+## What's here
+
+| | |
+|---|---|
+| **Core** | canonical form, the partial order, disjunctive sums, negation, birthdays |
+| **Numbers** | dyadic rationals both ways, Conway's simplicity rule |
+| **Named values** | `*`, `^`, `v`, nimbers, switches, `tiny`, `miny` |
+| **Stops** | left/right stops, confusion intervals, infinitesimality, hot/tepid tests |
+| **Reduced form** | reduced canonical form, and `ish` — the infinitesimal remainder |
+| **Thermography** | heating, overheating, cooling, temperature, mean value |
+| **Notation** | render to readable text, and parse it back |
+| **Rulesets** | Domineering, Cram, Nim, Blue-Red Hackenbush |
+
+Games are only **partially** ordered, so `<=` and `>=` are defined but `<` and
+`>` deliberately are not — `not (G <= H)` does not imply `G > H`. Use
+`compare()` for the four-way answer, which includes *confused*.
+
+```python
+>>> from pycgt import compare, STAR, ZERO
+>>> compare(STAR, ZERO)
+<Relation.CONFUSED: '||'>
+```
+
+## A worked example
+
+[`examples/berlekamp_1988.py`](examples/berlekamp_1988.py) reproduces
+Berlekamp's *Blockbusting and Domineering* (1988) — his Table III sequences,
+their period-5/saltus-1 structure, and the overheating bound from Appendix B.1 —
+and checks the results against the paper.
+
+```console
+$ python examples/berlekamp_1988.py
+  period 5, saltus 1: holds
+  x_1 is the only non-number: 1*
+  ok    G_2 = tiny-2
+  ok    G_3 = +-1 + 2*tiny-2
+```
+
+## Correctness
+
+The interesting values in this field are easy to get subtly wrong, so nothing
+here is trusted because it looks right. The test suite validates against
+**external** sources:
+
+- **CGSuite** — canonical forms, temperatures and means of Domineering 2×n
+  boards, generated by driving CGSuite 2.2 headlessly.
+- **Berlekamp (1988)**, *Blockbusting and Domineering*, Appendix B.1 — his
+  exact values for the 2-wide Domineering rectangles, `G₂ = tiny-2` and
+  `G₃ = ±1 + 2·tiny-2`.
+- **Wolfe**, via Guy's Problem 4 in *Games of No Chance* — the 4×5 board is `1`.
+- **Uiterwijk**, [arXiv:1305.3257](https://arxiv.org/pdf/1305.3257) — the
+  value of the 11×2 board.
+- **Closed forms** — Nim sums follow exclusive-or; Hackenbush strings give the
+  expected dyadic rationals; Cram values are nimbers.
+
+Plus internal laws that catch real bugs: `G + (−G) = 0`, transposing a
+Domineering board negates its value, `ish(G)` is *always* infinitesimal, and
+canonical form is idempotent.
+
+## Provenance
+
+Implemented clean-room from the mathematics — *Winning Ways*, Siegel's
+*Combinatorial Game Theory*, and Berlekamp (1988). CGSuite is GPL; its source
+was consulted **only** for the API needed to run it as a test oracle, and none
+of its implementation was used or ported. This library is MIT.
+
+## Limitations
+
+Honest about scope:
+
+- **Short games only.** No loopy games, stoppers, or `on`/`off`.
+- **No misère theory** and no misère quotients.
+- **Slower than CGSuite**, which is a JVM program with far more optimisation.
+  Expect exact Domineering values up to about 2×16 comfortably.
+- **The number-temperature convention** (a number with denominator `2**k` has
+  temperature `−1/2**k`) is checked against CGSuite for `0` and `1/2` only.
+
+## Licence
+
+MIT.

pycgt-0.1.0/pyproject.toml

@@ -0,0 +1,80 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pycgt"
+version = "0.1.0"
+description = "Combinatorial game theory in pure Python: exact canonical forms, thermography, and game values"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "nehalahmedshaikh" }]
+keywords = [
+    "combinatorial-game-theory",
+    "canonical-form",
+    "surreal-numbers",
+    "thermography",
+    "temperature",
+    "domineering",
+    "nim",
+    "partizan-games",
+    "exact-arithmetic",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Education",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Typing :: Typed",
+]
+# Intentionally empty and meant to stay that way: the library must run
+# unchanged under Pyodide, so it works in a browser and in notebooks.
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-cov>=4", "mypy>=1.8", "ruff>=0.3"]
+
+[project.urls]
+Homepage = "https://github.com/nehalahmedshaikh/pycgt"
+Repository = "https://github.com/nehalahmedshaikh/pycgt"
+Issues = "https://github.com/nehalahmedshaikh/pycgt/issues"
+Changelog = "https://github.com/nehalahmedshaikh/pycgt/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+pycgt = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "--strict-markers"
+markers = ["slow: takes more than a second to run"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src/pycgt"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B", "C4", "RUF"]
+ignore = [
+    # Single letters are the notation of the field: G, H, L, R, s, t, n.
+    "E741",
+    # __all__ is grouped by topic with comments, which is far more useful for
+    # a public API than alphabetical order.
+    "RUF022",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["E501"]

pycgt-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pycgt-0.1.0/src/pycgt/__init__.py

@@ -0,0 +1,130 @@
+"""pycgt: combinatorial game theory in pure Python.
+
+Short games are exact objects built from the empty game up, so nothing here
+approximates: two values are equal, or one is greater, or they are *confused*
+with each other. There is no tolerance to set and no rounding.
+
+    >>> from pycgt import parse, render
+    >>> render(parse("{1|-1}") + parse("{1|-1}"))
+    '0'
+    >>> from pycgt.rulesets import domineering
+    >>> render(domineering.rectangle(2, 4))
+    'Miny(2)'
+    >>> from pycgt import temperature
+    >>> temperature(domineering.rectangle(2, 3))
+    Fraction(5, 4)
+
+Every :class:`Game` returned by this package is in canonical form, so ``==``
+means value equality.
+"""
+
+from .game import (
+    ZERO,
+    Game,
+    Outcome,
+    Relation,
+    add,
+    birthday,
+    canonical,
+    compare,
+    confused,
+    equals,
+    game,
+    geq,
+    greater,
+    leq,
+    multiple,
+    negate,
+    outcome,
+)
+from .notation import parse, render
+from .reduced import is_reduced, ish, reduced_canonical_form
+from .stops import (
+    confusion_interval,
+    is_hot,
+    is_infinitesimal,
+    is_tepid,
+    left_stop,
+    number_part,
+    right_stop,
+    stops,
+)
+from .thermal import cool, heat, mean, overheat, temperature, thermograph
+from .values import (
+    DOWN,
+    STAR,
+    UP,
+    as_number,
+    integer,
+    is_number,
+    miny,
+    nimber,
+    number,
+    plus_minus,
+    simplest_between,
+    switch,
+    tiny,
+    up_multiple,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # core
+    "Game",
+    "Outcome",
+    "Relation",
+    "ZERO",
+    "game",
+    "canonical",
+    "add",
+    "negate",
+    "multiple",
+    "birthday",
+    # order
+    "geq",
+    "leq",
+    "equals",
+    "greater",
+    "confused",
+    "compare",
+    "outcome",
+    # numbers and named values
+    "number",
+    "integer",
+    "as_number",
+    "is_number",
+    "simplest_between",
+    "STAR",
+    "UP",
+    "DOWN",
+    "nimber",
+    "up_multiple",
+    "switch",
+    "plus_minus",
+    "tiny",
+    "miny",
+    # stops
+    "left_stop",
+    "right_stop",
+    "stops",
+    "confusion_interval",
+    "is_infinitesimal",
+    "is_hot",
+    "is_tepid",
+    "number_part",
+    # reduced canonical form
+    "reduced_canonical_form",
+    "ish",
+    "is_reduced",
+    # thermography
+    "heat",
+    "overheat",
+    "cool",
+    "temperature",
+    "mean",
+    "thermograph",
+    # notation
+    "render",
+    "parse",
+]