biocrnpyler.core.mixture

Classes

Mixture([name, mechanisms, components, ...])

Container for components, mechanisms, and parameters in a CRN model.

class biocrnpyler.core.mixture.Mixture(name='', mechanisms=None, components=None, parameters=None, compartment: Compartment = None, parameter_file=None, overwrite_parameters=False, global_mechanisms=None, species=None, initial_condition_dictionary=None, global_component_enumerators=None, global_recursion_depth=4, local_recursion_depth=None)[source]

Container for components, mechanisms, and parameters in a CRN model.

A Mixture holds together all components (DNA, RNA, Protein, etc.), mechanisms (transcription, translation, binding, etc.), and parameters needed to compile a chemical reaction network (CRN). Mixtures can include default mechanisms that apply to all components, as well as global mechanisms that affect all species (e.g., dilution, degradation).

Parameters:

namestr, default=’’: Name of the mixture for identification and parameter lookup.
mechanismsdict, list, or Mechanism, optional: Default mechanisms for components in this mixture. Can be a dict with mechanism types (str) as keys and mechanism objects as values, a list of mechanism objects, or a single Mechanism.
componentslist of Component or Component, optional: Components to include in the mixture. Components are deep-copied when added to prevent modification of original objects.
parametersdict, optional: Dictionary of parameter values. Keys follow the format (mechanism, part_id, param_name).
compartmentCompartment, optional: Default compartment for all components and species in this mixture.
parameter_filestr, optional: Path to a CSV or TSV file containing parameters to load.
overwrite_parametersbool, default=False: If True, parameters from file/dict overwrite existing parameters. If False, existing parameters are preserved.
global_mechanismsdict, list, or GlobalMechanism, optional: Global mechanisms that apply to all species after component compilation (e.g., dilution, global degradation). Can be a dict, list, or single GlobalMechanism.
specieslist of Species or Species, optional: Additional species to add directly to the CRN without going through component compilation.
initial_condition_dictionarydict, optional: Dictionary mapping species to initial concentration values. Deprecated in favor of using parameters with mechanism=’initial concentration’.
global_component_enumeratorslist, optional: List of global component enumerators for advanced component generation patterns (e.g., creating all pairwise interactions).
global_recursion_depthint, default=4: Maximum recursion depth for global component enumeration during compilation.
local_recursion_depthint, optional: Maximum recursion depth for local component enumeration. If None, defaults to global_recursion_depth + 2.

Attributes:

namestr: Name of the mixture.
compartmentCompartment or None: Default compartment for the mixture.
componentslist of Component: List of components in the mixture (deep copies of added components).
mechanismsdict: Mechanism: Stores mixture mechanisms.
global_mechanismsdict: Mechanism: Stores global mechanisms in the mixture.
parameter_databaseParameterDatabase: Database storing all parameters for this mixture.
added_specieslist of Species: List of species added directly to the mixture.
global_component_enumeratorslist: List of global component enumerators.
global_recursion_depthint: Recursion depth for global component enumeration.
local_recursion_depthint: Recursion depth for local component enumeration.
crnChemicalReactionNetwork or None: The compiled CRN, created by calling compile_crn.

See also

Component: Base class for biomolecular components.
Mechanism: Base class for reaction generation schemas.
GlobalMechanism: Mechanisms that apply to all species.
ChemicalReactionNetwork: Container for species and reactions.

Notes

Components added to a Mixture are deep-copied to prevent unintended modifications. Each component’s mixture attribute is set to reference this Mixture, allowing components to access default mechanisms and parameters.

The compilation process follows these steps:

Global component enumeration (e.g., generating all interactions)
Local component enumeration (e.g., DNA –> RNA –> Protein)
Species generation from all enumerated components
Reaction generation from all enumerated components
Application of global mechanisms to all species

Examples

Create a basic mixture with components and mechanisms:

>>> # Create a simple transcription-translation mixture
>>> mixture = bcp.Mixture(
...     name="txtl_extract",
...     mechanisms={
...         'transcription': bcp.SimpleTranscription(),
...         'translation': bcp.SimpleTranslation()
...     },
...     parameters={'ktx': 0.05, 'ktl': 0.01}
... )

Add components to the mixture:

>>> promoter = bcp.Promoter("pconst")
>>> gene = bcp.DNA_construct([promoter, bcp.RBS('rbs'), bcp.CDS('gfp')])
>>> mixture.add_component(gene)

Compile the CRN:

>>> crn = mixture.compile_crn()
>>> print(
...     f"CRN has {len(crn.species)} species "
...     f"and {len(crn.reactions)} reactions")

add_component(component)[source]

Add a single component to the mixture.

Parameters:

componentComponent or list of Component: Component object to add to the mixture. If a list is provided, calls add_components instead. The component is deep-copied before being added.

Raises:

AssertionError: If the component is not a Component object.
ValueError: If a component with the same type and name already exists in the mixture.

Notes

Components are deep-copied when added to prevent modification of the original component. The copied component’s mixture attribute is set to this Mixture, and its compartment is set to the mixture’s compartment.

add_components(components: List[Component] | Component)[source]

Add multiple components to the mixture.

Parameters:

componentsComponent or list of Component: Component object(s) to add to the mixture. Each component is deep-copied before being added.

Raises:

ValueError: If components is not a Component, list of Components, or if any duplicate components are detected.

See also

add_component: Add a single component to the mixture.

add_global_mechanism(mechanism, mech_type=None, overwrite=False)[source]

Add a global mechanism to the mixture.

Global mechanisms are applied to all species after component compilation, enabling operations like dilution or global degradation.

Parameters:

mechanismGlobalMechanism: The global mechanism object to add. Must be a GlobalMechanism instance.
mech_typestr, optional: The type key under which to store the mechanism. If None, uses the mechanism’s mechanism_type attribute.
overwritebool, default=False: If True, replaces any existing global mechanism with the same key. If False, raises ValueError when key already exists.

Raises:

TypeError: If mechanism is not a GlobalMechanism object, or if mech_type is not a string.
ValueError: If mechanism key already exists and overwrite is False.

Notes

Global mechanisms are applied during compile_crn after all component reactions have been generated.

add_mechanism(mechanism, mech_type=None, overwrite=False)[source]

Add a mechanism to the mixture’s mechanism dictionary.

Parameters:

mechanismMechanism or GlobalMechanism: The mechanism object to add. If a GlobalMechanism is provided, it is automatically added to the global mechanisms dictionary.
mech_typestr, optional: The type key under which to store the mechanism. If None, uses the mechanism’s mechanism_type attribute.
overwritebool, default=False: If True, replaces any existing mechanisms with the same keys. If False, raises ValueError when keys already exist. If None, ignores mechanisms that already exist.

Raises:

TypeError: If mechanism is not a Mechanism object, or if mech_type is not a string.
ValueError: If mechanism key already exists and overwrite is None.

See also

add_global_mechanism: Add a global mechanism specifically.

add_mechanisms(mechanisms, overwrite=False)[source]

Add multiple mechanisms to the mixture.

Accepts mechanisms as a single object, list, or dictionary and adds them to the mixture’s mechanism dictionary. Can handle both regular Mechanism and GlobalMechanism objects.

Parameters:

mechanismsMechanism, GlobalMechanism, dict, or list: The mechanism(s) to add. Can be a single mechanism, a dict with mechanism types as keys and mechanisms as values, or a list of mechanisms.
overwritebool, default=False: If True, replaces any existing mechanisms with the same keys. If False, raises ValueError when keys already exist. If None, ignores mechanisms that already exist.

Raises:

ValueError: If mechanisms is not a valid type, or if mechanism key conflicts occur with overwrite=False.

See also

add_mechanism: Add a single mechanism to the mixture.

add_species(species: List[Species] | Species)[source]

Add species directly to the mixture without component compilation.

Parameters:

speciesSpecies or list of Species: Species object(s) to add directly to the mixture. These species will be included in the CRN during compilation.

Raises:

AssertionError: If any element in the list is not a Species object.

Notes

Species added this way bypass component enumeration and are added directly to the CRN during compile_crn.

add_species_to_crn(new_species, component=None, no_initial_concentrations=False, copy_species=True, compartment=None)[source]

Add species to the CRN with initial concentrations.

Helper method that adds species to the CRN and automatically looks up and assigns their initial concentrations.

Parameters:

new_speciesSpecies or list of Species: Species to add to the CRN.
componentComponent, optional: The component that generated these species. Used for component-specific initial concentration lookup.
no_initial_concentrationsbool, default=False: If True, skips initial concentration lookup and assignment.
copy_speciesbool, default=True: If True, deep-copies species before adding them to the CRN.
compartmentCompartment, optional: Compartment to assign to the species. Overrides species’ existing compartments.

Returns:

list of Species: All species in the CRN after addition (may include pre-existing species).

Notes

This method tracks which species are newly added and only assigns initial concentrations to those new species, preventing overwriting of previously set initial concentrations.

apply_global_mechanisms(species, compartment=None) → Tuple[List[Species], List[Reaction]][source]

Apply all global mechanisms to a set of species.

Calls each global mechanism’s update_species_global and update_reactions_global methods, then adds the resulting species and reactions to the CRN.

Parameters:

specieslist of Species: Species to which global mechanisms should be applied.
compartmentCompartment, optional: Compartment for newly generated species and reactions.

Returns:

tuple of (list of Species, list of Reaction): New species and reactions generated by global mechanisms.

Notes

Global mechanisms are typically used for operations that affect all species uniformly, such as dilution, global degradation, or compartment transport.

compile_crn(recursion_depth: int = None, initial_concentration_dict: dict = None, return_enumerated_components: bool = False, initial_concentrations_at_end: bool = False, copy_objects: bool = True, add_reaction_species: bool = True, compartment: Compartment = None) → ChemicalReactionNetwork[source]

Compile a chemical reaction network from the mixture.

Enumerates components, generates species and reactions from each component, applies global mechanisms, and returns a complete CRN.

Parameters:

recursion_depthint, optional: Maximum recursion depth for both local and global component enumeration. If None, uses self.global_recursion_depth.
initial_concentration_dictdict, optional: Dictionary mapping species to initial concentrations. This overrides all other initial concentration settings and is applied at the very end of compilation.
return_enumerated_componentsbool, default=False: If True, returns a tuple of (CRN, enumerated_components) instead of just the CRN.
initial_concentrations_at_endbool, default=False: If True, initial concentrations are only set at the end using the mixture’s parameter database, ignoring component-specific initial concentrations during compilation.
copy_objectsbool, default=True: If True, species and reactions are deep-copied when added to the CRN. Protects CRN validity at the expense of compilation speed.
add_reaction_speciesbool, default=True: If True, species appearing in reactions are automatically added to the CRN. Ensures no missing species at the expense of compilation speed.
compartmentCompartment, optional: Compartment to assign to all species and reactions that are not already assigned to a compartment. If None, uses self.compartment.

Returns:

ChemicalReactionNetwork or tuple: If return_enumerated_components is False, returns the compiled ChemicalReactionNetwork. If True, returns a tuple of (ChemicalReactionNetwork, list of enumerated Components).

Notes

The compilation process follows these steps:

Add any directly-added species to the CRN
Global component enumeration (generates component interactions)
Local component enumeration (e.g., DNA –> RNA –> Protein)
Generate species from all enumerated components
Generate reactions from all enumerated components
Apply global mechanisms to all species
Set initial concentrations

Examples

Basic compilation:

>>> gene = bcp.DNAassembly(
...     'GFP', promoter='pconst', rbs='RBS', protein='GFP')
>>> mixture = bcp.Mixture(
...     name="txtl_extract",
...     components=[gene],
...     mechanisms={
...         'transcription': bcp.SimpleTranscription(),
...         'translation': bcp.SimpleTranslation()
...     },
...     parameters={'ktx': 0.05, 'ktl': 0.01}
... )
>>> crn = mixture.compile_crn()

Compilation with custom initial concentrations:

>>> crn = mixture.compile_crn(
...     initial_concentration_dict={gene.dna: 1, gene.transcript: 50}
... )

Get both CRN and enumerated components:

>>> crn, components = mixture.compile_crn(
...     return_enumerated_components=True
... )

component_enumeration(comps_to_enumerate=None, recursion_depth=10) → List[Component][source]

Recursively enumerate components to generate derived components.

Calls each component’s enumerate_components method repeatedly to expand high-level components into their constituent parts (e.g., DNA_construct –> RNA_construct –> Protein).

Parameters:

comps_to_enumeratelist of Component, optional: Initial components to enumerate. If None, uses all components in the mixture.
recursion_depthint, default=10: Maximum number of enumeration iterations. Prevents infinite recursion.

Returns:

list of Component: All components including the original components and all derived components generated through enumeration.

Warns:

UserWarning: Warns if unenumerated components remain after reaching the recursion depth limit.

get_component(component=None, name=None, index=None)[source]

Retrieve components from the mixture by various criteria.

Exactly one of the three parameters must be provided.

Parameters:

componentComponent, optional: A component instance to search for. Returns components with matching type and name.
namestr, optional: Name of the component to search for. Returns all components with this name.
indexint, optional: Index of the component in the mixture’s component list.

Returns:

Component, list of Component, or None

Single Component if exactly one match is found or index is used
List of Components if multiple matches are found
None if no matches are found

Raises:

ValueError: If zero or more than one parameter is provided, or if parameters are of incorrect types.

get_initial_concentration(S: List | Species, component=None)[source]

Determine initial concentrations using parameter hierarchy.

Searches for initial concentration parameters for species following a hierarchical lookup strategy, defaulting to 0 if not found.

Parameters:

SSpecies or list of Species: Species object(s) for which to find initial concentrations. Lists are automatically flattened.
componentComponent, optional: The component that generated the species. Used for component-specific parameter lookup.

Returns:

dict: Dictionary mapping each Species object to its initial concentration value (float).

Raises:

ValueError: If any element in S is not a Species object.

Notes

The parameter lookup hierarchy is:

Component’s ParameterDatabase with mechanism='initial concentration', part_id=mixture.name, and parameter names: str(s), s.name, or component.name (where s is the component’s primary species)
Mixture’s ParameterDatabase with the same keys
Defaults to 0 if not found

get_mechanism(mechanism_type)[source]

Retrieve a mechanism by type from the mixture.

Parameters:

mechanism_typestr: The type identifier of the mechanism to retrieve (e.g., ‘transcription’, ‘translation’, ‘binding’).

Returns:

Mechanism or None: The requested mechanism object, or None if not found.

Raises:

TypeError: If mechanism_type is not a string.

get_parameter(mechanism, part_id, param_name)[source]

Retrieve a parameter from the mixture’s parameter database.

Parameters:

mechanismstr: Mechanism identifier for the parameter lookup key.
part_idstr: Part identifier for the parameter lookup key.
param_namestr: Name of the parameter to retrieve.

Returns:

Parameter or None: The parameter object, or None if not found.

global_component_enumeration(comps_to_enumerate=None, recursion_depth=None) → List[Component][source]

Apply global component enumerators to generate new components.

Global component enumerators create new components based on patterns across all components (e.g., generating all pairwise binding interactions between proteins).

Parameters:

comps_to_enumeratelist of Component, optional: Initial components to pass to enumerators. If None, uses all components in the mixture.
recursion_depthint, optional: Maximum number of enumeration iterations. If None, uses self.global_recursion_depth.

Returns:

list of Component: All components including original and newly generated components from global enumeration.

Notes

This method is called during compile_crn before local component enumeration. Global enumerators are useful for creating complex interaction networks without manually specifying every interaction.

property global_mechanisms: Mechanism: Stores global mechanisms in the mixture.

property mechanisms: Mechanism: Stores mixture mechanisms.

set_species(species: Species | str, material_type=None, attributes=None)[source]

Convert various inputs into Species objects.

Parameters:

speciesSpecies, str, or Component: The species to convert. Can be a Species object (returned as-is), a string (creates new Species), or a Component (extracts its species).
material_typestr, optional: Material type for the species (e.g., ‘dna’, ‘rna’, ‘protein’). Only used when creating new Species from strings.
attributeslist of str, optional: Attributes to assign to the species. Only used when creating new Species from strings.

Returns:

Species: The converted Species object.

Raises:

ValueError: If the input cannot be converted to a valid Species.

update_parameters(parameter_file=None, parameters=None, overwrite_parameters=True)[source]

Update the parameter database with new parameters.

Parameters:

parameter_filestr, optional: Path to a CSV or TSV file containing parameters to load.
parametersdict, optional: Dictionary of parameters to add. Keys follow the format (mechanism, part_id, param_name).
overwrite_parametersbool, default=True: If True, new parameter values overwrite existing ones. If False, existing parameters are preserved.