biocrnpyler.core.MassAction

class biocrnpyler.core.MassAction(k_forward: float | ParameterEntry, k_reverse: float | ParameterEntry = None)[source]

Bases: Propensity

Mass action kinetics propensity.

Implements mass action rate laws for chemical reactions. Supports both irreversible and reversible reactions. Propensities are computed differently for deterministic (ODE) and stochastic (Gillespie) simulations.

Parameters:

k_forward (float or ParameterEntry) – Forward reaction rate constant. Must be positive.
k_reverse (float, ParameterEntry, or None, optional) – Reverse reaction rate constant. If None, reaction is irreversible. If provided, must be positive.

Attributes:

name (str) – Set to ‘massaction’ for this propensity type.

See also

GeneralPropensity: Custom formula propensity.
Hill: Hill-type propensities.

Notes

Deterministic (ODE) propensity: For reaction A + B $\rightarrow$ C with rate constant $k$:

\[{\text{rate}} = k [\text{A}] [\text{B}] \]

where [A] and [B] are the concentrations of A and B.

Stochastic (Gillespie) propensity: For reaction A + B $\rightarrow$ C with rate constant $k$:

\[\begin{split} {\text{propensity}} &= k \cdot A \cdot (B-1) &\quad& \text{if $A = B$} \\ {\text{propensity}} &= k \cdot A \cdot B &\quad& \text{otherwise} \end{split}\]

where $A$ and $B$ represent molecular counts.

The stochastic formulation accounts for combinatorics of molecule selection. For stoichiometric coefficient $n > 1$:

\[{\text{factor}} = S \dots (S-1) \dots (S-n+1) \]

If k_reverse is provided, the reaction is reversible:

\[A + B \rightleftharpoons C \]

Two kinetic laws are created: one for forward, one for reverse.

Examples

Create an irreversible mass action propensity:

>>> prop = bcp.MassAction(k_forward=100.0)

Create a reversible mass action propensity:

>>> prop = bcp.MassAction(k_forward=100.0, k_reverse=0.01)
>>> prop.is_reversible
True

Use with ParameterEntry objects:

>>> kb = bcp.ParameterEntry('kb', 100.0, unit='1/(nM*s)')
>>> ku = bcp.ParameterEntry('ku', 0.01, unit='1/s')
>>> prop = bcp.MassAction(k_forward=kb, k_reverse=ku)

Methods

`create_kinetic_law`	Create SBML kinetic law for mass action reaction.
`from_dict`	Create a propensity from a dictionary.
`get_available_propensities`	Get all available propensity subclasses.
`is_valid_propensity`	Check if an object is a valid Propensity subclass instance.
`pretty_print`	Generate human-readable string representation of propensity.
`pretty_print_parameters`	Generate formatted string of all propensity parameters.
`pretty_print_rate`	Generate human-readable rate formula string.

__eq__(other)[source]

Test equality between propensities.

Parameters:: other (Propensity) – Other propensity to compare with.
Returns:: True if propensities have the same class and propensity_dict.
Return type:: bool

create_kinetic_law(model, sbml_reaction, stochastic, crn_reaction=None, reverse_reaction=False, **kwargs)[source]

Create SBML kinetic law for mass action reaction.

Generates SBML kinetic law with proper mass action formula for either forward or reverse direction.

Parameters:

model (libsbml.Model) – SBML model object.
sbml_reaction (libsbml.Reaction) – SBML reaction to add kinetic law to.
stochastic (bool) – If True, uses stochastic mass action formula accounting for combinatorics.
crn_reaction (Reaction) – Mass action reaction to use for the kinetic law.
reverse_reaction (bool, default False) – If True, creates kinetic law for reverse reaction.
**kwargs – Must include ‘crn_reaction’ (CRN Reaction object).

Returns:

Created SBML kinetic law object.

Return type:

libsbml.KineticLaw

Raises:

ValueError – If crn_reaction not provided or if rate formula is invalid.

classmethod from_dict(propensity_dict)[source]

Create a propensity from a dictionary.

Parameters:: propensity_dict (dict) – Dictionary with ‘parameters’ and ‘species’ keys containing parameter and species values.
Returns:: New instance of the propensity class.
Return type:: Propensity

static get_available_propensities() → Set[source]

Get all available propensity subclasses.

Returns:: Set of all Propensity subclass types available in BioCRNpyler.
Return type:: set

Examples

>>> propensities = bcp.Propensity.get_available_propensities()
>>> bcp.MassAction in propensities
True

property is_reversible

True if k_reverse is not None, False otherwise.

Type:: bool

static is_valid_propensity(propensity_type) → bool[source]

Check if an object is a valid Propensity subclass instance.

Recursively checks all subclasses of Propensity to determine if the given object is a valid propensity type.

Parameters:: propensity_type (object) – Object to check for Propensity validity.
Returns:: True if propensity_type is an instance of Propensity or any of its subclasses, False otherwise.
Return type:: bool

Examples

>>> prop = bcp.MassAction(k_forward=100.0)
>>> bcp.Propensity.is_valid_propensity(prop)
True
>>> bcp.Propensity.is_valid_propensity("not a propensity")
False

property k_forward

Forward rate constant value.

Type:: float

property k_reverse

Reverse rate constant value, None if irreversible.

Type:: float

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

Generate human-readable string representation of propensity.

Parameters:

show_parameters (bool, default True) – If True, includes parameter values in output.
**kwargs – Additional keyword arguments passed to formatting methods.

Returns:

Formatted string showing rate formula and optionally parameters.

Return type:

str

pretty_print_parameters(show_keys=True, **kwargs)[source]

Generate formatted string of all propensity parameters.

Parameters:

show_keys (bool, default True) – If True, shows search and found keys for ModelParameter objects (useful for debugging parameter lookup).
**kwargs – Additional formatting keyword arguments.

Returns:

Formatted string listing all parameters and their values.

Return type:

str

pretty_print_rate(**kwargs)[source]

Generate human-readable rate formula string.

Parameters:: **kwargs – Must include ‘reaction’ (CRN Reaction object) and ‘stochastic’ (bool) keys.
Returns:: Formatted rate formula showing forward rate and optionally reverse rate.
Return type:: str

property species: List

All species used in the propensity function.

Type:: List of Species