pycgt 0.1.0__py3-none-any.whl

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",
+]

pycgt/_piecewise.py

@@ -0,0 +1,208 @@
+"""Exact piecewise-linear functions on ``[0, inf)``.
+
+Internal support for :mod:`pycgt.thermal`. A thermograph boundary is a
+piecewise-linear function of the cooling temperature, so computing
+temperatures exactly means doing exact arithmetic on such functions: pointwise
+maxima and minima, shifts by ``+-t``, and analytic intersections.
+
+Breakpoints, values and slopes are all :class:`~fractions.Fraction`, so nothing
+here is approximate. Every operation preserves that.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from fractions import Fraction
+
+__all__ = ["PiecewiseLinear"]
+
+#: ``(start, value_at_start, slope_after_start)``. The final segment runs to
+#: infinity; the first must start at 0.
+Segment = tuple[Fraction, Fraction, Fraction]
+
+
+@dataclass(frozen=True, slots=True)
+class PiecewiseLinear:
+    """A continuous piecewise-linear function defined for ``t >= 0``."""
+
+    segments: tuple[Segment, ...]
+
+    def __post_init__(self) -> None:
+        if not self.segments:
+            raise ValueError("a piecewise-linear function needs a segment")
+        if self.segments[0][0] != 0:
+            raise ValueError("the first segment must start at t = 0")
+
+    # -- construction ----------------------------------------------------
+
+    @staticmethod
+    def constant(value: Fraction) -> PiecewiseLinear:
+        return PiecewiseLinear(((Fraction(0), Fraction(value), Fraction(0)),))
+
+    # -- evaluation ------------------------------------------------------
+
+    def _segment_at(self, t: Fraction) -> Segment:
+        chosen = self.segments[0]
+        for segment in self.segments:
+            if segment[0] <= t:
+                chosen = segment
+            else:
+                break
+        return chosen
+
+    def __call__(self, t: Fraction) -> Fraction:
+        start, value, slope = self._segment_at(t)
+        return value + slope * (t - start)
+
+    def slope_at(self, t: Fraction) -> Fraction:
+        """The slope just after ``t``."""
+        return self._segment_at(t)[2]
+
+    @property
+    def breakpoints(self) -> tuple[Fraction, ...]:
+        return tuple(s[0] for s in self.segments)
+
+    @property
+    def final_value(self) -> Fraction:
+        return self.segments[-1][1]
+
+    # -- shifts ----------------------------------------------------------
+
+    def minus_t(self) -> PiecewiseLinear:
+        """``f(t) - t``."""
+        return PiecewiseLinear(
+            tuple(
+                (start, value - start, slope - 1)
+                for start, value, slope in self.segments
+            )
+        )
+
+    def plus_t(self) -> PiecewiseLinear:
+        """``f(t) + t``."""
+        return PiecewiseLinear(
+            tuple(
+                (start, value + start, slope + 1)
+                for start, value, slope in self.segments
+            )
+        )
+
+    def negated(self) -> PiecewiseLinear:
+        return PiecewiseLinear(
+            tuple((start, -value, -slope) for start, value, slope in self.segments)
+        )
+
+    # -- combination -----------------------------------------------------
+
+    def _crossings_with(self, other: PiecewiseLinear) -> list[Fraction]:
+        """Where the two functions cross, as extra breakpoints."""
+        points = sorted(set(self.breakpoints) | set(other.breakpoints))
+        found: list[Fraction] = []
+        for i, a in enumerate(points):
+            b = points[i + 1] if i + 1 < len(points) else None
+            fa, fs = self(a), self.slope_at(a)
+            ga, gs = other(a), other.slope_at(a)
+            if fs == gs:
+                continue
+            t = a + (ga - fa) / (fs - gs)
+            if t > a and (b is None or t < b):
+                found.append(t)
+        return found
+
+    def _combine(
+        self, other: PiecewiseLinear, choose: Callable[[Fraction, Fraction], Fraction]
+    ) -> PiecewiseLinear:
+        points = sorted(
+            set(self.breakpoints)
+            | set(other.breakpoints)
+            | set(self._crossings_with(other))
+        )
+        segments: list[Segment] = []
+        for i, a in enumerate(points):
+            b = points[i + 1] if i + 1 < len(points) else None
+            # Decide which function wins on the open interval by probing
+            # inside it, which sidesteps ties at the endpoints.
+            probe = (a + b) / 2 if b is not None else a + 1
+            winner = self if choose(self(probe), other(probe)) == self(probe) else other
+            segments.append((a, winner(a), winner.slope_at(a)))
+        return PiecewiseLinear(_simplify(tuple(segments)))
+
+    def maximum(self, other: PiecewiseLinear) -> PiecewiseLinear:
+        return self._combine(other, max)
+
+    def minimum(self, other: PiecewiseLinear) -> PiecewiseLinear:
+        return self._combine(other, min)
+
+    def minus(self, other: PiecewiseLinear) -> PiecewiseLinear:
+        """``self - other``, exactly."""
+        points = sorted(set(self.breakpoints) | set(other.breakpoints))
+        segments = tuple(
+            (a, self(a) - other(a), self.slope_at(a) - other.slope_at(a))
+            for a in points
+        )
+        return PiecewiseLinear(_simplify(segments))
+
+    @staticmethod
+    def max_of(functions: Iterable[PiecewiseLinear]) -> PiecewiseLinear:
+        result: PiecewiseLinear | None = None
+        for f in functions:
+            result = f if result is None else result.maximum(f)
+        if result is None:
+            raise ValueError("max_of needs at least one function")
+        return result
+
+    @staticmethod
+    def min_of(functions: Iterable[PiecewiseLinear]) -> PiecewiseLinear:
+        result: PiecewiseLinear | None = None
+        for f in functions:
+            result = f if result is None else result.minimum(f)
+        if result is None:
+            raise ValueError("min_of needs at least one function")
+        return result
+
+    # -- freezing --------------------------------------------------------
+
+    def frozen_from(self, tau: Fraction, value: Fraction) -> PiecewiseLinear:
+        """Follow ``self`` below ``tau``, then hold ``value`` forever.
+
+        This is what forms the mast of a thermograph.
+        """
+        kept = [s for s in self.segments if s[0] < tau]
+        if not kept:
+            return PiecewiseLinear(((Fraction(0), value, Fraction(0)),))
+        return PiecewiseLinear(_simplify((*kept, (tau, value, Fraction(0)))))
+
+    def first_at_or_below(self, other: PiecewiseLinear) -> Fraction:
+        """The least ``t >= 0`` with ``self(t) <= other(t)``.
+
+        Used to find where a thermograph's two boundaries meet, which is the
+        temperature.
+        """
+        difference = self.minus(other)
+        for i, (start, value, slope) in enumerate(difference.segments):
+            if value <= 0:
+                return start
+            end = (
+                difference.segments[i + 1][0]
+                if i + 1 < len(difference.segments)
+                else None
+            )
+            if slope < 0:
+                crossing = start + value / -slope
+                if end is None or crossing <= end:
+                    return crossing
+        raise ArithmeticError("boundaries never meet; not a short game?")
+
+
+def _simplify(segments: tuple[Segment, ...]) -> tuple[Segment, ...]:
+    """Drop breakpoints that do not actually break anything."""
+    out: list[Segment] = []
+    for segment in segments:
+        if out:
+            prev_start, prev_value, prev_slope = out[-1]
+            start, value, slope = segment
+            continuous = prev_value + prev_slope * (start - prev_start) == value
+            if prev_slope == slope and continuous:
+                continue
+        out.append(segment)
+    return tuple(out)

pycgt/game.py

@@ -0,0 +1,341 @@
+"""Short games: the core object, its order, its arithmetic, and canonical form.
+
+A *short game* is a pair of finite sets of short games -- Left's options and
+Right's options -- and nothing else. Everything in combinatorial game theory is
+built from the empty game up, so nothing here is approximate: two games are
+equal, or one is greater, or they are *confused* with each other. There is no
+tolerance to set and no rounding to worry about.
+
+The load-bearing operation is :func:`canonical`. Two games of the same value
+have *identical* canonical forms, so once canonicalised, structural equality is
+value equality and comparison becomes a dictionary lookup. Without it, the
+values arising in real rulesets become unprintable and uncomparable within a
+few moves.
+
+**Invariant.** Every :class:`Game` returned by this package's public API is in
+canonical form. ``==`` therefore means value equality for such games. If you
+build a :class:`Game` by calling the constructor directly, that invariant is
+yours to maintain -- use :func:`game`, which canonicalises, or call
+:func:`equals` if unsure.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from enum import Enum
+from functools import cache
+
+__all__ = [
+    "ZERO",
+    "Game",
+    "Outcome",
+    "add",
+    "birthday",
+    "canonical",
+    "compare",
+    "confused",
+    "equals",
+    "game",
+    "geq",
+    "greater",
+    "leq",
+    "negate",
+    "outcome",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class Game:
+    """The game ``{left | right}``.
+
+    Instances are hashable and immutable. Prefer the :func:`game` factory,
+    which returns the canonical form.
+    """
+
+    left: frozenset[Game]
+    right: frozenset[Game]
+
+    # -- construction ----------------------------------------------------
+
+    @staticmethod
+    def of(left: Iterable[Game] = (), right: Iterable[Game] = ()) -> Game:
+        """The canonical game with the given options. Alias of :func:`game`."""
+        return game(left, right)
+
+    # -- arithmetic ------------------------------------------------------
+
+    def __neg__(self) -> Game:
+        return negate(self)
+
+    def __add__(self, other: Game) -> Game:
+        return add(self, other)
+
+    def __sub__(self, other: Game) -> Game:
+        return add(self, negate(other))
+
+    def __mul__(self, count: int) -> Game:
+        """``n`` copies summed. Not the Norton or ordinal product."""
+        if not isinstance(count, int):
+            return NotImplemented
+        return multiple(self, count)
+
+    __rmul__ = __mul__
+
+    # -- order -----------------------------------------------------------
+    # Games are only partially ordered, so <= and >= are genuine but < and >
+    # are deliberately *not* defined: "not (G <= H)" does not imply "G > H".
+    # Use compare() for the four-way answer.
+
+    def __le__(self, other: Game) -> bool:
+        return leq(self, other)
+
+    def __ge__(self, other: Game) -> bool:
+        return geq(self, other)
+
+    # -- display ---------------------------------------------------------
+
+    def __str__(self) -> str:
+        from .notation import render
+
+        return render(self)
+
+    def __repr__(self) -> str:
+        return f"Game({self})"
+
+    # -- convenience -----------------------------------------------------
+
+    @property
+    def canonical(self) -> Game:
+        """The canonical form. A no-op for games from the public API."""
+        return canonical(self)
+
+    @property
+    def birthday(self) -> int:
+        return birthday(self)
+
+    @property
+    def outcome(self) -> Outcome:
+        """Who wins under normal play."""
+        return outcome(self)
+
+    @property
+    def is_zero(self) -> bool:
+        return canonical(self) == ZERO
+
+
+def game(left: Iterable[Game] = (), right: Iterable[Game] = ()) -> Game:
+    """The canonical game ``{left | right}``."""
+    return canonical(Game(frozenset(left), frozenset(right)))
+
+
+#: The empty game. Second player wins.
+ZERO = Game(frozenset(), frozenset())
+
+
+# ---------------------------------------------------------------------------
+# Order
+# ---------------------------------------------------------------------------
+# Conway's definition: G >= H unless some H^L >= G, or some G^R <= H. The
+# recursion terminates because every option is strictly simpler than its
+# parent.
+
+_geq_cache: dict[tuple[Game, Game], bool] = {}
+
+
+def geq(g: Game, h: Game) -> bool:
+    """``g >= h``: Left wins ``g - h`` moving second."""
+    key = (g, h)
+    cached = _geq_cache.get(key)
+    if cached is not None:
+        return cached
+    result = not any(geq(hl, g) for hl in h.left) and not any(
+        geq(h, gr) for gr in g.right
+    )
+    _geq_cache[key] = result
+    return result
+
+
+def leq(g: Game, h: Game) -> bool:
+    """``g <= h``."""
+    return geq(h, g)
+
+
+def equals(g: Game, h: Game) -> bool:
+    """Value equality, whether or not either argument is canonical."""
+    return geq(g, h) and geq(h, g)
+
+
+def greater(g: Game, h: Game) -> bool:
+    """``g > h``: strictly greater."""
+    return geq(g, h) and not geq(h, g)
+
+
+def confused(g: Game, h: Game) -> bool:
+    """Neither ``>=`` nor ``<=``: whoever moves first in ``g - h`` wins."""
+    return not geq(g, h) and not geq(h, g)
+
+
+class Outcome(Enum):
+    """Who wins under normal play, where a player unable to move loses."""
+
+    LEFT = "Left"
+    RIGHT = "Right"
+    FIRST = "first player"
+    SECOND = "second player"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+def outcome(g: Game) -> Outcome:
+    """Classify ``g`` as positive, negative, zero, or confused with zero."""
+    positive, negative = geq(g, ZERO), geq(ZERO, g)
+    if positive and negative:
+        return Outcome.SECOND
+    if positive:
+        return Outcome.LEFT
+    if negative:
+        return Outcome.RIGHT
+    return Outcome.FIRST
+
+
+class Relation(Enum):
+    """The four possible relations between two games."""
+
+    EQUAL = "="
+    GREATER = ">"
+    LESS = "<"
+    CONFUSED = "||"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+def compare(g: Game, h: Game) -> Relation:
+    """The four-way comparison. Use this instead of ``<`` and ``>``."""
+    ge, le = geq(g, h), leq(g, h)
+    if ge and le:
+        return Relation.EQUAL
+    if ge:
+        return Relation.GREATER
+    if le:
+        return Relation.LESS
+    return Relation.CONFUSED
+
+
+# ---------------------------------------------------------------------------
+# Arithmetic
+# ---------------------------------------------------------------------------
+
+
+@cache
+def negate(g: Game) -> Game:
+    """``-g``: the same game with the players' roles exchanged."""
+    return Game(
+        frozenset(negate(r) for r in g.right),
+        frozenset(negate(l) for l in g.left),
+    )
+
+
+@cache
+def _add_raw(g: Game, h: Game) -> Game:
+    return Game(
+        frozenset(
+            [_add_raw(gl, h) for gl in g.left] + [_add_raw(g, hl) for hl in h.left]
+        ),
+        frozenset(
+            [_add_raw(gr, h) for gr in g.right] + [_add_raw(g, hr) for hr in h.right]
+        ),
+    )
+
+
+def add(g: Game, h: Game) -> Game:
+    """Disjunctive sum, canonicalised.
+
+    Canonicalising here rather than lazily matters: letting raw sums
+    accumulate makes the trees explode, and summing many components is the
+    common case.
+    """
+    return canonical(_add_raw(g, h))
+
+
+def multiple(g: Game, count: int) -> Game:
+    """``count`` copies of ``g`` summed, for any integer ``count``."""
+    total = ZERO
+    for _ in range(abs(count)):
+        total = add(total, g)
+    return negate(total) if count < 0 else total
+
+
+# ---------------------------------------------------------------------------
+# Canonical form
+# ---------------------------------------------------------------------------
+
+
+def _undominated_left(options: frozenset[Game]) -> frozenset[Game]:
+    """Left never needs an option that another of Left's options beats."""
+    return frozenset(
+        l for l in options if not any(o is not l and geq(o, l) for o in options)
+    )
+
+
+def _undominated_right(options: frozenset[Game]) -> frozenset[Game]:
+    return frozenset(
+        r for r in options if not any(o is not r and leq(o, r) for o in options)
+    )
+
+
+def _bypass_left(options: frozenset[Game], g: Game) -> frozenset[Game]:
+    """Replace each reversible Left option by what it reverses to.
+
+    If Left moves to ``G^L`` and Right can answer ``G^L -> G^{LR}`` with
+    ``G^{LR} <= G``, Right will always take that answer, so the detour is
+    worth nothing and Left's real choices are those available after it.
+    """
+    out: set[Game] = set()
+    for l in options:
+        reverser = next((lr for lr in l.right if leq(lr, g)), None)
+        if reverser is None:
+            out.add(l)
+        else:
+            out.update(reverser.left)
+    return frozenset(out)
+
+
+def _bypass_right(options: frozenset[Game], g: Game) -> frozenset[Game]:
+    out: set[Game] = set()
+    for r in options:
+        reverser = next((rl for rl in r.left if geq(rl, g)), None)
+        if reverser is None:
+            out.add(r)
+        else:
+            out.update(reverser.right)
+    return frozenset(out)
+
+
+@cache
+def canonical(g: Game) -> Game:
+    """The unique simplest game of the same value.
+
+    Options are canonicalised first, then dominated options are dropped and
+    reversible ones bypassed, repeatedly, until nothing changes. The result is
+    unique: two games are equal in value precisely when their canonical forms
+    are identical.
+    """
+    left = frozenset(canonical(x) for x in g.left)
+    right = frozenset(canonical(x) for x in g.right)
+    while True:
+        current = Game(left, right)
+        new_left = _undominated_left(_bypass_left(left, current))
+        new_right = _undominated_right(_bypass_right(right, current))
+        if new_left == left and new_right == right:
+            return current
+        left, right = new_left, new_right
+
+
+@cache
+def birthday(g: Game) -> int:
+    """The day ``g`` is born: 0 for the empty game, else one past its options."""
+    options = list(g.left) + list(g.right)
+    return 1 + max((birthday(x) for x in options), default=-1)