chemart / kappa-calculus

hub:
  repo_type: generator
  builtin: kappa-calculus
  tags:
  - banzhaf-yamamoto
chemistries:
- id: kappa-calculus
  name: Kappa calculus
  intuition: '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.

    '
  aliases:
  - κ-calculus
  - Kappa
  - Kappa language
  - rule-based modelling of site graphs
  origin: 'Danos & Laneve, 2004; the Kappa language: Danos, Feret, Fontana, Harmer, Krivine et al., 2007
    onwards'
  book: '9.7'
  refs:
  - '[208]'
  - doi:10.1016/j.tcs.2004.03.065
  family: rewriting
  kind: formalism
  constructive: true
  S:
    repr: '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}[.])

      '
    definition: implicit
    notes: 'Kappa site graphs are rigid (site names are distinct within an agent), so an embedding of
      a connected pattern is fixed by the image of one agent and the canonical form is the least breadth-first
      text over the possible roots.

      '
  R:
    definition: implicit
    arity:
    - 1
    - 2
    scheme: '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.

      '
    notes: 'Components of a rule''s left-hand side match distinct complexes (bimolecular); inside one
      complex only when a unimolecular rate is given (@ k {k_uni}). Rules with three or more disconnected
      components give reactions of that order.

      '
  A:
    reactor:
    - ode
    - ssa
    - graph-rewrite
    dilution: none
    notes: 'Kappa''s native semantics is a continuous-time Monte Carlo over the site graph (KaSim) that
      never enumerates species; Chemart flattens the rules into the equivalent mass-action reaction network
      (KaDE''s differential semantics), cut by species and complex-size budgets when polymerisation makes
      it infinite. The unflattened model is kept in extras (rules, signatures, init, kappa file text).

      '
  params:
  - name: model
    type: enum
    default: abc
    choices:
    - abc
    - dimerization
    - polymerization
    - egfr
    - custom
    role: structural
    meaning: 'abc: the ''Hello ABC'' model of the Kappa reference guide (sec. 1.3; 10 species, 11 reactions);
      dimerization: its ''symmetric dimerization'' rule (sec. 2.3.1.1); polymerization: its ''ambiguous
      molecularity'' rule A(x[.]),A(y[.]) -> A(x[1]),A(y[1]) @ 0.001 {0.1} (chains and rings, truncated);
      egfr: the EGFR network of Blinov et al. (2006) from KaDE''s benchmark egfr_net.ka (356 species,
      3749 reactions); custom: signatures, rules and init'
  - name: signatures
    type: list
    default: []
    range: e.g. ['A(x,c)', 'B(x)', 'C(x1{u p},x2{u p})']; the first state listed is the default
    role: structural
    meaning: 'custom only: agent signatures, Kappa 4 syntax Name(site{state state ...}, ...)'
  - name: rules
    type: list
    default: []
    range: e.g. ["'bind' A(x[.]), B(x[.]) <-> A(x[1]), B(x[1]) @ 1e-4, 0.1"]; edit notation A(x[./1]),B(x[./1])
      @ k; unimolecular rate as @ k {k_uni}
    role: kinetic
    meaning: 'custom only: Kappa rules with numeric rates; links [.] [n] [_] [#] [site.Agent], states
      {s} {#}, unwritten sites untested; agent creation and deletion are not supported'
  - name: init
    type: dict
    default: {}
    range: 'e.g. {''A(),B()'': 1000, ''C(x1{u},x2{u})'': 10000}'
    role: population
    meaning: 'custom only: initial copies of each Kappa expression (its connected components are the initial
      complexes; unwritten sites take the default state and are free)'
  - name: symmetry
    type: enum
    default: rule
    choices:
    - rule
    - lhs
    - none
    role: kinetic
    meaning: 'symmetry factor applied to rule rates (Kappa reference guide 3.3.1): rule = 1/|automorphisms
      of the left-hand side preserved on the right| (stance D, the biochemist convention), lhs = 1/|Aut(L)|
      (stance ND, the SSA convention), none = 1 (KaSim''s default)'
  - name: max_species
    type: int
    default: 2000
    min: 1
    max: 100000
    range: egfr closes at 356 species
    role: structural
    meaning: species budget of the closure; reactions that would add more are dropped and status becomes
      truncated
  - name: max_complex_size
    type: int
    default: 20
    min: 1
    max: 1000
    range: the largest egfr complex has 14 agents; polymerization closes only under this budget
    role: structural
    meaning: maximum agents in a complex; reactions producing a larger complex are dropped and status
      becomes truncated (KaDE's truncation option)
  provides:
  - topology
  - stoichiometry
  - rate-constants
  - initial-state
  - mass-conservation
  - sequence-structure-function
  fidelity: reconstructed
  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/'
  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.'
  phenomena:
  - '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'')'
  notes: 'Rule-based, combinatorially explosive species set: the archetype of a chemistry that should
    not be flattened blindly, which is why the flattening is budgeted and the rules themselves are kept
    in extras.rules and extras.kappa for exporters (KaSim, KaDE). The module also exports signatures,
    parse_rules, embed, automorphisms, canonical and kappa3_to_kappa4.

    '