biocrnpyler.core.ComplexSpecies

class biocrnpyler.core.ComplexSpecies(species: List[Species | str], name: str | None = None, material_type='complex', attributes=None, compartment=None, called_from_complex=False)

Bases: Species

Species formed from multiple bound species.

A special kind of species representing a complex of two or more bound species. ComplexSpecies should always be created using the Complex function, not directly. Order of species in the list does not matter: ComplexSpecies([s1, s2]) == ComplexSpecies([s2, s1]).

Parameters:

• species (list of Species or str) – List of species forming the complex. Must contain at least 2 species.

• name (str or None, optional) – Custom name for the complex. If None, generates a name from constituent species.

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

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

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

• called_from_complex (bool, default False) – Internal flag to enforce use of Complex function.

Attributes:

• species (list of Species) – Sorted list of constituent species in the complex.

• species_set (list of Species) – Unique species in the complex, sorted by string representation.

• name (str) – Name of the complex (auto-generated if not provided).

See also

Complex

Metaclass for creating ComplexSpecies.

OrderedComplexSpecies

Complex where species order matters.

Species

Base class for chemical species.

Notes

ComplexSpecies add an additional ‘_’ at the end of their string representation to differentiate edge cases.

Species order does not affect equality: ComplexSpecies([s1, s2]) == ComplexSpecies([s2, s1])

For ordered complexes, use OrderedComplexSpecies.

If no name is provided, the complex is named by concatenating all constituent species names with counts for duplicates.

Always use the Complex function to create ComplexSpecies:

>>> # Correct
>>> complex_species = bcp.Complex([S1, S2])

>>> # Incorrect (will raise warning)
>>> complex_species = bcp.ComplexSpecies([S1, S2])

Examples

Create a complex (using Complex function):

>>> S1 = bcp.Species('S1')
>>> S2 = bcp.Species('S2')
>>> complex_species = bcp.Complex([S1, S2])

Check if a species is in a complex:

>>> S1 in complex_species
True

Methods

add_attribute	Add an attribute to the species.
contains_species_monomer	Check if the species contains a monomer, ignoring context.
find_polymer_component	Find the polymer component within this monomer or its species.
flatten_list	Recursively flatten a nested list of species.
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.
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_species	Replace a species throughout the entire complex.
set_dir	Set the direction of the monomer and return self.
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.

__gt__(Species2)

Return self>value.

__lt__(Species2)

Return self<value.

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

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.

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]

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

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_species(species: Species, new_species: Species)

Replace a species throughout the entire complex.

Acts recursively on nested ComplexSpecies. Does not modify in place - returns a new ComplexSpecies.

Parameters:

• species (Species) – The species to replace.

• new_species (Species) – The species to replace with.

Returns:

A new ComplexSpecies with the replacement applied.

Return type:

ComplexSpecies

Raises:

ValueError – If either argument is not a Species instance.

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.