biocrnpyler.components.combinatorial_conformation

Classes

CombinatorialConformation(final_states[, ...])	Polymer conformation with combinatorial internal binding complexes.
CombinatorialConformationPromoter(...[, ...])	Combinatorial conformation with transcriptionally active states.

class biocrnpyler.components.combinatorial_conformation.CombinatorialConformation(final_states, initial_states=None, intermediate_states=None, excluded_states=None, state_part_ids=None, name=None, **kwargs)

Polymer conformation with combinatorial internal binding complexes.

A CombinatorialConformation component represents a polymer conformation (made of one unique OrderedPolymerSpecies) with multiple internal complexes that can bind and unbind in many different ways. Unlike CombinatorialComplex where individual species are added one at a time, this component adds groups of species in single steps to form the appropriate complexes. Uses a ‘conformation_change’ mechanism.

Parameters:

final_statesPolymerConformation or list of PolymerConformation

One or more final polymer conformations to be formed. All must contain the same unique OrderedPolymerSpecies.

initial_stateslist of PolymerConformation, optional

Initial polymer conformations that can bind/unbind to become final_states. If None or empty, defaults to the bare polymer without complexes.

intermediate_stateslist of PolymerConformation, optional

Allowed intermediate conformations formed when converting initial_states to final_states. If None, all possible intermediate conformations are enumerated.

excluded_stateslist of PolymerConformation, optional

Polymer conformations that will NOT be formed during enumeration. If None, no conformations are excluded.

state_part_idsdict, optional

Dictionary mapping PolymerConformation to string, used to generate shorter part-ids for conformations.

namestr, optional

Name of the component. If None, uses the internal polymer name.

**kwargs

Additional keyword arguments passed to the Component base class constructor.

Attributes:

final_stateslist of PolymerConformation

List of final conformation states.

initial_stateslist of PolymerConformation

List of initial conformation states.

intermediate_stateslist of PolymerConformation or None

List of allowed intermediates.

excluded_stateslist of PolymerConformation

List of excluded conformations.

internal_polymerOrderedPolymerSpecies

The unique polymer species common to all conformations.

state_part_idsdict

Dictionary for custom part-id naming.

combination_dictdict

Dictionary storing computed conformation changes.

See also

CombinatorialComplex

Combinatorial binding of simple complexes.

PolymerConformation

Species subclass for polymer conformations.

Component

Base class for biomolecular components.

Notes

Key differences from CombinatorialComplex:

• Operates on PolymerConformation objects instead of simple Species

• All conformations must share the same OrderedPolymerSpecies

• Adds groups of species simultaneously to form complexes

• Uses ‘conformation_change’ mechanism instead of ‘binding’

Reaction generation: The component generates conformation change reactions based on constraints:

• Without intermediate_states: initial_states <–> final_states

• With intermediate_states: initial_states <–> intermediate_states <–> final_states

Validation requirements: All conformations must:

1. Be PolymerConformation objects

2. Contain exactly one unique OrderedPolymerSpecies

3. Have the same internal polymer

Examples

Create a simple conformational change system:

>>> A, B, C, S = (bcp.Species(s) for s in ['A', 'B', 'C', 'S'])
>>> pc = bcp.PolymerConformation(polymer=[A, A, B, C])
>>> # Form a complex A:B by binding positions 0 and 2
>>> c1 = bcp.Complex([pc.polymers[0][0], pc.polymers[0][2]])
>>> pc1 = c1.parent
>>> # Form two complexes: A:B and A:C:S (S is external)
>>> c2 = bcp.Complex([pc1.polymers[0][1], pc1.polymers[0][3], S])
>>> pc2 = c2.parent
>>> # Create component to enumerate reactions
>>> cc = bcp.CombinatorialConformation(
...     final_states=pc2,
...     parameters={'kf': 1, 'kr': 0.01})

Using a Mixture to generate species and reactions:

>>> mixture = bcp.Mixture(components=[cc])
>>> crn = mixture.compile_crn()

__hash__()

Return hash(self).

add_attribute(attribute: str)

Add a single attribute to the component.

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

Parameters:

attributestr

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

Raises:

AssertionError

If attribute is not a string or is None.

Warning

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

Notes

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

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

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

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

Examples

Add attributes to tag a protein with special properties:

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

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

Add a mechanism to this component’s mechanism dictionary.

Parameters:

mechanismMechanism

The mechanism object to add.

mech_typestr, optional

The type key under which to store the mechanism. If None, uses the mechanism’s mechanism_type attribute.

overwritebool, default=False

If True, replaces any existing mechanism with the same key. If False, raises ValueError when key already exists.

optional_mechanismbool, default=False

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

Raises:

TypeError

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

ValueError

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

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

Add multiple mechanisms to this component.

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

Parameters:

mechanismsMechanism, GlobalMechanism, dict, or list

The mechanism(s) to add. Can be a single mechanism, a dict with mechanism types as keys and mechanisms as values, or a list of mechanisms.

overwritebool, default=False

If True, replaces any existing mechanisms with the same keys. If False, raises ValueError when keys already exist.

optional_mechanismbool, default=False

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

Raises:

ValueError

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

property compartment

Compartment or None: The compartment containing this component.

compute_species_changes(s0, sf)

Compute changes needed to convert conformation s0 into sf.

Analyzes what species need to be added and which complexes need to be merged to transform the initial conformation s0 into the final conformation sf. Assumes both conformations share the same underlying polymer.

Parameters:

s0PolymerConformation

Starting conformation.

sfPolymerConformation

Target final conformation.

Returns:

tuple of (dict, dict) or False

Returns False if s0 cannot be additively transformed into sf. Otherwise returns (species_changes, merged_complexes) where:

• species_changes: dict mapping (complex, positions) to list of external species to add

• merged_complexes: dict mapping (complex, positions) to list of complexes from s0 that merge to form sf

Notes

Returns False if:

• s0 has more complexes at any position than sf

• Any complex in sf cannot be formed additively from s0

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.

property excluded_states

List of excluded conformations.

Returns:

list of PolymerConformation

property final_states

List of final conformation states.

Returns:

list of PolymerConformation

get_combinations_between(s0, sf)

Get all conformation change combinations from s0 to sf.

Enumerates all possible orders of complex formation to transform conformation s0 into sf, generating tuples representing each step.

Parameters:

s0PolymerConformation

Starting conformation.

sfPolymerConformation

Target final conformation.

Returns:

list of tuple

List of (old_state, species_to_add, new_state) tuples representing all possible transformation pathways. Each tuple represents one conformation change step. Returns empty list if no valid pathways exist.

Notes

The method:

1. Computes which species/complexes change between s0 and sf

2. Generates all permutations (different formation orders)

3. For each permutation, creates conformational change steps

4. Filters out any combinations involving excluded_states

Unlike CombinatorialComplex, this method adds groups of species simultaneously to form complete complexes at polymer positions.

get_mechanism(mechanism_type, optional_mechanism=False)

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

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

Parameters:

mechanism_typestr

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

optional_mechanismbool, default=False

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

Returns:

Mechanism or None

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

Raises:

TypeError

If mechanism_type is not a string.

KeyError

If mechanism not found and optional_mechanism is False.

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

Retrieve parameter from component or mixture parameter database.

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

Parameters:

param_namestr

Name of the parameter to retrieve.

part_idstr, optional

Part identifier for the parameter lookup key.

mechanismstr, optional

Mechanism identifier for the parameter lookup key.

return_numericalbool, default=False

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

return_nonebool, default=False

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

check_mixturebool, default=True

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

Returns:

Parameter, Real, or None

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

Raises:

ValueError

If parameter not found and return_none is False.

Notes

Parameter lookup follows the hierarchy:

1. Component.parameter_database

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

get_species()

Get the bare polymer conformation.

Returns:

PolymerConformation

The internal polymer without any complexes.

property initial_states

List of initial conformation states.

Returns:

list of PolymerConformation

property intermediate_states

List of allowed intermediates.

Returns:

list of PolymerConformation or None

set_attributes(attributes: List[str])

Set multiple attributes for the component.

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

Parameters:

attributeslist of str or None

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

See also

add_attribute

Add a single attribute to the component.

Examples

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

set_mixture(mixture) → None

Set the mixture containing this component.

Parameters:

mixtureMixture or None

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

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

Convert various inputs into Species objects.

Parameters:

speciesSpecies, str, Component, or list

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

material_typestr, optional

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

compartmentCompartment, optional

Compartment to assign to the species. Only used when creating new Species from strings.

attributeslist of str, optional

Attributes to assign to the species. Only used when creating new Species from strings.

Returns:

Species or list of Species

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

Raises:

ValueError

If the input cannot be converted to a valid Species.

update_parameters(parameter_file=None, parameters=None, parameter_database=None, overwrite_parameters=True)

Update the parameter database with new parameters.

Parameters:

parameter_filestr, optional

Path to a CSV or TSV file containing parameters to load.

parametersdict, optional

Dictionary of parameters to add. Keys follow the format (mechanism, part_id, param_name).

parameter_databaseParameterDatabase, optional

Another parameter database to merge into component’s database.

overwrite_parametersbool, default=True

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

update_reactions()

Use ‘conformation_change’ mechanism to generate reactions.

Uses the ‘conformation_change’ mechanism to generate reactions for all possible conformation transformations between initial_states and final_states, optionally constrained by intermediate_states and excluding excluded_states.

Returns:

list of Reaction

List of all conformation change reactions (forward and reverse) along all enumerated pathways.

Notes

The method handles two cases:

With intermediate_states:

1. Generate reactions: initial_states <–> intermediate_states

2. Generate reactions: intermediate_states <–> final_states

Without intermediate_states: generate reactions: initial_states <–> final_states directly.

Duplicate reactions are automatically filtered out using reactions_added_dict. The method uses combination_dict computed by update_species or computes it if needed.

update_species()

Use ‘conformation_change’ mechanism to generate species.

Uses the ‘conformation_change’ mechanism to generate species for all possible conformation transformations between initial_states and final_states, optionally constrained by intermediate_states and excluding excluded_states.

Returns:

list of Species

List of all unique species generated, including polymer conformations and any additional species involved in conformation changes.

Notes

Duplicate species are automatically removed from the final list. The combination_dict is populated during this process for use by update_reactions.

class biocrnpyler.components.combinatorial_conformation.CombinatorialConformationPromoter(promoter_states, promoter_location, promoter_states_on=True, activating_complexes=None, inactivating_complexes=None, intermediate_states=None, final_states=None, name='CombinatorialConformationPromoter', **kwargs)

Combinatorial conformation with transcriptionally active states.

A CombinatorialConformationPromoter combines CombinatorialConformation and Promoter functionality, creating a polymer with combinatorial conformations where certain conformations can transcribe/express RNA/protein products. Specific conformations can be designated as transcriptionally active (‘on’) or inactive (‘off’).

Parameters:

promoter_stateslist of PolymerConformation

Polymer conformations used by the promoter. These states are designated as either ‘on’ or ‘off’ based on promoter_states_on.

promoter_locationint

Index of the monomer in the polymer conformation that represents the promoter location on the polymer.

promoter_states_onbool, default=True

If True, all promoter_states are transcribable. If False, all states except promoter_states are transcribable.

activating_complexeslist of ComplexSpecies, optional

Complexes that activate polymer conformations for transcription regardless of promoter_states.

inactivating_complexeslist of ComplexSpecies, optional

Complexes that inactivate polymer conformations, preventing transcription even if otherwise active.

intermediate_stateslist of PolymerConformation, optional

Allowed intermediate conformations (see CombinatorialConformation).

final_stateslist of PolymerConformation, optional

Final conformations (see CombinatorialConformation).

namestr, default=’CombinatorialConformationPromoter’

Name of the component.

**kwargs

Additional keyword arguments passed to the parent class constructors.

Attributes:

promoter_stateslist of PolymerConformation

List of designated promoter states.

promoter_states_onbool

Whether promoter_states are active or inactive.

promoter_locationint

Polymer position of the promoter.

activating_complexeslist of ComplexSpecies

Complexes that activate transcription.

inactivating_complexeslist of ComplexSpecies

Complexes that prevent transcription.

conformation_specieslist

All conformation species (populated by update_species).

See also

CombinatorialConformation

Base class for conformational changes.

Promoter

Base class for transcription initiation.

PolymerConformation

Polymer with internal complexes.

Notes

A conformation is transcriptionally active if:

1. (conformation in promoter_states AND promoter_states_on=True) OR (conformation not in promoter_states AND promoter_states_on=False)

2. OR any activating_complex is present in the conformation

3. AND no inactivating_complex is present

If inactivating_complex conflicts with active_state or active_complex, a warning is issued and transcription is prevented.

The promoter location determines which DNA species from the polymer is used for transcription initiation.

Examples

Create a promoter (operon) with conformational regulation:

>>> A, B, F = (bcp.Species(s) for s in ['A', 'B', 'F'])
>>> op = bcp.PolymerConformation(polymer=[B, A, B])
>>> OF0 = bcp.Complex([op.polymers[0][0], F]).parent  # F bound at pos'n 0
>>> OF1 = bcp.Complex([op.polymers[0][2], F]).parent  # F bound at pos'n 2
>>> OF2 = tbp.Complex([OF1.polymers[0][2], F]).parent # F bound to both
>>> # Looped conformations
>>> L0 = Complex([op.polymers[0][0], op.polymers[0][1], F]).parent
>>> L1 = Complex([op.polymers[0][2], op.polymers[0][1], F]).parent
>>> # Define fully bound looped states
>>> L0F1 = bcp.Complex(
...     [OF1.polymers[0][0], OF1.polymers[0][1], F]).parent
>>> L1F0 = bcp. Complex(
...     [OF0.polymers[0][2], OF0.polymers[0][1], F]).parent
>>> # Create promoter with specific active states
>>> ccp = bcp.CombinatorialConformationPromoter(
...     name="CCP",
...     intermediate_states=[OF0, OF1],
...     final_states=[OF2, L0F1, L1F0],
...     promoter_states=[L0F1, L1F0, L0, L1],  # transcribed states
...     promoter_states_on=True,
...     promoter_location=1
... )

With repression (toggle promoter_states_on):

>>> # Same setup as above, but with promoter_states_on=False
>>> # Now only states NOT in promoter_states will transcribe
>>> ccp = bcp.CombinatorialConformationPromoter(
...     name="CCP",
...     intermediate_states=[OF0, OF1],
...     final_states=[OF2, L0F1, L1F0],
...     promoter_states=[L0F1, L1F0, L0, L1],
...     promoter_states_on=False,
...     promoter_location=1
... )
>>> # Use in a DNAassembly for transcription
>>> assy = bcp.DNAassembly(
...     name="X", dna=op, promoter=ccp, rbs="rbs", protein="X")
>>> mixture = bcp.Mixture(
...     components=[assy],
...     mechanisms=[bcp.SimpleTranscription(), bcp.SimpleTranslation()],
...     parameters={'kf': 1, 'kr': 0.01, 'ktx': 1, 'ktl': 1}
... )
>>> crn = mixture.compile_crn()

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

compute_species_changes(s0, sf)

Compute changes needed to convert conformation s0 into sf.

Analyzes what species need to be added and which complexes need to be merged to transform the initial conformation s0 into the final conformation sf. Assumes both conformations share the same underlying polymer.

Parameters:

s0PolymerConformation

Starting conformation.

sfPolymerConformation

Target final conformation.

Returns:

tuple of (dict, dict) or False

Returns False if s0 cannot be additively transformed into sf. Otherwise returns (species_changes, merged_complexes) where:

• species_changes: dict mapping (complex, positions) to list of external species to add

• merged_complexes: dict mapping (complex, positions) to list of complexes from s0 that merge to form sf

Notes

Returns False if:

• s0 has more complexes at any position than sf

• Any complex in sf cannot be formed additively from s0

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.

property excluded_states

List of excluded conformations.

Returns:

list of PolymerConformation

property final_states

List of final conformation states.

Returns:

list of PolymerConformation

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_combinations_between(s0, sf)

Get all conformation change combinations from s0 to sf.

Enumerates all possible orders of complex formation to transform conformation s0 into sf, generating tuples representing each step.

Parameters:

s0PolymerConformation

Starting conformation.

sfPolymerConformation

Target final conformation.

Returns:

list of tuple

List of (old_state, species_to_add, new_state) tuples representing all possible transformation pathways. Each tuple represents one conformation change step. Returns empty list if no valid pathways exist.

Notes

The method:

1. Computes which species/complexes change between s0 and sf

2. Generates all permutations (different formation orders)

3. For each permutation, creates conformational change steps

4. Filters out any combinations involving excluded_states

Unlike CombinatorialComplex, this method adds groups of species simultaneously to form complete complexes at polymer positions.

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 bare polymer conformation.

Returns:

PolymerConformation

The internal polymer without any complexes.

property initial_states

List of initial conformation states.

Returns:

list of PolymerConformation

property intermediate_states

List of allowed intermediates.

Returns:

list of PolymerConformation or None

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.

property promoter_states

List of designated promoter states.

Returns:

list of PolymerConformation

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 conformation changes and transcription.

Generates reactions from both conformational changes (via CombinatorialConformation) and transcription (via Promoter) for conformations that are transcriptionally active.

Returns:

list of Reaction

List of all reactions including conformation change reactions and transcription reactions (RNAP binding, elongation, etc.) for active conformations.

Notes

For each conformation, determines if it is transcriptionally active using the same logic as update_species(). Only active conformations generate transcription reactions via Promoter.update_reactions.

The component name is temporarily changed to a state-specific name for each conformation to ensure unique reaction identifiers.

update_species()

Generate species for conformation changes and transcription.

Generates species from both conformational changes (via CombinatorialConformation) and transcription (via Promoter) for conformations that are transcriptionally active.

Returns:

list of Species

List of all unique species including conformation states and transcription-related species (RNAP complexes, transcripts, etc.) for active conformations.

Notes

For each conformation, determines if it is transcriptionally active based on:

• Whether it is in promoter_states (and promoter_states_on setting)

• Presence of activating_complexes

• Absence of inactivating_complexes

Only active conformations generate transcription species via Promoter.update_species().