Polymer

  1. Linear

class Linear(repeating_unit, num_repeating_units, orientations=None, random_seed=None, num_processes=1)

Bases: stk.molecular.topology_graphs.topology_graph.TopologyGraph

Represents a linear polymer topology graph.

vertices

The vertices which make up the topology graph.

Type

tuple of Vertex

edges

The edges which make up the topology graph.

Type

tuple of Edge

Examples

Linear polymers require building blocks with functional groups

import stk

bb1 = stk.BuildingBlock('NCCN', ['amine'])
bb2 = stk.BuildingBlock('O=CCC=O', ['aldehyde'])
polymer = stk.ConstructedMolecule(
    building_blocks=[bb1, bb2],
    topology_graph=stk.polymer.Linear('AB', 12)
)

However building blocks with a single functional group can also be provided as capping units

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

# p1 and p2 are different ways to write the same thing.
p1 = stk.ConstructedMolecule(
    building_blocks=[bb1, bb2, bb3],
    topology_graph=stk.polymer.Linear('ACB', 1)
)
p2 = stk.ConstructedMolecule(
    building_blocks=[bb1, bb2, bb3],
    topology_graph=stk.polymer.Linear((0, 2, 1), 1)
)

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

bb4 = stk.BuildingBlock('NCNCCN', ['amine'])

p3 = stk.ConstructedMolecule(
    building_blocks=[bb2, bb4],
    topology_graph=stk.polymer.Linear(
        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 Linear

# chain will always construct the same polymer.
chain = stk.polymer.Linear(
    repeating_unit='AB',
    num_repeating_untis=5,
    orientations=(0.65, 0.45)
)
# p4 and p5 are guaranteed to be the same as they used the same
# topology graph.
p4 = stk.ConstructedMolecule([bb2, bb4], chain)
p5 = stk.ConstructedMolecule([bb2, bb4], chain)

# chain2 may lead to a different polymer than chain, despite
# being initialized with the same parameters.
chain2 = stk.polymer.Linear(
    repeating_unit='AB',
    num_repeating_untis=5,
    orientations=(0.65, 0.45)
)

# p6 and p7 are guaranteed to be the same because they used the
# the same topology graph. However, they may be different to
# p4 and p5.
p6 = stk.ConstructedMolecule([bb2, bb4], chain2)
p7 = stk.ConstructedMolecule([bb2, bb4], chain2)

The random_seed parameter can be used to get reproducible results

# p8 and p9 are guaranteed to be the same, because chain3 and
# chain4 used the same random seed.

chain3 = stk.polymer.Linear(
    repeating_unit='AB',
    num_repeating_untis=5,
    orientations=(0.65, 0.45),
    random_seed=4
)
p8 = stk.ConstructedMolecule([bb2, bb4], chain3)

chain4 = stk.polymer.Linear(
    repeating_unit='AB',
    num_repeating_untis=5,
    orientations=(0.65, 0.45),
    random_seed=4
)
p9 = stk.ConstructedMolecule([bb2, bb4], chain4)

Methods

assign_building_blocks_to_vertices(self, …)

Assign building_blocks to vertices.

construct(self, mol)

Construct a ConstructedMolecule.
__init__(self, repeating_unit, num_repeating_units, orientations=None, random_seed=None, num_processes=1)

Initialize a Linear instance.

Parameters

  • repeating_unit (str or tuple of int) –

    A string specifying the repeating unit of the polymer. 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 polymer.

  • orientations (tuple of float, optional) –

    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 all cases.

    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 (int, optional) – The random seed to use when choosing random orientations.

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

Raises

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

assign_building_blocks_to_vertices(self, building_blocks)

Assign building_blocks to vertices.

Parameters

building_blocks (list of Molecule) – The BuildingBlock and ConstructedMolecule instances which represent the building block molecules used for construction. Only one instance is present per building block molecule, even if multiples of that building block join up to form the ConstructedMolecule.

Returns

Maps the building_blocks, to the Vertex objects in vertices they are placed on during construction. The dict has the form

building_block_vertices = {
    BuildingBlock(...): [Vertex(...), Vertex(...)],
    BuildingBlock(...): [
        Vertex(...),
        Vertex(...),
        Vertex(...),
    ]
    ConstructedMolecule(...): [Vertex(...)]
}

Return type

dict

construct(self, mol)

Construct a ConstructedMolecule.

Parameters

mol (ConstructedMolecule) – The ConstructedMolecule instance which needs to be constructed.

Returns

None

Return type

NoneType