stk.TopologyGraph

class stk.TopologyGraph(building_block_vertices, edges, reaction_factory, construction_stages, num_processes, optimizer, edge_groups=None, scale_multiplier=1.0)

Bases: object

An abstract base class for topology graphs.

It is responsible for the construction of molecules. To create a new topology graph, you want to subclass and implement this abstract base class.

Notes

Adding New Topology Graphs

You might notice that some of the methods of this abstract base class are implemented. This is purely for convenience when implementing subclasses. The implemented public methods are simply default implementations, which can safely be ignored or overridden, when implementing subclasses. Any private methods are implementation details of these default implementations.

Many classes, such as Vertex, Edge, EdgeGroup and ConstructionState, exist as implementation details of this default TopologyGraph implementation. You could ignore all of them, and define a new construct() method from scratch. In fact, your topology graph does not have to be represented as a graph at all. However, using the default implementation of TopologyGraph makes it significantly easier to implement a construction process. When using the default implementation of TopologyGraph, you mostly just need to implement a Vertex subclass, which is much easier than figuring out the whole construction process from scratch. In addition, you get benefits like parallel construction for free, as it is included in the default implementation.

Typically, adding a new topology graph will involve implementing any pure virtual methods of TopologyGraph, in a new subclass, as well as implementing any pure virtual methods of Vertex, again in a new subclass. Combined, this is just a handful of simple methods to implement. Sometimes, rarely, you might also want to subclass ConstructionState, when you want to add additional hooks during construction, by extending the methods of this class. If you do this, make sure to override _get_construction_state() to return your subclass of ConstructionState, rather than the base class, as is done by default. You can subclass and extend the methods of any class as you wish, but it would be unusual if this doesn’t cover all your requirements.

The Default Implementation

The default implementation of TopologyGraph represents the constructed molecule through a graph. The vertices indicate where building blocks are placed and the edges indicate which building blocks have bonds formed between them by the construction process.

Vertex instances are responsible for placing the building block molecules. By initializing the vertices with different parameters, you can alter how they position the building block molecules, and therefore allow the user to easily specify a different structural isomer.

Once a building block is placed on a vertex, the functional groups on the building block must be mapped to the different edges connected to the vertex. The number of functional groups in the building block must match the number of edges connected to the vertex.

Once the functional groups are mapped to edges, the edges are used to perform reactions on the building blocks. Edges are grouped in an EdgeGroup, and all functional groups present in the edge group are reacted together. Normally, unless you are doing something very exotic, an EdgeGroup will hold just one Edge, and the two functional groups on that edge will be reacted together through a single Reaction. This reaction will normally add the bonds which are required to form the joined-up constructed molecule, but note that it does not have to add any bonds at all. In addition, a Reaction can add and remove atoms from the constructed molecule. Which reaction is selected to join the functional groups depends on the ReactionFactory given to the TopologyGraph during initialization.

Once this is done, you have a ConstructedMolecule.

Examples

Subclass Implementation

The source code of subclasses, listed in topology_graph, can serve as good examples.

Changing the Building Blocks of a Topology Graph

To change the building blocks used by a topology graph you can use with_building_blocks() to get a clone of the topology graph holding the new building blocks

import stk

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

linear = stk.polymer.Linear(
    building_blocks=(bb1, bb2),
    repeating_unit='A',
    num_repeating_units=15,
)

bb3 = stk.BuildingBlock('BrCNCBr', [stk.BromoFactory()])
# All bb1 instances are replaced by bb3, but bb2 remains
# in place.
clone = linear.with_building_blocks({
    bb1: bb3,
})

Parameters:

• building_block_vertices (dict[BuildingBlock, Sequence[Vertex]]) – Maps each BuildingBlock to be placed, to the Vertex instances, on which it should be placed.

• edges (tuple[Edge, ...]) – The edges which make up the topology graph.

• reaction_factory (ReactionFactory) – Used to pick which Reaction is used on each EdgeGroup of the topology graph.

• construction_stages (tuple[Callable[[Vertex], bool], ...]) –

  A collection of Callable, each of which takes a Vertex and returns True or False. If the first Callable is applied to a vertex in the topology graph, and the result is True, that vertex is a part of the first construction stage. The second callable is then applied to all vertices not in the first stage and those which return True belong to the second stage and so on.

  Vertices which belong to the same construction stage all place building blocks together in parallel, before placement is done by any vertices which are part of a later stage. This breaks down parallel construction into serial stages if synchronization between stages is needed.

  If the topology graph is performing construction serially, then all vertices which belong to an earlier stage will place their building block before those at a later stage.

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

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

• edge_groups (tuple[EdgeGroup, ...] | None) – The edge groups of the topology graph, if None, every Edge is in its own edge group.

• scale_multiplier (float) – Scales the positions of the vertices.

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

Return a clone.

Returns:

The clone.

Return type:

Self

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