biocrnpyler.mechanisms.AntiDilutionConstitutiveCreation

class biocrnpyler.mechanisms.AntiDilutionConstitutiveCreation(name='anti_dilution_constiuitive_creation', material_type='dilution', filter_dict=None, default_on=True, recursive_species_filtering=True)[source]

Bases: GlobalMechanism

Global mechanism for constitutive creation to counter dilution.

A ‘dilution’ mechanism that constitutively creates species at a constant rate to maintain their concentration despite dilution. This is useful for modeling cellular machinery (ribosomes, polymerases, etc.) that is maintained at approximately constant levels through homeostatic mechanisms.

The production reaction for each species is

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

where S is any species and the rate is determined by ‘kdil’ (matching the dilution rate to maintain steady state).

Parameters:

name (str, default 'anti_dilution_constiuitive_creation') – Name identifier for this mechanism instance.
material_type (str, default 'dilution') – Type classification of this mechanism (used as mechanism_type).
filter_dict (dict, optional) – Dictionary for filtering which species are constitutively created. If None, all species are affected based on default_on.
default_on (bool, default True) – If True, creation applies to all species not explicitly filtered out. If False, creation applies only to explicitly filtered species.
recursive_species_filtering (bool, default True) – If True, filters based on all subspecies within ComplexSpecies. If False, filters only the ComplexSpecies itself.

Attributes:

name (str) – Name of the mechanism instance.
mechanism_type (str) – Type classification (‘dilution’).
filter_dict (dict) – Dictionary for filtering species.
default_on (bool) – Default behavior for unfiltered species.
recursive_species_filtering (bool) – Whether to filter ComplexSpecies recursively.

See also

Dilution: Dilution mechanism this counteracts.
GlobalMechanism: Base class for global mechanisms.

Notes

This mechanism generates a single irreversible mass-action reaction for each species that passes the filter, with rate constant ‘kdil’. It is typically used in conjunction with the Dilution mechanism to maintain steady-state concentrations of cellular machinery.

Common applications include:

Maintaining ribosome and polymerase concentrations in models
Homeostatic regulation of protein levels
Buffered species in cell-free systems
Representing constitutive expression of essential genes

Required parameters for this mechanism:

‘kdil’ : Creation rate constant (typically equal to dilution rate)

When used with Dilution on the same species with the same ‘kdil’ value, the species concentration remains constant (steady state).

Examples

Maintain ribosome concentration despite dilution:

>>> ribosome = bcp.Protein('ribosome')
>>> dilution = bcp.Dilution(default_on=True)
>>> creation = bcp.AntiDilutionConstitutiveCreation(
...     filter_dict={'ribosome': True},
...     default_on=False
... )
>>> mixture = bcp.Mixture(
...     components=[ribosome],
...     mechanisms={'dilution': dilution, 'creation': creation},
...     parameters={'kdil': 0.01}
... )

Maintain all machinery species at constant levels:

>>> machinery_species = [
...     bcp.Protein('ribosome', attributes=['machinery']),
...     bcp.Protein('RNAP', attributes=['machinery'])
... ]
>>> creation = bcp.AntiDilutionConstitutiveCreation(
...     filter_dict={'machinery': True},
...     default_on=False
... )

Methods

`apply_filter`	Determine if the global mechanism should act on a species.
`get_parameter`	Retrieve a parameter value from the mixture for a given species.
`update_reactions`	Generate constitutive creation reaction for a single species.
`update_reactions_global`	Apply mechanism's `update_reactions` to filtered species in a list.
`update_species`	Generate new species for a global mechanism acting on one species.
`update_species_global`	Apply mechanism's update_species to filtered species in a list.

apply_filter(s: Species)[source]

Determine if the global mechanism should act on a species.

Checks the species’s material_type, attributes, and name against the filter dictionary to decide if the mechanism should be applied.

Parameters:: s (Species) – The species to check against the filter dictionary.
Returns:: True if the mechanism should act on this species, False otherwise.
Return type:: bool

Notes

The filtering logic follows this hierarchy:

Checks all attributes and material_type of the species (and subspecies if recursive_species_filtering is True)
If any match is found in filter_dict, uses that boolean value
If conflicts occur (different attributes give different results), issues a warning and uses default_on
If no match is found, uses default_on

get_parameter(species, param_name, mixture)[source]

Retrieve a parameter value from the mixture for a given species.

Parameters:

species (Species) – The species for which to retrieve the parameter. Used as the part_id for parameter lookup.
param_name (str) – Name of the parameter to retrieve.
mixture (Mixture) – The mixture containing the parameters.

Returns:

The parameter value retrieved from the mixture.

Return type:

Parameter or float

Raises:

ValueError – If no parameter matching the (mechanism, species, param_name) combination can be found.

update_reactions(s, mixture)[source]

Generate constitutive creation reaction for a single species.

Creates an irreversible mass-action reaction that produces the species at rate ‘kdil’ to counteract dilution.

Parameters:

s (Species) – The species being constitutively created.
mixture (Mixture) – The mixture containing the ‘kdil’ parameter.

Returns:

List containing a single reaction: \(\emptyset\) \(\rightarrow\) S with rate ‘kdil’.

Return type:

list of Reaction

update_reactions_global(species_list: List[Species], mixture, compartment=None)[source]

Apply mechanism’s update_reactions to filtered species in a list.

Iterates through all species in the list, applies the filter to determine which species the mechanism acts upon, and calls update_reactions for each applicable species.

Parameters:

species_list (list of Species) – List of all species to potentially act upon.
mixture (Mixture) – The mixture containing parameters and other context.
compartment (Compartment, optional) – If provided, assigns this compartment to species that have the default compartment before generating reactions.

Returns:

List of all new reactions generated by the mechanism.

Return type:

list of Reaction

update_species(s: Species, mixture)[source]

Generate new species for a global mechanism acting on one species.

This is a template method that should be overridden by subclasses to define the species generated by the mechanism.

Parameters:

s (Species) – The species that the mechanism is acting upon.
mixture (Mixture) – The mixture containing parameters and other context.

Returns:

List of new species generated by the mechanism. Default implementation returns an empty list.

Return type:

list of Species

Notes

All GlobalMechanism subclasses should implement this method if they need to generate new species (e.g., enzyme-substrate complexes for degradation mechanisms).

update_species_global(species_list: List[Species], mixture, compartment=None)[source]

Apply mechanism’s update_species to filtered species in a list.

Iterates through all species in the list, applies the filter to determine which species the mechanism acts upon, and calls update_species for each applicable species.

Parameters:

species_list (list of Species) – List of all species to potentially act upon.
mixture (Mixture) – The mixture containing parameters and other context.
compartment (Compartment, optional) – If provided, assigns this compartment to any new species that have the default compartment.

Returns:

List of all new species generated by the mechanism.

Return type:

list of Species