rafkit 0.3.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rafkit
-Version: 0.3.0
+Version: 0.5.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
@@ -30,8 +30,8 @@ Dynamic: license-file
 
 [![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/)
+[![PyPI](https://img.shields.io/pypi/v/rafkit.svg?cacheSeconds=3600)](https://pypi.org/project/rafkit/)
+[![Python](https://img.shields.io/pypi/pyversions/rafkit.svg?cacheSeconds=3600)](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)
 
@@ -115,12 +115,33 @@ counted as **one** catalysed reaction, not two. Use `net.catalysis_level` — no
 | `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 |
+| `to_pnml` / `write_pnml` | PNML export (ISO/IEC 15909-2) for the Petri net ecosystem |
 | `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.
 
+## A reaction network is a Petri net
+
+Species are places, reactions are transitions, molecule counts are tokens. `write_pnml`
+exports to PNML (ISO/IEC 15909-2), so these networks open in Petri net editors, model
+checkers, and the unfolding tools that compute the causal structure of a run.
+
+Three things need care, and each is explicit rather than silent:
+
+- **Catalysis becomes a self-loop.** P/T nets have no read arc, so a catalyst is a pair
+  of arcs, consuming the token and returning it.
+- **Alternative catalyst sets become separate transitions**, named `r1`, `r1#2`, …, since
+  a transition's preset is a conjunction and cannot express "either set".
+- **Food gets source transitions**, because RAF food is inexhaustible and no initial
+  marking expresses that — a marking of *n* deadlocks after *n* uses.
+
+Inhibition has no `ptnet` representation and is written as a `toolspecific` annotation,
+with a warning in the file: a reader that ignores it gets a *different system*.
+Reactions requiring a catalyst that nothing provides are omitted and counted, since
+emitting them unconstrained would make them freely fireable — the opposite of the intent.
+
 ## Catalysis is a relation, not a list
 
 `catalysts[r]` is a set of **alternative catalyst sets**, following Huson, Xavier &

{rafkit-0.3.0 → rafkit-0.5.0}/README.md

@@ -2,8 +2,8 @@
 
 [![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/)
+[![PyPI](https://img.shields.io/pypi/v/rafkit.svg?cacheSeconds=3600)](https://pypi.org/project/rafkit/)
+[![Python](https://img.shields.io/pypi/pyversions/rafkit.svg?cacheSeconds=3600)](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)
 
@@ -87,12 +87,33 @@ counted as **one** catalysed reaction, not two. Use `net.catalysis_level` — no
 | `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 |
+| `to_pnml` / `write_pnml` | PNML export (ISO/IEC 15909-2) for the Petri net ecosystem |
 | `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.
 
+## A reaction network is a Petri net
+
+Species are places, reactions are transitions, molecule counts are tokens. `write_pnml`
+exports to PNML (ISO/IEC 15909-2), so these networks open in Petri net editors, model
+checkers, and the unfolding tools that compute the causal structure of a run.
+
+Three things need care, and each is explicit rather than silent:
+
+- **Catalysis becomes a self-loop.** P/T nets have no read arc, so a catalyst is a pair
+  of arcs, consuming the token and returning it.
+- **Alternative catalyst sets become separate transitions**, named `r1`, `r1#2`, …, since
+  a transition's preset is a conjunction and cannot express "either set".
+- **Food gets source transitions**, because RAF food is inexhaustible and no initial
+  marking expresses that — a marking of *n* deadlocks after *n* uses.
+
+Inhibition has no `ptnet` representation and is written as a `toolspecific` annotation,
+with a warning in the file: a reader that ignores it gets a *different system*.
+Reactions requiring a catalyst that nothing provides are omitted and counted, since
+emitting them unconstrained would make them freely fireable — the opposite of the intent.
+
 ## Catalysis is a relation, not a list
 
 `catalysts[r]` is a set of **alternative catalyst sets**, following Huson, Xavier &

{rafkit-0.3.0 → rafkit-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "rafkit"
-version = "0.3.0"
+version = "0.5.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.3.0 → rafkit-0.5.0}/src/rafkit/__init__.py

@@ -13,27 +13,35 @@ 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.complementary_polymer import (complement,
+                                          complementary_polymer)
+from rafkit.firing_disk import firing_disk_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.pnml import to_pnml, write_pnml
 from rafkit.raf import (
     RafResult, catrenet_strictly_autocatalytic, core_raf, exploitability,
     has_unique_irraf, irrraf_census, is_food_catalysed, max_raf, max_raf_strict,
     sample_irrraf,
 )
 
-__version__ = "0.3.0"
+__version__ = "0.5.0"
 
 __all__ = [
-    "BinaryPolymerNetwork", "binary_polymer", "ReactionNetwork",
+    "BinaryPolymerNetwork", "binary_polymer",
+    "complementary_polymer",
+    "firing_disk_polymer",
+    "complement", "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",
+    "to_pnml", "write_pnml",
     "simulate", "propensities", "Trajectory",
     "max_urafs", "is_uraf", "is_uninhibited", "support", "classes_from_inhibitors",
 ]

{rafkit-0.3.0 → rafkit-0.5.0}/src/rafkit/binary_polymer.py

@@ -66,6 +66,7 @@ class BinaryPolymerNetwork:
     max_len: int
     food_len: int
     directions: tuple[int, ...] = ()
+    inhibitors: tuple[frozenset[int], ...] = ()
 
     def __post_init__(self):
         object.__setattr__(self, "catalysts",
@@ -76,6 +77,16 @@ class BinaryPolymerNetwork:
             raise ValueError(
                 f"directions has {len(self.directions)} entries for "
                 f"{len(self.reactions)} reactions")
+        if not self.inhibitors:
+            object.__setattr__(self, "inhibitors",
+                               (frozenset(),) * len(self.reactions))
+        elif len(self.inhibitors) != len(self.reactions):
+            raise ValueError(
+                f"inhibitors has {len(self.inhibitors)} entries for "
+                f"{len(self.reactions)} reactions")
+        else:
+            object.__setattr__(self, "inhibitors",
+                               tuple(frozenset(i) for i in self.inhibitors))
 
     def reactants(self, r: int) -> tuple[int, ...]:
         """Molecules consumed by reaction `r`, in its stored direction."""
@@ -105,7 +116,28 @@ class BinaryPolymerNetwork:
         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)
+        # Counted over the reversible PAIR: a cleavage-ligation pair is one reaction, so
+        # take the union of the two directions' catalysts. Under `paired_catalysis` the
+        # halves are identical and this is exactly the old count; it differs only where
+        # the directions were drawn separately -- as in C-BPM, where a catalyst acts on
+        # one direction only and counting the ligation half alone would miss every
+        # cleavage catalyst.
+        total = 0
+        for i in range(n_pairs):
+            both = self.catalysts[i]
+            if i + n_pairs < self.n_reactions:
+                both = both | self.catalysts[i + n_pairs]
+            total += len(both)
+        return total / len(self.molecules)
+
+    @property
+    def n_inhibiting_molecules(self) -> int:
+        """`k` in Hordijk & Steel's encoding — distinct molecules that inhibit.
+
+        This is the exponent in `max_urafs`'s `2**k` cost, not a chemistry parameter,
+        which is why `binary_polymer` lets you cap it directly.
+        """
+        return len({x for inh in self.inhibitors for x in inh})
 
     @property
     def n_molecules(self) -> int:
@@ -136,7 +168,9 @@ def _strings(max_len: int) -> Iterator[str]:
 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:
+                   paired_catalysis: bool = True,
+                   q: float = 0.0,
+                   n_inhibitors: int | None = None) -> BinaryPolymerNetwork:
     """Generate one binary-polymer network with catalysis at probability `p`.
 
     `cleavage=True` adds the reverse `ab -> a + b` of every ligation, doubling the
@@ -147,6 +181,20 @@ def binary_polymer(max_len: int = 8, food_len: int = 2, p: float = 1e-3,
     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.
+
+    `q` is the inhibition probability, the mirror of `p`: each (eligible molecule,
+    reaction) pair becomes an inhibition edge with probability `q` (Hordijk & Steel
+    2012, Part II). `q=0`, the default, leaves the network uninhibited and every
+    existing result unchanged.
+
+    `n_inhibitors` caps how many **distinct molecules** may inhibit, drawn uniformly.
+    That cap is `k` in the (X_i, R_i) encoding, and `max_urafs` costs `2**k` maximal-RAF
+    computations -- so it is the difference between a feasible u-RAF census and an
+    impossible one. Leaving it `None` makes every molecule eligible, which is faithful
+    to the model but puts `max_urafs` out of reach on any network of interesting size;
+    `is_uraf` and `is_uninhibited` stay cheap either way. Inhibition is drawn on the
+    ligation half and **shared with the reverse** under `paired_catalysis`, exactly as
+    catalysis is, so the reversible reaction remains one unit.
     """
     if max_len < 2:
         raise ValueError(f"max_len must be at least 2, got {max_len}")
@@ -154,6 +202,10 @@ def binary_polymer(max_len: int = 8, food_len: int = 2, p: float = 1e-3,
         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}")
+    if not 0.0 <= q <= 1.0:
+        raise ValueError(f"q is a probability, got {q}")
+    if n_inhibitors is not None and n_inhibitors < 0:
+        raise ValueError(f"n_inhibitors must be non-negative, got {n_inhibitors}")
     rng = rng or np.random.default_rng()
 
     molecules = tuple(_strings(max_len))
@@ -184,6 +236,23 @@ def binary_polymer(max_len: int = 8, food_len: int = 2, p: float = 1e-3,
     )
     # Paired: the cleavage half re-uses its ligation's catalysts rather than redrawing.
     catalysts = drawn + drawn if (cleavage and paired_catalysis) else drawn
+
+    # Inhibition, drawn the same sparse way and over the same paired unit as catalysis.
+    # Eligibility is restricted FIRST so that k is exactly n_inhibitors, rather than
+    # whatever a q-dependent draw happens to produce.
+    if q > 0.0:
+        eligible = (np.arange(n_mol) if n_inhibitors is None else
+                    rng.choice(n_mol, size=min(n_inhibitors, n_mol), replace=False))
+        i_counts = rng.binomial(len(eligible), q, size=n_draw)
+        i_drawn = tuple(
+            frozenset(rng.choice(eligible, size=int(k), replace=False).tolist()) if k
+            else frozenset()
+            for k in i_counts
+        )
+        inhibitors = (i_drawn + i_drawn if (cleavage and paired_catalysis) else i_drawn)
+    else:
+        inhibitors = ()
     return BinaryPolymerNetwork(molecules=molecules, food=food, reactions=reactions,
                                 catalysts=catalysts, p=p, max_len=max_len,
-                                food_len=food_len, directions=directions)
+                                food_len=food_len, directions=directions,
+                                inhibitors=inhibitors)

rafkit-0.5.0/src/rafkit/complementary_polymer.py

@@ -0,0 +1,115 @@
+"""E5 — Serra & Villani's C-BPM, where catalysis follows STRUCTURE rather than a coin flip.
+
+Reproduced from Serra & Villani, *Entropy* 28(2), 184 (2026), §2.2, rather than invented:
+an in-house structured-catalysis ensemble would be a worse version of a published one.
+
+**The reaction set is identical to the K-BPM's.** Cleavage splits a polymer, condensation
+joins two, and the condensation product ``R-M1M2-R'`` is just the concatenation of the two
+reactants. What differs is *which catalyst catalyses which reaction*, and that single change
+is the whole point of the model:
+
+* a species is a catalyst with probability ``p_cat``, and a catalyst is a **cleavage**
+  catalyst with probability ``p_cleave``, otherwise a **condensation** catalyst;
+* a catalyst carries an **active site** — a substring of itself, of length ``Lambda`` drawn
+  uniformly from ``[site_min, site_max]`` — plus a cut/suture position inside that site;
+* it acts on whatever is **complementary** to that site (binary complement, 0<->1).
+
+The consequence, and the reason this ensemble exists: a K-catalyst's targets are
+independent draws, while a **C-catalyst's targets all share one template**, so they are
+structurally correlated. Serra & Villani measure the signature of that as a much higher and
+much more irregular reactions-per-catalyst distribution (~400 against ~20).
+
+Only polymers at least as long as the active site can be catalysts, which falls out of the
+construction rather than being imposed.
+
+⚠ **This implements their "total chemistry" mode** — every species up to ``max_len`` exists
+and catalysis is assigned over that set. Their alternative **firing-disk** mode grows the
+species set outward from a small seed and is a genuinely different construction, not a
+parameter of this one; it is not implemented here.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from rafkit.binary_polymer import BinaryPolymerNetwork, _strings
+
+_FLIP = str.maketrans("01", "10")
+
+
+def complement(s: str) -> str:
+    """Binary complement — the paper's "an A must correspond to a B, and vice versa"."""
+    return s.translate(_FLIP)
+
+
+def complementary_polymer(max_len: int = 8, food_len: int = 2, p_cat: float = 0.05,
+                          p_cleave: float = 0.5, site_min: int = 3, site_max: int = 4,
+                          rng: np.random.Generator | None = None) -> BinaryPolymerNetwork:
+    """Generate one C-chemistry: catalysis by active-site complementarity.
+
+    Defaults are the paper's Figure 3 ensemble (``p_cat=0.05``, ``p_cleave=0.5``, active
+    sites uniform on 3..4). Returns the same `BinaryPolymerNetwork` a K-chemistry does, so
+    every downstream consumer -- `max_raf`, the protocell, the u-RAF layer -- is unchanged.
+    """
+    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}")
+    for name, v in (("p_cat", p_cat), ("p_cleave", p_cleave)):
+        if not 0.0 <= v <= 1.0:
+            raise ValueError(f"{name} is a probability, got {v}")
+    if not 1 <= site_min <= site_max:
+        raise ValueError(f"need 1 <= site_min <= site_max, got {site_min}, {site_max}")
+    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
+    )
+    reactions = ligations + ligations
+    directions = (1,) * len(ligations) + (-1,) * len(ligations)
+    n_pairs = len(ligations)
+    lig_at = {(a, b): i for i, (a, b, _) in enumerate(ligations)}
+    # cleavage of `ab` at offset k is the reverse of the ligation a + b -> ab
+    cleave_at = {(index[m], k): n_pairs + lig_at[(index[m[:k]], index[m[k:]])]
+                 for m in molecules for k in range(1, len(m))}
+
+    by_prefix: dict[str, list[str]] = {}
+    by_suffix: dict[str, list[str]] = {}
+    for m in molecules:
+        for k in range(1, len(m) + 1):
+            by_prefix.setdefault(m[:k], []).append(m)
+            by_suffix.setdefault(m[-k:], []).append(m)
+
+    catalysts: list[set[int]] = [set() for _ in reactions]
+    for x, mol in enumerate(molecules):
+        if len(mol) < site_min or rng.random() >= p_cat:
+            continue
+        width = int(rng.integers(site_min, min(site_max, len(mol)) + 1))
+        start = int(rng.integers(0, len(mol) - width + 1))
+        site = mol[start:start + width]
+        cut = int(rng.integers(1, width))          # split point inside the active site
+        if rng.random() < p_cleave:
+            # cleave any polymer carrying a segment complementary to the whole site
+            target = complement(site)
+            for m in molecules:
+                pos = m.find(target)
+                while pos != -1:
+                    catalysts[cleave_at[(index[m], pos + cut)]].add(x)
+                    pos = m.find(target, pos + 1)
+        else:
+            # join a molecule ENDING complementary to site[:cut] to one STARTING
+            # complementary to site[cut:]
+            left, right = complement(site[:cut]), complement(site[cut:])
+            for a in by_suffix.get(left, ()):
+                for b in by_prefix.get(right, ()):
+                    if len(a) + len(b) <= max_len:
+                        catalysts[lig_at[(index[a], index[b])]].add(x)
+
+    return BinaryPolymerNetwork(
+        molecules=molecules, food=food, reactions=reactions,
+        catalysts=tuple(frozenset(c) for c in catalysts),
+        p=p_cat, max_len=max_len, food_len=food_len, directions=directions)

rafkit-0.5.0/src/rafkit/firing_disk.py

@@ -0,0 +1,139 @@
+"""Serra & Villani's FIRING-DISK construction — a chemistry grown, not enumerated.
+
+Reproduced from *Entropy* 28(2), 184 (2026), §2.2. The contrast with every other generator
+here is the point:
+
+* `binary_polymer` and `complementary_polymer` **enumerate** every string up to `max_len`
+  and sprinkle catalysis over the result. A species exists because it is short enough.
+* the firing disk **grows** outward from a small seed. A species exists only if some
+  reaction in the network actually **makes** it.
+
+So a firing-disk chemistry is closed under its own production by construction, where an
+enumerated one is full of species nothing can reach. That difference plausibly matters a
+great deal for protocell viability, because unreachable species dilute the material without
+contributing to it -- which is why this exists.
+
+The loop is theirs: seed a disk of short polymers, designate some as cleavage or
+condensation catalysts, find every reaction the current catalysts enable among the current
+species, run them, and give each **newly generated** species a chance `p_cat` of being a
+catalyst itself -- iterating "until there are no more new reactions or new species to add,
+or some termination condition is met."
+
+⚠ **Food is taken to be the firing disk.** The paper does not say what plays the role of
+food when such a chemistry is embedded in a protocell, and the disk is the only externally
+given set, so that is the reading used here -- an assumption, not a quotation.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from rafkit.binary_polymer import BinaryPolymerNetwork, _strings
+from rafkit.complementary_polymer import complement
+
+
+def _site(mol, site_min, site_max, rng):
+    width = int(rng.integers(site_min, min(site_max, len(mol)) + 1))
+    start = int(rng.integers(0, len(mol) - width + 1))
+    site = mol[start:start + width]
+    return site, int(rng.integers(1, width))
+
+
+def firing_disk_polymer(disk_size: int = 24, disk_len: int = 4, max_len: int = 10,
+                        p_cat: float = 0.05, p_cleave: float = 0.5,
+                        n_cleave_cat: int = 2, n_cond_cat: int = 2,
+                        site_min: int = 3, site_max: int = 4,
+                        max_species: int = 4000, max_rounds: int = 200,
+                        rng: np.random.Generator | None = None) -> BinaryPolymerNetwork:
+    """Grow one C-chemistry outward from a firing disk.
+
+    Defaults follow the paper's Figure 3 ensemble where stated: 24 initial species of
+    length <= 4, ``Lmax = 10``, ``p_cat = 0.05``, ``p_cleave = 0.5``, active sites uniform
+    on 3..4. ``n_cleave_cat`` / ``n_cond_cat`` are their ``NCLini`` / ``NCDini``, whose
+    values Figure 3 does not state.
+
+    ``max_species`` and ``max_rounds`` are the "termination condition" their text leaves
+    open; both are reported through the returned network's size rather than raising, but a
+    run that hits ``max_species`` is a **truncated** chemistry and should be treated as
+    such.
+    """
+    if not 1 <= site_min <= site_max:
+        raise ValueError(f"need 1 <= site_min <= site_max, got {site_min}, {site_max}")
+    for name, v in (("p_cat", p_cat), ("p_cleave", p_cleave)):
+        if not 0.0 <= v <= 1.0:
+            raise ValueError(f"{name} is a probability, got {v}")
+    rng = rng or np.random.default_rng()
+
+    pool = [m for m in _strings(disk_len) if len(m) >= 1]
+    disk = list(rng.choice(pool, size=min(disk_size, len(pool)), replace=False))
+    species: set[str] = set(disk)
+
+    # catalyst -> (site, cut, is_cleaver); seeded per NCLini / NCDini, then grown by p_cat
+    cats: dict[str, tuple[str, int, bool]] = {}
+    eligible = [m for m in disk if len(m) >= site_min]
+    rng.shuffle(eligible)
+    for m in eligible[:n_cleave_cat]:
+        s, c = _site(m, site_min, site_max, rng); cats[m] = (s, c, True)
+    for m in eligible[n_cleave_cat:n_cleave_cat + n_cond_cat]:
+        s, c = _site(m, site_min, site_max, rng); cats[m] = (s, c, False)
+
+    # split -> set of catalysts, for each direction; a "split" is the pair (a, b) of ab
+    lig: dict[tuple[str, str], set[str]] = {}
+    cle: dict[tuple[str, str], set[str]] = {}
+
+    for _ in range(max_rounds):
+        fresh: set[str] = set()
+        by_pre: dict[str, list[str]] = {}
+        by_suf: dict[str, list[str]] = {}
+        for m in species:
+            for k in range(1, len(m) + 1):
+                by_pre.setdefault(m[:k], []).append(m)
+                by_suf.setdefault(m[-k:], []).append(m)
+        for cat, (site, cut, is_cleaver) in list(cats.items()):
+            if is_cleaver:
+                target = complement(site)
+                for m in list(species):
+                    pos = m.find(target)
+                    while pos != -1:
+                        k = pos + cut
+                        if 0 < k < len(m):
+                            a, b = m[:k], m[k:]
+                            cle.setdefault((a, b), set()).add(cat)
+                            fresh.update({a, b} - species)
+                        pos = m.find(target, pos + 1)
+            else:
+                left, right = complement(site[:cut]), complement(site[cut:])
+                for a in by_suf.get(left, ()):
+                    for b in by_pre.get(right, ()):
+                        if len(a) + len(b) <= max_len:
+                            lig.setdefault((a, b), set()).add(cat)
+                            if a + b not in species:
+                                fresh.add(a + b)
+        if not fresh:
+            break
+        for m in sorted(fresh):
+            if len(species) >= max_species:
+                break
+            species.add(m)
+            if len(m) >= site_min and rng.random() < p_cat:
+                s, c = _site(m, site_min, site_max, rng)
+                cats[m] = (s, c, rng.random() < p_cleave)
+
+    # Emit in the paired layout the rest of the library expects: every split that appears
+    # in either direction becomes one ligation and one cleavage, each carrying only the
+    # catalysts actually assigned to that direction.
+    splits = sorted(set(lig) | set(cle))
+    splits = [(a, b) for a, b in splits if a in species and b in species
+              and a + b in species]
+    molecules = tuple(sorted(species, key=lambda m: (len(m), m)))
+    index = {m: i for i, m in enumerate(molecules)}
+    ligations = tuple((index[a], index[b], index[a + b]) for a, b in splits)
+    reactions = ligations + ligations
+    directions = (1,) * len(ligations) + (-1,) * len(ligations)
+    catalysts = tuple(frozenset(index[c] for c in lig.get(s, ()) if c in index)
+                      for s in splits) + \
+                tuple(frozenset(index[c] for c in cle.get(s, ()) if c in index)
+                      for s in splits)
+    food = frozenset(index[m] for m in disk if m in index)
+    return BinaryPolymerNetwork(
+        molecules=molecules, food=food, reactions=reactions, catalysts=catalysts,
+        p=p_cat, max_len=max_len, food_len=disk_len, directions=directions)

rafkit-0.5.0/src/rafkit/pnml.py

@@ -0,0 +1,139 @@
+"""Export to PNML, the ISO/IEC 15909-2 Petri net interchange format.
+
+A catalytic reaction network *is* a Petri net: species are places, reactions are
+transitions, molecule counts are tokens. Exporting makes these networks readable by the
+Petri net ecosystem -- editors, model checkers, and the unfolding tools that compute the
+causal DAG of a run.
+
+Three things in the RAF model have no direct Place/Transition equivalent, and each is
+handled explicitly rather than silently:
+
+**Catalysis becomes a self-loop.** P/T nets have no read arc, so a catalyst is written
+as a pair of arcs, place -> transition -> place: the token is consumed and immediately
+returned, which is behaviourally what a catalyst does.
+
+**Alternative catalyst sets become separate transitions.** A transition's preset is a
+conjunction, so it cannot express "either of these sets". A reaction with `k` catalyst
+sets is emitted as `k` transitions sharing reactants and products, each with self-loops
+for one set. They are named ``r1``, ``r1#2``, ``r1#3`` … so the grouping survives.
+
+**Food becomes a source transition.** RAF food is inexhaustible, which no initial
+marking expresses: a marking of *n* deadlocks after *n* uses. Each food place therefore
+gets a source transition with an empty preset, which can always fire.
+
+Not expressible, and reported rather than dropped:
+
+* **Inhibition** has no standard P/T representation. Inhibitor arcs exist in extended
+  formalisms but not in the ``ptnet`` grammar, so they are written as a
+  ``<toolspecific>`` annotation. A tool that ignores it will read a net **without** the
+  inhibition, which is a *different system* -- so `to_pnml` says so in a comment.
+* **χ = ∅** ("must be catalysed, and nothing does") is a RAF-theoretic condition, not a
+  Petri net one. Such reactions can never fire in any RAF, and emitting them as
+  unconstrained transitions would make them freely fireable -- the opposite. They are
+  omitted, and counted in the header comment.
+"""
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+PNML_NS = "http://www.pnml.org/version-2009/grammar/pnml"
+PTNET = "http://www.pnml.org/version-2009/grammar/ptnet"
+
+
+def _el(parent, tag, **attrs):
+    return ET.SubElement(parent, tag, {k: str(v) for k, v in attrs.items()})
+
+
+def _named(parent, text):
+    name = _el(parent, "name")
+    _el(name, "text").text = text
+    return name
+
+
+def to_pnml(net, net_id: str = "rafkit", food_sources: bool = True) -> str:
+    """Serialise a network to PNML text.
+
+    `food_sources` adds a source transition per food place so that food is
+    inexhaustible, matching RAF semantics. Turn it off to get a net whose food is
+    limited to its initial marking -- which is a different system, and will deadlock.
+    """
+    inhibitors = getattr(net, "inhibitors", ()) or ((),) * net.n_reactions
+    names = getattr(net, "names", None) or [f"r{i + 1}" for i in range(net.n_reactions)]
+
+    root = ET.Element("pnml", {"xmlns": PNML_NS})
+    pnet = _el(root, "net", id=net_id, type=PTNET)
+    _named(pnet, net_id)
+    page = _el(pnet, "page", id="page1")
+
+    for m, mol in enumerate(net.molecules):
+        place = _el(page, "place", id=f"p{m}")
+        _named(place, mol)
+        marking = _el(place, "initialMarking")
+        _el(marking, "text").text = "1" if m in net.food else "0"
+
+    arc_id = 0
+
+    def arc(src, dst):
+        nonlocal arc_id
+        arc_id += 1
+        a = _el(page, "arc", id=f"a{arc_id}", source=src, target=dst)
+        insc = _el(a, "inscription")
+        _el(insc, "text").text = "1"
+
+    skipped = 0
+    for r in range(net.n_reactions):
+        chi = net.catalysts[r]
+        if not chi:
+            skipped += 1            # must be catalysed, nothing does: cannot ever fire
+            continue
+        for k, catalyst_set in enumerate(sorted(chi, key=lambda u: sorted(u))):
+            tid = f"t{r}" if k == 0 else f"t{r}_{k}"
+            label = names[r] if k == 0 else f"{names[r]}#{k + 1}"
+            trans = _el(page, "transition", id=tid)
+            _named(trans, label)
+            if inhibitors[r]:
+                ts = _el(trans, "toolspecific", tool="rafkit", version="1")
+                _el(ts, "inhibitors").text = " ".join(
+                    sorted(net.molecules[x] for x in inhibitors[r]))
+            for x in net.reactants(r):
+                arc(f"p{x}", tid)
+            for x in net.products(r):
+                arc(tid, f"p{x}")
+            for c in catalyst_set:            # read arc, as a self-loop
+                arc(f"p{c}", tid)
+                arc(tid, f"p{c}")
+
+    if food_sources:
+        for m in sorted(net.food):
+            tid = f"src{m}"
+            trans = _el(page, "transition", id=tid)
+            _named(trans, f"source:{net.molecules[m]}")
+            arc(tid, f"p{m}")
+
+    ET.indent(root, space="  ")
+    body = ET.tostring(root, encoding="unicode")
+    notes = [f"Generated by rafkit. {net.n_molecules} species, "
+             f"{net.n_reactions} reactions."]
+    if skipped:
+        notes.append(f"{skipped} reaction(s) omitted: they require a catalyst and "
+                     f"nothing catalyses them, so they can never fire.")
+    if any(inhibitors):
+        notes.append("Inhibition is recorded in a toolspecific element only; the "
+                     "ptnet grammar has no inhibitor arc. A tool that ignores it "
+                     "reads a DIFFERENT system, without the inhibition.")
+    if food_sources:
+        notes.append("Food places have source transitions, so food is inexhaustible.")
+    # A comment may not contain "--" anywhere, nor end with "-". Sanitising here
+    # rather than trusting the call sites: this text is prepended as raw XML, so it
+    # bypasses ElementTree's escaping entirely, and an unescaped double hyphen makes
+    # the whole document unparseable. Found by an independent PNML reader, not by us.
+    safe = [n.replace("--", "\u2014").rstrip("-") for n in notes]
+    header = "<?xml version='1.0' encoding='UTF-8'?>\n<!--\n  " + \
+             "\n  ".join(safe) + "\n-->\n"
+    return header + body + "\n"
+
+
+def write_pnml(net, path: str | Path, **kwargs) -> None:
+    """Write a network to a PNML file."""
+    Path(path).write_text(to_pnml(net, **kwargs))

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rafkit
-Version: 0.3.0
+Version: 0.5.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
@@ -30,8 +30,8 @@ Dynamic: license-file
 
 [![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/)
+[![PyPI](https://img.shields.io/pypi/v/rafkit.svg?cacheSeconds=3600)](https://pypi.org/project/rafkit/)
+[![Python](https://img.shields.io/pypi/pyversions/rafkit.svg?cacheSeconds=3600)](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)
 
@@ -115,12 +115,33 @@ counted as **one** catalysed reaction, not two. Use `net.catalysis_level` — no
 | `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 |
+| `to_pnml` / `write_pnml` | PNML export (ISO/IEC 15909-2) for the Petri net ecosystem |
 | `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.
 
+## A reaction network is a Petri net
+
+Species are places, reactions are transitions, molecule counts are tokens. `write_pnml`
+exports to PNML (ISO/IEC 15909-2), so these networks open in Petri net editors, model
+checkers, and the unfolding tools that compute the causal structure of a run.
+
+Three things need care, and each is explicit rather than silent:
+
+- **Catalysis becomes a self-loop.** P/T nets have no read arc, so a catalyst is a pair
+  of arcs, consuming the token and returning it.
+- **Alternative catalyst sets become separate transitions**, named `r1`, `r1#2`, …, since
+  a transition's preset is a conjunction and cannot express "either set".
+- **Food gets source transitions**, because RAF food is inexhaustible and no initial
+  marking expresses that — a marking of *n* deadlocks after *n* uses.
+
+Inhibition has no `ptnet` representation and is written as a `toolspecific` annotation,
+with a warning in the file: a reader that ignores it gets a *different system*.
+Reactions requiring a catalyst that nothing provides are omitted and counted, since
+emitting them unconstrained would make them freely fireable — the opposite of the intent.
+
 ## Catalysis is a relation, not a list
 
 `catalysts[r]` is a set of **alternative catalyst sets**, following Huson, Xavier &

{rafkit-0.3.0 → rafkit-0.5.0}/src/rafkit.egg-info/SOURCES.txt

@@ -4,19 +4,25 @@ pyproject.toml
 src/rafkit/__init__.py
 src/rafkit/binary_polymer.py
 src/rafkit/catalysis.py
+src/rafkit/complementary_polymer.py
 src/rafkit/crs.py
+src/rafkit/firing_disk.py
 src/rafkit/gillespie.py
 src/rafkit/inhibition.py
 src/rafkit/network.py
+src/rafkit/pnml.py
 src/rafkit/raf.py
 src/rafkit.egg-info/PKG-INFO
 src/rafkit.egg-info/SOURCES.txt
 src/rafkit.egg-info/dependency_links.txt
 src/rafkit.egg-info/requires.txt
 src/rafkit.egg-info/top_level.txt
+tests/test_complementary_polymer.py
 tests/test_crs.py
+tests/test_firing_disk.py
 tests/test_gillespie.py
 tests/test_inhibition.py
+tests/test_pnml.py
 tests/test_published_examples.py
 tests/test_raf.py
 tests/test_seeding.py

rafkit-0.5.0/tests/test_complementary_polymer.py

@@ -0,0 +1,115 @@
+"""C-BPM — Serra & Villani, *Entropy* 28(2), 184 (2026), §2.2.
+
+The load-bearing test is `test_every_catalysed_reaction_has_a_matching_site`: it re-derives
+the complementarity rule from the catalyst's own string, independently of the code that
+assigned it. Everything else is a property from the paper.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from rafkit import binary_polymer, complement, complementary_polymer, max_raf
+
+
+def _catalysts(net):
+    """Flatten the catalyst relation: each entry is a set of conjunctive GROUPS."""
+    return {x for entry in net.catalysts for group in entry for x in group}
+
+
+def _edges(net):
+    return sum(len(group) for entry in net.catalysts for group in entry)
+
+
+def _sites(mol, site_min, site_max):
+    for w in range(site_min, min(site_max, len(mol)) + 1):
+        for i in range(len(mol) - w + 1):
+            yield mol[i:i + w]
+
+
+class TestComplement:
+    def test_flips_bits_and_is_an_involution(self):
+        assert complement("100110") == "011001"          # the paper's own example
+        assert complement(complement("10110")) == "10110"
+
+
+class TestConstruction:
+    def test_reaction_set_matches_the_k_model(self):
+        """C-BPM changes WHICH catalyst acts, not what reactions exist."""
+        c = complementary_polymer(max_len=6, rng=np.random.default_rng(0))
+        k = binary_polymer(max_len=6, cleavage=True, rng=np.random.default_rng(0))
+        assert c.molecules == k.molecules
+        assert c.reactions == k.reactions
+        assert c.directions == k.directions
+
+    def test_no_catalysis_when_p_cat_zero(self):
+        c = complementary_polymer(max_len=6, p_cat=0.0, rng=np.random.default_rng(0))
+        assert all(not s for s in c.catalysts)
+        assert c.catalysis_level == 0.0
+
+    def test_only_polymers_at_least_as_long_as_a_site_catalyse(self):
+        """Falls out of the construction; the paper states it as a consequence."""
+        c = complementary_polymer(max_len=7, p_cat=1.0, site_min=4, site_max=4,
+                                  rng=np.random.default_rng(1))
+        for x in _catalysts(c):
+            assert len(c.molecules[x]) >= 4
+
+    def test_deterministic_for_a_seed(self):
+        a = complementary_polymer(max_len=6, rng=np.random.default_rng(5))
+        b = complementary_polymer(max_len=6, rng=np.random.default_rng(5))
+        assert a.catalysts == b.catalysts
+
+    def test_every_catalysed_reaction_has_a_matching_site(self):
+        """Re-derive the rule from the catalyst's string, not from the assigning code.
+
+        For a condensation the catalyst must hold a site whose first part complements the
+        first reactant's SUFFIX and whose second part complements the second's PREFIX; for
+        a cleavage, a site complementary to a segment spanning the cut in the substrate.
+        """
+        smin, smax = 3, 4
+        c = complementary_polymer(max_len=7, p_cat=0.3, site_min=smin, site_max=smax,
+                                  rng=np.random.default_rng(3))
+        checked = 0
+        for r, cats in enumerate(c.catalysts):
+            for group in cats:
+                for x in group:
+                    cat = c.molecules[x]
+                    a, b, ab = (c.molecules[i] for i in c.reactions[r])
+                    if c.directions[r] > 0:                       # condensation a + b -> ab
+                        ok = any(a.endswith(complement(s[:k])) and
+                                 b.startswith(complement(s[k:]))
+                                 for s in _sites(cat, smin, smax)
+                                 for k in range(1, len(s)))
+                    else:                                          # cleavage ab -> a + b
+                        cut = len(a)
+                        ok = any(complement(s) in
+                                 {ab[cut - k: cut - k + len(s)] for k in range(1, len(s))}
+                                 for s in _sites(cat, smin, smax))
+                    assert ok, f"{cat!r} catalyses {a!r}+{b!r}->{ab!r} with no matching site"
+                    checked += 1
+        assert checked > 100, f"only {checked} assignments exercised"
+
+
+class TestPaperSignature:
+    def test_far_fewer_catalysts_each_doing_far_more(self):
+        """Their headline contrast: ~400 reactions per C-catalyst against ~20 for K."""
+        c = complementary_polymer(max_len=8, p_cat=0.05, rng=np.random.default_rng(0))
+        k = binary_polymer(max_len=8, p=0.003, cleavage=True, rng=np.random.default_rng(0))
+        per = lambda n: _edges(n) / max(len(_catalysts(n)), 1)
+        assert per(c) > 5 * per(k)
+        assert len(_catalysts(c)) < len(_catalysts(k)) / 5
+
+    def test_hosts_a_raf(self):
+        c = complementary_polymer(max_len=8, p_cat=0.05, rng=np.random.default_rng(0))
+        assert len(max_raf(c).reactions) > 0
+
+
+class TestValidation:
+    @pytest.mark.parametrize("kw", [dict(p_cat=1.5), dict(p_cleave=-0.1)])
+    def test_probabilities_checked(self, kw):
+        with pytest.raises(ValueError, match="is a probability"):
+            complementary_polymer(max_len=5, **kw)
+
+    def test_site_bounds_checked(self):
+        with pytest.raises(ValueError, match="site_min <= site_max"):
+            complementary_polymer(max_len=5, site_min=4, site_max=3)

rafkit-0.5.0/tests/test_firing_disk.py

@@ -0,0 +1,87 @@
+"""The firing-disk construction — Serra & Villani, *Entropy* 28(2), 184 (2026), §2.2.
+
+The load-bearing property is `test_every_species_is_produced_or_seed`: a grown chemistry
+is closed under its own production, which is exactly what distinguishes it from an
+enumerated one and is the reason it exists here.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from rafkit import binary_polymer, firing_disk_polymer, max_raf
+
+
+class TestGrowth:
+    def test_every_species_is_produced_or_seed(self):
+        """No unreachable species: each molecule is food, or some reaction makes it."""
+        net = firing_disk_polymer(rng=np.random.default_rng(0))
+        made = {m for r in range(net.n_reactions) for m in net.products(r)}
+        for x in range(net.n_molecules):
+            assert x in net.food or x in made, f"{net.molecules[x]!r} unreachable"
+
+    def test_disk_is_the_food_set(self):
+        net = firing_disk_polymer(disk_size=16, disk_len=4,
+                                  rng=np.random.default_rng(1))
+        assert len(net.food) == 16
+        assert all(len(net.molecules[x]) <= 4 for x in net.food)
+
+    def test_respects_max_len(self):
+        net = firing_disk_polymer(max_len=6, rng=np.random.default_rng(2))
+        assert all(len(m) <= 6 for m in net.molecules)
+
+    def test_no_seed_catalysts_means_no_growth(self):
+        """Nothing can fire, so the chemistry is the disk and there are no reactions."""
+        net = firing_disk_polymer(n_cleave_cat=0, n_cond_cat=0, p_cat=0.0,
+                                  disk_size=20, rng=np.random.default_rng(3))
+        assert net.n_reactions == 0
+        assert net.n_molecules == 20
+
+    def test_deterministic_for_a_seed(self):
+        a = firing_disk_polymer(max_len=8, rng=np.random.default_rng(7))
+        b = firing_disk_polymer(max_len=8, rng=np.random.default_rng(7))
+        assert a.molecules == b.molecules and a.catalysts == b.catalysts
+
+    def test_reactions_are_consistent_splits(self):
+        net = firing_disk_polymer(max_len=8, rng=np.random.default_rng(4))
+        for a, b, ab in net.reactions:
+            assert net.molecules[a] + net.molecules[b] == net.molecules[ab]
+
+
+class TestPaperEnsemble:
+    """Figure 3's ensemble: ~2000 species, ~40,000 reactions, ~100 catalysts."""
+
+    @pytest.mark.parametrize("seed", range(3))
+    def test_reaches_the_published_scale(self, seed):
+        """Across seeds, not just the lucky one -- these are ensemble claims."""
+        net = firing_disk_polymer(rng=np.random.default_rng(seed))    # paper defaults
+        assert 1500 <= net.n_molecules <= 2100
+        assert 20_000 <= net.n_reactions <= 45_000
+        n_cat = len({x for e in net.catalysts for g in e for x in g})
+        assert 40 <= n_cat <= 200, n_cat
+
+    @pytest.mark.parametrize("seed", range(3))
+    def test_raf_is_nearly_the_whole_chemistry(self, seed):
+        """Their large C-chemistries host 'a RAF often as large as the entire chemistry'."""
+        net = firing_disk_polymer(rng=np.random.default_rng(seed))
+        assert len(max_raf(net).reactions) > 0.8 * net.n_reactions
+
+    @pytest.mark.parametrize("seed", range(3))
+    def test_far_fewer_catalysts_than_a_k_chemistry_of_the_same_size(self, seed):
+        """Figure 3b's contrast: a C-catalyst drives many more reactions than a K one."""
+        c = firing_disk_polymer(rng=np.random.default_rng(seed))
+        k = binary_polymer(max_len=8, food_len=2, p=0.003, cleavage=True,
+                           rng=np.random.default_rng(seed))
+        per = lambda n: (sum(len(g) for e in n.catalysts for g in e)
+                         / max(len({x for e in n.catalysts for g in e for x in g}), 1))
+        assert per(c) > 5 * per(k)
+
+
+class TestValidation:
+    def test_probabilities_checked(self):
+        with pytest.raises(ValueError, match="is a probability"):
+            firing_disk_polymer(p_cat=2.0)
+
+    def test_site_bounds_checked(self):
+        with pytest.raises(ValueError, match="site_min <= site_max"):
+            firing_disk_polymer(site_min=5, site_max=3)

{rafkit-0.3.0 → rafkit-0.5.0}/tests/test_inhibition.py

@@ -237,3 +237,62 @@ class TestDownstreamUnderInhibition:
         u = max_urafs(net, inh, reactions=raf)[0]
         census = irrraf_census(net, u, n_samples=5, rng=np.random.default_rng(0))
         assert census["n_distinct"] >= 1
+
+
+# --- generated inhibition: binary_polymer's q / n_inhibitors -----------------------
+
+class TestGeneratedInhibition:
+    """`binary_polymer(q=..., n_inhibitors=...)` -- Hordijk & Steel (2012) Part II."""
+
+    def test_q_zero_leaves_network_uninhibited(self):
+        net = binary_polymer(max_len=5, food_len=2, p=0.01,
+                             rng=np.random.default_rng(0), cleavage=True)
+        assert all(not i for i in net.inhibitors)
+        assert net.n_inhibiting_molecules == 0
+        assert classes_from_inhibitors(net) == ()
+
+    def test_q_does_not_disturb_catalysis(self):
+        """Adding inhibition must not change the chemistry it is added to.
+
+        Every result recorded before inhibition existed was measured at q=0; if the
+        catalysis draw shifted, those numbers would silently stop reproducing.
+        """
+        kw = dict(max_len=5, food_len=2, p=0.01, cleavage=True)
+        a = binary_polymer(rng=np.random.default_rng(3), **kw)
+        b = binary_polymer(rng=np.random.default_rng(3), q=0.05, n_inhibitors=4, **kw)
+        assert a.catalysts == b.catalysts
+        assert a.reactions == b.reactions
+
+    def test_n_inhibitors_caps_k_exactly(self):
+        """`k` is the exponent in max_urafs' 2**k, so the cap must be exact, not a mean."""
+        for cap in (1, 3, 8):
+            net = binary_polymer(max_len=5, food_len=2, p=0.01, q=0.3,
+                                 n_inhibitors=cap, rng=np.random.default_rng(1),
+                                 cleavage=True)
+            assert net.n_inhibiting_molecules <= cap
+            assert len(classes_from_inhibitors(net)) == net.n_inhibiting_molecules
+
+    def test_paired_directions_share_inhibitors(self):
+        """A reversible cleavage-ligation pair is ONE unit, for inhibition as for catalysis."""
+        net = binary_polymer(max_len=5, food_len=2, p=0.01, q=0.1, n_inhibitors=5,
+                             rng=np.random.default_rng(2), cleavage=True,
+                             paired_catalysis=True)
+        half = net.n_reactions // 2
+        assert net.inhibitors[:half] == net.inhibitors[half:]
+
+    def test_inhibition_can_only_shrink_the_raf(self):
+        """u-RAFs are RAFs, so no u-RAF may exceed the uninhibited maximal RAF."""
+        kw = dict(max_len=5, food_len=2, p=0.02, cleavage=True)
+        base = binary_polymer(rng=np.random.default_rng(5), **kw)
+        inh = binary_polymer(rng=np.random.default_rng(5), q=0.02, n_inhibitors=6, **kw)
+        ceiling = len(max_raf(base).reactions)
+        for u in max_urafs(inh):
+            assert len(u) <= ceiling
+
+    def test_q_rejects_non_probability(self):
+        with pytest.raises(ValueError, match="q is a probability"):
+            binary_polymer(max_len=4, q=1.5)
+
+    def test_negative_n_inhibitors_rejected(self):
+        with pytest.raises(ValueError, match="n_inhibitors must be non-negative"):
+            binary_polymer(max_len=4, q=0.1, n_inhibitors=-1)

rafkit-0.5.0/tests/test_pnml.py

@@ -0,0 +1,124 @@
+"""PNML export.
+
+A catalytic reaction network is a Petri net, and exporting one makes it readable by
+that ecosystem. Three parts of the RAF model have no direct Place/Transition
+equivalent, and the tests that matter are the ones checking each is handled explicitly:
+catalysts become self-loops, alternative catalyst sets become separate transitions, and
+food gets source transitions so it cannot run out.
+
+Validated during development against **pm4py**, an independent PNML reader, which is
+how the double-hyphen bug below was found. pm4py is AGPL and is deliberately not a
+dependency; these tests use the standard library only.
+"""
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+
+import pytest
+
+from rafkit import parse_crs
+from rafkit.pnml import to_pnml, write_pnml
+
+NS = {"p": "http://www.pnml.org/version-2009/grammar/pnml"}
+
+
+def _parse(net, **kw):
+    return ET.fromstring(to_pnml(net, **kw))
+
+
+def _ids(root, tag):
+    return [e.get("id") for e in root.iterfind(f".//p:{tag}", NS)]
+
+
+def _labels(root, tag):
+    out = []
+    for e in root.iterfind(f".//p:{tag}", NS):
+        t = e.find("p:name/p:text", NS)
+        out.append(t.text if t is not None else None)
+    return out
+
+
+class TestWellFormedness:
+    def test_output_parses(self):
+        net = parse_crs("Food: a, b\nr1 : a + b [c] => c\n")
+        assert _parse(net).tag.endswith("pnml")
+
+    def test_header_comment_has_no_double_hyphen(self):
+        """Regression. The header is prepended as raw XML, so it bypasses
+        ElementTree's escaping entirely, and `--` inside a comment makes the whole
+        document unparseable. An independent PNML reader caught this; the export
+        itself was silent."""
+        net = parse_crs("Food: a, b\nr1 : a + b [c] {z} => c\nr2 : a [] => q\n")
+        text = to_pnml(net)
+        header = text[:text.index("<pnml")]
+        assert "--" not in header.replace("<!--", "").replace("-->", "")
+        ET.fromstring(text)          # would raise if it were not well-formed
+
+    def test_every_arc_endpoint_exists(self):
+        net = parse_crs("Food: a, b\nr1 : a + b [{c,d},e] => c\nr2 : a + c [c] => d\n")
+        root = _parse(net)
+        nodes = set(_ids(root, "place")) | set(_ids(root, "transition"))
+        for arc in root.iterfind(".//p:arc", NS):
+            assert arc.get("source") in nodes
+            assert arc.get("target") in nodes
+
+
+class TestMapping:
+    def test_places_are_molecules(self):
+        net = parse_crs("Food: a, b\nr1 : a + b [c] => c\n")
+        assert set(_labels(_parse(net), "place")) == set(net.molecules)
+
+    def test_alternative_catalyst_sets_become_separate_transitions(self):
+        """A transition's preset is a conjunction, so it cannot express "either set"."""
+        net = parse_crs("Food: a, b\nr1 : a + b [{c,d},e] => c\n")
+        labels = [l for l in _labels(_parse(net), "transition")
+                  if not l.startswith("source:")]
+        assert sorted(labels) == ["r1", "r1#2"]
+
+    def test_a_catalyst_becomes_a_self_loop(self):
+        net = parse_crs("Food: a, b\nr1 : a + b [c] => c\n")
+        root = _parse(net)
+        place = {l: i for i, l in zip(_ids(root, "place"), _labels(root, "place"))}
+        arcs = {(a.get("source"), a.get("target"))
+                for a in root.iterfind(".//p:arc", NS)}
+        # c catalyses r1: both directions must be present.
+        assert (place["c"], "t0") in arcs and ("t0", place["c"]) in arcs
+
+    def test_food_gets_source_transitions_so_it_cannot_run_out(self):
+        net = parse_crs("Food: a, b\nr1 : a + b [c] => c\n")
+        labels = _labels(_parse(net), "transition")
+        assert "source:a" in labels and "source:b" in labels
+
+    def test_food_sources_can_be_turned_off(self):
+        net = parse_crs("Food: a, b\nr1 : a + b [c] => c\n")
+        labels = _labels(_parse(net, food_sources=False), "transition")
+        assert not any(l.startswith("source:") for l in labels)
+
+
+class TestWhatCannotBeExpressed:
+    def test_reactions_that_can_never_fire_are_omitted_and_counted(self):
+        """chi = empty means "must be catalysed, and nothing does". Emitting it as an
+        unconstrained transition would make it freely fireable, the opposite of the
+        intent, so it is dropped and the header says how many."""
+        net = parse_crs("Food: a, b\nr1 : a + b [c] => c\nr2 : a [] => q\n")
+        text = to_pnml(net)
+        labels = [l for l in _labels(ET.fromstring(text), "transition")
+                  if not l.startswith("source:")]
+        assert labels == ["r1"]
+        assert "1 reaction(s) omitted" in text
+
+    def test_inhibition_is_recorded_and_flagged_as_lossy(self):
+        net = parse_crs("Food: a, b\nr1 : a + b [c] {z} => c\n")
+        text = to_pnml(net)
+        root = ET.fromstring(text)
+        ts = root.find(".//p:transition/p:toolspecific", NS)
+        assert ts is not None and ts.get("tool") == "rafkit"
+        assert ts.find("p:inhibitors", NS).text == "z"
+        assert "DIFFERENT system" in text     # the warning is not optional
+
+
+def test_write_pnml_round_trips_through_a_file(tmp_path):
+    net = parse_crs("Food: a, b\nr1 : a + b [c] => c\n")
+    path = tmp_path / "net.pnml"
+    write_pnml(net, path)
+    assert ET.parse(path).getroot().tag.endswith("pnml")