biocrnpyler.core.propensities

Classes

`GeneralPropensity`(propensity_function, ...)	Propensity with user-defined formula string.
`Hill`(k, s1, K, n, d)	Base class for Hill-type propensities.
`HillNegative`(k, s1, K, n)	Negative Hill function propensity (repression).
`HillPositive`(k, s1, K, n)	Positive Hill function propensity (activation).
`MassAction`(k_forward[, k_reverse])	Mass action kinetics propensity.
`Propensity`()	Base class for reaction propensity functions in BioCRNpyler.
`ProportionalHillNegative`(k, s1, K, n, d)	Proportional negative Hill function propensity.
`ProportionalHillPositive`(k, s1, K, n, d)	Proportional positive Hill function propensity.

class biocrnpyler.core.propensities.GeneralPropensity(propensity_function: str, propensity_species: List[Species], propensity_parameters: List[ParameterEntry])[source]

Propensity with user-defined formula string.

A GeneralPropensity allows specification of arbitrary kinetic rate laws using a formula string. The formula can reference species and parameters that are validated and tracked.

Parameters:

propensity_functionstr: Valid mathematical formula as a string (e.g., ‘k*S1*S2’). Must contain all referenced species and parameters.
propensity_specieslist of Species: List of Species objects used in the formula. Each species must appear in the propensity_function string.
propensity_parameterslist of ParameterEntry: List of ParameterEntry objects used in the formula. Each parameter name must appear in the propensity_function string.

Attributes:

propensity_functionstr: The mathematical formula defining the rate law.
namestr: Set to ‘general’ for this propensity type.

Raises:

TypeError: If propensity_species or propensity_parameters contain invalid types.
ValueError: If species or parameters in lists do not appear in the formula.

See also

MassAction: Mass action kinetics propensity.
Hill: Hill-type propensities.

Notes

The propensity_function string must be a valid mathematical expression that can be parsed by libsbml.parseL3Formula(). It can include:

Arithmetic operators: +, -, *, /, ^
Mathematical functions: exp, log, sin, cos, etc.
Species names (as strings matching their representation)
Parameter names (matching ParameterEntry.parameter_name)

Examples

Create a custom Michaelis-Menten propensity:

>>> S = bcp.Species('S')
>>> E = bcp.Species('E')
>>> kcat = bcp.ParameterEntry('kcat', 0.1)
>>> Km = bcp.ParameterEntry('Km', 10.0)
>>> prop = bcp.GeneralPropensity(
...     propensity_function='kcat*E*S/(Km + S)',
...     propensity_species=[S, E],
...     propensity_parameters=[kcat, Km]
... )

Create a custom regulatory function:

>>> X = bcp.Species('X')
>>> Y = bcp.Species('Y')
>>> k1 = bcp.ParameterEntry('k1', 1.0)
>>> k2 = bcp.ParameterEntry('k2', 0.5)
>>> prop = bcp.GeneralPropensity(
...     propensity_function='k1*X + k2*Y^2',
...     propensity_species=[X, Y],
...     propensity_parameters=[k1, k2]
... )

__eq__(other)[source]

Test equality between propensities.

Parameters:

otherPropensity: Other propensity to compare with.

Returns:

bool: True if propensities have the same class and propensity_dict.

create_kinetic_law(model, sbml_reaction, **kwargs)[source]

Create SBML kinetic law using the propensity_function string.

Translates species and parameter names to SBML identifiers and creates the kinetic law from the formula string.

Parameters:

modellibsbml.Model: SBML model object.
sbml_reactionlibsbml.Reaction: SBML reaction to add kinetic law to.
**kwargs: Additional keyword arguments (unused for GeneralPropensity).

Returns:

libsbml.KineticLaw: Created SBML kinetic law object.

Raises:

ValueError: If the propensity_function cannot be parsed as valid SBML formula.

classmethod from_dict(propensity_dict)[source]

Create a propensity from a dictionary.

Parameters:

propensity_dictdict: Dictionary with ‘parameters’ and ‘species’ keys containing parameter and species values.

Returns:

Propensity: New instance of the propensity class.

static get_available_propensities() → Set[source]

Get all available propensity subclasses.

Returns:

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

Examples

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

property is_reversible

bool: Whether the propensity represents a reversible reaction.

Default is False. Subclasses override this for reversible kinetics.

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_typeobject: Object to check for Propensity validity.

Returns:

bool: True if propensity_type is an instance of Propensity or any of its subclasses, False otherwise.

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

Float : Forward rate constant.

Raises:

NotImplementedError: Must be implemented by subclasses that use rate constants.

property k_reverse

Float or None: Reverse rate constant for reversible reactions.

Raises:

NotImplementedError: Must be implemented by subclasses that use rate constants.

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

Generate human-readable string representation of propensity.

Parameters:

show_parametersbool, default=True: If True, includes parameter values in output.
**kwargs: Additional keyword arguments passed to formatting methods.

Returns:

str: Formatted string showing rate formula and optionally parameters.

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

Generate formatted string of all propensity parameters.

Parameters:

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

Returns:

str: Formatted string listing all parameters and their values.

pretty_print_rate(**kwargs)[source]

Return the propensity function formula string.

Returns:

str: The propensity_function formula.

property species: List: List of Species : All species used in the propensity function.

class biocrnpyler.core.propensities.Hill(k: float, s1: Species, K: float, n: float, d: Species)[source]

Base class for Hill-type propensities.

Hill propensities implement cooperative binding kinetics with sigmoidal response curves. This base class provides common functionality for positive and negative Hill functions.

Parameters:

kfloat or ParameterEntry: Maximum rate constant. Must be positive.
s1Species: Input species that drives the Hill function.
Kfloat or ParameterEntry: Half-saturation (dissociation) constant. Must be positive.
nfloat or ParameterEntry: Hill coefficient (cooperativity). Must be positive. Values > 1 indicate positive cooperativity, < 1 negative cooperativity.
dSpecies or None: Optional species for proportional Hill functions. If provided, rate is proportional to this species concentration.

Attributes:

kfloat: float: Maximum rate constant value.
Kfloat: float: Half-saturation (dissociation) constant value.
nfloat: float: Hill coefficient (cooperativity) value.
s1Species: Species: Input species driving the Hill function.
dSpecies or None: Species: Proportional species (None if not proportional).

See also

HillPositive: Positive Hill function.
HillNegative: Negative Hill function (repression).
ProportionalHillPositive: Proportional positive Hill.
ProportionalHillNegative: Proportional negative Hill.

Notes

This is an abstract base class. Use the specific subclasses:

HillPositive: Activation, \(k s_1^n / (K^n + s_1^n)\)
HillNegative: Repression, \(k / (1 + (s_1/K)^n)\)
ProportionalHillPositive: \(k d s_1^n / (K^n + s_1^n)\)
ProportionalHillNegative: \(k d / (1 + (s_1/K)^n)\)

Hill functions are not reversible - k_reverse is not supported.

property K: float: Half-saturation (dissociation) constant value.

__eq__(other)[source]

Test equality between propensities.

Parameters:

otherPropensity: Other propensity to compare with.

Returns:

bool: True if propensities have the same class and propensity_dict.

create_kinetic_law(model, sbml_reaction, stochastic, **kwargs)[source]

Create SBML kinetic law for Hill propensity.

This method is shared by all Hill subclasses.

Parameters:

modellibsbml.Model: SBML model object.
sbml_reactionlibsbml.Reaction: SBML reaction to add kinetic law to.
stochasticbool: If True, uses stochastic formulation (same as deterministic for Hill functions).
**kwargs: Additional arguments. ‘reverse_reaction’ is not supported.

Returns:

libsbml.KineticLaw: Created SBML kinetic law object.

Raises:

ValueError: If reverse_reaction=True (Hill propensities cannot be reversible) or if rate formula is invalid.

property d: Species: Proportional species (None if not proportional).

classmethod from_dict(propensity_dict)[source]

Create a propensity from a dictionary.

Parameters:

propensity_dictdict: Dictionary with ‘parameters’ and ‘species’ keys containing parameter and species values.

Returns:

Propensity: New instance of the propensity class.

static get_available_propensities() → Set[source]

Get all available propensity subclasses.

Returns:

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

Examples

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

property is_reversible

bool: Whether the propensity represents a reversible reaction.

Default is False. Subclasses override this for reversible kinetics.

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_typeobject: Object to check for Propensity validity.

Returns:

bool: True if propensity_type is an instance of Propensity or any of its subclasses, False otherwise.

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: float: Maximum rate constant value.

property k_forward

Float : Forward rate constant.

Raises:

NotImplementedError: Must be implemented by subclasses that use rate constants.

property k_reverse

Float or None: Reverse rate constant for reversible reactions.

Raises:

NotImplementedError: Must be implemented by subclasses that use rate constants.

property n: float: Hill coefficient (cooperativity) value.

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

Generate human-readable string representation of propensity.

Parameters:

show_parametersbool, default=True: If True, includes parameter values in output.
**kwargs: Additional keyword arguments passed to formatting methods.

Returns:

str: Formatted string showing rate formula and optionally parameters.

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

Generate formatted string of all propensity parameters.

Parameters:

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

Returns:

str: Formatted string listing all parameters and their values.

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

Generate human-readable rate formula string.

Raises:

NotImplementedError: Hill base class doesn’t have a rate formula. Use subclasses HillPositive, HillNegative, ProportionalHillPositive, or ProportionalHillNegative.

property s1: Species: Input species driving the Hill function.

property species: List: List of Species : All species used in the propensity function.

class biocrnpyler.core.propensities.HillNegative(k: float, s1: Species, K: float, n: float)[source]

Negative Hill function propensity (repression).

Implements a repressive Hill function. As s1 increases, the rate decreases from k toward zero.

Parameters:

kfloat or ParameterEntry: Maximum rate constant (when s1=0). Must be positive.
s1Species: Input species that represses the reaction.
Kfloat or ParameterEntry: Half-saturation constant (concentration at half-maximal repression). Must be positive.
nfloat or ParameterEntry: Hill coefficient (cooperativity). Must be positive. Values > 1 indicate ultrasensitive repression.

Attributes:

namestr: Set to ‘hillnegative’ for this propensity type.

See also

HillPositive: Activating Hill function.
ProportionalHillNegative: Proportional negative Hill.

Notes

The following mathematical formula is implemented:

\[p(s_1; k, K, n) = \frac{k}{1 + (s_1/K)^n}\]

leading to the following behavior:

When s1 = 0: rate = k
When s1 = K: rate = k/2
When s1 >> K: rate -> 0
Larger n gives sharper (more switch-like) repression

Examples

Create a Hill repression propensity:

>>> R = bcp.Species('R')  # Repressor
>>> prop = bcp.HillNegative(k=10.0, s1=R, K=50.0, n=2.0)

Model transcriptional repression:

>>> repressor = bcp.Species('repressor')
>>> kmax = bcp.ParameterEntry('kmax', 1.0)
>>> Ki = bcp.ParameterEntry('Ki', 100.0)
>>> prop = bcp.HillNegative(k=kmax, s1=repressor, K=Ki, n=2.0)

property K: float: Half-saturation (dissociation) constant value.

__eq__(other)[source]

Test equality between propensities.

Parameters:

otherPropensity: Other propensity to compare with.

Returns:

bool: True if propensities have the same class and propensity_dict.

create_kinetic_law(model, sbml_reaction, stochastic, **kwargs)[source]

Create SBML kinetic law for Hill propensity.

This method is shared by all Hill subclasses.

Parameters:

modellibsbml.Model: SBML model object.
sbml_reactionlibsbml.Reaction: SBML reaction to add kinetic law to.
stochasticbool: If True, uses stochastic formulation (same as deterministic for Hill functions).
**kwargs: Additional arguments. ‘reverse_reaction’ is not supported.

Returns:

libsbml.KineticLaw: Created SBML kinetic law object.

Raises:

ValueError: If reverse_reaction=True (Hill propensities cannot be reversible) or if rate formula is invalid.

property d: Species: Proportional species (None if not proportional).

classmethod from_dict(propensity_dict)[source]

Create a propensity from a dictionary.

Parameters:

propensity_dictdict: Dictionary with ‘parameters’ and ‘species’ keys containing parameter and species values.

Returns:

Propensity: New instance of the propensity class.

static get_available_propensities() → Set[source]

Get all available propensity subclasses.

Returns:

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

Examples

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

property is_reversible

bool: Whether the propensity represents a reversible reaction.

Default is False. Subclasses override this for reversible kinetics.

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_typeobject: Object to check for Propensity validity.

Returns:

bool: True if propensity_type is an instance of Propensity or any of its subclasses, False otherwise.

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: float: Maximum rate constant value.

property k_forward

Float : Forward rate constant.

Raises:

NotImplementedError: Must be implemented by subclasses that use rate constants.

property k_reverse

Float or None: Reverse rate constant for reversible reactions.

Raises:

NotImplementedError: Must be implemented by subclasses that use rate constants.

property n: float: Hill coefficient (cooperativity) value.

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

Generate human-readable string representation of propensity.

Parameters:

show_parametersbool, default=True: If True, includes parameter values in output.
**kwargs: Additional keyword arguments passed to formatting methods.

Returns:

str: Formatted string showing rate formula and optionally parameters.

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

Generate formatted string of all propensity parameters.

Parameters:

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

Returns:

str: Formatted string listing all parameters and their values.

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

Generate human-readable rate formula string.

Returns:

str: Formatted Hill negative formula.

property s1: Species: Input species driving the Hill function.

property species: List: List of Species : All species used in the propensity function.

class biocrnpyler.core.propensities.HillPositive(k: float, s1: Species, K: float, n: float)[source]

Positive Hill function propensity (activation).

Implements an activating Hill function with sigmoidal dose-response curve. As s1 increases, the rate approaches k.

Parameters:

kfloat or ParameterEntry: Maximum rate constant. Must be positive.
s1Species: Input species that activates the reaction.
Kfloat or ParameterEntry: Half-saturation constant (concentration at half-maximal rate). Must be positive.
nfloat or ParameterEntry: Hill coefficient (cooperativity). Must be positive. Values > 1 indicate ultrasensitivity.

Attributes:

namestr: Set to ‘hillpositive’ for this propensity type.

See also

HillNegative: Repressive Hill function.
ProportionalHillPositive: Proportional positive Hill.

Notes

The following formula is implemented:

\[p(s_1; k, K, n) = \frac{k s_1^n}{K^n + s_1^n},\]

leading to the following behaviors:

When s1 = 0: rate ≈ 0
When s1 = K: rate = k/2
When s1 >> K: rate -> k
Larger n gives sharper (more switch-like) response

Examples

Create a Hill activation propensity:

>>> X = bcp.Species('X')
>>> prop = bcp.HillPositive(k=10.0, s1=X, K=50.0, n=2.0)

Use with parameter objects:

>>> kmax = bcp.ParameterEntry('kmax', 10.0)
>>> Kd = bcp.ParameterEntry('Kd', 50.0)
>>> hill_n = bcp.ParameterEntry('n', 2.0)
>>> prop = bcp.HillPositive(k=kmax, s1=X, K=Kd, n=hill_n)

property K: float: Half-saturation (dissociation) constant value.

__eq__(other)[source]

Test equality between propensities.

Parameters:

otherPropensity: Other propensity to compare with.

Returns:

bool: True if propensities have the same class and propensity_dict.

create_kinetic_law(model, sbml_reaction, stochastic, **kwargs)[source]

Create SBML kinetic law for Hill propensity.

This method is shared by all Hill subclasses.

Parameters:

modellibsbml.Model: SBML model object.
sbml_reactionlibsbml.Reaction: SBML reaction to add kinetic law to.
stochasticbool: If True, uses stochastic formulation (same as deterministic for Hill functions).
**kwargs: Additional arguments. ‘reverse_reaction’ is not supported.

Returns:

libsbml.KineticLaw: Created SBML kinetic law object.

Raises:

ValueError: If reverse_reaction=True (Hill propensities cannot be reversible) or if rate formula is invalid.

property d: Species: Proportional species (None if not proportional).

classmethod from_dict(propensity_dict)[source]

Create a propensity from a dictionary.

Parameters:

propensity_dictdict: Dictionary with ‘parameters’ and ‘species’ keys containing parameter and species values.

Returns:

Propensity: New instance of the propensity class.

static get_available_propensities() → Set[source]

Get all available propensity subclasses.

Returns:

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

Examples

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

property is_reversible

bool: Whether the propensity represents a reversible reaction.

Default is False. Subclasses override this for reversible kinetics.

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_typeobject: Object to check for Propensity validity.

Returns:

bool: True if propensity_type is an instance of Propensity or any of its subclasses, False otherwise.

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: float: Maximum rate constant value.

property k_forward

Float : Forward rate constant.

Raises:

NotImplementedError: Must be implemented by subclasses that use rate constants.

property k_reverse

Float or None: Reverse rate constant for reversible reactions.

Raises:

NotImplementedError: Must be implemented by subclasses that use rate constants.

property n: float: Hill coefficient (cooperativity) value.

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

Generate human-readable string representation of propensity.

Parameters:

show_parametersbool, default=True: If True, includes parameter values in output.
**kwargs: Additional keyword arguments passed to formatting methods.

Returns:

str: Formatted string showing rate formula and optionally parameters.

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

Generate formatted string of all propensity parameters.

Parameters:

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

Returns:

str: Formatted string listing all parameters and their values.

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

Generate human-readable rate formula string.

Returns:

str: Formatted Hill positive formula.

property s1: Species: Input species driving the Hill function.

property species: List: List of Species : All species used in the propensity function.

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

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_forwardfloat or ParameterEntry: Forward reaction rate constant. Must be positive.
k_reversefloat, ParameterEntry, or None, optional: Reverse reaction rate constant. If None, reaction is irreversible. If provided, must be positive.

Attributes:

namestr: 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 –> C with rate constant k:

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

Stochastic (Gillespie) propensity: For reaction A + B –> C with rate constant k:

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

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

\[\text{factor} = S \cdot (S-1) \cdot ... \cdot (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)

__eq__(other)[source]

Test equality between propensities.

Parameters:

otherPropensity: Other propensity to compare with.

Returns:

bool: True if propensities have the same class and propensity_dict.

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:

modellibsbml.Model: SBML model object.
sbml_reactionlibsbml.Reaction: SBML reaction to add kinetic law to.
stochasticbool: If True, uses stochastic mass action formula accounting for combinatorics.
crn_reactionReaction: Mass action reaction to use for the kinetic law.
reverse_reactionbool, default=False: If True, creates kinetic law for reverse reaction.
**kwargs: Must include ‘crn_reaction’ (CRN Reaction object).

Returns:

libsbml.KineticLaw: Created SBML kinetic law object.

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_dictdict: Dictionary with ‘parameters’ and ‘species’ keys containing parameter and species values.

Returns:

Propensity: New instance of the propensity class.

static get_available_propensities() → Set[source]

Get all available propensity subclasses.

Returns:

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

Examples

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

property is_reversible: bool: True if k_reverse is not None, False otherwise.

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_typeobject: Object to check for Propensity validity.

Returns:

bool: True if propensity_type is an instance of Propensity or any of its subclasses, False otherwise.

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: float: Forward rate constant value.

property k_reverse: float: Reverse rate constant value, None if irreversible.

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

Generate human-readable string representation of propensity.

Parameters:

show_parametersbool, default=True: If True, includes parameter values in output.
**kwargs: Additional keyword arguments passed to formatting methods.

Returns:

str: Formatted string showing rate formula and optionally parameters.

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

Generate formatted string of all propensity parameters.

Parameters:

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

Returns:

str: Formatted string listing all parameters and their values.

pretty_print_rate(**kwargs)[source]

Generate human-readable rate formula string.

Parameters:

**kwargs: Must include ‘reaction’ (CRN Reaction object) and ‘stochastic’ (bool) keys.

Returns:

str: Formatted rate formula showing forward rate and optionally reverse rate.

property species: List: List of Species : All species used in the propensity function.

class biocrnpyler.core.propensities.Propensity[source]

Base class for reaction propensity functions in BioCRNpyler.

Propensities define the rate laws for chemical reactions in a CRN. Different propensity types implement different kinetic models such as mass action, Hill functions, and custom formulas. Propensities can be deterministic (ODE) or stochastic (Gillespie).

Attributes:

propensity_dictdict: Dictionary with ‘species’ and ‘parameters’ keys storing the species and parameters used in the propensity function.
namestr or None: Name identifier for the propensity type.

See also

MassAction: Mass action kinetics propensity.
GeneralPropensity: Custom formula propensity.
Hill: Base class for Hill-type propensities.

Notes

This is an abstract base class that should be subclassed to implement specific propensity types. Subclasses must implement:

create_kinetic_law: Generate SBML kinetic law
pretty_print_rate: Human-readable rate formula

The propensity_dict structure:

‘species’: {<name>: Species object, …}
‘parameters’: {<name>: Parameter or number, …}

__eq__(other)[source]

Test equality between propensities.

Parameters:

otherPropensity: Other propensity to compare with.

Returns:

bool: True if propensities have the same class and propensity_dict.

create_kinetic_law(reaction, reverse_reaction, stochastic, **kwargs)[source]

Create SBML kinetic law for a reaction.

Parameters:

reactionlibsbml.Reaction: SBML reaction object to add kinetic law to.
reverse_reactionbool: If True, creates kinetic law for reverse direction.
stochasticbool: If True, uses stochastic propensity formulation.
**kwargs: Additional arguments (e.g., crn_reaction, model).

Returns:

libsbml.KineticLaw: Created SBML kinetic law object.

Raises:

NotImplementedError: Must be implemented by subclasses.

classmethod from_dict(propensity_dict)[source]

Create a propensity from a dictionary.

Parameters:

propensity_dictdict: Dictionary with ‘parameters’ and ‘species’ keys containing parameter and species values.

Returns:

Propensity: New instance of the propensity class.

static get_available_propensities() → Set[source]

Get all available propensity subclasses.

Returns:

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

Examples

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

property is_reversible

bool: Whether the propensity represents a reversible reaction.

Default is False. Subclasses override this for reversible kinetics.

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_typeobject: Object to check for Propensity validity.

Returns:

bool: True if propensity_type is an instance of Propensity or any of its subclasses, False otherwise.

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

Float : Forward rate constant.

Raises:

NotImplementedError: Must be implemented by subclasses that use rate constants.

property k_reverse

Float or None: Reverse rate constant for reversible reactions.

Raises:

NotImplementedError: Must be implemented by subclasses that use rate constants.

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

Generate human-readable string representation of propensity.

Parameters:

show_parametersbool, default=True: If True, includes parameter values in output.
**kwargs: Additional keyword arguments passed to formatting methods.

Returns:

str: Formatted string showing rate formula and optionally parameters.

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

Generate formatted string of all propensity parameters.

Parameters:

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

Returns:

str: Formatted string listing all parameters and their values.

pretty_print_rate(**kwargs)[source]

Generate human-readable rate formula string.

Parameters:

**kwargs: Formatting keyword arguments (e.g., reaction, stochastic).

Returns:

str: Formatted rate formula string.

Raises:

NotImplementedError: Must be implemented by subclasses.

property species: List: List of Species : All species used in the propensity function.

class biocrnpyler.core.propensities.ProportionalHillNegative(k: float, s1: Species, K: float, n: float, d: Species)[source]

Proportional negative Hill function propensity.

Implements a repressive Hill function with rate proportional to a species concentration. Commonly used for regulated production where a repressor inhibits production from a template/enzyme.

Parameters:

kfloat or ParameterEntry: Maximum rate constant per unit of d (when s1=0). Must be positive.
s1Species: Input species that represses the reaction (e.g., repressor).
Kfloat or ParameterEntry: Half-saturation constant for repression by s1. Must be positive.
nfloat or ParameterEntry: Hill coefficient. Must be positive.
dSpecies: Proportional species (e.g., DNA template, enzyme). Rate scales linearly with this species concentration.

Attributes:

namestr: Set to ‘proportionalhillnegative’ for this propensity type.

See also

HillNegative: Non-proportional negative Hill.
ProportionalHillPositive: Proportional positive Hill.

Notes

The following mathematical formula: is used:

\[p(s_1, d; k, K, n) = \frac{k d}{1 + (s_1/K)^n}\]

This is commonly used for repressed transcription where

d = DNA template concentration
s1 = repressor concentration
Rate is proportional to template but repressed by s1

and resulting in the following behaviors:

When d = 0: rate = 0 (no template/enzyme)
When s1 = 0: rate = k*d (fully derepressed)
When s1 >> K: rate -> 0 (fully repressed)

Examples

Model repressed transcription:

>>> repressor = bcp.Species('repressor')
>>> DNA = bcp.Species('DNA')
>>> prop = bcp.ProportionalHillNegative(
...     k=0.1, s1=repressor, K=50.0, n=2.0, d=DNA)

Model enzyme with allosteric inhibitor:

>>> inhibitor = bcp.Species('inhibitor')
>>> enzyme = bcp.Species('enzyme')
>>> kcat = bcp.ParameterEntry('kcat', 10.0)
>>> Ki = bcp.ParameterEntry('Ki', 100.0)
>>> prop = bcp.ProportionalHillNegative(
...     k=kcat, s1=inhibitor, K=Ki, n=2.0, d=enzyme)

property K: float: Half-saturation (dissociation) constant value.

__eq__(other)[source]

Test equality between propensities.

Parameters:

otherPropensity: Other propensity to compare with.

Returns:

bool: True if propensities have the same class and propensity_dict.

create_kinetic_law(model, sbml_reaction, stochastic, **kwargs)[source]

Create SBML kinetic law for Hill propensity.

This method is shared by all Hill subclasses.

Parameters:

modellibsbml.Model: SBML model object.
sbml_reactionlibsbml.Reaction: SBML reaction to add kinetic law to.
stochasticbool: If True, uses stochastic formulation (same as deterministic for Hill functions).
**kwargs: Additional arguments. ‘reverse_reaction’ is not supported.

Returns:

libsbml.KineticLaw: Created SBML kinetic law object.

Raises:

ValueError: If reverse_reaction=True (Hill propensities cannot be reversible) or if rate formula is invalid.

property d: Species: Proportional species (None if not proportional).

classmethod from_dict(propensity_dict)[source]

Create a propensity from a dictionary.

Parameters:

propensity_dictdict: Dictionary with ‘parameters’ and ‘species’ keys containing parameter and species values.

Returns:

Propensity: New instance of the propensity class.

static get_available_propensities() → Set[source]

Get all available propensity subclasses.

Returns:

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

Examples

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

property is_reversible

bool: Whether the propensity represents a reversible reaction.

Default is False. Subclasses override this for reversible kinetics.

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_typeobject: Object to check for Propensity validity.

Returns:

bool: True if propensity_type is an instance of Propensity or any of its subclasses, False otherwise.

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: float: Maximum rate constant value.

property k_forward

Float : Forward rate constant.

Raises:

NotImplementedError: Must be implemented by subclasses that use rate constants.

property k_reverse

Float or None: Reverse rate constant for reversible reactions.

Raises:

NotImplementedError: Must be implemented by subclasses that use rate constants.

property n: float: Hill coefficient (cooperativity) value.

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

Generate human-readable string representation of propensity.

Parameters:

show_parametersbool, default=True: If True, includes parameter values in output.
**kwargs: Additional keyword arguments passed to formatting methods.

Returns:

str: Formatted string showing rate formula and optionally parameters.

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

Generate formatted string of all propensity parameters.

Parameters:

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

Returns:

str: Formatted string listing all parameters and their values.

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

Generate human-readable rate formula string.

Returns:

str: Formatted proportional Hill negative formula.

property s1: Species: Input species driving the Hill function.

property species: List: List of Species : All species used in the propensity function.

class biocrnpyler.core.propensities.ProportionalHillPositive(k: float, s1: Species, K: float, n: float, d: Species)[source]

Proportional positive Hill function propensity.

Implements a positive Hill function with rate proportional to a species concentration. Commonly used for regulated production where the rate depends on both an activator and a template/enzyme.

Parameters:

kfloat or ParameterEntry: Maximum rate constant per unit of d. Must be positive.
s1Species: Input species that activates the reaction (e.g., transcription factor).
Kfloat or ParameterEntry: Half-saturation constant for s1. Must be positive.
nfloat or ParameterEntry: Hill coefficient (cooperativity). Must be positive.
dSpecies: Proportional species (e.g., DNA template, enzyme). Rate scales linearly with this species concentration.

Attributes:

namestr: Set to ‘proportionalhillpositive’ for this propensity type.

See also

HillPositive: Non-proportional positive Hill.
ProportionalHillNegative: Proportional negative Hill.

Notes

The following mathematical formula: is used for the popensity:

\[p(s_1, d; k, K, n) = \frac{k d s_1^n}{K^n + s_1^n}\]

This is commonly used for transcription, where

d = DNA template concentration
s1 = transcription factor concentration
Rate is proportional to both template and TF activation

This results in the following behaviors:

When d = 0: rate = 0 (no template/enzyme)
When s1 = 0: rate ≈ 0 (no activation)
When s1 >> K: rate -> k*d (fully activated, proportional to d)

Examples

Model regulated transcription:

>>> TF = bcp.Species('TF')  # Transcription factor
>>> DNA = bcp.Species('DNA')  # DNA template
>>> prop = bcp.ProportionalHillPositive(
...     k=0.1, s1=TF, K=50.0, n=2.0, d=DNA)

Model enzyme with allosteric activator:

>>> activator = bcp.Species('activator')
>>> enzyme = bcp.Species('enzyme')
>>> kcat = bcp.ParameterEntry('kcat', 10.0)
>>> Ka = bcp.ParameterEntry('Ka', 100.0)
>>> prop = bcp.ProportionalHillPositive(
...     k=kcat, s1=activator, K=Ka, n=2.0, d=enzyme)

property K: float: Half-saturation (dissociation) constant value.

__eq__(other)[source]

Test equality between propensities.

Parameters:

otherPropensity: Other propensity to compare with.

Returns:

bool: True if propensities have the same class and propensity_dict.

create_kinetic_law(model, sbml_reaction, stochastic, **kwargs)[source]

Create SBML kinetic law for Hill propensity.

This method is shared by all Hill subclasses.

Parameters:

modellibsbml.Model: SBML model object.
sbml_reactionlibsbml.Reaction: SBML reaction to add kinetic law to.
stochasticbool: If True, uses stochastic formulation (same as deterministic for Hill functions).
**kwargs: Additional arguments. ‘reverse_reaction’ is not supported.

Returns:

libsbml.KineticLaw: Created SBML kinetic law object.

Raises:

ValueError: If reverse_reaction=True (Hill propensities cannot be reversible) or if rate formula is invalid.

property d: Species: Proportional species (None if not proportional).

classmethod from_dict(propensity_dict)[source]

Create a propensity from a dictionary.

Parameters:

propensity_dictdict: Dictionary with ‘parameters’ and ‘species’ keys containing parameter and species values.

Returns:

Propensity: New instance of the propensity class.

static get_available_propensities() → Set[source]

Get all available propensity subclasses.

Returns:

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

Examples

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

property is_reversible

bool: Whether the propensity represents a reversible reaction.

Default is False. Subclasses override this for reversible kinetics.

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_typeobject: Object to check for Propensity validity.

Returns:

bool: True if propensity_type is an instance of Propensity or any of its subclasses, False otherwise.

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: float: Maximum rate constant value.

property k_forward

Float : Forward rate constant.

Raises:

NotImplementedError: Must be implemented by subclasses that use rate constants.

property k_reverse

Float or None: Reverse rate constant for reversible reactions.

Raises:

NotImplementedError: Must be implemented by subclasses that use rate constants.

property n: float: Hill coefficient (cooperativity) value.

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

Generate human-readable string representation of propensity.

Parameters:

show_parametersbool, default=True: If True, includes parameter values in output.
**kwargs: Additional keyword arguments passed to formatting methods.

Returns:

str: Formatted string showing rate formula and optionally parameters.

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

Generate formatted string of all propensity parameters.

Parameters:

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

Returns:

str: Formatted string listing all parameters and their values.

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

Generate human-readable rate formula string.

Returns:

str: Formatted proportional Hill positive formula.

property s1: Species: Input species driving the Hill function.

property species: List: List of Species : All species used in the propensity function.