biocrnpyler.mechanisms.GlobalMechanism

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

Bases: Mechanism

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:

• name (str) – Name identifier for this mechanism instance.

• mechanism_type (str, default '') – Type classification of this mechanism.

• filter_dict (dict, 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_on (bool, 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_filtering (bool, 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:

• name (str) – Name of the mechanism instance.

• mechanism_type (str) – Type classification of this mechanism.

• 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

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] $\rightarrow$
]

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 reactions for a global mechanism acting on one 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)

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:

1. Checks all attributes and material_type of the species (and subspecies if recursive_species_filtering is True)

2. If any match is found in filter_dict, uses that boolean value

3. If conflicts occur (different attributes give different results), issues a warning and uses default_on

4. If no match is found, uses default_on

get_parameter(species, param_name, mixture)

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)

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:

• s (Species) – The species that the mechanism is acting upon.

• mixture (Mixture) – The mixture containing parameters and other context.

Returns:

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

Return type:

list of Reaction

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)

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)

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)

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