rafkit 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rafkit
-Version: 0.3.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,12 +115,33 @@ counted as **one** catalysed reaction, not two. Use `net.catalysis_level` — no
 | `binary_polymer` | Kauffman binary polymer generator, with optional cleavage |
 | `ReactionNetwork` | arbitrary catalytic reaction systems, same protocol |
 | `read_crs` / `write_crs` | CatReNet's CRS interchange format |
+| `to_pnml` / `write_pnml` | PNML export (ISO/IEC 15909-2) for the Petri net ecosystem |
 | `simulate` | Gillespie direct method — watch subRAFs seed themselves into existence |
 | `max_urafs` | uninhibited RAFs, when a molecule can prevent a reaction |
 
 Every algorithm carries hand-computed known-answer tests, because a RAF algorithm that
 is subtly wrong produces plausible numbers rather than errors.
 
+## A reaction network is a Petri net
+
+Species are places, reactions are transitions, molecule counts are tokens. `write_pnml`
+exports to PNML (ISO/IEC 15909-2), so these networks open in Petri net editors, model
+checkers, and the unfolding tools that compute the causal structure of a run.
+
+Three things need care, and each is explicit rather than silent:
+
+- **Catalysis becomes a self-loop.** P/T nets have no read arc, so a catalyst is a pair
+  of arcs, consuming the token and returning it.
+- **Alternative catalyst sets become separate transitions**, named `r1`, `r1#2`, …, since
+  a transition's preset is a conjunction and cannot express "either set".
+- **Food gets source transitions**, because RAF food is inexhaustible and no initial
+  marking expresses that — a marking of *n* deadlocks after *n* uses.
+
+Inhibition has no `ptnet` representation and is written as a `toolspecific` annotation,
+with a warning in the file: a reader that ignores it gets a *different system*.
+Reactions requiring a catalyst that nothing provides are omitted and counted, since
+emitting them unconstrained would make them freely fireable — the opposite of the intent.
+
 ## Catalysis is a relation, not a list
 
 `catalysts[r]` is a set of **alternative catalyst sets**, following Huson, Xavier &

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

@@ -87,12 +87,33 @@ counted as **one** catalysed reaction, not two. Use `net.catalysis_level` — no
 | `binary_polymer` | Kauffman binary polymer generator, with optional cleavage |
 | `ReactionNetwork` | arbitrary catalytic reaction systems, same protocol |
 | `read_crs` / `write_crs` | CatReNet's CRS interchange format |
+| `to_pnml` / `write_pnml` | PNML export (ISO/IEC 15909-2) for the Petri net ecosystem |
 | `simulate` | Gillespie direct method — watch subRAFs seed themselves into existence |
 | `max_urafs` | uninhibited RAFs, when a molecule can prevent a reaction |
 
 Every algorithm carries hand-computed known-answer tests, because a RAF algorithm that
 is subtly wrong produces plausible numbers rather than errors.
 
+## A reaction network is a Petri net
+
+Species are places, reactions are transitions, molecule counts are tokens. `write_pnml`
+exports to PNML (ISO/IEC 15909-2), so these networks open in Petri net editors, model
+checkers, and the unfolding tools that compute the causal structure of a run.
+
+Three things need care, and each is explicit rather than silent:
+
+- **Catalysis becomes a self-loop.** P/T nets have no read arc, so a catalyst is a pair
+  of arcs, consuming the token and returning it.
+- **Alternative catalyst sets become separate transitions**, named `r1`, `r1#2`, …, since
+  a transition's preset is a conjunction and cannot express "either set".
+- **Food gets source transitions**, because RAF food is inexhaustible and no initial
+  marking expresses that — a marking of *n* deadlocks after *n* uses.
+
+Inhibition has no `ptnet` representation and is written as a `toolspecific` annotation,
+with a warning in the file: a reader that ignores it gets a *different system*.
+Reactions requiring a catalyst that nothing provides are omitted and counted, since
+emitting them unconstrained would make them freely fireable — the opposite of the intent.
+
 ## Catalysis is a relation, not a list
 
 `catalysts[r]` is a set of **alternative catalyst sets**, following Huson, Xavier &

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

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

@@ -19,13 +19,14 @@ from rafkit.gillespie import Trajectory, propensities, simulate
 from rafkit.inhibition import (classes_from_inhibitors, is_uninhibited, is_uraf,
                                max_urafs, support)
 from rafkit.network import ReactionNetwork
+from rafkit.pnml import to_pnml, write_pnml
 from rafkit.raf import (
     RafResult, catrenet_strictly_autocatalytic, core_raf, exploitability,
     has_unique_irraf, irrraf_census, is_food_catalysed, max_raf, max_raf_strict,
     sample_irrraf,
 )
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 __all__ = [
     "BinaryPolymerNetwork", "binary_polymer", "ReactionNetwork",
@@ -34,6 +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.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.3.0 → rafkit-0.4.0/src/rafkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rafkit
-Version: 0.3.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,12 +115,33 @@ counted as **one** catalysed reaction, not two. Use `net.catalysis_level` — no
 | `binary_polymer` | Kauffman binary polymer generator, with optional cleavage |
 | `ReactionNetwork` | arbitrary catalytic reaction systems, same protocol |
 | `read_crs` / `write_crs` | CatReNet's CRS interchange format |
+| `to_pnml` / `write_pnml` | PNML export (ISO/IEC 15909-2) for the Petri net ecosystem |
 | `simulate` | Gillespie direct method — watch subRAFs seed themselves into existence |
 | `max_urafs` | uninhibited RAFs, when a molecule can prevent a reaction |
 
 Every algorithm carries hand-computed known-answer tests, because a RAF algorithm that
 is subtly wrong produces plausible numbers rather than errors.
 
+## A reaction network is a Petri net
+
+Species are places, reactions are transitions, molecule counts are tokens. `write_pnml`
+exports to PNML (ISO/IEC 15909-2), so these networks open in Petri net editors, model
+checkers, and the unfolding tools that compute the causal structure of a run.
+
+Three things need care, and each is explicit rather than silent:
+
+- **Catalysis becomes a self-loop.** P/T nets have no read arc, so a catalyst is a pair
+  of arcs, consuming the token and returning it.
+- **Alternative catalyst sets become separate transitions**, named `r1`, `r1#2`, …, since
+  a transition's preset is a conjunction and cannot express "either set".
+- **Food gets source transitions**, because RAF food is inexhaustible and no initial
+  marking expresses that — a marking of *n* deadlocks after *n* uses.
+
+Inhibition has no `ptnet` representation and is written as a `toolspecific` annotation,
+with a warning in the file: a reader that ignores it gets a *different system*.
+Reactions requiring a catalyst that nothing provides are omitted and counted, since
+emitting them unconstrained would make them freely fireable — the opposite of the intent.
+
 ## Catalysis is a relation, not a list
 
 `catalysts[r]` is a set of **alternative catalyst sets**, following Huson, Xavier &

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

@@ -8,6 +8,7 @@ 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
@@ -17,6 +18,7 @@ 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_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")