biocrnpyler.components.dna.misc

Classes

DNABindingSite(name, binders[, ...])	DNA binding site component for protein-DNA interactions.
IntegraseSite(name[, site_type, integrase, ...])	Integrase attachment site for site-specific recombination.
Operator(name[, binders])	Operator sequence component for visualization.
Origin(name, **kwargs)	Origin of replication component for visualization.
UserDefined(name[, dpl_type])	User-defined DNA part with no intrinsic functionality.

class biocrnpyler.components.dna.misc.DNABindingSite(name, binders, no_stop_codons=None, assembly=None, **kwargs)

DNA binding site component for protein-DNA interactions.

A DNABindingSite represents a specific DNA sequence where proteins can bind. This class models protein-DNA binding interactions using the ‘binding’ mechanism to generate species and reactions during CRN compilation. The binding site can accommodate multiple different binding proteins, each creating separate binding equilibria.

Parameters:

namestr

Name of the DNA binding site.

bindersSpecies, str, or list

Protein species that can bind to this site. Can be a single binder or a list of multiple binders.

no_stop_codonsbool, optional

If True, indicates the sequence has no stop codons (relevant for coding sequences).

assemblyDNAassembly, optional

The DNA assembly containing this binding site.

**kwargs

Additional keyword arguments passed to the parent DNA_part class.

Attributes:

binderslist of Species

List of protein species that can bind to this site.

dna_to_bindSpecies or None

The DNA species that contains this binding site.

mechanismsdict

Dictionary containing the binding mechanism (defaults to One_Step_Cooperative_Binding).

See also

IntegraseSite

Specialized binding site for integrase proteins.

DNA_part

Base class for DNA component parts.

One_Step_Cooperative_Binding

Default binding mechanism used.

Notes

The DNABindingSite uses the ‘binding’ mechanism to generate binding reactions for each protein in the binders list. Each binder creates an independent binding equilibrium with the DNA.

The dna_to_bind attribute is set during component enumeration and represents the actual DNA species containing this binding site.

Examples

Create a binding site for a transcription factor:

>>> binding_site = bcp.DNABindingSite(
...     name='operator_lac',
...     binders='protein_LacI'
... )

Create a binding site with multiple binders:

>>> binding_site = bcp.DNABindingSite(
...     name='enhancer',
...     binders=['protein_TF1', 'protein_TF2', 'protein_TF3']
... )

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

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.

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_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() → None

Get the primary species associated with this component.

Returns:

None

Subclasses should override this method to return their primary Species object.

Notes

This is a placeholder that should be implemented by subclasses.

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 binding site with updated DNA reference.

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

Parameters:

internal_speciesSpecies, optional

The new DNA species to bind to.

**kwargs

Additional keyword arguments (currently unused).

Returns:

DNABindingSite or None

A shallow copy of this binding site with updated dna_to_bind attribute if parent is DNA. Returns None if parent is not DNA.

Notes

This method is called during component enumeration to create copies of binding sites with updated DNA references when DNA constructs are enumerated into their constituent parts.

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

Use ‘binding’ mechanism to generate protein-DNA reactions.

Uses the ‘binding’ mechanism to generate binding and unbinding reactions for each protein binder with the DNA containing this binding site.

Returns:

list of Reaction

List of binding/unbinding reactions for all binders. Returns empty list if dna_to_bind is None.

Notes

This method is called during CRN compilation by Mixture.compile_crn. Each binder generates its own binding equilibrium with unique kinetic parameters identified by part_id.

update_species()

Use ‘binding’ mechanism to generate protein-DNA species.

Uses the ‘binding’ mechanism to generate species for each protein binder and their DNA-protein complexes when bound to the DNA containing this binding site.

Returns:

list of Species

List containing all binder proteins and DNA-protein complexes generated by the binding mechanism. Returns only the binders if dna_to_bind is None.

Notes

This method is called during CRN compilation by Mixture.compile_crn. If dna_to_bind is not set (None), only the binder species are returned without generating complexes.

Each binder generates its own set of binding species with unique part_id identifiers based on the binder’s name.

class biocrnpyler.components.dna.misc.IntegraseSite(name, site_type='attB', integrase='int1', dinucleotide=1, no_stop_codons=None, integrase_binding=True, **kwargs)

Integrase attachment site for site-specific recombination.

An IntegraseSite represents a specialized DNA binding site where integrase proteins can bind and catalyze site-specific recombination. This component uses the ‘binding’ mechanism to model integrase-DNA binding and the ‘integration’ mechanism to generate recombination reactions. The class handles both intramolecular (same DNA molecule) and intermolecular (different DNA molecules) recombination events between compatible attachment sites (attB/attP producing attL/attR, or similar).

Parameters:

namestr

Name of the integrase site.

site_typestr, default=’attB’

Type of attachment site. Common types include ‘attB’, ‘attP’, ‘attL’, ‘attR’, ‘FLP’, ‘CRE’. Determines recombination compatibility.

integrasestr or Species, default=’int1’

The integrase protein that recognizes this site. Can be a string name or Species object.

dinucleotideint, default=1

Specific dinucleotide variant of the attachment site. Different dinucleotides allow orthogonal recombination systems.

no_stop_codonsbool, optional

If True, indicates the sequence has no stop codons.

integrase_bindingbool, default=True

If True, integrase must bind before recombination. If False, recombination occurs without explicit binding (simplified model).

**kwargs

Additional keyword arguments passed to parent class.

Attributes:

integraseSpecies

The integrase protein species that catalyzes recombination.

dinucleotideint

The dinucleotide variant identifier.

site_typestr

The type of attachment site (attB, attP, etc.).

other_dnaSpecies or None

Reference to DNA from another molecule (for intermolecular events).

linked_sitesdict

Dictionary tracking connected recombination partner sites.

complexed_versionSpecies or None

The integrase-bound version of this site.

integrase_bindingbool

Whether explicit integrase binding is modeled.

See also

DNABindingSite

Parent class for general DNA binding sites.

BasicIntegration

Mechanism for integrase-mediated recombination.

One_Step_Cooperative_Binding

Mechanism for integrase binding.

Notes

Integrase sites follow specific recombination rules:

• attB + attP –> attL + attR (integration)

• attL + attR –> attB + attP (excision)

• Compatible sites must have matching integrases and dinucleotides

The linked_sites dictionary maintains connections between compatible recombination partners, enabling the generation of appropriate recombination reactions during CRN compilation.

Recombination can be intramolecular (creating loops or deletions) or intermolecular (joining or exchanging DNA segments between molecules).

Examples

Create a basic attB site for phage integration:

>>> attB = bcp.IntegraseSite(
...     name='attB',
...     site_type='attB',
...     integrase='int_phiC31'
... )

Create orthogonal integration sites with different dinucleotides:

>>> site1 = bcp.IntegraseSite(
...     name='att1',
...     site_type='attB',
...     dinucleotide=1,
...     integrase='int1'
... )
>>> site2 = bcp.IntegraseSite(
...     name='att2',
...     site_type='attB',
...     dinucleotide=2,
...     integrase='int1'
... )

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

Return hash value for the integrase site.

Returns:

int

Combined hash of the parent DNABindingSite and the dna_to_bind species.

Notes

The hash combines the parent class hash with the dna_to_bind hash to ensure unique identification of sites bound to specific DNA.

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.

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.

get_complexed_species(dna)

Create the integrase-bound complex for this site.

Parameters:

dnaSpecies

The DNA species containing this integrase site.

Returns:

Complex

A complex containing the DNA bound by two integrase molecules (dimeric binding typical of integrases).

Notes

Most integrases bind as dimers to catalyze recombination, hence the complex contains two integrase molecules.

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_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() → None

Get the primary species associated with this component.

Returns:

None

Subclasses should override this method to return their primary Species object.

Notes

This is a placeholder that should be implemented by subclasses.

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 integrase site with updated DNA reference.

This method handles the complex task of copying integrase sites during component enumeration, maintaining proper linkages between recombination partner sites.

Parameters:

internal_speciesSpecies, optional

The new DNA species containing this integrase site.

**kwargs

Additional keyword arguments. If ‘practice_run’ is True, performs special handling to preserve initial site linkage configuration.

Returns:

IntegraseSite or None

A copy of this integrase site with updated dna_to_bind and properly managed linked site references. Returns None if the parent DNABindingSite.update_component returns None.

Notes

This method manages the complex bookkeeping required for integrase site recombination:

Practice Run Mode (‘practice_run’=True): During combinatorial enumeration’s practice run, the method preserves the initial configuration of linked sites by updating references in partner sites to point to the newly created copy.

Normal Mode (‘practice_run’=False or not specified):

• For intramolecular reactions: Only populates linked sites if both recombination partners are bound by integrase (or both unbound if integrase_binding is False)

• For intermolecular reactions: Always populates linked sites to enable proper reaction generation

The method ensures that only one site of a recombination pair generates the reaction, preventing duplicate reactions in the CRN.

update_integrase(int_name)

Set or update the integrase protein for this site.

Parameters:

int_namestr or Species

Name of the integrase protein or a Species object.

Notes

Converts the input to a protein Species object and stores it in the integrase attribute.

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

Use ‘binding’ and ‘integration’ mechanisms to generate reactions.

Creates binding reactions (if integrase_binding is True) and recombination reactions with linked partner sites. Handles both intramolecular (same DNA) and intermolecular (different DNA) recombination events.

Returns:

list of Reaction

List containing:

• Integrase binding reactions (if integrase_binding is True)

• Recombination reactions with each linked partner site

Returns empty list if no linked sites exist.

Notes

For each linked partner site, the method determines whether to generate a recombination reaction based on:

1. Intramolecular reactions (same DNA molecule):

   • Only generates reaction if both sites are properly bound (or unbound if integrase_binding is False)

   • Prevents duplicate reactions by checking if complex_parent is already in the linked sites data

   • Creates DNA loops, deletions, or inversions

2. Intermolecular reactions (different DNA molecules):

   • Generates reactions for all DNA molecules listed in linked_sites

   • These DNAs are added by partner sites that were processed earlier

   • Creates DNA joining, exchange, or integration events

The method uses the ‘integration’ mechanism to generate the actual recombination reactions with appropriate kinetic parameters identified by the integrase name as part_id.

Each site pair generates only one reaction (not two) to avoid duplicates, with the reaction generation responsibility determined by the update order and population status of linked sites.

update_species()

Generate species associated with binding and integration.

Generate the list of species associated with the binding site, including integrase-DNA complexes generated by the parent DNA binding site if integrase_binding is True.

Returns:

list of Species

If integrase_binding is True, returns species from parent DNABindingSite including integrase-DNA complexes. If False, returns only the binder proteins without generating complexes.

Notes

When integrase_binding is False, the model assumes simplified recombination without explicit binding steps, useful for simplified models where binding kinetics are not important.

class biocrnpyler.components.dna.misc.Operator(name, binders=None, **kwargs)

Operator sequence component for visualization.

An Operator represents an operator DNA sequence (a regulatory element where repressor proteins typically bind) in a genetic construct. Like Origin and UserDefined parts, it primarily serves as a visual marker and does not use any mechanisms, therefore it does not generate species or reactions during CRN compilation. While the component can store references to binding proteins, it does not model the actual binding interactions.

Parameters:

namestr

Name of the operator sequence.

bindersSpecies, str, list, or None, optional

Protein(s) that bind to this operator. Can be a single binder, a list of binders, or None. This is stored for reference but does not generate binding reactions.

**kwargs

Additional keyword arguments passed to the parent DNA_part class.

Attributes:

namestr

Name of the operator.

binderslist of Species

List of protein species that can bind this operator (for reference only).

See also

DNA_part

Base class for DNA component parts.

DNABindingSite

Functional binding site that generates reactions.

RegulatedPromoter

Promoter with functional operator-like behavior.

Notes

Operators do not use any mechanisms and do not generate any species or reactions - both update_species and update_reactions return empty lists.

For functional operator behavior with actual binding reactions, use DNABindingSite or include operators within RegulatedPromoter components, which do use binding mechanisms to generate reactions.

The binder attribute stores potential binding proteins for documentation purposes but does not create binding interactions in the model.

Examples

Create a lac operator:

>>> lac_op = bcp.Operator(
...     name='lacO',
...     binders='protein_LacI'
... )

Create an operator with multiple potential binders:

>>> multi_op = bcp.Operator(
...     name='operator_1',
...     binders=['protein_RepA', 'protein_RepB']
... )

Create an operator without specifying binders:

>>> generic_op = bcp.Operator(name='op1')

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

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.

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_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() → None

Get the primary species associated with this component.

Returns:

None

Subclasses should override this method to return their primary Species object.

Notes

This is a placeholder that should be implemented by subclasses.

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

Returns:

list

Empty list, as operators have no associated mechanism.

Notes

For functional operator behavior with binding reactions, use DNABindingSite or RegulatedPromoter instead.

update_species()

Generate species for the operator.

Returns:

list

Empty list, as operators have no associated mechanism.

Notes

For functional operator behavior with species generation, use DNABindingSite instead.

class biocrnpyler.components.dna.misc.Origin(name, **kwargs)

Origin of replication component for visualization.

An Origin represents an origin of replication (ORI) in a DNA construct. Like UserDefined parts, it serves primarily as a visual marker and does not use any mechanisms, therefore it does not generate any species or reactions during CRN compilation. This component is useful for marking replication origins in plasmids or other DNA constructs for documentation and visualization purposes.

Parameters:

namestr

Name of the origin of replication.

**kwargs

Additional keyword arguments passed to the parent DNA_part class.

Attributes:

namestr

Name of the origin.

See also

DNA_part

Base class for DNA component parts.

UserDefined

General placeholder for non-functional parts.

Operator

Placeholder for operator sequences.

Notes

Origins do not use any mechanisms and do not generate any species or reactions - both update_species and update_reactions return empty lists.

While real origins of replication are essential for plasmid maintenance, their function is typically not modeled in gene expression CRNs, hence this component serves as a placeholder for construct annotation.

Examples

Create a standard E. coli origin:

>>> ori = bcp.Origin(name='pUC_ori')

Create a low-copy origin:

>>> p15a_ori = bcp.Origin(name='p15A_ori')

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

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.

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_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() → None

Get the primary species associated with this component.

Returns:

None

Subclasses should override this method to return their primary Species object.

Notes

This is a placeholder that should be implemented by subclasses.

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_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 the origin of replication.

Returns:

list

Empty list, as origins have no associated mechanism.

update_species()

Generate species for the origin of replication.

Returns:

list

Empty list, as origins have no associated mechanism.

class biocrnpyler.components.dna.misc.UserDefined(name, dpl_type=None, **kwargs)

User-defined DNA part with no intrinsic functionality.

A UserDefined part serves as a placeholder or label in DNA constructs. It represents a DNA sequence that exists in the construct but does not use any mechanisms and therefore does not generate any species or reactions during CRN compilation. This is useful for marking regions of DNA that are important for visualization, documentation, or future extension but do not participate in the modeled biochemical processes.

Parameters:

namestr

Name of the user-defined part.

dpl_typestr, optional

Type identifier for DNA Parts Library compatibility. Can be used to specify the category or function of this part for external tools or databases.

**kwargs

Additional keyword arguments passed to the parent DNA_part class.

Attributes:

namestr

Name of the part.

dpl_typestr or None

DNA Parts Library type identifier.

See also

DNA_part

Base class for DNA component parts.

Origin

Specialized placeholder for origins of replication.

Operator

Specialized placeholder for operator sequences.

Notes

UserDefined parts do not use any mechanisms and do not generate any species or reactions during CRN compilation - both update_species and update_reactions return empty lists.

This component is particularly useful for:

• Marking spacer sequences or linkers

• Placeholder for parts not yet modeled

• Annotation regions for construct visualization

• Future extension points in genetic designs

Examples

Create a spacer sequence:

>>> spacer = bcp.UserDefined(
...     name='spacer_50bp',
...     dpl_type='spacer'
... )

Create a placeholder for an unmodeled part:

>>> unknown = bcp.UserDefined(
...     name='unknown_region',
...     dpl_type='uncharacterized'
... )

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

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.

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_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() → None

Get the primary species associated with this component.

Returns:

None

Subclasses should override this method to return their primary Species object.

Notes

This is a placeholder that should be implemented by subclasses.

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_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 the user-defined part.

Returns:

list

Empty list, as user-defined parts have no associated mechanism.

update_species()

Generate species for the user-defined part.

Returns:

list

Empty list, as user-defined parts have no associated mechanism.