biocrnpyler.core.PolymerConformation

class biocrnpyler.core.PolymerConformation(complexes=None, polymer=None, material_type='conformation', name=None, **kwargs)[source]

Bases: Species, MonomerCollection

Set of polymers and their connections via ComplexSpecies.

Represents a conformation of one or more PolymerSpecies connected by ComplexSpecies containing monomers from the polymers. This class provides unique naming for conformations and serves as a data structure for polymer hypergraphs.

Parameters:

complexes (list of ComplexSpecies, optional) – List of ComplexSpecies connecting monomers from OrderedPolymerSpecies. Must contain monomers from the polymers.
polymer (OrderedPolymerSpecies or list of Species, optional) – Single polymer or list of species to form a polymer. Exactly one of complexes or polymer must be provided.
material_type (str, default 'conformation') – Material type identifier.
name (str or None, optional) – Custom name for the conformation. If None, auto-generated.
**kwargs – Additional keyword arguments passed to Species constructor.

Attributes:

polymers (list of OrderedPolymerSpecies) – List of polymers in this conformation.
complexes (list of ComplexSpecies) – List of complexes connecting monomers in the polymers.
name (str) – Auto-generated name encoding polymer and complex structure.

See also

OrderedPolymerSpecies: Polymer species for chemical reactions.
ComplexSpecies: Complex of multiple bound species.
Complex: Metaclass for creating complexes.

Notes

Auto-generated names follow the format: conformation__[Polymer1]_[Polymer2]_[indices]_[Complex1]_[Complex2]__

where indices encode which polymers each complex binds to and the list of PolymerSpecies and ComplexSpecies are in alphabetical order.

A PolymerConformation represents a hypergraph where:

Monomers are vertices
ComplexSpecies are hyperedges connecting arbitrary numbers of vertices
Multiple edges between the same vertices are allowed

Users typically do not create PolymerConformations directly. The Complex function automatically creates them when complexing monomers from OrderedPolymerSpecies.

Examples

Create from a single polymer:

>>> S1 = bcp.Species('S1')
>>> S2 = bcp.Species('S2')
>>> polymer = bcp.OrderedPolymerSpecies([S1, S2])
>>> conformation = bcp.PolymerConformation(polymer=polymer)

Methods

`add_attribute`	Add an attribute to the species.
`contains_species_monomer`	Check if the species contains a monomer, ignoring context.
`copy_remove_complexes`	Returns a new PolymerConformation without these complexes.
`count_polymer`
`find_polymer_component`	Find the polymer component within this monomer or its species.
`flatten_list`	Recursively flatten a nested list of species.
`from_polymer_conformation`	Create PolymerConformation from existing conformations.
`from_polymer_replacement`	Create PolymerConformation by replacing polymers.
`get_complex`
`get_complexes_at`
`get_orphan`	Create a copy of this monomer without a parent reference.
`get_polymer`
`get_polymer_indices`
`get_polymer_positions`
`get_removed`	Create a fully detached copy of this monomer.
`get_species`	Get a list containing this species.
`monomer_eq`	Check if two monomers are equal, ignoring parent and position.
`monomer_insert`	Insert this monomer into a polymer at a specific position.
`pretty_print`	Generate a human-readable string representation of the species.
`remove`	Remove the species from its parent polymer.
`remove_attribute`	Remove an attribute from the species.
`remove_complex`
`replace_species`	Replace a species with another species.
`set_dir`	Set the direction of the monomer and return self.
`subhash`	Compute hash contribution from monomer properties.

__eq__(other)[source]

Check if two species are equivalent.

Two species are equal if they have the same name, material_type, attributes (as sets), parent, compartment, and position.

Parameters:: other (Species) – The species to compare with.
Returns:: True if species are equivalent, False otherwise.
Return type:: bool

Notes

Equality between parents and children can result in loops, so string equality is used for parent comparison.

__gt__(Species2)[source]: Return self>value.

__lt__(Species2)[source]: Return self<value.

add_attribute(attribute: str)[source]

Add an attribute to the species.

Parameters:: attribute (str) – The attribute to add. Must be an alphanumeric string and non-None.
Raises:: AssertionError – If attribute is not an alphanumeric string or is None.

Notes

Duplicate attributes are not added - each attribute appears only once in the attributes list.

Examples

>>> species = bcp.Species('MyProtein')
>>> species.add_attribute('degraded')
>>> species.attributes
['degraded']

contains_species_monomer(s)[source]

Check if the species contains a monomer, ignoring context.

Parameters:: s (Species) – The species monomer to search for.
Returns:: True if the species contains a monomer equal to s (ignoring parent, position, and direction), False otherwise.
Return type:: bool

Notes

This is a less stringent version of __contains__ that checks without considering Species.parent, Species.position, or direction. Useful for determining if a species is present regardless of its polymer context.

copy_remove_complexes(complexes)[source]: Returns a new PolymerConformation without these complexes.

find_polymer_component()[source]

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:: The monomer that is part of a polymer structure, or None if no polymer component is found.
Return type:: OrderedMonomer or None
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.

static flatten_list(in_list) → List[source]

Recursively flatten a nested list of species.

Parameters:: in_list (list or Species) – A potentially nested list of species, or a single species.
Returns:: Flattened list containing all species. None elements are filtered out.
Return type:: list

Examples

>>> S1 = bcp.Species('S1')
>>> S2 = bcp.Species('S2')
>>> nested = [S1, [S2, None]]
>>> bcp.Species.flatten_list(nested)
[S1, S2]

classmethod from_polymer_conformation(pcs, complexes=None, complexes_to_remove=None, **kwargs)[source]

Create PolymerConformation from existing conformations.

Produces a new PolymerConformation by merging complexes from previous PolymerConformations and adding new complexes.

Parameters:

pcs (list of PolymerConformation) – List of existing PolymerConformations to merge.
complexes (list of ComplexSpecies, optional) – Additional complexes to add to the conformation. Default is an empty list.
complexes_to_remove (list of ComplexSpecies, optional) – Complexes to exclude from the merged conformation. Default is an empty list.
**kwargs – Additional keyword arguments for the new PolymerConformation.

Returns:

New conformation merging all input conformations and complexes.

Return type:

PolymerConformation

Raises:

TypeError – If pcs is not a list of PolymerConformations.

classmethod from_polymer_replacement(pc, old_polymers, new_polymers, **kwargs)[source]

Create PolymerConformation by replacing polymers.

Produces a PolymerConformation from an existing one by replacing specified polymers with new ones, updating all complexes accordingly.

Parameters:

pc (PolymerConformation) – The conformation to modify.
old_polymers (list of OrderedPolymerSpecies) – Polymers to replace. Must be the same instances (not just equal) as those in pc.polymers.
new_polymers (list of OrderedPolymerSpecies) – New polymers to use as replacements. Must be the same length as old_polymers.
**kwargs – Additional keyword arguments for the new PolymerConformation. Defaults are inherited from pc if not specified.

Returns:

New conformation with polymers replaced.

Return type:

PolymerConformation

Raises:

TypeError – If arguments are not the correct types.
ValueError – If old_polymers are not instances in pc.polymers, or if lists have different lengths.

Notes

This method updates all complexes to reference monomers from the new polymers at the same positions as in the old polymers.

get_orphan()[source]

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:: A copy of this monomer with parent set to None but position and direction preserved.
Return type:: OrderedMonomer

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(recursive=None)[source]

Get a list containing this species.

Returns:: A list containing only this species: [self].
Return type:: list of Species

Notes

This method is used in recursive calls where ComplexSpecies returns a list of constituent species while Species returns just itself in a list. The recursive parameter is accepted for compatibility but not used in the base Species class.

monomer_eq(other)[source]

Check if two monomers are equal, ignoring parent and position.

Parameters:: other (Species) – The species to compare with.
Returns:: True if species have the same name, material_type, attributes, and compartment, regardless of parent or position.
Return type:: bool

Notes

This is the same as normal equality but does not check for parents or positions. Useful for comparing species that may be in different polymer contexts.

monomer_insert(parent: OrderedPolymer, position: int, direction=None)[source]

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:

parent (OrderedPolymer) – The polymer to insert this monomer into.
position (int) – The position index where this monomer is being inserted.
direction (str, 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.

pretty_print(show_material=True, show_compartment=False, show_attributes=True, show_initial_condition=False, **kwargs)[source]

Generate a human-readable string representation of the species.

Parameters:

show_material (bool, default True) – If True, includes material_type in brackets around the species.
show_compartment (bool, default False) – If True, shows the compartment name in the representation.
show_attributes (bool, default True) – If True, includes attributes in parentheses after the name.
show_initial_condition (bool, default False) – Placeholder for compatibility with CRN printing.
**kwargs – Additional keyword arguments (currently unused).

Returns:

Formatted string representation of the species.

Return type:

str

Notes

This method provides more detailed output than __repr__, useful for understanding CRNs but does not return string identifiers compatible with parsers.

Format: material_type[name(attr1, attr2)-direction]

Examples

>>> S = bcp.Species('S', material_type='protein',
...                 attributes=['active'])
>>> S.pretty_print()
'protein[S(active)]'

remove()[source]

Remove the species from its parent polymer.

Overrides OrderedMonomer.remove to also remove the direction attribute if present.

Returns:: Returns self after removal for method chaining.
Return type:: Species

remove_attribute(attribute: str)[source]

Remove an attribute from the species.

Parameters:: attribute (str) – The attribute to remove. Must be an alphanumeric string.

Notes

If the attribute is not present or is None, no action is taken. All occurrences of the attribute are removed from the attributes list.

replace_species(species, new_species)[source]

Replace a species with another species.

For a simple Species, returns new_species if this species equals species, otherwise returns self. For complex species, acts recursively.

Parameters:

species (Species) – The species to search for and replace.
new_species (Species) – The species to replace with.

Returns:

Either new_species (if self == species) or self.

Return type:

Species

Raises:

ValueError – If either argument is not a Species instance.

set_dir(direction)[source]

Set the direction of the monomer and return self.

Convenience method for setting direction in a fluent interface style.

Parameters:: direction (str, int, or None) – The direction to assign to this monomer.
Returns:: Returns self for method chaining.
Return type:: OrderedMonomer

Examples

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

subhash()[source]

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:: Hash value based on monomer-specific properties.
Return type:: int

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.