biocrnpyler.core.Complex

class biocrnpyler.core.Complex(*args, **kwargs)

Bases: object

Metaclass for creating chemical complexes.

Complex is not a class that gets instantiated directly - it creates instances of ComplexSpecies, OrderedComplexSpecies, OrderedPolymerSpecies, or PolymerConformation based on the input species and their parent relationships.

Parameters:

• species (list of Species) – List of species to combine into a complex. Can include standalone Species, Species with parents (monomers in polymers), or entire OrderedPolymerSpecies.

• ordered (bool, default False) – If True, creates OrderedComplexSpecies where species order matters. If False, creates ComplexSpecies where order is irrelevant.

• **kwargs – Additional keyword arguments passed to the created species class.

Returns:

• ComplexSpecies, OrderedComplexSpecies, OrderedPolymerSpecies, or

• PolymerConformation – The type of species returned depends on the input structure:

  • Simple species list -> ComplexSpecies or OrderedComplexSpecies

  • Monomers from one polymer -> OrderedPolymerSpecies

  • Monomers from multiple polymers/conformations -> PolymerConformation

See also

ComplexSpecies

Unordered complex of multiple species.

OrderedComplexSpecies

Ordered complex of multiple species.

OrderedPolymerSpecies

Polymer species for reactions.

PolymerConformation

Multiple polymers with connections.

Notes

The __new__ method implements logic for different scenarios:

1. No parents: Creates ComplexSpecies or OrderedComplexSpecies

2. Single polymer parent: Creates OrderedPolymerSpecies with complex at binding site

3. Multiple polymer parents or conformations: Creates PolymerConformation merging all complexes

4. Error cases: Raises exceptions for invalid combinations

The correct species type is automatically determined from the input, allowing flexible complex formation without explicit type selection.

Examples

Create a simple complex:

>>> S1 = bcp.Species('S1')
>>> S2 = bcp.Species('S2')
>>> complex = bcp.Complex([S1, S2])
>>> type(complex)
biocrnpyler.core.species.ComplexSpecies

Create an ordered complex:

>>> ordered = bcp.Complex([S1, S2], ordered=True)
>>> type(ordered)
biocrnpyler.core.species.OrderedComplexSpecies

Create a complex at a polymer binding site:

>>> S3 = bcp.Species('S3')
>>> polymer = bcp.OrderedPolymerSpecies([S1, S2])
>>> # S1 is now inside the polymer at position 0
>>> complex = bcp.Complex([polymer[0], S3])
>>> type(complex.parent)
biocrnpyler.core.species.OrderedPolymerSpecies

Methods

static __new__(cls, *args, **kwargs)

Create an instance of the appropriate species type.

This method analyzes the input species and their parent relationships to determine which type of complex to create.

Parameters:

• *args – Positional arguments, first should be the species list.

• **kwargs – Keyword arguments including ‘species’ and ‘ordered’.

Returns:

• ComplexSpecies, OrderedComplexSpecies, OrderedPolymerSpecies, or

• PolymerConformation – The appropriate species type based on input structure.

Raises:

• TypeError – If species argument is not a list, or if trying to complex entire OrderedPolymerSpecies that are already in PolymerConformations, or if invalid parent types are found.

• ValueError – If trying to form complexes between monomers from multiple OrderedPolymerSpecies without PolymerConformations.

Notes

Cases handled:

1. No Species have parents -> ComplexSpecies or 1OrderedComplexSpecies`

2. Single Species has parent OrderedPolymerSpecies (no parent) -> OrderedPolymerSpecies with complex at binding site

3. Multiple Species with OrderedPolymerSpecies1` parents (no parents) -> Error (must use PolymerConformations)

4. Entire OrderedPolymerSpecies in PolymerConformations -> Error

5. One or more Species from polymer Conformations -> PolymerConformation merging all complexes