Skip to content

reactions

RL4CRN.iocrns.reactions

Reaction primitives for IOCRNs.

This module defines the core reaction objects used throughout the package:

  • Reaction is the abstract base class that stores reaction structure (reactants/products), parameter slots (possibly unknown), optional input-channel associations for parameters, and context hooks used when embedding reactions in an IOCRN or registering them in a reaction library.

  • MassAction implements standard mass-action kinetics with an optional scalar input modulation of the rate constant.

  • HillProduction implements regulated production from the empty complex using Hill-type activation/repression.

Reactions are designed to be:

  • library-friendly: each reaction can be registered and retrieved by ID, while equality is typically based on a structure-only signature.
  • CRN-friendly: once a reaction is placed in an IOCRN, it can precompute index mappings (species/input labels → integer indices) for fast simulation.

Conventions:

  • Stoichiometry is represented implicitly by repeated labels in reactant_labels / product_labels (e.g. ['A','A'] means 2A).
  • Parameter vectors are aligned with input_channels and params_controllability; unknown parameters are represented by None.

Reaction

__init__(reactant_labels, product_labels, input_channels=[None], params=[None], params_controllability=[False], ID=None, signature=None)

Base class for reactions used in IOCRNs.

A Reaction defines:

  • a structure (reactants/products, optional "inputs" that modulate parameters),
  • a parameter vector (with optional unknown entries),
  • bookkeeping fields used when the reaction is placed inside a CRN (species/input indices) and inside a library (reaction ID).

The class is intended to be subclassed by specific kinetic laws (e.g. MassAction, HillProduction). Subclasses must implement propensity and to_reaction_format.

Parameters are stored in parallel lists:

  • params[j]: numerical value (float-like) or None if unknown.
  • params_controllability[j]: whether the parameter is controllable.
  • input_channels[j]: name of the input signal multiplying/modulating that parameter, or None if the parameter is not input-dependent.

These lists must have identical length.

Notes
  • The constructor sorts reactants/products and de-duplicates + sorts input_labels (excluding None) for deterministic behavior.
  • Equality (==) is defined via the reaction signature only. A signature is meant to identify the topology/structure of a reaction, ignoring parameter values.
PARAMETER DESCRIPTION
reactant_labels

Labels of reactant species (can be empty for ∅).
product_labels

Labels of product species (can be empty for ∅).
input_channels

Input channel per parameter slot. Can contain None.

DEFAULT: [None]

params

Parameter values per slot. None entries denote unknown parameters.

DEFAULT: [None]

params_controllability

Boolean flag per slot indicating controllability.

DEFAULT: [False]

ID

Optional integer identifier used when the reaction is registered in a RL4CRN.iocrns.reaction_library.ReactionLibrary.

DEFAULT: None

signature

Optional string uniquely identifying the structure of the reaction.

DEFAULT: None

ATTRIBUTE DESCRIPTION
reactant_labels

Sorted list of reactant labels.
product_labels

Sorted list of product labels.
input_channels

Input channel list, aligned with params.
params

Parameter list (may contain None values).
params_controllability

Controllability list, aligned with params.
num_parameters

Number of parameters (length of params).
input_labels

Sorted list of unique non-None input channel labels.
ID

Reaction ID in a library context (or None).
signature

Structural signature (or None).
crn

Set by set_crn_context when placed in an IOCRN.

get_ID()

Return the reaction's library ID (or None if unset).

set_ID(ID)

Set the reaction's library ID.

get_num_controllable_parameters()

Return the number of controllable parameters.

get_num_unknown_params()

Return the number of unknown parameters (None entries).

propensity(x, u)

Compute the propensity/rate contribution of this reaction.

Subclasses must implement this.

PARAMETER DESCRIPTION
x

Full CRN state vector (species concentrations/counts).
u

Full input vector (input signal values).
RETURNS DESCRIPTION
float

Propensity of the reaction under the provided state and inputs.

__call__(x, u)

Alias for propensity.

set_crn_context(crn)

Attach the reaction to an IOCRN context.

Subclasses typically override this to precompute index arrays for fast propensity evaluation.

PARAMETER DESCRIPTION
crn

IOCRN instance providing label->index maps.

__eq__(other)

Check structural equivalence via signature.

Two reactions are considered equal if their signatures are equal.

set_library_context(reaction_library)

Resolve and set this reaction's ID from a reaction library.

Finds the first reaction in reaction_library with the same signature (via __eq__) and sets ID accordingly.

PARAMETER DESCRIPTION
reaction_library

A RL4CRN.iocrns.reaction_library.ReactionLibrary.
RAISES DESCRIPTION
ValueError

If no matching reaction is found.

to_reaction_format()

Serialize the reaction to the project's DSL/CRN text format.

Subclasses must implement this.

RETURNS DESCRIPTION
str

A line of text such as 'A:1 -- mak(k) -> B:1;'.

MassAction

Bases: Reaction

__init__(reactant_labels, product_labels, input_channels=[None], params=[None], params_controllability=[True])

Mass-action reaction with optional input modulation.

A mass-action reaction has the form:

\[\sum_i \nu_i X_i \;\longrightarrow\; \sum_i \nu'_i X_i\]

with propensity

\[a(x, u) = k \;\prod_{X_i \in \text{reactants}} x_i \; g(u),\]

where:

  • \(k\) is the (possibly unknown) rate constant,
  • \(x_i\) are the reactant concentrations/counts,
  • \(g(u)\) is an optional scalar input modulation. In the current implementation:
    • if the single input_channel is None then \(g(u)=1\),
    • otherwise \(g(u)=u_{c}\) for the corresponding input channel/index.

The parameter layout is fixed to a single scalar parameter:

  • ``params = [k]
PARAMETER DESCRIPTION
reactant_labels

Reactant species labels. Empty means a 0th-order reaction (∅ → ...).
product_labels

Product species labels. Empty means degradation (... → ∅).
input_channels

A single-element list [channel] or [None].

DEFAULT: [None]

params

A single-element list [k] where k may be None.

DEFAULT: [None]

params_controllability

A single-element list indicating controllability of k.

DEFAULT: [True]

ATTRIBUTE DESCRIPTION
rate_constant

The mass-action rate constant k (float or None).
signature

Structural signature (depends only on reactants/products).
num_continuous_parameters

Always 1.
num_discrete_parameters

Always 0.
num_unknown_params

Number of unknown parameters (0 or 1).

set_parameters(params)

Set the rate constant.

PARAMETER DESCRIPTION
params

Single-element list [k].
RAISES DESCRIPTION
AssertionError

If params does not have length 1.

get_involved_species()

Return sorted unique species involved in the reaction (reactants ∪ products).

get_involved_inputs()

Return input channel labels used by the reaction (excluding None).

get_stoichiometry_dict()

Return stoichiometry coefficients as a dictionary.

Reactants contribute -1 per occurrence, products +1 per occurrence.

RETURNS DESCRIPTION

dict[str, int]: Mapping species label -> net stoichiometric coefficient.

set_crn_context(crn)

Precompute indices for fast propensity evaluation.

PARAMETER DESCRIPTION
crn

IOCRN instance providing label->index maps.

propensity(x, u)

Compute the mass-action propensity.

PARAMETER DESCRIPTION
x

Full species state vector of the parent IOCRN.
u

Full input vector of the parent IOCRN.
RETURNS DESCRIPTION
float

Reaction propensity.
Notes

This implementation multiplies all reactant entries via np.prod. For repeated reactants, the state is indexed with repeated indices, so the product includes appropriate powers.

__str__()

Human-readable string representation.

to_reaction_format()

Serialize to the CRN DSL.

RETURNS DESCRIPTION
str

DSL line, e.g. 'A:1 -- mak(k*u1) -> B:1;'.
Notes

The DSL formatting here distinguishes the "zero-order input generation" special-case when there are no reactants but an input channel exists.

get_ID()

Return the reaction's library ID (or None if unset).

set_ID(ID)

Set the reaction's library ID.

get_num_controllable_parameters()

Return the number of controllable parameters.

get_num_unknown_params()

Return the number of unknown parameters (None entries).

__call__(x, u)

Alias for propensity.

__eq__(other)

Check structural equivalence via signature.

Two reactions are considered equal if their signatures are equal.

set_library_context(reaction_library)

Resolve and set this reaction's ID from a reaction library.

Finds the first reaction in reaction_library with the same signature (via __eq__) and sets ID accordingly.

PARAMETER DESCRIPTION
reaction_library

A RL4CRN.iocrns.reaction_library.ReactionLibrary.
RAISES DESCRIPTION
ValueError

If no matching reaction is found.

HillProduction

Bases: Reaction

__init__(product_labels, activator_labels, repressor_labels, input_channels=[None], params=[None], params_controllability=[True])

Hill-regulated production reaction (Hill coefficients fixed to 1).

This reaction represents regulated production from the empty complex:

\[\emptyset \rightarrow \text{products}\]

with a propensity of the form:

\[ a(x) = b + V_{\max} \;\Bigg(\prod_{i \in A} \frac{x_i}{K_{a,i} + x_i}\Bigg) \Bigg(\prod_{j \in R} \frac{K_{r,j}}{K_{r,j} + x_j}\Bigg),\]

where: - \(b\) is the basal production rate, - \(V_{\max}\) is the maximal regulated production rate, - \(A\) is the set of activators, \(R\) the set of repressors, - Hill coefficients are fixed to 1 in this implementation.

Parameter layout (after sorting activator/repressor labels): params = [b, Vmax, Ka_1, ..., Ka_|A|, Kr_1, ..., Kr_|R|]

Note

Each parameter slot may be associated with an input_channel label. In the current implementation, the input vector u is collected but not applied inside propensity. This is a placeholder for future extensions where parameters may be modulated by inputs.

PARAMETER DESCRIPTION
product_labels

Product species labels (non-empty).
activator_labels

Activator species labels (may be empty).
repressor_labels

Repressor species labels (may be empty).
input_channels

Input channel list aligned with params (may contain None).

DEFAULT: [None]

params

Parameter list aligned with input_channels (may contain None).

DEFAULT: [None]

params_controllability

Controllability flags aligned with params.

DEFAULT: [True]

ATTRIBUTE DESCRIPTION
basal_rate

Basal rate b.
maximal_rate

Maximal rate Vmax.
activator_dissociation_constants

List of Ka values, aligned with sorted activators.
repressor_dissociation_constants

List of Kr values, aligned with sorted repressors.
signature

Structural signature independent of parameter values.
num_continuous_parameters

2 + |A| + |R|.
num_discrete_parameters

0 (Hill coefficients fixed to 1 here).
num_unknown_params

Number of unknown parameters (None entries).

set_parameters(params)

Set the full parameter vector.

Layout

[b, Vmax, Ka_1, ..., Ka_|A|, Kr_1, ..., Kr_|R|]

PARAMETER DESCRIPTION
params

Parameter vector matching the layout above.
RAISES DESCRIPTION
AssertionError

If the provided vector has the wrong length.

get_involved_species()

Return sorted unique species involved (products ∪ activators ∪ repressors).

get_involved_inputs()

Returns a list of all inputs involved in the reaction. Returns: - input_labels: list of strings representing the labels of the involved inputs.

get_stoichiometry_dict()

Return stoichiometry coefficients as a dictionary (products only).

RETURNS DESCRIPTION

dict[str, int]: Mapping product label -> stoichiometric coefficient.

set_crn_context(crn)

Precompute indices for fast propensity evaluation.

PARAMETER DESCRIPTION
crn

IOCRN instance providing label->index maps.

propensity(x, u)

Compute Hill-regulated production propensity.

PARAMETER DESCRIPTION
x

Full species state vector of the parent IOCRN.
u

Full input vector of the parent IOCRN.
RETURNS DESCRIPTION
float

Reaction propensity.
Notes

Input modulations of Hill coefficients are fixed to 1. This method currently does not apply input modulation to parameters even if input_channels are set.

__str__()

Human-readable string representation.

to_reaction_format()

Serialize to the CRN DSL.

RETURNS DESCRIPTION
str

DSL line, e.g. 'emptyset -- hill(b=..., Vm=..., A(Ka,1), R(Kr,1)) -> X:1;'.
Notes

This method emits a hill(...) construct assumed to be understood by your SSA/DSL backend. If the backend expects a different argument order or syntax, adapt accordingly.

get_ID()

Return the reaction's library ID (or None if unset).

set_ID(ID)

Set the reaction's library ID.

get_num_controllable_parameters()

Return the number of controllable parameters.

get_num_unknown_params()

Return the number of unknown parameters (None entries).

__call__(x, u)

Alias for propensity.

__eq__(other)

Check structural equivalence via signature.

Two reactions are considered equal if their signatures are equal.

set_library_context(reaction_library)

Resolve and set this reaction's ID from a reaction library.

Finds the first reaction in reaction_library with the same signature (via __eq__) and sets ID accordingly.

PARAMETER DESCRIPTION
reaction_library

A RL4CRN.iocrns.reaction_library.ReactionLibrary.
RAISES DESCRIPTION
ValueError

If no matching reaction is found.

ActiveDegradation

Bases: Reaction

__init__(substrate_label, enzyme_label, input_channels=[None], params=[None], params_controllability=[True])

Active degradation reaction (Hill coefficients fixed to 1).

This reaction represents regulated degradation of a substrate species by an enzyme:

\[\text{substrate} \rightarrow \emptyset\]

with a propensity of the form:

\[ a(x) = a D\;\frac{x}{K_D + x},\]

where: - \(a\) is the maximal degradation rate per degradation enzyme, - \(D\) is the degradation enzyme concentration (picked from the species), - \(K\) is the Michaelis constant for degradation, - Hill coefficients are fixed to 1 in this implementation.

Parameter layout (after sorting activator/repressor labels): params = [a, K]

Note

Each parameter slot may be associated with an input_channel label. In the current implementation, the input vector u is collected but not applied inside propensity. This is a placeholder for future extensions where parameters may be modulated by inputs.

PARAMETER DESCRIPTION
substrate_label

Substrate species label (non-empty).
enzyme_label

Enzyme species label (non-empty).
input_channels

Input channel list aligned with params (may contain None).

DEFAULT: [None]

params

Parameter list aligned with input_channels (may contain None).

DEFAULT: [None]

params_controllability

Controllability flags aligned with params.

DEFAULT: [True]

ATTRIBUTE DESCRIPTION
maximal_rate

Maximal rate a.
michaelis_constant

Michaelis constant K.
signature

Structural signature independent of parameter values.
num_continuous_parameters

2.
num_discrete_parameters

0 (Hill coefficients fixed to 1 here).
num_unknown_params

Number of unknown parameters (None entries).

set_parameters(params)

Set the full parameter vector.

Layout

[a, K]

PARAMETER DESCRIPTION
params

Parameter vector matching the layout above.
RAISES DESCRIPTION
AssertionError

If the provided vector has the wrong length.

get_involved_species()

Return sorted unique species involved (substrate ∪ enzyme).

get_involved_inputs()

Returns a list of all inputs involved in the reaction. Returns: - input_labels: list of strings representing the labels of the involved inputs.

get_stoichiometry_dict()

Return stoichiometry coefficients as a dictionary (reactant only).

RETURNS DESCRIPTION

dict[str, int]: Mapping reactant label -> stoichiometric coefficient.

set_crn_context(crn)

Precompute indices for fast propensity evaluation.

PARAMETER DESCRIPTION
crn

IOCRN instance providing label->index maps.

propensity(x, u)

Compute Active Degradation propensity.

PARAMETER DESCRIPTION
x

Full species state vector of the parent IOCRN.
u

Full input vector of the parent IOCRN.
RETURNS DESCRIPTION
float

Reaction propensity.

__str__()

Human-readable string representation.

get_ID()

Return the reaction's library ID (or None if unset).

set_ID(ID)

Set the reaction's library ID.

get_num_controllable_parameters()

Return the number of controllable parameters.

get_num_unknown_params()

Return the number of unknown parameters (None entries).

__call__(x, u)

Alias for propensity.

__eq__(other)

Check structural equivalence via signature.

Two reactions are considered equal if their signatures are equal.

set_library_context(reaction_library)

Resolve and set this reaction's ID from a reaction library.

Finds the first reaction in reaction_library with the same signature (via __eq__) and sets ID accordingly.

PARAMETER DESCRIPTION
reaction_library

A RL4CRN.iocrns.reaction_library.ReactionLibrary.
RAISES DESCRIPTION
ValueError

If no matching reaction is found.

to_reaction_format()

Serialize the reaction to the project's DSL/CRN text format.

Subclasses must implement this.

RETURNS DESCRIPTION
str

A line of text such as 'A:1 -- mak(k) -> B:1;'.