biocrnpyler.core.reaction

Classes

Reaction(inputs, outputs, propensity_type)

Chemical reaction in a CRN with species and rate law.

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

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:

inputslist of Species or list of WeightedSpecies: Reactant species. Can be Species objects (stoichiometry=1) or WeightedSpecies objects (with custom stoichiometry). Duplicates are automatically combined.
outputslist 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_typePropensity: Propensity object defining the rate law (e.g., MassAction, Hill).

Attributes:

inputslist of WeightedSpecies: List of WeightedSpecies: Reactant species with stoichiometry.
outputslist of WeightedSpecies: List of WeightedSpecies: Product species with stoichiometry.
propensity_typePropensity: Propensity: The rate law for this reaction.
is_reversiblebool: bool: True if the reaction has reversible kinetics.
specieslist of Species: List of Species: All species involved in the reaction.

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 –> B becomes 2A –> 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 <--> B

Use the from_massaction class method:

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

__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:

itemSpecies: Species to check for.

Returns:

bool: True if species is in inputs, outputs, or propensity species.

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:

otherReaction: Another reaction to compare with.

Returns:

bool: True if reactions have identical inputs, outputs, and propensity.

Raises:

TypeError: If other is not a Reaction object.

Notes

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

A + B –> C equals B + A –> C
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:

inputslist of Species or list of WeightedSpecies: Reactant species.
outputslist of Species or list of WeightedSpecies: Product species.
k_forwardfloat: Forward reaction rate constant. Must be positive.
k_reversefloat, optional: Reverse reaction rate constant. If None, reaction is irreversible. If provided, must be positive.

Returns:

Reaction: New Reaction object with MassAction propensity.

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]: List of WeightedSpecies: Reactant species with stoichiometry.

property is_reversible: bool

bool: True if the reaction has reversible kinetics.

Determined by the propensity type’s is_reversible property.

property outputs: List[WeightedSpecies]: List of WeightedSpecies: Product species with stoichiometry.

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_ratesbool, default=True: If True, includes rate law formula below reaction equation.
show_materialbool, default=True: If True, shows species material types (e.g., ‘dna’, ‘protein’).
show_attributesbool, default=True: If True, shows species attributes.
show_parametersbool, 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:

str: Formatted reaction string. Format: ‘inputs –> outputs’ or ‘inputs <–> outputs’ (reversible) Optionally followed by rate law and parameters.

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 --> B
 Kf=k_forward * A
  k_forward=0.1        Kf = 0.1 * A

>>> print(rxn.pretty_print(show_rates=False))
A --> B

property propensity_type: Propensity: Propensity: The rate law for this reaction.

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:

speciesSpecies: Species to be replaced.
new_speciesSpecies: Species to replace with.

Returns:

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

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 --> C

property species: List[Species]

List of 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:

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

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]