How it works

How to describe a chemistry you could never enumerate. Agents are proteins with named sites; a site can hold an internal state and a bond to another site, and a rule rewrites a *partial* pattern - bind these two sites, phosphorylate this one - regardless of what else is attached. One rule therefore stands for an enormous number of concrete reactions between complexes. Twenty-odd rules for a receptor pathway expand to thousands of reactions, which is exactly why you keep the rules and never flatten them.

S

agents (proteins) with named sites; a site may carry an internal state (e.g. u/p) and a link to one site of another agent. A species is a complex: a connected, fully specified site graph, identified up to isomorphism. Species id and structure are its canonical Kappa expression, e.g. A(x[1],c[2]),B(x[1]),C(x1{u}[2],x2{u}[.]) · implicit

R

rules rewrite patterns (partially specified site graphs) by binding, unbinding and changing internal states, e.g. 'rule 2' A(x[_],c[.]), C(x1{u}[.]) -> A(x[_],c[2]), C(x1{u}[2]) @ 1e-4. One rule stands for every reaction between complexes that contain its left-hand side; the network is the closure of the rules over the complexes reachable from the initial ones. · arity 1, 2

A

ode, ssa, graph-rewrite · none

Parameters

What to look for

• a handful of rules stands for many reactions: the 23 EGFR rules (39 one-way rules) flatten to 356 species and 3749 reactions (Blinov et al. 2006)
• ABC model (reference guide fig. 3): unmodified C is replaced first by singly (Cpu) then doubly phosphorylated C (Cpp); the AB complexes settle slightly below 400
• asymmetric binding polymerises (chains and, with a unimolecular rate, rings); symmetric binding gives strict dimers (reference guide 2.3.1.1)
• rule symmetries change rates: under stance D a symmetric rule that breaks its symmetry ('1p') fires twice as often as one that keeps it ('2p')

Implementation decisions

• Language: the book's one paragraph and Danos & Laneve (2004) define the κ-calculus with sites that are bound, or free and visible or hidden. Chemart implements the subset of its successor, the Kappa 4 language of the reference guide, that covers exactly binding, unbinding and internal-state change: visible/hidden is an internal state {v h}. The 2004 paper's pdftotext extraction lost its Greek and symbols, so its algebraic syntax was not reproduced; the semantics (proteins with sites, complexes as connected graphs, complexation/decomplexation rules) is the same.
• Not supported (ValueError): agent creation and deletion ('.' slots, + and - in edit notation), counters, tokens, %var names and algebraic rate expressions (rates are numbers). Hence agents of every type are conserved, given in extras.conservation.
• v1 parameters agent_signatures (callable), rules (callable) and rates (matrix) became the model choice plus the custom signatures/rules/init lists in Kappa syntax, with rates written in the rules. Added symmetry, max_species and max_complex_size.
• Flattening follows KaDE's differential semantics: each connected component of a rule's left-hand side matches its own complex; both components of a two-component rule match inside one complex only when a unimolecular rate {k} is given (KaSim instead applies a single rate to both cases). Rules with three or more components give only reactions of that order.
• Rate of a flattened reaction R: k_R = sum over the embeddings of the rule into the reactant copies that yield R of gamma * Omega / prod m_i!, in molecule-count units with volume 1 (the rule rates of the published models are already per molecule). Then k_R prod x_i^m_i equals the rule activity of reference guide eq. (1), e.g. gamma n(n-1) for an A + A rule under 'none'. Reactions produced by several rules sum their rates; extras.reaction_rules lists the rules.
• Symmetry convention default: 'rule' (stance D, 1/|Aut(L) preserved in R|), argued for in the reference guide's appendix E and named the biochemist convention by KaDE; 'lhs' (stance ND, SSA) and 'none' (KaSim's default, Null) are offered. The guide's prose says both '1p' and '2p' have activity k/2 under stance ND, but its eq. (1)-(2) give 2 embeddings x 1/2 x k = k; Chemart follows the equations, and the ratios the guide states ('1p' twice '2p' under D, and twice itself under ND) hold.
• Species identity: the canonical Kappa expression (least breadth-first text over roots of the smallest agent type, sites in signature order, bonds numbered by appearance) is both id and structure, so isomorphic complexes are one species regardless of how they are written.
• Named models: abc is the reference guide's section 1.3 model with its %var rates (on 1e-4, off 0.1, mod 1) and %init (1000 A, 1000 B, 10000 C); dimerization and polymerization are single rules printed in section 2.3.1.1 without initial amounts, so their initial_state is omitted (the seed is the free monomer). egfr translates KaDE's egfr_net.ka (Kappa 3: a bare site is free, site~state!link) programmatically into Kappa 4 with its %var values substituted; signatures are read off its %init lines; rules are labelled R1..R22 in file order.
• Published counts reproduced: egfr gives 356 species and 3749 reactions, the numbers of Blinov et al. (2006) and of KaDE's ground network. The ABC network (10 species, 11 reactions) is not counted in the sources; it was derived by hand from the five rules and agrees with the generator.
• Truncation: max_complex_size drops reactions whose products exceed it (KaDE offers the same truncation); max_species is expand's species budget. Either sets status truncated. polymerization is infinite: with max_complex_size n it gives chains of 1..n agents and rings of 2..n (a monomer cannot bind itself because embeddings are injective).
• Mass-action is the only law: Kappa rules carry stochastic rate constants and the flattened ODE is the mass-action system over complexes. No flow, no energies.

Sources

• Banzhaf, W. & Yamamoto, L. (2015). Artificial Chemistries, section 9.7 (one paragraph: proteins with binding sites, complexes as graphs, graph-rewriting rules for binding and dissociation).
• Danos, V. & Laneve, C. (2004). Formal molecular biology. Theoretical Computer Science 325(1):69-110 (book [208]). Proteins with sites, complexes as connected graphs, monotonic (complexation) and antimonotonic (decomplexation) reactions. https://www.cs.unibo.it/~laneve/papers/fmb.pdf
• Fontana, W., Boutillier, P., Feret, J. & Krivine, J. The Kappa Language: A Reference Guide v4. KappaLanguage.org. Sections 1.3 (ABC model and rates), 2.2-2.4 (patterns, arrow and edit notation, signatures, default states, %init), 3.2-3.3 (symmetry, rule activity, the ND/D/Null stances, eqs. 1-4), 3.5 (rate constants), 3.7 (ambiguous molecularity), appendix E (symmetries of a rule). https://kappalanguage.org/static/manual.pdf
• Camporesi, F., Feret, J. & Lý, K. Q. (2017). KaDE: a tool to compile Kappa rules into (reduced) ODE models. CMSB 2017. ODE semantics d[S]/dt = sum gamma(r) [r,R] Delta(R,S) prod [R_i], the three rate conventions, disconnected components kept apart unless a unary rate is given, truncation by complex size. https://www.di.ens.fr/~feret/CMSB2017-tool-paper/kade-tool-paper.pdf ; ground species counts of the benchmarks (egfr_net: 356): https://www.di.ens.fr/~feret/CMSB2017-tool-paper/
• KappaTools repository, examples/abc.ka (the ABC model in edit notation) and examples/benchmarks/CMSB2017-KaDe-tool-paper/BNGL/egfr_net.ka (the EGFR model in Kappa 3). https://github.com/Kappa-Dev/KappaTools
• Blinov, M. L., Faeder, J. R., Goldstein, B. & Hlavacek, W. S. (2006). A network model of early events in epidermal growth factor receptor signaling that accounts for combinatorial complexity. Biosystems 83(2-3):136-151: 356 molecular species connected by 3749 unidirectional reactions. https://pubmed.ncbi.nlm.nih.gov/16233948/

Banzhaf & Yamamoto, Artificial Chemistries (2015), §9.7

Preview at default parameters

10 species · 11 reactions · status complete · seed 1

A(x[.],c[.]) + B(x[.]) -> A(x[1],c[.]),B(x[1])  [mass-action k=0.0001]
A(x[1],c[.]),B(x[1]) -> A(x[.],c[.]) + B(x[.])  [mass-action k=0.1]
C(x1{u}[.],x2{u}[.]) + A(x[1],c[.]),B(x[1]) -> A(x[1],c[2]),B(x[1]),C(x1{u}[2],x2{u}[.])  [mass-action k=0.0001]
A(x[1],c[2]),B(x[1]),C(x1{u}[2],x2{u}[.]) -> A(x[.],c[1]),C(x1{u}[1],x2{u}[.]) + B(x[.])  [mass-action k=0.1]
A(x[1],c[2]),B(x[1]),C(x1{u}[2],x2{u}[.]) -> A(x[1],c[.]),B(x[1]) + C(x1{p}[.],x2{u}[.])  [mass-action k=1.0]
A(x[.],c[1]),C(x1{u}[1],x2{u}[.]) -> A(x[.],c[.]) + C(x1{p}[.],x2{u}[.])  [mass-action k=1.0]
B(x[.]) + A(x[.],c[1]),C(x1{u}[1],x2{u}[.]) -> A(x[1],c[2]),B(x[1]),C(x1{u}[2],x2{u}[.])  [mass-action k=0.0001]
A(x[.],c[.]) + C(x1{p}[.],x2{u}[.]) -> A(x[.],c[1]),C(x1{p}[.],x2{u}[1])  [mass-action k=0.0001]
A(x[.],c[1]),C(x1{p}[.],x2{u}[1]) -> A(x[.],c[.]) + C(x1{p}[.],x2{p}[.])  [mass-action k=1.0]
B(x[.]) + A(x[.],c[1]),C(x1{p}[.],x2{u}[1]) -> A(x[1],c[2]),B(x[1]),C(x1{p}[.],x2{u}[2])  [mass-action k=0.0001]
A(x[1],c[2]),B(x[1]),C(x1{p}[.],x2{u}[2]) -> A(x[.],c[1]),C(x1{p}[.],x2{u}[1]) + B(x[.])  [mass-action k=0.1]

Generated by the uploader with chemart push; the hub never runs uploaded code.