Kinetic Laws

Kinetic laws for chemical reactions.

---

stochastix.kinetics.Constant

Constant(k: float, transform: Callable = None)

Constant kinetics for zeroth-order reactions.

This class implements constant kinetics where the reaction rate is independent of species concentrations, representing a zeroth-order reaction.

Attributes:

• k –

  The rate constant.

• transform –

  A function to transform the rate constant k before it is used, e.g., jnp.exp for log-rates.

• _requires_species –

  Tuple of species names required by this kinetics.

Methods:

• propensity_fn –

  Computes the constant propensity.

• ode_rate_fn –

  Computes the constant deterministic rate.

Parameters:

• k (float) –

  The rate constant.

• transform (Callable, default: None ) –

  A function to transform the rate constant k before it's used, e.g., jnp.exp for log-rates. Defaults to the identity function.

---

stochastix.kinetics.MassAction

MassAction(k: float, transform: Callable = None)

Mass-action kinetics for elementary reactions.

The propensity is computed as k * product_i C(x_i, s_i), where C is the binomial coefficient, x_i is the count of species i, and s_i is its stoichiometric coefficient. This corresponds to the standard stochastic formulation of mass-action kinetics.

The deterministic rate is computed as k * product_i (x_i/V)^s_i, where V is the volume.

Attributes:

• k –

  The rate constant.

• transform –

  A function to transform the rate constant k before it's used, e.g., jnp.exp for log-rates.

• _requires_species –

  Tuple of species names required by this kinetics.

Methods:

• propensity_fn –

  Computes the stochastic mass-action propensity.

• ode_rate_fn –

  Computes the deterministic mass-action rate.

Parameters:

• k (float) –

  The rate constant. The units depend on the order of the reaction.

• transform (Callable, default: None ) –

  A function to transform the rate constant k before it's used, e.g., jnp.exp for log-rates. Defaults to the identity function.

---

stochastix.kinetics.MichaelisMenten

MichaelisMenten(
    enzyme: str | float,
    k_cat: float,
    k_m: float,
    transform_k_cat: Callable = None,
    transform_k_m: Callable = None,
    *,
    _enzyme_idx: int = -1,
)

Michaelis-Menten kinetics for enzyme-catalyzed reactions.

The substrate is inferred from the reactants of the reaction, assuming it has a single reactant species. The rate is given by v_max * S / (k_m + S), where v_max = k_cat * E. The enzyme E can be a fixed abundance or a dynamic species.

Attributes:

• enzyme –

  The enzyme, which can be specified as a species name or a fixed abundance.

• enzyme_idx –

  The index of the enzyme species in the state vector.

• k_cat –

  The turnover number (units of 1/time).

• k_m –

  The Michaelis constant (units of concentration).

• transform_k_cat –

  A function to transform the k_cat parameter.

• transform_k_m –

  A function to transform the k_m parameter.

• _requires_species –

  Tuple of species names required by this kinetics.

Methods:

• propensity_fn –

  Calculates the Michaelis-Menten propensity.

• ode_rate_fn –

  Calculates the Michaelis-Menten deterministic rate.

Parameters:

• enzyme (str | float) –

  The enzyme, either as a species name or a fixed abundance (in number of molecules).

• k_cat (float) –

  The turnover number (in 1/time).

• k_m (float) –

  The Michaelis constant (in concentration).

• transform_k_cat (Callable, default: None ) –

  A transform for k_cat.

• transform_k_m (Callable, default: None ) –

  A transform for k_m.

• _enzyme_idx (int, default: -1 ) –

  Internal use: index of the enzyme species.

---

1D Hill Functions

---

stochastix.kinetics.HillActivator

HillActivator(
    regulator: str,
    v: float | ndarray,
    K: float | ndarray,
    n: float | ndarray = 1.0,
    v0: float | ndarray = 0.0,
    transform_v: Callable = None,
    transform_K: Callable = None,
    transform_n: Callable = None,
    transform_v0: Callable = None,
    *,
    _regulator_idx: int = -1,
)

Hill kinetics for gene activation by a single regulator.

This class implements Hill kinetics for modeling gene activation, where the expression rate increases with regulator concentration following a sigmoidal response curve.

Attributes:

• regulator –

  The name of the regulator species that activates the reaction.

• regulator_idx –

  The index of the regulator species in the state vector.

• v –

  The limiting rate, in concentration/time.

• K –

  The half-saturation constant, in concentration units.

• n –

  The Hill coefficient. Must be positive.

• v0 –

  The leaky (basal) expression rate, in concentration/time.

• transform_v –

  A function to transform the v parameter.

• transform_K –

  A function to transform the K parameter.

• transform_n –

  A function to transform the n parameter.

• transform_v0 –

  A function to transform the v0 parameter.

• _requires_species –

  Tuple of species names required by this kinetics.

Methods:

• propensity_fn –

  Calculate the Hill activator propensity.

• ode_rate_fn –

  Calculate the Hill activator ODE rate.

Parameters:

• regulator (str) –

  The name of the regulator species.

• v (float | ndarray) –

  The limiting rate (concentration/time).

• K (float | ndarray) –

  The half-saturation constant (concentration).

• n (float | ndarray, default: 1.0 ) –

  The Hill coefficient (must be positive). Defaults to 1.0.

• v0 (float | ndarray, default: 0.0 ) –

  The leaky expression rate (concentration/time). Defaults to 0.0.

• transform_v (Callable, default: None ) –

  A transform for v.

• transform_K (Callable, default: None ) –

  A transform for K.

• transform_n (Callable, default: None ) –

  A transform for n.

• transform_v0 (Callable, default: None ) –

  A transform for v0.

• _regulator_idx (int, default: -1 ) –

  Internal use: index of the regulator species.

---

stochastix.kinetics.HillRepressor

HillRepressor(
    regulator: str,
    v: float | ndarray,
    K: float | ndarray,
    n: float | ndarray = 1.0,
    v0: float | ndarray = 0.0,
    transform_v: Callable = None,
    transform_K: Callable = None,
    transform_n: Callable = None,
    transform_v0: Callable = None,
    *,
    _regulator_idx: int = -1,
)

Hill kinetics for gene repression by a single regulator.

This class implements Hill kinetics for modeling gene repression, where the expression rate decreases with regulator concentration following an inverted sigmoidal response curve.

Attributes:

• regulator –

  The name of the regulator species that represses the reaction.

• regulator_idx –

  The index of the regulator species in the state vector.

• v –

  The limiting rate, in concentration/time.

• K –

  The half-saturation constant, in concentration units.

• n –

  The Hill coefficient. Must be positive.

• v0 –

  The leaky (basal) expression rate, in concentration/time.

• transform_v –

  A function to transform the v parameter.

• transform_K –

  A function to transform the K parameter.

• transform_n –

  A function to transform the n parameter.

• transform_v0 –

  A function to transform the v0 parameter.

• _requires_species –

  Tuple of species names required by this kinetics.

Methods:

• propensity_fn –

  Calculate the Hill repressor propensity.

• ode_rate_fn –

  Calculate the Hill repressor ODE rate.

Parameters:

• regulator (str) –

  The name of the regulator species.

• v (float | ndarray) –

  The limiting rate (concentration/time).

• K (float | ndarray) –

  The half-saturation constant (concentration).

• n (float | ndarray, default: 1.0 ) –

  The Hill coefficient (must be positive). Defaults to 1.0.

• v0 (float | ndarray, default: 0.0 ) –

  The leaky expression rate (concentration/time). Defaults to 0.0.

• transform_v (Callable, default: None ) –

  A transform for v.

• transform_K (Callable, default: None ) –

  A transform for K.

• transform_n (Callable, default: None ) –

  A transform for n.

• transform_v0 (Callable, default: None ) –

  A transform for v0.

• _regulator_idx (int, default: -1 ) –

  Internal use: index of the regulator species.

---

stochastix.kinetics.HillSingleRegulator

HillSingleRegulator(
    regulator: str,
    v: float | ndarray,
    K: float | ndarray,
    n: float | ndarray,
    v0: float | ndarray = 0.0,
    transform_v: Callable = None,
    transform_K: Callable = None,
    transform_n: Callable = None,
    transform_v0: Callable = None,
    *,
    _regulator_idx: int = -1,
)

Hill kinetics for a single regulator with flexible activation/repression.

This class provides a general form of Hill kinetics that can model both activation and repression using a single formulation. The sign of the Hill coefficient n determines the regulatory behavior.

Attributes:

• regulator –

  The name of the regulator species.

• regulator_idx –

  The index of the regulator species in the state vector.

• v –

  The limiting rate, in concentration/time.

• K –

  The half-saturation constant, in concentration units.

• n –

  The Hill coefficient. Positive for activation, negative for repression.

• v0 –

  The leaky (basal) expression rate, in concentration/time.

• transform_v –

  A transform for the v parameter.

• transform_K –

  A transform for the K parameter.

• transform_n –

  A transform for the n parameter.

• transform_v0 –

  A transform for the v0 parameter.

• _requires_species –

  Tuple of species names required by this kinetics.

Methods:

• propensity_fn –

  Calculate the Hill propensity.

• ode_rate_fn –

  Calculate the Hill ODE rate.

Parameters:

• regulator (str) –

  The name of the regulator species.

• v (float | ndarray) –

  The limiting rate (concentration/time).

• K (float | ndarray) –

  The half-saturation constant (concentration).

• n (float | ndarray) –

  The Hill coefficient (positive for activation, negative for repression).

• v0 (float | ndarray, default: 0.0 ) –

  The leaky expression rate (concentration/time). Defaults to 0.0.

• transform_v (Callable, default: None ) –

  A transform for v.

• transform_K (Callable, default: None ) –

  A transform for K.

• transform_n (Callable, default: None ) –

  A transform for n.

• transform_v0 (Callable, default: None ) –

  A transform for v0.

• _regulator_idx (int, default: -1 ) –

  Internal use: index of the regulator species.

---

2D Hill Functions

---

stochastix.kinetics.HillAA

HillAA(
    activator1: str,
    activator2: str,
    v: float | ndarray,
    K1: float | ndarray,
    K2: float | ndarray,
    n1: float | ndarray,
    n2: float | ndarray,
    logic: str,
    competitive_binding: bool = False,
    v0: float | ndarray = 0.0,
    transform_v: Callable = None,
    transform_K1: Callable = None,
    transform_K2: Callable = None,
    transform_n1: Callable = None,
    transform_n2: Callable = None,
    transform_v0: Callable = None,
    *,
    _activator1_idx: int = -1,
    _activator2_idx: int = -1,
)

Hill kinetics for gene regulation by two activators.

This class implements Hill kinetics for modeling gene expression regulated by two activator species, supporting different logical combinations (AND/OR) and binding modes (competitive/independent).

Attributes:

• activator1 –

  The name of the first activator species.

• activator2 –

  The name of the second activator species.

• activator1_idx –

  The index of the first activator in the state vector.

• activator2_idx –

  The index of the second activator in the state vector.

• logic –

  The logic for gene expression, either 'and' or 'or'.

• competitive_binding –

  Whether the activators bind competitively.

• v –

  The limiting rate, in concentration/time.

• v0 –

  The leaky (basal) expression rate, in concentration/time.

• K1 –

  The half-saturation constant for the first activator, in concentration.

• K2 –

  The half-saturation constant for the second activator, in concentration.

• n1 –

  The Hill coefficient for the first activator (must be positive).

• n2 –

  The Hill coefficient for the second activator (must be positive).

• transform_v –

  A function to transform the v parameter.

• transform_K1 –

  A function to transform the K1 parameter.

• transform_K2 –

  A function to transform the K2 parameter.

• transform_n1 –

  A function to transform the n1 parameter.

• transform_n2 –

  A function to transform the n2 parameter.

• transform_v0 –

  A function to transform the v0 parameter.

• _requires_species –

  Tuple of species names required by this kinetics.

Methods:

• propensity_fn –

  Calculate the Hill activator-activator propensity.

• ode_rate_fn –

  Calculates the deterministic ODE rate for two activators.

Parameters:

• activator1 (str) –

  The name of the first activator species.

• activator2 (str) –

  The name of the second activator species.

• v (float | ndarray) –

  The limiting rate, in concentration/time.

• K1 (float | ndarray) –

  The half-saturation constant for activator1, in concentration.

• K2 (float | ndarray) –

  The half-saturation constant for activator2, in concentration.

• n1 (float | ndarray) –

  The Hill coefficient for activator1 (must be positive).

• n2 (float | ndarray) –

  The Hill coefficient for activator2 (must be positive).

• logic (str) –

  The interaction logic, either 'and' or 'or'.

• competitive_binding (bool, default: False ) –

  Whether binding is competitive. Defaults to False.

• v0 (float | ndarray, default: 0.0 ) –

  The leaky (basal) rate, in concentration/time. Defaults to 0.0.

• transform_v (Callable, default: None ) –

  A transform for v.

• transform_K1 (Callable, default: None ) –

  A transform for K1.

• transform_K2 (Callable, default: None ) –

  A transform for K2.

• transform_n1 (Callable, default: None ) –

  A transform for n1.

• transform_n2 (Callable, default: None ) –

  A transform for n2.

• transform_v0 (Callable, default: None ) –

  A transform for v0.

• _activator1_idx (int, default: -1 ) –

  Internal use: index of the first activator.

• _activator2_idx (int, default: -1 ) –

  Internal use: index of the second activator.

Raises:

• ValueError –

  If logic is not 'and' or 'or', or if logic is 'and' and competitive_binding is True.

---

stochastix.kinetics.HillAR

HillAR(
    activator: str,
    repressor: str,
    v: float | ndarray,
    Ka: float | ndarray,
    Kr: float | ndarray,
    na: float | ndarray,
    nr: float | ndarray,
    logic: str,
    competitive_binding: bool = False,
    v0: float | ndarray = 0.0,
    transform_v: Callable = None,
    transform_Ka: Callable = None,
    transform_Kr: Callable = None,
    transform_na: Callable = None,
    transform_nr: Callable = None,
    transform_v0: Callable = None,
    *,
    _activator_idx: int = -1,
    _repressor_idx: int = -1,
)

Hill kinetics for gene regulation by one activator and one repressor.

This class implements Hill kinetics for modeling gene expression regulated by both an activator and a repressor species, supporting different logical combinations (AND/OR) and binding modes (competitive/independent).

Attributes:

• activator –

  The name of the activator species.

• repressor –

  The name of the repressor species.

• activator_idx –

  The index of the activator in the state vector.

• repressor_idx –

  The index of the repressor in the state vector.

• logic –

  The logic for gene expression. Use 'and' for (A AND NOT R) and 'or' for (A OR NOT R).

• competitive_binding –

  Whether the regulators bind competitively.

• v –

  The limiting rate, in concentration/time.

• v0 –

  The leaky (basal) expression rate, in concentration/time.

• Ka –

  The half-saturation constant for the activator, in concentration.

• Kr –

  The half-saturation constant for the repressor, in concentration.

• na –

  The Hill coefficient for the activator (must be positive).

• nr –

  The Hill coefficient for the repressor (must be positive).

• transform_v –

  A function to transform the v parameter.

• transform_Ka –

  A function to transform the Ka parameter.

• transform_Kr –

  A function to transform the Kr parameter.

• transform_na –

  A function to transform the na parameter.

• transform_nr –

  A function to transform the nr parameter.

• transform_v0 –

  A function to transform the v0 parameter.

• _requires_species –

  Tuple of species names required by this kinetics.

Methods:

• propensity_fn –

  Calculate the Hill activator-repressor propensity.

• ode_rate_fn –

  Calculates the deterministic ODE rate for one activator and one repressor.

Parameters:

• activator (str) –

  The name of the activator species.

• repressor (str) –

  The name of the repressor species.

• v (float | ndarray) –

  The limiting rate, in concentration/time.

• Ka (float | ndarray) –

  The half-saturation constant for the activator, in concentration.

• Kr (float | ndarray) –

  The half-saturation constant for the repressor, in concentration.

• na (float | ndarray) –

  The Hill coefficient for the activator (must be positive).

• nr (float | ndarray) –

  The Hill coefficient for the repressor (must be positive).

• logic (str) –

  The interaction logic, either 'and' or 'or'.

• competitive_binding (bool, default: False ) –

  Whether binding is competitive. Defaults to False.

• v0 (float | ndarray, default: 0.0 ) –

  The leaky (basal) rate, in concentration/time. Defaults to 0.0.

• transform_v (Callable, default: None ) –

  A transform for v.

• transform_Ka (Callable, default: None ) –

  A transform for Ka.

• transform_Kr (Callable, default: None ) –

  A transform for Kr.

• transform_na (Callable, default: None ) –

  A transform for na.

• transform_nr (Callable, default: None ) –

  A transform for nr.

• transform_v0 (Callable, default: None ) –

  A transform for v0.

• _activator_idx (int, default: -1 ) –

  Internal use: index of the activator.

• _repressor_idx (int, default: -1 ) –

  Internal use: index of the repressor.

Raises:

• ValueError –

  If logic is not 'and' or 'or'.

---

stochastix.kinetics.HillRR

HillRR(
    repressor1: str,
    repressor2: str,
    v: float | ndarray,
    K1: float | ndarray,
    K2: float | ndarray,
    n1: float | ndarray,
    n2: float | ndarray,
    logic: str,
    competitive_binding: bool = False,
    v0: float | ndarray = 0.0,
    transform_v: Callable = None,
    transform_K1: Callable = None,
    transform_K2: Callable = None,
    transform_n1: Callable = None,
    transform_n2: Callable = None,
    transform_v0: Callable = None,
    *,
    _repressor1_idx: int = -1,
    _repressor2_idx: int = -1,
)

Hill kinetics for gene regulation by two repressors.

This class implements Hill kinetics for modeling gene expression regulated by two repressor species, supporting different logical combinations (AND/OR) and binding modes (competitive/independent).

Attributes:

• repressor1 –

  The name of the first repressor species.

• repressor2 –

  The name of the second repressor species.

• repressor1_idx –

  The index of the first repressor in the state vector.

• repressor2_idx –

  The index of the second repressor in the state vector.

• logic –

  The logic for gene expression. Use 'and' for (NOT R1 AND NOT R2) and 'or' for (NOT R1 OR NOT R2).

• competitive_binding –

  Whether the repressors bind competitively.

• v –

  The limiting rate, in concentration/time.

• v0 –

  The leaky (basal) expression rate, in concentration/time.

• K1 –

  The half-saturation constant for the first repressor, in concentration.

• K2 –

  The half-saturation constant for the second repressor, in concentration.

• n1 –

  The Hill coefficient for the first repressor (must be positive).

• n2 –

  The Hill coefficient for the second repressor (must be positive).

• transform_v –

  A function to transform the v parameter.

• transform_K1 –

  A function to transform the K1 parameter.

• transform_K2 –

  A function to transform the K2 parameter.

• transform_n1 –

  A function to transform the n1 parameter.

• transform_n2 –

  A function to transform the n2 parameter.

• transform_v0 –

  A function to transform the v0 parameter.

• _requires_species –

  Tuple of species names required by this kinetics.

Methods:

• propensity_fn –

  Calculate the Hill repressor-repressor propensity.

• ode_rate_fn –

  Calculates the deterministic ODE rate for two repressors.

Parameters:

• repressor1 (str) –

  The name of the first repressor species.

• repressor2 (str) –

  The name of the second repressor species.

• v (float | ndarray) –

  The limiting rate, in concentration/time.

• K1 (float | ndarray) –

  The half-saturation constant for repressor1, in concentration.

• K2 (float | ndarray) –

  The half-saturation constant for repressor2, in concentration.

• n1 (float | ndarray) –

  The Hill coefficient for repressor1 (must be positive).

• n2 (float | ndarray) –

  The Hill coefficient for repressor2 (must be positive).

• logic (str) –

  The interaction logic, either 'and' or 'or'.

• competitive_binding (bool, default: False ) –

  Whether binding is competitive. Defaults to False.

• v0 (float | ndarray, default: 0.0 ) –

  The leaky (basal) rate, in concentration/time. Defaults to 0.0.

• transform_v (Callable, default: None ) –

  A transform for v.

• transform_K1 (Callable, default: None ) –

  A transform for K1.

• transform_K2 (Callable, default: None ) –

  A transform for K2.

• transform_n1 (Callable, default: None ) –

  A transform for n1.

• transform_n2 (Callable, default: None ) –

  A transform for n2.

• transform_v0 (Callable, default: None ) –

  A transform for v0.

• _repressor1_idx (int, default: -1 ) –

  Internal use: index of the first repressor.

• _repressor2_idx (int, default: -1 ) –

  Internal use: index of the second repressor.

Raises:

• ValueError –

  If logic is not 'and' or 'or', or if logic is 'and' and competitive_binding is True.

---

Neural Kinetic Laws

---

stochastix.kinetics.MLP

MLP(
    input_species: str | tuple[str, ...],
    hidden_sizes: tuple[int, ...],
    activation: Callable = relu,
    final_activation: Callable = softplus,
    weight_init: Callable | None = None,
    bias_init: Callable | None = None,
    *,
    key: ndarray,
)

Multi-Layer Perceptron kinetics for data-driven rate modeling.

This class allows for flexible, data-driven modeling of reaction rates where the functional form is unknown and can be learned from data. The MLP takes species concentrations/counts as input and outputs a reaction rate.

input_species="*" triggers deferred initialization.

Supports deferred initialization when input_species is "*". This creates the concrete MLP architecture upon initialization of the ReactionNetwork it is a part of. This allows the MLP to be created when the full list of species in the network is known.

Attributes:

• mlp –

  The Multi-Layer Perceptron model for rate computation.

• _input_species_idx –

  Tuple of species indices used as MLP inputs.

• _hidden_sizes –

  Tuple of integers specifying the number of neurons in each hidden layer.

• _activation –

  The activation function for the hidden layers.

• _final_activation –

  The activation function for the output layer. This should ensure the rate is always non-negative (e.g., jax.nn.softplus).

• _weight_init –

  The weight initialization function for the MLP.

• _bias_init –

  The bias initialization function for the MLP.

• _mlp_init_key –

  A jax.random.PRNGKey for the random initialization of MLP weights.

Methods:

• propensity_fn –

  Calculates the propensity using the MLP.

• ode_rate_fn –

  Calculates the ODE rate using the MLP.

Parameters:

• input_species (str | tuple[str, ...]) –

  Species names to use as MLP inputs. Can be a single string, a tuple of strings, or "*" to use all network species (triggers deferred initialization).

• hidden_sizes (tuple[int, ...]) –

  The number of neurons in each hidden layer.

• activation (Callable, default: relu ) –

  Activation function for hidden layers.

• final_activation (Callable, default: softplus ) –

  Activation for the output layer.

• weight_init (Callable | None, default: None ) –

  Weight initializer.

• bias_init (Callable | None, default: None ) –

  Bias initializer.

• key (ndarray) –

  JAX random key for weight initialization.

---

Abstract Base Class

---

stochastix.kinetics.AbstractKinetics

AbstractKinetics(_requires_species: tuple[str, ...])

Abstract base class for kinetic laws.

This class defines the interface for all kinetic law implementations used in chemical reaction networks. Concrete subclasses must implement both stochastic propensity and deterministic ODE rate calculations.

Attributes:

• _requires_species –

  Tuple of species names required by this kinetics.

Methods:

• propensity_fn –

  Computes the propensity for a reaction.

• ode_rate_fn –

  Computes the rate for ODE integration.

propensity_fn

propensity_fn(x, reactants, t=None, volume=1.0)

Computes the propensity for a reaction.

This method must be implemented by all concrete kinetics classes. It calculates the stochastic reaction propensity, typically denoted as a(x).

Parameters:

• x –

  The current state vector (species counts).

• reactants –

  The stoichiometry of the reactants for this reaction.

• t –

  The current time (optional).

• volume –

  The volume of the system (optional).

Returns:

• –

  The computed propensity for the reaction (in units of 1/time).

ode_rate_fn

ode_rate_fn(x, reactants, t=None, volume=1.0)

Computes the rate for ODE integration.

This method must be implemented by all concrete kinetics classes. It calculates the deterministic rate of the reaction for use in an ODE model.

Parameters:

• x –

  The current state vector (species counts).

• reactants –

  The stoichiometry of the reactants for this reaction.

• t –

  The current time (optional).

• volume –

  The volume of the system (optional).

Returns:

• –

  The computed deterministic rate (in units of molecules/time).

_bind_to_network

_bind_to_network(
    species_map: dict[str, int],
) -> AbstractKinetics

Binds the kinetics object to a network's species map.

This internal method is called when a ReactionNetwork is created. It allows the kinetics object to store any necessary information derived from the network structure, such as the indices of regulator species.

Note

This method should always return a deep copy of the kinetics object to avoid side effects between different network instances.

Parameters:

• species_map (dict[str, int]) –

  A dictionary mapping species names to their integer indices.

Returns:

• AbstractKinetics –

  A new, bound AbstractKinetics object.