tstate 0.1.0__tar.gz

tstate-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/

tstate-0.1.0/LICENSE

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

tstate-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.5
+Name: tstate
+Version: 0.1.0
+Summary: Explicit-state reachability, closure, and attractor computation
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# tstate
+
+Explicit-state reachability, closure, and attractor computation for finite
+transition systems. Pure Python, no dependencies.
+
+## Install
+
+    pip install -e .
+
+## API
+
+    from tstate import TransitionSystem, make_quotient_system
+
+    edges = {"s0": ["s1"], "s1": ["s2"], "s2": ["s2"]}
+    ts = TransitionSystem(["s0"], lambda s: edges[s])
+
+    ts.reachable()
+    ts.is_closed(frozenset({"s2"}))
+    ts.closure_theorem()
+    ts.existential_attractor(frozenset({"s2"}))
+    ts.universal_attractor(frozenset({"s2"}))
+
+    ts = make_quotient_system(n=1000, k=3, local_succ=lambda v: {1} if v == 0 else {2})
+    len(ts.reachable())     # 501501
+
+## Scaling
+
+| n    | full (3^n) | quotient    |
+|------|------------|-------------|
+| 9    | 19,683     | —           |
+| 100  | 3^100      | 5,151       |
+| 1000 | 3^1000     | 501,501     |
+| 5000 | 3^5000     | 12,507,501  |
+
+## Test
+
+    pytest -q

tstate-0.1.0/README.md

@@ -0,0 +1,37 @@
+# tstate
+
+Explicit-state reachability, closure, and attractor computation for finite
+transition systems. Pure Python, no dependencies.
+
+## Install
+
+    pip install -e .
+
+## API
+
+    from tstate import TransitionSystem, make_quotient_system
+
+    edges = {"s0": ["s1"], "s1": ["s2"], "s2": ["s2"]}
+    ts = TransitionSystem(["s0"], lambda s: edges[s])
+
+    ts.reachable()
+    ts.is_closed(frozenset({"s2"}))
+    ts.closure_theorem()
+    ts.existential_attractor(frozenset({"s2"}))
+    ts.universal_attractor(frozenset({"s2"}))
+
+    ts = make_quotient_system(n=1000, k=3, local_succ=lambda v: {1} if v == 0 else {2})
+    len(ts.reachable())     # 501501
+
+## Scaling
+
+| n    | full (3^n) | quotient    |
+|------|------------|-------------|
+| 9    | 19,683     | —           |
+| 100  | 3^100      | 5,151       |
+| 1000 | 3^1000     | 501,501     |
+| 5000 | 3^5000     | 12,507,501  |
+
+## Test
+
+    pytest -q

tstate-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "tstate"
+version = "0.1.0"
+description = "Explicit-state reachability, closure, and attractor computation"
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tstate"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]
+ignore = ["E501", "UP046"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.coverage.run]
+source = ["tstate"]

tstate-0.1.0/src/tstate/__init__.py

@@ -0,0 +1,19 @@
+"""tstate — explicit-state reachability and attractor computation."""
+
+from tstate.core import (
+    TransitionSystem,
+    from_count_vector,
+    make_quotient_system,
+    make_system,
+    to_count_vector,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "TransitionSystem",
+    "from_count_vector",
+    "make_quotient_system",
+    "make_system",
+    "to_count_vector",
+    "__version__",
+]

tstate-0.1.0/src/tstate/core.py

@@ -0,0 +1,168 @@
+"""Reference implementation of transition-system closure concepts."""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Callable, Hashable, Iterable
+from itertools import product
+from typing import Generic, TypeVar
+
+S = TypeVar("S", bound=Hashable)
+
+
+class TransitionSystem(Generic[S]):
+    """A finite transition system (S, ->)."""
+
+    def __init__(
+        self,
+        init_states: Iterable[S],
+        succ: Callable[[S], Iterable[S]],
+    ) -> None:
+        self.init_states: frozenset[S] = frozenset(init_states)
+        self._succ = succ
+
+    def succ(self, s: S) -> frozenset[S]:
+        return frozenset(self._succ(s))
+
+    def post(self, X: frozenset[S]) -> frozenset[S]:
+        return frozenset(s2 for s in X for s2 in self.succ(s))
+
+    def pre(self, X: frozenset[S], universe: frozenset[S]) -> frozenset[S]:
+        return frozenset(s for s in universe if self.succ(s) & X)
+
+    def reachable(self) -> frozenset[S]:
+        visited: set[S] = set(self.init_states)
+        queue: deque[S] = deque(self.init_states)
+        while queue:
+            s = queue.popleft()
+            for s2 in self.succ(s):
+                if s2 not in visited:
+                    visited.add(s2)
+                    queue.append(s2)
+        return frozenset(visited)
+
+    def reachable_lfp(self) -> frozenset[S]:
+        X: frozenset[S] = frozenset()
+        while True:
+            nxt = self.init_states | self.post(X)
+            if nxt == X:
+                return X
+            X = nxt
+
+    def is_closed(self, X: frozenset[S]) -> bool:
+        return self.post(X) <= X
+
+    def closure_theorem(self) -> dict:
+        R = self.reachable()
+        contains_init = self.init_states <= R
+        closed = self.is_closed(R)
+        minimal = True
+        for s in R:
+            if s in self.init_states:
+                continue
+            candidate = R - {s}
+            if self.init_states <= candidate and self.is_closed(candidate):
+                minimal = False
+                break
+        return {
+            "reachable_size": len(R),
+            "contains_init": contains_init,
+            "closed": closed,
+            "minimal": minimal,
+            "theorem_holds": contains_init and closed and minimal,
+        }
+
+    def existential_attractor(self, A: frozenset[S]) -> frozenset[S]:
+        universe = self.reachable()
+        X: frozenset[S] = frozenset()
+        while True:
+            nxt = A | self.pre(X, universe)
+            if nxt == X:
+                return X
+            X = nxt
+
+    def universal_attractor(self, A: frozenset[S]) -> frozenset[S]:
+        universe = self.reachable()
+        X: frozenset[S] = frozenset()
+        while True:
+            nxt = A
+            for s in universe:
+                post_s = self.succ(s)
+                if post_s and post_s <= X:
+                    nxt = nxt | {s}
+            if nxt == X:
+                return X
+            X = nxt
+
+
+def make_system(
+    n: int,
+    k: int,
+    local_succ: Callable[[int], set[int]],
+    *,
+    async_update: bool = True,
+) -> TransitionSystem[tuple[int, ...]]:
+    init = (0,) * n
+
+    if async_update:
+
+        def succ(state: tuple[int, ...]) -> set[tuple[int, ...]]:
+            if len(state) != n or not all(0 <= v < k for v in state):
+                return set()
+            out: set[tuple[int, ...]] = set()
+            for i in range(n):
+                for new_v in local_succ(state[i]):
+                    if new_v == state[i]:
+                        continue
+                    s = list(state)
+                    s[i] = new_v
+                    out.add(tuple(s))
+            return out
+
+    else:
+
+        def succ(state: tuple[int, ...]) -> set[tuple[int, ...]]:
+            if len(state) != n or not all(0 <= v < k for v in state):
+                return set()
+            options = [sorted(local_succ(v)) for v in state]
+            return {tuple(p) for p in product(*options)}
+
+    return TransitionSystem([init], succ)
+
+
+def to_count_vector(state: tuple[int, ...], k: int) -> tuple[int, ...]:
+    counts = [0] * k
+    for v in state:
+        counts[v] += 1
+    return tuple(counts)
+
+
+def from_count_vector(cv: tuple[int, ...]) -> tuple[int, ...]:
+    out: list[int] = []
+    for v, c in enumerate(cv):
+        out.extend([v] * c)
+    return tuple(out)
+
+
+def make_quotient_system(
+    n: int,
+    k: int,
+    local_succ: Callable[[int], set[int]],
+) -> TransitionSystem[tuple[int, ...]]:
+    init_cv = (n,) + (0,) * (k - 1)
+
+    def cv_succ(cv: tuple[int, ...]) -> set[tuple[int, ...]]:
+        out: set[tuple[int, ...]] = set()
+        for v in range(k):
+            if cv[v] == 0:
+                continue
+            for new_v in local_succ(v):
+                if new_v == v:
+                    continue
+                nxt = list(cv)
+                nxt[v] -= 1
+                nxt[new_v] += 1
+                out.add(tuple(nxt))
+        return out
+
+    return TransitionSystem([init_cv], cv_succ)

tstate-0.1.0/tests/test_core.py

@@ -0,0 +1,113 @@
+"""Tests for reference/closure_reference.py."""
+
+from __future__ import annotations
+
+import pytest
+
+from tstate.core import (
+    TransitionSystem,
+    from_count_vector,
+    make_quotient_system,
+    make_system,
+    to_count_vector,
+)
+
+
+def _simple_chain() -> TransitionSystem[str]:
+    edges = {"s0": ["s1"], "s1": ["s2"], "s2": ["s2"]}
+    return TransitionSystem(["s0"], lambda s: edges[s])
+
+
+def test_reachable_chain() -> None:
+    assert _simple_chain().reachable() == frozenset({"s0", "s1", "s2"})
+
+
+def test_reachable_lfp_matches_bfs() -> None:
+    ts = _simple_chain()
+    assert ts.reachable_lfp() == ts.reachable()
+
+
+def test_is_closed() -> None:
+    ts = _simple_chain()
+    assert ts.is_closed(frozenset({"s0", "s1", "s2"}))
+    assert ts.is_closed(frozenset({"s2"}))
+    assert not ts.is_closed(frozenset({"s0", "s1"}))
+    assert not ts.is_closed(frozenset({"s0"}))
+
+
+def test_closure_theorem_chain() -> None:
+    r = _simple_chain().closure_theorem()
+    assert r["theorem_holds"]
+    assert r["reachable_size"] == 3
+
+
+def _branching() -> TransitionSystem[str]:
+    edges = {"s0": ["s0", "s1"], "s1": ["s2"], "s2": ["s2"]}
+    return TransitionSystem(["s0"], lambda s: edges[s])
+
+
+def test_existential_attractor_branching() -> None:
+    ts = _branching()
+    assert ts.existential_attractor(frozenset({"s2"})) == frozenset({"s0", "s1", "s2"})
+
+
+def test_universal_attractor_branching() -> None:
+    ts = _branching()
+    assert ts.universal_attractor(frozenset({"s2"})) == frozenset({"s1", "s2"})
+
+
+def test_universal_attractor_self() -> None:
+    ts = _branching()
+    assert ts.universal_attractor(frozenset({"s0"})) == frozenset({"s0"})
+
+
+def _k2(v: int) -> set[int]:
+    return {0, 1}
+
+
+def _k3_progress(v: int) -> set[int]:
+    return {1} if v == 0 else {2}
+
+
+def test_agents_3_reachable() -> None:
+    assert len(make_system(3, 2, _k2).reachable()) == 8
+
+
+def test_agents_3_closure_theorem() -> None:
+    assert make_system(3, 2, _k2).closure_theorem()["theorem_holds"]
+
+
+def test_agents_10_quotient() -> None:
+    ts = make_quotient_system(10, 3, _k3_progress)
+    R = ts.reachable()
+    assert ts.closure_theorem()["theorem_holds"]
+    assert len(R) == (10 + 1) * (10 + 2) // 2
+
+
+def test_agents_100_quotient() -> None:
+    ts = make_quotient_system(100, 3, _k3_progress)
+    assert ts.closure_theorem()["theorem_holds"]
+    assert len(ts.reachable()) == (100 + 1) * (100 + 2) // 2
+
+
+def test_agents_1000_quotient() -> None:
+    ts = make_quotient_system(1000, 3, _k3_progress)
+    assert len(ts.reachable()) == (1000 + 1) * (1000 + 2) // 2
+
+
+def test_quotient_matches_full_modulo_symmetry() -> None:
+    n, k = 4, 3
+    full = make_system(n, k, _k3_progress).reachable()
+    quot = make_quotient_system(n, k, _k3_progress).reachable()
+    full_cvs = {to_count_vector(s, k) for s in full}
+    assert full_cvs == quot
+
+
+def test_count_vector_roundtrip() -> None:
+    for state in [(0, 1, 2), (1, 1, 1), (2, 2, 0)]:
+        assert from_count_vector(to_count_vector(state, 3)) == tuple(sorted(state))
+
+
+def test_unknown_state_raises() -> None:
+    with pytest.raises(KeyError):
+        _simple_chain().succ("nonexistent")