hub:
  repo_type: generator
  builtin: bigan-conservative-crn
  tags:
  - banzhaf-yamamoto
chemistries:
- id: bigan-conservative-crn
  name: Conservative random chemical reaction networks
  intuition: 'A random reaction network built to be thermodynamically honest. Each abstract chemical gets
    a random free energy of formation; reactions are drawn as association, dissociation and transformation
    steps, and every backward rate is then computed from the forward one so detailed balance holds. The
    result is a network you can drive out of equilibrium with a nutrient influx and still trust. It is
    the easiest place to see what the thermodynamic tier costs: consistency is a constraint between forward
    and reverse rates, not extra data.

    '
  origin: Bigan, Steyaert & Douady, 2013
  book: 11.3.2
  refs:
  - '[117]'
  - '[756]'
  - '[956]'
  family: network
  kind: generator
  constructive: false
  S:
    repr: N abstract chemicals A_0..A_(N-1), each with a random Gibbs free energy of formation
    definition: explicit
  R:
    definition: implicit
    arity:
    - 1
    - 2
    scheme: association A_i + A_j -> A_k ; dissociation A_i -> A_j + A_k ; transformation A_i -> A_j ;
      each kept as a forward/reverse pair
    notes: 'Reactions are added one at a time at random, keeping the network conservative (a strictly
      positive mass vector m with m^T S = 0 exists), until no remaining reaction can be added.

      '
  A:
    reactor: ode
    dilution: external nutrient inflow drives the system out of equilibrium
  params:
  - name: N
    type: int
    default: 10
    min: 2
    max: 20
    role: structural
    meaning: number of chemical species (the paper uses 10, and 20 for checks)
  - name: max_reactions
    type: int
    default: 0
    min: 0
    role: structural
    meaning: stop after this many direct reactions; 0 builds a maximum-sized network (17-96, mean 42 direct
      reactions for N = 10 in the paper)
  - name: kinetics
    type: enum
    default: mass-action
    choices:
    - mass-action
    - saturating
    role: kinetic
    meaning: saturating kinetics f = k prod [A]/(1 + [A]/K) models molecular crowding
  - name: k_avg_mono
    type: float
    default: 100.0
    min: 0
    role: kinetic
    meaning: 'geometric mean of monomolecular forward constants (1/s): k = k_avg 10^U(-s/2, s/2)'
  - name: k_avg_bi
    type: float
    default: 10000.0
    min: 0
    role: kinetic
    meaning: geometric mean of bimolecular forward constants (1/(M s))
  - name: s
    type: float
    default: 0.0
    min: 0
    role: kinetic
    meaning: spread of forward rate constants, in orders of magnitude
  - name: K_avg
    type: float
    default: 0.01
    min: 0
    role: kinetic
    meaning: geometric mean saturation concentration (M) for saturating kinetics
  - name: p
    type: float
    default: 0.0
    min: 0
    role: kinetic
    meaning: spread of saturation concentrations, in orders of magnitude
  - name: G_max
    type: float
    default: 15.0
    min: 0
    role: thermodynamic
    meaning: formation free energies are drawn as G_i/RT ~ U(0, G_max)
  - name: nutrient
    type: int
    default: 5
    min: -1
    role: population
    meaning: index of the species receiving the external flux (the paper uses A5); -1 for a closed system
  - name: nutrient_flux
    type: float
    default: 1.0
    min: 0
    role: population
    meaning: external nutrient flux f_nu (M/s)
  - name: initial_concentration
    type: float
    default: 0.001
    min: 0
    role: population
    meaning: initial concentration of every species (the paper uses 1 mM)
  provides:
  - topology
  - stoichiometry
  - rate-constants
  - rate-law
  - energies
  - thermodynamic-consistency
  - mass-conservation
  - flow
  - initial-state
  fidelity: reconstructed
  sources:
  - Bigan, E., Steyaert, J.-M. & Douady, S. (2013). Properties of random complex chemical reaction networks
    and their relevance to biological toy models. arXiv:1303.7439, sections 2-3
  decisions:
  - 'Topology follows sec. 2.1: exchange reactions are excluded, candidates are tried in random order,
    and a candidate is kept while a mass vector m >= 1 with m^T S = 0 exists (checked by linear programming).
    Once that vector is unique, a candidate is kept iff it is orthogonal to it.'
  - 'Kinetics follow sec. 2.2 with the paper''s values: k_avg_mono = 1e2 /s, k_avg_bi = 1e4 /(M s), K_avg
    = 1e-2 M, G/RT ~ U(0, 15), s = p = 0. The forward direction is the one with decreasing free energy,
    and the reverse constant is k_forward exp(-|dG|/RT) with c0 = 1 M. The paper''s printed reverse formulas
    for mixed molecularity differ only by the c0 factor, which is 1 here.'
  - Forward/reverse reactions are adjacent, with their indices listed in extras.reaction_pairs. extras.energies
    holds G_i/RT, and extras.conservation holds the admissible mass vector (integers when rational).
  - The old density parameter is not part of the network (the paper sweeps initial density to compute
    equilibria) and is dropped. The nutrient flux is the network inflow.
  phenomena:
  - at equilibrium one chemical dominates as a function of density (saturating kinetics)
  - under nutrient flux all but one species reach constant concentration while one grows unbounded - a
    'directed transformation machine' producing a putative membrane precursor
  notes: 'The easiest thermodynamic entry: random generation with a conservativity check and backward
    rates fixed by detailed balance.

    '