Kinetics

Reaction kinetics shared by the biology packages: molecular species, saturating reactions, and repression.

MichaelisMentenInteraction(label, *, target=None, reactants=None, products=None, substrate='n', vmax=1.0, km=1.0, modifiers=None, mode='rate')

Bases: ReactionInteraction

Reaction at the Michaelis-Menten propensity vmax S / (km + S), times every modifier to its coefficient.

The substrate S is a state of the target, or a function of the namespace that returns an amount that is no state of its own, such as the phosphorylated form A_T - A of a protein whose total is conserved. The modifiers are the enzymes that catalyse the reaction, which scale the propensity but do not change, so vmax is a catalytic rate when the reaction has modifiers and a maximal rate when it has none. The maximal rate and the Michaelis constant are functions of the namespace, which reads the parameters of the target, or numbers.

Parameters:

Name	Type	Description	Default
label	str	The label of the reaction, unique among the parts of its system.	required
target	Annotated[str | None, RoleSpec()]	The path of the element, group, or field whose states the species named by a state alone are.	None
reactants	Annotated[Stoichiometry | None, RoleSpec(variadic=True)]	The coefficients of the reactants, or None for a source.	None
products	Annotated[Stoichiometry | None, RoleSpec(variadic=True)]	The coefficients of the products, or None for a sink.	None
substrate	str | Callable[[SimpleNamespace], object]	The name of the state of the target that saturates the propensity, or a function of the namespace that returns the amount that does.	'n'
vmax	Callable[[SimpleNamespace], object] | float	A function of the namespace that returns the maximal or catalytic rate, or a number.	1.0
km	Callable[[SimpleNamespace], object] | float	A function of the namespace that returns the Michaelis constant, or a number.	1.0
modifiers	Annotated[Stoichiometry | None, RoleSpec(variadic=True)]	The coefficients of the modifiers, the enzymes that scale the propensity, or None.	None
mode	str	The form of the laws, 'rate', 'jump', or 'langevin'.	'rate'

Raises:

Type	Description
ValidationError	The substrate is neither a name nor a function, a rate is neither a function nor a number, or the reaction cannot take its species or mode.

Examples:

>>> from skcomplex.core.components.elements import CompartmentElement
>>> from skcomplex.core.components.system import System
>>> from skcomplex.core.engine.runtime import Simulation
>>> from skcomplex.systems.biology.common.kinetics import MichaelisMentenInteraction
>>> uptake = MichaelisMentenInteraction(
...     'uptake', target='cell', reactants={'n': 1}, substrate='n', vmax=1.0, km=100.0
... )
>>> system = System(elements=[CompartmentElement('cell', n=500.0)], interactions=[uptake])
>>> trajectory = Simulation(system, dt=1.0).prepare().run(until=10.0).trajectory_
>>> round(float(trajectory.values('cell.n')[-1]), 3)
491.679

Source code in src/skcomplex/systems/biology/common/kinetics/_michaelis_menten.py

def __init__(
    self,
    label: str,
    *,
    target: Annotated[str | None, RoleSpec()] = None,
    reactants: Annotated[Stoichiometry | None, RoleSpec(variadic=True)] = None,
    products: Annotated[Stoichiometry | None, RoleSpec(variadic=True)] = None,
    substrate: str | Callable[[SimpleNamespace], object] = 'n',
    vmax: Callable[[SimpleNamespace], object] | float = 1.0,
    km: Callable[[SimpleNamespace], object] | float = 1.0,
    modifiers: Annotated[Stoichiometry | None, RoleSpec(variadic=True)] = None,
    mode: str = 'rate',
) -> None:
    super().__init__(label, target=target, reactants=reactants, products=products, modifiers=modifiers, mode=mode)
    self.substrate = substrate
    self.vmax = vmax
    self.km = km

RepressionInteraction(label, *, reactants=None, products=None, modifiers=None, alpha=1.0, alpha0=0.0, K=1.0, n=1.0, mode='rate')

Bases: ReactionInteraction

Synthesis of a product at the rate alpha0 + alpha (1 - hill(y, K, n)), repressed by a modifier y.

The product, such as the mRNA of a gene, gains units at the leaky rate alpha0 plus the rate alpha lowered by the decreasing Hill function 1 / (1 + (y / K)^n) of the one modifier, the repressor. The repressor enters the rate and does not change. In the mode 'jump' every synthesis is a random event that adds one unit.

Parameters:

Name	Type	Description	Default
label	str	The label of the repression.	required
reactants	Annotated[Stoichiometry | None, RoleSpec(variadic=True)]	The coefficients of the reactants, or None for a synthesis from a source.	None
products	Annotated[Stoichiometry | None, RoleSpec(variadic=True)]	The coefficient of the synthesized state, such as {('gene', 'm'): 1}.	None
modifiers	Annotated[Stoichiometry | None, RoleSpec(variadic=True)]	The coefficient of the repressor state, such as {('repressor', 'p'): 1}.	None
alpha	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The synthesis rate without repressor.	1.0
alpha0	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The leaky synthesis rate at saturating repressor.	0.0
K	Annotated[float, ParameterSpec(domain=open(0, oo))]	The repressor amount at half repression.	1.0
n	Annotated[float, ParameterSpec(domain=open(0, oo))]	The Hill coefficient of the repression.	1.0
mode	str	The form of the laws, 'rate', 'jump', or 'langevin'.	'rate'

Raises:

Type	Description
ValidationError	The mode is unknown, the reaction has neither reactants nor products, or an entry is not a pair of a path and a state name with a positive coefficient.

Examples:

>>> from skcomplex.core.components.system import System
>>> from skcomplex.core.engine.runtime import Simulation
>>> from skcomplex.systems.biology.systems_biology import RepressionInteraction, SpeciesElement
>>> repression = RepressionInteraction(
...     'repression', products={('mRNA', 'x'): 1}, modifiers={('repressor', 'x'): 1}, alpha=2.0, K=1.0
... )
>>> species = [SpeciesElement('mRNA'), SpeciesElement('repressor', x=1.0)]
>>> trajectory = Simulation(System(elements=species, interactions=[repression]), dt=0.1).prepare()
>>> round(float(trajectory.run(until=1.0).trajectory_.values('mRNA.x')[-1]), 3)
1.0

Source code in src/skcomplex/systems/biology/common/kinetics/_repression.py

def __init__(
    self,
    label: str,
    *,
    reactants: Annotated[Stoichiometry | None, RoleSpec(variadic=True)] = None,
    products: Annotated[Stoichiometry | None, RoleSpec(variadic=True)] = None,
    modifiers: Annotated[Stoichiometry | None, RoleSpec(variadic=True)] = None,
    alpha: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
    alpha0: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
    K: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    n: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    mode: str = 'rate',
) -> None:
    super().__init__(label, reactants=reactants, products=products, modifiers=modifiers, mode=mode)
    self.alpha = alpha
    self.alpha0 = alpha0
    self.K = K
    self.n = n

SpeciesElement(label, visual=None, *, x=0.0)

Bases: Element

Molecular species, an mRNA, an enzyme, a messenger, or a metabolite, with a nonnegative concentration x.

A species has no laws of its own, and reactions synthesize, convert, and degrade it.

Parameters:

Name	Type	Description	Default
label	str	The label of the species.	required
visual	VisualSpec | None	How the element is drawn, or None for default_visual_.	None
x	Annotated[float, StateSpec(domain=closed_open(0, oo))]	The initial concentration.	0.0

Examples:

>>> from skcomplex.systems.biology.systems_biology import SpeciesElement
>>> SpeciesElement('camp', x=2.0).x
2.0

Source code in src/skcomplex/systems/biology/common/kinetics/_species.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x