rafkit 0.1.0__tar.gz → 0.2.0__tar.gz

{rafkit-0.1.0/src/rafkit.egg-info → rafkit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rafkit
-Version: 0.1.0
+Version: 0.2.0
 Summary: Autocatalytic (RAF) sets in catalytic reaction networks: maximal RAFs, irreducible cores, and Kauffman binary polymer models.
 Author: James P. Galasyn, Claude Théodore
 License: MIT
@@ -33,6 +33,7 @@ Dynamic: license-file
 [![PyPI](https://img.shields.io/pypi/v/rafkit.svg)](https://pypi.org/project/rafkit/)
 [![Python](https://img.shields.io/pypi/pyversions/rafkit.svg)](https://pypi.org/project/rafkit/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21954795.svg)](https://doi.org/10.5281/zenodo.21954795)
 
 Autocatalytic (RAF) sets in catalytic reaction networks — maximal RAFs, irreducible
 cores, Kauffman binary polymer models, and interoperability with
@@ -109,13 +110,40 @@ counted as **one** catalysed reaction, not two. Use `net.catalysis_level` — no
 | `irrraf_census` | how many *distinct* irreducible cores a network carries |
 | `exploitability` | share of RAF products contributing no catalysis back |
 | `is_food_catalysed` | whether a core runs on food catalysis alone, and so carries no heredity |
+| `core_raf` / `has_unique_irraf` | Huson, Xavier & Steel's polynomial test for a *unique* irreducible RAF |
+| `catalytically_reachable` | what can be made without any spontaneous reaction |
 | `binary_polymer` | Kauffman binary polymer generator, with optional cleavage |
 | `ReactionNetwork` | arbitrary catalytic reaction systems, same protocol |
 | `read_crs` / `write_crs` | CatReNet's CRS interchange format |
+| `simulate` | Gillespie direct method — watch subRAFs seed themselves into existence |
 
 Every algorithm carries hand-computed known-answer tests, because a RAF algorithm that
 is subtly wrong produces plausible numbers rather than errors.
 
+## Catalysis is a relation, not a list
+
+`catalysts[r]` is a set of **alternative catalyst sets**, following Huson, Xavier &
+Steel (2024). Any one set being fully present suffices, and each set is a conjunctive
+requirement:
+
+| `catalysts[r]` | meaning |
+|---|---|
+| `{{a}, {b}}` | *a* **or** *b* — the simple case, and what a flat list of catalysts meant |
+| `{{a, d}, {e}}` | (*a* **and** *d*) **or** *e* |
+| `{}` | **must** be catalysed, and nothing does: never in a RAF |
+| `{frozenset()}` | **may proceed uncatalysed**; always satisfied |
+
+The last two rows are a real distinction rather than a technicality — in the §2.4 system
+of that paper it decides which reactions can join an RAF — and a flat list collapses
+them. In CRS, a braced group is conjunctive: `[{a,d}, e]`, with `[]` and `[{}]` for the
+last two rows.
+
+Constructors still accept a plain iterable of molecules and normalise it, so simple
+systems stay simple to write.
+
+**Still not representable:** inhibition (Hordijk & Steel 2012, Part II), where a
+molecule can *prevent* a reaction.
+
 ## Notes on irreducible cores
 
 There may be **exponentially many** irreducible RAFs inside one maximal RAF, and
@@ -145,6 +173,13 @@ pytest -q
 Releases are documented in [CHANGELOG.md](CHANGELOG.md); the release procedure is
 [docs/RELEASING.md](docs/RELEASING.md).
 
+## Citing
+
+Cite the concept DOI [10.5281/zenodo.21954795](https://doi.org/10.5281/zenodo.21954795),
+which always resolves to the latest version; `CITATION.cff` also lists the per-version
+DOI. If you use the CatReNet interoperability or the validation fixture, please cite
+CatReNet too.
+
 ## References
 
 - Hordijk & Steel, "Detecting autocatalytic, self-sustaining sets in chemical reaction

{rafkit-0.1.0 → rafkit-0.2.0}/README.md

@@ -5,6 +5,7 @@
 [![PyPI](https://img.shields.io/pypi/v/rafkit.svg)](https://pypi.org/project/rafkit/)
 [![Python](https://img.shields.io/pypi/pyversions/rafkit.svg)](https://pypi.org/project/rafkit/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21954795.svg)](https://doi.org/10.5281/zenodo.21954795)
 
 Autocatalytic (RAF) sets in catalytic reaction networks — maximal RAFs, irreducible
 cores, Kauffman binary polymer models, and interoperability with
@@ -81,13 +82,40 @@ counted as **one** catalysed reaction, not two. Use `net.catalysis_level` — no
 | `irrraf_census` | how many *distinct* irreducible cores a network carries |
 | `exploitability` | share of RAF products contributing no catalysis back |
 | `is_food_catalysed` | whether a core runs on food catalysis alone, and so carries no heredity |
+| `core_raf` / `has_unique_irraf` | Huson, Xavier & Steel's polynomial test for a *unique* irreducible RAF |
+| `catalytically_reachable` | what can be made without any spontaneous reaction |
 | `binary_polymer` | Kauffman binary polymer generator, with optional cleavage |
 | `ReactionNetwork` | arbitrary catalytic reaction systems, same protocol |
 | `read_crs` / `write_crs` | CatReNet's CRS interchange format |
+| `simulate` | Gillespie direct method — watch subRAFs seed themselves into existence |
 
 Every algorithm carries hand-computed known-answer tests, because a RAF algorithm that
 is subtly wrong produces plausible numbers rather than errors.
 
+## Catalysis is a relation, not a list
+
+`catalysts[r]` is a set of **alternative catalyst sets**, following Huson, Xavier &
+Steel (2024). Any one set being fully present suffices, and each set is a conjunctive
+requirement:
+
+| `catalysts[r]` | meaning |
+|---|---|
+| `{{a}, {b}}` | *a* **or** *b* — the simple case, and what a flat list of catalysts meant |
+| `{{a, d}, {e}}` | (*a* **and** *d*) **or** *e* |
+| `{}` | **must** be catalysed, and nothing does: never in a RAF |
+| `{frozenset()}` | **may proceed uncatalysed**; always satisfied |
+
+The last two rows are a real distinction rather than a technicality — in the §2.4 system
+of that paper it decides which reactions can join an RAF — and a flat list collapses
+them. In CRS, a braced group is conjunctive: `[{a,d}, e]`, with `[]` and `[{}]` for the
+last two rows.
+
+Constructors still accept a plain iterable of molecules and normalise it, so simple
+systems stay simple to write.
+
+**Still not representable:** inhibition (Hordijk & Steel 2012, Part II), where a
+molecule can *prevent* a reaction.
+
 ## Notes on irreducible cores
 
 There may be **exponentially many** irreducible RAFs inside one maximal RAF, and
@@ -117,6 +145,13 @@ pytest -q
 Releases are documented in [CHANGELOG.md](CHANGELOG.md); the release procedure is
 [docs/RELEASING.md](docs/RELEASING.md).
 
+## Citing
+
+Cite the concept DOI [10.5281/zenodo.21954795](https://doi.org/10.5281/zenodo.21954795),
+which always resolves to the latest version; `CITATION.cff` also lists the per-version
+DOI. If you use the CatReNet interoperability or the validation fixture, please cite
+CatReNet too.
+
 ## References
 
 - Hordijk & Steel, "Detecting autocatalytic, self-sustaining sets in chemical reaction

{rafkit-0.1.0 → rafkit-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rafkit"
-version = "0.1.0"
+version = "0.2.0"
 description = "Autocatalytic (RAF) sets in catalytic reaction networks: maximal RAFs, irreducible cores, and Kauffman binary polymer models."
 readme = "README.md"
 license = { text = "MIT" }

{rafkit-0.1.0 → rafkit-0.2.0}/src/rafkit/__init__.py

@@ -2,7 +2,8 @@
 
 A small, dependency-light implementation of RAF theory (Hordijk & Steel 2004):
 maximal RAFs, the self-referential ("strictly autocatalytic") variant, irreducible
-RAF sampling, and Kauffman's binary polymer model as a generator.
+RAF sampling, Kauffman's binary polymer model as a generator, and stochastic simulation
+of a network so that subRAFs can be watched seeding themselves into existence.
 
 Every algorithm here is written from the published papers and carries hand-computed
 known-answer tests, because a RAF algorithm that is subtly wrong produces plausible
@@ -12,18 +13,24 @@ See the README for the calibration against Steel, Hordijk & Smith (2012) and for
 CatReNet interoperability.
 """
 from rafkit.binary_polymer import BinaryPolymerNetwork, binary_polymer
+from rafkit.catalysis import catalysing_molecules, is_catalysed, normalise
 from rafkit.crs import parse_crs, read_crs, to_crs, write_crs
+from rafkit.gillespie import Trajectory, propensities, simulate
 from rafkit.network import ReactionNetwork
 from rafkit.raf import (
-    RafResult, catrenet_strictly_autocatalytic, exploitability, irrraf_census,
-    is_food_catalysed, max_raf, max_raf_strict, sample_irrraf,
+    RafResult, catrenet_strictly_autocatalytic, core_raf, exploitability,
+    has_unique_irraf, irrraf_census, is_food_catalysed, max_raf, max_raf_strict,
+    sample_irrraf,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 __all__ = [
     "BinaryPolymerNetwork", "binary_polymer", "ReactionNetwork",
     "RafResult", "max_raf", "max_raf_strict", "sample_irrraf", "irrraf_census",
     "exploitability", "is_food_catalysed", "catrenet_strictly_autocatalytic",
+    "core_raf", "has_unique_irraf",
+    "is_catalysed", "catalysing_molecules", "normalise",
     "parse_crs", "read_crs", "to_crs", "write_crs",
+    "simulate", "propensities", "Trajectory",
 ]

{rafkit-0.1.0 → rafkit-0.2.0}/src/rafkit/binary_polymer.py

@@ -44,6 +44,8 @@ from typing import Iterator
 
 import numpy as np
 
+from rafkit.catalysis import normalise
+
 
 @dataclass(frozen=True)
 class BinaryPolymerNetwork:
@@ -66,6 +68,8 @@ class BinaryPolymerNetwork:
     directions: tuple[int, ...] = ()
 
     def __post_init__(self):
+        object.__setattr__(self, "catalysts",
+                           tuple(normalise(c) for c in self.catalysts))
         if not self.directions:                      # default: all ligations
             object.__setattr__(self, "directions", (1,) * len(self.reactions))
         elif len(self.directions) != len(self.reactions):

rafkit-0.2.0/src/rafkit/catalysis.py

@@ -0,0 +1,78 @@
+"""The catalysis relation χ, and the one predicate everything else is built on.
+
+Huson, Xavier & Steel (2024) treat catalysis as a relation between **sets** of molecules
+and reactions: reaction ``r`` proceeds when *some* catalyst set ``U`` in ``chi(r)`` is
+entirely available. That single structure expresses three things a flat set of catalysts
+cannot:
+
+===========================  ============================================================
+``chi(r)``                   meaning
+===========================  ============================================================
+``{{a}, {b}}``               *a* **or** *b* -- the simple, disjunctive case
+``{{a, d}, {e}}``            (*a* **and** *d*) **or** *e* -- conjunctive requirements
+``{}`` (no sets at all)      **must** be catalysed, and nothing catalyses it: never in a RAF
+``{frozenset()}``            **may proceed uncatalysed**; always satisfied
+===========================  ============================================================
+
+The last two are a genuine distinction rather than a technicality -- in their §2.4 system
+it is what separates a reaction that can join an RAF from one that cannot -- and writing
+catalysts as a flat set collapses them.
+
+`is_catalysed` handles all four rows without special-casing, because ``any()`` over no
+sets is False and the empty set is a subset of everything.
+"""
+from __future__ import annotations
+
+from typing import Iterable
+
+CatalystSets = frozenset[frozenset[int]]
+
+
+def normalise(spec) -> CatalystSets:
+    """Accept either the simple or the general form and return the general one.
+
+    A flat iterable of molecule indices -- the form used everywhere before conjunctive
+    catalysis existed, and still the right one to write by hand for simple systems --
+    becomes one singleton set per molecule, which is exactly equivalent.
+    """
+    if spec is None:
+        return frozenset()
+    out = []
+    for item in spec:
+        if isinstance(item, (frozenset, set, tuple, list)):
+            out.append(frozenset(int(x) for x in item))
+        else:
+            out.append(frozenset({int(item)}))
+    return frozenset(out)
+
+
+def is_catalysed(chi: CatalystSets, available: Iterable[int]) -> bool:
+    """Whether some catalyst set of a reaction is fully present.
+
+    Note the two edge cases fall out rather than being handled: with no catalyst sets
+    `any()` is False, so the reaction can never run; with the empty set present,
+    ``frozenset() <= available`` is True, so it always can.
+    """
+    avail = available if isinstance(available, (set, frozenset)) else frozenset(available)
+    return any(U <= avail for U in chi)
+
+
+def catalysing_molecules(chi: CatalystSets) -> frozenset[int]:
+    """Every molecule that appears in any catalyst set.
+
+    The right notion of "x catalyses r" when catalysis is conjunctive: x may be
+    necessary without being sufficient, and it still counts as catalysing.
+    """
+    return frozenset().union(*chi) if chi else frozenset()
+
+
+def requires_non_food(chi: CatalystSets, available: Iterable[int], food) -> bool:
+    """Whether some *satisfiable* catalyst set is not contained in the food set.
+
+    This is the strictly-autocatalytic condition of Huson, Xavier & Steel (2024) §3.1
+    stated exactly: ``U subset-of cl(F)`` and ``U not-subset-of F``. Under simple
+    catalysis it reduces to "has a catalyst that is a non-food product", which is what
+    `max_raf_strict` meant before this module existed.
+    """
+    avail = available if isinstance(available, (set, frozenset)) else frozenset(available)
+    return any(U <= avail and not U <= food for U in chi)

{rafkit-0.1.0 → rafkit-0.2.0}/src/rafkit/crs.py

@@ -14,7 +14,13 @@ The format is a food line and one line per reaction::
     r2 : ab [aa] => abab
 
 `[...]` lists catalysts, `<->` marks a reversible reaction and `=>` (or `->`) an
-irreversible one. A reversible reaction is read as **two** reactions, forward and
+irreversible one.
+
+Catalysts are alternatives, any one of which suffices. A braced group is a
+**conjunctive** requirement -- `[{a,d}, e]` means *a and d together*, or *e* -- which
+is the notation Huson, Xavier & Steel (2024) use. Two edge cases carry meaning and are
+not interchangeable: `[]` means the reaction **must** be catalysed and nothing does so,
+while `[{}]` means it **may proceed uncatalysed**. A reversible reaction is read as **two** reactions, forward and
 reverse, sharing a catalyst set -- which is the reading its own generator uses.
 
 `X + X -> Y` is written `X ... -> Y`, with the repeated reactant collapsed. Since
@@ -39,6 +45,20 @@ def _split_list(text: str) -> list[str]:
     return [s for s in (t.strip() for t in re.split(r"[,+]", text)) if s]
 
 
+def _parse_catalysts(text: str) -> list[list[str]]:
+    """Parse a catalyst list into alternative sets, honouring braced conjunctions.
+
+    Splitting on commas alone is wrong the moment a braced group appears -- `{a,d}`
+    would become `{a` and `d}` -- so groups are pulled out first.
+    """
+    groups, rest = [], text
+    for m in re.finditer(r"\{([^}]*)\}", text):
+        groups.append(_split_list(m.group(1)))     # may be empty: {} means "uncatalysed"
+    rest = re.sub(r"\{[^}]*\}", " ", text)
+    groups += [[name] for name in _split_list(rest)]
+    return groups
+
+
 def parse_crs(text: str) -> ReactionNetwork:
     """Parse CRS text into a `ReactionNetwork`."""
     food_names: list[str] = []
@@ -56,11 +76,11 @@ def parse_crs(text: str) -> ReactionNetwork:
             continue
         name, body = m.group("name"), m.group("body")
 
-        cats: list[str] = []
+        cats: list[list[str]] = []
         if "[" in body:
             pre, rest = body.split("[", 1)
             inside, post = rest.split("]", 1)
-            cats = _split_list(inside)
+            cats = _parse_catalysts(inside)
             body = pre + " " + post
 
         arrow = _ARROW.search(body)
@@ -75,12 +95,12 @@ def parse_crs(text: str) -> ReactionNetwork:
     for n in food_names:
         index.setdefault(n, len(index))
     for _, lhs, rhs, cats, _ in parsed:
-        for n in (*lhs, *rhs, *cats):
+        for n in (*lhs, *rhs, *(x for g in cats for x in g)):
             index.setdefault(n, len(index))
 
     pairs, catalysts, names = [], [], []
     for name, lhs, rhs, cats, reversible in parsed:
-        cat = frozenset(index[c] for c in cats)
+        cat = frozenset(frozenset(index[c] for c in g) for g in cats)
         fwd = (tuple(index[x] for x in lhs), tuple(index[x] for x in rhs))
         pairs.append(fwd); catalysts.append(cat); names.append(name)
         if reversible:
@@ -119,12 +139,21 @@ def to_crs(net, comment: str = "") -> str:
     for r in range(net.n_reactions):
         lhs = " + ".join(dict.fromkeys(name(x) for x in net.reactants(r)))
         rhs = " + ".join(dict.fromkeys(name(x) for x in net.products(r)))
-        cats = ",".join(sorted(name(c) for c in net.catalysts[r]))
+        cats = _format_catalysts(net, r)
         out.append(f"{names[r]} : {lhs} [{cats}] => {rhs}")
     out.append("")
     return "\n".join(out)
 
 
+def _format_catalysts(net, r: int) -> str:
+    """Render a reaction's catalyst sets, using braces only where they are needed."""
+    parts = []
+    for U in sorted(net.catalysts[r], key=lambda u: sorted(u)):
+        names = sorted(net.molecules[c] for c in U)
+        parts.append(names[0] if len(names) == 1 else "{" + ",".join(names) + "}")
+    return ",".join(parts)
+
+
 def write_crs(net, path: str | Path, comment: str = "") -> None:
     """Write a network to a CRS file."""
     Path(path).write_text(to_crs(net, comment))

rafkit-0.2.0/src/rafkit/gillespie.py

@@ -0,0 +1,196 @@
+"""Stochastic simulation of a catalytic reaction network (Gillespie direct method).
+
+The point of this module is the one thing the rest of this library cannot express:
+**a subRAF has to be seeded before it can run.** A reaction catalysed by its own
+product cannot start until that product appears by an *uncatalysed* event, so a maximal
+RAF does not switch on -- it assembles as an order-dependent sequence of rare events.
+That is Hordijk & Steel, "Autocatalytic sets extended: dynamics, inhibition, and a
+generalization" (*J. Syst. Chem.* 3, 5, 2012), and `examples/` reproduces it.
+
+Everything here is deliberately small. Rates are mass-action with unit kinetic constants,
+because the published reference assigns no others and inventing them would make the
+reproduction unfalsifiable. The one non-unit constant is the **uncatalysed rate
+reduction factor**, which is the mechanism under test.
+
+Conventions, all inherited from the reference rather than chosen here:
+
+* a reaction whose catalyst is absent still proceeds, at ``1 / uncatalysed_factor``;
+* food molecules are replenished when they fall below ``food_floor``;
+* a ligation ``a + b -> ab`` with ``a == b`` takes the pair count ``n(n-1)/2``, not ``n^2``.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from rafkit.catalysis import is_catalysed
+
+UNCATALYSED_FACTOR = 20.0   # Hordijk & Steel (2012): "a small reduction factor of 20"
+FOOD_FLOOR = 5              # "replenished when they fall below a concentration of five"
+
+
+@dataclass
+class Trajectory:
+    """Recorded history of one run."""
+
+    times: np.ndarray                    # (n_samples,)
+    counts: np.ndarray                   # (n_samples, n_molecules)
+    molecules: tuple[str, ...]
+    first_fired: dict[int, float] = field(default_factory=dict)
+    """Reaction index -> time it first fired, in either direction."""
+    first_uncatalysed: dict[int, float] = field(default_factory=dict)
+    """Reaction index -> time it first fired *without* its catalyst present.
+
+    This is the seeding record, and the reason the module exists: a subRAF that is
+    catalysed only by its own products appears here before it appears anywhere else.
+    """
+    first_appearance: dict[int, float] = field(default_factory=dict)
+    """Molecule index -> time it first existed, at EVENT resolution.
+
+    Deliberately not read off `counts`, which is sampled every `sample_every` events
+    and therefore aliases any species that is produced and consumed between samples.
+    An early version of this module inferred appearance order from the samples and
+    reported a molecule appearing before its own reactant.
+    """
+
+    def of(self, name: str) -> np.ndarray:
+        """Count trace for a molecule, by name."""
+        return self.counts[:, self.molecules.index(name)]
+
+    def first_seen(self, name: str) -> float | None:
+        """When a molecule first existed, at event resolution; None if it never did."""
+        return self.first_appearance.get(self.molecules.index(name))
+
+
+def _pair_count(counts: np.ndarray, reactants: tuple[int, ...]) -> float:
+    """Number of distinct reactant combinations available.
+
+    Distinct species multiply; a species reacting with itself takes n(n-1)/2, which is
+    the standard mass-action combinatorial factor and not merely n^2 -- a molecule
+    cannot react with itself.
+    """
+    if len(reactants) == 1:
+        return float(counts[reactants[0]])
+    a, b = reactants
+    if a == b:
+        n = counts[a]
+        return float(n * (n - 1) / 2)
+    return float(counts[a] * counts[b])
+
+
+def propensities(net, counts: np.ndarray, *,
+                 uncatalysed_factor: float = UNCATALYSED_FACTOR,
+                 reactions=None) -> np.ndarray:
+    """Propensity of every reaction under the current counts.
+
+    A reaction with at least one catalyst present runs at the full rate; one with none
+    runs at ``1 / uncatalysed_factor`` of it. That difference is the whole mechanism:
+    it makes seeding rare but not impossible.
+
+    `reactions` restricts which reactions may fire. **This is a fidelity requirement,
+    not a convenience.** Hordijk & Steel study "the molecular flow on this maximal RAF";
+    simulating the entire generated network instead lets any reaction fire uncatalysed,
+    so species arrive by routes outside the set under study and the seeding sequence the
+    experiment exists to observe is destroyed. An earlier version of this module did
+    exactly that, and produced a molecule before the only reaction that makes it.
+    """
+    out = np.zeros(net.n_reactions)
+    allowed = range(net.n_reactions) if reactions is None else reactions
+    present = frozenset(np.flatnonzero(counts).tolist())
+    for r in allowed:
+        combos = _pair_count(counts, net.reactants(r))
+        if combos <= 0:
+            continue
+        catalysed = is_catalysed(net.catalysts[r], present)
+        out[r] = combos if catalysed else combos / uncatalysed_factor
+    return out
+
+
+def simulate(net, *, n_events: int = 25_000, rng=None,
+             uncatalysed_factor: float = UNCATALYSED_FACTOR,
+             food_floor: int = FOOD_FLOOR, initial_food: int | None = None,
+             sample_every: int = 25, reactions=None) -> Trajectory:
+    """Run the direct method for `n_events` reaction events.
+
+    Starts from food only, which is the point: everything else has to be made, and the
+    parts of the network that catalyse their own production have to be seeded by an
+    uncatalysed event first.
+
+    `reactions` restricts the reaction set -- pass a maximal RAF to reproduce the
+    published experiment; see `propensities` for why the default of "everything" is
+    the wrong choice for that purpose.
+    """
+    rng = rng if rng is not None else np.random.default_rng()
+    counts = np.zeros(net.n_molecules, dtype=np.int64)
+    food = np.array(sorted(net.food), dtype=int)
+    counts[food] = initial_food if initial_food is not None else food_floor
+
+    times, samples = [0.0], [counts.copy()]
+    first_fired: dict[int, float] = {}
+    first_uncat: dict[int, float] = {}
+    first_seen: dict[int, float] = {int(f): 0.0 for f in food}
+    t = 0.0
+
+    for step in range(n_events):
+        a = propensities(net, counts, uncatalysed_factor=uncatalysed_factor,
+                         reactions=reactions)
+        a0 = a.sum()
+        if a0 <= 0:
+            break                                   # nothing can fire; state is dead
+        t += float(rng.exponential(1.0 / a0))
+        r = int(rng.choice(net.n_reactions, p=a / a0))
+
+        if r not in first_fired:
+            first_fired[r] = t
+        if r not in first_uncat and not is_catalysed(
+                net.catalysts[r], frozenset(np.flatnonzero(counts).tolist())):
+            first_uncat[r] = t
+
+        for x in net.reactants(r):
+            counts[x] -= 1
+        for x in net.products(r):
+            counts[x] += 1
+            first_seen.setdefault(int(x), t)
+        counts[food] = np.maximum(counts[food], food_floor)   # replenish
+
+        if (step + 1) % sample_every == 0:
+            times.append(t)
+            samples.append(counts.copy())
+
+    return Trajectory(times=np.array(times), counts=np.array(samples),
+                      molecules=net.molecules, first_fired=first_fired,
+                      first_uncatalysed=first_uncat, first_appearance=first_seen)
+
+
+def catalytically_reachable(net, reactions=None) -> frozenset[int]:
+    """Molecules obtainable using **only catalysed firings** -- no seeding required.
+
+    Everything outside this set needs at least one uncatalysed (spontaneous) reaction
+    before it can exist, which is what makes the assembly of a maximal RAF an
+    order-dependent sequence of rare events rather than a switch.
+
+    It is a **least fixpoint**, and the obvious cheaper definition is wrong: taking only
+    the reactions with a *food* catalyst under-counts, because a reaction whose catalyst
+    is itself produced by the always-on part becomes catalysed later without ever needing
+    a seed. Iterating to a fixpoint is what closes that gap -- checked against simulation
+    on twelve networks, where the cheaper version fails on three of them and this does
+    not.
+
+    Static counterpart of `Trajectory.first_uncatalysed`: this predicts *which* molecules
+    require a seeding event, the trajectory records *when* one happened.
+    """
+    from rafkit.raf import _closure
+
+    allowed = frozenset(range(net.n_reactions) if reactions is None else reactions)
+    avail = frozenset(net.food)
+    while True:
+        enabled = frozenset(
+            r for r in allowed
+            if all(x in avail for x in net.reactants(r))
+            and is_catalysed(net.catalysts[r], avail)
+        )
+        nxt = _closure(net, enabled)
+        if nxt == avail:
+            return avail
+        avail = nxt

{rafkit-0.1.0 → rafkit-0.2.0}/src/rafkit/network.py

@@ -24,6 +24,8 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
+from rafkit.catalysis import normalise
+
 
 @dataclass(frozen=True)
 class ReactionNetwork:
@@ -43,6 +45,8 @@ class ReactionNetwork:
     names: tuple[str, ...] = ()
 
     def __post_init__(self):
+        object.__setattr__(self, "catalysts",
+                           tuple(normalise(c) for c in self.catalysts))
         if len(self.catalysts) != len(self.reaction_pairs):
             raise ValueError(
                 f"{len(self.catalysts)} catalyst sets for "

{rafkit-0.1.0 → rafkit-0.2.0}/src/rafkit/raf.py

@@ -28,6 +28,8 @@ from __future__ import annotations
 from dataclasses import dataclass
 
 from rafkit.binary_polymer import BinaryPolymerNetwork
+from rafkit.catalysis import (catalysing_molecules, is_catalysed,
+                              requires_non_food)
 
 
 @dataclass(frozen=True)
@@ -80,7 +82,8 @@ def max_raf(net: BinaryPolymerNetwork) -> RafResult:
         have = _closure(net, current)
         keep = frozenset(
             r for r in current
-            if all(x in have for x in net.reactants(r)) and (net.catalysts[r] & have)
+            if all(x in have for x in net.reactants(r))
+            and is_catalysed(net.catalysts[r], have)
         )
         if keep == current:
             return RafResult(reactions=current, closure=have, n_rounds=rounds)
@@ -109,7 +112,7 @@ def exploitability(net: BinaryPolymerNetwork, raf: RafResult) -> dict:
     reactants_in_raf = set()
     for r in raf.reactions:
         reactants_in_raf.update(net.reactants(r))
-        catalyses_in_raf |= (net.catalysts[r] & products)
+        catalyses_in_raf |= (catalysing_molecules(net.catalysts[r]) & products)
 
     strict = products - catalyses_in_raf
     unused = strict - reactants_in_raf
@@ -120,7 +123,8 @@ def exploitability(net: BinaryPolymerNetwork, raf: RafResult) -> dict:
     for m in strict:
         survives = frozenset(
             r for r in raf.reactions
-            if m not in net.reactions[r] and net.catalysts[r] & (raf.closure - {m})
+            if m not in net.reactions[r]
+            and is_catalysed(net.catalysts[r], raf.closure - {m})
         )
         sub = RafResult(reactions=survives, closure=_closure(net, survives),
                         n_rounds=0)
@@ -151,10 +155,11 @@ def _refine(net: BinaryPolymerNetwork, reactions: frozenset[int],
     current = reactions
     while True:
         have = _closure(net, current)
-        pool = have - net.food if strict else have
         keep = frozenset(
             r for r in current
-            if all(x in have for x in net.reactants(r)) and (net.catalysts[r] & pool)
+            if all(x in have for x in net.reactants(r))
+            and (requires_non_food(net.catalysts[r], have, net.food) if strict
+                 else is_catalysed(net.catalysts[r], have))
         )
         if keep == current:
             return current
@@ -271,7 +276,7 @@ def is_food_catalysed(net: BinaryPolymerNetwork, core: frozenset[int]) -> bool:
     """
     if not core:
         return False
-    return all(net.catalysts[r] & net.food for r in core)
+    return all(is_catalysed(net.catalysts[r], net.food) for r in core)
 
 
 def catrenet_strictly_autocatalytic(net, raf: RafResult | None = None) -> frozenset[int]:
@@ -296,5 +301,34 @@ def catrenet_strictly_autocatalytic(net, raf: RafResult | None = None) -> frozen
         raf = max_raf(net)
     if raf.is_empty:
         return frozenset()
-    pool = raf.closure - net.food
-    return frozenset(r for r in raf.reactions if net.catalysts[r] & pool)
+    return frozenset(r for r in raf.reactions
+                     if requires_non_food(net.catalysts[r], raf.closure, net.food))
+
+
+def core_raf(net, reactions=None) -> frozenset[int]:
+    """`Core(Q)`: the reactions whose removal collapses the whole set.
+
+    Defined by Huson, Xavier & Steel (2024) as
+    ``Core(Q) = {r in R : phi(R \\ {r}) = empty}``. Their result: **this set is an RAF
+    if and only if the system has a unique irreducible RAF**, and when it is, it *is*
+    that iRAF. `has_unique_irraf` is the usable form of that test.
+    """
+    allowed = frozenset(range(net.n_reactions) if reactions is None else reactions)
+    return frozenset(r for r in allowed if not _refine(net, allowed - {r}))
+
+
+def has_unique_irraf(net, reactions=None) -> bool:
+    """Whether the system has exactly one irreducible RAF, in polynomial time.
+
+    Deciding how *many* iRAFs there are is hard in general -- there may be
+    exponentially many, and finding the smallest is NP-hard (Steel, Hordijk & Smith
+    2012) -- but the *unique* case is cheap, which is the point of `core_raf`.
+
+    Returns False when there is no RAF at all: no iRAF is not one iRAF.
+    """
+    allowed = frozenset(range(net.n_reactions) if reactions is None else reactions)
+    maximal = _refine(net, allowed)
+    if not maximal:
+        return False
+    core = core_raf(net, allowed)
+    return bool(core) and _refine(net, core) == core

{rafkit-0.1.0 → rafkit-0.2.0/src/rafkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rafkit
-Version: 0.1.0
+Version: 0.2.0
 Summary: Autocatalytic (RAF) sets in catalytic reaction networks: maximal RAFs, irreducible cores, and Kauffman binary polymer models.
 Author: James P. Galasyn, Claude Théodore
 License: MIT
@@ -33,6 +33,7 @@ Dynamic: license-file
 [![PyPI](https://img.shields.io/pypi/v/rafkit.svg)](https://pypi.org/project/rafkit/)
 [![Python](https://img.shields.io/pypi/pyversions/rafkit.svg)](https://pypi.org/project/rafkit/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21954795.svg)](https://doi.org/10.5281/zenodo.21954795)
 
 Autocatalytic (RAF) sets in catalytic reaction networks — maximal RAFs, irreducible
 cores, Kauffman binary polymer models, and interoperability with
@@ -109,13 +110,40 @@ counted as **one** catalysed reaction, not two. Use `net.catalysis_level` — no
 | `irrraf_census` | how many *distinct* irreducible cores a network carries |
 | `exploitability` | share of RAF products contributing no catalysis back |
 | `is_food_catalysed` | whether a core runs on food catalysis alone, and so carries no heredity |
+| `core_raf` / `has_unique_irraf` | Huson, Xavier & Steel's polynomial test for a *unique* irreducible RAF |
+| `catalytically_reachable` | what can be made without any spontaneous reaction |
 | `binary_polymer` | Kauffman binary polymer generator, with optional cleavage |
 | `ReactionNetwork` | arbitrary catalytic reaction systems, same protocol |
 | `read_crs` / `write_crs` | CatReNet's CRS interchange format |
+| `simulate` | Gillespie direct method — watch subRAFs seed themselves into existence |
 
 Every algorithm carries hand-computed known-answer tests, because a RAF algorithm that
 is subtly wrong produces plausible numbers rather than errors.
 
+## Catalysis is a relation, not a list
+
+`catalysts[r]` is a set of **alternative catalyst sets**, following Huson, Xavier &
+Steel (2024). Any one set being fully present suffices, and each set is a conjunctive
+requirement:
+
+| `catalysts[r]` | meaning |
+|---|---|
+| `{{a}, {b}}` | *a* **or** *b* — the simple case, and what a flat list of catalysts meant |
+| `{{a, d}, {e}}` | (*a* **and** *d*) **or** *e* |
+| `{}` | **must** be catalysed, and nothing does: never in a RAF |
+| `{frozenset()}` | **may proceed uncatalysed**; always satisfied |
+
+The last two rows are a real distinction rather than a technicality — in the §2.4 system
+of that paper it decides which reactions can join an RAF — and a flat list collapses
+them. In CRS, a braced group is conjunctive: `[{a,d}, e]`, with `[]` and `[{}]` for the
+last two rows.
+
+Constructors still accept a plain iterable of molecules and normalise it, so simple
+systems stay simple to write.
+
+**Still not representable:** inhibition (Hordijk & Steel 2012, Part II), where a
+molecule can *prevent* a reaction.
+
 ## Notes on irreducible cores
 
 There may be **exponentially many** irreducible RAFs inside one maximal RAF, and
@@ -145,6 +173,13 @@ pytest -q
 Releases are documented in [CHANGELOG.md](CHANGELOG.md); the release procedure is
 [docs/RELEASING.md](docs/RELEASING.md).
 
+## Citing
+
+Cite the concept DOI [10.5281/zenodo.21954795](https://doi.org/10.5281/zenodo.21954795),
+which always resolves to the latest version; `CITATION.cff` also lists the per-version
+DOI. If you use the CatReNet interoperability or the validation fixture, please cite
+CatReNet too.
+
 ## References
 
 - Hordijk & Steel, "Detecting autocatalytic, self-sustaining sets in chemical reaction

{rafkit-0.1.0 → rafkit-0.2.0}/src/rafkit.egg-info/SOURCES.txt

@@ -3,7 +3,9 @@ README.md
 pyproject.toml
 src/rafkit/__init__.py
 src/rafkit/binary_polymer.py
+src/rafkit/catalysis.py
 src/rafkit/crs.py
+src/rafkit/gillespie.py
 src/rafkit/network.py
 src/rafkit/raf.py
 src/rafkit.egg-info/PKG-INFO
@@ -12,4 +14,7 @@ src/rafkit.egg-info/dependency_links.txt
 src/rafkit.egg-info/requires.txt
 src/rafkit.egg-info/top_level.txt
 tests/test_crs.py
-tests/test_raf.py
+tests/test_gillespie.py
+tests/test_published_examples.py
+tests/test_raf.py
+tests/test_seeding.py

rafkit-0.2.0/tests/test_gillespie.py

@@ -0,0 +1,112 @@
+"""Hand-computable correctness tests for the stochastic simulator.
+
+A Gillespie implementation that is subtly wrong produces plausible trajectories rather
+than errors, so these check arithmetic that can be worked out on paper, plus the one
+structural invariant that caught two real defects while this module was being written:
+**a molecule can never appear before its reactants.**
+"""
+from __future__ import annotations
+
+import numpy as np
+import pytest
+from rafkit import binary_polymer, max_raf
+from rafkit.network import ReactionNetwork
+
+from rafkit.gillespie import (UNCATALYSED_FACTOR, _pair_count, propensities,
+                                   simulate)
+
+
+def _net(molecules, food, pairs, catalysts):
+    return ReactionNetwork(molecules=tuple(molecules), food=frozenset(food),
+                           reaction_pairs=tuple(pairs),
+                           catalysts=tuple(frozenset(c) for c in catalysts))
+
+
+class TestPairCount:
+    def test_distinct_reactants_multiply(self):
+        assert _pair_count(np.array([3, 4, 0]), (0, 1)) == 12
+
+    def test_a_species_cannot_react_with_itself(self):
+        # 5 copies give 10 distinct pairs, not 25: n(n-1)/2.
+        assert _pair_count(np.array([5, 0, 0]), (0, 0)) == 10
+
+    def test_one_copy_gives_no_self_pair(self):
+        assert _pair_count(np.array([1, 0, 0]), (0, 0)) == 0
+
+    def test_single_reactant_is_its_own_count(self):
+        assert _pair_count(np.array([0, 0, 7]), (2,)) == 7
+
+
+class TestPropensities:
+    def test_catalysed_runs_at_full_rate(self):
+        n = _net("abc", [0, 1], [((0, 1), (2,))], [{2}])
+        counts = np.array([3, 4, 1])          # catalyst c present
+        assert propensities(n, counts)[0] == pytest.approx(12.0)
+
+    def test_uncatalysed_runs_at_the_reduced_rate(self):
+        n = _net("abc", [0, 1], [((0, 1), (2,))], [{2}])
+        counts = np.array([3, 4, 0])          # catalyst absent
+        assert propensities(n, counts)[0] == pytest.approx(12.0 / UNCATALYSED_FACTOR)
+
+    def test_the_reduction_factor_is_exactly_the_ratio(self):
+        n = _net("abc", [0, 1], [((0, 1), (2,))], [{2}])
+        with_cat = propensities(n, np.array([3, 4, 1]))[0]
+        without = propensities(n, np.array([3, 4, 0]))[0]
+        assert with_cat / without == pytest.approx(UNCATALYSED_FACTOR)
+
+    def test_missing_reactant_gives_zero(self):
+        n = _net("abc", [0], [((0, 1), (2,))], [{2}])
+        assert propensities(n, np.array([9, 0, 9]))[0] == 0.0
+
+    def test_restriction_silences_excluded_reactions(self):
+        n = _net("abcd", [0, 1], [((0, 1), (2,)), ((0, 1), (3,))], [{2}, {3}])
+        a = propensities(n, np.array([3, 4, 1, 1]), reactions=[0])
+        assert a[0] > 0 and a[1] == 0.0
+
+
+class TestSimulation:
+    def test_food_is_never_depleted_below_the_floor(self):
+        net = binary_polymer(max_len=4, food_len=2, p=0.02,
+                             rng=np.random.default_rng(0), cleavage=True)
+        tr = simulate(net, n_events=800, rng=np.random.default_rng(1), food_floor=5)
+        for f in net.food:
+            assert tr.counts[:, f].min() >= 5
+
+    def test_same_seed_gives_the_same_trajectory(self):
+        net = binary_polymer(max_len=4, food_len=2, p=0.02,
+                             rng=np.random.default_rng(0), cleavage=True)
+        kw = dict(n_events=500, reactions=sorted(max_raf(net).reactions))
+        a = simulate(net, rng=np.random.default_rng(7), **kw)
+        b = simulate(net, rng=np.random.default_rng(7), **kw)
+        assert a.first_appearance == b.first_appearance
+        assert np.array_equal(a.counts, b.counts)
+
+    def test_every_molecule_has_a_route_that_predates_it(self):
+        """The invariant that caught three defects while this was written.
+
+        For each non-food molecule, **at least one** reaction producing it must have all
+        its reactants present at or before it appeared. Requiring that of *every*
+        producing reaction is the wrong claim -- a species is typically also a cleavage
+        product of something larger and later -- and asserting it fails on a correct
+        simulator, which is how the first version of this test behaved.
+        """
+        net = binary_polymer(max_len=5, food_len=2, p=0.0045,
+                             rng=np.random.default_rng(540), cleavage=True)
+        raf = sorted(max_raf(net).reactions)
+        tr = simulate(net, n_events=4000, rng=np.random.default_rng(3), reactions=raf)
+
+        for mol, t_mol in tr.first_appearance.items():
+            if mol in net.food:
+                continue                      # supplied from outside; no route needed
+            routes = [r for r in raf if mol in net.products(r)]
+            assert routes, f"{net.molecules[mol]} appeared but nothing produces it"
+            assert any(
+                all((t := tr.first_appearance.get(x)) is not None and t <= t_mol
+                    for x in net.reactants(r))
+                for r in routes
+            ), f"{net.molecules[mol]} appeared before any route to it was available"
+
+    def test_a_dead_network_stops_rather_than_spinning(self):
+        n = _net("ab", [0], [((0, 1), (1,))], [{1}])   # reactant b never exists
+        tr = simulate(n, n_events=100, rng=np.random.default_rng(0))
+        assert tr.times[-1] == 0.0

rafkit-0.2.0/tests/test_published_examples.py

@@ -0,0 +1,197 @@
+"""Worked examples from the literature, with their published answers.
+
+Every case here is a system somebody else wrote down and stated the answer for, so a
+failure means this library disagrees with the field rather than with our expectations.
+That is the strongest kind of test available, and cheaper than it looks -- these are all
+five reactions or fewer.
+"""
+from __future__ import annotations
+
+from itertools import combinations
+
+import numpy as np
+import pytest
+
+from rafkit import max_raf, parse_crs, sample_irrraf
+from rafkit.raf import _refine, core_raf, has_unique_irraf
+
+
+def _named(net, reactions):
+    return frozenset(net.names[r] for r in reactions)
+
+
+def _all_raf_subsets(net):
+    n = net.n_reactions
+    return [s for k in range(1, n + 1) for c in combinations(range(n), k)
+            if (s := frozenset(c)) and _refine(net, s) == s]
+
+
+# ---------------------------------------------------------------------------
+# Huson, Xavier & Steel, J. R. Soc. Interface 21(214):20230732 (2024),
+# the illustration of corollary 3.1: "based on Kauffman's binary polymer model
+# with food set F = {0,1,00,01,10,11}".
+KAUFFMAN_BPM = """
+Food: 0, 1, 00, 01, 10, 11
+r1 : 10 + 0    [01100] => 100
+r2 : 01 + 100  [0]     => 01100
+r3 : 10 + 1    [0]     => 101
+r4 : 11 + 10   [101]   => 1110
+r5 : 1110 + 0  [101]   => 11100
+"""
+
+
+class TestKauffmanBinaryPolymerExample:
+    """"This system is itself an RAF and it contains six other RAFs as subsets."""
+
+    def test_the_whole_system_is_a_raf(self):
+        net = parse_crs(KAUFFMAN_BPM)
+        assert _named(net, max_raf(net).reactions) == {"r1", "r2", "r3", "r4", "r5"}
+
+    def test_exactly_the_seven_published_rafs(self):
+        net = parse_crs(KAUFFMAN_BPM)
+        got = {frozenset(net.names[r] for r in s) for s in _all_raf_subsets(net)}
+        assert got == {
+            frozenset({"r3"}),
+            frozenset({"r1", "r2"}),
+            frozenset({"r3", "r4"}),
+            frozenset({"r1", "r2", "r3"}),
+            frozenset({"r3", "r4", "r5"}),
+            frozenset({"r1", "r2", "r3", "r4"}),
+            frozenset({"r1", "r2", "r3", "r4", "r5"}),
+        }
+
+    def test_the_irreducible_ones_are_r1r2_and_r3(self):
+        net = parse_crs(KAUFFMAN_BPM)
+        cores = {_named(net, sample_irrraf(net, max_raf(net).reactions,
+                                           np.random.default_rng(i)))
+                 for i in range(50)}
+        assert cores == {frozenset({"r1", "r2"}), frozenset({"r3"})}
+
+    def test_two_irrafs_means_the_core_test_says_not_unique(self):
+        net = parse_crs(KAUFFMAN_BPM)
+        assert not has_unique_irraf(net)
+
+
+# ---------------------------------------------------------------------------
+# Same paper, §4.1: three iRAFs, none nested, "each one is a subset of the union
+# of the two others" -- the case that makes extending pairwise results to three fail.
+THREE_IRRAFS = """
+Food: f
+r1 : f [x1] => x2 + x3
+r2 : f [x2] => x1 + x3
+r3 : f [x3] => x1 + x2
+"""
+
+
+class TestThreeIrreducibleRafs:
+    def test_finds_all_three_published_irrafs(self):
+        net = parse_crs(THREE_IRRAFS)
+        cores = {_named(net, sample_irrraf(net, max_raf(net).reactions,
+                                           np.random.default_rng(i)))
+                 for i in range(60)}
+        assert cores == {frozenset({"r1", "r2"}), frozenset({"r1", "r3"}),
+                         frozenset({"r2", "r3"})}
+
+    def test_no_irraf_is_nested_in_another(self):
+        net = parse_crs(THREE_IRRAFS)
+        cores = list({sample_irrraf(net, max_raf(net).reactions,
+                                    np.random.default_rng(i)) for i in range(60)})
+        for a in cores:
+            for b in cores:
+                assert a == b or not (a < b)
+
+    def test_each_is_contained_in_the_union_of_the_other_two(self):
+        """The published subtlety: pairwise non-nesting does not extend to triples."""
+        net = parse_crs(THREE_IRRAFS)
+        cores = list({sample_irrraf(net, max_raf(net).reactions,
+                                    np.random.default_rng(i)) for i in range(60)})
+        assert len(cores) == 3
+        for i, c in enumerate(cores):
+            others = cores[:i] + cores[i + 1:]
+            assert c <= others[0] | others[1]
+
+
+class TestCoreRaf:
+    def test_core_is_the_iraf_when_it_is_unique(self):
+        # Mutually dependent pair: neither reaction survives without the other, so the
+        # maximal RAF is already irreducible and Core must equal it.
+        net = parse_crs("Food: a, b\nr1 : a + b [d] => c\nr2 : a + c [c] => d\n")
+        assert has_unique_irraf(net)
+        assert core_raf(net) == max_raf(net).reactions
+
+    def test_no_raf_is_not_a_unique_iraf(self):
+        net = parse_crs("Food: a, b\nr1 : a + b [z] => c\n")
+        assert max_raf(net).is_empty
+        assert not has_unique_irraf(net)
+
+
+# ---------------------------------------------------------------------------
+# Huson, Xavier & Steel (2024), Example 3.2 — conjunctive catalysis.
+#   r1 : a + b [{a,d}]    -> e      catalyst set {a,d}: BOTH required
+#   r2 : b + c [{a,b}, e] -> d      {a,b} together, or e alone
+#   r3 : d     [{a,b}]    -> c
+EXAMPLE_3_2 = """
+Food: a, b, c
+r1 : a + b [{a,d}]    => e
+r2 : b + c [{a,b},e]  => d
+r3 : d     [{a,b}]    => c
+"""
+
+
+class TestConjunctiveCatalysisExample:
+    """"{r2}, {r1,r2}, {r2,r3} and {r1,r2,r3} are RAFs, however {r1,r2} is the only
+    strictly autocatalytic RAF."
+
+    Unrepresentable before conjunctive catalyst sets existed in this library.
+    """
+
+    def test_exactly_the_four_published_rafs(self):
+        net = parse_crs(EXAMPLE_3_2)
+        got = {frozenset(net.names[r] for r in s) for s in _all_raf_subsets(net)}
+        assert got == {
+            frozenset({"r2"}),
+            frozenset({"r1", "r2"}),
+            frozenset({"r2", "r3"}),
+            frozenset({"r1", "r2", "r3"}),
+        }
+
+    def test_the_only_strictly_autocatalytic_raf_is_r1r2(self):
+        from rafkit import max_raf_strict
+        net = parse_crs(EXAMPLE_3_2)
+        assert _named(net, max_raf_strict(net).reactions) == {"r1", "r2"}
+
+
+# ---------------------------------------------------------------------------
+# Huson, Xavier & Steel (2024) §2.4 — the system Example 3.1 traces the algorithm on.
+# It needs BOTH new features: conjunctive sets, and the distinction between
+#   r2 : chi = {{}}  "may proceed uncatalysed"   and
+#   r3 : chi = {}    "must be catalysed, and nothing does"
+# which a flat set of catalysts collapses into one.
+SECTION_2_4 = """
+Food: a, b
+r1 : a + a [{c,d},e] => c
+r2 : b + c [{}]      => d
+r3 : b + b []        => e
+r4 : a + e [a]       => b
+r5 : c + d [d]       => g + g
+"""
+
+
+class TestUncatalysedDistinctionExample:
+    """"This system has {r1, r2, r5} as its maxRAF, and {r1, r2} as its unique iRAF." """
+
+    def test_the_published_maxraf(self):
+        net = parse_crs(SECTION_2_4)
+        assert _named(net, max_raf(net).reactions) == {"r1", "r2", "r5"}
+
+    def test_the_published_unique_iraf(self):
+        net = parse_crs(SECTION_2_4)
+        assert has_unique_irraf(net)
+        assert _named(net, core_raf(net)) == {"r1", "r2"}
+
+    def test_the_two_empty_catalyst_forms_are_not_interchangeable(self):
+        """r2 (may run uncatalysed) is in the maxRAF; r3 (must be catalysed, nothing
+        does) can never be. Collapsing them would put both in or both out."""
+        net = parse_crs(SECTION_2_4)
+        names = _named(net, max_raf(net).reactions)
+        assert "r2" in names and "r3" not in names

{rafkit-0.1.0 → rafkit-0.2.0}/tests/test_raf.py

@@ -124,6 +124,7 @@ class TestGenerator:
 
     def test_p_one_catalyses_everything(self):
         n = binary_polymer(max_len=4, food_len=2, p=1.0, rng=np.random.default_rng(0))
+        # p=1.0: every molecule catalyses every reaction, one singleton set each.
         assert all(len(c) == n.n_molecules for c in n.catalysts)
 
     def test_seeded_generation_is_reproducible(self):

rafkit-0.2.0/tests/test_seeding.py

@@ -0,0 +1,83 @@
+"""Gate 1: a maximal RAF assembles by seeding, it does not switch on.
+
+Reproduces the mechanism reported by Hordijk & Steel, "Autocatalytic sets extended:
+dynamics, inhibition, and a generalization" (*J. Syst. Chem.* 3, 5, 2012): parts of a
+maximal RAF catalysed only by their own products cannot start until those products
+appear by a rare **uncatalysed** reaction, so the set comes into existence as an
+order-dependent sequence of events.
+
+Their exact network is a random draw we cannot reconstruct, so these run over an
+ensemble of networks generated at **their published parameters** (n=5, t=2, p=0.0045,
+cleavage-ligation) and assert only what is *causally necessary*. Two phenomenological
+features of their figure are deliberately not asserted here:
+
+* a species declining once a later subRAF consumes it -- topology-specific, and it does
+  not reproduce cleanly on these networks;
+* growth levelling off as cleavage catches up -- it does reproduce, but needs a longer
+  run than their 25,000 events, so it lives in `examples/` where run length is free.
+
+Both were measured before being dropped, rather than quietly omitted.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from rafkit import binary_polymer, max_raf, simulate
+from rafkit.catalysis import is_catalysed
+from rafkit.gillespie import catalytically_reachable
+
+# Hordijk & Steel (2012) §"A realistic example".
+PUBLISHED = dict(max_len=5, food_len=2, p=0.0045)
+SEEDS = [540, 442, 1591, 1660, 44, 95]
+
+
+def _run(seed, n_events=20_000):
+    net = binary_polymer(**PUBLISHED, rng=np.random.default_rng(seed), cleavage=True)
+    raf = sorted(max_raf(net).reactions)
+    if not raf:
+        pytest.skip(f"seed {seed} generated no RAF")
+    return net, raf, simulate(net, n_events=n_events, rng=np.random.default_rng(0),
+                              reactions=raf)
+
+
+@pytest.mark.parametrize("seed", SEEDS)
+def test_food_catalysed_reactions_never_need_seeding(seed):
+    """Criterion 1. Food never depletes, so a reaction with a food catalyst always has
+    one: it can run from t=0 and can never fire uncatalysed. Exact, not statistical."""
+    net, raf, tr = _run(seed)
+    food_catalysed = [r for r in raf if is_catalysed(net.catalysts[r], net.food)]
+    assert food_catalysed, "no always-on reactions in this network"
+    for r in food_catalysed:
+        assert r not in tr.first_uncatalysed, (
+            f"reaction {r} has a food catalyst yet fired uncatalysed")
+
+
+@pytest.mark.parametrize("seed", SEEDS)
+def test_nothing_beyond_the_catalytic_core_appears_before_a_seeding_event(seed):
+    """Criterion 2, and the mechanism itself: molecules that catalysed firings alone
+    cannot reach must wait for a spontaneous reaction."""
+    net, raf, tr = _run(seed)
+    reachable = catalytically_reachable(net, raf)
+    beyond = {m: t for m, t in tr.first_appearance.items() if m not in reachable}
+    if not beyond:
+        pytest.skip("this network needs no seeding; nothing to test")
+
+    assert tr.first_uncatalysed, "molecules appeared beyond the core with no seeding event"
+    first_seed = min(tr.first_uncatalysed.values())
+    earliest, t = min(beyond.items(), key=lambda kv: kv[1])
+    assert t >= first_seed, (
+        f"{net.molecules[earliest]} appeared at {t:.4f}, before the first seeding "
+        f"event at {first_seed:.4f}")
+
+
+def test_the_static_prediction_is_tighter_than_the_naive_one():
+    """`catalytically_reachable` iterates to a fixpoint. Taking only food-catalysed
+    reactions is the tempting cheaper version and it under-counts, because a reaction
+    catalysed by something the always-on part makes becomes catalysed without a seed."""
+    from rafkit.raf import _closure
+    net = binary_polymer(**PUBLISHED, rng=np.random.default_rng(95), cleavage=True)
+    raf = sorted(max_raf(net).reactions)
+    naive = _closure(net, frozenset(r for r in raf
+                                    if is_catalysed(net.catalysts[r], net.food)))
+    assert naive < catalytically_reachable(net, raf)