biocrnpyler.components.basic

Classes

ChemicalComplex(species[, name, ...])	Complex formed by binding of two or more molecular species.
DNA(name[, length, attributes])	DNA sequence component with specified length.
Enzyme(enzyme, substrates, products[, ...])	Enzyme that catalyzes conversion of substrates to products.
Metabolite(name[, attributes, precursors, ...])	Metabolic compound that can be produced, utilized, or degraded.
Protein(name[, length, attributes])	Protein component with specified length.
RNA(name[, length, attributes])	RNA sequence component with specified length.

class biocrnpyler.components.basic.ChemicalComplex(species: List[Species], name: str = None, material_type='complex', attributes=None, **kwargs)

Complex formed by binding of two or more molecular species.

A ChemicalComplex component represents a molecular complex formed when two or more species bind together. The complex automatically inherits attributes from its constituent species. The component uses a ‘binding’ mechanism to generate binding and unbinding reactions.

Parameters:

specieslist of Species, str, or Component

List of species that form the complex. Must contain at least two elements. Each element can be a Species object, string name, or Component with an associated species.

namestr, optional

Name of the complex. If None, a name is automatically generated from the constituent species names.

material_typestr, default=’complex’

Material type identifier for the complex species. Can be customized for specific complex types.

attributeslist of str, optional

List of attribute tags to associate with the complex species. The complex also inherits attributes from its constituent species.

**kwargs

Additional keyword arguments passed to the Component base class constructor.

Attributes:

speciesComplex

The complex species object created from the constituent species.

internal_specieslist of Species

List of individual species that make up the complex.

See also

Component

Base class for biomolecular components.

Species

Chemical species representation.

Complex

Species subclass for molecular complexes.

Notes

The ChemicalComplex component uses a ‘binding’ mechanism which must be provided by the containing mixture. The binding mechanism generates:

• Forward binding reactions (species –> complex)

• Reverse unbinding reactions (complex –> species)

The first species in the list is treated as the ‘bindee’ and remaining species are treated as ‘binders’ in the binding mechanism.

Examples

Create a simple protein-DNA complex:

>>> complex = bcp.ChemicalComplex(
...     species=['TF_protein', 'DNA_promoter'],
...     name='TF_bound'
... )

Create an enzyme-substrate complex:

>>> complex = bcp.ChemicalComplex(
...     species=['protein_E', 'S'],
...     name='ES_complex'
... )

Use with a mixture and binding mechanism:

>>> from biocrnpyler.mechanisms import One_Step_Binding
>>> mixture = bcp.Mixture(
...     components=[complex],
...     mechanisms={'binding': One_Step_Binding()},
...     parameters={'kb': 1.0, 'ku': 0.1}
... )
>>> crn = mixture.compile_crn()

__hash__()

Return hash(self).

add_attribute(attribute: str)

Add a single attribute to the component.

Adds an attribute tag to the component’s attribute list and to its associated species object, if one exists. Attributes can be used for mechanism selection, species filtering, and tracking special properties.

Parameters:

attributestr

Attribute string to add to the component. Must be a non-None string value.

Raises:

AssertionError

If attribute is not a string or is None.

Warning

If the component has no internal species to which the attribute can be added.

Notes

Attributes are commonly used to tag components with properties such as:

• Degradation tags (e.g., ‘degtagged’, ‘ssrAtagged’, )

• Functional properties (e.g., ‘fluorescent’, ‘membranebound’)

• Regulatory elements (e.g., ‘inducible’, ‘repressible’)

Examples

Add attributes to tag a protein with special properties:

>>> protein = bcp.Protein('GFP')
>>> protein.add_attribute('fluorescent')
>>> protein.add_attribute('ssrAtagged')
>>> protein.attributes
['fluorescent', 'ssrAtagged']

add_mechanism(mechanism: Mechanism, mech_type=None, overwrite=False, optional_mechanism=False)

Add a mechanism to this component’s mechanism dictionary.

Parameters:

mechanismMechanism

The mechanism object to add.

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 mechanism with the same key. If False, raises ValueError when key already exists.

optional_mechanismbool, default=False

If True, suppresses the ValueError when a mechanism key conflict occurs and overwrite is False.

Raises:

TypeError

If mechanism is not a Mechanism object, or if mech_type is not a string.

ValueError

If mechanism key already exists, overwrite is False, and optional_mechanism is False.

add_mechanisms(mechanisms: Mechanism | GlobalMechanism, overwrite=False, optional_mechanism=False)

Add multiple mechanisms to this component.

Accepts mechanisms as a single object, list, or dictionary and adds them to the component’s mechanism dictionary.

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.

optional_mechanismbool, default=False

If True, suppresses ValueError when mechanism key conflicts occur and overwrite is False.

Raises:

ValueError

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

property compartment

Compartment or None: The compartment containing this component.

enumerate_components(previously_enumerated=None) → List

Enumerate derived components created from this component.

This method generates new components based on the current component, typically used during CRN compilation to expand higher-level components into their constituent parts and products.

Parameters:

previously_enumeratedset or list, optional

Collection of components that have already been enumerated, used to prevent infinite recursion in component enumeration.

Returns:

list

List of new components created from this component. This base implementation returns an empty list.

Notes

Subclasses override this method to implement specific enumeration behavior. For example:

• A DNA_construct returns copies of its parts and RNA_construct objects representing transcripts.

• An RNA_construct returns copies of its parts and Protein components representing translation products.

get_mechanism(mechanism_type, optional_mechanism=False)

Retrieve a mechanism by type from the component or its mixture.

Searches first in the component’s mechanism dictionary, then falls back to the mixture’s mechanisms if not found.

Parameters:

mechanism_typestr

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

optional_mechanismbool, default=False

If True, returns None when mechanism not found. If False, raises KeyError when mechanism not found.

Returns:

Mechanism or None

The requested mechanism object, or None if not found and optional_mechanism is True.

Raises:

TypeError

If mechanism_type is not a string.

KeyError

If mechanism not found and optional_mechanism is False.

get_parameter(param_name: str, part_id=None, mechanism=None, return_numerical=False, return_none=False, check_mixture=True) → Parameter | Real

Retrieve parameter from component or mixture parameter database.

Searches first in the component’s parameter database, then falls back to the mixture’s parameter database if not found.

Parameters:

param_namestr

Name of the parameter to retrieve.

part_idstr, optional

Part identifier for the parameter lookup key.

mechanismstr, optional

Mechanism identifier for the parameter lookup key.

return_numericalbool, default=False

If True, returns the numerical value. If False, returns the Parameter object.

return_nonebool, default=False

If True, returns None when parameter not found. If False, raises ValueError when parameter not found.

check_mixturebool, default=True

If True, searches the mixture’s parameter database if not found in the component’s database.

Returns:

Parameter, Real, or None

The parameter object or its numerical value, or None if not found and return_none is True.

Raises:

ValueError

If parameter not found and return_none is False.

Notes

Parameter lookup follows the hierarchy:

1. Component.parameter_database

2. Component.mixture.parameter_database (if check_mixture is True)

get_species() → List[Species]

Get the complex species.

Returns:

Complex

The complex species object containing all constituent species.

set_attributes(attributes: List[str])

Set multiple attributes for the component.

Adds a list of attribute tags to the component and its associated species by calling add_attribute for each attribute in the list.

Parameters:

attributeslist of str or None

List of attribute strings to add to the component. If None, no action is taken.

See also

add_attribute

Add a single attribute to the component.

Examples

>>> comp = bcp.Protein(name="MyProtein")
>>> comp.set_attributes(["degtagged", "fluorescent"])
>>> comp.attributes
['degtagged', 'fluorescent']

set_mixture(mixture) → None

Set the mixture containing this component.

Parameters:

mixtureMixture or None

The mixture object that contains this component and provides default mechanisms and parameters.

classmethod set_species(species: Species | str, material_type=None, compartment=None, attributes=None) → Species

Convert various inputs into Species objects.

Parameters:

speciesSpecies, str, Component, or list

The species to convert. Can be a Species object (returned as-is), a string (creates new Species), a Component (extracts its species), or a list of any of these types.

material_typestr, optional

Material type for the species (e.g., ‘dna’, ‘rna’, ‘protein’). Only used when creating new Species from strings.

compartmentCompartment, optional

Compartment to assign to the species. 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 or list of Species

The converted Species object(s). Returns a list if input was a list.

Raises:

ValueError

If the input cannot be converted to a valid Species.

update_parameters(parameter_file=None, parameters=None, parameter_database=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).

parameter_databaseParameterDatabase, optional

Another parameter database to merge into component’s database.

overwrite_parametersbool, default=True

If True, new parameter values overwrite existing ones. If False, existing parameters are preserved.

update_reactions() → List[Reaction]

Use ‘binding’ mechanism to generate binding/unbinding reactions.

Uses the ‘binding’ mechanism to generate reactions for complex formation (binding) and dissociation (unbinding).

Returns:

list of Reaction

List of reactions generated by the binding mechanism, typically including forward binding and reverse unbinding reactions.

update_species() → List[Species]

Use ‘binding’ mechanism to generate species for binding reactions.

Uses the ‘binding’ mechanism to generate all species needed for binding and unbinding reactions, including the individual species and the complex.

Returns:

list of Species

List of all species generated by the binding mechanism, typically including the constituent species and the complex species.

class biocrnpyler.components.basic.DNA(name, length=0, attributes=None, **kwargs)

DNA sequence component with specified length.

A DNA component represents a DNA sequence with a given length in base pairs. This component has no associated mechanism to generate species or reactions, but can be used as a building block for more complex genetic constructs.

Parameters:

namestr

Name of the DNA sequence.

lengthint, default=0

Length of the DNA sequence in base pairs.

attributeslist of str, optional

List of attribute tags to associate with the DNA species.

**kwargs

Additional keyword arguments passed to the Component base class constructor.

Attributes:

speciesSpecies

The DNA species object with material_type=’dna’.

See also

RNA

RNA sequence component.

Protein

Protein sequence component.

Component

Base class for biomolecular components.

Examples

Create a simple DNA sequence:

>>> dna = bcp.DNA(name='my_gene', length=1000)
>>> dna.get_species()
dna_my_gene

Create DNA with attributes:

>>> promoter = bcp.DNA(
...     name='pLac',
...     length=100,
...     attributes=['inducible', 'strong']
... )

__hash__()

Return hash(self).

add_attribute(attribute: str)

Add a single attribute to the component.

Adds an attribute tag to the component’s attribute list and to its associated species object, if one exists. Attributes can be used for mechanism selection, species filtering, and tracking special properties.

Parameters:

attributestr

Attribute string to add to the component. Must be a non-None string value.

Raises:

AssertionError

If attribute is not a string or is None.

Warning

If the component has no internal species to which the attribute can be added.

Notes

Attributes are commonly used to tag components with properties such as:

• Degradation tags (e.g., ‘degtagged’, ‘ssrAtagged’, )

• Functional properties (e.g., ‘fluorescent’, ‘membranebound’)

• Regulatory elements (e.g., ‘inducible’, ‘repressible’)

Examples

Add attributes to tag a protein with special properties:

>>> protein = bcp.Protein('GFP')
>>> protein.add_attribute('fluorescent')
>>> protein.add_attribute('ssrAtagged')
>>> protein.attributes
['fluorescent', 'ssrAtagged']

add_mechanism(mechanism: Mechanism, mech_type=None, overwrite=False, optional_mechanism=False)

Add a mechanism to this component’s mechanism dictionary.

Parameters:

mechanismMechanism

The mechanism object to add.

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 mechanism with the same key. If False, raises ValueError when key already exists.

optional_mechanismbool, default=False

If True, suppresses the ValueError when a mechanism key conflict occurs and overwrite is False.

Raises:

TypeError

If mechanism is not a Mechanism object, or if mech_type is not a string.

ValueError

If mechanism key already exists, overwrite is False, and optional_mechanism is False.

add_mechanisms(mechanisms: Mechanism | GlobalMechanism, overwrite=False, optional_mechanism=False)

Add multiple mechanisms to this component.

Accepts mechanisms as a single object, list, or dictionary and adds them to the component’s mechanism dictionary.

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.

optional_mechanismbool, default=False

If True, suppresses ValueError when mechanism key conflicts occur and overwrite is False.

Raises:

ValueError

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

property compartment

Compartment or None: The compartment containing this component.

enumerate_components(previously_enumerated=None) → List

Enumerate derived components created from this component.

This method generates new components based on the current component, typically used during CRN compilation to expand higher-level components into their constituent parts and products.

Parameters:

previously_enumeratedset or list, optional

Collection of components that have already been enumerated, used to prevent infinite recursion in component enumeration.

Returns:

list

List of new components created from this component. This base implementation returns an empty list.

Notes

Subclasses override this method to implement specific enumeration behavior. For example:

• A DNA_construct returns copies of its parts and RNA_construct objects representing transcripts.

• An RNA_construct returns copies of its parts and Protein components representing translation products.

get_mechanism(mechanism_type, optional_mechanism=False)

Retrieve a mechanism by type from the component or its mixture.

Searches first in the component’s mechanism dictionary, then falls back to the mixture’s mechanisms if not found.

Parameters:

mechanism_typestr

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

optional_mechanismbool, default=False

If True, returns None when mechanism not found. If False, raises KeyError when mechanism not found.

Returns:

Mechanism or None

The requested mechanism object, or None if not found and optional_mechanism is True.

Raises:

TypeError

If mechanism_type is not a string.

KeyError

If mechanism not found and optional_mechanism is False.

get_parameter(param_name: str, part_id=None, mechanism=None, return_numerical=False, return_none=False, check_mixture=True) → Parameter | Real

Retrieve parameter from component or mixture parameter database.

Searches first in the component’s parameter database, then falls back to the mixture’s parameter database if not found.

Parameters:

param_namestr

Name of the parameter to retrieve.

part_idstr, optional

Part identifier for the parameter lookup key.

mechanismstr, optional

Mechanism identifier for the parameter lookup key.

return_numericalbool, default=False

If True, returns the numerical value. If False, returns the Parameter object.

return_nonebool, default=False

If True, returns None when parameter not found. If False, raises ValueError when parameter not found.

check_mixturebool, default=True

If True, searches the mixture’s parameter database if not found in the component’s database.

Returns:

Parameter, Real, or None

The parameter object or its numerical value, or None if not found and return_none is True.

Raises:

ValueError

If parameter not found and return_none is False.

Notes

Parameter lookup follows the hierarchy:

1. Component.parameter_database

2. Component.mixture.parameter_database (if check_mixture is True)

get_species() → Species

Get the DNA species.

Returns:

Species

The DNA species object with material_type=’dna’.

set_attributes(attributes: List[str])

Set multiple attributes for the component.

Adds a list of attribute tags to the component and its associated species by calling add_attribute for each attribute in the list.

Parameters:

attributeslist of str or None

List of attribute strings to add to the component. If None, no action is taken.

See also

add_attribute

Add a single attribute to the component.

Examples

>>> comp = bcp.Protein(name="MyProtein")
>>> comp.set_attributes(["degtagged", "fluorescent"])
>>> comp.attributes
['degtagged', 'fluorescent']

set_mixture(mixture) → None

Set the mixture containing this component.

Parameters:

mixtureMixture or None

The mixture object that contains this component and provides default mechanisms and parameters.

classmethod set_species(species: Species | str, material_type=None, compartment=None, attributes=None) → Species

Convert various inputs into Species objects.

Parameters:

speciesSpecies, str, Component, or list

The species to convert. Can be a Species object (returned as-is), a string (creates new Species), a Component (extracts its species), or a list of any of these types.

material_typestr, optional

Material type for the species (e.g., ‘dna’, ‘rna’, ‘protein’). Only used when creating new Species from strings.

compartmentCompartment, optional

Compartment to assign to the species. 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 or list of Species

The converted Species object(s). Returns a list if input was a list.

Raises:

ValueError

If the input cannot be converted to a valid Species.

update_parameters(parameter_file=None, parameters=None, parameter_database=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).

parameter_databaseParameterDatabase, optional

Another parameter database to merge into component’s database.

overwrite_parametersbool, default=True

If True, new parameter values overwrite existing ones. If False, existing parameters are preserved.

update_reactions() → List

Generate reactions associated with the DNA component.

Returns:

list

Empty list, as DNA has no associated mechanism.

update_species() → List[Species]

Generate species associated with the DNA component.

Returns:

list of Species

List containing only the DNA species itself, as DNA has no associated mechanism to produce additional species.

class biocrnpyler.components.basic.Enzyme(enzyme: Species | str | Component, substrates: List[Species | str | Component], products: List[Species | str | Component], attributes=None, **kwargs)

Enzyme that catalyzes conversion of substrates to products.

An Enzyme component represents an enzyme that catalyzes the conversion of one or more substrates into one or more products. The enzyme itself is not consumed in the reaction. This component uses a ‘catalysis’ mechanism to generate the appropriate chemical reactions.

Parameters:

enzymeSpecies, str, or Component

The enzyme species that catalyzes the reaction. Can be a Species object, a string name (creates new protein Species), or a Component with an associated species.

substrateslist of Species, str, or Component

List of substrate species that are consumed by the enzymatic reaction. Each element can be a Species object, string name, or Component.

productslist of Species, str, or Component

List of product species that are produced by the enzymatic reaction. Each element can be a Species object, string name, or Component.

attributeslist of str, optional

List of attribute tags to associate with the enzyme species.

**kwargs

Additional keyword arguments passed to the Component base class constructor.

Attributes:

enzymeSpecies

The enzyme species object.

substrateslist of Species

List of substrate species for the enzymatic reaction.

productslist of Species

List of product species for the enzymatic reaction.

See also

Component

Base class for biomolecular components.

Metabolite

Component for metabolic compounds.

ChemicalComplex

Component for molecular complexes.

Notes

The Enzyme component assumes all substrates are converted to all products in a single enzymatic step:

S1 + S2 + … + SN + E –> P1 + P2 + … + PM + E

For enzymes that catalyze multiple distinct reactions, create separate Enzyme components with the same internal enzyme species.

The component uses a mechanism called ‘catalysis’ which must be provided by the containing mixture. Common catalysis mechanisms include Michaelis-Menten kinetics and other enzymatic rate laws.

Examples

Create a simple enzyme that converts substrate S to product P:

>>> enzyme = bcp.Enzyme(
...     enzyme='E',
...     substrates=['S'],
...     products=['P']
... )
>>> enzyme.get_species()
protein_E

Create an enzyme with multiple substrates and products:

>>> enzyme = bcp.Enzyme(
...     enzyme='Kinase',
...     substrates=['ATP', 'Protein'],
...     products=['ADP', 'Protein_P']
... )

Use with a mixture and Michaelis-Menten mechanism:

>>> from biocrnpyler.mechanisms import MichaelisMenten
>>> mixture = bcp.Mixture(
...     components=[enzyme],
...     mechanisms={'catalysis': MichaelisMenten()},
...     parameters={'kb': 0.1, 'ku': 0.01, 'kcat': 1.0}
... )
>>> crn = mixture.compile_crn()

__hash__()

Return hash(self).

add_attribute(attribute: str)

Add a single attribute to the component.

Adds an attribute tag to the component’s attribute list and to its associated species object, if one exists. Attributes can be used for mechanism selection, species filtering, and tracking special properties.

Parameters:

attributestr

Attribute string to add to the component. Must be a non-None string value.

Raises:

AssertionError

If attribute is not a string or is None.

Warning

If the component has no internal species to which the attribute can be added.

Notes

Attributes are commonly used to tag components with properties such as:

• Degradation tags (e.g., ‘degtagged’, ‘ssrAtagged’, )

• Functional properties (e.g., ‘fluorescent’, ‘membranebound’)

• Regulatory elements (e.g., ‘inducible’, ‘repressible’)

Examples

Add attributes to tag a protein with special properties:

>>> protein = bcp.Protein('GFP')
>>> protein.add_attribute('fluorescent')
>>> protein.add_attribute('ssrAtagged')
>>> protein.attributes
['fluorescent', 'ssrAtagged']

add_mechanism(mechanism: Mechanism, mech_type=None, overwrite=False, optional_mechanism=False)

Add a mechanism to this component’s mechanism dictionary.

Parameters:

mechanismMechanism

The mechanism object to add.

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 mechanism with the same key. If False, raises ValueError when key already exists.

optional_mechanismbool, default=False

If True, suppresses the ValueError when a mechanism key conflict occurs and overwrite is False.

Raises:

TypeError

If mechanism is not a Mechanism object, or if mech_type is not a string.

ValueError

If mechanism key already exists, overwrite is False, and optional_mechanism is False.

add_mechanisms(mechanisms: Mechanism | GlobalMechanism, overwrite=False, optional_mechanism=False)

Add multiple mechanisms to this component.

Accepts mechanisms as a single object, list, or dictionary and adds them to the component’s mechanism dictionary.

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.

optional_mechanismbool, default=False

If True, suppresses ValueError when mechanism key conflicts occur and overwrite is False.

Raises:

ValueError

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

property compartment

Compartment or None: The compartment containing this component.

enumerate_components(previously_enumerated=None) → List

Enumerate derived components created from this component.

This method generates new components based on the current component, typically used during CRN compilation to expand higher-level components into their constituent parts and products.

Parameters:

previously_enumeratedset or list, optional

Collection of components that have already been enumerated, used to prevent infinite recursion in component enumeration.

Returns:

list

List of new components created from this component. This base implementation returns an empty list.

Notes

Subclasses override this method to implement specific enumeration behavior. For example:

• A DNA_construct returns copies of its parts and RNA_construct objects representing transcripts.

• An RNA_construct returns copies of its parts and Protein components representing translation products.

get_mechanism(mechanism_type, optional_mechanism=False)

Retrieve a mechanism by type from the component or its mixture.

Searches first in the component’s mechanism dictionary, then falls back to the mixture’s mechanisms if not found.

Parameters:

mechanism_typestr

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

optional_mechanismbool, default=False

If True, returns None when mechanism not found. If False, raises KeyError when mechanism not found.

Returns:

Mechanism or None

The requested mechanism object, or None if not found and optional_mechanism is True.

Raises:

TypeError

If mechanism_type is not a string.

KeyError

If mechanism not found and optional_mechanism is False.

get_parameter(param_name: str, part_id=None, mechanism=None, return_numerical=False, return_none=False, check_mixture=True) → Parameter | Real

Retrieve parameter from component or mixture parameter database.

Searches first in the component’s parameter database, then falls back to the mixture’s parameter database if not found.

Parameters:

param_namestr

Name of the parameter to retrieve.

part_idstr, optional

Part identifier for the parameter lookup key.

mechanismstr, optional

Mechanism identifier for the parameter lookup key.

return_numericalbool, default=False

If True, returns the numerical value. If False, returns the Parameter object.

return_nonebool, default=False

If True, returns None when parameter not found. If False, raises ValueError when parameter not found.

check_mixturebool, default=True

If True, searches the mixture’s parameter database if not found in the component’s database.

Returns:

Parameter, Real, or None

The parameter object or its numerical value, or None if not found and return_none is True.

Raises:

ValueError

If parameter not found and return_none is False.

Notes

Parameter lookup follows the hierarchy:

1. Component.parameter_database

2. Component.mixture.parameter_database (if check_mixture is True)

get_species() → Species

Get the enzyme species.

Returns:

Species

The enzyme species object that catalyzes the reaction.

property products: List

List of product species for the enzymatic reaction.

Returns:

list of Species

set_attributes(attributes: List[str])

Set multiple attributes for the component.

Adds a list of attribute tags to the component and its associated species by calling add_attribute for each attribute in the list.

Parameters:

attributeslist of str or None

List of attribute strings to add to the component. If None, no action is taken.

See also

add_attribute

Add a single attribute to the component.

Examples

>>> comp = bcp.Protein(name="MyProtein")
>>> comp.set_attributes(["degtagged", "fluorescent"])
>>> comp.attributes
['degtagged', 'fluorescent']

set_mixture(mixture) → None

Set the mixture containing this component.

Parameters:

mixtureMixture or None

The mixture object that contains this component and provides default mechanisms and parameters.

classmethod set_species(species: Species | str, material_type=None, compartment=None, attributes=None) → Species

Convert various inputs into Species objects.

Parameters:

speciesSpecies, str, Component, or list

The species to convert. Can be a Species object (returned as-is), a string (creates new Species), a Component (extracts its species), or a list of any of these types.

material_typestr, optional

Material type for the species (e.g., ‘dna’, ‘rna’, ‘protein’). Only used when creating new Species from strings.

compartmentCompartment, optional

Compartment to assign to the species. 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 or list of Species

The converted Species object(s). Returns a list if input was a list.

Raises:

ValueError

If the input cannot be converted to a valid Species.

property substrates: List

List of substrate species for the enzymatic reaction.

Returns:

list of Species

update_parameters(parameter_file=None, parameters=None, parameter_database=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).

parameter_databaseParameterDatabase, optional

Another parameter database to merge into component’s database.

overwrite_parametersbool, default=True

If True, new parameter values overwrite existing ones. If False, existing parameters are preserved.

update_reactions() → List[Reaction]

Use ‘catalysis’ mechanism to generate enzymatic reactions.

Uses the ‘catalysis’ mechanism to generate all reactions needed for the enzymatic conversion of substrates to products.

Returns:

list of Reaction

List of all reactions generated by the catalysis mechanism, typically including substrate binding, catalysis, and product release steps.

update_species() → List[Species]

Use ‘catalysis’ mechanism to generate enzymatic species.

Uses the ‘catalysis’ mechanism to generate all species needed for the enzymatic reaction, including enzyme, substrates, products, and any intermediate complexes.

Returns:

list of Species

List of all species generated by the catalysis mechanism, typically including enzyme, substrates, products, and enzyme-substrate complexes.

class biocrnpyler.components.basic.Metabolite(name: str, attributes=None, precursors=None, products=None, **kwargs)

Metabolic compound that can be produced, utilized, or degraded.

A Metabolite component represents a metabolic compound that participates in biochemical pathways. It can have precursors (species that are converted into this metabolite) and products (species that this metabolite is converted into). The component uses a ‘metabolic_pathway’ mechanism to generate production and degradation reactions.

Parameters:

namestr

Name of the metabolite.

attributeslist of str, optional

List of attribute tags to associate with the metabolite species.

precursorslist of Species, str, Component, or None, optional

List of chemical species that are directly transformed into this metabolite via the production mechanism. None represents constitutive production (production from nothing).

productslist of Species, str, Component, or None, optional

List of chemical species produced from this metabolite via the degradation mechanism. None represents total degradation (degradation to nothing).

**kwargs

Additional keyword arguments passed to the Component base class constructor.

Attributes:

speciesSpecies

The metabolite species object with material_type=’metabolite’.

precursorslist of Species or None

List of precursor species. None values represent constitutive production.

productslist of Species or None

List of product species. None values represent total degradation.

See also

Enzyme

Enzymatic component for catalysis.

Component

Base class for biomolecular components.

Notes

The Metabolite component looks for a ‘metabolic_pathway’ mechanism but will not throw an error if it is not found. If the mechanism is present:

• Production reactions are generated from precursors to the metabolite

• Degradation reactions are generated from the metabolite to products

None is a valid precursor/product representing constitutive production/degradation.

Examples

Create a metabolite with constitutive production and degradation:

>>> atp = bcp.Metabolite(
...     name='ATP',
...     precursors=[None],
...     products=[None]
... )

Create a metabolite with specific precursor and product:

>>> adp = bcp.Metabolite(
...     name='ADP',
...     precursors=['ATP'],
...     products=['AMP']
... )

Use with a mixture and metabolic pathway mechanism:

>>> from biocrnpyler.mechanisms import OneStepPathway
>>> mixture = bcp.Mixture(
...     components=[atp],
...     mechanisms={'metabolic_pathway': OneStepPathway()},
...     parameters={'k': 0.1}
... )
>>> crn = mixture.compile_crn()

__hash__()

Return hash(self).

add_attribute(attribute: str)

Add a single attribute to the component.

Adds an attribute tag to the component’s attribute list and to its associated species object, if one exists. Attributes can be used for mechanism selection, species filtering, and tracking special properties.

Parameters:

attributestr

Attribute string to add to the component. Must be a non-None string value.

Raises:

AssertionError

If attribute is not a string or is None.

Warning

If the component has no internal species to which the attribute can be added.

Notes

Attributes are commonly used to tag components with properties such as:

• Degradation tags (e.g., ‘degtagged’, ‘ssrAtagged’, )

• Functional properties (e.g., ‘fluorescent’, ‘membranebound’)

• Regulatory elements (e.g., ‘inducible’, ‘repressible’)

Examples

Add attributes to tag a protein with special properties:

>>> protein = bcp.Protein('GFP')
>>> protein.add_attribute('fluorescent')
>>> protein.add_attribute('ssrAtagged')
>>> protein.attributes
['fluorescent', 'ssrAtagged']

add_mechanism(mechanism: Mechanism, mech_type=None, overwrite=False, optional_mechanism=False)

Add a mechanism to this component’s mechanism dictionary.

Parameters:

mechanismMechanism

The mechanism object to add.

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 mechanism with the same key. If False, raises ValueError when key already exists.

optional_mechanismbool, default=False

If True, suppresses the ValueError when a mechanism key conflict occurs and overwrite is False.

Raises:

TypeError

If mechanism is not a Mechanism object, or if mech_type is not a string.

ValueError

If mechanism key already exists, overwrite is False, and optional_mechanism is False.

add_mechanisms(mechanisms: Mechanism | GlobalMechanism, overwrite=False, optional_mechanism=False)

Add multiple mechanisms to this component.

Accepts mechanisms as a single object, list, or dictionary and adds them to the component’s mechanism dictionary.

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.

optional_mechanismbool, default=False

If True, suppresses ValueError when mechanism key conflicts occur and overwrite is False.

Raises:

ValueError

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

property compartment

Compartment or None: The compartment containing this component.

enumerate_components(previously_enumerated=None) → List

Enumerate derived components created from this component.

This method generates new components based on the current component, typically used during CRN compilation to expand higher-level components into their constituent parts and products.

Parameters:

previously_enumeratedset or list, optional

Collection of components that have already been enumerated, used to prevent infinite recursion in component enumeration.

Returns:

list

List of new components created from this component. This base implementation returns an empty list.

Notes

Subclasses override this method to implement specific enumeration behavior. For example:

• A DNA_construct returns copies of its parts and RNA_construct objects representing transcripts.

• An RNA_construct returns copies of its parts and Protein components representing translation products.

get_mechanism(mechanism_type, optional_mechanism=False)

Retrieve a mechanism by type from the component or its mixture.

Searches first in the component’s mechanism dictionary, then falls back to the mixture’s mechanisms if not found.

Parameters:

mechanism_typestr

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

optional_mechanismbool, default=False

If True, returns None when mechanism not found. If False, raises KeyError when mechanism not found.

Returns:

Mechanism or None

The requested mechanism object, or None if not found and optional_mechanism is True.

Raises:

TypeError

If mechanism_type is not a string.

KeyError

If mechanism not found and optional_mechanism is False.

get_parameter(param_name: str, part_id=None, mechanism=None, return_numerical=False, return_none=False, check_mixture=True) → Parameter | Real

Retrieve parameter from component or mixture parameter database.

Searches first in the component’s parameter database, then falls back to the mixture’s parameter database if not found.

Parameters:

param_namestr

Name of the parameter to retrieve.

part_idstr, optional

Part identifier for the parameter lookup key.

mechanismstr, optional

Mechanism identifier for the parameter lookup key.

return_numericalbool, default=False

If True, returns the numerical value. If False, returns the Parameter object.

return_nonebool, default=False

If True, returns None when parameter not found. If False, raises ValueError when parameter not found.

check_mixturebool, default=True

If True, searches the mixture’s parameter database if not found in the component’s database.

Returns:

Parameter, Real, or None

The parameter object or its numerical value, or None if not found and return_none is True.

Raises:

ValueError

If parameter not found and return_none is False.

Notes

Parameter lookup follows the hierarchy:

1. Component.parameter_database

2. Component.mixture.parameter_database (if check_mixture is True)

get_species() → Species

Get the metabolite species.

Returns:

Species

The metabolite species object with material_type=’metabolite’.

set_attributes(attributes: List[str])

Set multiple attributes for the component.

Adds a list of attribute tags to the component and its associated species by calling add_attribute for each attribute in the list.

Parameters:

attributeslist of str or None

List of attribute strings to add to the component. If None, no action is taken.

See also

add_attribute

Add a single attribute to the component.

Examples

>>> comp = bcp.Protein(name="MyProtein")
>>> comp.set_attributes(["degtagged", "fluorescent"])
>>> comp.attributes
['degtagged', 'fluorescent']

set_mixture(mixture) → None

Set the mixture containing this component.

Parameters:

mixtureMixture or None

The mixture object that contains this component and provides default mechanisms and parameters.

classmethod set_species(species: Species | str, material_type=None, compartment=None, attributes=None) → Species

Convert various inputs into Species objects.

Parameters:

speciesSpecies, str, Component, or list

The species to convert. Can be a Species object (returned as-is), a string (creates new Species), a Component (extracts its species), or a list of any of these types.

material_typestr, optional

Material type for the species (e.g., ‘dna’, ‘rna’, ‘protein’). Only used when creating new Species from strings.

compartmentCompartment, optional

Compartment to assign to the species. 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 or list of Species

The converted Species object(s). Returns a list if input was a list.

Raises:

ValueError

If the input cannot be converted to a valid Species.

update_parameters(parameter_file=None, parameters=None, parameter_database=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).

parameter_databaseParameterDatabase, optional

Another parameter database to merge into component’s database.

overwrite_parametersbool, default=True

If True, new parameter values overwrite existing ones. If False, existing parameters are preserved.

update_reactions() → List

Use ‘metabolic_pathway’ mechanism to generate reactions.

Uses the ‘metabolic_pathway’ mechanism (if present) to generate production reactions (from precursors to metabolite) and degradation reactions (from metabolite to products).

Returns:

list of Reaction

List of reactions including production and degradation pathways. If no mechanism is present, returns an empty list.

update_species() → List[Species]

Use ‘metabolic_pathway’ mechanism to generate species.

Uses the ‘metabolic_pathway’ mechanism (if present) to generate species for production reactions (from precursors to metabolite) and degradation reactions (from metabolite to products).

Returns:

list of Species

List of species including the metabolite itself and any additional species generated by the ‘metabolic_pathway’ mechanism. If no mechanism is present, returns only the metabolite species.

class biocrnpyler.components.basic.Protein(name: str, length=0, attributes=None, **kwargs)

Protein component with specified length.

A Protein component represents a protein or peptide with a given length in amino acids. This component has no associated mechanism to generate species or reactions, but can be used to represent enzymes, transcription factors, structural proteins, or any other protein molecules.

Parameters:

namestr

Name of the protein.

lengthint, default=0

Length of the protein in number of amino acids.

attributeslist of str, optional

List of attribute tags to associate with the protein species. Common attributes include degradation tags (e.g., ‘ssrAtagged’) or functional properties (e.g., ‘fluorescent’).

**kwargs

Additional keyword arguments passed to the Component base class constructor.

Attributes:

speciesSpecies

The protein species object with material_type=’protein’.

See also

DNA

DNA sequence component.

RNA

RNA sequence component.

Enzyme

Enzymatic protein component.

Component

Base class for biomolecular components.

Examples

Create a simple protein:

>>> protein = bcp.Protein(name='GFP', length=238)
>>> protein.get_species()
protein_GFP

Create a protein with degradation tag:

>>> protein = bcp.Protein(
...     name='LacI',
...     length=360,
...     attributes=['ssrAtagged']
... )

__hash__()

Return hash(self).

add_attribute(attribute: str)

Add a single attribute to the component.

Adds an attribute tag to the component’s attribute list and to its associated species object, if one exists. Attributes can be used for mechanism selection, species filtering, and tracking special properties.

Parameters:

attributestr

Attribute string to add to the component. Must be a non-None string value.

Raises:

AssertionError

If attribute is not a string or is None.

Warning

If the component has no internal species to which the attribute can be added.

Notes

Attributes are commonly used to tag components with properties such as:

• Degradation tags (e.g., ‘degtagged’, ‘ssrAtagged’, )

• Functional properties (e.g., ‘fluorescent’, ‘membranebound’)

• Regulatory elements (e.g., ‘inducible’, ‘repressible’)

Examples

Add attributes to tag a protein with special properties:

>>> protein = bcp.Protein('GFP')
>>> protein.add_attribute('fluorescent')
>>> protein.add_attribute('ssrAtagged')
>>> protein.attributes
['fluorescent', 'ssrAtagged']

add_mechanism(mechanism: Mechanism, mech_type=None, overwrite=False, optional_mechanism=False)

Add a mechanism to this component’s mechanism dictionary.

Parameters:

mechanismMechanism

The mechanism object to add.

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 mechanism with the same key. If False, raises ValueError when key already exists.

optional_mechanismbool, default=False

If True, suppresses the ValueError when a mechanism key conflict occurs and overwrite is False.

Raises:

TypeError

If mechanism is not a Mechanism object, or if mech_type is not a string.

ValueError

If mechanism key already exists, overwrite is False, and optional_mechanism is False.

add_mechanisms(mechanisms: Mechanism | GlobalMechanism, overwrite=False, optional_mechanism=False)

Add multiple mechanisms to this component.

Accepts mechanisms as a single object, list, or dictionary and adds them to the component’s mechanism dictionary.

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.

optional_mechanismbool, default=False

If True, suppresses ValueError when mechanism key conflicts occur and overwrite is False.

Raises:

ValueError

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

property compartment

Compartment or None: The compartment containing this component.

enumerate_components(previously_enumerated=None) → List

Enumerate derived components created from this component.

This method generates new components based on the current component, typically used during CRN compilation to expand higher-level components into their constituent parts and products.

Parameters:

previously_enumeratedset or list, optional

Collection of components that have already been enumerated, used to prevent infinite recursion in component enumeration.

Returns:

list

List of new components created from this component. This base implementation returns an empty list.

Notes

Subclasses override this method to implement specific enumeration behavior. For example:

• A DNA_construct returns copies of its parts and RNA_construct objects representing transcripts.

• An RNA_construct returns copies of its parts and Protein components representing translation products.

get_mechanism(mechanism_type, optional_mechanism=False)

Retrieve a mechanism by type from the component or its mixture.

Searches first in the component’s mechanism dictionary, then falls back to the mixture’s mechanisms if not found.

Parameters:

mechanism_typestr

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

optional_mechanismbool, default=False

If True, returns None when mechanism not found. If False, raises KeyError when mechanism not found.

Returns:

Mechanism or None

The requested mechanism object, or None if not found and optional_mechanism is True.

Raises:

TypeError

If mechanism_type is not a string.

KeyError

If mechanism not found and optional_mechanism is False.

get_parameter(param_name: str, part_id=None, mechanism=None, return_numerical=False, return_none=False, check_mixture=True) → Parameter | Real

Retrieve parameter from component or mixture parameter database.

Searches first in the component’s parameter database, then falls back to the mixture’s parameter database if not found.

Parameters:

param_namestr

Name of the parameter to retrieve.

part_idstr, optional

Part identifier for the parameter lookup key.

mechanismstr, optional

Mechanism identifier for the parameter lookup key.

return_numericalbool, default=False

If True, returns the numerical value. If False, returns the Parameter object.

return_nonebool, default=False

If True, returns None when parameter not found. If False, raises ValueError when parameter not found.

check_mixturebool, default=True

If True, searches the mixture’s parameter database if not found in the component’s database.

Returns:

Parameter, Real, or None

The parameter object or its numerical value, or None if not found and return_none is True.

Raises:

ValueError

If parameter not found and return_none is False.

Notes

Parameter lookup follows the hierarchy:

1. Component.parameter_database

2. Component.mixture.parameter_database (if check_mixture is True)

get_species() → Species

Get the protein species.

Returns:

Species

The protein species object with material_type=’protein’.

set_attributes(attributes: List[str])

Set multiple attributes for the component.

Adds a list of attribute tags to the component and its associated species by calling add_attribute for each attribute in the list.

Parameters:

attributeslist of str or None

List of attribute strings to add to the component. If None, no action is taken.

See also

add_attribute

Add a single attribute to the component.

Examples

>>> comp = bcp.Protein(name="MyProtein")
>>> comp.set_attributes(["degtagged", "fluorescent"])
>>> comp.attributes
['degtagged', 'fluorescent']

set_mixture(mixture) → None

Set the mixture containing this component.

Parameters:

mixtureMixture or None

The mixture object that contains this component and provides default mechanisms and parameters.

classmethod set_species(species: Species | str, material_type=None, compartment=None, attributes=None) → Species

Convert various inputs into Species objects.

Parameters:

speciesSpecies, str, Component, or list

The species to convert. Can be a Species object (returned as-is), a string (creates new Species), a Component (extracts its species), or a list of any of these types.

material_typestr, optional

Material type for the species (e.g., ‘dna’, ‘rna’, ‘protein’). Only used when creating new Species from strings.

compartmentCompartment, optional

Compartment to assign to the species. 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 or list of Species

The converted Species object(s). Returns a list if input was a list.

Raises:

ValueError

If the input cannot be converted to a valid Species.

update_parameters(parameter_file=None, parameters=None, parameter_database=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).

parameter_databaseParameterDatabase, optional

Another parameter database to merge into component’s database.

overwrite_parametersbool, default=True

If True, new parameter values overwrite existing ones. If False, existing parameters are preserved.

update_reactions() → List

Generate reactions associated with the protein component.

Returns:

list

Empty list, as Protein has no associated mechanism.

update_species() → List[Species]

Generate species associated with the protein component.

Returns:

list of Species

List containing only the protein species itself, as Protein has no associated mechanism to produce additional species.

class biocrnpyler.components.basic.RNA(name: str, length=0, attributes=None, **kwargs)

RNA sequence component with specified length.

An RNA component represents an RNA sequence with a given length in base pairs. This component has no associated mechanism to generate species or reactions, but can be used to represent mRNA, tRNA, rRNA, or other RNA molecules.

Parameters:

namestr

Name of the RNA sequence.

lengthint, default=0

Length of the RNA sequence in base pairs.

attributeslist of str, optional

List of attribute tags to associate with the RNA species.

**kwargs

Additional keyword arguments passed to the Component base class constructor.

Attributes:

speciesSpecies

The RNA species object with material_type=’rna’.

See also

DNA

DNA sequence component.

Protein

Protein sequence component.

Component

Base class for biomolecular components.

Examples

Create a simple RNA sequence:

>>> rna = bcp.RNA(name='my_transcript', length=500)
>>> rna.get_species()
rna_my_transcript

Create mRNA with attributes:

>>> mrna = bcp.RNA(
...     name='gfp_mrna',
...     length=750,
...     attributes=['coding', 'stable']
... )

__hash__()

Return hash(self).

add_attribute(attribute: str)

Add a single attribute to the component.

Adds an attribute tag to the component’s attribute list and to its associated species object, if one exists. Attributes can be used for mechanism selection, species filtering, and tracking special properties.

Parameters:

attributestr

Attribute string to add to the component. Must be a non-None string value.

Raises:

AssertionError

If attribute is not a string or is None.

Warning

If the component has no internal species to which the attribute can be added.

Notes

Attributes are commonly used to tag components with properties such as:

• Degradation tags (e.g., ‘degtagged’, ‘ssrAtagged’, )

• Functional properties (e.g., ‘fluorescent’, ‘membranebound’)

• Regulatory elements (e.g., ‘inducible’, ‘repressible’)

Examples

Add attributes to tag a protein with special properties:

>>> protein = bcp.Protein('GFP')
>>> protein.add_attribute('fluorescent')
>>> protein.add_attribute('ssrAtagged')
>>> protein.attributes
['fluorescent', 'ssrAtagged']

add_mechanism(mechanism: Mechanism, mech_type=None, overwrite=False, optional_mechanism=False)

Add a mechanism to this component’s mechanism dictionary.

Parameters:

mechanismMechanism

The mechanism object to add.

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 mechanism with the same key. If False, raises ValueError when key already exists.

optional_mechanismbool, default=False

If True, suppresses the ValueError when a mechanism key conflict occurs and overwrite is False.

Raises:

TypeError

If mechanism is not a Mechanism object, or if mech_type is not a string.

ValueError

If mechanism key already exists, overwrite is False, and optional_mechanism is False.

add_mechanisms(mechanisms: Mechanism | GlobalMechanism, overwrite=False, optional_mechanism=False)

Add multiple mechanisms to this component.

Accepts mechanisms as a single object, list, or dictionary and adds them to the component’s mechanism dictionary.

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.

optional_mechanismbool, default=False

If True, suppresses ValueError when mechanism key conflicts occur and overwrite is False.

Raises:

ValueError

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

property compartment

Compartment or None: The compartment containing this component.

enumerate_components(previously_enumerated=None) → List

Enumerate derived components created from this component.

This method generates new components based on the current component, typically used during CRN compilation to expand higher-level components into their constituent parts and products.

Parameters:

previously_enumeratedset or list, optional

Collection of components that have already been enumerated, used to prevent infinite recursion in component enumeration.

Returns:

list

List of new components created from this component. This base implementation returns an empty list.

Notes

Subclasses override this method to implement specific enumeration behavior. For example:

• A DNA_construct returns copies of its parts and RNA_construct objects representing transcripts.

• An RNA_construct returns copies of its parts and Protein components representing translation products.

get_mechanism(mechanism_type, optional_mechanism=False)

Retrieve a mechanism by type from the component or its mixture.

Searches first in the component’s mechanism dictionary, then falls back to the mixture’s mechanisms if not found.

Parameters:

mechanism_typestr

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

optional_mechanismbool, default=False

If True, returns None when mechanism not found. If False, raises KeyError when mechanism not found.

Returns:

Mechanism or None

The requested mechanism object, or None if not found and optional_mechanism is True.

Raises:

TypeError

If mechanism_type is not a string.

KeyError

If mechanism not found and optional_mechanism is False.

get_parameter(param_name: str, part_id=None, mechanism=None, return_numerical=False, return_none=False, check_mixture=True) → Parameter | Real

Retrieve parameter from component or mixture parameter database.

Searches first in the component’s parameter database, then falls back to the mixture’s parameter database if not found.

Parameters:

param_namestr

Name of the parameter to retrieve.

part_idstr, optional

Part identifier for the parameter lookup key.

mechanismstr, optional

Mechanism identifier for the parameter lookup key.

return_numericalbool, default=False

If True, returns the numerical value. If False, returns the Parameter object.

return_nonebool, default=False

If True, returns None when parameter not found. If False, raises ValueError when parameter not found.

check_mixturebool, default=True

If True, searches the mixture’s parameter database if not found in the component’s database.

Returns:

Parameter, Real, or None

The parameter object or its numerical value, or None if not found and return_none is True.

Raises:

ValueError

If parameter not found and return_none is False.

Notes

Parameter lookup follows the hierarchy:

1. Component.parameter_database

2. Component.mixture.parameter_database (if check_mixture is True)

get_species() → Species

Get the RNA species.

Returns:

Species

The RNA species object with material_type=’rna’.

set_attributes(attributes: List[str])

Set multiple attributes for the component.

Adds a list of attribute tags to the component and its associated species by calling add_attribute for each attribute in the list.

Parameters:

attributeslist of str or None

List of attribute strings to add to the component. If None, no action is taken.

See also

add_attribute

Add a single attribute to the component.

Examples

>>> comp = bcp.Protein(name="MyProtein")
>>> comp.set_attributes(["degtagged", "fluorescent"])
>>> comp.attributes
['degtagged', 'fluorescent']

set_mixture(mixture) → None

Set the mixture containing this component.

Parameters:

mixtureMixture or None

The mixture object that contains this component and provides default mechanisms and parameters.

classmethod set_species(species: Species | str, material_type=None, compartment=None, attributes=None) → Species

Convert various inputs into Species objects.

Parameters:

speciesSpecies, str, Component, or list

The species to convert. Can be a Species object (returned as-is), a string (creates new Species), a Component (extracts its species), or a list of any of these types.

material_typestr, optional

Material type for the species (e.g., ‘dna’, ‘rna’, ‘protein’). Only used when creating new Species from strings.

compartmentCompartment, optional

Compartment to assign to the species. 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 or list of Species

The converted Species object(s). Returns a list if input was a list.

Raises:

ValueError

If the input cannot be converted to a valid Species.

update_parameters(parameter_file=None, parameters=None, parameter_database=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).

parameter_databaseParameterDatabase, optional

Another parameter database to merge into component’s database.

overwrite_parametersbool, default=True

If True, new parameter values overwrite existing ones. If False, existing parameters are preserved.

update_reactions() → List

Generate reactions associated with the RNA component.

Returns:

list

Empty list, as RNA has no associated mechanism.

update_species() → List[Species]

Generate species associated with the RNA component.

Returns:

list of Species

List containing only the RNA species itself, as RNA has not associated mechanism to produce additional species.