biocrnpyler.components.dna.promoter

Classes

ActivatablePromoter(name, activator[, ...])	Promoter with Hill function-based activation.
CombinatorialPromoter(name, regulators[, ...])	Promoter with combinatorial regulatory logic.
Promoter(name[, assembly, transcript, ...])	Basic promoter component for constitutive transcription.
RegulatedPromoter(name, regulators[, leak, ...])	Promoter with simple independent regulatory binding.
RepressiblePromoter(name, repressor[, ...])	Promoter with Hill function-based repression.

class biocrnpyler.components.dna.promoter.ActivatablePromoter(name, activator, transcript=None, leak=False, **kwargs)

Promoter with Hill function-based activation.

An activatable promoter models transcriptional activation by a single regulator species using Hill function kinetics. The component uses a ‘transcription’ mechanism (PositiveHillTranscription) to generate species and reactions where the transcription rate increases with activator concentration following cooperative binding dynamics.

Parameters:

namestr

Name of the promoter.

activatorSpecies or str

The activator protein species that enhances transcription.

transcriptRNA or str, optional

The RNA transcript produced by this promoter.

leakbool, default=False

If True, allows basal transcription without activator. If False, no transcription occurs without activator binding.

**kwargs

Additional keyword arguments passed to parent Promoter class.

Attributes:

activatorSpecies

The activator protein that enhances transcription.

leakbool

Whether basal (leak) transcription is allowed.

See also

RepressiblePromoter

Hill function-based repression.

RegulatedPromoter

Independent regulator binding.

PositiveHillTranscription

Mechanism for Hill activation.

Notes

The activation follows a Hill function:

\[\text{rate} = k_{\text{max}} \frac{[A]^n}{K_d^n + [A]^n} + k_{\text{leak}}\]

where [A] is activator concentration, n is the Hill coefficient, and \(K_d\) is the dissociation constant.

Examples

Create an activatable promoter:

>>> promoter = bcp.ActivatablePromoter(
...     name='p_ara',
...     activator='protein_AraC',
...     leak=True
... )

__eq__(other)

Test equality between two DNA_parts.

Parts are equal if they have the same type, name, parent assembly/ construct, direction, and position.

Parameters:

otherDNA_part

The other part to compare with.

Returns:

bool

True if parts are equal, False otherwise.

Notes

Equality requires matching:

1. Type (both must be the same DNA_part subclass)

2. Name (identical names)

3. Assembly/parent (same parent construct or both have None)

4. Direction (both forward or both reverse)

5. Position (same position in parent construct)

Parts are considered equal even if their parent constructs are different objects, as long as the string representations of the parents match.

__hash__()

Compute hash value for this monomer.

Returns:

int

Hash value based on position, direction, name (if present), and parent.

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.

clone(position, direction, parent_dna)

Attach this part to a specific position in a DNA construct.

Parameters:

positionint

Position in the parent DNA where this part should be placed.

directionstr

Orientation of the part: ‘forward’ or ‘reverse’.

parent_dnaDNA_construct or OrderedPolymer

The DNA construct that will contain this part.

Returns:

DNA_part

Returns self after setting position and parent.

Notes

This method establishes the relationship between a part and its containing construct, setting the part’s position and orientation.

property compartment

Compartment or None: The compartment containing this component.

property dna_species

Species: The chemical species representation of this DNA part.

Returns a Species object with material_type=’part’ representing this DNA_part as a chemical species in the CRN.

property dna_to_bind

Species or None: DNA species used as transcription template.

If not explicitly set, defaults to the assembly’s DNA species.

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.

find_polymer_component()

Find the polymer component within this monomer or its species.

Searches this monomer and, if it is a ComplexSpecies, its constituent species to find which one is marked as a polymer component.

Returns:

OrderedMonomer or None

The monomer that is part of a polymer structure, or None if no polymer component is found.

Raises:

ValueError

If multiple species are marked as polymer components in the same location.

Notes

This method is primarily used internally to handle complex species that may contain monomers as part of larger structures.

classmethod from_promoter(name, assembly, transcript, protein)

Create a promoter instance from another promoter or string.

Factory method for creating promoters from various input types.

Parameters:

namePromoter or str

Either a string name for a new promoter, or an existing Promoter object to copy.

assemblyDNAassembly

The assembly containing this promoter.

transcriptRNA or str

The RNA transcript produced by this promoter.

proteinProtein, str, or list

The protein product(s) for expression mixtures.

Returns:

Promoter

A new Promoter instance. If name is a Promoter, returns a deep copy with updated assembly, transcript, and protein attributes.

Raises:

TypeError

If name is neither a string nor a Promoter.

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_orphan()

Create a copy of this monomer without a parent reference.

Returns a copy that retains position and direction but has no parent polymer. Useful for temporarily working with monomers outside their polymer context.

Returns:

OrderedMonomer

A copy of this monomer with parent set to None but position and direction preserved.

See also

get_removed

Create a fully detached copy.

remove

Remove this monomer from its parent in place.

Notes

This is a shallow copy of the monomer object itself, though the parent reference is explicitly cleared.

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_protein_for_expression()

Get protein product for expression mixtures.

In expression mixtures, transcription may be bypassed and translation may occur directly from DNA. This method returns the protein product when the gene is expressed.

Returns:

list of Species or None

The protein product(s) if transcript is None, otherwise None.

Notes

This is used by expression mixtures where the transcript species is omitted and translation occurs directly.

get_removed()

Create a fully detached copy of this monomer.

Returns a copy with all polymer-related attributes (parent, position, direction) cleared. Also removes ‘forward’ and ‘reverse’ attributes if present.

Returns:

OrderedMonomer

A copy of this monomer with no parent, position, or direction, and with directional attributes removed.

See also

get_orphan

Create a copy without parent but with position and direction.

remove

Remove this monomer from its parent in place.

Notes

This method is useful for creating completely independent copies of monomers that can be reused in different contexts without any polymer associations.

get_species()

Get the primary species associated with this promoter.

Returns:

None

Promoters do not have a primary species; they are part of a DNA assembly.

monomer_insert(parent: OrderedPolymer, position: int, direction=None)

Insert this monomer into a polymer at a specific position.

Sets the monomer’s parent, position, and direction attributes to reflect its insertion into the polymer. Marks the monomer (or its polymer component if it is a complex species) as a polymer component.

Parameters:

parentOrderedPolymer

The polymer to insert this monomer into.

positionint

The position index where this monomer is being inserted.

directionstr, int, or None, optional

The direction for this monomer. If None, uses the monomer’s existing direction.

Raises:

ValueError

If position is None, or if parent is None.

remove()

Remove this monomer from its parent polymer.

Clears the monomer’s parent, position, and direction attributes, effectively detaching it from any polymer structure.

Returns:

OrderedMonomer

Returns self for method chaining.

See also

get_removed

Create a fully detached copy of the monomer.

get_orphan

Create a copy with parent removed but position and direction preserved.

reverse()

Reverse the orientation of this DNA part.

Flips the direction of the part between ‘forward’ and ‘reverse’.

Returns:

DNA_part

Returns self after reversing direction.

Notes

This method is typically called when a containing construct is reversed, ensuring all parts maintain proper relative orientation.

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_dir(direction)

Set the direction of the monomer and return self.

Convenience method for setting direction in a fluent interface style.

Parameters:

directionstr, int, or None

The direction to assign to this monomer.

Returns:

OrderedMonomer

Returns self for method chaining.

Examples

>>> monomer = bcp.OrderedMonomer().set_dir('forward')
>>> monomer.direction
'forward'

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.

subhash()

Compute hash contribution from monomer properties.

Computes a hash value based on the monomer’s position, direction, and name (if present), excluding the parent reference.

Returns:

int

Hash value based on monomer-specific properties.

Notes

This method is used by __hash__ to compute the monomer’s hash contribution. It excludes the parent to avoid circular dependencies in hash computation.

unclone()

Remove this part from its parent construct.

Detaches the part from any parent construct or assembly, resetting its position and parent references.

Returns:

DNA_part

Returns self after removal from parent.

See also

clone

Attach the part to a construct at a specific position.

Notes

This method calls the remove method from the OrderedMonomer base class to detach the part from its parent polymer structure.

After calling this method, the part becomes “orphaned” and can be attached to a different construct using clone.

update_component(internal_species=None, **kwargs)

Create a copy of the promoter with updated DNA binding target.

Used for component enumeration when promoters are part of larger constructs that need to be duplicated with different species.

Parameters:

internal_speciesSpecies, optional

The new DNA species to use as the binding target.

**kwargs

Additional keyword arguments (currently unused).

Returns:

Promoter or None

A shallow copy of this promoter with the updated dna_to_bind attribute. Returns None if parent is RNA.

Raises:

TypeError

If parent is neither DNA nor RNA construct.

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

Use ‘transcription’ mechanism to generate activation reactions.

Parameters:

**kwargs

Additional keyword arguments passed to the transcription mechanism.

Returns:

list of Reaction

List of reactions for Hill-based transcriptional activation.

update_species(**kwargs)

Use ‘transcription’ mechanism to generate activation species.

Parameters:

**kwargs

Additional keyword arguments passed to the transcription mechanism.

Returns:

list of Species

List of species generated by the transcription mechanism for Hill-based activation.

class biocrnpyler.components.dna.promoter.CombinatorialPromoter(name, regulators, leak=False, assembly=None, transcript=None, length=0, mechanisms=None, parameters=None, protein=None, tx_capable_list=None, cooperativity=None, **kwargs)

Promoter with combinatorial regulatory logic.

A combinatorial promoter allows multiple regulators to bind cooperatively, where transcription behavior depends on the specific combination of bound regulators. The component uses the ‘binding’ mechanism (Combinatorial_Cooperative_Binding) to generate all possible DNA-regulator complexes and the ‘transcription’ mechanism to generate reactions for each regulatory state. This enables complex logic gates (AND, OR, NOR, etc.) and multi-input regulatory functions.

Parameters:

namestr

Name of the promoter.

regulatorsSpecies, str, or list

List of regulator species that can bind to the promoter. Regulators can bind in various combinations.

leakbool, default=False

If True, allows transcription from promoter states not in tx_capable_list (including unbound state). If False, only states in tx_capable_list transcribe.

assemblyDNAassembly, optional

The assembly containing this promoter.

transcriptRNA or str, optional

The RNA transcript produced by this promoter.

lengthint, default=0

Length of the promoter in base pairs.

mechanismsdict or list, optional

Custom mechanisms for this promoter.

parametersdict, optional

Parameter values specific to this promoter.

proteinProtein, str, list, or None, optional

Protein product(s) for expression mixtures.

tx_capable_listlist of list, optional

List specifying which combinations of bound regulators enable transcription. Each element is a list of regulator names (strings or Species). If None, all combinations enable transcription.

cooperativitydict, optional

Dictionary mapping regulator names to their cooperativity values (Hill coefficients) for binding, e.g., {‘regulator1’: 2, ‘regulator2’: 1}.

**kwargs

Additional keyword arguments passed to parent class.

Attributes:

regulatorslist of Species

Sorted list of protein regulators (sorted for consistency).

cooperativitydict or None

Cooperativity values for each regulator.

tx_capable_listlist of set

List of regulator combinations (as sets) that enable transcription.

leakbool

Whether leak transcription is allowed for non-capable states.

complex_combinationsdict

Dictionary mapping combinations to their DNA-regulator complexes.

tx_capable_complexeslist of Species

List of DNA complexes that can transcribe.

leak_complexeslist of Species

List of DNA complexes that transcribe with leak parameters.

See also

RegulatedPromoter

Independent regulatory binding.

Combinatorial_Cooperative_Binding

Binding mechanism used by this promoter.

Notes

Only combinations in tx_capable_list transcribe with full rate; others transcribe with leak rate (if leak is True) or not at all.

Regulators are automatically sorted alphabetically to ensure consistent ordering when checking combinations.

Examples

Create an AND gate promoter (transcribes only when both bound):

>>> promoter = bcp.CombinatorialPromoter(
...     name='p_and',
...     regulators=['TF1', 'TF2'],
...     tx_capable_list=[['TF1', 'TF2']],
...     leak=False
... )

Create an OR gate promoter (transcribes when either is bound):

>>> promoter = bcp.CombinatorialPromoter(
...     name='p_or',
...     regulators=['TF1', 'TF2'],
...     tx_capable_list=[['TF1'], ['TF2'], ['TF1', 'TF2']],
...     leak=False
... )

Create a promoter with cooperative binding:

>>> promoter = bcp.CombinatorialPromoter(
...     name='p_coop',
...     regulators=['TF1', 'TF2'],
...     cooperativity={'TF1': 2, 'TF2': 1},
...     tx_capable_list=[['TF1', 'TF2']]
... )

__eq__(other)

Test equality between two DNA_parts.

Parts are equal if they have the same type, name, parent assembly/ construct, direction, and position.

Parameters:

otherDNA_part

The other part to compare with.

Returns:

bool

True if parts are equal, False otherwise.

Notes

Equality requires matching:

1. Type (both must be the same DNA_part subclass)

2. Name (identical names)

3. Assembly/parent (same parent construct or both have None)

4. Direction (both forward or both reverse)

5. Position (same position in parent construct)

Parts are considered equal even if their parent constructs are different objects, as long as the string representations of the parents match.

__hash__()

Compute hash value for this monomer.

Returns:

int

Hash value based on position, direction, name (if present), and parent.

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.

clone(position, direction, parent_dna)

Attach this part to a specific position in a DNA construct.

Parameters:

positionint

Position in the parent DNA where this part should be placed.

directionstr

Orientation of the part: ‘forward’ or ‘reverse’.

parent_dnaDNA_construct or OrderedPolymer

The DNA construct that will contain this part.

Returns:

DNA_part

Returns self after setting position and parent.

Notes

This method establishes the relationship between a part and its containing construct, setting the part’s position and orientation.

property compartment

Compartment or None: The compartment containing this component.

property dna_species

Species: The chemical species representation of this DNA part.

Returns a Species object with material_type=’part’ representing this DNA_part as a chemical species in the CRN.

property dna_to_bind

Species or None: DNA species used as transcription template.

If not explicitly set, defaults to the assembly’s DNA species.

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.

find_polymer_component()

Find the polymer component within this monomer or its species.

Searches this monomer and, if it is a ComplexSpecies, its constituent species to find which one is marked as a polymer component.

Returns:

OrderedMonomer or None

The monomer that is part of a polymer structure, or None if no polymer component is found.

Raises:

ValueError

If multiple species are marked as polymer components in the same location.

Notes

This method is primarily used internally to handle complex species that may contain monomers as part of larger structures.

classmethod from_promoter(name, assembly, transcript, protein)

Create a promoter instance from another promoter or string.

Factory method for creating promoters from various input types.

Parameters:

namePromoter or str

Either a string name for a new promoter, or an existing Promoter object to copy.

assemblyDNAassembly

The assembly containing this promoter.

transcriptRNA or str

The RNA transcript produced by this promoter.

proteinProtein, str, or list

The protein product(s) for expression mixtures.

Returns:

Promoter

A new Promoter instance. If name is a Promoter, returns a deep copy with updated assembly, transcript, and protein attributes.

Raises:

TypeError

If name is neither a string nor a Promoter.

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_orphan()

Create a copy of this monomer without a parent reference.

Returns a copy that retains position and direction but has no parent polymer. Useful for temporarily working with monomers outside their polymer context.

Returns:

OrderedMonomer

A copy of this monomer with parent set to None but position and direction preserved.

See also

get_removed

Create a fully detached copy.

remove

Remove this monomer from its parent in place.

Notes

This is a shallow copy of the monomer object itself, though the parent reference is explicitly cleared.

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_protein_for_expression()

Get protein product for expression mixtures.

In expression mixtures, transcription may be bypassed and translation may occur directly from DNA. This method returns the protein product when the gene is expressed.

Returns:

list of Species or None

The protein product(s) if transcript is None, otherwise None.

Notes

This is used by expression mixtures where the transcript species is omitted and translation occurs directly.

get_removed()

Create a fully detached copy of this monomer.

Returns a copy with all polymer-related attributes (parent, position, direction) cleared. Also removes ‘forward’ and ‘reverse’ attributes if present.

Returns:

OrderedMonomer

A copy of this monomer with no parent, position, or direction, and with directional attributes removed.

See also

get_orphan

Create a copy without parent but with position and direction.

remove

Remove this monomer from its parent in place.

Notes

This method is useful for creating completely independent copies of monomers that can be reused in different contexts without any polymer associations.

get_species()

Get the primary species associated with this promoter.

Returns:

None

Promoters do not have a primary species; they are part of a DNA assembly.

monomer_insert(parent: OrderedPolymer, position: int, direction=None)

Insert this monomer into a polymer at a specific position.

Sets the monomer’s parent, position, and direction attributes to reflect its insertion into the polymer. Marks the monomer (or its polymer component if it is a complex species) as a polymer component.

Parameters:

parentOrderedPolymer

The polymer to insert this monomer into.

positionint

The position index where this monomer is being inserted.

directionstr, int, or None, optional

The direction for this monomer. If None, uses the monomer’s existing direction.

Raises:

ValueError

If position is None, or if parent is None.

remove()

Remove this monomer from its parent polymer.

Clears the monomer’s parent, position, and direction attributes, effectively detaching it from any polymer structure.

Returns:

OrderedMonomer

Returns self for method chaining.

See also

get_removed

Create a fully detached copy of the monomer.

get_orphan

Create a copy with parent removed but position and direction preserved.

reverse()

Reverse the orientation of this DNA part.

Flips the direction of the part between ‘forward’ and ‘reverse’.

Returns:

DNA_part

Returns self after reversing direction.

Notes

This method is typically called when a containing construct is reversed, ensuring all parts maintain proper relative orientation.

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_dir(direction)

Set the direction of the monomer and return self.

Convenience method for setting direction in a fluent interface style.

Parameters:

directionstr, int, or None

The direction to assign to this monomer.

Returns:

OrderedMonomer

Returns self for method chaining.

Examples

>>> monomer = bcp.OrderedMonomer().set_dir('forward')
>>> monomer.direction
'forward'

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.

subhash()

Compute hash contribution from monomer properties.

Computes a hash value based on the monomer’s position, direction, and name (if present), excluding the parent reference.

Returns:

int

Hash value based on monomer-specific properties.

Notes

This method is used by __hash__ to compute the monomer’s hash contribution. It excludes the parent to avoid circular dependencies in hash computation.

unclone()

Remove this part from its parent construct.

Detaches the part from any parent construct or assembly, resetting its position and parent references.

Returns:

DNA_part

Returns self after removal from parent.

See also

clone

Attach the part to a construct at a specific position.

Notes

This method calls the remove method from the OrderedMonomer base class to detach the part from its parent polymer structure.

After calling this method, the part becomes “orphaned” and can be attached to a different construct using clone.

update_component(internal_species=None, **kwargs)

Create a copy of the promoter with updated DNA binding target.

Used for component enumeration when promoters are part of larger constructs that need to be duplicated with different species.

Parameters:

internal_speciesSpecies, optional

The new DNA species to use as the binding target.

**kwargs

Additional keyword arguments (currently unused).

Returns:

Promoter or None

A shallow copy of this promoter with the updated dna_to_bind attribute. Returns None if parent is RNA.

Raises:

TypeError

If parent is neither DNA nor RNA construct.

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

Generate reactions for combinatorial regulatory logic.

Uses the ‘transcription’ and ‘binding’ mechanisms to generate binding reactions for all regulator combinations and transcription reactions for capable and leak complexes.

Returns:

list of Reaction

List containing:

• Cooperative binding reactions for all regulator combinations

• Transcription reactions from unbound DNA (if leak is True)

• Transcription reactions from capable complexes

• Transcription reactions from leak complexes (if leak is True)

Warns:

UserWarning

If no complexes can transcribe after calling update_species.

Notes

This method automatically calls update_species if the complex lists are empty, ensuring that species generation occurs before reaction generation.

Each transcription reaction uses a unique part_id that identifies the regulatory state, constructed from the promoter name and bound regulators (e.g., ‘p_name_TF1_TF2_RNAP’).

update_species()

Generate species for combinatorial regulatory logic.

Uses the ‘transcription’ and ‘binding’ mechanisms to generate all possible DNA-regulator complexes through cooperative binding and identifies which complexes enable transcription based on tx_capable_list.

Returns:

list of Species

List containing:

• The unbound DNA

• All regulator species

• All DNA-regulator binding complexes

• Transcription-related species for capable complexes

• Transcription-related species for leak complexes (if leak is True)

Notes

The method classifies DNA-regulator complexes into two categories:

• tx_capable_complexes: Complexes that match combinations in tx_capable_list and transcribe with full rate parameters

• leak_complexes: Complexes not in tx_capable_list that transcribe with leak parameters (if leak is True)

Complexes are stored in these attributes for use by update_reactions.

class biocrnpyler.components.dna.promoter.Promoter(name, assembly=None, transcript=None, length=0, mechanisms=None, parameters=None, protein=None, dna_to_bind=None, **kwargs)

Basic promoter component for constitutive transcription.

A promoter represents a DNA regulatory element that controls transcription of an RNA transcript. This base class implements constitutive (unregulated) transcription. The component uses the ‘transcription’ mechanism to generate species and reactions during CRN compilation. The promoter must be included in a DNAassembly or DNA_construct to function properly.

Parameters:

namestr

Name of the promoter.

assemblyDNAassembly, optional

The DNA assembly containing this promoter. If provided, the assembly’s name is used to create the default transcript.

transcriptRNA, str, or None, optional

The RNA transcript produced by this promoter. If None and assembly is provided, creates an RNA species using the assembly’s name. Can be a list of transcripts for multi-cistronic operons.

lengthint, default=0

Length of the promoter sequence in base pairs.

mechanismsdict or list, optional

Custom mechanisms for this promoter, overriding mixture defaults.

parametersdict, optional

Parameter values specific to this promoter.

proteinProtein, str, list, or None, optional

Protein product(s) for expression mixtures where transcription is bypassed. Can be a single protein, list of proteins, or None.

dna_to_bindDNA or Species, optional

The DNA species that serves as the transcription template. If None, uses the assembly’s DNA when available.

**kwargs

Additional keyword arguments passed to the parent DNA_part class.

Attributes:

transcriptSpecies, list of Species, or None

The RNA transcript(s) produced by transcription.

proteinlist of Species or None

Protein product(s) for expression systems.

lengthint

Length of the promoter in base pairs.

dna_to_bindSpecies or None

Species or None: DNA species used as transcription template.

See also

RegulatedPromoter

Promoter with independent regulator binding.

ActivatablePromoter

Promoter with Hill function activation.

RepressiblePromoter

Promoter with Hill function repression.

CombinatorialPromoter

Promoter with combinatorial regulation.

DNAassembly

Container for promoters and genetic constructs.

Notes

Promoters cannot have initial concentrations set directly. Initial conditions must be set on the containing DNAassembly or DNA_construct.

Examples

Create a basic constitutive promoter:

>>> promoter = bcp.Promoter(
...     name='pconst',
...     transcript='mRNA_gfp'
... )

Create a promoter within an assembly:

>>> assembly = bcp.DNAassembly(name='gene_x')
>>> promoter = bcp.Promoter(
...     name='p_lac',
...     assembly=assembly
... )

__eq__(other)

Test equality between two DNA_parts.

Parts are equal if they have the same type, name, parent assembly/ construct, direction, and position.

Parameters:

otherDNA_part

The other part to compare with.

Returns:

bool

True if parts are equal, False otherwise.

Notes

Equality requires matching:

1. Type (both must be the same DNA_part subclass)

2. Name (identical names)

3. Assembly/parent (same parent construct or both have None)

4. Direction (both forward or both reverse)

5. Position (same position in parent construct)

Parts are considered equal even if their parent constructs are different objects, as long as the string representations of the parents match.

__hash__()

Compute hash value for this monomer.

Returns:

int

Hash value based on position, direction, name (if present), and parent.

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.

clone(position, direction, parent_dna)

Attach this part to a specific position in a DNA construct.

Parameters:

positionint

Position in the parent DNA where this part should be placed.

directionstr

Orientation of the part: ‘forward’ or ‘reverse’.

parent_dnaDNA_construct or OrderedPolymer

The DNA construct that will contain this part.

Returns:

DNA_part

Returns self after setting position and parent.

Notes

This method establishes the relationship between a part and its containing construct, setting the part’s position and orientation.

property compartment

Compartment or None: The compartment containing this component.

property dna_species

Species: The chemical species representation of this DNA part.

Returns a Species object with material_type=’part’ representing this DNA_part as a chemical species in the CRN.

property dna_to_bind

Species or None: DNA species used as transcription template.

If not explicitly set, defaults to the assembly’s DNA species.

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.

find_polymer_component()

Find the polymer component within this monomer or its species.

Searches this monomer and, if it is a ComplexSpecies, its constituent species to find which one is marked as a polymer component.

Returns:

OrderedMonomer or None

The monomer that is part of a polymer structure, or None if no polymer component is found.

Raises:

ValueError

If multiple species are marked as polymer components in the same location.

Notes

This method is primarily used internally to handle complex species that may contain monomers as part of larger structures.

classmethod from_promoter(name, assembly, transcript, protein)

Create a promoter instance from another promoter or string.

Factory method for creating promoters from various input types.

Parameters:

namePromoter or str

Either a string name for a new promoter, or an existing Promoter object to copy.

assemblyDNAassembly

The assembly containing this promoter.

transcriptRNA or str

The RNA transcript produced by this promoter.

proteinProtein, str, or list

The protein product(s) for expression mixtures.

Returns:

Promoter

A new Promoter instance. If name is a Promoter, returns a deep copy with updated assembly, transcript, and protein attributes.

Raises:

TypeError

If name is neither a string nor a Promoter.

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_orphan()

Create a copy of this monomer without a parent reference.

Returns a copy that retains position and direction but has no parent polymer. Useful for temporarily working with monomers outside their polymer context.

Returns:

OrderedMonomer

A copy of this monomer with parent set to None but position and direction preserved.

See also

get_removed

Create a fully detached copy.

remove

Remove this monomer from its parent in place.

Notes

This is a shallow copy of the monomer object itself, though the parent reference is explicitly cleared.

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_protein_for_expression()

Get protein product for expression mixtures.

In expression mixtures, transcription may be bypassed and translation may occur directly from DNA. This method returns the protein product when the gene is expressed.

Returns:

list of Species or None

The protein product(s) if transcript is None, otherwise None.

Notes

This is used by expression mixtures where the transcript species is omitted and translation occurs directly.

get_removed()

Create a fully detached copy of this monomer.

Returns a copy with all polymer-related attributes (parent, position, direction) cleared. Also removes ‘forward’ and ‘reverse’ attributes if present.

Returns:

OrderedMonomer

A copy of this monomer with no parent, position, or direction, and with directional attributes removed.

See also

get_orphan

Create a copy without parent but with position and direction.

remove

Remove this monomer from its parent in place.

Notes

This method is useful for creating completely independent copies of monomers that can be reused in different contexts without any polymer associations.

get_species()

Get the primary species associated with this promoter.

Returns:

None

Promoters do not have a primary species; they are part of a DNA assembly.

monomer_insert(parent: OrderedPolymer, position: int, direction=None)

Insert this monomer into a polymer at a specific position.

Sets the monomer’s parent, position, and direction attributes to reflect its insertion into the polymer. Marks the monomer (or its polymer component if it is a complex species) as a polymer component.

Parameters:

parentOrderedPolymer

The polymer to insert this monomer into.

positionint

The position index where this monomer is being inserted.

directionstr, int, or None, optional

The direction for this monomer. If None, uses the monomer’s existing direction.

Raises:

ValueError

If position is None, or if parent is None.

remove()

Remove this monomer from its parent polymer.

Clears the monomer’s parent, position, and direction attributes, effectively detaching it from any polymer structure.

Returns:

OrderedMonomer

Returns self for method chaining.

See also

get_removed

Create a fully detached copy of the monomer.

get_orphan

Create a copy with parent removed but position and direction preserved.

reverse()

Reverse the orientation of this DNA part.

Flips the direction of the part between ‘forward’ and ‘reverse’.

Returns:

DNA_part

Returns self after reversing direction.

Notes

This method is typically called when a containing construct is reversed, ensuring all parts maintain proper relative orientation.

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_dir(direction)

Set the direction of the monomer and return self.

Convenience method for setting direction in a fluent interface style.

Parameters:

directionstr, int, or None

The direction to assign to this monomer.

Returns:

OrderedMonomer

Returns self for method chaining.

Examples

>>> monomer = bcp.OrderedMonomer().set_dir('forward')
>>> monomer.direction
'forward'

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.

subhash()

Compute hash contribution from monomer properties.

Computes a hash value based on the monomer’s position, direction, and name (if present), excluding the parent reference.

Returns:

int

Hash value based on monomer-specific properties.

Notes

This method is used by __hash__ to compute the monomer’s hash contribution. It excludes the parent to avoid circular dependencies in hash computation.

unclone()

Remove this part from its parent construct.

Detaches the part from any parent construct or assembly, resetting its position and parent references.

Returns:

DNA_part

Returns self after removal from parent.

See also

clone

Attach the part to a construct at a specific position.

Notes

This method calls the remove method from the OrderedMonomer base class to detach the part from its parent polymer structure.

After calling this method, the part becomes “orphaned” and can be attached to a different construct using clone.

update_component(internal_species=None, **kwargs)

Create a copy of the promoter with updated DNA binding target.

Used for component enumeration when promoters are part of larger constructs that need to be duplicated with different species.

Parameters:

internal_speciesSpecies, optional

The new DNA species to use as the binding target.

**kwargs

Additional keyword arguments (currently unused).

Returns:

Promoter or None

A shallow copy of this promoter with the updated dna_to_bind attribute. Returns None if parent is RNA.

Raises:

TypeError

If parent is neither DNA nor RNA construct.

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

Generate reactions associated with this promoter.

Calls the ‘transcription’ mechanism to generate reactions for constitutive transcription from the DNA template.

Returns:

list of Reaction

List of reactions generated by the transcription mechanism, including RNA polymerase binding and transcript production.

update_species()

Generate species associated with this promoter.

Calls the transcription mechanism to generate species for constitutive transcription from the DNA template.

Returns:

list of Species

List of species generated by the transcription mechanism, including RNA polymerase-DNA complexes and transcripts.

class biocrnpyler.components.dna.promoter.RegulatedPromoter(name: str, regulators, leak=True, assembly=None, transcript=None, length=0, mechanisms=None, parameters=None, **kwargs)

Promoter with simple independent regulatory binding.

A regulated promoter allows multiple regulatory proteins (activators or repressors) to bind independently to the promoter DNA. Each regulator binds independently, and transcription can occur from both bound and unbound states with different rates. The component uses the ‘binding’ mechanism (One_Step_Cooperative_Binding by default) to generate DNA-regulator complexes and the ‘transcription’ mechanism to generate transcription reactions from each regulatory state.

Parameters:

namestr

Name of the promoter.

regulatorsSpecies, str, or list

Regulator species that bind to the promoter. Can be a single regulator or a list. Each regulator binds independently.

leakbool, default=True

If True, allows transcription from the unbound promoter state (leak expression). If False, only bound states transcribe.

assemblyDNAassembly, optional

The assembly containing this promoter.

transcriptRNA or str, optional

The RNA transcript produced by this promoter.

lengthint, default=0

Length of the promoter in base pairs.

mechanismsdict or list, optional

Custom mechanisms for this promoter.

parametersdict, optional

Parameter values specific to this promoter.

**kwargs

Additional keyword arguments passed to parent class.

Attributes:

regulatorslist of Species

List of protein species that regulate this promoter.

leakbool

Whether leak transcription (from unbound state) is allowed.

complexeslist of Species

List of DNA-regulator complexes generated during compilation.

See also

Promoter

Base promoter class.

ActivatablePromoter

Hill function-based activation.

RepressiblePromoter

Hill function-based repression.

CombinatorialPromoter

Combinatorial regulation logic.

Notes

Each regulator binds independently, creating multiple DNA-protein complexes. Transcription can occur from each complex with different parameters identified by part_id.

The leak behavior allows modeling of constitutive expression that occurs even without regulator binding.

Examples

Create a promoter with a single regulator:

>>> promoter = bcp.RegulatedPromoter(
...     name='p_reg',
...     regulators='protein_TF',
...     leak=True
... )

Create a promoter with multiple independent regulators:

>>> promoter = bcp.RegulatedPromoter(
...     name='p_multi',
...     regulators=['protein_TF1', 'protein_TF2'],
...     leak=False
... )

__eq__(other)

Test equality between two DNA_parts.

Parts are equal if they have the same type, name, parent assembly/ construct, direction, and position.

Parameters:

otherDNA_part

The other part to compare with.

Returns:

bool

True if parts are equal, False otherwise.

Notes

Equality requires matching:

1. Type (both must be the same DNA_part subclass)

2. Name (identical names)

3. Assembly/parent (same parent construct or both have None)

4. Direction (both forward or both reverse)

5. Position (same position in parent construct)

Parts are considered equal even if their parent constructs are different objects, as long as the string representations of the parents match.

__hash__()

Compute hash value for this monomer.

Returns:

int

Hash value based on position, direction, name (if present), and parent.

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.

clone(position, direction, parent_dna)

Attach this part to a specific position in a DNA construct.

Parameters:

positionint

Position in the parent DNA where this part should be placed.

directionstr

Orientation of the part: ‘forward’ or ‘reverse’.

parent_dnaDNA_construct or OrderedPolymer

The DNA construct that will contain this part.

Returns:

DNA_part

Returns self after setting position and parent.

Notes

This method establishes the relationship between a part and its containing construct, setting the part’s position and orientation.

property compartment

Compartment or None: The compartment containing this component.

property dna_species

Species: The chemical species representation of this DNA part.

Returns a Species object with material_type=’part’ representing this DNA_part as a chemical species in the CRN.

property dna_to_bind

Species or None: DNA species used as transcription template.

If not explicitly set, defaults to the assembly’s DNA species.

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.

find_polymer_component()

Find the polymer component within this monomer or its species.

Searches this monomer and, if it is a ComplexSpecies, its constituent species to find which one is marked as a polymer component.

Returns:

OrderedMonomer or None

The monomer that is part of a polymer structure, or None if no polymer component is found.

Raises:

ValueError

If multiple species are marked as polymer components in the same location.

Notes

This method is primarily used internally to handle complex species that may contain monomers as part of larger structures.

classmethod from_promoter(name, assembly, transcript, protein)

Create a promoter instance from another promoter or string.

Factory method for creating promoters from various input types.

Parameters:

namePromoter or str

Either a string name for a new promoter, or an existing Promoter object to copy.

assemblyDNAassembly

The assembly containing this promoter.

transcriptRNA or str

The RNA transcript produced by this promoter.

proteinProtein, str, or list

The protein product(s) for expression mixtures.

Returns:

Promoter

A new Promoter instance. If name is a Promoter, returns a deep copy with updated assembly, transcript, and protein attributes.

Raises:

TypeError

If name is neither a string nor a Promoter.

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_orphan()

Create a copy of this monomer without a parent reference.

Returns a copy that retains position and direction but has no parent polymer. Useful for temporarily working with monomers outside their polymer context.

Returns:

OrderedMonomer

A copy of this monomer with parent set to None but position and direction preserved.

See also

get_removed

Create a fully detached copy.

remove

Remove this monomer from its parent in place.

Notes

This is a shallow copy of the monomer object itself, though the parent reference is explicitly cleared.

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_protein_for_expression()

Get protein product for expression mixtures.

In expression mixtures, transcription may be bypassed and translation may occur directly from DNA. This method returns the protein product when the gene is expressed.

Returns:

list of Species or None

The protein product(s) if transcript is None, otherwise None.

Notes

This is used by expression mixtures where the transcript species is omitted and translation occurs directly.

get_removed()

Create a fully detached copy of this monomer.

Returns a copy with all polymer-related attributes (parent, position, direction) cleared. Also removes ‘forward’ and ‘reverse’ attributes if present.

Returns:

OrderedMonomer

A copy of this monomer with no parent, position, or direction, and with directional attributes removed.

See also

get_orphan

Create a copy without parent but with position and direction.

remove

Remove this monomer from its parent in place.

Notes

This method is useful for creating completely independent copies of monomers that can be reused in different contexts without any polymer associations.

get_species()

Get the primary species associated with this promoter.

Returns:

None

Promoters do not have a primary species; they are part of a DNA assembly.

monomer_insert(parent: OrderedPolymer, position: int, direction=None)

Insert this monomer into a polymer at a specific position.

Sets the monomer’s parent, position, and direction attributes to reflect its insertion into the polymer. Marks the monomer (or its polymer component if it is a complex species) as a polymer component.

Parameters:

parentOrderedPolymer

The polymer to insert this monomer into.

positionint

The position index where this monomer is being inserted.

directionstr, int, or None, optional

The direction for this monomer. If None, uses the monomer’s existing direction.

Raises:

ValueError

If position is None, or if parent is None.

remove()

Remove this monomer from its parent polymer.

Clears the monomer’s parent, position, and direction attributes, effectively detaching it from any polymer structure.

Returns:

OrderedMonomer

Returns self for method chaining.

See also

get_removed

Create a fully detached copy of the monomer.

get_orphan

Create a copy with parent removed but position and direction preserved.

reverse()

Reverse the orientation of this DNA part.

Flips the direction of the part between ‘forward’ and ‘reverse’.

Returns:

DNA_part

Returns self after reversing direction.

Notes

This method is typically called when a containing construct is reversed, ensuring all parts maintain proper relative orientation.

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_dir(direction)

Set the direction of the monomer and return self.

Convenience method for setting direction in a fluent interface style.

Parameters:

directionstr, int, or None

The direction to assign to this monomer.

Returns:

OrderedMonomer

Returns self for method chaining.

Examples

>>> monomer = bcp.OrderedMonomer().set_dir('forward')
>>> monomer.direction
'forward'

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.

subhash()

Compute hash contribution from monomer properties.

Computes a hash value based on the monomer’s position, direction, and name (if present), excluding the parent reference.

Returns:

int

Hash value based on monomer-specific properties.

Notes

This method is used by __hash__ to compute the monomer’s hash contribution. It excludes the parent to avoid circular dependencies in hash computation.

unclone()

Remove this part from its parent construct.

Detaches the part from any parent construct or assembly, resetting its position and parent references.

Returns:

DNA_part

Returns self after removal from parent.

See also

clone

Attach the part to a construct at a specific position.

Notes

This method calls the remove method from the OrderedMonomer base class to detach the part from its parent polymer structure.

After calling this method, the part becomes “orphaned” and can be attached to a different construct using clone.

update_component(internal_species=None, **kwargs)

Create a copy of the promoter with updated DNA binding target.

Used for component enumeration when promoters are part of larger constructs that need to be duplicated with different species.

Parameters:

internal_speciesSpecies, optional

The new DNA species to use as the binding target.

**kwargs

Additional keyword arguments (currently unused).

Returns:

Promoter or None

A shallow copy of this promoter with the updated dna_to_bind attribute. Returns None if parent is RNA.

Raises:

TypeError

If parent is neither DNA nor RNA construct.

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

Generate reactions for regulated transcription.

Uses the ‘binding’ mechanism to generate binding reactions for each regulator and the ‘transcription’ mechanism to generate transcription reactions for each regulatory state (bound and unbound).

Returns:

list of Reaction

List containing all binding reactions for regulators and transcription reactions for each DNA state.

Notes

Reactions are generated for:

• Regulator binding and unbinding to DNA

• Transcription from unbound DNA (if leak is True)

• Transcription from each DNA-regulator complex

update_species()

Generate species for regulated transcription.

Uses the ‘transcription’ and ‘binding’ mechanisms to generate species for regulator-DNA binding and transcription from each regulatory state. Generates DNA-regulator complexes and identifies which complexes can transcribe.

Returns:

list of Species

List containing all DNA-regulator complexes and species generated by the transcription mechanism for each regulatory state.

Notes

The method generates:

• DNA-regulator binding complexes for each regulator

• Transcription-related species for unbound DNA (if leak is True)

• Transcription-related species for each DNA-regulator complex

Complexes are stored in self.complexes for use in update_reactions.

class biocrnpyler.components.dna.promoter.RepressiblePromoter(name, repressor, transcript=None, leak=False, **kwargs)

Promoter with Hill function-based repression.

A repressible promoter models transcriptional repression by a single regulator species using Hill function kinetics. The component uses a ‘transcription’ mechanism (NegativeHillTranscription) to generate species and reactions where the transcription rate decreases with repressor concentration following cooperative binding dynamics.

Parameters:

namestr

Name of the promoter.

repressorSpecies or str

The repressor protein species that inhibits transcription.

transcriptRNA or str, optional

The RNA transcript produced by this promoter.

leakbool, default=False

If True, allows residual transcription even at high repressor concentrations. If False, transcription is fully repressed.

**kwargs

Additional keyword arguments passed to parent Promoter class.

Attributes:

repressorSpecies

The repressor protein that inhibits transcription.

leakbool

Whether leak transcription at high repressor is allowed.

See also

ActivatablePromoter

Hill function-based activation.

RegulatedPromoter

Independent regulator binding.

NegativeHillTranscription

Mechanism for Hill repression.

Notes

The repression follows a Hill function:

\[\text{rate} = k_{\text{max}} \frac{K_d^n}{K_d^n + [R]^n} + k_{\text{leak}}\]

where [R] is repressor concentration, n is the Hill coefficient, and \(K_d\) is the dissociation constant.

Examples

Create a repressible promoter:

>>> promoter = bcp.RepressiblePromoter(
...     name='p_lac',
...     repressor='protein_LacI',
...     leak=False
... )

__eq__(other)

Test equality between two DNA_parts.

Parts are equal if they have the same type, name, parent assembly/ construct, direction, and position.

Parameters:

otherDNA_part

The other part to compare with.

Returns:

bool

True if parts are equal, False otherwise.

Notes

Equality requires matching:

1. Type (both must be the same DNA_part subclass)

2. Name (identical names)

3. Assembly/parent (same parent construct or both have None)

4. Direction (both forward or both reverse)

5. Position (same position in parent construct)

Parts are considered equal even if their parent constructs are different objects, as long as the string representations of the parents match.

__hash__()

Compute hash value for this monomer.

Returns:

int

Hash value based on position, direction, name (if present), and parent.

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.

clone(position, direction, parent_dna)

Attach this part to a specific position in a DNA construct.

Parameters:

positionint

Position in the parent DNA where this part should be placed.

directionstr

Orientation of the part: ‘forward’ or ‘reverse’.

parent_dnaDNA_construct or OrderedPolymer

The DNA construct that will contain this part.

Returns:

DNA_part

Returns self after setting position and parent.

Notes

This method establishes the relationship between a part and its containing construct, setting the part’s position and orientation.

property compartment

Compartment or None: The compartment containing this component.

property dna_species

Species: The chemical species representation of this DNA part.

Returns a Species object with material_type=’part’ representing this DNA_part as a chemical species in the CRN.

property dna_to_bind

Species or None: DNA species used as transcription template.

If not explicitly set, defaults to the assembly’s DNA species.

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.

find_polymer_component()

Find the polymer component within this monomer or its species.

Searches this monomer and, if it is a ComplexSpecies, its constituent species to find which one is marked as a polymer component.

Returns:

OrderedMonomer or None

The monomer that is part of a polymer structure, or None if no polymer component is found.

Raises:

ValueError

If multiple species are marked as polymer components in the same location.

Notes

This method is primarily used internally to handle complex species that may contain monomers as part of larger structures.

classmethod from_promoter(name, assembly, transcript, protein)

Create a promoter instance from another promoter or string.

Factory method for creating promoters from various input types.

Parameters:

namePromoter or str

Either a string name for a new promoter, or an existing Promoter object to copy.

assemblyDNAassembly

The assembly containing this promoter.

transcriptRNA or str

The RNA transcript produced by this promoter.

proteinProtein, str, or list

The protein product(s) for expression mixtures.

Returns:

Promoter

A new Promoter instance. If name is a Promoter, returns a deep copy with updated assembly, transcript, and protein attributes.

Raises:

TypeError

If name is neither a string nor a Promoter.

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_orphan()

Create a copy of this monomer without a parent reference.

Returns a copy that retains position and direction but has no parent polymer. Useful for temporarily working with monomers outside their polymer context.

Returns:

OrderedMonomer

A copy of this monomer with parent set to None but position and direction preserved.

See also

get_removed

Create a fully detached copy.

remove

Remove this monomer from its parent in place.

Notes

This is a shallow copy of the monomer object itself, though the parent reference is explicitly cleared.

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_protein_for_expression()

Get protein product for expression mixtures.

In expression mixtures, transcription may be bypassed and translation may occur directly from DNA. This method returns the protein product when the gene is expressed.

Returns:

list of Species or None

The protein product(s) if transcript is None, otherwise None.

Notes

This is used by expression mixtures where the transcript species is omitted and translation occurs directly.

get_removed()

Create a fully detached copy of this monomer.

Returns a copy with all polymer-related attributes (parent, position, direction) cleared. Also removes ‘forward’ and ‘reverse’ attributes if present.

Returns:

OrderedMonomer

A copy of this monomer with no parent, position, or direction, and with directional attributes removed.

See also

get_orphan

Create a copy without parent but with position and direction.

remove

Remove this monomer from its parent in place.

Notes

This method is useful for creating completely independent copies of monomers that can be reused in different contexts without any polymer associations.

get_species()

Get the primary species associated with this promoter.

Returns:

None

Promoters do not have a primary species; they are part of a DNA assembly.

monomer_insert(parent: OrderedPolymer, position: int, direction=None)

Insert this monomer into a polymer at a specific position.

Sets the monomer’s parent, position, and direction attributes to reflect its insertion into the polymer. Marks the monomer (or its polymer component if it is a complex species) as a polymer component.

Parameters:

parentOrderedPolymer

The polymer to insert this monomer into.

positionint

The position index where this monomer is being inserted.

directionstr, int, or None, optional

The direction for this monomer. If None, uses the monomer’s existing direction.

Raises:

ValueError

If position is None, or if parent is None.

remove()

Remove this monomer from its parent polymer.

Clears the monomer’s parent, position, and direction attributes, effectively detaching it from any polymer structure.

Returns:

OrderedMonomer

Returns self for method chaining.

See also

get_removed

Create a fully detached copy of the monomer.

get_orphan

Create a copy with parent removed but position and direction preserved.

reverse()

Reverse the orientation of this DNA part.

Flips the direction of the part between ‘forward’ and ‘reverse’.

Returns:

DNA_part

Returns self after reversing direction.

Notes

This method is typically called when a containing construct is reversed, ensuring all parts maintain proper relative orientation.

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_dir(direction)

Set the direction of the monomer and return self.

Convenience method for setting direction in a fluent interface style.

Parameters:

directionstr, int, or None

The direction to assign to this monomer.

Returns:

OrderedMonomer

Returns self for method chaining.

Examples

>>> monomer = bcp.OrderedMonomer().set_dir('forward')
>>> monomer.direction
'forward'

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.

subhash()

Compute hash contribution from monomer properties.

Computes a hash value based on the monomer’s position, direction, and name (if present), excluding the parent reference.

Returns:

int

Hash value based on monomer-specific properties.

Notes

This method is used by __hash__ to compute the monomer’s hash contribution. It excludes the parent to avoid circular dependencies in hash computation.

unclone()

Remove this part from its parent construct.

Detaches the part from any parent construct or assembly, resetting its position and parent references.

Returns:

DNA_part

Returns self after removal from parent.

See also

clone

Attach the part to a construct at a specific position.

Notes

This method calls the remove method from the OrderedMonomer base class to detach the part from its parent polymer structure.

After calling this method, the part becomes “orphaned” and can be attached to a different construct using clone.

update_component(internal_species=None, **kwargs)

Create a copy of the promoter with updated DNA binding target.

Used for component enumeration when promoters are part of larger constructs that need to be duplicated with different species.

Parameters:

internal_speciesSpecies, optional

The new DNA species to use as the binding target.

**kwargs

Additional keyword arguments (currently unused).

Returns:

Promoter or None

A shallow copy of this promoter with the updated dna_to_bind attribute. Returns None if parent is RNA.

Raises:

TypeError

If parent is neither DNA nor RNA construct.

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

Use ‘transcription’ mechanism to generate repression reactions.

Parameters:

**kwargs

Additional keyword arguments passed to the ‘transcription’ mechanism.

Returns:

list of Reaction

List of reactions for Hill-based transcriptional repression.

update_species(**kwargs)

Use ‘transcription’ mechanism to generate repression species.

Parameters:

**kwargs

Additional keyword arguments passed to the transcription mechanism.

Returns:

list of Species

List of species generated by the ‘transcription’ mechanism for Hill-based repression.