biocrnpyler.mechanisms.global_mechanisms

Classes

`AntiDilutionConstitutiveCreation`([name, ...])	Global mechanism for constitutive species creation to counter dilution.
`Deg_Tagged_Degradation`(degradase[, deg_tag, ...])	Michaelis-Menten degradation of deg-tagged proteins by degradase.
`Degradation_mRNA_MM`(nuclease[, name, ...])	Michaelis-Menten mRNA degradation by endonucleases.
`Dilution`([name, mechanism_type, ...])	Global mechanism for species dilution or degradation.
`GlobalMechanism`(name[, mechanism_type, ...])	Base class for global mechanisms that act on all species in a mixture.

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

Global mechanism for constitutive species 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

∅ –> S

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

Parameters:

namestr, default=’anti_dilution_constiuitive_creation’: Name identifier for this mechanism instance.
material_typestr, default=’dilution’: Type classification of this mechanism (used as mechanism_type).
filter_dictdict, optional: Dictionary for filtering which species are constitutively created. If None, all species are affected based on default_on.
default_onbool, default=True: If True, creation applies to all species not explicitly filtered out. If False, creation applies only to explicitly filtered species.
recursive_species_filteringbool, default=True: If True, filters based on all subspecies within ComplexSpecies. If False, filters only the ComplexSpecies itself.

Attributes:

namestr: Name of the mechanism instance.
mechanism_typestr: Type classification (‘dilution’).
filter_dictdict: Dictionary for filtering species.
default_onbool: Default behavior for unfiltered species.
recursive_species_filteringbool: 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
... )

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:

sSpecies: The species to check against the filter dictionary.

Returns:

bool: True if the mechanism should act on this species, False otherwise.

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:

speciesSpecies: The species for which to retrieve the parameter. Used as the part_id for parameter lookup.
param_namestr: Name of the parameter to retrieve.
mixtureMixture: The mixture containing the parameters.

Returns:

Parameter or float: The parameter value retrieved from the mixture.

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:

sSpecies: The species being constitutively created.
mixtureMixture: The mixture containing the ‘kdil’ parameter.

Returns:

list of Reaction: List containing a single reaction: ∅ –> S with rate ‘kdil’.

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_listlist of Species: List of all species to potentially act upon.
mixtureMixture: The mixture containing parameters and other context.
compartmentCompartment, optional: If provided, assigns this compartment to species that have the default compartment before generating reactions.

Returns:

list of Reaction: List of all new reactions generated by the mechanism.

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:

sSpecies: The species that the mechanism is acting upon.
mixtureMixture: The mixture containing parameters and other context.

Returns:

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

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_listlist of Species: List of all species to potentially act upon.
mixtureMixture: The mixture containing parameters and other context.
compartmentCompartment, optional: If provided, assigns this compartment to any new species that have the default compartment.

Returns:

list of Species: List of all new species generated by the mechanism.

class biocrnpyler.mechanisms.global_mechanisms.Deg_Tagged_Degradation(degradase, deg_tag='degtagged', name='deg_tagged_degradation', mechanism_type='degradation', filter_dict=None, recursive_species_filtering=False, default_on=False, **kwargs)[source]

Michaelis-Menten degradation of deg-tagged proteins by degradase.

A ‘degradation’ mechanism that uses Michaelis-Menten kinetics to model the targeted enzymatic degradation of proteins tagged for degradation (e.g., via degron sequences). Only species with a specific degradation tag attribute and material_type ‘protein’ are degraded.

The degradation reaction scheme is

Protein_degtagged + degradase <–> Protein_degtagged:degradase –> degradase

where Protein_degtagged is any protein with the degradation tag.

Parameters:

degradaseSpecies: The degradase enzyme species that degrades tagged proteins.
deg_tagstr, default=’degtagged’: The attribute name used to identify proteins tagged for degradation.
namestr, default=’deg_tagged_degradation’: Name identifier for this mechanism instance.
mechanism_typestr, default=’degradation’: Type classification of this mechanism.
filter_dictdict, optional: Dictionary for filtering species. Default is {deg_tag: True} to degrade only species with the degradation tag.
recursive_species_filteringbool, default=False: If True, searches within ComplexSpecies recursively. If False, only acts on top-level species.
default_onbool, default=False: If True, mechanism acts on all species not filtered. If False, only acts on filtered species.
**kwargs: Additional keyword arguments passed to parent classes.

Attributes:

degradaseSpecies: The degradase enzyme species.
namestr: Name of the mechanism instance.
mechanism_typestr: Type classification (‘degradation’).
filter_dictdict: Dictionary for filtering species.
default_onbool: Default behavior for unfiltered species.
recursive_species_filteringbool: Whether to filter ComplexSpecies recursively.

See also

MichaelisMenten: Base enzyme kinetics mechanism.
Degradation_mRNA_MM: Global mRNA degradation mechanism.
GlobalMechanism: Base class for global mechanisms.

Notes

This mechanism implements targeted protein degradation similar to biological systems like the ubiquitin-proteasome system or degron-mediated degradation. Unlike global degradation mechanisms, it only affects proteins explicitly tagged with the specified attribute.

The mechanism is not recursive by default, meaning it only degrades proteins directly tagged with the deg_tag attribute, not proteins within ComplexSpecies unless the complex itself is tagged.

Common applications include:

Modeling ssrA-tagged protein degradation
Implementing synthetic degron systems
Targeted protein knockdown experiments
Conditional protein stability control

Required parameters for this mechanism:

‘kdeg’ : Catalytic rate constant for protein degradation
‘kb’ : Forward binding rate for degradase-protein association
‘ku’ : Reverse unbinding rate for degradase-protein dissociation

The deg_tag attribute must be added to protein species that should be degraded. By default, the mechanism looks for the ‘degtagged’ attribute but this can be customized via the deg_tag parameter.

Examples

Model ssrA-tagged protein degradation:

>>> clpxp = bcp.Protein('ClpXP')
>>> stable_protein = bcp.Protein('stable')
>>> tagged_protein = bcp.Protein('tagged', attributes=['degtagged'])
>>> degradation = bcp.Deg_Tagged_Degradation(
...     degradase=clpxp.species,
...     deg_tag='degtagged'
... )
>>> mixture = bcp.Mixture(
...     components=[clpxp, stable_protein, tagged_protein],
...     mechanisms={'degradation': degradation},
...     parameters={'kdeg': 0.5, 'kb': 1.0, 'ku': 0.1}
... )

Use custom degradation tags:

>>> proteasome = bcp.Protein('proteasome')
>>> ubiquitinated = bcp.Protein('target', attributes=['ubiquitinated'])
>>> degradation = bcp.Deg_Tagged_Degradation(
...     degradase=proteasome.species,
...     deg_tag='ubiquitinated'
... )

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:

sSpecies: The species to check against the filter dictionary.

Returns:

bool: True if the mechanism should act on this species, False otherwise.

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:

speciesSpecies: The species for which to retrieve the parameter. Used as the part_id for parameter lookup.
param_namestr: Name of the parameter to retrieve.
mixtureMixture: The mixture containing the parameters.

Returns:

Parameter or float: The parameter value retrieved from the mixture.

Raises:

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

update_reactions(s, mixture)[source]

Generate reactions for deg-tagged protein degradation reactions.

Creates two mass-action reactions implementing Michaelis-Menten kinetics for targeted protein degradation: reversible binding and irreversible catalysis.

Parameters:

sSpecies: The tagged protein species to be degraded.
mixtureMixture: The mixture containing parameters ‘kdeg’, ‘kb’, and ‘ku’.

Returns:

list of Reaction: List of two reactions for tagged protein degradation: [binding_reaction, catalysis_reaction].

Notes

Generates standard Michaelis-Menten reactions:

Protein + degradase <–> Protein:degradase (rates ‘kb’ and ‘ku’)
Protein:degradase –> degradase (rate ‘kdeg’)

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_listlist of Species: List of all species to potentially act upon.
mixtureMixture: The mixture containing parameters and other context.
compartmentCompartment, optional: If provided, assigns this compartment to species that have the default compartment before generating reactions.

Returns:

list of Reaction: List of all new reactions generated by the mechanism.

update_species(s, mixture)[source]

Generate species for deg-tagged protein degradation reactions.

Creates enzyme-substrate complexes needed for Michaelis-Menten degradation kinetics of tagged proteins.

Parameters:

sSpecies: The species to check for degradation tagging.
mixtureMixture: The mixture containing parameters.

Returns:

list of Species: List containing the degradase:protein complex species.

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_listlist of Species: List of all species to potentially act upon.
mixtureMixture: The mixture containing parameters and other context.
compartmentCompartment, optional: If provided, assigns this compartment to any new species that have the default compartment.

Returns:

list of Species: List of all new species generated by the mechanism.

class biocrnpyler.mechanisms.global_mechanisms.Degradation_mRNA_MM(nuclease, name='rna_degradation_mm', mechanism_type='rna_degradation', default_on=False, recursive_species_filtering=True, filter_dict=None, **kwargs)[source]

Michaelis-Menten mRNA degradation by endonucleases.

A ‘rna_degradation’ mechanism that uses Michaelis-Menten kinetics to model the enzymatic degradation of mRNA by endonucleases. All species with material_type ‘rna’ are degraded, including those within ComplexSpecies.

The degradation reaction scheme is

mRNA + Endo <–> mRNA:Endo –> Endo

where mRNA is any RNA species and Endo is the endonuclease.

Parameters:

nucleaseSpecies: The endonuclease species that degrades mRNA.
namestr, default=’rna_degradation_mm’: Name identifier for this mechanism instance.
mechanism_typestr, default=’rna_degradation’: Type classification of this mechanism.
default_onbool, default=False: If True, mechanism acts on all species not filtered. If False, only acts on filtered species.
recursive_species_filteringbool, default=True: If True, searches for RNA within ComplexSpecies recursively. If False, only acts on top-level species.
filter_dictdict, optional: Dictionary for filtering species. Default is {‘rna’: True, ‘notdegradable’: False} to degrade RNA but not species marked as not degradable.
**kwargs: Additional keyword arguments passed to parent classes.

Attributes:

nucleaseSpecies: The endonuclease species.
namestr: Name of the mechanism instance.
mechanism_typestr: Type classification (‘rna_degradation’).
filter_dictdict: Dictionary for filtering species.
default_onbool: Default behavior for unfiltered species.
recursive_species_filteringbool: Whether to filter ComplexSpecies recursively.

See also

MichaelisMenten: Base enzyme kinetics mechanism.
Deg_Tagged_Degradation: Targeted protein degradation.
GlobalMechanism: Base class for global mechanisms.

Notes

This mechanism handles three cases:

Pure RNA species: Degraded completely (RNA –> ∅)
RNA in ComplexSpecies: Complex is broken apart, RNA is degraded, non-RNA components are released
OrderedPolymerSpecies: Not affected by this mechanism

The mechanism generates Michaelis-Menten reactions with three rate constants per species. ComplexSpecies containing RNA are separated during degradation, including embedded ComplexSpecies. However, OrderedPolymerSpecies (like DNA or assembled proteins) are ignored.

Required parameters for this mechanism:

‘kdeg’ : Catalytic rate constant for RNA degradation
‘kb’ : Forward binding rate for nuclease-RNA association
‘ku’ : Reverse unbinding rate for nuclease-RNA dissociation

The default filter_dict applies degradation to all ‘rna’ species but excludes any species with the ‘notdegradable’ attribute, allowing fine-grained control over which RNA species are degraded.

Examples

Model global mRNA degradation in a cell-free system:

>>> rnase = bcp.Protein('RNase')
>>> mrna = bcp.RNA('mRNA')
>>> degradation = bcp.Degradation_mRNA_MM(nuclease=rnase.species)
>>> mixture = bcp.Mixture(
...     components=[rnase, mrna],
...     mechanisms={'rna_degradation': degradation},
...     parameters={'kdeg': 0.1, 'kb': 1.0, 'ku': 0.5}
... )

Protect specific RNAs from degradation:

>>> rnase = bcp.Protein('RNase')
>>> stable_rna = bcp.RNA('stable', attributes=['notdegradable'])
>>> unstable_rna = bcp.RNA('unstable')
>>> degradation = bcp.Degradation_mRNA_MM(nuclease=rnase.species)
>>> mixture = bcp.Mixture(
...     components=[rnase, stable_rna, unstable_rna],
...     mechanisms={'rna_degradation': degradation},
...     parameters={'kdeg': 0.1, 'kb': 1.0, 'ku': 0.5}
... )

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:

sSpecies: The species to check against the filter dictionary.

Returns:

bool: True if the mechanism should act on this species, False otherwise.

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:

speciesSpecies: The species for which to retrieve the parameter. Used as the part_id for parameter lookup.
param_namestr: Name of the parameter to retrieve.
mixtureMixture: The mixture containing the parameters.

Returns:

Parameter or float: The parameter value retrieved from the mixture.

Raises:

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

update_reactions(s, mixture)[source]

Generate Michaelis-Menten degradation reactions for mRNA.

Creates two mass-action reactions implementing Michaelis-Menten kinetics for RNA degradation: reversible binding and irreversible catalysis.

Parameters:

sSpecies: The species to check for RNA degradation.
mixtureMixture: The mixture containing parameters ‘kdeg’, ‘kb’, and ‘ku’.

Returns:

list of Reaction: List of reactions for RNA degradation. Empty list if species should not be degraded.

Notes

Generates standard Michaelis-Menten reactions:

RNA + nuclease <–> RNA:nuclease (rates ‘kb’ and ‘ku’)
RNA:nuclease –> nuclease (rate ‘kdeg’)

For ComplexSpecies containing RNA, non-RNA components are released in the catalytic step instead of being degraded.

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_listlist of Species: List of all species to potentially act upon.
mixtureMixture: The mixture containing parameters and other context.
compartmentCompartment, optional: If provided, assigns this compartment to species that have the default compartment before generating reactions.

Returns:

list of Reaction: List of all new reactions generated by the mechanism.

update_species(s, mixture)[source]

Generate species for mRNA degradation reactions.

Creates enzyme-substrate complexes needed for Michaelis-Menten degradation kinetics. Handles RNA in ComplexSpecies by identifying non-RNA components that will be released.

Parameters:

sSpecies: The species to check for RNA degradation.
mixtureMixture: The mixture containing parameters.

Returns:

list of Species: List of new species (enzyme-substrate complexes) generated for degradation reactions. Empty list if species should not be degraded.

Notes

Behavior depends on species type:

Pure RNA species: Creates nuclease:RNA complex
ComplexSpecies containing RNA: Creates nuclease:complex complex, identifies non-RNA products to be released
OrderedPolymerSpecies: Returns empty list (not degraded)

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_listlist of Species: List of all species to potentially act upon.
mixtureMixture: The mixture containing parameters and other context.
compartmentCompartment, optional: If provided, assigns this compartment to any new species that have the default compartment.

Returns:

list of Species: List of all new species generated by the mechanism.

class biocrnpyler.mechanisms.global_mechanisms.Dilution(name='global_degradation_via_dilution', mechanism_type='dilution', filter_dict=None, default_on=True, recursive_species_filtering=True)[source]

Global mechanism for species dilution or degradation.

A ‘dilution’ mechanism that removes species from the system at a rate proportional to their concentration. This models dilution due to cell growth, continuous flow in a bioreactor, or general degradation processes.

The dilution reaction for each species is

S –> ∅

where S is any species and the rate is determined by ‘kdil’.

Parameters:

namestr, default=’global_degradation_via_dilution’: Name identifier for this mechanism instance.
mechanism_typestr, default=’dilution’: Type classification of this mechanism.
filter_dictdict, optional: Dictionary for filtering which species undergo dilution. If None, all species are affected based on default_on.
default_onbool, default=True: If True, dilution applies to all species not explicitly filtered out. If False, dilution applies only to explicitly filtered species.
recursive_species_filteringbool, default=True: If True, filters based on all subspecies within ComplexSpecies. If False, filters only the ComplexSpecies itself.

Attributes:

namestr: Name of the mechanism instance.
mechanism_typestr: Type classification (‘dilution’).
filter_dictdict: Dictionary for filtering species.
default_onbool: Default behavior for unfiltered species.
recursive_species_filteringbool: Whether to filter ComplexSpecies recursively.

See also

AntiDilutionConstitutiveCreation: Counter-mechanism for constant concentration.
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’. By default, it applies to all species (default_on=True) unless specific species are excluded via the filter_dict.

Common applications include:

Modeling cell growth and dilution in batch cultures
Continuous flow bioreactor systems
Simplified degradation for all cellular components
Washout effects in chemostats

Required parameters for this mechanism:

‘kdil’ : Dilution rate constant (per species if needed)

The mechanism can be selectively applied using filter_dict. For example, to exclude specific species from dilution, set filter_dict={‘notdiluted’: False} and tag those species with the ‘notdiluted’ attribute.

Examples

Apply dilution to all species in a mixture:

>>> dilution_mech = bcp.Dilution(default_on=True)
>>> mixture = bcp.Mixture(
...     components=[bcp.Protein('A'), bcp.Protein('B')],
...     mechanisms={'dilution': dilution_mech},
...     parameters={'kdil': 0.01}
... )

Apply dilution only to proteins, excluding DNA:

>>> dilution_mech = bcp.Dilution(
...     filter_dict={'protein': True, 'dna': False},
...     default_on=False
... )
>>> mixture = bcp.Mixture(
...     components=[bcp.Protein('P'), bcp.DNA('gene')],
...     mechanisms={'dilution': dilution_mech},
...     parameters={'kdil': 0.01}
... )

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:

sSpecies: The species to check against the filter dictionary.

Returns:

bool: True if the mechanism should act on this species, False otherwise.

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:

speciesSpecies: The species for which to retrieve the parameter. Used as the part_id for parameter lookup.
param_namestr: Name of the parameter to retrieve.
mixtureMixture: The mixture containing the parameters.

Returns:

Parameter or float: The parameter value retrieved from the mixture.

Raises:

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

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

Generate dilution reaction for a single species.

Creates an irreversible mass-action reaction that removes the species from the system at rate ‘kdil’.

Parameters:

sSpecies: The species undergoing dilution.
mixtureMixture: The mixture containing the ‘kdil’ parameter.

Returns:

list of Reaction: List containing a single reaction: S –> ∅ with rate ‘kdil’.

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_listlist of Species: List of all species to potentially act upon.
mixtureMixture: The mixture containing parameters and other context.
compartmentCompartment, optional: If provided, assigns this compartment to species that have the default compartment before generating reactions.

Returns:

list of Reaction: List of all new reactions generated by the mechanism.

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:

sSpecies: The species that the mechanism is acting upon.
mixtureMixture: The mixture containing parameters and other context.

Returns:

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

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_listlist of Species: List of all species to potentially act upon.
mixtureMixture: The mixture containing parameters and other context.
compartmentCompartment, optional: If provided, assigns this compartment to any new species that have the default compartment.

Returns:

list of Species: List of all new species generated by the mechanism.

class biocrnpyler.mechanisms.global_mechanisms.GlobalMechanism(name: str, mechanism_type: str = '', filter_dict: Dict = None, default_on: bool = False, recursive_species_filtering: bool = False)[source]

Base class for global mechanisms that act on all species in a mixture.

Global mechanisms are applied by mixtures to all species after components have generated their species. Unlike regular mechanisms that act on specific component interactions, global mechanisms function universally on species based on their properties (material type, attributes, or name).

Global mechanisms use a filter dictionary to determine which species they act upon. For each species, the mechanism checks the species’s material type, attributes, and name against the filter dictionary. If a match returns True, the mechanism acts on that species; if False, it does not.

Parameters:

namestr: Name identifier for this mechanism instance.
mechanism_typestr, default=’’: Type classification of this mechanism.
filter_dictdict, optional: Dictionary mapping species properties (material_type, attributes, or name) to boolean values. True means the mechanism acts on species with that property, False means it does not. If None, an empty dictionary is used.
default_onbool, default=False: Determines behavior when a species is not found in filter_dict. If True, the mechanism acts on unfiltered species. If False, it does not. Also used as the default when filter conflicts occur.
recursive_species_filteringbool, default=False: Determines how ComplexSpecies are filtered. If True, filtering is based on all subspecies recursively. If False, filtering acts only on the ComplexSpecies itself.

Attributes:

namestr: Name of the mechanism instance.
mechanism_typestr: Type classification of this mechanism.
filter_dictdict: Dictionary for filtering species.
default_onbool: Default behavior for unfiltered species.
recursive_species_filteringbool: Whether to filter ComplexSpecies recursively.

See also

Dilution: Global mechanism for species dilution.
Degradation_mRNA_MM: Global mRNA degradation mechanism.
Mechanism: Base class for all mechanisms.

Notes

GlobalMechanisms should be used cautiously as the order in which they are called may affect the final CRN. The calling order may need to be carefully defined in Mixture subclasses to ensure expected behavior.

Filter dictionary usage:

Keys can be material_type, attribute names, or species names
Values are boolean (True = apply mechanism, False = do not apply)
When conflicts occur, a warning is issued and default_on is used
Attributes take precedence over material_type when both are present

All parameters required by the global mechanism must be present in the Mixture’s parameter dictionary. Global mechanisms are assumed to take a single species as input.

Examples

Create a custom global degradation mechanism:

>>> class CustomDegradation(bcp.GlobalMechanism):
...     def update_reactions(self, s, mixture):
...         kdeg = self.get_parameter(s, 'kdeg', mixture)
...         return [bcp.Reaction.from_massaction(
...             inputs=[s], outputs=[], k_forward=kdeg
...         )]

Use with a filter to degrade only proteins:

>>> mech = CustomDegradation(
...     name='protein_degradation',
...     mechanism_type='degradation',
...     filter_dict={'protein': True},
...     default_on=False
... )
>>> mixture = bcp.Mixture(
...     components=[bcp.Protein('A'), bcp.RNA('B')],
...     mechanisms={'degradation': mech},
...     parameters={'kdeg': 0.01}
... )
>>> mixture.compile_crn()
Species = protein_A, rna_B
Reactions = [
    protein[A] -->
]

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:

sSpecies: The species to check against the filter dictionary.

Returns:

bool: True if the mechanism should act on this species, False otherwise.

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:

speciesSpecies: The species for which to retrieve the parameter. Used as the part_id for parameter lookup.
param_namestr: Name of the parameter to retrieve.
mixtureMixture: The mixture containing the parameters.

Returns:

Parameter or float: The parameter value retrieved from the mixture.

Raises:

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

update_reactions(s, mixture)[source]

Generate reactions for a global mechanism acting on one species.

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

Parameters:

sSpecies: The species that the mechanism is acting upon.
mixtureMixture: The mixture containing parameters and other context.

Returns:

list of Reaction: List of reactions generated by the mechanism. Default implementation returns an empty list.

Notes

All GlobalMechanism subclasses should implement this method to define the reactions the mechanism produces (e.g., degradation reactions, dilution reactions, etc.).

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_listlist of Species: List of all species to potentially act upon.
mixtureMixture: The mixture containing parameters and other context.
compartmentCompartment, optional: If provided, assigns this compartment to species that have the default compartment before generating reactions.

Returns:

list of Reaction: List of all new reactions generated by the mechanism.

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:

sSpecies: The species that the mechanism is acting upon.
mixtureMixture: The mixture containing parameters and other context.

Returns:

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

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_listlist of Species: List of all species to potentially act upon.
mixtureMixture: The mixture containing parameters and other context.
compartmentCompartment, optional: If provided, assigns this compartment to any new species that have the default compartment.

Returns:

list of Species: List of all new species generated by the mechanism.