biocrnpyler.core.OrderedPolymerSpecies

class biocrnpyler.core.OrderedPolymerSpecies(species, name=None, material_type='ordered_polymer', compartment=None, attributes=None, circular=False)

Bases: OrderedComplexSpecies, OrderedPolymer

Ordered polymer that can participate in chemical reactions.

A polymer composed of Species (which are also OrderedMonomers) that can act as a reactant or product in chemical reactions. The internal species represent multiple binding sites and/or functional regions.

Parameters:

• species (list of Species or list of [Species, direction]) – List of species monomers to form the polymer. Each element can be a Species or a [Species, direction] pair.

• name (str or None, optional) – Custom name for the polymer. If None, auto-generated from constituent species.

• material_type (str, default 'ordered_polymer') – Material type identifier for the polymer.

• compartment (Compartment, str, or None, optional) – Compartment containing the polymer.

• attributes (list of str or None, optional) – Attributes for the polymer species.

• circular (bool, default False) – If True, the polymer has circular topology (e.g., plasmid).

Attributes:

• polymer (tuple of Species) – Ordered tuple of species monomers in the polymer.

• species (tuple of Species) – Alias for polymer (inherited from OrderedPolymer).

• circular (bool) – Flag indicating circular topology.

• default_material (str) – Class attribute defining default material type.

See also

OrderedPolymer

Base class for ordered polymers.

OrderedComplexSpecies

Ordered complex base class.

PolymerConformation

Set of polymers with connections.

Notes

When used as a reaction input, either the entire OrderedPolymerSpecies or one of its internal Species (with Species.parent = OrderedPolymerSpecies) can be passed to mechanisms.

Species inside an OrderedPolymerSpecies model multiple binding sites and/or functional regions. ComplexSpecies can be formed at specific locations by passing the internal Species.

The circular attribute indicates circular topology but does not automatically enforce circular constraints in operations.

Examples

Create a linear polymer:

>>> S1 = bcp.Species('S1')
>>> S2 = bcp.Species('S2')
>>> polymer = bcp.OrderedPolymerSpecies(
...     species=[S1, S2],
...     name='my_polymer'
... )
>>> len(polymer)
2

Create a circular polymer (plasmid):

>>> plasmid = bcp.OrderedPolymerSpecies(
...     species=[S1, S2],
...     circular=True
... )
>>> plasmid.circular
True

Methods

add_attribute	Add an attribute to the species.
append	Add a monomer to the end of the polymer.
changed	Callback method invoked whenever the polymer structure changes.
contains_species_monomer	Check if the species contains a monomer, ignoring context.
delpart	Remove a monomer from the polymer at a specific position.
direction_invert	Invert a direction value.
find_polymer_component	Find the polymer component within this monomer or its species.
flatten_list	Recursively flatten a nested list of species.
from_polymer_species	Create OrderedPolymerSpecies with specific monomers replaced.
get_orphan	Create a copy of this monomer without a parent reference.
get_removed	Create a fully detached copy of this monomer.
get_species	Get all species in the complex.
get_species_list
insert	Insert a monomer at a specific position in the polymer.
monomer_count	Count occurrences of a monomer in the complex.
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	A more powerful printing function.
remove	Remove the species from its parent polymer.
remove_attribute	Remove an attribute from the species.
replace	Replace a monomer at a specific position in the polymer.
replace_species	Replaces species with new_species in the entire Complex Species.
reverse	Reverse the order and directions of all monomers in the polymer.
set_dir	Set the direction of the monomer and return self.
set_species_list
subhash	Compute hash contribution from monomer properties.

__contains__(item)

Check if a species is contained in the complex.

Parameters:

item (Species) – The species to search for.

Returns:

True if the species is found in the complex or any nested complexes, False otherwise.

Return type:

bool

Raises:

ValueError – If item is not a Species instance.

Notes

This method searches recursively through nested ComplexSpecies to find the target species.

__eq__(other)

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.

__getitem__(ii)

Get a monomer or slice of monomers from the polymer.

Parameters:

ii (int or slice) – Index or slice to retrieve from the polymer.

Returns:

The monomer at the given index, or a tuple of monomers for a slice.

Return type:

OrderedMonomer or tuple

__gt__(Species2)

Return self>value.

__len__()

Return the number of monomers in the polymer.

Returns:

The number of monomers in the polymer sequence.

Return type:

int

__lt__(Species2)

Return self<value.

__setitem__(ii, val)

Replace a monomer at a specific position.

Parameters:

• ii (int) – Index at which to replace the monomer.

• val (OrderedMonomer) – The new monomer to insert at the position.

Notes

Internally calls replace with the monomer’s existing direction.

add_attribute(attribute: str)

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']

append(part, direction=None)

Add a monomer to the end of the polymer.

Appends a copy of the given monomer to the end of the polymer sequence by calling insert at the final position.

Parameters:

• part (OrderedMonomer) – The monomer to append. A copy of this monomer will be added.

• direction (str, int, or None, optional) – Direction for the appended monomer. If None, uses the monomer’s existing direction if available.

See also

insert

Insert a monomer at a specific position.

Examples

>>> polymer = bcp.OrderedPolymer(parts=[])
>>> mon = bcp.OrderedMonomer()
>>> polymer.append(mon, direction='forward')
>>> len(polymer)
1

changed()

Callback method invoked whenever the polymer structure changes.

This method is called after operations that modify the polymer, such as insert, replace, delpart, or reverse. Subclasses can override this to implement custom behavior when the polymer is modified.

Notes

The base implementation does nothing. Override in subclasses to add functionality like name regeneration, validation, or notifications.

contains_species_monomer(s)

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.

delpart(position)

Remove a monomer from the polymer at a specific position.

Removes the monomer at the given position, shifts all subsequent monomers to lower positions, and calls the changed callback.

Parameters:

position (int) – Index of the monomer to remove. Must be a valid position in the polymer.

See also

replace

Replace a monomer at a specific position.

insert

Insert a monomer at a specific position.

Notes

The removed monomer’s remove method is called to clear its parent, position, and direction. If the polymer has a name attribute and a make_name method, the name is regenerated after deletion.

direction_invert(dirname)

Invert a direction value.

Converts a direction to its opposite orientation. Used during polymer reversal operations.

Parameters:

dirname (str, int, or None) –

The direction to invert. Supported values:

• ’forward’ \(\rightleftharpoons\) ‘reverse’

• 0 \(\rightleftharpoons\) 1

• None -> None

Returns:

The inverted direction. Returns the input unchanged if it cannot be inverted.

Return type:

str, int, or None

Warns:

UserWarning – If the direction value is not recognized.

Examples

>>> polymer = bcp.OrderedPolymer(parts=[])
>>> polymer.direction_invert('forward')
'reverse'
>>> polymer.direction_invert(0)
1

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:

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

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_species(ops, replace_dict, **kwargs)

Create OrderedPolymerSpecies with specific monomers replaced.

Parameters:

• ops (OrderedPolymerSpecies) – The original polymer species to modify.

• replace_dict (dict) – Dictionary mapping monomer indices (int) to new Species to insert at those positions.

• **kwargs – Additional keyword arguments for the new OrderedPolymerSpecies. Defaults are inherited from ops if not specified.

Returns:

New polymer with specified monomers replaced.

Return type:

OrderedPolymerSpecies

Notes

If replace_dict is empty, returns a deep copy of ops.

Examples

Replace monomer at position 1:

>>> S1 = bcp.Species('S1')
>>> S2 = bcp.Species('S2')
>>> S3 = bcp.Species('S3')
>>> polymer = bcp.OrderedPolymerSpecies([S1, S2])
>>> new_polymer = bcp.OrderedPolymerSpecies.from_polymer_species(
...     polymer, {1: S3}
... )

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:

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

Return type:

OrderedMonomer

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_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:

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

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=False)

Get all species in the complex.

Parameters:

recursive (bool, default False) – If True, returns species inside nested ComplexSpecies recursively. If False, returns only this ComplexSpecies.

Returns:

List of species. If recursive=False, returns [self]. If recursive=True, returns [self] plus all constituent species.

Return type:

list of Species

insert(position, part, direction=None)

Insert a monomer at a specific position in the polymer.

Inserts a copy of the given monomer at the specified position, shifting all subsequent monomers to higher positions. Calls the changed callback after insertion.

Parameters:

• position (int) – Index at which to insert the monomer. Must be between 0 and len(polymer) (inclusive).

• part (OrderedMonomer) – The monomer to insert. A copy of this monomer will be added.

• direction (str, int, or None, optional) – Direction for the inserted monomer. If None, uses the monomer’s existing direction.

See also

append

Add a monomer to the end of the polymer.

replace

Replace a monomer at a specific position.

Notes

The monomer is deep-copied before insertion to maintain independence from the original object.

monomer_count(m)

Count occurrences of a monomer in the complex.

Parameters:

m (Species) – The monomer to count.

Returns:

Number of times the monomer appears in the complex, using monomer_eq for equality comparison.

Return type:

int

Notes

This effectively implements self.species.count(m) but uses monomer_eq for equality, which ignores parent and position.

monomer_eq(other)

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)

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)

A more powerful printing function.

Useful for understanding CRNs but does not return string identifiers. show_material toggles whether species.material is printed. show_attributes toggles whether species.attributes is printed.

remove()

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)

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(position, part, direction=None)

Replace a monomer at a specific position in the polymer.

Removes the monomer at the given position and inserts a copy of the new monomer in its place. Calls the changed callback after replacement.

Parameters:

• position (int) – Index of the monomer to replace. Must be a valid position in the polymer.

• part (OrderedMonomer) – The monomer to insert. A copy of this monomer will be added.

• direction (str, int, or None, optional) – Direction for the new monomer. If None, uses the monomer’s existing direction.

See also

insert

Insert a monomer at a specific position.

delpart

Remove a monomer from the polymer.

Notes

The removed monomer’s remove method is called to clear its parent, position, and direction attributes.

replace_species(species: Species, new_species: Species)

Replaces species with new_species in the entire Complex Species.

Acts recursively on nested ComplexSpecies.

reverse()

Reverse the order and directions of all monomers in the polymer.

Reverses the polymer sequence and inverts the direction of each monomer. Updates all monomer positions to reflect their new locations. Calls the changed callback after reversal.

Notes

This operation modifies the polymer in place. All monomers have their directions inverted using direction_invert and their positions updated to match the reversed sequence.

Examples

>>> mon1 = bcp.OrderedMonomer()
>>> mon2 = bcp.OrderedMonomer()
>>> polymer = bcp.OrderedPolymer(
...     parts=[[mon1, 'forward'], [mon2, 'reverse']]
... )
>>> polymer.reverse()
>>> polymer[0].direction
'forward'
>>> polymer[1].direction
'reverse'

set_dir(direction)

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

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.