biocrnpyler.core.Mixture

class biocrnpyler.core.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]

Bases: object

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:

  • name (str, default '') – Name of the mixture for identification and parameter lookup.

  • mechanisms (dict, 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.

  • components (list of Component or Component, optional) – Components to include in the mixture. Components are deep-copied when added to prevent modification of original objects.

  • parameters (dict, optional) – Dictionary of parameter values. Keys follow the format (mechanism, part_id, param_name).

  • compartment (Compartment, optional) – Default compartment for all components and species in this mixture.

  • parameter_file (str, optional) – Path to a CSV or TSV file containing parameters to load.

  • overwrite_parameters (bool, default False) – If True, parameters from file/dict overwrite existing parameters. If False, existing parameters are preserved.

  • global_mechanisms (dict, 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.

  • species (list of Species or Species, optional) – Additional species to add directly to the CRN without going through component compilation.

  • initial_condition_dictionary (dict, optional) – Dictionary mapping species to initial concentration values. Deprecated in favor of using parameters with mechanism=’initial concentration’.

  • global_component_enumerators (list, optional) – List of global component enumerators for advanced component generation patterns (e.g., creating all pairwise interactions).

  • global_recursion_depth (int, default 4) – Maximum recursion depth for global component enumeration during compilation.

  • local_recursion_depth (int, optional) – Maximum recursion depth for local component enumeration. If None, defaults to global_recursion_depth + 2.

Attributes:

  • name (str) – Name of the mixture.

  • compartment (Compartment or None) – Default compartment for the mixture.

  • components (list of Component) – List of components in the mixture (deep copies of added components).

  • mechanisms (dict) – Dictionary of default mechanisms, keyed by mechanism type (str).

  • global_mechanisms (dict) – Dictionary of global mechanisms, keyed by mechanism type (str).

  • parameter_database (ParameterDatabase) – Database storing all parameters for this mixture.

  • added_species (list of Species) – List of species added directly to the mixture.

  • global_component_enumerators (list) – List of global component enumerators.

  • global_recursion_depth (int) – Recursion depth for global component enumeration.

  • local_recursion_depth (int) – Recursion depth for local component enumeration.

  • crn (ChemicalReactionNetwork 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:

  1. Global component enumeration (e.g., generating all interactions)

  2. Local component enumeration (e.g., DNA \(\rightarrow\) RNA \(\rightarrow\) Protein)

  3. Species generation from all enumerated components

  4. Reaction generation from all enumerated components

  5. 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")

Methods

add_component

Add a single component to the mixture.

add_components

Add multiple components to the mixture.

add_global_mechanism

Add a global mechanism to the mixture.

add_mechanism

Add a mechanism to the mixture's mechanism dictionary.

add_mechanisms

Add multiple mechanisms to the mixture.

add_species

Add species directly to the mixture without component compilation.

add_species_to_crn

Add species to the CRN with initial concentrations.

apply_global_mechanisms

Apply all global mechanisms to a set of species.

compile_crn

Compile a chemical reaction network from the mixture.

component_enumeration

Recursively enumerate components to generate derived components.

get_component

Retrieve components from the mixture by various criteria.

get_initial_concentration

Determine initial concentrations using parameter hierarchy.

get_mechanism

Retrieve a mechanism by type from the mixture.

get_parameter

Retrieve a parameter from the mixture's parameter database.

global_component_enumeration

Apply global component enumerators to generate new components.

set_species

Convert various inputs into Species objects.

update_parameters

Update the parameter database with new parameters.
add_component(component)[source]

Add a single component to the mixture.

Parameters:

component (Component 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:

components (Component 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:

  • mechanism (GlobalMechanism) – The global mechanism object to add. Must be a GlobalMechanism instance.

  • mech_type (str, optional) – The type key under which to store the mechanism. If None, uses the mechanism’s mechanism_type attribute.

  • overwrite (bool, 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:

  • mechanism (Mechanism or GlobalMechanism) – The mechanism object to add. If a GlobalMechanism is provided, it is automatically added to the global mechanisms dictionary.

  • mech_type (str, optional) – The type key under which to store the mechanism. If None, uses the mechanism’s mechanism_type attribute.

  • overwrite (bool, 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:

  • mechanisms (Mechanism, 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.

  • overwrite (bool, 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:

species (Species 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_species (Species or list of Species) – Species to add to the CRN.

  • component (Component, optional) – The component that generated these species. Used for component-specific initial concentration lookup.

  • no_initial_concentrations (bool, default False) – If True, skips initial concentration lookup and assignment.

  • copy_species (bool, default True) – If True, deep-copies species before adding them to the CRN.

  • compartment (Compartment, optional) – Compartment to assign to the species. Overrides species’ existing compartments.

Returns:

All species in the CRN after addition (may include pre-existing species).

Return type:

list of 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:

  • species (list of Species) – Species to which global mechanisms should be applied.

  • compartment (Compartment, optional) – Compartment for newly generated species and reactions.

Returns:

New species and reactions generated by global mechanisms.

Return type:

tuple of (list of Species, list of Reaction)

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_depth (int, optional) – Maximum recursion depth for both local and global component enumeration. If None, uses self.global_recursion_depth.

  • initial_concentration_dict (dict, 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_components (bool, default False) – If True, returns a tuple of (CRN, enumerated_components) instead of just the CRN.

  • initial_concentrations_at_end (bool, 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_objects (bool, 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_species (bool, default True) – If True, species appearing in reactions are automatically added to the CRN. Ensures no missing species at the expense of compilation speed.

  • compartment (Compartment, optional) – Compartment to assign to all species and reactions that are not already assigned to a compartment. If None, uses self.compartment.

Returns:

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

Return type:

ChemicalReactionNetwork or tuple

Notes

The compilation process follows these steps:

  1. Add any directly-added species to the CRN

  2. Global component enumeration (generates component interactions)

  3. Local component enumeration (e.g., DNA \(\rightarrow\) RNA \(\rightarrow\) Protein)

  4. Generate species from all enumerated components

  5. Generate reactions from all enumerated components

  6. Apply global mechanisms to all species

  7. 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 \(\rightarrow\) RNA_construct \(\rightarrow\) Protein).

Parameters:

  • comps_to_enumerate (list of Component, optional) – Initial components to enumerate. If None, uses all components in the mixture.

  • recursion_depth (int, default 10) – Maximum number of enumeration iterations. Prevents infinite recursion.

Returns:

All components including the original components and all derived components generated through enumeration.

Return type:

list of Component

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:

  • component (Component, optional) – A component instance to search for. Returns components with matching type and name.

  • name (str, optional) – Name of the component to search for. Returns all components with this name.

  • index (int, optional) – Index of the component in the mixture’s component list.

Returns:

  • 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

Return type:

Component, list of Component, or None

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:

  • S (Species or list of Species) – Species object(s) for which to find initial concentrations. Lists are automatically flattened.

  • component (Component, optional) – The component that generated the species. Used for component-specific parameter lookup.

Returns:

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

Return type:

dict

Raises:

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

Notes

The parameter lookup hierarchy is:

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

  2. Mixture’s ParameterDatabase with the same keys

  3. Defaults to 0 if not found

get_mechanism(mechanism_type)[source]

Retrieve a mechanism by type from the mixture.

Parameters:

mechanism_type (str) – The type identifier of the mechanism to retrieve (e.g., ‘transcription’, ‘translation’, ‘binding’).

Returns:

The requested mechanism object, or None if not found.

Return type:

Mechanism or None

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:

  • mechanism (str) – Mechanism identifier for the parameter lookup key.

  • part_id (str) – Part identifier for the parameter lookup key.

  • param_name (str) – Name of the parameter to retrieve.

Returns:

The parameter object, or None if not found.

Return type:

Parameter or None

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_enumerate (list of Component, optional) – Initial components to pass to enumerators. If None, uses all components in the mixture.

  • recursion_depth (int, optional) – Maximum number of enumeration iterations. If None, uses self.global_recursion_depth.

Returns:

All components including original and newly generated components from global enumeration.

Return type:

list of Component

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

Stores global mechanisms in the mixture.

Type:

Mechanism

property mechanisms

Stores mixture mechanisms.

Type:

Mechanism

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

Convert various inputs into Species objects.

Parameters:

  • species (Species, 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_type (str, optional) – Material type for the species (e.g., ‘dna’, ‘rna’, ‘protein’). Only used when creating new Species from strings.

  • attributes (list of str, optional) – Attributes to assign to the species. Only used when creating new Species from strings.

Returns:

The converted Species object.

Return type:

Species

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_file (str, optional) – Path to a CSV or TSV file containing parameters to load.

  • parameters (dict, optional) – Dictionary of parameters to add. Keys follow the format (mechanism, part_id, param_name).

  • overwrite_parameters (bool, default True) – If True, new parameter values overwrite existing ones. If False, existing parameters are preserved.