biocrnpyler.mixtures.extract

Classes

EnergyTxTlExtract([name, rnap, ribosome, ...])	TX-TL cell extract with explicit machinery and energy consumption.
ExpressionExtract([name])	Gene expression extract without explicit TX-TL machinery.
SimpleTxTlExtract([name])	TX-TL extract with simple transcription and translation mechanisms.
TxTlExtract([name, rnap, ribosome, rnaase])	TX-TL extract with explicit transcription and translation machinery.

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

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:

namestr, default=’’

Name of the mixture for identification and parameter lookup.

rnapstr, default=’RNAP’

Name for the RNA polymerase protein species.

ribosomestr, default=’Ribo’

Name for the ribosome protein species.

rnaasestr, default=’RNAase’

Name for the ribonuclease protein species.

ntpsstr, default=’NTPs’

Name for the nucleotide triphosphate species (lumped NTPs).

ndpsstr, default=’NDPs’

Name for the nucleotide diphosphate species (lumped NDPs).

amino_acidsstr, default=’amino_acids’

Name for the amino acid species (lumped amino acids).

fuelstr, default=’Fuel_3PGA’

Name for the fuel species used for NTP regeneration (e.g., 3PGA).

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.

rnapProtein

RNA polymerase component.

ribosomeProtein

Ribosome component.

rnaaseProtein

Ribonuclease component.

amino_acidsMetabolite

Amino acid metabolite component.

fuelMetabolite

Fuel metabolite component for ATP regeneration.

ndpsMetabolite

Nucleotide diphosphate metabolite component.

ntpsMetabolite

Nucleotide triphosphate metabolite component with fuel-dependent regeneration.

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

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 <–> DNA:RNAP; NTP + DNA:RNAP –> DNA + RNAP + mRNA + NDP)

• ‘translation’ : Energy_Translation_MM - Michaelis-Menten translation with length-dependent amino acid and NTP consumption (mRNA + Rib <–> mRNA:Rib; AA + NTP + mRNA:Rib –> 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()

add_component(component)

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)

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)

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)

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)

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)

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)

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]]

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

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:

1. Add any directly-added species to the CRN

2. Global component enumeration (generates component interactions)

3. Local component enumeration (e.g., DNA –> RNA –> 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]

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)

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)

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:

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)

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)

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]

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)

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)

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.

class biocrnpyler.mixtures.extract.ExpressionExtract(name='', **kwargs)

Gene expression extract without explicit TX-TL machinery.

A simplified mixture that models gene expression as a single direct reaction from DNA to protein, without explicitly representing transcription and translation as separate processes. This extract lumps transcription and translation into a single ‘expression’ reaction, eliminating intermediate mRNA species and cellular machinery (ribosomes, polymerases, etc.).

This extract is appropriate for coarse-grained models where mRNA dynamics are negligible and computational efficiency is prioritized over mechanistic detail.

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

SimpleTxTlExtract

TX-TL with separate transcription and translation.

TxTlExtract

TX-TL with explicit machinery.

OneStepGeneExpression

Mechanism used for expression.

Mixture

Base class for all mixtures.

Notes

Default mechanisms included:

• ‘transcription’ : OneStepGeneExpression - Single-step gene expression (DNA –> DNA + Protein) without intermediate mRNA

• ‘translation’ : EmptyMechanism - Dummy mechanism that generates no reactions (translation is disabled)

• ‘catalysis’ : BasicCatalysis - Simple catalytic reactions without explicit enzyme binding

• ‘binding’ : One_Step_Binding - Simple multi-species binding

Key features of this extract:

• No explicit transcription or translation steps

• No cellular machinery (RNAP, ribosomes, RNases)

• No intermediate mRNA species

• Simplified parameter space (single ‘kexpress’ rate)

• Fast compilation and simulation

When compiled, this extract automatically disables transcript generation in DNA assemblies that produce proteins, routing expression directly from DNA to protein.

Common applications include:

• High-level gene circuit modeling

• Steady-state or quasi-steady-state analyses

• Rapid prototyping of genetic designs

• Models where mRNA dynamics are negligible

Examples

Create an expression mixture for GFP production:

>>> gfp_gene = bcp.DNAassembly(
...     name='gfp_construct',
...     promoter='pconst',
...     protein='GFP'
... )
>>> mixture = bcp.ExpressionExtract(
...     name='expression_mixture',
...     components=[gfp_gene],
...     parameter_file='mixtures/extract_parameters.tsv'
... )
>>> crn = mixture.compile_crn()

add_component(component)

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)

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)

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)

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)

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)

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)

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]]

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(**kwargs) → ChemicalReactionNetwork

Compile CRN with transcript generation disabled in gene expression.

Overrides the parent compile_crn method to automatically disable transcript generation in DNA assemblies that produce proteins. This ensures that gene expression proceeds directly from DNA to protein without intermediate mRNA species.

Parameters:

**kwargs

Additional keyword arguments passed to the parent Mixture compile_crn method.

Returns:

ChemicalReactionNetwork

Compiled chemical reaction network with expression reactions.

Notes

This method automatically modifies DNA assemblies before compilation:

• For assemblies with a protein product, sets transcript to False

• RNA-only assemblies (no protein) are not affected

• Mechanisms receive protein instead of transcript when transcript is disabled

This behavior enables the single-step expression mechanism to route production directly to protein.

See Mixture.compile_crn for a more detailed description of the parent method behavior.

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

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)

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)

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:

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)

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)

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]

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)

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)

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.

class biocrnpyler.mixtures.extract.SimpleTxTlExtract(name='', **kwargs)

TX-TL extract with simple transcription and translation mechanisms.

A mixture that models transcription and translation as separate catalytic reactions without explicitly representing cellular machinery (RNAP, ribosomes, RNases). This extract uses simple mass-action kinetics where DNA and mRNA act as catalysts for transcript and protein production, respectively. Unlike ExpressionExtract, this mixture includes explicit mRNA species and separate TX-TL steps. Unlike TxTlExtract, it does not model enzyme binding or resource competition.

This extract includes global RNA degradation via dilution.

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

ExpressionExtract

Single-step expression without transcripts.

TxTlExtract

TX-TL with explicit machinery.

SimpleTranscription

Mechanism used for transcription.

SimpleTranslation

Mechanism used for translation.

Mixture

Base class for all mixtures.

Notes

Default mechanisms included:

• ‘transcription’ : SimpleTranscription - Simple catalytic transcription (DNA –> DNA + mRNA) without explicit RNAP binding

• ‘translation’ : SimpleTranslation - Simple catalytic translation (mRNA –> mRNA + Protein) without explicit ribosome binding

• ‘rna_degradation’ : Dilution - Global RNA degradation mechanism (mRNA –> ∅) applied to all RNA species

• ‘catalysis’ : BasicCatalysis - Simple catalytic reactions without explicit enzyme binding

• ‘binding’ : One_Step_Binding - Simple multi-species binding

Key features of this extract:

• Explicit transcription and translation steps

• Intermediate mRNA species

• Simple mass-action kinetics (no enzyme binding)

• No cellular machinery (RNAP, ribosomes)

• Global RNA degradation

• Faster simulation than Michaelis-Menten models

Common applications include:

• Gene circuit modeling with explicit TX-TL

• Models where machinery is not limiting

• Constitutive or weakly regulated promoters

• Rapid prototyping with mRNA dynamics

Examples

Create a simple TX-TL mixture for GFP expression:

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

add_component(component)

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)

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)

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)

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)

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)

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)

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]]

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

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:

1. Add any directly-added species to the CRN

2. Global component enumeration (generates component interactions)

3. Local component enumeration (e.g., DNA –> RNA –> 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]

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)

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)

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:

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)

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)

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]

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)

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)

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.

class biocrnpyler.mixtures.extract.TxTlExtract(name='', rnap='RNAP', ribosome='Ribo', rnaase='RNAase', **kwargs)

TX-TL extract with explicit transcription and translation machinery.

A mixture that models transcription and translation with explicit representation of RNA polymerase (RNAP), ribosomes, and RNases. This extract uses Michaelis-Menten kinetics for transcription and translation, explicitly tracking enzyme-substrate binding and catalysis. Unlike SimpleTxTlExtract, this mixture models resource competition and enzyme sequestration effects.

This model does not include explicit energy species. For energy-aware modeling, use EnergyTxTlExtract.

Parameters:

namestr, default=’’

Name of the mixture for identification and parameter lookup.

rnapstr, default=’RNAP’

Name for the RNA polymerase protein species.

ribosomestr, default=’Ribo’

Name for the ribosome protein species.

rnaasestr, default=’RNAase’

Name for the ribonuclease protein species.

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

crnChemicalReactionNetwork or None

The compiled CRN, created by calling compile_crn.

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.

rnapProtein

RNA polymerase component.

ribosomeProtein

Ribosome component.

rnaaseProtein

Ribonuclease component.

See also

SimpleTxTlExtract

TX-TL without explicit machinery.

EnergyTxTlExtract

TX-TL with explicit energy consumption.

ExpressionExtract

Combined TX-TL without transcripts.

Mixture

Base class for all mixtures.

Notes

This mixture automatically adds the following components:

• RNA polymerase (RNAP)

• Ribosome

• Ribonuclease (RNase)

Default mechanisms included:

• ‘transcription’ : Transcription_MM - Michaelis-Menten transcription with explicit RNAP binding (DNA + RNAP <–> DNA:RNAP –> DNA + RNAP + mRNA)

• ‘translation’ : Translation_MM - Michaelis-Menten translation with explicit ribosome binding (mRNA + Rib <–> mRNA:Rib –> mRNA + Rib + Protein)

• ‘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

Key features of this mixture:

• Explicit modeling of transcription and translation machinery

• Resource competition effects (multiple genes compete for RNAP)

• Enzyme sequestration in complexes

• RNA degradation dynamics

• Suitable for modeling TX-TL systems with limited machinery

Common applications include:

• Cell-free TX-TL systems

• Resource allocation in gene circuits

• Gene expression burden studies

• Synthetic biology prototyping

Examples

Create a TX-TL mixture for GFP expression:

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

add_component(component)

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)

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)

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)

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)

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)

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)

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]]

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

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:

1. Add any directly-added species to the CRN

2. Global component enumeration (generates component interactions)

3. Local component enumeration (e.g., DNA –> RNA –> 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]

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)

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)

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:

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)

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)

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]

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)

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)

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.