stk.polymer.Linear
- class stk.polymer.Linear(building_blocks, repeating_unit, num_repeating_units, orientations=None, random_seed=None, reaction_factory=GenericReactionFactory(), num_processes=1, optimizer=<stk._internal.optimizers.null.NullOptimizer object>, scale_multiplier=1.0)[source]
Bases:
TopologyGraph
Represents a linear polymer topology graph.
Building blocks with two functional groups are required, unless the building block’s position is specified to only be at the capping positions.
Examples
Construction
Linear polymers require building blocks with two functional groups
import stk bb1 = stk.BuildingBlock('NCCN', stk.PrimaryAminoFactory()) bb2 = stk.BuildingBlock('O=CCC=O', stk.AldehydeFactory()) polymer = stk.ConstructedMolecule( topology_graph=stk.polymer.Linear( building_blocks=[bb1, bb2], repeating_unit='AB', num_repeating_units=4, ), )
Suggested Optimization
For
Linear
topologies, it is recommend to use theCollapser
optimizer.import stk bb1 = stk.BuildingBlock('NCCN', stk.PrimaryAminoFactory()) bb2 = stk.BuildingBlock('O=CCC=O', stk.AldehydeFactory()) polymer = stk.ConstructedMolecule( topology_graph=stk.polymer.Linear( building_blocks=[bb1, bb2], repeating_unit='AB', num_repeating_units=4, # Setting scale_steps to False tends to lead to a # better structure. optimizer=stk.Collapser(scale_steps=False), ), )
Construction with Capping Units
Building blocks with a single functional group can also be provided as capping units
import stk bb1 = stk.BuildingBlock('NCC(F)N', stk.PrimaryAminoFactory()) bb2 = stk.BuildingBlock('O=CCC=O', stk.AldehydeFactory()) bb3 = stk.BuildingBlock('BrCCN', stk.PrimaryAminoFactory()) polymer = stk.ConstructedMolecule( topology_graph=stk.polymer.Linear( building_blocks=[bb1, bb2, bb3], repeating_unit='ABABC', num_repeating_units=1, ), )
Defining the Orientation of Each Building Block
The orientations parameter allows the direction of each building block along to the chain to be flipped
import stk bb1 = stk.BuildingBlock('O=CCC=O', stk.AldehydeFactory()) bb2 = stk.BuildingBlock('NC(Br)CN', stk.PrimaryAminoFactory()) p1 = stk.ConstructedMolecule( topology_graph=stk.polymer.Linear( building_blocks=[bb1, bb2], 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( building_blocks=[bb1, bb2], repeating_unit='AB', num_repeating_units=5, orientations=[0.65, 0.45], ) # p2 and p3 are guaranteed to be the same as they used the # same topology graph. p2 = stk.ConstructedMolecule(chain) p3 = stk.ConstructedMolecule(chain) # chain2 may lead to a different polymer than chain, # despite being initialized with the same parameters. chain2 = stk.polymer.Linear( building_blocks=[bb1, bb2], repeating_unit='AB', num_repeating_units=5, orientations=[0.65, 0.45] ) # p4 and p5 are guaranteed to be the same because they used # the same topology graph. However, they may be different # to p2 and p3. p4 = stk.ConstructedMolecule(chain2) p5 = stk.ConstructedMolecule(chain2)
The random_seed parameter can be used to get reproducible results
# p6 and p7 are guaranteed to be the same, because chain3 # and chain4 used the same random seed. chain3 = stk.polymer.Linear( building_blocks=[bb1, bb2], repeating_unit='AB', num_repeating_units=5, orientations=[0.65, 0.45], random_seed=4, ) p6 = stk.ConstructedMolecule(chain3) chain4 = stk.polymer.Linear( building_blocks=[bb1, bb2], repeating_unit='AB', num_repeating_units=5, orientations=[0.65, 0.45], random_seed=4, ) p7 = stk.ConstructedMolecule(chain4)
Using Numbers to Define the Repeating Unit
The repeating unit can also be specified through the indices of the building blocks
import stk bb1 = stk.BuildingBlock('NCCN', stk.PrimaryAminoFactory()) bb2 = stk.BuildingBlock('O=CCC=O', stk.AldehydeFactory()) bb3 = stk.BuildingBlock('NCCN', stk.PrimaryAminoFactory()) # p1 and p2 are different ways to write the same thing. p1 = stk.ConstructedMolecule( topology_graph=stk.polymer.Linear( building_blocks=[bb1, bb2, bb3], repeating_unit='ACB', num_repeating_units=1, ), ) p2 = stk.ConstructedMolecule( topology_graph=stk.polymer.Linear( building_blocks=[bb1, bb2, bb3], repeating_unit=[0, 2, 1], num_repeating_units=1, ), )
- Parameters:
building_blocks (list[BuildingBlock]) – The building blocks of the polymer.
repeating_unit (str | list[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.
For each character in the repeating unit, a value between
0
and1
(both inclusive). It indicates the probability that each monomer will have its orientation along the chain flipped. If0
then the monomer is guaranteed not to flip. If1
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 between0
and1
is chosen. IfNone
then0
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
.If there is only one building block in the constructed polymer i.e. the repeating_unit has a length of 1 and num_repeating_units is 1, the building block will not be re-oriented, even if you provide a value to orientations.
random_seed (int | Generator | None) – The random seed to use when choosing random orientations.
reaction_factory (ReactionFactory) – The factory to use for creating reactions between functional groups of building blocks.
num_processes (int) – The number of parallel processes to create during
construct()
.optimizer (Optimizer) – Used to optimize the structure of the constructed molecule.
scale_multiplier (float) – Scales the positions of the vertices.
- Raises:
ValueError – If the length of orientations is not equal in length to repeating_unit or to the total number of vertices.
Methods
Return a clone.
Construct a
ConstructedMolecule
.Yield the building blocks.
Get the number of times building_block is present.
Return a clone holding different building blocks.
- construct()
Construct a
ConstructedMolecule
.- Returns:
The data describing the
ConstructedMolecule
.- Return type:
- 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:
- 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:
- with_building_blocks(building_block_map)[source]
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: