biocrnpyler.mixtures.BasicPURE

class biocrnpyler.mixtures.BasicPURE(name='PURE', rnap='RNAP', ribosome='Ribo', rnaase='RNAase', ntps='NTPs', ndps='NDPs', amino_acids='AAs', fuel='ATP', parameter_file='mixtures/pure_parameters.tsv', **kwargs)[source]

Bases: Mixture

PURE cell-free protein synthesis system with energy consumption.

A mixture that models the PURE (Protein synthesis Using Recombinant Elements) reconstituted cell-free transcription-translation system 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 EnergyTxTlExtract, this mixture does not include fuel regeneration mechanisms. Energy carriers (ATP, NTPs, amino acids) are consumed but not regenerated, making this suitable for modeling resource-limited PURE systems. Different amino acids and nucleotides are lumped into single meta-species for simplicity.

Note that fuel (default ‘ATP’) is modeled as a separate molecule from other nucleotides (‘NTPs’), allowing independent tracking of energy consumption.

Energy usage for transcription and translation is length-dependent, reflecting stoichiometric consumption during biopolymer synthesis.

Parameters:

name (str, default 'PURE') – Name identifier for the mixture.
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 excluding ATP).
ndps (str, default 'NDPs') – Name for the nucleotide diphosphate species (lumped NDPs).
amino_acids (str, default 'AAs') – Name for the amino acid species (lumped amino acids).
fuel (str, default 'ATP') – Name for the primary energy carrier species (ATP).
parameter_file (str, default 'mixtures/pure_parameters.tsv') – Path to file containing default parameter values for the PURE system.
**kwargs – Additional keyword arguments passed to the parent Mixture class.

Attributes:

rnap (Protein) – RNA polymerase component.
ribosome (Protein) – Ribosome component.
rnaase (Protein) – Ribonuclease component.
ntps (Metabolite) – Nucleotide triphosphate metabolite component (excluding ATP).
amino_acids (Metabolite) – Amino acid metabolite component.
fuel (Metabolite) – Fuel metabolite component (ATP).
name (str) – Name of the mixture.

See also

EnergyTxTlExtract: TX-TL with fuel regeneration.
TxTlExtract: TX-TL with machinery but no 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 excluding ATP, lumped)
NDPs (nucleotide diphosphates, lumped)
Fuel (ATP for energy)

Default mechanisms included:

‘transcription’ : Energy_Transcription_MM - Michaelis-Menten transcription with length-dependent ATP and NTP consumption
‘translation’ : Energy_Translation_MM - Michaelis-Menten translation with length-dependent amino acid and ATP consumption
‘rna_degradation’ : Degradation_mRNA_MM - Global RNA degradation by RNase using Michaelis-Menten kinetics
‘catalysis’ : MichaelisMenten - General Michaelis-Menten enzyme catalysis for user-defined enzymatic reactions
‘binding’ : One_Step_Binding - Simple multi-species binding for forming complexes

Key features of this mixture:

Explicit modeling of PURE system components
Length-dependent energy consumption (realistic stoichiometry)
No fuel regeneration mechanisms (finite resource pool)
Resource competition effects (genes compete for RNAP and ribosomes)
Resource depletion dynamics (ATP, NTPs, amino acids deplete)
Enzyme sequestration in complexes
RNA degradation by RNase
Separate tracking of ATP vs other NTPs
Suitable for modeling batch-mode PURE reactions

Energy model details:

Transcription: Consumes L NTPs and L ATPs per mRNA of length L
Translation: Consumes L amino acids and 4L ATPs per protein of length L (4 ATPs per amino acid reflect GTP hydrolysis during elongation)
No regeneration: ATP, NTPs, and amino acids are consumed but not regenerated
Energy depletion: Expression stops when resources are exhausted
Length parameter L: Represents gene/protein length in appropriate units
Lumped species: Different nucleotides lumped into NTPs, different amino acids lumped into single species
Separate ATP: ATP tracked separately from other NTPs for independent energy accounting

Differences from EnergyTxTlExtract:

No fuel regeneration pathway (no NTP regeneration from 3PGA or other fuel sources)
ATP modeled as separate fuel species rather than included in NTPs
Default parameter file points to PURE-specific parameters
Intended for modeling finite-resource batch reactions
More realistic for in vitro PURE systems

Common applications include:

PURE cell-free TX-TL systems
Resource-limited gene expression modeling
TX-TL system optimization with fixed resource budgets
Batch mode TX-TL reactions
Energy budget and resource allocation studies
Multi-gene expression burden analysis
In vitro synthetic biology applications

Examples

Create a PURE mixture for GFP expression:

>>> gfp_gene = bcp.DNAassembly(
...     name='gfp_construct',
...     promoter='pconst',
...     rbs='bcd2',
...     transcript='gfp_mrna',
...     protein='GFP'
... )
>>> mixture = bcp.BasicPURE(
...     name='pure_mixture',
...     components=[gfp_gene],
...     parameter_file='mixtures/pure_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.