biocrnpyler.Complex

class biocrnpyler.Complex(*args, **kwargs)[source]

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:
specieslist of Species

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

orderedbool, 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
__init__(*args, **kwargs)

Methods

__init__(*args, **kwargs)

static __new__(cls, *args, **kwargs)[source]

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