biocrnpyler.mechanisms.Dilution

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

Bases: GlobalMechanism

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

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

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

Parameters:

  • name (str, default 'global_degradation_via_dilution') – Name identifier for this mechanism instance.

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

  • filter_dict (dict, optional) – Dictionary for filtering which species undergo dilution. If None, all species are affected based on default_on.

  • default_on (bool, default True) – If True, dilution applies to all species not explicitly filtered out. If False, dilution 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

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}
... )

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 dilution 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:

  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)[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: 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:

  • s (Species) – The species undergoing dilution.

  • mixture (Mixture) – The mixture containing the ‘kdil’ parameter.

Returns:

List containing a single reaction: S \(\rightarrow\) \(\emptyset\) 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