Macrocycle

class Macrocycle(building_blocks, repeating_unit, num_repeating_units, orientations=None, random_seed=None, reaction_factory=GenericReactionFactory(), num_processes=1, optimizer=<stk.molecular.topology_graphs.topology_graph.optimizers.null.NullOptimizer object>)[source]

Bases: TopologyGraph

Represents a macrocycle topology graph.

Building blocks with two functional groups are required for this topology.

Examples

Construction

This topology graph essentially makes a polymer chain and joins the ends, hence the constructor parameters allows you to specify the chain

import stk

macrocycle = stk.ConstructedMolecule(
    topology_graph=stk.macrocycle.Macrocycle(
        building_blocks=(
            stk.BuildingBlock(
                smiles='BrCCBr',
                functional_groups=[stk.BromoFactory()],
            ),
            stk.BuildingBlock(
                smiles='BrCNCBr',
                functional_groups=[stk.BromoFactory()],
            ),
        ),
        repeating_unit='AB',
        num_repeating_units=5,
    ),
)

Suggested Optimization

For Macrocycle topologies, it is recommended to use the MCHammer optimizer.

import stk

macrocycle = stk.ConstructedMolecule(
    topology_graph=stk.macrocycle.Macrocycle(
        building_blocks=(
            stk.BuildingBlock(
                smiles='BrCCBr',
                functional_groups=[stk.BromoFactory()],
            ),
            stk.BuildingBlock(
                smiles='BrCNCBr',
                functional_groups=[stk.BromoFactory()],
            ),
        ),
        repeating_unit='AB',
        num_repeating_units=5,
        optimizer=stk.MCHammer(),
    ),
)

Defining the Orientation of Each Building Block

The orientations parameter allows the direction of each building block along to the chain to be flipped

import stk

bb1 = stk.BuildingBlock('BrCCBr', [stk.BromoFactory()])
bb2 = stk.BuildingBlock('BrCOCCBr', [stk.BromoFactory()])

c1 = stk.ConstructedMolecule(
    topology_graph=stk.macrocycle.Macrocycle(
        building_blocks=(bb1, bb2),
        repeating_unit='AB',
        num_repeating_units=5,
        orientations=(1, 0.5),
    ),
)

In the above example, bb1 is guaranteed to be flipped, bb2 has a 50% chance of being flipped, each time it is placed on a node.

Note that whether a building block will be flipped or not is decided during the initialization of Macrocycle

# cycle will always construct the same macrocycle.
cycle = stk.macrocycle.Macrocycle(
    building_blocks=(bb1, bb2),
    repeating_unit='AB',
    num_repeating_units=5,
    orientations=(0.65, 0.45),
)
# c2 and c3 are guaranteed to be the same as they used the
# same topology graph.
c2 = stk.ConstructedMolecule(cycle)
c3 = stk.ConstructedMolecule(cycle)

# cycle2 may lead to a different polymer than chain,
# despite being initialized with the same parameters.
cycle2 = stk.macrocycle.Macrocycle(
    building_blocks=(bb1, bb2),
    repeating_unit='AB',
    num_repeating_units=5,
    orientations=(0.65, 0.45)
)

# c4 and c5 are guaranteed to be the same because they used
# the same topology graph. However, they may be different
# to c2 and c3.
c4 = stk.ConstructedMolecule(cycle2)
c5 = stk.ConstructedMolecule(cycle2)

The random_seed parameter can be used to get reproducible results

# c6 and c7 are guaranteed to be the same, because cycle3
# and cycle4 used the same random seed.

cycle3 = stk.macrocycle.Macrocycle(
    building_blocks=(bb1, bb2),
    repeating_unit='AB',
    num_repeating_units=5,
    orientations=(0.65, 0.45),
    random_seed=4,
)
c6 = stk.ConstructedMolecule(cycle3)

cycle4 = stk.macrocycle.Macrocycle(
    building_blocks=(bb1, bb2),
    repeating_unit='AB',
    num_repeating_units=5,
    orientations=(0.65, 0.45),
    random_seed=4,
)
c7 = stk.ConstructedMolecule(cycle4)

Using Numbers to Define the Repeating Unit

The repeating unit can also be specified through the indices of the building blocks

import stk

bb1 = stk.BuildingBlock('BrCCBr', [stk.BromoFactory()])
bb2 = stk.BuildingBlock('BrCNCBr', [stk.BromoFactory()])
bb3 = stk.BuildingBlock('BrCNNCBr', [stk.BromoFactory()])

# c1 and c2 are different ways to write the same thing.
c1 = stk.ConstructedMolecule(
    topology_graph=stk.macrocycle.Macrocycle(
        building_blocks=(bb1, bb2, bb3),
        repeating_unit='ACB',
        num_repeating_units=3
    )
)
c2 = stk.ConstructedMolecule(
    topology_graph=stk.macrocycle.Macrocycle(
        building_blocks=(bb1, bb2, bb3),
        repeating_unit=(0, 2, 1),
        num_repeating_units=3,
    )
)

Methods

`clone`()	Return a clone.
`construct`()	Construct a `ConstructedMolecule`.
`get_building_blocks`()	Yield the building blocks.
`get_num_building_block`(building_block)	Get the number of times building_block is present.
`with_building_blocks`(building_block_map)	Return a clone holding different building blocks.

__init__(building_blocks, repeating_unit, num_repeating_units, orientations=None, random_seed=None, reaction_factory=GenericReactionFactory(), num_processes=1, optimizer=<stk.molecular.topology_graphs.topology_graph.optimizers.null.NullOptimizer object>)[source]

Initialize a Macrocycle instance.

Parameters:

building_blocks (tuple[BuildingBlock, ...]) – The building blocks of the macrocycle.
repeating_unit (Union[str, tuple[int, ...]]) –
A string specifying the repeating unit of the macrocycle. For example, 'AB' or 'ABB'. The first building block passed to building_blocks is 'A' and so on.

The repeating unit can also be specified by the indices of building_blocks, for example 'ABB' can be written as (0, 1, 1).
num_repeating_units (int) – The number of repeating units which are used to make the macrocycle.
orientations (Optional[tuple[float, ...]]) –
For each character in the repeating unit, a value between 0 and 1 (both inclusive) must be given in a tuple. It indicates the probability that each monomer will have its orientation along the chain flipped. If 0 then the monomer is guaranteed not to flip. If 1 it is guaranteed to flip. This allows the user to create head-to-head or head-to-tail chains, as well as chain with a preference for head-to-head or head-to-tail if a number between 0 and 1 is chosen. If None, then 0 is picked in every case.

It is also possible to supply an orientation for every vertex in the final topology graph. In this case, the length of orientations must be equal to len(repeating_unit)*num_repeating_units.
random_seed (Optional[int]) – The random seed to use when choosing random orientations.
num_processes (int) – The number of parallel processes to create during construct().
optimizer (Optimizer) – Used to optimize the structure of the constructed molecule.

Raises:

ValueError – If the length of orientations is not equal in length to repeating_unit or to the total number of vertices.

clone()[source]

Return a clone.

Return type:: Macrocycle
Returns:: The clone.

construct()

Construct a ConstructedMolecule.

Return type:: ConstructionResult
Returns:: The data describing the ConstructedMolecule.

get_building_blocks()

Yield the building blocks.

Building blocks are yielded in an order based on their position in the topology graph. For two equivalent topology graphs, but with different building blocks, equivalently positioned building blocks will be yielded at the same time.

Yields:: A building block of the topology graph.
Return type:: Iterator[BuildingBlock]

get_num_building_block(building_block)

Get the number of times building_block is present.

Parameters:: building_block (BuildingBlock) – The building block whose frequency in the topology graph is desired.
Return type:: int
Returns:: The number of times building_block is present in the topology graph.

with_building_blocks(building_block_map)[source]

Return a clone holding different building blocks.

Parameters:: building_block_map (dict[BuildingBlock, BuildingBlock]) – Maps a building block in the current topology graph to the building block which should replace it in the clone. If a building block should be not replaced in the clone, it can be omitted from the map.
Return type:: Macrocycle
Returns:: The clone.