rafkit 0.6.0__tar.gz → 0.7.1__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rafkit
-Version: 0.6.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.6.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.6.0 → rafkit-0.7.1}/pyproject.toml

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

@@ -29,6 +29,10 @@ 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.templated_polymer import (catalysis_motifs, degree_preserving_null,
+                                      matched_f_cbpm, matched_f_random,
+                                      motif_matched_null, templated_catalysts,
+                                      templated_polymer)
 from rafkit.catalysis import catalysing_molecules, is_catalysed, normalise
 from rafkit.crs import parse_crs, read_crs, to_crs, write_crs
 from rafkit.dilution import (DilutionResult, flux_linear, flux_quadratic,
@@ -37,6 +41,7 @@ from rafkit.dilution import (DilutionResult, flux_linear, flux_quadratic,
 from rafkit.gillespie import Trajectory, propensities, simulate
 from rafkit.inhibition import (classes_from_inhibitors, is_uninhibited, is_uraf,
                                max_urafs, support)
+from rafkit.andl import to_andl, write_andl
 from rafkit.network import ReactionNetwork
 from rafkit.permeation import permeable_by_length, permeation_flux
 from rafkit.pnml import to_pnml, write_pnml
@@ -54,13 +59,15 @@ from rafkit.raf import (
     sample_irrraf,
 )
 
-__version__ = "0.6.0"
+__version__ = "0.7.1"
 
 __all__ = [
     "BinaryPolymerNetwork", "binary_polymer",
     "Consistency", "is_thermodynamically_consistent", "stoichiometry", "affinities",
     "complementary_polymer",
     "firing_disk_polymer",
+    "templated_polymer", "templated_catalysts", "catalysis_motifs",
+    "degree_preserving_null", "motif_matched_null", "matched_f_random", "matched_f_cbpm",
     "complement", "ReactionNetwork",
     "RafResult", "max_raf", "max_raf_strict", "sample_irrraf", "irrraf_census",
     "exploitability", "is_food_catalysed", "catrenet_strictly_autocatalytic",
@@ -77,6 +84,7 @@ __all__ = [
     "detailed_balance_residual", "transfer_matrix", "elongation_ratio", "mean_length",
     "sequence_correlation_length", "unpaired_catalysis",
     "Kinetics", "kinetics_from_energies",
+    "to_andl", "write_andl",
     "to_pnml", "write_pnml",
     "simulate", "propensities", "Trajectory",
     "max_urafs", "is_uraf", "is_uninhibited", "support", "classes_from_inhibitors",

rafkit-0.7.1/src/rafkit/andl.py

@@ -0,0 +1,301 @@
+"""Export to ANDL, the PetriNuts framework's executable Petri net format.
+
+`rafkit.pnml` makes a network *readable* by the Petri net ecosystem; this module makes it
+*runnable*. ANDL (the plain-text format shared by Snoopy, Spike and Marcie) carries what
+PNML's ``ptnet`` grammar cannot: stochastic rate constants. A file written here is a
+complete stochastic Petri net that Spike executes directly -- an independently developed
+simulator re-running this chemistry from its definition, which is the entire point.
+
+**The semantics exported are mass action, and nothing else.** Every transition's
+propensity is its rate constant times the falling-factorial count product over its
+pre-places -- what Gillespie's direct method computes and what Spike's ``MassAction``
+was *measured* to compute (2026-08-29, three-toy calibration; see
+``docs/DESIGN_candl_exporter.md`` in the abiogenesis repository):
+
+* a catalyst becomes a **consume-and-produce self-loop**, so it multiplies the
+  propensity by its count and is required to be present. This matches chemistries whose
+  catalysis is mass action in the catalyst count. It does **not** match
+  `rafkit.gillespie`, whose catalysis is a threshold -- any catalyst present buys the
+  full rate, and the propensity does not scale with catalyst count. That is a different
+  system, and this module makes no attempt to encode it.
+* alternative catalyst sets become **separate transitions** whose propensities sum --
+  which *is* the mass-action reading of "either catalyses": each catalytic channel is
+  its own elementary reaction. ⚠ Channel names are MANGLED into the emitted ids
+  (``r1``'s second channel becomes ``t_4_r1_2``, not ``r1#2``): the authoritative
+  spelling of every id and rate constant is the generated file itself, and any id that
+  needed a disambiguating suffix is listed in the file's header. Read the file before
+  writing a ``.spc`` override.
+* a catalyst set that is EMPTY (``chi = {∅}``, CRS ``[{}]`` -- "may proceed
+  uncatalysed") emits its spontaneous channel at the reaction's own ``k``, with no
+  self-loops. It therefore CONFLICTS with ``k_uncat``, which would be a second
+  spontaneous rate for the same reaction: that combination is refused.
+* ``a + a -> aa`` is emitted with a weight-2 arc, and Spike computes the standard
+  unordered pair count ``n(n-1)/2`` (measured, not assumed -- the alternatives sat
+  19-25 SE away). ⚠ This is `rafkit.gillespie`'s convention exactly. It is **not**
+  `abiogenesis.stochastic`'s, which counts ordered pairs ``n(n-1)``: a caller mapping
+  that chemistry must pre-double identical-reactant rate constants. Two in-house
+  conventions differing by 2x on self-pairs -- state which one your rates mean.
+
+Rate constants are emitted as **named constants** (``k_<transition>``), so a Spike
+``.spc`` configuration can override any single rate without regenerating the file --
+which is what makes a mutation control a config change rather than a code path.
+
+Refused rather than silently altered -- an executable file that drops a feature does not
+*document* a different system, it **runs** one:
+
+* **inhibition**: no ANDL representation; `to_andl` raises. (`rafkit.pnml` may annotate
+  instead, because a PNML reader sees the annotation; a simulator would not.)
+* **a catalyst that is also a reactant of the same reaction**: the self-loop and the
+  consuming arc merge into a weight-2 pre-arc, and implementations disagree on the
+  combinatorics that implies. Raise, until someone measures what the target tool does.
+* ``χ = ∅`` ("must be catalysed, nothing does") with no uncatalysed channel: omitted and
+  counted in the header, as in `rafkit.pnml` -- emitting it unconstrained would make an
+  impossible reaction fireable.
+
+Stoichiometry is read from the **multiplicity of the reactant/product tuples**.
+`ReactionNetwork`'s contract treats those as sets ("it would be for stoichiometry, which
+this class does not model"). `parse_crs` and `BinaryPolymerNetwork` preserve duplicates
+in the tuples they build -- but ⚠ **`to_crs` does not**: it deduplicates reactants, so an
+in-library ``write_crs -> read_crs -> to_andl`` round-trip silently halves self-pair
+stoichiometry (``a + a -> aa`` exports with a weight-1 arc, wrong kinetics AND wrong
+mass balance). Nothing here can detect a deduplicated tuple; do not route stoichiometric
+exports through the CRS text format.
+"""
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+from collections.abc import Mapping
+from pathlib import Path
+
+__all__ = ["to_andl", "write_andl"]
+
+
+def _identifier(name: str, taken: dict[str, object], prefix: str, key: object) -> str:
+    """A deterministic ANDL identifier for `name`, unique within `taken`.
+
+    ⚠ Length-prefixed (``s_1_a``, ``s_2_ab``), and it is load-bearing: Spike 1.6.0rc2
+    silently MISROUTES a transition's products when one place name is a proper prefix
+    of another (measured 2026-08-29: with places ``s_0`` and ``s_00``, tokens landed in
+    unrelated places, exceeding their own maximum possible production). The length
+    prefix makes a proper prefix relation between distinct names impossible; applied
+    to transition names too, where ``t_r1`` / ``t_r1_u`` had the same shape.
+    """
+    clean = re.sub(r"[^0-9a-zA-Z_]", "_", name)      # ASCII-only: Spike rejects
+    base = f"{prefix}{len(clean)}_{clean}"           # non-ASCII identifiers
+    cand, n = base, 1
+    while cand in taken and taken[cand] != key:
+        n += 1
+        cand = f"{base}__{n}"
+    taken[cand] = key
+    return cand
+
+
+def _rate(value, what: str) -> float:
+    """A rate constant fit to be executed: finite and non-negative, loudly otherwise.
+
+    Spike loads ``nan`` without complaint (measured), so garbage here surfaces only as
+    meaningless simulation output -- the silent-wrong-system failure this module's
+    refusals exist to prevent."""
+    v = float(value)
+    if not math.isfinite(v) or v < 0.0:
+        raise ValueError(f"{what} = {value!r} is not a finite non-negative rate")
+    return v
+
+
+def _per_reaction(value, n_reactions: int, what: str) -> list[float]:
+    if value is None:
+        raise ValueError(f"{what} is required: ANDL exists to carry rate constants")
+    if isinstance(value, Mapping):
+        raise ValueError(
+            f"{what} must be a scalar or a per-reaction sequence, not a mapping -- "
+            "iterating a dict would silently use its KEYS as rates")
+    try:
+        seq = [_rate(value, what)] * n_reactions
+    except TypeError:
+        seq = [_rate(v, f"{what}[{i}]") for i, v in enumerate(value)]
+        if len(seq) != n_reactions:
+            raise ValueError(f"{what} covers {len(seq)} reactions, "
+                             f"but the network has {n_reactions}")
+    return seq
+
+
+def _per_molecule(value, net, what: str) -> dict[int, float]:
+    """None -> {}; scalar -> every food molecule; mapping name->value -> those."""
+    if value is None:
+        return {}
+    if isinstance(value, dict):
+        index = {m: i for i, m in enumerate(net.molecules)}
+        missing = [n for n in value if n not in index]
+        if missing:
+            raise ValueError(f"{what} names unknown molecules: {sorted(missing)}")
+        return {index[n]: _rate(v, f"{what}[{n}]") for n, v in value.items()}
+    return {m: _rate(value, what) for m in sorted(net.food)}
+
+
+def to_andl(net, k, *, name: str = "rafkit", k_uncat=None, marking=None,
+            food_influx=None, washout=None) -> str:
+    """Serialise a network plus mass-action rate constants to ANDL text.
+
+    `k` (scalar or per-reaction sequence) is the rate constant of each **catalysed
+    channel**: one transition per catalyst set, propensity ``k * prod(reactants) *
+    prod(catalyst set members)``, summed across alternative sets by construction.
+
+    `k_uncat` (optional, scalar or per-reaction) adds one **uncatalysed transition per
+    reaction** at that constant -- the background channel, ``prod(reactants)`` only.
+    With it, a ``χ = ∅`` reaction exports as its background channel alone; without it,
+    such reactions are omitted and counted in the header.
+
+    `marking` is a ``{molecule name: count}`` dict; molecules not named start at 0,
+    except food, which starts at 1 unless overridden (the `rafkit.pnml` default).
+
+    `food_influx` / `washout`: scalar (applied to every food molecule / every molecule
+    respectively) or ``{molecule name: rate}``. Influx becomes a source transition with
+    an empty preset -- constant propensity equal to the rate. Washout becomes a sink
+    transition per molecule, propensity ``rate * count``.
+    """
+    n_r = net.n_reactions
+    ks = _per_reaction(k, n_r, "k")
+    kus = _per_reaction(k_uncat, n_r, "k_uncat") if k_uncat is not None else None
+    names = getattr(net, "names", None) or [f"r{i + 1}" for i in range(n_r)]
+
+    inhibitors = getattr(net, "inhibitors", ()) or ()
+    inhibited = [names[r] for r in range(n_r) if r < len(inhibitors) and inhibitors[r]]
+    if inhibited:
+        raise ValueError(
+            "inhibition has no ANDL representation, and an executable export that "
+            "drops it RUNS a different system rather than documenting one; strip the "
+            f"inhibitors first if that system is what you want: {inhibited}")
+
+    dup_m = sorted({m for m in net.molecules if list(net.molecules).count(m) > 1})
+    if dup_m:
+        raise ValueError(f"duplicate molecule names {dup_m}: two distinct places "
+                         "would share one identifier, and the file would lie")
+    dup_r = sorted({n for n in names if list(names).count(n) > 1})
+    if dup_r:
+        raise ValueError(f"duplicate reaction names {dup_r}: their transitions and "
+                         "rate constants would collide")
+
+    taken: dict[str, object] = {}
+    place = [_identifier(m, taken, "s_", ("mol", i))
+             for i, m in enumerate(net.molecules)]
+
+    marking = dict(marking or {})
+    index = {m: i for i, m in enumerate(net.molecules)}
+    unknown = [n for n in marking if n not in index]
+    if unknown:
+        raise ValueError(f"marking names unknown molecules: {sorted(unknown)}")
+    counts = {i: 0 for i in range(net.n_molecules)}
+    for m in net.food:
+        counts[m] = 1
+    for n, v in marking.items():
+        iv = int(v)
+        if iv != v or iv < 0:
+            raise ValueError(f"marking[{n!r}] = {v!r}: initial markings are "
+                             "non-negative integers; refusing to truncate or "
+                             "go negative (Spike loads a negative marking silently)")
+        counts[index[n]] = iv
+
+    influx = _per_molecule(food_influx, net, "food_influx")
+    outflux = _per_molecule(washout, net, "washout") if isinstance(washout, dict) \
+        else ({m: _rate(washout, "washout") for m in range(net.n_molecules)}
+              if washout is not None else {})
+
+    constants: list[tuple[str, float]] = []
+    transitions: list[tuple[str, str, str]] = []      # (tid, arcs, kname)
+    skipped = 0
+
+    def arcs_text(consumed: Counter, produced: Counter) -> str:
+        parts = []
+        for p in sorted(set(consumed) | set(produced)):
+            if consumed.get(p):
+                parts.append(f"[{place[p]} - {consumed[p]}]")
+            if produced.get(p):
+                parts.append(f"[{place[p]} + {produced[p]}]")
+        return " & ".join(parts)
+
+    for r in range(n_r):
+        reactants = Counter(net.reactants(r))
+        products = Counter(net.products(r))
+        chi = net.catalysts[r]
+        if frozenset() in chi and kus is not None:
+            raise ValueError(
+                f"reaction {names[r]!r} has an EMPTY catalyst set (may proceed "
+                "uncatalysed): its spontaneous channel already runs at k, and "
+                "k_uncat would add a second spontaneous rate on identical arcs. "
+                "One spontaneous rate per reaction; pick one.")
+        for j, cat_set in enumerate(sorted(chi, key=lambda u: sorted(u))):
+            clash = sorted(set(cat_set) & set(reactants))
+            if clash:
+                raise ValueError(
+                    f"reaction {names[r]!r}: catalyst(s) "
+                    f"{[net.molecules[c] for c in clash]} are also reactants. The "
+                    "self-loop would merge with the consuming arc into a weight-2 "
+                    "pre-arc, whose combinatorics differ between implementations; "
+                    "refusing until the target tool's convention is measured.")
+            tid = _identifier(names[r] if j == 0 else f"{names[r]}#{j + 1}",
+                              taken, "t_", ("rxn", r, j))
+            kname = f"k_{tid}"
+            constants.append((kname, ks[r]))
+            consumed = reactants + Counter(cat_set)
+            produced = products + Counter(cat_set)
+            transitions.append((tid, arcs_text(consumed, produced), kname))
+        if kus is not None:
+            tid = _identifier(f"{names[r]}_u", taken, "t_", ("unc", r))
+            kname = f"k_{tid}"
+            constants.append((kname, kus[r]))
+            transitions.append((tid, arcs_text(reactants, products), kname))
+        elif not chi:
+            skipped += 1
+
+    for m, rate in sorted(influx.items()):
+        tid = _identifier(f"src_{net.molecules[m]}", taken, "t_", ("src", m))
+        kname = f"k_{tid}"
+        constants.append((kname, rate))
+        transitions.append((tid, f"[{place[m]} + 1]", kname))
+    for m, rate in sorted(outflux.items()):
+        tid = _identifier(f"out_{net.molecules[m]}", taken, "t_", ("out", m))
+        kname = f"k_{tid}"
+        constants.append((kname, rate))
+        transitions.append((tid, f"[{place[m]} - 1]", kname))
+
+    notes = [f"Generated by rafkit. {net.n_molecules} species, {n_r} reactions.",
+             "Semantics: mass action; catalysts are consume-and-produce self-loops",
+             "(propensity scales with catalyst count); identical-reactant pairs use",
+             "the unordered convention n(n-1)/2 (Spike, measured 2026-08-29)."]
+    if skipped:
+        notes.append(f"{skipped} reaction(s) omitted: they require a catalyst, "
+                     "nothing catalyses them, and no k_uncat was given, so they "
+                     "can never fire.")
+    if not influx:
+        notes.append("NO FOOD SOURCES: food is limited to its initial marking and "
+                     "WILL deplete. This is a different system from RAF semantics "
+                     "(rafkit.pnml defaults sources ON); pass food_influx for a "
+                     "driven run.")
+    suffixed = sorted(t for t in taken if "__" in t)
+    if suffixed:
+        notes.append("Disambiguated ids (name collisions across kinds): "
+                     + ", ".join(suffixed))
+
+    safe_name = re.sub(r"[^0-9a-zA-Z_]", "_", name) or "rafkit"
+    lines = ["/*"] + [f" * {n}" for n in notes] + [" */", "",
+             f"spn  [{safe_name}]", "{"]
+    if constants:
+        lines += ["constants:", "all:"]
+        lines += [f"  double {kn} = {kv!r};" for kn, kv in constants]
+        lines.append("")
+    lines += ["places:", "discrete:"]
+    lines += [f"  {place[m]} = {counts[m]};" for m in range(net.n_molecules)]
+    lines.append("")
+    lines += ["transitions:", "stochastic:"]
+    for tid, arcs, kname in transitions:
+        lines += [f"  {tid}", "    :", f"    : {arcs}",
+                  f"    : MassAction({kname})", "    ;"]
+    lines += ["}", ""]
+    return "\n".join(lines)
+
+
+def write_andl(net, k, path: str | Path, **kwargs) -> None:
+    """Write a network plus rate constants to an ANDL file."""
+    Path(path).write_text(to_andl(net, k, **kwargs), encoding="utf-8")