Host Guest Complex

class Complex(host, guests, num_processes=1, optimizer=<stk.molecular.topology_graphs.topology_graph.optimizers.null.NullOptimizer object>)[source]

Bases: stk.molecular.topology_graphs.topology_graph.topology_graph.topology_graph.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

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 guests.

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, as well as its displacement

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,
    ),
)

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__(host, guests, num_processes=1, optimizer=<stk.molecular.topology_graphs.topology_graph.optimizers.null.NullOptimizer object>)[source]

Initialize an instance of Complex.

Parameters
  • host (BuildingBlock) – The host molecule.

  • guests (Union[Guest, 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.

clone()[source]

Return a clone.

Return type

Complex

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)

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

TopologyGraph

Returns

The clone.

class Guest(building_block, start_vector=(1.0, 0.0, 0.0), end_vector=(1.0, 0.0, 0.0), displacement=(1.0, 0.0, 0.0))[source]

Bases: object

Holds the data defining the placement of a guest molecule.

Methods

get_building_block()

Return the building block.

get_displacement()

Return the displacement.

get_end_vector()

Return the end vector.

get_start_vector()

Return the start vector.

__init__(building_block, start_vector=(1.0, 0.0, 0.0), end_vector=(1.0, 0.0, 0.0), displacement=(1.0, 0.0, 0.0))[source]

Initialize a Guest instance.

Parameters
  • building_block (BuildingBlock) – The guest molecule.

  • start_vector (tuple[float, float, float]) – A direction vector which gets aligned with end_vector.

  • end_vector (tuple[float, float, float]) – A direction vector which determines the rotation applied to the building_block. A rotation such that start_vector is transformed into end_vector is applied.

  • displacement (tuple[float, float, float]) – The translational offset of the guest.

get_building_block()[source]

Return the building block.

Return type

BuildingBlock

Returns

The building block.

get_displacement()[source]

Return the displacement.

Return type

tuple[float, float, float]

Returns

The displacement.

get_end_vector()[source]

Return the end vector.

Return type

tuple[float, float, float]

Returns

The end vector.

get_start_vector()[source]

Return the start vector.

Return type

tuple[float, float, float]

Returns

The start vector.