Host Guest Complex

class Complex(host, guest=None, guest_start=None, guest_target=None, displacement=None, guests=None, 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, guest=None, guest_start=None, guest_target=None, displacement=None, guests=None, 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 (Optional[Iterable[Guest]]) – The guest molecules. Can be a single Guest instance if only one guest is being used.

  • guest (Optional[BuildingBlock]) – The guest molecule. This API is deprecated and will be removed in any stk version released on, or after, 01/01/2022. Use the guests parameter instead.

  • guest_start (Optional[tuple[float, float, float]]) – A direction vector which gets aligned with guest_target. This API is deprecated and will be removed in any stk version released on, or after, 01/01/2022. Use the guests parameter instead.

  • guest_target (Optional[tuple[float, float, float]]) – A direction vector which determines the rotation applied to the guest. A rotation such that guest_start is transformed into guest_target is applied. This API is deprecated and will be removed in any stk version released on, or after, 01/01/2022. Use the guests parameter instead.

  • displacement (Optional[tuple[float, float, float]]) – The translational offset of the guest. This API is deprecated and will be removed in any stk version released on, or after, 01/01/2022. Use the guests parameter instead.

  • num_processes (int) – The number of parallel processes to create during construct().

  • optimizer (Optimizer) – Used to optimize the structure of the constructed molecule.

Raises
  • TypeError – If guest_start or guest_target is defined but the other is not.

  • ValueError – If the old API and new API are used simultaneously.

  • RuntimeError – If no guests are provided.

Return type

None

clone()[source]

Return a clone.

Returns

The clone. Has the same type as the original topology graph.

Return type

TopologyGraph

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

BuildingBlock – A building block of the topology graph.

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) – 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. Has the same type as the original topology graph.

Return type

TopologyGraph

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.

Return type

None

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.