biocrnpyler.core.Reaction

class biocrnpyler.core.Reaction(inputs: List[Species] | List[WeightedSpecies], outputs: List[Species] | List[WeightedSpecies], propensity_type: Propensity)[source]

Bases: object

Chemical reaction in a CRN with species and rate law.

A Reaction represents a chemical transformation between species with an associated propensity (rate law). Reactions can be irreversible or reversible, and support various kinetic models through different propensity types.

Parameters:

inputs (list of Species or list of WeightedSpecies) – Reactant species. Can be Species objects (stoichiometry=1) or WeightedSpecies objects (with custom stoichiometry). Duplicates are automatically combined.
outputs (list of Species or list of WeightedSpecies) – Product species. Can be Species objects (stoichiometry=1) or WeightedSpecies objects (with custom stoichiometry). Duplicates are automatically combined.
propensity_type (Propensity) – Propensity object defining the rate law (e.g., MassAction, Hill).

Attributes:

inputs (list of WeightedSpecies) – Reactant species with stoichiometry.
outputs (list of WeightedSpecies) – Product species with stoichiometry.
propensity_type (Propensity) – The rate law for this reaction.
is_reversible (bool) – True if the propensity supports reversible kinetics.
species (list of Species) – All species involved in the reaction (inputs, outputs, and propensity species).

See also

Species: Chemical species in a CRN.
WeightedSpecies: Species with stoichiometric coefficient.
Propensity: Base class for rate laws.
MassAction: Mass action kinetics propensity.

Notes

A reaction has the form:

\[\sum_i n_i I_i \rightarrow \sum_i m_i O_i, \]

where \(n_i\) is the stoichiometry of reactant \(I_i\) and \(m_i\) is the stoichiometry of product \(O_i\).

For reversible reactions:

\[\sum_i n_i I_i \rightleftharpoons \sum_i m_i O_i. \]

Stoichiometry is handled as follows:

Species lists automatically combine duplicates
A + A \(\rightarrow\) B becomes 2A \(\rightarrow\) B
Stoichiometry affects rate calculations in mass action kinetics

Different propensity types implement different rate laws:

MassAction: Standard mass action kinetics
Hill functions: Cooperative binding kinetics
GeneralPropensity: Custom formula

Examples

Create a simple irreversible reaction:

>>> A = bcp.Species('A')
>>> B = bcp.Species('B')
>>> prop = bcp.MassAction(k_forward=0.1)
>>> rxn = bcp.Reaction([A], [B], prop)

Create a reversible reaction:

>>> C = bcp.Species('C')
>>> prop = bcp.MassAction(k_forward=100.0, k_reverse=0.01)
>>> rxn = bcp.Reaction([A, B], [C], prop)
>>> rxn.is_reversible
True

Create a reaction with stoichiometry:

>>> rxn = bcp.Reaction([A, A], [B], prop)  # 2A $\rightleftharpoons$ B

Use the from_massaction class method:

>>> rxn = bcp.Reaction.from_massaction([A, B], [C], k_forward=100.0)

Methods

`from_massaction`	Create a Reaction with mass action kinetics.
`pretty_print`	Generate detailed, formatted string representation of reaction.
`replace_species`	Create new reaction with a species replaced.

__contains__(item: Species)[source]

Check if a species is involved in the reaction.

Checks whether a species appears in the reaction’s inputs, outputs, or propensity (e.g., Hill kinetics with regulatory species).

Parameters:: item (Species) – Species to check for.
Returns:: True if species is in inputs, outputs, or propensity species.
Return type:: bool
Raises:: NotImplementedError – If item is not a Species object.

Examples

>>> A = bcp.Species('A')
>>> B = bcp.Species('B')
>>> C = bcp.Species('C')
>>> rxn = bcp.Reaction.from_massaction([A], [B], k_forward=0.1)
>>> A in rxn
True
>>> C in rxn
False

__eq__(other)[source]

Test equality between reactions.

Two reactions are equal if they have the same inputs, outputs, and propensity (in any order).

Parameters:: other (Reaction) – Another reaction to compare with.
Returns:: True if reactions have identical inputs, outputs, and propensity.
Return type:: bool
Raises:: TypeError – If other is not a Reaction object.

Notes

Order of species in inputs/outputs doesn’t matter:

\[ {\text{A}} + {\text{B}} \rightarrow {\text{C}} \qquad\text{equals}\qquad {\text{B}} + {\text{A}} \rightarrow {\text{C}} \]

since species are compared using sets.

classmethod from_massaction(inputs: List[Species] | List[WeightedSpecies], outputs: List[Species] | List[WeightedSpecies], k_forward: float, k_reverse: float = None)[source]

Create a Reaction with mass action kinetics.

Convenience constructor for creating reactions with MassAction propensity.

Parameters:

inputs (list of Species or list of WeightedSpecies) – Reactant species.
outputs (list of Species or list of WeightedSpecies) – Product species.
k_forward (float) – Forward reaction rate constant. Must be positive.
k_reverse (float, optional) – Reverse reaction rate constant. If None, reaction is irreversible. If provided, must be positive.

Returns:

New Reaction object with MassAction propensity.

Return type:

Reaction

Examples

Create an irreversible reaction:

>>> A = bcp.Species('A')
>>> B = bcp.Species('B')
>>> rxn = bcp.Reaction.from_massaction([A], [B], k_forward=0.1)

Create a reversible reaction:

>>> rxn = bcp.Reaction.from_massaction(
...     [A, B], [C], k_forward=100.0, k_reverse=0.01)

property inputs: List[WeightedSpecies]

Reactant species with stoichiometry.

Type:: List of WeightedSpecies

property is_reversible: bool

True if the reaction has reversible kinetics.

Determined by the propensity type’s is_reversible property.

Type:: bool

property outputs: List[WeightedSpecies]

Product species with stoichiometry.

Type:: List of WeightedSpecies

pretty_print(show_rates=True, show_material=True, show_attributes=True, show_parameters=True, **kwargs)[source]

Generate detailed, formatted string representation of reaction.

Parameters:

show_rates (bool, default True) – If True, includes rate law formula below reaction equation.
show_material (bool, default True) – If True, shows species material types (e.g., ‘dna’, ‘protein’).
show_attributes (bool, default True) – If True, shows species attributes.
show_parameters (bool, default True) – If True, shows parameter values in rate law.
**kwargs – Additional keyword arguments passed to species and propensity pretty_print methods. Can include ‘stochastic’ (bool) for stochastic vs deterministic rate display.

Returns:

Formatted reaction string. Format: ‘inputs \(\rightarrow\) outputs’ or ‘inputs \(\rightleftharpoons\) outputs’ (reversible) Optionally followed by rate law and parameters.

Return type:

str

Examples

>>> A = bcp.Species('A')
>>> B = bcp.Species('B')
>>> rxn = bcp.Reaction.from_massaction([A], [B], k_forward=0.1)
>>> print(rxn.pretty_print())
A $\rightarrow$ B
 Kf=k_forward * A
  k_forward=0.1        Kf = 0.1 * A

>>> print(rxn.pretty_print(show_rates=False))
A $\rightarrow$ B

property propensity_type: Propensity

The rate law for this reaction.

Type:: Propensity

replace_species(species: Species, new_species: Species)[source]

Create new reaction with a species replaced.

Replaces all occurrences of a species throughout the reaction (inputs, outputs, and propensity species) with a new species.

Parameters:

species (Species) – Species to be replaced.
new_species (Species) – Species to replace with.

Returns:

New Reaction object with species replaced. The original reaction is not modified.

Return type:

Reaction

Raises:

ValueError – If either argument is not a Species object.

Examples

>>> A = bcp.Species('A')
>>> B = bcp.Species('B')
>>> C = bcp.Species('C')
>>> rxn = bcp.Reaction.from_massaction([A, B], [C], k_forward=0.1)
>>> D = bcp.Species('D')
>>> rxn2 = rxn.replace_species(A, D)  # D + B $\rightarrow$ C

property species: List[Species]

All species involved in the reaction.

Returns a flattened list of all species from inputs, outputs, and the propensity (e.g., Hill functions have regulatory species).

Returns:: All species in the reaction. May contain duplicates if a species appears in multiple roles.
Return type:: list of Species

Notes

This property collects species from three sources:

Input species (reactants)
Output species (products)
Propensity species (e.g., activators/repressors in Hill)

Examples

>>> A = bcp.Species('A')
>>> B = bcp.Species('B')
>>> rxn = bcp.Reaction.from_massaction([A], [B], k_forward=0.1)
>>> rxn.species
[A, B]

Type:: List of Species