rafkit 0.1.0__tar.gz

rafkit-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,136 @@
+# 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/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "rafkit"
+version = "0.1.0"
+description = "Autocatalytic (RAF) sets in catalytic reaction networks: maximal RAFs, irreducible cores, and Kauffman binary polymer models."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [
+  { name = "James P. Galasyn" },
+  { name = "Claude Théodore" },
+]
+keywords = [
+  "autocatalytic-sets", "RAF", "origin-of-life", "chemical-reaction-networks",
+  "systems-chemistry", "binary-polymer-model", "catalysis", "abiogenesis",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Chemistry",
+  "Topic :: Scientific/Engineering :: Artificial Life",
+]
+dependencies = ["numpy>=1.24"]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8",
+  "pytest-cov>=4",
+  "pytest-xdist>=3",        # parallel test execution (pytest -n auto)
+]
+
+[project.urls]
+Homepage = "https://github.com/jimgalasyn/rafkit"
+Issues = "https://github.com/jimgalasyn/rafkit/issues"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

rafkit-0.1.0/setup.cfg

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

rafkit-0.1.0/src/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-0.1.0/src/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)