stk.host_guest.Complex

class stk.host_guest.Complex(host, guests, num_processes=1, optimizer=<stk._internal.optimizers.null.NullOptimizer object>)[source]

Bases: TopologyGraph

Represents a host-guest complex topology graph.

Host and guest building blocks do not require functional groups.

Examples

Construction

You can use ConstructedMolecule instances as the host, but you should turn them into a BuildingBlock first. For guest molecules, you must define a Guest from a BuildingBlock.

import stk

host = stk.ConstructedMolecule(
    topology_graph=stk.cage.FourPlusSix(
        building_blocks=(
            stk.BuildingBlock(
                smiles='NC1CCCCC1N',
                functional_groups=[
                    stk.PrimaryAminoFactory(),
                ],
            ),
            stk.BuildingBlock(
                smiles='O=Cc1cc(C=O)cc(C=O)c1',
                functional_groups=[stk.AldehydeFactory()],
            ),
        ),
        optimizer=stk.MCHammer(),
    ),
)
complex = stk.ConstructedMolecule(
    topology_graph=stk.host_guest.Complex(
        host=stk.BuildingBlock.init_from_molecule(host),
        guests=stk.host_guest.Guest(
            building_block=stk.BuildingBlock('[Br][Br]'),
        ),
    ),
)

You can also generate complexes with multiple Guest molecules.

import stk

host = stk.ConstructedMolecule(
    topology_graph=stk.cage.FourPlusSix(
        building_blocks=(
            stk.BuildingBlock(
                smiles='NC1CCCCC1N',
                functional_groups=[
                    stk.PrimaryAminoFactory(),
                ],
            ),
            stk.BuildingBlock(
                smiles='O=Cc1cc(C=O)cc(C=O)c1',
                functional_groups=[stk.AldehydeFactory()],
            ),
        ),
        optimizer=stk.MCHammer(),
    ),
)
guest1 = stk.host_guest.Guest(
    building_block=stk.BuildingBlock('BrBr'),
    displacement=(0., 3., 0.),
)
guest2 = stk.host_guest.Guest(
    building_block=stk.BuildingBlock('C1CCCC1'),
)

complex = stk.ConstructedMolecule(
    topology_graph=stk.host_guest.Complex(
        host=stk.BuildingBlock.init_from_molecule(host),
        guests=(guest1, guest2),
    ),
)

Suggested Optimization

For Complex topologies, it is recommended to use the Spinner optimizer. It is also recommended that the building blocks are already optimized prior to construction. This optimizer will work on multi-guest systems.

import stk

host = stk.ConstructedMolecule(
    topology_graph=stk.cage.FourPlusSix(
        building_blocks=(
            stk.BuildingBlock(
                smiles='NC1CCCCC1N',
                functional_groups=[
                    stk.PrimaryAminoFactory(),
                ],
            ),
            stk.BuildingBlock(
                smiles='O=Cc1cc(C=O)cc(C=O)c1',
                functional_groups=[stk.AldehydeFactory()],
            ),
        ),
        optimizer=stk.MCHammer(),
    ),
)
guest1 = stk.host_guest.Guest(
    building_block=stk.BuildingBlock('BrBr'),
    displacement=(0., 3., 0.),
)
guest2 = stk.host_guest.Guest(
    building_block=stk.BuildingBlock('C1CCCC1'),
)

complex = stk.ConstructedMolecule(
    topology_graph=stk.host_guest.Complex(
        host=stk.BuildingBlock.init_from_molecule(host),
        guests=(guest1, guest2),
        optimizer=stk.Spinner(),
    ),
)

Changing the Position of the Guest

You can change the position and orientation of the Guest.

import stk

host = stk.ConstructedMolecule(
    topology_graph=stk.cage.FourPlusSix(
        building_blocks=(
            stk.BuildingBlock(
                smiles='BrCCBr',
                functional_groups=[stk.BromoFactory()],
            ),
            stk.BuildingBlock(
                smiles='BrCC(Br)CBr',
                functional_groups=[stk.BromoFactory()],
            ),
        ),
    ),
)

guest_building_block = stk.BuildingBlock('[Br][Br]')
guest = stk.host_guest.Guest(
    building_block=guest_building_block,
    # Apply a rotation onto the guest molecule such that
    # the vector returned by get_direction() has the same
    # direction as [1, 1, 1].
    start_vector=guest_building_block.get_direction(),
    end_vector=[1, 1, 1],
    # Change the displacement of the guest.
    displacement=[5.3, 2.1, 7.1],
)
complex = stk.ConstructedMolecule(
    topology_graph=stk.host_guest.Complex(
        host=stk.BuildingBlock.init_from_molecule(host),
        guests=guest,
    ),
)

Tip

The host of a Complex will always be placed at the origin, not at the centroid of the input building block. Therefore, to place a guest at the centroid of the host use displacement=(0, 0, 0), which is the default behaviour.

Initialize an instance of Complex.

Parameters:

host (BuildingBlock) – The host molecule.
guests (Union[Guest, abc.Iterable[Guest]]) – The guest molecules. Can be a single Guest instance if only one guest is being used.
num_processes (int) – The number of parallel processes to create during construct().
optimizer (Optimizer) – Used to optimize the structure of the constructed molecule.

Methods

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

clone()[source]

Return a clone.

Returns:: The clone.
Return type:: Complex

construct()

Construct a ConstructedMolecule.

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

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.
Returns:: The number of times building_block is present in the topology graph.
Return type:: int

with_building_blocks(building_block_map)

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.
Returns:: The clone.
Return type:: Self