rafkit 0.1.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rafkit
-Version: 0.1.0
+Version: 0.3.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,70 @@ 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 |
+| `max_urafs` | uninhibited RAFs, when a molecule can prevent a reaction |
 
 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.
+
+## Inhibition
+
+A molecule can prevent a reaction. `max_urafs` returns the **uninhibited RAFs** of
+Hordijk & Steel (2012), and returns a *collection* rather than one set, because
+inhibition destroys the monotonicity that makes a maximal RAF unique — there is no
+"the" maximal u-RAF.
+
+```
+Food: a, b
+r1 : a + b [a] {d} => c      # inhibited by d
+r2 : a + b [b] {c} => d      # inhibited by c
+```
+
+Two maximal u-RAFs, `{r1}` and `{r2}`: each is an RAF whose support avoids its own
+inhibitor, and their union is an RAF that fails the uninhibited condition.
+
+`simulate` respects inhibition too — an inhibited reaction has propensity zero, so a
+running network can **lose** a subRAF, not merely gain one. See
+`examples/inhibition_dissolution.py`.
+
+The set-theoretic tools need no special handling: `sample_irrraf`, `irrraf_census`,
+`core_raf` and `catalytically_reachable` all take a reaction set, and passing a u-RAF
+is correct because the uninhibited property is inherited downward — every sub-RAF of a
+u-RAF is a u-RAF.
+
+Deciding whether a u-RAF exists is NP-complete, but the problem is fixed-parameter
+tractable in *k*, the number of inhibition classes — and **k is a property of how you
+encode inhibition, not of the chemistry.** `classes_from_inhibitors` groups by
+inhibiting *molecule*, so *k* is the number of distinct inhibitors rather than the
+number of inhibited reactions, which is the difference between `2^k` being feasible
+and not.
+
 ## Notes on irreducible cores
 
 There may be **exponentially many** irreducible RAFs inside one maximal RAF, and
@@ -145,6 +203,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.3.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,70 @@ 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 |
+| `max_urafs` | uninhibited RAFs, when a molecule can prevent a reaction |
 
 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.
+
+## Inhibition
+
+A molecule can prevent a reaction. `max_urafs` returns the **uninhibited RAFs** of
+Hordijk & Steel (2012), and returns a *collection* rather than one set, because
+inhibition destroys the monotonicity that makes a maximal RAF unique — there is no
+"the" maximal u-RAF.
+
+```
+Food: a, b
+r1 : a + b [a] {d} => c      # inhibited by d
+r2 : a + b [b] {c} => d      # inhibited by c
+```
+
+Two maximal u-RAFs, `{r1}` and `{r2}`: each is an RAF whose support avoids its own
+inhibitor, and their union is an RAF that fails the uninhibited condition.
+
+`simulate` respects inhibition too — an inhibited reaction has propensity zero, so a
+running network can **lose** a subRAF, not merely gain one. See
+`examples/inhibition_dissolution.py`.
+
+The set-theoretic tools need no special handling: `sample_irrraf`, `irrraf_census`,
+`core_raf` and `catalytically_reachable` all take a reaction set, and passing a u-RAF
+is correct because the uninhibited property is inherited downward — every sub-RAF of a
+u-RAF is a u-RAF.
+
+Deciding whether a u-RAF exists is NP-complete, but the problem is fixed-parameter
+tractable in *k*, the number of inhibition classes — and **k is a property of how you
+encode inhibition, not of the chemistry.** `classes_from_inhibitors` groups by
+inhibiting *molecule*, so *k* is the number of distinct inhibitors rather than the
+number of inhibited reactions, which is the difference between `2^k` being feasible
+and not.
+
 ## Notes on irreducible cores
 
 There may be **exponentially many** irreducible RAFs inside one maximal RAF, and
@@ -117,6 +175,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.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rafkit"
-version = "0.1.0"
+version = "0.3.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.3.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,27 @@ 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.inhibition import (classes_from_inhibitors, is_uninhibited, is_uraf,
+                               max_urafs, support)
 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.3.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",
+    "max_urafs", "is_uraf", "is_uninhibited", "support", "classes_from_inhibitors",
 ]

{rafkit-0.1.0 → rafkit-0.3.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.3.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.3.0}/src/rafkit/crs.py

@@ -14,7 +14,16 @@ 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 brace group **after** the catalyst bracket lists **inhibitors**, space- or
+comma-separated, following CatReNet: `r1 : a + b [c] {d e} -> x`. 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 +48,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,44 +79,54 @@ def parse_crs(text: str) -> ReactionNetwork:
             continue
         name, body = m.group("name"), m.group("body")
 
-        cats: list[str] = []
+        inhib: 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
+            # A brace group AFTER the catalysts is the inhibitor list (CatReNet).
+            m_inh = re.search(r"\{([^}]*)\}", body)
+            if m_inh:
+                inhib = [t for t in re.split(r"[,\s]+", m_inh.group(1)) if t]
+                body = body[:m_inh.start()] + " " + body[m_inh.end():]
 
         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,
+        parsed.append((name, _split_list(lhs), _split_list(rhs), cats, inhib,
                        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):
+    for _, lhs, rhs, cats, inhib, _ in parsed:
+        for n in (*lhs, *rhs, *(x for g in cats for x in g), *inhib):
             index.setdefault(n, len(index))
 
-    pairs, catalysts, names = [], [], []
-    for name, lhs, rhs, cats, reversible in parsed:
-        cat = frozenset(index[c] for c in cats)
+    pairs, catalysts, names, inhibitors = [], [], [], []
+    for name, lhs, rhs, cats, inhib, reversible in parsed:
+        cat = frozenset(frozenset(index[c] for c in g) for g in cats)
+        inh = frozenset(index[x] for x in inhib)
         fwd = (tuple(index[x] for x in lhs), tuple(index[x] for x in rhs))
         pairs.append(fwd); catalysts.append(cat); names.append(name)
+        inhibitors.append(inh)
         if reversible:
             pairs.append((fwd[1], fwd[0]))
             catalysts.append(cat)
             names.append(f"{name}_rev")
+            inhibitors.append(inh)
 
     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))
+                           names=tuple(names),
+                           inhibitors=tuple(inhibitors))
 
 
 def read_crs(path: str | Path) -> ReactionNetwork:
@@ -119,12 +152,25 @@ 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]))
-        out.append(f"{names[r]} : {lhs} [{cats}] => {rhs}")
+        cats = _format_catalysts(net, r)
+        inh = getattr(net, "inhibitors", ())
+        inh_s = ""
+        if inh and inh[r]:
+            inh_s = " {" + " ".join(sorted(name(x) for x in inh[r])) + "}"
+        out.append(f"{names[r]} : {lhs} [{cats}]{inh_s} => {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))