rafkit 0.7.0__tar.gz → 0.7.1__tar.gz

{rafkit-0.7.0/src/rafkit.egg-info → rafkit-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rafkit
-Version: 0.7.0
+Version: 0.7.1
 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
@@ -39,8 +39,9 @@ Dynamic: license-file
 [![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
-[CatReNet](https://github.com/husonlab/catrenet).
+cores, binary polymer chemistries whose catalysis is drawn, structured or templated, and
+interoperability with [CatReNet](https://github.com/husonlab/catrenet) and the Petri net
+tools.
 
 Pure Python and NumPy. No Java, no GUI, no install beyond `pip`.
 
@@ -115,10 +116,17 @@ counted as **one** catalysed reaction, not two. Use `net.catalysis_level` — no
 | `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 |
+| `binary_polymer` | Kauffman's K-BPM: catalysis by coin flip, with optional cleavage |
+| `complementary_polymer` | Serra & Villani's C-BPM: catalysis by active-site complementarity, not by coin flip |
+| `firing_disk_polymer` | their firing-disk construction — a chemistry *grown* from a seed, closed under its own production |
+| `templated_polymer` / `templated_catalysts` | templated ligation: a species catalyses `a + b -> ab` iff it carries the product's complement — nothing is drawn |
+| `degree_preserving_null` / `motif_matched_null` | same reactions, rewired catalysis — the nulls a structured chemistry is compared against |
+| `matched_f_random` / `matched_f_cbpm` | the K-BPM and C-BPM at a structured chemistry's catalysis level |
+| `catalysis_motifs` | what a chemistry and its nulls are compared on |
 | `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 |
+| `to_andl` / `write_andl` | ANDL export with mass-action rate constants — runs unchanged in Spike |
 | `simulate` | Gillespie direct method — watch subRAFs seed themselves into existence |
 | `max_urafs` | uninhibited RAFs, when a molecule can prevent a reaction |
 | `run_serial_dilution` / `run_cstr` | dilution protocols for growing–dividing compartments — **not a RAF algorithm**, see below |
@@ -133,6 +141,67 @@ counted as **one** catalysed reaction, not two. Use `net.catalysis_level` — no
 Every algorithm carries hand-computed known-answer tests, because a RAF algorithm that
 is subtly wrong produces plausible numbers rather than errors.
 
+## Catalysis three ways: drawn, structured, and templated
+
+`binary_polymer` is Kauffman's K-BPM: every string up to `max_len` exists, and whether a
+species catalyses a reaction is an independent coin flip at probability `p`. Two more
+ensembles keep that reaction set and change the one thing that matters — *which* catalyst
+catalyses *which* reaction.
+
+**`complementary_polymer`** is Serra & Villani's C-BPM (*Entropy* 28(2), 184, 2026),
+reproduced rather than invented. A catalyst carries an active site — a substring of itself,
+3–4 residues long by default — and acts on whatever is complementary to that site. A
+K-catalyst's targets are independent draws; a C-catalyst's targets all share one template,
+so they are structurally correlated, and Serra & Villani measure the signature of that as a
+far higher and far more irregular reactions-per-catalyst distribution (~400 against ~20).
+**`firing_disk_polymer`** is their other construction. Rather than enumerating every string
+and sprinkling catalysis over the result, it grows the chemistry outward from a small seed,
+so a species exists only if some reaction actually makes it: an enumerated chemistry is
+full of species nothing can reach, and a grown one is closed under its own production by
+construction. ⚠ Food is taken to be the firing disk, an assumption the paper leaves open.
+
+**`templated_polymer`** draws nothing. A species templates the ligation `a + b -> ab`
+exactly when it contains the (reverse) complement of the product — or, under
+`rule="junction"`, of the `2h` residues spanning the junction — given both reactants reach
+the per-side overlap `h`. The catalysis graph is a *function* of the sequence set, which is
+the content of a template world and the reason this generator has no `rng` argument. The
+cleavage carries its ligation's templates, so a template changes a reversible reaction's
+rate and never its equilibrium. `templated_catalysts` is the same rule as a pure function
+over whatever strands exist, for a simulator that holds explicit strands.
+
+Sized on the complete `max_len` 7 set, the two rules behave very differently, and the
+numbers are pinned as known answers:
+
+| | |
+|---|---|
+| junction rule, `h` ≤ 2 | **saturates** — every eligible reaction templated by 194 or 46 species, f = 978 and 142 against ~5 for a random chemistry at the RAF threshold: a uniform speed-up with no specificity left |
+| product rule, `h` 2 | f = 12.9, with the template count *falling* with product length — 46 for a 4-mer, exactly one for a 7-mer, its own complement |
+| either rule, `h` 3 | the **maximal RAF is empty**: templated reactions need reactants of length ≥ `h`, and only untemplated reactions make those from a food set shorter than `h` |
+
+The last row is the one to remember. `max_raf` remains the right question about closure
+and the wrong one about whether templating acts — the chemistry is perfectly runnable on an
+uncatalysed background.
+
+**A structured chemistry needs something to be compared against**, and "random at the same
+f" is a poor choice: at a templated f, a random chemistry spreads its edges over nearly
+every reaction (reach ~0.92 against the product rule's 0.61). So each null holds something
+different fixed, and `catalysis_motifs` reports what they are compared on — f, reach,
+catalysts per reaction by product length, self-catalysed reactions, mutual pairs, and the
+maximal RAF's size, all counted on the reversible pair:
+
+- `degree_preserving_null` — a double-edge-swap chain keeping every degree;
+  `stratified=True` also keeps the *lengths* of each reaction's templates, which the plain
+  shuffle breaks along with the sequence tie.
+- `motif_matched_null` — random catalysis with exactly the network's edge count,
+  self-catalysed reactions and mutual pairs; `match_lengths=True` plants them at the
+  network's own lengths, without which it is a second random chemistry with two counts
+  pinned.
+- `matched_f_random` / `matched_f_cbpm` — the K-BPM and C-BPM at the network's catalysis
+  level, in expectation.
+
+Every one of these returns the same `BinaryPolymerNetwork`, so everything in the table
+above runs on them unchanged.
+
 ## Four modules are deliberately off-theme: `dilution`, `permeation`, `thermo` and `autocatalysis`
 
 Everything above takes a `ReactionNetwork` and asks a RAF question of it. `rafkit.dilution`
@@ -388,6 +457,33 @@ 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.
 
+### Readable is not runnable: `to_andl`
+
+PNML's `ptnet` grammar has no place for a rate constant, so a PNML file documents a
+network without being able to run it. `to_andl` / `write_andl` export the same network to
+ANDL, the PetriNuts format shared by Snoopy, Spike and Marcie, with mass-action rate
+constants — a complete stochastic Petri net that Spike executes directly. An independently
+developed simulator re-running this chemistry from its definition is the entire point.
+
+The semantics are mass action and nothing else, and they were **measured** against Spike
+1.6.0rc2 rather than read from its documentation: a catalyst is a consume-and-produce
+self-loop, so the propensity scales with catalyst count; alternative catalyst sets are
+separate transitions whose propensities sum; and `a + a -> aa` is a weight-2 arc counted
+as unordered pairs, `n(n−1)/2`, with the alternatives 19–25 standard errors away.
+⚠ Catalysis scaling with catalyst count is *not* what `simulate` does — there any catalyst
+present buys the full rate — so this export runs a different system from the in-library
+simulator, deliberately; the pair convention, on the other hand, is `simulate`'s exactly.
+Rate constants are emitted as named constants, so a Spike `.spc` configuration can override
+any single rate without regenerating the file.
+
+Refused rather than silently altered, because an executable file that drops a feature does
+not *document* a different system, it **runs** one: inhibition (PNML may annotate it, since
+a reader sees the annotation; a simulator would not), and a catalyst that is also a
+reactant of the same reaction, whose self-loop merges with the consuming arc into a
+weight-2 pre-arc with implementation-dependent combinatorics. The latter means a
+`templated_polymer` network, in which a template can be its own reactant, is refused until
+someone measures what Spike does with it.
+
 ## Catalysis is a relation, not a list
 
 `catalysts[r]` is a set of **alternative catalyst sets**, following Huson, Xavier &

{rafkit-0.7.0 → rafkit-0.7.1}/README.md

@@ -8,8 +8,9 @@
 [![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
-[CatReNet](https://github.com/husonlab/catrenet).
+cores, binary polymer chemistries whose catalysis is drawn, structured or templated, and
+interoperability with [CatReNet](https://github.com/husonlab/catrenet) and the Petri net
+tools.
 
 Pure Python and NumPy. No Java, no GUI, no install beyond `pip`.
 
@@ -84,10 +85,17 @@ counted as **one** catalysed reaction, not two. Use `net.catalysis_level` — no
 | `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 |
+| `binary_polymer` | Kauffman's K-BPM: catalysis by coin flip, with optional cleavage |
+| `complementary_polymer` | Serra & Villani's C-BPM: catalysis by active-site complementarity, not by coin flip |
+| `firing_disk_polymer` | their firing-disk construction — a chemistry *grown* from a seed, closed under its own production |
+| `templated_polymer` / `templated_catalysts` | templated ligation: a species catalyses `a + b -> ab` iff it carries the product's complement — nothing is drawn |
+| `degree_preserving_null` / `motif_matched_null` | same reactions, rewired catalysis — the nulls a structured chemistry is compared against |
+| `matched_f_random` / `matched_f_cbpm` | the K-BPM and C-BPM at a structured chemistry's catalysis level |
+| `catalysis_motifs` | what a chemistry and its nulls are compared on |
 | `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 |
+| `to_andl` / `write_andl` | ANDL export with mass-action rate constants — runs unchanged in Spike |
 | `simulate` | Gillespie direct method — watch subRAFs seed themselves into existence |
 | `max_urafs` | uninhibited RAFs, when a molecule can prevent a reaction |
 | `run_serial_dilution` / `run_cstr` | dilution protocols for growing–dividing compartments — **not a RAF algorithm**, see below |
@@ -102,6 +110,67 @@ counted as **one** catalysed reaction, not two. Use `net.catalysis_level` — no
 Every algorithm carries hand-computed known-answer tests, because a RAF algorithm that
 is subtly wrong produces plausible numbers rather than errors.
 
+## Catalysis three ways: drawn, structured, and templated
+
+`binary_polymer` is Kauffman's K-BPM: every string up to `max_len` exists, and whether a
+species catalyses a reaction is an independent coin flip at probability `p`. Two more
+ensembles keep that reaction set and change the one thing that matters — *which* catalyst
+catalyses *which* reaction.
+
+**`complementary_polymer`** is Serra & Villani's C-BPM (*Entropy* 28(2), 184, 2026),
+reproduced rather than invented. A catalyst carries an active site — a substring of itself,
+3–4 residues long by default — and acts on whatever is complementary to that site. A
+K-catalyst's targets are independent draws; a C-catalyst's targets all share one template,
+so they are structurally correlated, and Serra & Villani measure the signature of that as a
+far higher and far more irregular reactions-per-catalyst distribution (~400 against ~20).
+**`firing_disk_polymer`** is their other construction. Rather than enumerating every string
+and sprinkling catalysis over the result, it grows the chemistry outward from a small seed,
+so a species exists only if some reaction actually makes it: an enumerated chemistry is
+full of species nothing can reach, and a grown one is closed under its own production by
+construction. ⚠ Food is taken to be the firing disk, an assumption the paper leaves open.
+
+**`templated_polymer`** draws nothing. A species templates the ligation `a + b -> ab`
+exactly when it contains the (reverse) complement of the product — or, under
+`rule="junction"`, of the `2h` residues spanning the junction — given both reactants reach
+the per-side overlap `h`. The catalysis graph is a *function* of the sequence set, which is
+the content of a template world and the reason this generator has no `rng` argument. The
+cleavage carries its ligation's templates, so a template changes a reversible reaction's
+rate and never its equilibrium. `templated_catalysts` is the same rule as a pure function
+over whatever strands exist, for a simulator that holds explicit strands.
+
+Sized on the complete `max_len` 7 set, the two rules behave very differently, and the
+numbers are pinned as known answers:
+
+| | |
+|---|---|
+| junction rule, `h` ≤ 2 | **saturates** — every eligible reaction templated by 194 or 46 species, f = 978 and 142 against ~5 for a random chemistry at the RAF threshold: a uniform speed-up with no specificity left |
+| product rule, `h` 2 | f = 12.9, with the template count *falling* with product length — 46 for a 4-mer, exactly one for a 7-mer, its own complement |
+| either rule, `h` 3 | the **maximal RAF is empty**: templated reactions need reactants of length ≥ `h`, and only untemplated reactions make those from a food set shorter than `h` |
+
+The last row is the one to remember. `max_raf` remains the right question about closure
+and the wrong one about whether templating acts — the chemistry is perfectly runnable on an
+uncatalysed background.
+
+**A structured chemistry needs something to be compared against**, and "random at the same
+f" is a poor choice: at a templated f, a random chemistry spreads its edges over nearly
+every reaction (reach ~0.92 against the product rule's 0.61). So each null holds something
+different fixed, and `catalysis_motifs` reports what they are compared on — f, reach,
+catalysts per reaction by product length, self-catalysed reactions, mutual pairs, and the
+maximal RAF's size, all counted on the reversible pair:
+
+- `degree_preserving_null` — a double-edge-swap chain keeping every degree;
+  `stratified=True` also keeps the *lengths* of each reaction's templates, which the plain
+  shuffle breaks along with the sequence tie.
+- `motif_matched_null` — random catalysis with exactly the network's edge count,
+  self-catalysed reactions and mutual pairs; `match_lengths=True` plants them at the
+  network's own lengths, without which it is a second random chemistry with two counts
+  pinned.
+- `matched_f_random` / `matched_f_cbpm` — the K-BPM and C-BPM at the network's catalysis
+  level, in expectation.
+
+Every one of these returns the same `BinaryPolymerNetwork`, so everything in the table
+above runs on them unchanged.
+
 ## Four modules are deliberately off-theme: `dilution`, `permeation`, `thermo` and `autocatalysis`
 
 Everything above takes a `ReactionNetwork` and asks a RAF question of it. `rafkit.dilution`
@@ -357,6 +426,33 @@ 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.
 
+### Readable is not runnable: `to_andl`
+
+PNML's `ptnet` grammar has no place for a rate constant, so a PNML file documents a
+network without being able to run it. `to_andl` / `write_andl` export the same network to
+ANDL, the PetriNuts format shared by Snoopy, Spike and Marcie, with mass-action rate
+constants — a complete stochastic Petri net that Spike executes directly. An independently
+developed simulator re-running this chemistry from its definition is the entire point.
+
+The semantics are mass action and nothing else, and they were **measured** against Spike
+1.6.0rc2 rather than read from its documentation: a catalyst is a consume-and-produce
+self-loop, so the propensity scales with catalyst count; alternative catalyst sets are
+separate transitions whose propensities sum; and `a + a -> aa` is a weight-2 arc counted
+as unordered pairs, `n(n−1)/2`, with the alternatives 19–25 standard errors away.
+⚠ Catalysis scaling with catalyst count is *not* what `simulate` does — there any catalyst
+present buys the full rate — so this export runs a different system from the in-library
+simulator, deliberately; the pair convention, on the other hand, is `simulate`'s exactly.
+Rate constants are emitted as named constants, so a Spike `.spc` configuration can override
+any single rate without regenerating the file.
+
+Refused rather than silently altered, because an executable file that drops a feature does
+not *document* a different system, it **runs** one: inhibition (PNML may annotate it, since
+a reader sees the annotation; a simulator would not), and a catalyst that is also a
+reactant of the same reaction, whose self-loop merges with the consuming arc into a
+weight-2 pre-arc with implementation-dependent combinatorics. The latter means a
+`templated_polymer` network, in which a template can be its own reactant, is refused until
+someone measures what Spike does with it.
+
 ## Catalysis is a relation, not a list
 
 `catalysts[r]` is a set of **alternative catalyst sets**, following Huson, Xavier &

{rafkit-0.7.0 → rafkit-0.7.1}/pyproject.toml

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

@@ -59,7 +59,7 @@ from rafkit.raf import (
     sample_irrraf,
 )
 
-__version__ = "0.7.0"
+__version__ = "0.7.1"
 
 __all__ = [
     "BinaryPolymerNetwork", "binary_polymer",

{rafkit-0.7.0 → rafkit-0.7.1}/src/rafkit/binary_polymer.py

@@ -102,29 +102,49 @@ class BinaryPolymerNetwork:
     def n_cleavages(self) -> int:
         return sum(1 for d in self.directions if d < 0)
 
+    def pair_index(self) -> list[tuple[int, int | None]]:
+        """The reversible pairs as (ligation entry, cleavage entry or None), ONE source for every
+        pair-wise consumer. The standard layout -- every ligation first, then every cleavage,
+        `i` with `i + n` -- is recognised by position; any other layout (a designed chemistry
+        stores +1, -1 per reaction) is paired by the reaction TRIPLE, a cleavage with the
+        ligation of the same (a, b, ab). Refused: a triple stored twice in one direction, or a
+        cleavage with no ligation -- read with unrelated reactions unioned is the failure this
+        exists to close (review of PR 17)."""
+        n_c = self.n_cleavages
+        n = self.n_reactions - n_c
+        if n_c == 0:
+            return [(i, None) for i in range(self.n_reactions)]
+        if (n_c == n and tuple(self.directions[:n]) == (1,) * n
+                and all(self.reactions[i] == self.reactions[i + n] for i in range(n))):
+            return [(i, i + n) for i in range(n)]
+        lig = {}
+        for i, (trip, d) in enumerate(zip(self.reactions, self.directions)):
+            if d > 0:
+                if trip in lig:
+                    raise ValueError(f"the ligation {trip} is stored twice; reversible pairs are ambiguous")
+                lig[trip] = i
+        out = {i: None for i in lig.values()}
+        for j, (trip, d) in enumerate(zip(self.reactions, self.directions)):
+            if d < 0:
+                if trip not in lig:
+                    raise ValueError(f"the cleavage {trip} (reaction {j}) has no ligation to pair with")
+                if out[lig[trip]] is not None:
+                    raise ValueError(f"the cleavage {trip} is stored twice; reversible pairs are ambiguous")
+                out[lig[trip]] = j
+        return sorted(out.items())
+
     @property
     def n_pairs(self) -> int:
-        """Reversible pairs, under the ONE layout every pair-wise consumer assumes: every
-        ligation first, then (optionally) every cleavage, reaction ``i`` paired with
-        ``i + n``. Refused otherwise -- a network with the right count and interleaved
-        directions would otherwise be read with unrelated reactions unioned."""
-        n = self.n_reactions - self.n_cleavages
-        if self.n_cleavages not in (0, n):
-            raise ValueError("expected every ligation, optionally followed by every cleavage: "
-                             f"{n} ligations and {self.n_cleavages} cleavages")
-        if tuple(self.directions[:n]) != (1,) * n or tuple(self.directions[n:]) != (-1,) * self.n_cleavages:
-            raise ValueError("expected every ligation first, then every cleavage, reaction i "
-                             "paired with i + n; the directions are interleaved")
-        return n
+        """Reversible pairs (a ligation with its cleavage, or a ligation alone)."""
+        return len(self.pair_index())
 
     def pair_catalysts(self) -> list[frozenset]:
         """Per reversible pair, the union of the two directions' catalyst sets (the raw
         conjunctive groups). Under `paired_catalysis` the halves are identical and this is
         each ligation's own set; it differs only where the directions were drawn separately
         -- as in C-BPM, where a catalyst acts on one direction only."""
-        n = self.n_pairs
-        return [self.catalysts[i] | self.catalysts[i + n] if self.n_cleavages else self.catalysts[i]
-                for i in range(n)]
+        return [self.catalysts[i] if j is None else self.catalysts[i] | self.catalysts[j]
+                for i, j in self.pair_index()]
 
     @property
     def catalysis_level(self) -> float:

{rafkit-0.7.0 → rafkit-0.7.1}/src/rafkit/templated_polymer.py

@@ -155,11 +155,10 @@ def _edges(net: BinaryPolymerNetwork) -> int:
 def _simple_paired_edges(net: BinaryPolymerNetwork) -> list[tuple[int, int]]:
     """The (template, pair) edges of a network whose catalysis is disjunctive and paired --
     what a rewiring null can preserve. Anything else is refused rather than flattened."""
-    n = _n_pairs(net)
-    for i in range(n):
+    for i, j in net.pair_index():
         if any(len(group) != 1 for group in net.catalysts[i]):
             raise ValueError("a rewiring null needs disjunctive (singleton) catalyst sets")
-        if net.n_cleavages and net.catalysts[i] != net.catalysts[i + n]:
+        if j is not None and net.catalysts[i] != net.catalysts[j]:
             raise ValueError("a rewiring null needs paired catalysis: a ligation and its "
                              "cleavage sharing one catalyst set")
     return [(t, i) for i, c in enumerate(_pair_catalysts(net)) for t in sorted(c)]
@@ -167,10 +166,17 @@ def _simple_paired_edges(net: BinaryPolymerNetwork) -> list[tuple[int, int]]:
 
 def _with_pair_catalysts(net: BinaryPolymerNetwork, cats: Sequence[frozenset[int]]
                          ) -> BinaryPolymerNetwork:
-    drawn = tuple(frozenset(c) for c in cats)
+    """`net` with each reversible pair's catalyst set replaced; the two halves of a pair
+    receive the same set whatever the layout (`pair_index`)."""
+    by_entry = [frozenset()] * net.n_reactions
+    for (i, j), c in zip(net.pair_index(), cats):
+        by_entry[i] = frozenset(c)
+        if j is not None:
+            by_entry[j] = frozenset(c)
+    drawn = tuple(by_entry)
     return BinaryPolymerNetwork(
         molecules=net.molecules, food=net.food, reactions=net.reactions,
-        catalysts=drawn + drawn if net.n_cleavages else drawn, p=net.p, max_len=net.max_len,
+        catalysts=drawn, p=net.p, max_len=net.max_len,
         food_len=net.food_len, directions=net.directions, inhibitors=net.inhibitors)
 
 
@@ -204,7 +210,7 @@ def catalysis_motifs(net: BinaryPolymerNetwork, *, raf: bool = True) -> dict:
     """
     cats = _pair_catalysts(net)
     n = len(cats)
-    product = [net.reactions[i][2] for i in range(n)]
+    product = [net.reactions[i][2] for i, _ in net.pair_index()]
     edges = sum(len(c) for c in cats)
     catalysed = [i for i in range(n) if cats[i]]
     by_len: dict[int, list[int]] = {}
@@ -329,7 +335,7 @@ def motif_matched_null(net: BinaryPolymerNetwork, rng: np.random.Generator, *,
     target = catalysis_motifs(net, raf=False)
     n = _n_pairs(net)
     _simple_paired_edges(net)                               # refuse what cannot be matched
-    product = [net.reactions[i][2] for i in range(n)]
+    product = [net.reactions[i][2] for i, _ in net.pair_index()]
     making: dict[int, list[int]] = {}
     for i, q in enumerate(product):
         making.setdefault(q, []).append(i)

{rafkit-0.7.0 → rafkit-0.7.1/src/rafkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rafkit
-Version: 0.7.0
+Version: 0.7.1
 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
@@ -39,8 +39,9 @@ Dynamic: license-file
 [![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
-[CatReNet](https://github.com/husonlab/catrenet).
+cores, binary polymer chemistries whose catalysis is drawn, structured or templated, and
+interoperability with [CatReNet](https://github.com/husonlab/catrenet) and the Petri net
+tools.
 
 Pure Python and NumPy. No Java, no GUI, no install beyond `pip`.
 
@@ -115,10 +116,17 @@ counted as **one** catalysed reaction, not two. Use `net.catalysis_level` — no
 | `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 |
+| `binary_polymer` | Kauffman's K-BPM: catalysis by coin flip, with optional cleavage |
+| `complementary_polymer` | Serra & Villani's C-BPM: catalysis by active-site complementarity, not by coin flip |
+| `firing_disk_polymer` | their firing-disk construction — a chemistry *grown* from a seed, closed under its own production |
+| `templated_polymer` / `templated_catalysts` | templated ligation: a species catalyses `a + b -> ab` iff it carries the product's complement — nothing is drawn |
+| `degree_preserving_null` / `motif_matched_null` | same reactions, rewired catalysis — the nulls a structured chemistry is compared against |
+| `matched_f_random` / `matched_f_cbpm` | the K-BPM and C-BPM at a structured chemistry's catalysis level |
+| `catalysis_motifs` | what a chemistry and its nulls are compared on |
 | `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 |
+| `to_andl` / `write_andl` | ANDL export with mass-action rate constants — runs unchanged in Spike |
 | `simulate` | Gillespie direct method — watch subRAFs seed themselves into existence |
 | `max_urafs` | uninhibited RAFs, when a molecule can prevent a reaction |
 | `run_serial_dilution` / `run_cstr` | dilution protocols for growing–dividing compartments — **not a RAF algorithm**, see below |
@@ -133,6 +141,67 @@ counted as **one** catalysed reaction, not two. Use `net.catalysis_level` — no
 Every algorithm carries hand-computed known-answer tests, because a RAF algorithm that
 is subtly wrong produces plausible numbers rather than errors.
 
+## Catalysis three ways: drawn, structured, and templated
+
+`binary_polymer` is Kauffman's K-BPM: every string up to `max_len` exists, and whether a
+species catalyses a reaction is an independent coin flip at probability `p`. Two more
+ensembles keep that reaction set and change the one thing that matters — *which* catalyst
+catalyses *which* reaction.
+
+**`complementary_polymer`** is Serra & Villani's C-BPM (*Entropy* 28(2), 184, 2026),
+reproduced rather than invented. A catalyst carries an active site — a substring of itself,
+3–4 residues long by default — and acts on whatever is complementary to that site. A
+K-catalyst's targets are independent draws; a C-catalyst's targets all share one template,
+so they are structurally correlated, and Serra & Villani measure the signature of that as a
+far higher and far more irregular reactions-per-catalyst distribution (~400 against ~20).
+**`firing_disk_polymer`** is their other construction. Rather than enumerating every string
+and sprinkling catalysis over the result, it grows the chemistry outward from a small seed,
+so a species exists only if some reaction actually makes it: an enumerated chemistry is
+full of species nothing can reach, and a grown one is closed under its own production by
+construction. ⚠ Food is taken to be the firing disk, an assumption the paper leaves open.
+
+**`templated_polymer`** draws nothing. A species templates the ligation `a + b -> ab`
+exactly when it contains the (reverse) complement of the product — or, under
+`rule="junction"`, of the `2h` residues spanning the junction — given both reactants reach
+the per-side overlap `h`. The catalysis graph is a *function* of the sequence set, which is
+the content of a template world and the reason this generator has no `rng` argument. The
+cleavage carries its ligation's templates, so a template changes a reversible reaction's
+rate and never its equilibrium. `templated_catalysts` is the same rule as a pure function
+over whatever strands exist, for a simulator that holds explicit strands.
+
+Sized on the complete `max_len` 7 set, the two rules behave very differently, and the
+numbers are pinned as known answers:
+
+| | |
+|---|---|
+| junction rule, `h` ≤ 2 | **saturates** — every eligible reaction templated by 194 or 46 species, f = 978 and 142 against ~5 for a random chemistry at the RAF threshold: a uniform speed-up with no specificity left |
+| product rule, `h` 2 | f = 12.9, with the template count *falling* with product length — 46 for a 4-mer, exactly one for a 7-mer, its own complement |
+| either rule, `h` 3 | the **maximal RAF is empty**: templated reactions need reactants of length ≥ `h`, and only untemplated reactions make those from a food set shorter than `h` |
+
+The last row is the one to remember. `max_raf` remains the right question about closure
+and the wrong one about whether templating acts — the chemistry is perfectly runnable on an
+uncatalysed background.
+
+**A structured chemistry needs something to be compared against**, and "random at the same
+f" is a poor choice: at a templated f, a random chemistry spreads its edges over nearly
+every reaction (reach ~0.92 against the product rule's 0.61). So each null holds something
+different fixed, and `catalysis_motifs` reports what they are compared on — f, reach,
+catalysts per reaction by product length, self-catalysed reactions, mutual pairs, and the
+maximal RAF's size, all counted on the reversible pair:
+
+- `degree_preserving_null` — a double-edge-swap chain keeping every degree;
+  `stratified=True` also keeps the *lengths* of each reaction's templates, which the plain
+  shuffle breaks along with the sequence tie.
+- `motif_matched_null` — random catalysis with exactly the network's edge count,
+  self-catalysed reactions and mutual pairs; `match_lengths=True` plants them at the
+  network's own lengths, without which it is a second random chemistry with two counts
+  pinned.
+- `matched_f_random` / `matched_f_cbpm` — the K-BPM and C-BPM at the network's catalysis
+  level, in expectation.
+
+Every one of these returns the same `BinaryPolymerNetwork`, so everything in the table
+above runs on them unchanged.
+
 ## Four modules are deliberately off-theme: `dilution`, `permeation`, `thermo` and `autocatalysis`
 
 Everything above takes a `ReactionNetwork` and asks a RAF question of it. `rafkit.dilution`
@@ -388,6 +457,33 @@ 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.
 
+### Readable is not runnable: `to_andl`
+
+PNML's `ptnet` grammar has no place for a rate constant, so a PNML file documents a
+network without being able to run it. `to_andl` / `write_andl` export the same network to
+ANDL, the PetriNuts format shared by Snoopy, Spike and Marcie, with mass-action rate
+constants — a complete stochastic Petri net that Spike executes directly. An independently
+developed simulator re-running this chemistry from its definition is the entire point.
+
+The semantics are mass action and nothing else, and they were **measured** against Spike
+1.6.0rc2 rather than read from its documentation: a catalyst is a consume-and-produce
+self-loop, so the propensity scales with catalyst count; alternative catalyst sets are
+separate transitions whose propensities sum; and `a + a -> aa` is a weight-2 arc counted
+as unordered pairs, `n(n−1)/2`, with the alternatives 19–25 standard errors away.
+⚠ Catalysis scaling with catalyst count is *not* what `simulate` does — there any catalyst
+present buys the full rate — so this export runs a different system from the in-library
+simulator, deliberately; the pair convention, on the other hand, is `simulate`'s exactly.
+Rate constants are emitted as named constants, so a Spike `.spc` configuration can override
+any single rate without regenerating the file.
+
+Refused rather than silently altered, because an executable file that drops a feature does
+not *document* a different system, it **runs** one: inhibition (PNML may annotate it, since
+a reader sees the annotation; a simulator would not), and a catalyst that is also a
+reactant of the same reaction, whose self-loop merges with the consuming arc into a
+weight-2 pre-arc with implementation-dependent combinatorics. The latter means a
+`templated_polymer` network, in which a template can be its own reactant, is refused until
+someone measures what Spike does with it.
+
 ## Catalysis is a relation, not a list
 
 `catalysts[r]` is a set of **alternative catalyst sets**, following Huson, Xavier &

{rafkit-0.7.0 → rafkit-0.7.1}/tests/test_templated_polymer.py

@@ -322,9 +322,10 @@ class TestMotifs:
 class TestGuards:
     """Review of 5a3c5a8 / 14e13f1 (PR 17): the layout, the loops and the edges that were unguarded."""
 
-    def test_an_interleaved_layout_is_refused_not_misread(self):
-        """Every pair-wise consumer reads reaction i with i + n. A network with the right COUNT
-        of cleavages but ligation, cleavage, ligation, ... would union unrelated reactions."""
+    def test_an_interleaved_layout_is_paired_by_its_triples(self):
+        """Every pair-wise consumer reads a pair as (ligation, its cleavage). The standard layout is
+        by position; a designed chemistry storing +1, -1 per reaction is paired by the triple and
+        reads IDENTICALLY -- the same f, the same motifs, the same null degrees."""
         from rafkit.binary_polymer import BinaryPolymerNetwork
         net = templated_polymer(max_len=5)
         n = net.n_reactions // 2
@@ -333,12 +334,32 @@ class TestGuards:
             molecules=net.molecules, food=net.food, reactions=tuple(net.reactions[k] for k in order),
             catalysts=tuple(net.catalysts[k] for k in order), p=net.p, max_len=net.max_len,
             food_len=net.food_len, directions=tuple(net.directions[k] for k in order))
-        assert mixed.n_cleavages == n                      # the count alone would pass
-        for read in (lambda: mixed.n_pairs, lambda: mixed.catalysis_level, lambda: catalysis_motifs(mixed),
-                     lambda: degree_preserving_null(mixed, np.random.default_rng(0))):
-            with pytest.raises(ValueError, match="interleaved"):
-                read()
-        assert net.n_pairs == n and len(net.pair_catalysts()) == n
+        assert mixed.n_pairs == net.n_pairs == n
+        assert mixed.pair_index() == [(2 * i, 2 * i + 1) for i in range(n)]
+        assert mixed.catalysis_level == net.catalysis_level
+        a, b = catalysis_motifs(net), catalysis_motifs(mixed)
+        assert a == b
+        null = degree_preserving_null(mixed, np.random.default_rng(0))
+        assert null.catalysts[0::2] == null.catalysts[1::2]            # the halves still share one set
+        # the same degrees as the standard layout's null from the same seed, read through the pairs
+        ref = degree_preserving_null(net, np.random.default_rng(0))
+        deg = lambda x: sorted(len(x.catalysts[i]) for i, _ in x.pair_index())
+        assert deg(null) == deg(ref) and deg(mixed) == deg(net)
+
+    def test_a_cleavage_without_its_ligation_is_refused(self):
+        from rafkit.binary_polymer import BinaryPolymerNetwork
+        net = templated_polymer(max_len=4)
+        n = net.n_reactions // 2
+        # drop one ligation, keep its cleavage: no triple to pair with
+        keep = [k for k in range(net.n_reactions) if k != 0]
+        orphan = BinaryPolymerNetwork(
+            molecules=net.molecules, food=net.food, reactions=tuple(net.reactions[k] for k in keep),
+            catalysts=tuple(net.catalysts[k] for k in keep), p=net.p, max_len=net.max_len,
+            food_len=net.food_len, directions=tuple(net.directions[k] for k in keep))
+        with pytest.raises(ValueError, match="no ligation to pair"):
+            orphan.n_pairs
+        with pytest.raises(ValueError, match="no ligation to pair"):
+            catalysis_motifs(orphan)
 
     def test_blocked_proposals_are_the_sequential_stream(self):
         from rafkit.templated_polymer import _proposals