rafkit 0.2.0__tar.gz → 0.4.0__tar.gz

{rafkit-0.2.0/src/rafkit.egg-info → rafkit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rafkit
-Version: 0.2.0
+Version: 0.4.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
@@ -115,11 +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 &
@@ -141,8 +163,37 @@ last two rows.
 Constructors still accept a plain iterable of molecules and normalise it, so simple
 systems stay simple to write.
 
-**Still not representable:** inhibition (Hordijk & Steel 2012, Part II), where a
-molecule can *prevent* a reaction.
+## Inhibition
+
+A molecule can prevent a reaction. `max_urafs` returns the **uninhibited RAFs** of
+Hordijk & Steel (2012), and returns a *collection* rather than one set, because
+inhibition destroys the monotonicity that makes a maximal RAF unique — there is no
+"the" maximal u-RAF.
+
+```
+Food: a, b
+r1 : a + b [a] {d} => c      # inhibited by d
+r2 : a + b [b] {c} => d      # inhibited by c
+```
+
+Two maximal u-RAFs, `{r1}` and `{r2}`: each is an RAF whose support avoids its own
+inhibitor, and their union is an RAF that fails the uninhibited condition.
+
+`simulate` respects inhibition too — an inhibited reaction has propensity zero, so a
+running network can **lose** a subRAF, not merely gain one. See
+`examples/inhibition_dissolution.py`.
+
+The set-theoretic tools need no special handling: `sample_irrraf`, `irrraf_census`,
+`core_raf` and `catalytically_reachable` all take a reaction set, and passing a u-RAF
+is correct because the uninhibited property is inherited downward — every sub-RAF of a
+u-RAF is a u-RAF.
+
+Deciding whether a u-RAF exists is NP-complete, but the problem is fixed-parameter
+tractable in *k*, the number of inhibition classes — and **k is a property of how you
+encode inhibition, not of the chemistry.** `classes_from_inhibitors` groups by
+inhibiting *molecule*, so *k* is the number of distinct inhibitors rather than the
+number of inhibited reactions, which is the difference between `2^k` being feasible
+and not.
 
 ## Notes on irreducible cores
 

{rafkit-0.2.0 → rafkit-0.4.0}/README.md

@@ -87,11 +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 &
@@ -113,8 +135,37 @@ last two rows.
 Constructors still accept a plain iterable of molecules and normalise it, so simple
 systems stay simple to write.
 
-**Still not representable:** inhibition (Hordijk & Steel 2012, Part II), where a
-molecule can *prevent* a reaction.
+## Inhibition
+
+A molecule can prevent a reaction. `max_urafs` returns the **uninhibited RAFs** of
+Hordijk & Steel (2012), and returns a *collection* rather than one set, because
+inhibition destroys the monotonicity that makes a maximal RAF unique — there is no
+"the" maximal u-RAF.
+
+```
+Food: a, b
+r1 : a + b [a] {d} => c      # inhibited by d
+r2 : a + b [b] {c} => d      # inhibited by c
+```
+
+Two maximal u-RAFs, `{r1}` and `{r2}`: each is an RAF whose support avoids its own
+inhibitor, and their union is an RAF that fails the uninhibited condition.
+
+`simulate` respects inhibition too — an inhibited reaction has propensity zero, so a
+running network can **lose** a subRAF, not merely gain one. See
+`examples/inhibition_dissolution.py`.
+
+The set-theoretic tools need no special handling: `sample_irrraf`, `irrraf_census`,
+`core_raf` and `catalytically_reachable` all take a reaction set, and passing a u-RAF
+is correct because the uninhibited property is inherited downward — every sub-RAF of a
+u-RAF is a u-RAF.
+
+Deciding whether a u-RAF exists is NP-complete, but the problem is fixed-parameter
+tractable in *k*, the number of inhibition classes — and **k is a property of how you
+encode inhibition, not of the chemistry.** `classes_from_inhibitors` groups by
+inhibiting *molecule*, so *k* is the number of distinct inhibitors rather than the
+number of inhibited reactions, which is the difference between `2^k` being feasible
+and not.
 
 ## Notes on irreducible cores
 

{rafkit-0.2.0 → rafkit-0.4.0}/pyproject.toml

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

@@ -16,14 +16,17 @@ from rafkit.binary_polymer import BinaryPolymerNetwork, binary_polymer
 from rafkit.catalysis import catalysing_molecules, is_catalysed, normalise
 from rafkit.crs import parse_crs, read_crs, to_crs, write_crs
 from rafkit.gillespie import Trajectory, propensities, simulate
+from rafkit.inhibition import (classes_from_inhibitors, is_uninhibited, is_uraf,
+                               max_urafs, support)
 from rafkit.network import ReactionNetwork
+from rafkit.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.2.0"
+__version__ = "0.4.0"
 
 __all__ = [
     "BinaryPolymerNetwork", "binary_polymer", "ReactionNetwork",
@@ -32,5 +35,7 @@ __all__ = [
     "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.2.0 → rafkit-0.4.0}/src/rafkit/crs.py

@@ -20,7 +20,10 @@ Catalysts are alternatives, any one of which suffices. A braced group is a
 **conjunctive** requirement -- `[{a,d}, e]` means *a and d together*, or *e* -- which
 is the notation Huson, Xavier & Steel (2024) use. Two edge cases carry meaning and are
 not interchangeable: `[]` means the reaction **must** be catalysed and nothing does so,
-while `[{}]` means it **may proceed uncatalysed**. A reversible reaction is read as **two** reactions, forward and
+while `[{}]` means it **may proceed uncatalysed**.
+
+A brace group **after** the catalyst bracket lists **inhibitors**, space- or
+comma-separated, following CatReNet: `r1 : a + b [c] {d e} -> x`. A reversible reaction is read as **two** reactions, forward and
 reverse, sharing a catalyst set -- which is the reading its own generator uses.
 
 `X + X -> Y` is written `X ... -> Y`, with the repeated reactant collapsed. Since
@@ -76,44 +79,54 @@ def parse_crs(text: str) -> ReactionNetwork:
             continue
         name, body = m.group("name"), m.group("body")
 
+        inhib: list[str] = []
         cats: list[list[str]] = []
         if "[" in body:
             pre, rest = body.split("[", 1)
             inside, post = rest.split("]", 1)
             cats = _parse_catalysts(inside)
             body = pre + " " + post
+            # A brace group AFTER the catalysts is the inhibitor list (CatReNet).
+            m_inh = re.search(r"\{([^}]*)\}", body)
+            if m_inh:
+                inhib = [t for t in re.split(r"[,\s]+", m_inh.group(1)) if t]
+                body = body[:m_inh.start()] + " " + body[m_inh.end():]
 
         arrow = _ARROW.search(body)
         if not arrow:
             continue
         lhs, rhs = body[:arrow.start()], body[arrow.end():]
-        parsed.append((name, _split_list(lhs), _split_list(rhs), cats,
+        parsed.append((name, _split_list(lhs), _split_list(rhs), cats, inhib,
                        arrow.group(1) in ("<->", "<=>")))
 
     # Stable molecule indexing: food first, then order of appearance.
     index: dict[str, int] = {}
     for n in food_names:
         index.setdefault(n, len(index))
-    for _, lhs, rhs, cats, _ in parsed:
-        for n in (*lhs, *rhs, *(x for g in cats for x in g)):
+    for _, lhs, rhs, cats, inhib, _ in parsed:
+        for n in (*lhs, *rhs, *(x for g in cats for x in g), *inhib):
             index.setdefault(n, len(index))
 
-    pairs, catalysts, names = [], [], []
-    for name, lhs, rhs, cats, reversible in parsed:
+    pairs, catalysts, names, inhibitors = [], [], [], []
+    for name, lhs, rhs, cats, inhib, reversible in parsed:
         cat = frozenset(frozenset(index[c] for c in g) for g in cats)
+        inh = frozenset(index[x] for x in inhib)
         fwd = (tuple(index[x] for x in lhs), tuple(index[x] for x in rhs))
         pairs.append(fwd); catalysts.append(cat); names.append(name)
+        inhibitors.append(inh)
         if reversible:
             pairs.append((fwd[1], fwd[0]))
             catalysts.append(cat)
             names.append(f"{name}_rev")
+            inhibitors.append(inh)
 
     molecules = tuple(sorted(index, key=index.get))
     return ReactionNetwork(molecules=molecules,
                            food=frozenset(index[n] for n in food_names),
                            reaction_pairs=tuple(pairs),
                            catalysts=tuple(catalysts),
-                           names=tuple(names))
+                           names=tuple(names),
+                           inhibitors=tuple(inhibitors))
 
 
 def read_crs(path: str | Path) -> ReactionNetwork:
@@ -140,7 +153,11 @@ def to_crs(net, comment: str = "") -> str:
         lhs = " + ".join(dict.fromkeys(name(x) for x in net.reactants(r)))
         rhs = " + ".join(dict.fromkeys(name(x) for x in net.products(r)))
         cats = _format_catalysts(net, r)
-        out.append(f"{names[r]} : {lhs} [{cats}] => {rhs}")
+        inh = getattr(net, "inhibitors", ())
+        inh_s = ""
+        if inh and inh[r]:
+            inh_s = " {" + " ".join(sorted(name(x) for x in inh[r])) + "}"
+        out.append(f"{names[r]} : {lhs} [{cats}]{inh_s} => {rhs}")
     out.append("")
     return "\n".join(out)
 

{rafkit-0.2.0 → rafkit-0.4.0}/src/rafkit/gillespie.py

@@ -15,6 +15,8 @@ reduction factor**, which is the mechanism under test.
 Conventions, all inherited from the reference rather than chosen here:
 
 * a reaction whose catalyst is absent still proceeds, at ``1 / uncatalysed_factor``;
+* a reaction with an **inhibitor present does not proceed at all** -- inhibition is a
+  block, not a slowdown, and it is independent of catalysis;
 * food molecules are replenished when they fall below ``food_floor``;
 * a ligation ``a + b -> ab`` with ``a == b`` takes the pair count ``n(n-1)/2``, not ``n^2``.
 """
@@ -88,6 +90,11 @@ def propensities(net, counts: np.ndarray, *,
     runs at ``1 / uncatalysed_factor`` of it. That difference is the whole mechanism:
     it makes seeding rare but not impossible.
 
+    **Inhibition is absolute**: if any molecule inhibiting a reaction is present, its
+    propensity is zero regardless of catalysis. This is what lets a running network
+    *lose* a subRAF rather than only gain one -- the effect Hordijk, Naylor, Krasnogor
+    & Fellermann (2018) report as toxic elements causing loss of autocatalytic subsets.
+
     `reactions` restricts which reactions may fire. **This is a fidelity requirement,
     not a convenience.** Hordijk & Steel study "the molecular flow on this maximal RAF";
     simulating the entire generated network instead lets any reaction fire uncatalysed,
@@ -98,10 +105,13 @@ def propensities(net, counts: np.ndarray, *,
     out = np.zeros(net.n_reactions)
     allowed = range(net.n_reactions) if reactions is None else reactions
     present = frozenset(np.flatnonzero(counts).tolist())
+    inhibitors = getattr(net, "inhibitors", ())
     for r in allowed:
         combos = _pair_count(counts, net.reactants(r))
         if combos <= 0:
             continue
+        if inhibitors and (inhibitors[r] & present):
+            continue                      # inhibited: blocked outright
         catalysed = is_catalysed(net.catalysts[r], present)
         out[r] = combos if catalysed else combos / uncatalysed_factor
     return out

rafkit-0.4.0/src/rafkit/inhibition.py

@@ -0,0 +1,114 @@
+"""Uninhibited RAFs, where a molecule can prevent a reaction.
+
+Hordijk & Steel (2012), Part II. Inhibition is given as ``k`` pairs ``(X_i, R_i)``:
+every molecule in ``X_i`` inhibits every reaction in ``R_i``. A set ``R'`` is an
+**uninhibited RAF** (u-RAF) when
+
+* **(u-1)** ``R'`` is an RAF, and
+* **(u-2)** ``R' ∩ R_i != empty`` implies ``supp(R') ∩ X_i = empty``,
+
+where ``supp(R')`` is every molecule appearing as a reactant or product in ``R'``.
+
+**Inhibition breaks the structure the rest of this library rests on.** Adding a reaction
+can now *disable* another, so the maximal-RAF operator is no longer monotone -- and
+monotonicity is what gives a *unique* maximum (Huson, Xavier & Steel 2024, lemma 3.1).
+There is therefore no "the" maximal u-RAF: `max_urafs` returns a **collection**, and
+that difference is in the signature deliberately rather than in a footnote. Deciding
+whether a u-RAF exists at all is NP-complete.
+
+What rescues it is that the problem is fixed-parameter tractable in ``k``, by their
+theorem 1: the maximal u-RAFs are exactly the non-empty sets ``s(R_J ∩ R^J)`` as ``J``
+ranges over subsets of ``[k]``. So the cost is ``2^k`` calls to the ordinary maximal-RAF
+algorithm, and **``k`` is a property of how inhibition is encoded, not of the
+chemistry**. One class per inhibited reaction makes ``2^k`` hopeless immediately;
+`classes_from_inhibitors` groups by inhibiting *molecule* instead, which is what the
+paper means by considering "types" of molecules that inhibit "types" of reactions.
+"""
+from __future__ import annotations
+
+from itertools import combinations
+
+from rafkit.raf import _refine
+
+Inhibition = tuple[tuple[frozenset[int], frozenset[int]], ...]
+
+
+def support(net, reactions) -> frozenset[int]:
+    """Every molecule that is a reactant or product of some reaction in the set.
+
+    Catalysts are deliberately excluded: the paper's ``supp`` is over reactants and
+    products only, and including catalysts would make (u-2) strictly harder to satisfy.
+    """
+    out: set[int] = set()
+    for r in reactions:
+        out.update(net.reactants(r))
+        out.update(net.products(r))
+    return frozenset(out)
+
+
+def classes_from_inhibitors(net) -> Inhibition:
+    """Build the ``(X_i, R_i)`` classes from a network's per-reaction inhibitors.
+
+    Grouped by inhibiting **molecule**, so ``k`` is the number of distinct inhibitors
+    rather than the number of inhibited reactions. That choice is the difference
+    between a feasible ``2^k`` and an impossible one, and it costs nothing: the pair
+    ``({x}, {reactions x inhibits})`` expresses exactly the same relation.
+    """
+    by_molecule: dict[int, set[int]] = {}
+    for r, inhibitors in enumerate(getattr(net, "inhibitors", ()) or ()):
+        for x in inhibitors:
+            by_molecule.setdefault(x, set()).add(r)
+    return tuple((frozenset({x}), frozenset(rs))
+                 for x, rs in sorted(by_molecule.items()))
+
+
+def is_uninhibited(net, reactions, inhibition: Inhibition) -> bool:
+    """Condition (u-2): nothing the set makes or uses inhibits anything the set does."""
+    rs = frozenset(reactions)
+    supp = support(net, rs)
+    return all(not (rs & R_i) or not (supp & X_i) for X_i, R_i in inhibition)
+
+
+def is_uraf(net, reactions, inhibition: Inhibition) -> bool:
+    """Both conditions: an RAF that inhibits none of its own reactions."""
+    rs = frozenset(reactions)
+    return bool(rs) and _refine(net, rs) == rs and is_uninhibited(net, rs, inhibition)
+
+
+def max_urafs(net, inhibition: Inhibition | None = None,
+              reactions=None) -> tuple[frozenset[int], ...]:
+    """All maximal uninhibited RAFs, by Hordijk & Steel (2012) theorem 1.
+
+    Returns a tuple because there is generally more than one and none of them is
+    canonical -- see the module docstring. Empty tuple means no u-RAF exists.
+
+    Cost is ``2^k`` maximal-RAF computations, with ``k = len(inhibition)``.
+    """
+    if inhibition is None:
+        inhibition = classes_from_inhibitors(net)
+    allowed = frozenset(range(net.n_reactions) if reactions is None else reactions)
+    if not inhibition:
+        maximal = _refine(net, allowed)
+        return (maximal,) if maximal else ()
+
+    k = len(inhibition)
+    found: set[frozenset[int]] = set()
+    for size in range(k + 1):
+        for J in combinations(range(k), size):
+            Jset = set(J)
+            # R_J: reactions untouched by every class NOT in J.
+            R_J = frozenset(
+                r for r in allowed
+                if all(not (support(net, {r}) & inhibition[j][0])
+                       for j in range(k) if j not in Jset))
+            # R^J: reactions inhibited by no class IN J.
+            R_super = frozenset(
+                r for r in allowed if all(r not in inhibition[j][1] for j in Jset))
+            candidate = _refine(net, R_J & R_super)
+            if candidate:
+                found.add(candidate)
+
+    # Different J can yield nested results; only the maximal ones are u-RAFs by (iii).
+    return tuple(sorted((s for s in found
+                         if not any(s < t for t in found)),
+                        key=lambda s: (-len(s), sorted(s))))

{rafkit-0.2.0 → rafkit-0.4.0}/src/rafkit/network.py

@@ -43,6 +43,12 @@ class ReactionNetwork:
     reaction_pairs: tuple[tuple[tuple[int, ...], tuple[int, ...]], ...]
     catalysts: tuple[frozenset[int], ...]
     names: tuple[str, ...] = ()
+    inhibitors: tuple[frozenset[int], ...] = ()
+    """Per reaction, the molecules that inhibit it (CatReNet's model and CRS form).
+
+    `rafkit.inhibition.classes_from_inhibitors` converts this into the (X_i, R_i)
+    classes the algorithm needs, grouping by molecule to keep k small.
+    """
 
     def __post_init__(self):
         object.__setattr__(self, "catalysts",
@@ -51,6 +57,12 @@ class ReactionNetwork:
             raise ValueError(
                 f"{len(self.catalysts)} catalyst sets for "
                 f"{len(self.reaction_pairs)} reactions")
+        if not self.inhibitors:
+            object.__setattr__(self, "inhibitors",
+                               (frozenset(),) * len(self.reaction_pairs))
+        else:
+            object.__setattr__(self, "inhibitors",
+                               tuple(frozenset(i) for i in self.inhibitors))
         if not self.names:
             object.__setattr__(
                 self, "names", tuple(f"r{i + 1}" for i in range(len(self.reaction_pairs))))

rafkit-0.4.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.2.0 → rafkit-0.4.0}/src/rafkit/raf.py

@@ -218,15 +218,24 @@ def sample_irrraf(net: BinaryPolymerNetwork, reactions: frozenset[int],
     return current
 
 
-def irrraf_census(net: BinaryPolymerNetwork, raf: RafResult, n_samples: int,
+def irrraf_census(net: BinaryPolymerNetwork, raf, n_samples: int,
                   rng, strict: bool = False) -> dict:
     """Sample irreducible RAFs and report how many distinct ones turn up.
 
+    `raf` may be a `RafResult` or a bare set of reactions -- pass one of the u-RAFs
+    from `rafkit.inhibition.max_urafs` to take a census under inhibition. That is
+    correct without further conditions because the uninhibited property is inherited
+    downward: every sub-RAF of a u-RAF is itself a u-RAF (Hordijk & Steel 2012), so
+    every core sampled from one is uninhibited too.
+
     The count is the quantity of interest: it upper-bounds the number of
     distinguishable lineages the chemistry can carry, so a census of 1 means there
     is nothing to inherit and no ecology is possible regardless of the dynamics
     later placed on top.
     """
+    if not isinstance(raf, RafResult):
+        raf = RafResult(reactions=frozenset(raf),
+                        closure=_closure(net, frozenset(raf)), n_rounds=0)
     if raf.is_empty:
         return {"n_samples": 0, "n_distinct": 0, "sizes": [], "mean_size": float("nan"),
                 "mean_jaccard": float("nan"), "min_jaccard": float("nan"),

{rafkit-0.2.0 → rafkit-0.4.0/src/rafkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rafkit
-Version: 0.2.0
+Version: 0.4.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
@@ -115,11 +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 &
@@ -141,8 +163,37 @@ last two rows.
 Constructors still accept a plain iterable of molecules and normalise it, so simple
 systems stay simple to write.
 
-**Still not representable:** inhibition (Hordijk & Steel 2012, Part II), where a
-molecule can *prevent* a reaction.
+## Inhibition
+
+A molecule can prevent a reaction. `max_urafs` returns the **uninhibited RAFs** of
+Hordijk & Steel (2012), and returns a *collection* rather than one set, because
+inhibition destroys the monotonicity that makes a maximal RAF unique — there is no
+"the" maximal u-RAF.
+
+```
+Food: a, b
+r1 : a + b [a] {d} => c      # inhibited by d
+r2 : a + b [b] {c} => d      # inhibited by c
+```
+
+Two maximal u-RAFs, `{r1}` and `{r2}`: each is an RAF whose support avoids its own
+inhibitor, and their union is an RAF that fails the uninhibited condition.
+
+`simulate` respects inhibition too — an inhibited reaction has propensity zero, so a
+running network can **lose** a subRAF, not merely gain one. See
+`examples/inhibition_dissolution.py`.
+
+The set-theoretic tools need no special handling: `sample_irrraf`, `irrraf_census`,
+`core_raf` and `catalytically_reachable` all take a reaction set, and passing a u-RAF
+is correct because the uninhibited property is inherited downward — every sub-RAF of a
+u-RAF is a u-RAF.
+
+Deciding whether a u-RAF exists is NP-complete, but the problem is fixed-parameter
+tractable in *k*, the number of inhibition classes — and **k is a property of how you
+encode inhibition, not of the chemistry.** `classes_from_inhibitors` groups by
+inhibiting *molecule*, so *k* is the number of distinct inhibitors rather than the
+number of inhibited reactions, which is the difference between `2^k` being feasible
+and not.
 
 ## Notes on irreducible cores
 

{rafkit-0.2.0 → rafkit-0.4.0}/src/rafkit.egg-info/SOURCES.txt

@@ -6,7 +6,9 @@ src/rafkit/binary_polymer.py
 src/rafkit/catalysis.py
 src/rafkit/crs.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
@@ -15,6 +17,8 @@ src/rafkit.egg-info/requires.txt
 src/rafkit.egg-info/top_level.txt
 tests/test_crs.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.4.0/tests/test_inhibition.py

@@ -0,0 +1,239 @@
+"""Uninhibited RAFs — Hordijk & Steel (2012), Part II.
+
+The load-bearing test here is `test_matches_brute_force`: for networks small enough to
+enumerate every subset, the fixed-parameter algorithm is checked against a direct
+search that shares no code with it. Everything else in this file is a property from the
+paper, asserted rather than assumed.
+"""
+from __future__ import annotations
+
+from itertools import chain, combinations
+
+import numpy as np
+import pytest
+
+from rafkit import binary_polymer, max_raf, parse_crs
+from rafkit.inhibition import (classes_from_inhibitors, is_uninhibited, is_uraf,
+                               max_urafs, support)
+from rafkit.raf import _refine
+
+
+def _powerset(items):
+    items = list(items)
+    return chain.from_iterable(combinations(items, k) for k in range(len(items) + 1))
+
+
+def _brute_force_max_urafs(net, inhibition):
+    """Every maximal u-RAF, by direct enumeration. Shares no code with max_urafs."""
+    urafs = [frozenset(s) for s in _powerset(range(net.n_reactions))
+             if s and is_uraf(net, s, inhibition)]
+    return {s for s in urafs if not any(s < t for t in urafs)}
+
+
+class TestDefinition:
+    def test_support_is_reactants_and_products_only(self):
+        net = parse_crs("Food: a, b\nr1 : a + b [z] => c\n")
+        names = {net.molecules[m] for m in support(net, {0})}
+        assert names == {"a", "b", "c"}       # z is a catalyst, not in the support
+
+    def test_inhibition_by_something_absent_from_the_support_is_harmless(self):
+        # z inhibits r1, but z is neither reactant nor product of r1, so (u-2) holds.
+        net = parse_crs("Food: a, b\nr1 : a + b [a] {z} => c\n")
+        assert is_uninhibited(net, {0}, classes_from_inhibitors(net))
+        assert is_uraf(net, {0}, classes_from_inhibitors(net))
+
+    def test_a_set_that_inhibits_its_own_reaction_is_not_a_uraf(self):
+        net = parse_crs("Food: a, b\nr1 : a + b [c] => c\n")
+        c = net.molecules.index("c")
+        inh = ((frozenset({c}), frozenset({0})),)
+        assert _refine(net, {0}) == {0}            # it IS an RAF
+        assert not is_uraf(net, {0}, inh)          # but not uninhibited
+
+    def test_raf_is_unaffected_by_inhibition(self):
+        """The paper defines RAF without reference to inhibition; (u-2) is separate.
+        CatReNet instead filters inhibited reactions inside its maxRaf, so its result
+        differs from the definition here whenever inhibitors are present."""
+        net = parse_crs("Food: a, b\nr1 : a + b [a] => c\nr2 : a + c [a] => d\n")
+        assert len(max_raf(net).reactions) == 2
+
+
+class TestTheorem1:
+    def test_a_subset_of_a_uraf_that_is_a_raf_is_a_uraf(self):
+        """Stated in the paper: (u-2) is inherited downward."""
+        net = parse_crs(
+            "Food: a, b\nr1 : a + b [a] => c\nr2 : a + c [a] => d\nr3 : a + d [a] => e\n")
+        e = net.molecules.index("e")
+        inh = ((frozenset({e}), frozenset({2})),)
+        whole = max_urafs(net, inh)
+        assert whole
+        for u in whole:
+            for s in _powerset(u):
+                s = frozenset(s)
+                if s and _refine(net, s) == s:
+                    assert is_uraf(net, s, inh)
+
+    # Seeds probed to give a maximal RAF of 4-12 reactions with >=2 produced
+    # molecules, so exhaustive enumeration is feasible and the constraint bites.
+    @pytest.mark.parametrize("seed", [1, 5, 7, 12, 13, 15, 16])
+    def test_matches_brute_force(self, seed):
+        """The fixed-parameter algorithm against direct enumeration of every subset.
+
+        The two computations share no code: one walks subsets of [k] and calls the
+        maximal-RAF fixpoint, the other tests every subset of the RAF directly.
+        """
+        net = binary_polymer(max_len=4, food_len=2, p=0.01,
+                             rng=np.random.default_rng(seed), cleavage=True)
+        raf = sorted(max_raf(net).reactions)
+        assert 3 <= len(raf) <= 12, "seed no longer yields an enumerable RAF"
+
+        # Inhibit reactions by molecules the set actually makes, so (u-2) can fail.
+        produced = sorted(support(net, raf) - net.food)
+        assert len(produced) >= 2
+        inh = tuple((frozenset({produced[i]}), frozenset({raf[i]}))
+                    for i in range(2))
+
+        assert set(max_urafs(net, inh, reactions=raf)) == \
+            _brute_force_max_urafs_on(net, raf, inh)
+
+
+def _brute_force_max_urafs_on(net, allowed, inhibition):
+    urafs = [frozenset(s) for s in _powerset(allowed)
+             if s and is_uraf(net, s, inhibition)]
+    return {s for s in urafs if not any(s < t for t in urafs)}
+
+
+class TestCollectionSemantics:
+    def test_there_can_be_more_than_one_maximal_uraf(self):
+        """The structural break: no unique maximum, so the API returns a collection.
+
+        Two independent always-on reactions, each inhibited by the other's product.
+        Neither can coexist with the other, and neither is canonical.
+        """
+        net = parse_crs(
+            "Food: a, b\nr1 : a + b [a] => c\nr2 : a + b [b] => d\n")
+        c, d = net.molecules.index("c"), net.molecules.index("d")
+        inh = ((frozenset({c}), frozenset({1})), (frozenset({d}), frozenset({0})))
+        got = {frozenset(net.names[r] for r in u) for u in max_urafs(net, inh)}
+        assert got == {frozenset({"r1"}), frozenset({"r2"})}
+
+    def test_no_inhibition_gives_back_the_maximal_raf(self):
+        net = parse_crs("Food: a, b\nr1 : a + b [c] => c\n")
+        assert max_urafs(net, ()) == (max_raf(net).reactions,)
+
+    def test_no_uraf_returns_an_empty_collection(self):
+        net = parse_crs("Food: a, b\nr1 : a + b [c] => c\n")
+        c = net.molecules.index("c")
+        assert max_urafs(net, ((frozenset({c}), frozenset({0})),)) == ()
+
+
+class TestClassEncoding:
+    def test_grouping_is_by_inhibiting_molecule_not_by_reaction(self):
+        """k is the cost, and it is a property of the encoding. Grouping by molecule
+        keeps k at the number of distinct inhibitors rather than of inhibited
+        reactions, which is the difference between 2^k feasible and not."""
+        net = parse_crs(
+            "Food: a, b\nr1 : a + b [a] {z} => c\nr2 : a + b [b] {z} => d\n")
+        classes = classes_from_inhibitors(net)
+        assert len(classes) == 1                       # one inhibitor, not two reactions
+        (X, R), = classes
+        assert {net.molecules[x] for x in X} == {"z"}
+        assert R == frozenset({0, 1})
+
+
+class TestDivergenceFromCatReNet:
+    """CatReNet computes something different once inhibitors are present.
+
+    Its `maxRaf` filters inhibited reactions *during* the RAF computation, where
+    Hordijk & Steel (2012) define an RAF without reference to inhibition and add (u-2)
+    as a separate condition on u-RAFs. On the network below CatReNet's `maxRaf` and
+    `uRaf` both return nothing, while two maximal u-RAFs exist by the definition.
+
+    Verified by hand rather than asserted: `{r1}` is an RAF, its support is {a,b,c},
+    and the only class inhibiting r1 is {d} — so (u-2) holds. Likewise `{r2}`. Their
+    union is an RAF but fails (u-2), which is why neither can be extended.
+    """
+
+    NET = "Food: a, b\nr1 : a + b [a] {d} => c\nr2 : a + b [b] {c} => d\n"
+
+    def test_two_maximal_urafs_exist_where_catrenet_reports_none(self):
+        net = parse_crs(self.NET)
+        got = {frozenset(net.names[r] for r in u) for u in max_urafs(net)}
+        assert got == {frozenset({"r1"}), frozenset({"r2"})}
+
+    def test_each_is_a_raf_satisfying_u2_but_their_union_is_not(self):
+        net = parse_crs(self.NET)
+        cls = classes_from_inhibitors(net)
+        assert is_uraf(net, {0}, cls) and is_uraf(net, {1}, cls)
+        assert _refine(net, {0, 1}) == {0, 1}          # the union IS an RAF
+        assert not is_uninhibited(net, {0, 1}, cls)    # but violates (u-2)
+
+
+class TestDynamics:
+    """Inhibition in the simulator, which is what lets a network *lose* a subRAF."""
+
+    def test_an_inhibited_reaction_has_zero_propensity(self):
+        from rafkit.gillespie import propensities
+        net = parse_crs("Food: a, b\nr1 : a + b [a] {z} => c\n")
+        counts = np.zeros(net.n_molecules, dtype=np.int64)
+        for m in net.food:
+            counts[m] = 5
+        assert propensities(net, counts)[0] > 0            # z absent: runs
+        counts[net.molecules.index("z")] = 1
+        assert propensities(net, counts)[0] == 0.0         # z present: blocked outright
+
+    def test_inhibition_blocks_rather_than_slows(self):
+        """Distinct from the uncatalysed case, which merely runs at a reduced rate."""
+        from rafkit.gillespie import propensities
+        net = parse_crs("Food: a, b\nr1 : a + b [q] {z} => c\n")
+        counts = np.zeros(net.n_molecules, dtype=np.int64)
+        for m in net.food:
+            counts[m] = 5
+        uncatalysed = propensities(net, counts)[0]
+        assert uncatalysed > 0                             # no catalyst, still proceeds
+        counts[net.molecules.index("z")] = 1
+        assert propensities(net, counts)[0] == 0.0
+
+    def test_a_subraf_stops_producing_once_its_inhibitor_appears(self):
+        """Dissolution. r2 runs as soon as c exists; r3 is self-catalysed so its
+        product e arrives only after a rare uncatalysed event, and blocks r2."""
+        from rafkit import simulate
+        net = parse_crs(
+            "Food: a, b\nr1 : a + b [a] => c\nr2 : a + c [c] {e} => d\n"
+            "r3 : a + b [e] => e\n")
+        tr = simulate(net, n_events=4000, rng=np.random.default_rng(2), sample_every=10)
+        t_e = tr.first_seen("e")
+        assert t_e is not None, "the inhibitor never appeared; test is vacuous"
+
+        d = tr.of("d").astype(float)
+        i = int(np.searchsorted(tr.times, t_e))
+        assert d[i] > 0, "d never accumulated before the block; test is vacuous"
+        assert d[-1] == d[i], "d kept growing after its reaction was inhibited"
+
+
+class TestDownstreamUnderInhibition:
+    """The set-theoretic tools need no change: pass a u-RAF and they stay correct,
+    because the uninhibited property is inherited downward."""
+
+    def _setup(self, seed=7):
+        net = binary_polymer(max_len=4, food_len=2, p=0.01,
+                             rng=np.random.default_rng(seed), cleavage=True)
+        raf = sorted(max_raf(net).reactions)
+        produced = sorted(support(net, raf) - net.food)
+        inh = tuple((frozenset({produced[i]}), frozenset({raf[i]})) for i in range(2))
+        return net, raf, inh
+
+    def test_cores_sampled_from_a_uraf_are_themselves_urafs(self):
+        from rafkit import sample_irrraf
+        net, raf, inh = self._setup()
+        urafs = max_urafs(net, inh, reactions=raf)
+        assert urafs
+        for u in urafs:
+            for i in range(10):
+                assert is_uraf(net, sample_irrraf(net, u, np.random.default_rng(i)), inh)
+
+    def test_census_accepts_a_bare_reaction_set(self):
+        from rafkit import irrraf_census
+        net, raf, inh = self._setup()
+        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

rafkit-0.4.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")