rafkit 0.1.0__py3-none-any.whl

rafkit/__init__.py

@@ -0,0 +1,29 @@
+"""rafkit -- autocatalytic (RAF) sets in catalytic reaction networks.
+
+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.
+
+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
+numbers rather than errors.
+
+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.crs import parse_crs, read_crs, to_crs, write_crs
+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,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BinaryPolymerNetwork", "binary_polymer", "ReactionNetwork",
+    "RafResult", "max_raf", "max_raf_strict", "sample_irrraf", "irrraf_census",
+    "exploitability", "is_food_catalysed", "catrenet_strictly_autocatalytic",
+    "parse_crs", "read_crs", "to_crs", "write_crs",
+]

rafkit/binary_polymer.py

@@ -0,0 +1,185 @@
+"""E4 — Kauffman's binary polymer model.
+
+The canonical setting for the closure phase transition (Kauffman 1986; Hordijk &
+Steel 2004), and the setting in which the closure phase transition is usually
+located.
+
+Molecules are binary strings of length 1..`max_len`. The food set is every string of
+length <= `food_len`. Reactions are **ligations** `a + b -> ab` for every ordered pair
+whose concatenation is within `max_len`, and -- when `cleavage=True` -- the reverse
+`ab -> a + b` as well.
+
+Cleavage was originally omitted on the grounds that it "makes every product trivially
+reachable". That is overstated but **directionally right**, and a first attempt to
+overturn it here was wrong and is recorded so it is not retried: the argument was that
+a cleavage can only fire on a molecule you already have, and a long molecule was
+ligated from shorter ones that must therefore already be present, so the closure could
+not grow.
+
+**Measured, it grows a lot** -- at `max_len=6`, `p=0.004`, from 6-15 molecules to ~120
+in three of four seeds. The flaw in the argument is that a polymer has *many* splits:
+`0101` may be reachable only as `01`+`01`, while the cleavage `0101 -> 010 + 1` yields
+`010`, which no catalysed ligation produces. Production and cleavage need not use the
+same split, so cleavage genuinely enlarges reachability.
+
+More reachable molecules means more catalysts in the closure at any catalysis level,
+so a ligation-only model sits at a markedly higher transition than a
+cleavage-ligation one. See the README for the measured comparison.
+
+It matters because the published binary-polymer references use cleavage-ligation
+chemistries -- Steel, Hordijk & Smith (2012), whose f ~ 1.20 transition this model is
+calibrated against, and Serra & Villani (2026) -- so a ligation-only model cannot be
+compared to either without correction.
+
+Catalysis is assigned independently: each (molecule, reaction) pair is a catalysis
+edge with probability `p`. That uniform assignment is the model's defining
+simplification and also its main limitation — real catalysis is structured, which is
+what ensembles E5/E6 exist to test.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from itertools import product as _product
+from typing import Iterator
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class BinaryPolymerNetwork:
+    """A generated binary-polymer chemistry.
+
+    `reactions[i] = (a, b, ab)` as molecule indices, always stored in that order
+    regardless of which way the reaction runs. `directions[i]` is `+1` for a ligation
+    `a + b -> ab` and `-1` for a cleavage `ab -> a + b`; use `reactants()` and
+    `products()` rather than unpacking the triple by hand. `catalysts[i]` is the set of
+    molecule indices catalysing reaction `i`.
+    """
+
+    molecules: tuple[str, ...]
+    food: frozenset[int]
+    reactions: tuple[tuple[int, int, int], ...]
+    catalysts: tuple[frozenset[int], ...]
+    p: float
+    max_len: int
+    food_len: int
+    directions: tuple[int, ...] = ()
+
+    def __post_init__(self):
+        if not self.directions:                      # default: all ligations
+            object.__setattr__(self, "directions", (1,) * len(self.reactions))
+        elif len(self.directions) != len(self.reactions):
+            raise ValueError(
+                f"directions has {len(self.directions)} entries for "
+                f"{len(self.reactions)} reactions")
+
+    def reactants(self, r: int) -> tuple[int, ...]:
+        """Molecules consumed by reaction `r`, in its stored direction."""
+        a, b, ab = self.reactions[r]
+        return (a, b) if self.directions[r] > 0 else (ab,)
+
+    def products(self, r: int) -> tuple[int, ...]:
+        """Molecules produced by reaction `r`, in its stored direction."""
+        a, b, ab = self.reactions[r]
+        return (ab,) if self.directions[r] > 0 else (a, b)
+
+    @property
+    def n_cleavages(self) -> int:
+        return sum(1 for d in self.directions if d < 0)
+
+    @property
+    def catalysis_level(self) -> float:
+        """`f` in the published convention: catalysed reactions per molecule.
+
+        Steel, Hordijk & Smith (2012) define f = p|R| where **R counts reversible
+        `cleavage-ligation` reactions**, i.e. a ligation and its reverse are ONE
+        reaction. Reporting `mean_catalysed_per_molecule` against their f therefore
+        double-counts a cleavage chemistry and lands 2x too high. This property is the
+        comparable quantity; use it, and not `mean_catalysed_per_molecule`, whenever a
+        number is set beside theirs.
+        """
+        if not self.molecules:
+            return 0.0
+        n_pairs = self.n_reactions - self.n_cleavages
+        return sum(len(c) for c in self.catalysts[:n_pairs]) / len(self.molecules)
+
+    @property
+    def n_molecules(self) -> int:
+        return len(self.molecules)
+
+    @property
+    def n_reactions(self) -> int:
+        return len(self.reactions)
+
+    @property
+    def mean_catalysed_per_molecule(self) -> float:
+        """Reactions catalysed per molecule — the model's natural control variable.
+
+        Kauffman's transition is usually located in this quantity rather than in `p`
+        directly, because `p` alone is not comparable across network sizes.
+        """
+        if not self.molecules:
+            return 0.0
+        return sum(len(c) for c in self.catalysts) / len(self.molecules)
+
+
+def _strings(max_len: int) -> Iterator[str]:
+    for n in range(1, max_len + 1):
+        for bits in _product("01", repeat=n):
+            yield "".join(bits)
+
+
+def binary_polymer(max_len: int = 8, food_len: int = 2, p: float = 1e-3,
+                   rng: np.random.Generator | None = None,
+                   cleavage: bool = False,
+                   paired_catalysis: bool = True) -> BinaryPolymerNetwork:
+    """Generate one binary-polymer network with catalysis at probability `p`.
+
+    `cleavage=True` adds the reverse `ab -> a + b` of every ligation, doubling the
+    stored reaction count.
+
+    `paired_catalysis` (default True) makes a ligation and its reverse **one
+    catalysed unit**, sharing a catalyst set -- the reversible "cleavage-ligation"
+    reaction of Steel, Hordijk & Smith (2012), and the convention their f = p|R| is
+    measured in. Set False to draw the two directions independently; that is a
+    different chemistry and its f is not comparable to theirs.
+    """
+    if max_len < 2:
+        raise ValueError(f"max_len must be at least 2, got {max_len}")
+    if not 0 <= food_len < max_len:
+        raise ValueError(f"food_len must be in [0, max_len), got {food_len}")
+    if not 0.0 <= p <= 1.0:
+        raise ValueError(f"p is a probability, got {p}")
+    rng = rng or np.random.default_rng()
+
+    molecules = tuple(_strings(max_len))
+    index = {m: i for i, m in enumerate(molecules)}
+    food = frozenset(i for i, m in enumerate(molecules) if len(m) <= food_len)
+
+    ligations = tuple(
+        (index[a], index[b], index[a + b])
+        for a in molecules for b in molecules if len(a) + len(b) <= max_len
+    )
+    if cleavage:
+        reactions = ligations + ligations
+        directions = (1,) * len(ligations) + (-1,) * len(ligations)
+    else:
+        reactions = ligations
+        directions = (1,) * len(ligations)
+
+    # Sparse Bernoulli draw: sampling the number of catalysts per reaction and then
+    # which ones is O(edges) rather than O(molecules x reactions), which matters --
+    # the dense product is ~10^8 at max_len=10.
+    n_mol = len(molecules)
+    n_draw = len(ligations) if (cleavage and paired_catalysis) else len(reactions)
+    counts = rng.binomial(n_mol, p, size=n_draw)
+    drawn = tuple(
+        frozenset(rng.choice(n_mol, size=int(k), replace=False).tolist()) if k else
+        frozenset()
+        for k in counts
+    )
+    # Paired: the cleavage half re-uses its ligation's catalysts rather than redrawing.
+    catalysts = drawn + drawn if (cleavage and paired_catalysis) else drawn
+    return BinaryPolymerNetwork(molecules=molecules, food=food, reactions=reactions,
+                                catalysts=catalysts, p=p, max_len=max_len,
+                                food_len=food_len, directions=directions)

rafkit/crs.py

@@ -0,0 +1,130 @@
+"""Read and write CatReNet's CRS format.
+
+CRS is the interchange format of CatReNet (Huson, Xavier & Steel, *Bioinformatics*
+40(8) btae515, 2024), the reference implementation of RAF theory. Supporting it means
+networks can be round-tripped between this library and the field's existing tooling,
+and that any result here can be checked against an independent implementation.
+
+The format is a food line and one line per reaction::
+
+    # a comment
+    Food: a, b, aa, ab
+
+    r1 : aa + b [ab,ba] <-> aab
+    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
+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
+reactants are sets for every RAF computation, nothing is lost; stoichiometry is not
+modelled here either way.
+
+This module talks to CatReNet only through files. No CatReNet code is used or
+derived from -- it is GPL v3, and this library is MIT.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from rafkit.network import ReactionNetwork
+
+_ARROW = re.compile(r"\s*(<->|<=>|=>|->)\s*")
+_LINE = re.compile(r"^\s*(?P<name>[^:]+?)\s*:\s*(?P<body>.*)$")
+
+
+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_crs(text: str) -> ReactionNetwork:
+    """Parse CRS text into a `ReactionNetwork`."""
+    food_names: list[str] = []
+    parsed: list[tuple[str, list[str], list[str], list[str], bool]] = []
+
+    for raw in text.splitlines():
+        line = raw.split("#", 1)[0].strip()
+        if not line:
+            continue
+        if line.lower().startswith("food:"):
+            food_names += _split_list(line.split(":", 1)[1])
+            continue
+        m = _LINE.match(line)
+        if not m:
+            continue
+        name, body = m.group("name"), m.group("body")
+
+        cats: list[str] = []
+        if "[" in body:
+            pre, rest = body.split("[", 1)
+            inside, post = rest.split("]", 1)
+            cats = _split_list(inside)
+            body = pre + " " + post
+
+        arrow = _ARROW.search(body)
+        if not arrow:
+            continue
+        lhs, rhs = body[:arrow.start()], body[arrow.end():]
+        parsed.append((name, _split_list(lhs), _split_list(rhs), cats,
+                       arrow.group(1) in ("<->", "<=>")))
+
+    # Stable molecule indexing: food first, then order of appearance.
+    index: dict[str, int] = {}
+    for n in food_names:
+        index.setdefault(n, len(index))
+    for _, lhs, rhs, cats, _ in parsed:
+        for n in (*lhs, *rhs, *cats):
+            index.setdefault(n, len(index))
+
+    pairs, catalysts, names = [], [], []
+    for name, lhs, rhs, cats, reversible in parsed:
+        cat = frozenset(index[c] for c 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:
+            pairs.append((fwd[1], fwd[0]))
+            catalysts.append(cat)
+            names.append(f"{name}_rev")
+
+    molecules = tuple(sorted(index, key=index.get))
+    return ReactionNetwork(molecules=molecules,
+                           food=frozenset(index[n] for n in food_names),
+                           reaction_pairs=tuple(pairs),
+                           catalysts=tuple(catalysts),
+                           names=tuple(names))
+
+
+def read_crs(path: str | Path) -> ReactionNetwork:
+    """Read a CRS file."""
+    return parse_crs(Path(path).read_text())
+
+
+def to_crs(net, comment: str = "") -> str:
+    """Serialise any network exposing the rafkit protocol to CRS text.
+
+    Reversible pairs are **not** re-merged: each stored direction is written as its
+    own one-way reaction. That round-trips faithfully and keeps the output honest
+    about what the object actually holds.
+    """
+    out = []
+    if comment:
+        out += [f"# {line}" for line in comment.splitlines()]
+    name = lambda m: net.molecules[m]
+    out.append("")
+    out.append("Food: " + ", ".join(sorted(name(m) for m in net.food)))
+    out.append("")
+    names = getattr(net, "names", None) or [f"r{i + 1}" for i in range(net.n_reactions)]
+    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]))
+        out.append(f"{names[r]} : {lhs} [{cats}] => {rhs}")
+    out.append("")
+    return "\n".join(out)
+
+
+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/network.py

@@ -0,0 +1,82 @@
+"""A general catalytic reaction network.
+
+`BinaryPolymerNetwork` stores its reactions compactly as `(a, b, ab)` triples, which
+is what makes tens of thousands of them cheap, but it can only express ligation and
+cleavage over binary strings. `ReactionNetwork` expresses an arbitrary catalytic
+reaction system -- any molecule names, any number of reactants and products -- and
+exposes the **same small protocol** the RAF algorithms use, so `max_raf`,
+`max_raf_strict`, `sample_irrraf`, `irrraf_census` and `exploitability` all work on
+either without change:
+
+    food                molecule indices supplied from outside
+    molecules           names, indexed
+    n_molecules
+    n_reactions
+    catalysts[r]        frozenset of molecule indices catalysing reaction r
+    reactants(r)        molecules consumed by r
+    products(r)         molecules produced by r
+    reactions[r]        every molecule involved in r (membership tests only)
+
+This is what makes the library usable on networks that did not come from a polymer
+model -- see `rafkit.crs` for reading them from CatReNet's CRS format.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ReactionNetwork:
+    """An arbitrary catalytic reaction system.
+
+    `reaction_pairs[i] = (reactants, products)` as tuples of molecule indices.
+    Reactants and products are treated as **sets**: a reaction `X + X -> Y` requires
+    only that `X` be present, so listing `X` once is not a loss of information for
+    any RAF computation (it would be for stoichiometry, which this class does not
+    model).
+    """
+
+    molecules: tuple[str, ...]
+    food: frozenset[int]
+    reaction_pairs: tuple[tuple[tuple[int, ...], tuple[int, ...]], ...]
+    catalysts: tuple[frozenset[int], ...]
+    names: tuple[str, ...] = ()
+
+    def __post_init__(self):
+        if len(self.catalysts) != len(self.reaction_pairs):
+            raise ValueError(
+                f"{len(self.catalysts)} catalyst sets for "
+                f"{len(self.reaction_pairs)} reactions")
+        if not self.names:
+            object.__setattr__(
+                self, "names", tuple(f"r{i + 1}" for i in range(len(self.reaction_pairs))))
+        elif len(self.names) != len(self.reaction_pairs):
+            raise ValueError(
+                f"{len(self.names)} names for {len(self.reaction_pairs)} reactions")
+
+    @property
+    def n_molecules(self) -> int:
+        return len(self.molecules)
+
+    @property
+    def n_reactions(self) -> int:
+        return len(self.reaction_pairs)
+
+    @property
+    def reactions(self) -> tuple[tuple[int, ...], ...]:
+        """Every molecule involved in each reaction; for membership tests only."""
+        return tuple(r + p for r, p in self.reaction_pairs)
+
+    def reactants(self, r: int) -> tuple[int, ...]:
+        return self.reaction_pairs[r][0]
+
+    def products(self, r: int) -> tuple[int, ...]:
+        return self.reaction_pairs[r][1]
+
+    @property
+    def mean_catalysed_per_molecule(self) -> float:
+        if not self.molecules:
+            return 0.0
+        return sum(len(c) for c in self.catalysts) / len(self.molecules)
+
+    catalysis_level = mean_catalysed_per_molecule

rafkit/raf.py

@@ -0,0 +1,300 @@
+"""RAF closure and exploitability.
+
+`max_raf` is the standard Hordijk & Steel (2004) maximal-RAF algorithm. A reaction
+set R' is a RAF over food set F when every reaction in R' is catalysed by a molecule
+producible from F using R' (reflexively autocatalytic), and every reactant is itself
+producible from F using R' (F-generated). The maximal RAF is unique and is reached by
+iteratively discarding reactions that fail either condition.
+
+`exploitability` measures how much of what a RAF produces contributes no catalysis
+back to it. A molecule counts as an exploiter when the RAF produces it and it
+catalyses nothing in the RAF -- reproduced by the closed set's catalysts, giving
+nothing to closure in return. It is a cheap, purely structural observable; it says
+nothing on its own about whether such a molecule could invade dynamically.
+
+Several definitions are defensible, so one is fixed here as the PRIMARY and two
+variants are computed alongside it, reported but never substituted for it:
+
+* `strict`   -- PRIMARY, as above.
+* `unused`   -- produced by the RAF, catalyses nothing in the RAF, **and** is not a
+                reactant of any RAF reaction. A strictly smaller set: these molecules
+                are dead weight in both roles.
+* `dispensable` -- produced by the RAF and removable without shrinking the RAF. The
+                most demanding, and the closest to the hypercycle sense of a parasite:
+                the network's throughput builds it and would lose nothing by not.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from rafkit.binary_polymer import BinaryPolymerNetwork
+
+
+@dataclass(frozen=True)
+class RafResult:
+    reactions: frozenset[int]        # indices of the maximal RAF
+    closure: frozenset[int]          # molecules producible from F using the RAF
+    n_rounds: int                    # fixpoint iterations taken
+
+    @property
+    def size(self) -> int:
+        return len(self.reactions)
+
+    @property
+    def is_empty(self) -> bool:
+        return not self.reactions
+
+
+def _closure(net: BinaryPolymerNetwork, reactions: frozenset[int]) -> frozenset[int]:
+    """Molecules producible from the food set using `reactions`.
+
+    Direction-aware: a ligation fires when both its reactants are present, a cleavage
+    when its single reactant is. Cleavage **does** enlarge this set, because a polymer
+    has many splits and need not be cleaved along the one it was built from -- see the
+    `binary_polymer` docstring, where the contrary argument is recorded as refuted.
+    """
+    have = set(net.food)
+    pending = [(net.reactants(r), net.products(r)) for r in reactions]
+    changed = True
+    while changed:
+        changed = False
+        still = []
+        for reactants, products in pending:
+            if all(x in have for x in reactants):
+                for x in products:
+                    if x not in have:
+                        have.add(x)
+                        changed = True
+            else:
+                still.append((reactants, products))
+        pending = still
+    return frozenset(have)
+
+
+def max_raf(net: BinaryPolymerNetwork) -> RafResult:
+    """The maximal RAF, by iterative removal to a fixpoint (Hordijk & Steel 2004)."""
+    current = frozenset(range(net.n_reactions))
+    rounds = 0
+    while True:
+        rounds += 1
+        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 keep == current:
+            return RafResult(reactions=current, closure=have, n_rounds=rounds)
+        current = keep
+        if not current:
+            return RafResult(reactions=current, closure=_closure(net, current),
+                             n_rounds=rounds)
+
+
+def exploitability(net: BinaryPolymerNetwork, raf: RafResult) -> dict:
+    """Exploiter fractions among the molecules the RAF produces.
+
+    Denominator is RAF products excluding food: food is supplied from outside, so
+    counting it would inflate the fraction with molecules the network never had to
+    make. Returns fractions and raw counts; `nan` fractions when the RAF is empty,
+    which is honest -- there is nothing to exploit.
+    """
+    products = frozenset(raf.closure) - frozenset(net.food)
+    n = len(products)
+    if raf.is_empty or n == 0:
+        nan = float("nan")
+        return {"n_products": n, "strict": nan, "unused": nan, "dispensable": nan,
+                "n_strict": 0, "n_unused": 0, "n_dispensable": 0}
+
+    catalyses_in_raf = set()
+    reactants_in_raf = set()
+    for r in raf.reactions:
+        reactants_in_raf.update(net.reactants(r))
+        catalyses_in_raf |= (net.catalysts[r] & products)
+
+    strict = products - catalyses_in_raf
+    unused = strict - reactants_in_raf
+
+    # `dispensable`: removing the molecule must not shrink the RAF. Removing m kills
+    # every reaction producing or consuming m, and every reaction m alone catalysed.
+    dispensable = set()
+    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})
+        )
+        sub = RafResult(reactions=survives, closure=_closure(net, survives),
+                        n_rounds=0)
+        again = _refine(net, sub.reactions)
+        if len(again) == len(raf.reactions) - _touching(net, raf, m):
+            dispensable.add(m)
+
+    return {"n_products": n,
+            "strict": len(strict) / n, "n_strict": len(strict),
+            "unused": len(unused) / n, "n_unused": len(unused),
+            "dispensable": len(dispensable) / n, "n_dispensable": len(dispensable)}
+
+
+def _touching(net: BinaryPolymerNetwork, raf: RafResult, m: int) -> int:
+    """RAF reactions that directly involve `m` as reactant or product."""
+    return sum(1 for r in raf.reactions if m in net.reactions[r])
+
+
+def _refine(net: BinaryPolymerNetwork, reactions: frozenset[int],
+            strict: bool = False) -> frozenset[int]:
+    """One RAF fixpoint restricted to a reaction subset.
+
+    `strict=True` requires every catalyst to be a **non-food** molecule the set
+    produces, which is the self-referential reading of "reflexively autocatalytic"
+    (see `is_food_catalysed`). Default `False` is the literal Hordijk & Steel
+    condition and is what `max_raf` and every prior result use.
+    """
+    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 keep == current:
+            return current
+        current = keep
+        if not current:
+            return current
+
+
+def max_raf_strict(net: BinaryPolymerNetwork) -> RafResult:
+    """The maximal self-referential RAF: catalysts must be non-food products.
+
+    The subset of the maximal RAF that actually needs its own output to run. This is
+    the object a propagule would have to carry, so it -- not `max_raf` -- is where a
+    count of lineages has to be taken.
+    """
+    current = _refine(net, frozenset(range(net.n_reactions)), strict=True)
+    return RafResult(reactions=current, closure=_closure(net, current), n_rounds=0)
+
+
+def sample_irrraf(net: BinaryPolymerNetwork, reactions: frozenset[int],
+                  rng, strict: bool = False) -> frozenset[int]:
+    """One irreducible RAF contained in `reactions`, by randomized shrinking.
+
+    An irreducible RAF (Hordijk & Steel) is a RAF with no proper subset that is
+    itself a RAF: a minimal self-sustaining core. It is the natural formal stand-in
+    for a *lineage* -- the smallest thing a propagule has to carry to re-establish
+    the network from food alone.
+
+    Walk the reactions in a random order and try to drop each one, keeping the
+    refined remainder whenever it is non-empty. One pass suffices, because maximal
+    RAF is monotone in the reaction set: if dropping `r` collapses the set, it also
+    collapses every subset, so a reaction that survives its own visit can never
+    become removable later. Every reaction present at the end was therefore visited
+    while present and found irremovable, which is the definition.
+
+    The random order is what makes this a *sampler* -- different orders land in
+    different irreducible cores. Distinct results are a lower bound on how many
+    exist, never an upper one.
+
+    **Prior art.** This is Steel, Hordijk & Smith, "Minimal autocatalytic networks"
+    (arXiv:1212.4450, 2012), which describes the same remove-and-refine procedure and
+    the same randomised re-ordering to sample. It was reinvented here on 2026-08-15
+    and the attribution added on discovery. The same paper proves there may be exponentially many irrRAFs and that finding the
+    smallest RAF is NP-hard, so a distinct-count that never saturates is the expected
+    result rather than a surprising one.
+    """
+    current = _refine(net, reactions, strict=strict)
+    order = list(current)
+    rng.shuffle(order)
+    for r in order:
+        if r not in current:
+            continue
+        trial = _refine(net, current - {r}, strict=strict)
+        if trial:
+            current = trial
+    return current
+
+
+def irrraf_census(net: BinaryPolymerNetwork, raf: RafResult, n_samples: int,
+                  rng, strict: bool = False) -> dict:
+    """Sample irreducible RAFs and report how many distinct ones turn up.
+
+    The count is the quantity of interest: it upper-bounds the number of
+    distinguishable lineages the chemistry can carry, so a census of 1 means there
+    is nothing to inherit and no ecology is possible regardless of the dynamics
+    later placed on top.
+    """
+    if raf.is_empty:
+        return {"n_samples": 0, "n_distinct": 0, "sizes": [], "mean_size": float("nan"),
+                "mean_jaccard": float("nan"), "min_jaccard": float("nan"),
+                "union_size": 0, "core_size": 0}
+
+    found: list[frozenset[int]] = []
+    seen: set[frozenset[int]] = set()
+    for _ in range(n_samples):
+        s = sample_irrraf(net, raf.reactions, rng, strict=strict)
+        found.append(s)
+        seen.add(s)
+
+    distinct = sorted(seen, key=len)
+    jac = []
+    for i in range(len(distinct)):
+        for j in range(i + 1, len(distinct)):
+            a, b = distinct[i], distinct[j]
+            jac.append(len(a & b) / len(a | b))
+    self_ref = [c for c in distinct if not is_food_catalysed(net, c)]
+    union: frozenset[int] = frozenset().union(*distinct)
+    core: frozenset[int] = distinct[0]
+    for s in distinct[1:]:
+        core = core & s
+
+    return {"n_samples": n_samples,
+            "n_distinct": len(distinct),
+            "n_self_referential": len(self_ref),
+            "self_ref_sizes": [len(c) for c in self_ref],
+            "sizes": [len(s) for s in distinct],
+            "mean_size": sum(len(s) for s in found) / len(found),
+            "mean_jaccard": sum(jac) / len(jac) if jac else float("nan"),
+            "min_jaccard": min(jac) if jac else float("nan"),
+            "union_size": len(union),
+            "core_size": len(core)}
+
+
+def is_food_catalysed(net: BinaryPolymerNetwork, core: frozenset[int]) -> bool:
+    """Whether every reaction in `core` has a catalyst in the food set.
+
+    Such a core is a RAF by the letter of the definition -- food is in the closure,
+    so "catalysed by a molecule producible from F" is satisfied -- but it is not
+    self-referential: it runs wherever the food runs, needs none of its own products,
+    and therefore carries no heredity. A propagule is not required to establish it.
+
+    This is a real degeneracy of the RAF definition rather than a quirk of E4, and it
+    has to be split out before any count of cores can be read as a count of lineages.
+    """
+    if not core:
+        return False
+    return all(net.catalysts[r] & net.food for r in core)
+
+
+def catrenet_strictly_autocatalytic(net, raf: RafResult | None = None) -> frozenset[int]:
+    """CatReNet's `strictlyAutocatalyticMaxRaf`, for cross-checking.
+
+    CatReNet documents this as "a Max RAF that has the additional property that any
+    contained reaction requires at least one molecule type for catalyzation that is
+    not in the food set". Reproduced here by **black-box behavioural inference** from
+    its published output on a generated network -- no CatReNet source was read, and
+    none could be used, since it is GPL v3 and this library is MIT.
+
+    The operation is a **filter on the maximal RAF, without re-refinement**: keep
+    every reaction having at least one non-food catalyst, and stop. That is *not* the
+    same as `max_raf_strict`, which imposes the same condition inside the fixpoint
+    and therefore returns a set that is itself a RAF. Dropping reactions can break
+    F-generation for the ones that remain, so this result need not be a RAF -- which
+    is exactly why it is offered for interoperability rather than for analysis.
+
+    On the committed CatReNet fixture: `max_raf` 183, this 175, `max_raf_strict` 161.
+    """
+    if raf is None:
+        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)

rafkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: rafkit
+Version: 0.1.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
+Project-URL: Homepage, https://github.com/jimgalasyn/rafkit
+Project-URL: Issues, https://github.com/jimgalasyn/rafkit/issues
+Keywords: autocatalytic-sets,RAF,origin-of-life,chemical-reaction-networks,systems-chemistry,binary-polymer-model,catalysis,abiogenesis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Artificial Life
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-cov>=4; extra == "test"
+Requires-Dist: pytest-xdist>=3; extra == "test"
+Dynamic: license-file
+
+# rafkit
+
+[![CI](https://github.com/JimGalasyn/rafkit/actions/workflows/ci.yml/badge.svg)](https://github.com/JimGalasyn/rafkit/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/JimGalasyn/rafkit/branch/main/graph/badge.svg)](https://codecov.io/gh/JimGalasyn/rafkit)
+[![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)
+
+Autocatalytic (RAF) sets in catalytic reaction networks — maximal RAFs, irreducible
+cores, Kauffman binary polymer models, and interoperability with
+[CatReNet](https://github.com/husonlab/catrenet).
+
+Pure Python and NumPy. No Java, no GUI, no install beyond `pip`.
+
+```python
+from rafkit import binary_polymer, max_raf, sample_irrraf
+import numpy as np
+
+net = binary_polymer(max_len=8, food_len=2, p=1.5e-3, cleavage=True)
+raf = max_raf(net)
+print(raf.size, "reactions in the maximal RAF")
+
+core = sample_irrraf(net, raf.reactions, np.random.default_rng(0))
+print(len(core), "reactions in one irreducible core")
+```
+
+## Why this exists
+
+RAF theory (Hordijk & Steel 2004) formalises collectively autocatalytic sets: a set of
+reactions is a RAF over a food set when every reaction is catalysed by something the
+set can make, and every reactant can be built up from food using the set. The
+reference implementation, **CatReNet**, is an excellent Java/JavaFX desktop
+application. This is a small library for people who want the same algorithms inside a
+Python analysis pipeline.
+
+## Validated against the reference implementation
+
+`tests/data/catrenet_polymer_n6.crs` was generated by CatReNet's own `polymer-tool`,
+and the expected counts in `tests/test_crs.py` are what CatReNet's `catrenet-tool`
+reports on it. The test suite therefore checks this implementation against an
+independent one on every run, with no Java required.
+
+| algorithm | rafkit | CatReNet 1.1.0 |
+|---|---|---|
+| `max_raf` | 183 | 183 |
+| `catrenet_strictly_autocatalytic` | 175 | 175 |
+| `max_raf_strict` | 161 | *(different object — see below)* |
+
+**A documented divergence.** CatReNet's `strictlyAutocatalyticMaxRaf` *filters* the
+maximal RAF for reactions having a non-food catalyst, without re-refining, so its
+result need not itself be a RAF. `max_raf_strict` imposes the same condition inside
+the fixpoint, so its result is a RAF, and is correspondingly smaller. Both are
+available; they answer different questions. CatReNet's behaviour was reproduced by
+black-box inference from its output — no CatReNet source was read or used.
+
+## Calibration
+
+The RAF phase transition in Kauffman's binary polymer model, measured here against
+the published value of *f* ≈ 1.20 (Steel, Hordijk & Smith 2012, n=10, t=2), where
+*f* = p|R| is the mean number of catalysed reactions per molecule:
+
+| model | transition |
+|---|---|
+| ligation only | *f* ≈ 4.7 |
+| ligation + cleavage | *f* ≈ 3.1 |
+| ligation + cleavage, **catalysis paired per reversible reaction** | 0 seeds at *f* ≤ 1.22, all seeds by *f* ≈ 1.59 |
+
+Two conventions have to match before any comparison to the literature means anything:
+the model must include **cleavage**, and a reversible cleavage–ligation pair must be
+counted as **one** catalysed reaction, not two. Use `net.catalysis_level` — not
+`mean_catalysed_per_molecule` — whenever a number is placed beside a published *f*.
+
+## What's implemented
+
+| | |
+|---|---|
+| `max_raf` | maximal RAF, by fixpoint (Hordijk & Steel 2004) |
+| `max_raf_strict` | maximal RAF whose catalysts must be non-food products |
+| `catrenet_strictly_autocatalytic` | CatReNet's similarly-named filter, for interop |
+| `sample_irrraf` | one irreducible RAF, by randomised shrinking (Steel, Hordijk & Smith 2012) |
+| `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 |
+| `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 |
+
+Every algorithm carries hand-computed known-answer tests, because a RAF algorithm that
+is subtly wrong produces plausible numbers rather than errors.
+
+## Notes on irreducible cores
+
+There may be **exponentially many** irreducible RAFs inside one maximal RAF, and
+finding the smallest is NP-hard (Steel, Hordijk & Smith 2012). `sample_irrraf` returns
+*one*, chosen by the random order it walks; `irrraf_census` samples repeatedly and
+reports how many distinct ones it saw. That count is always a **lower bound**, never
+an upper one.
+
+`is_food_catalysed` exists because a core whose every reaction has a food catalyst
+satisfies the letter of the RAF definition while being in no sense self-referential —
+it runs wherever the food runs. Split those out before reading a count of cores as a
+count of anything biological.
+
+## Install
+
+```bash
+pip install rafkit
+```
+
+Development:
+
+```bash
+pip install -e ".[test]"
+pytest -q
+```
+
+Releases are documented in [CHANGELOG.md](CHANGELOG.md); the release procedure is
+[docs/RELEASING.md](docs/RELEASING.md).
+
+## References
+
+- Hordijk & Steel, "Detecting autocatalytic, self-sustaining sets in chemical reaction
+  systems," *J. Theor. Biol.* 227, 451 (2004).
+- Steel, Hordijk & Smith, "Minimal autocatalytic networks," *J. Theor. Biol.* 332, 96
+  (2013); arXiv:1212.4450.
+- Hordijk & Steel, "Autocatalytic sets extended: dynamics, inhibition, and a
+  generalization," *J. Syst. Chem.* 3, 5 (2012); arXiv:1206.1017.
+- Huson, Xavier & Steel, "CatReNet: interactive analysis of (auto-)catalytic reaction
+  networks," *Bioinformatics* 40(8), btae515 (2024).
+- Serra & Villani, "Template-Based Catalysis and the Emergence of Collectively
+  Autocatalytic Systems," *Entropy* 28(2), 184 (2026).
+
+## License
+
+MIT. CatReNet is GPL v3 and is **not** a dependency — this library interoperates with
+it only through files, and contains no code derived from it.

rafkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+rafkit/__init__.py,sha256=vFS1jwt22jDA10PISTmg-P9m0sQqnkM_xNE0Ghgy4lE,1267
+rafkit/binary_polymer.py,sha256=1mPeqKnaF94PFTuQIbPJqAc5L8uayCgOIkiwURjtqAI,8164
+rafkit/crs.py,sha256=uDBgptk4eRVfbd8U8k8Y6tbxVARBuVPv7xKQo5tz9bE,4853
+rafkit/network.py,sha256=Fdzvdrjh_PxFELc7xhApxdL642SaUqu1b7s2pb5gG9A,3198
+rafkit/raf.py,sha256=pF8aC2LLUJ-PBEl5oVYBElwtXjX_juwaZ_A2JS2FSYU,13314
+rafkit-0.1.0.dist-info/licenses/LICENSE,sha256=pXi-REGP6qna7DadI_rzujveoXI4u3PxyD-Af-G_XPc,1073
+rafkit-0.1.0.dist-info/METADATA,sha256=t4wZRi5Syfyoa92nxkAAh0J_XmIP2z1TRujmJ9Sw5YQ,7464
+rafkit-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+rafkit-0.1.0.dist-info/top_level.txt,sha256=88Ez83YyTIb7nzD1WhnXkYIS4JNfKKMmIvhHNJZiVZc,7
+rafkit-0.1.0.dist-info/RECORD,,

rafkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rafkit-0.1.0.dist-info/licenses/LICENSE

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

rafkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rafkit