biocrnpyler.mixtures.EnergyTxTlExtract

class biocrnpyler.mixtures.EnergyTxTlExtract(name='', rnap='RNAP', ribosome='Ribo', rnaase='RNAase', ntps='NTPs', ndps='NDPs', amino_acids='amino_acids', fuel='Fuel_3PGA', **kwargs)[source]

Bases: Mixture

TX-TL cell extract with explicit machinery and energy consumption.

A mixture that models transcription and translation with explicit representation of RNA polymerase (RNAP), ribosomes, RNases, and energy carrier molecules. This extract uses Michaelis-Menten kinetics with length-dependent fuel consumption to model realistic TX-TL energetics. Unlike TxTlExtract, this mixture explicitly tracks NTPs, amino acids, and fuel species (e.g., 3PGA for NTP regeneration).

Energy usage for transcription and translation is length-dependent, reflecting the stoichiometric consumption of NTPs and amino acids during biopolymer synthesis.

Parameters:

name (str, default '') – Name of the mixture for identification and parameter lookup.
rnap (str, default 'RNAP') – Name for the RNA polymerase protein species.
ribosome (str, default 'Ribo') – Name for the ribosome protein species.
rnaase (str, default 'RNAase') – Name for the ribonuclease protein species.
ntps (str, default 'NTPs') – Name for the nucleotide triphosphate species (lumped NTPs).
ndps (str, default 'NDPs') – Name for the nucleotide diphosphate species (lumped NDPs).
amino_acids (str, default 'amino_acids') – Name for the amino acid species (lumped amino acids).
fuel (str, default 'Fuel_3PGA') – Name for the fuel species used for NTP regeneration (e.g., 3PGA).
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.
rnap (Protein) – RNA polymerase component.
ribosome (Protein) – Ribosome component.
rnaase (Protein) – Ribonuclease component.
amino_acids (Metabolite) – Amino acid metabolite component.
fuel (Metabolite) – Fuel metabolite component for ATP regeneration.
ndps (Metabolite) – Nucleotide diphosphate metabolite component.
ntps (Metabolite) – Nucleotide triphosphate metabolite component with fuel-dependent regeneration.
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

TxTlExtract: TX-TL with machinery but no energy.
SimpleTxTlExtract: TX-TL without machinery or energy.
Energy_Transcription_MM: Mechanism for energy-consuming transcription.
Energy_Translation_MM: Mechanism for energy-consuming translation.
Mixture: Base class for all mixtures.

Notes

This mixture automatically adds the following components:

RNA polymerase (RNAP)
Ribosome
Ribonuclease (RNase)
Amino acids (lumped)
NTPs (nucleotide triphosphates, lumped)
NDPs (nucleotide diphosphates, lumped)
Fuel (e.g., 3PGA for ATP regeneration)

Default mechanisms included:

‘transcription’ : Energy_Transcription_MM - Michaelis-Menten transcription with length-dependent NTP consumption (DNA + RNAP \(\rightleftharpoons\) DNA:RNAP; NTP + DNA:RNAP \(\rightarrow\) DNA + RNAP + mRNA + NDP)
‘translation’ : Energy_Translation_MM - Michaelis-Menten translation with length-dependent amino acid and NTP consumption (mRNA + Rib \(\rightleftharpoons\) mRNA:Rib; AA + NTP + mRNA:Rib \(\rightarrow\) mRNA + Rib + Protein + NDP)
‘rna_degradation’ : Degradation_mRNA_MM - Global RNA degradation by RNase using Michaelis-Menten kinetics
‘catalysis’ : MichaelisMenten - General Michaelis-Menten enzyme catalysis
‘binding’ : One_Step_Binding - Simple multi-species binding
‘pathway’ : OneStepPathway - Metabolite conversion (added to NTPs and fuel components)

Key features of this mixture:

Explicit modeling of transcription and translation machinery
Length-dependent energy consumption
NTP regeneration from fuel species
Resource competition and depletion effects
Realistic modeling of TX-TL resource limits
Energy-dependent expression dynamics

Energy model details:

Transcription consumes L NTPs per mRNA of length L
Translation consumes L amino acids and 4L NTPs per protein of length L
Fuel species regenerates NTPs from NDPs
Different nucleotides and amino acids are lumped together

Common applications include:

Cell-free TX-TL systems with limited resources
Models of energy-limited gene expression
Resource allocation and burden studies
TX-TL system optimization
Metabolic coupling with gene expression

Examples

Create an energy-aware TX-TL mixture for GFP expression:

>>> gfp_gene = bcp.DNAassembly(
...     name='gfp_construct',
...     promoter='pconst',
...     rbs='bcd2',
...     transcript='gfp_mrna',
...     protein='GFP'
... )
>>> mixture = bcp.EnergyTxTlExtract(
...     name='energy_txtl_mixture',
...     components=[gfp_gene],
...     parameter_file='mixtures/extract_parameters.tsv'
... )
>>> crn = mixture.compile_crn()

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:

Add any directly-added species to the CRN
Global component enumeration (generates component interactions)
Local component enumeration (e.g., DNA \(\rightarrow\) RNA \(\rightarrow\) 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 \(\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:

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_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.