Generators#

stochastix.generators.lotka_volterra_model #

lotka_volterra_model(
    alpha: float | floating = 1.1,
    beta: float | floating = 0.4,
    gamma: float | floating = 0.4,
) -> ReactionNetwork

Generate a basic Lotka-Volterra predator-prey model.

This model describes the dynamics of two interacting species, a predator and a prey, based on the following reactions:

Prey reproduction: prey -> 2 prey with rate alpha.
Predator-prey interaction: prey + predator -> 2 predator with rate beta.
Predator death: predator -> 0 with rate gamma.

Parameters:

alpha (float | floating, default: 1.1 ) –

The rate of prey reproduction.
beta (float | floating, default: 0.4 ) –

The rate of predation.
gamma (float | floating, default: 0.4 ) –

The rate of predator death.

Returns:

ReactionNetwork –

ReactionNetwork representing the Lotka-Volterra system.

stochastix.generators.sirs_model #

sirs_model(
    beta: float | floating = 1.0,
    gamma: float | floating = 0.1,
    nu: float | floating = 0.01,
) -> ReactionNetwork

Generate a classic SIRS epidemiological model.

This model describes the spread of an infectious disease in a population based on the following reactions:

Infection: S + I -> 2 I (transmission rate beta)
Recovery: I -> R (recovery rate gamma)
Loss of immunity: R -> S (waning immunity rate nu)

The model assumes: - S: Susceptible individuals - I: Infected individuals - R: Recovered individuals (with temporary immunity)

Note

Setting the waning immunity rate nu to zero reduces this model to the classic SIR model.

Parameters:

beta (float | floating, default: 1.0 ) –

The transmission rate (rate of infection per S-I contact).
gamma (float | floating, default: 0.1 ) –

The recovery rate (rate at which infected individuals recover).
nu (float | floating, default: 0.01 ) –

The waning immunity rate (rate at which recovered individuals lose immunity and become susceptible again).

Returns:

ReactionNetwork –

ReactionNetwork representing the SIRS system.

stochastix.generators.single_gene_expression_model #

single_gene_expression_model(
    k_m: float | floating = 0.1,
    k_p: float | floating = 10.0,
    gamma_m: float | floating = 0.1,
    gamma_p: float | floating = 0.01,
) -> ReactionNetwork

Generate a Thattai-van Oudenaarden model for single-gene expression.

This model describes the stochastic production and degradation of mRNA and protein from a single gene. It includes four fundamental reactions:

Transcription: 0 -> mRNA (mRNA production)
Translation: mRNA -> mRNA + P (Protein production from mRNA)
mRNA Degradation: mRNA -> 0
Protein Degradation: P -> 0

Parameters:

k_m (float | floating, default: 0.1 ) –

Transcription rate (rate of mRNA production).
k_p (float | floating, default: 10.0 ) –

Translation rate (rate of protein production per mRNA).
gamma_m (float | floating, default: 0.1 ) –

mRNA degradation rate.
gamma_p (float | floating, default: 0.01 ) –

Protein degradation rate.

Returns:

ReactionNetwork –

ReactionNetwork representing the single-gene expression system.

stochastix.generators.michaelis_menten_explicit_model #

michaelis_menten_explicit_model(
    k_f: float | floating = 0.01,
    k_r: float | floating = 0.001,
    k_cat: float | floating = 0.1,
) -> ReactionNetwork

Generate an explicit Michaelis-Menten enzyme kinetics model.

This model explicitly describes the formation of an enzyme-substrate complex (C) from an enzyme (E) and substrate (S), and the subsequent production of a product (P).

The model includes three reactions: 1. Binding: E + S -> C (forward reaction) 2. Unbinding: C -> E + S (reverse reaction) 3. Conversion: C -> E + P (catalytic reaction)

Parameters:

k_f (float | floating, default: 0.01 ) –

The forward rate constant for enzyme-substrate binding.
k_r (float | floating, default: 0.001 ) –

The reverse rate constant for complex dissociation.
k_cat (float | floating, default: 0.1 ) –

The catalytic rate constant for product formation.

Returns:

ReactionNetwork –

ReactionNetwork representing the explicit Michaelis-Menten system.

stochastix.generators.schlogl_model #

schlogl_model(
    k1: float | floating = 1.0,
    k2: float | floating = 0.18,
    k3: float | floating = 2.4,
    k4: float | floating = 1.0,
) -> ReactionNetwork

Generate the Schlögl model, a classic example of a bistable system.

This model describes the dynamics of a single species X subject to autocatalysis and degradation. The reactions are: 1. Autocatalysis: 2X -> 3X (forward reaction) 2. Reverse Autocatalysis: 3X -> 2X (reverse reaction) 3. Production: 0 -> X (zeroth-order production) 4. Degradation: X -> 0 (first-order degradation)

The model is known to exhibit bistability for certain parameter values, meaning it can exist in two different stable steady states.

Parameters:

k1 (float | floating, default: 1.0 ) –

The rate constant for the forward autocatalytic reaction.
k2 (float | floating, default: 0.18 ) –

The rate constant for the reverse autocatalytic reaction.
k3 (float | floating, default: 2.4 ) –

The rate constant for the production reaction.
k4 (float | floating, default: 1.0 ) –

The rate constant for the degradation reaction.

Returns:

ReactionNetwork –

ReactionNetwork representing the Schlögl system.

stochastix.generators.hopfield_kinetic_proofreading_model #

hopfield_kinetic_proofreading_model(
    k_f: float | floating = 1.0,
    k_r: float | floating = 0.1,
    k_p: float | floating = 1.0,
    k_d: float | floating = 0.1,
    k_cat: float | floating = 10.0,
) -> ReactionNetwork

Generate a Hopfield kinetic proofreading model.

This model describes how an enzyme can achieve high fidelity by introducing an intermediate, energy-dependent proofreading step. This allows the system to discard incorrectly bound substrates before they are converted to a product.

The model involves a substrate (S), an enzyme (E), an initial complex (C), an activated complex (C_activated), and a product (P).

The reactions are: 1. Binding: E + S -> C (rate k_f) 2. Unbinding: C -> E + S (rate k_r) 3. Activation (Proofreading step): C -> C_activated (rate k_p) 4. Discard: C_activated -> E + S (rate k_d) 5. Catalysis: C_activated -> E + P (rate k_cat)

Parameters:

k_f (float | floating, default: 1.0 ) –

The forward rate constant for enzyme-substrate binding.
k_r (float | floating, default: 0.1 ) –

The reverse rate constant for initial complex dissociation.
k_p (float | floating, default: 1.0 ) –

The rate of activation to the proofreading state.
k_d (float | floating, default: 0.1 ) –

The rate of discarding the substrate from the activated state.
k_cat (float | floating, default: 10.0 ) –

The catalytic rate for product formation.

Returns:

ReactionNetwork –

ReactionNetwork representing the Hopfield kinetic proofreading system.

stochastix.generators.toggle_switch_model #

toggle_switch_model(
    alpha: float
    | floating
    | ndarray
    | tuple
    | list = 100.0,
    alpha0: float | floating | ndarray | tuple | list = 0.1,
    K: float | floating | ndarray | tuple | list = 50.0,
    beta: float | floating | ndarray | tuple | list = 1.0,
    n: float | floating | ndarray | tuple | list = 2.0,
) -> ReactionNetwork

Generate a toggle switch gene regulatory network.

The toggle switch is a synthetic bistable network where two genes mutually repress each other (A represses B, and B represses A), creating a system with two stable states.

The model includes the following reactions: 1. Gene A expression, repressed by B. 2. Gene B expression, repressed by A. 3. Protein degradation of A and B.

Parameters:

alpha (float | floating | ndarray | tuple | list, default: 100.0 ) –

Maximum expression rate(s). Can be a single float or a tuple/list for individual rates (alpha_A, alpha_B).
alpha0 (float | floating | ndarray | tuple | list, default: 0.1 ) –

Leaky expression rate(s). Can be a single float or a tuple/list for individual rates (alpha0_A, alpha0_B).
K (float | floating | ndarray | tuple | list, default: 50.0 ) –

Half-saturation constant(s) for repression. Can be a single float or a tuple/list (K_A, K_B).
beta (float | floating | ndarray | tuple | list, default: 1.0 ) –

Protein degradation rate(s). Can be a single float or a tuple/list (beta_A, beta_B).
n (float | floating | ndarray | tuple | list, default: 2.0 ) –

Hill coefficient(s) for repression. Must be positive. Can be a single float or a tuple/list (n_A, n_B).

Returns:

ReactionNetwork –

ReactionNetwork representing the toggle switch system.

stochastix.generators.repressilator_model #

repressilator_model(
    alpha: float
    | floating
    | ndarray
    | tuple
    | list = 100.0,
    alpha0: float | floating | ndarray | tuple | list = 1.0,
    K: float | floating | ndarray | tuple | list = 50.0,
    beta: float | floating | ndarray | tuple | list = 5.0,
    n: float | floating | ndarray | tuple | list = 2.0,
) -> ReactionNetwork

Generate a repressilator gene regulatory network.

The repressilator is a synthetic genetic clock built from three genes that repress each other in a cycle (A represses B, B represses C, and C represses A), leading to oscillatory dynamics.

The model includes the following reactions: 1. Gene A expression, repressed by C. 2. Gene B expression, repressed by A. 3. Gene C expression, repressed by B. 4. Degradation of proteins A, B, and C.

The expression rates are modeled using repressive Hill kinetics with a basal (leaky) expression term.

Parameters:

alpha (float | floating | ndarray | tuple | list, default: 100.0 ) –

Maximum expression rate for each gene. Can be a single float or a tuple/list (alpha_A, alpha_B, alpha_C).
alpha0 (float | floating | ndarray | tuple | list, default: 1.0 ) –

Leaky expression rate for each gene. Can be a single float or a tuple/list (alpha0_A, alpha0_B, alpha0_C).
K (float | floating | ndarray | tuple | list, default: 50.0 ) –

Half-saturation constant for repression. Can be a single float or a tuple/list (K_A, K_B, K_C).
beta (float | floating | ndarray | tuple | list, default: 5.0 ) –

Protein degradation rate. Can be a single float or a tuple/list (beta_A, beta_B, beta_C).
n (float | floating | ndarray | tuple | list, default: 2.0 ) –

Hill coefficient for repression (must be positive). Can be a single float or a tuple/list (n_A, n_B, n_C).

Returns:

ReactionNetwork –

ReactionNetwork representing the repressilator system.

stochastix.generators.ffl_c1_model #

ffl_c1_model(
    k_x: float | floating = 0.0,
    beta_x: float | floating = 0.0,
    alpha_y: float | floating = 100.0,
    alpha0_y: float | floating = 0.1,
    K_xy: float | floating = 50.0,
    n_xy: float | floating = 2.0,
    beta_y: float | floating = 1.0,
    alpha_z: float | floating = 100.0,
    alpha0_z: float | floating = 0.1,
    K_xz: float | floating = 50.0,
    K_yz: float | floating = 50.0,
    n_xz: float | floating = 2.0,
    n_yz: float | floating = 2.0,
    beta_z: float | floating = 1.0,
    logic: str = 'and',
    competitive_binding: bool = False,
) -> ReactionNetwork

Generate a coherent type 1 feed-forward loop (C1-FFL) network.

In a C1-FFL, a master regulator X activates a second regulator Y, and both X and Y jointly activate a target gene Z. This motif is known for its ability to act as a sign-sensitive delay element or a persistence detector.

The network consists of three genes (X, Y, Z) with the following interactions: 1. X production and degradation (optional). 2. Y production, activated by X. 3. Z production, activated by both X and Y. 4. Degradation of Y and Z.

The regulation of Z by X and Y can be configured with 'and' or 'or' logic.

Note

The default model is built with no dynamics for X. You can include reactions for X by extending the model after it is generated.

Example

To add a reaction where X is produced at a constant rate:

model = ffl_c1_model(k_x=10.0)

To add a reaction where X production is activated by a signal S:

from stochastix.kinetics import HillActivator
from stochastix.reaction import Reaction

model = ffl_c1_model()
x_production_reaction = Reaction(
    '0 -> X',
    HillActivator(regulator='S', v=100.0, K=50.0, n=2.0, v0=0.1),
    name='X_production'
)
model = model + x_production_reaction

Parameters:

k_x (float | floating, default: 0.0 ) –

Production rate of X. If 0, the reaction 0 -> X is not included.
beta_x (float | floating, default: 0.0 ) –

Degradation rate of X. If 0, the reaction X -> 0 is not included.
alpha_y (float | floating, default: 100.0 ) –

Maximum production rate of Y (activated by X).
alpha0_y (float | floating, default: 0.1 ) –

Leaky production rate of Y.
K_xy (float | floating, default: 50.0 ) –

Half-saturation constant for X activating Y.
n_xy (float | floating, default: 2.0 ) –

Hill coefficient for X activating Y.
beta_y (float | floating, default: 1.0 ) –

Degradation rate of Y.
alpha_z (float | floating, default: 100.0 ) –

Maximum production rate of Z (activated by X and Y).
alpha0_z (float | floating, default: 0.1 ) –

Leaky production rate of Z.
K_xz (float | floating, default: 50.0 ) –

Half-saturation constant for X activating Z.
K_yz (float | floating, default: 50.0 ) –

Half-saturation constant for Y activating Z.
n_xz (float | floating, default: 2.0 ) –

Hill coefficient for X activating Z.
n_yz (float | floating, default: 2.0 ) –

Hill coefficient for Y activating Z.
beta_z (float | floating, default: 1.0 ) –

Degradation rate of Z.
logic (str, default: 'and' ) –

The logic for Z regulation by X and Y ('and' or 'or').
competitive_binding (bool, default: False ) –

Whether X and Y bind competitively to Z's promoter.

Returns:

ReactionNetwork –

ReactionNetwork representing the C1-FFL system.