Mutation¶

Mutation is carried by Mutator objects. They inherit Mutator and define a method mutate(). This method must take a single molecule and return a mutant.

Examples of how mutators work can be seen the documentation of the various Mutator classes, for example RandomBuildingBlock, SimilarBuildingBlock or RandomMutation.

Making New Mutators¶

Mutators must simply inherit the Mutator class. This is an abstract base class and its virtual methods must be implemented.

exception MutationError¶

Bases: Exception

Used for errors which occuring during mutation operations.

__init__(self, /, *args, **kwargs)¶: Initialize self. See help(type(self)) for accurate signature.

args¶

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class Mutator¶

Bases: stk.calculators.base_calculators.EAOperation

Creates mutants.

Methods

`mutate`(self, mol)	Return a mutant of mol.
`set_cache_use`(self, use_cache)	Set use of the molecular cache on or off.

__init__(self, /, *args, **kwargs)¶: Initialize self. See help(type(self)) for accurate signature.

mutate(self, mol)¶

Return a mutant of mol.

Parameters: mol (Molecule) – The molecule to be mutated.
Returns: mol – The mutant.
Return type: Molecule

set_cache_use(self, use_cache)¶

Set use of the molecular cache on or off.

Parameters: use_cache (bool) – True if the molecular cache is to be used.
Returns: The calculator.
Return type: EAOperation
Raises: NotImplementedError – This is a virtual method and needs to be implemented in a subclass.

class RandomBuildingBlock(building_blocks, key, duplicate_building_blocks=False, random_seed=None, use_cache=False)¶

Bases: stk.calculators.base_calculators._EAOperation, stk.calculators.ea.mutators.Mutator

Substitutes random building blocks.

This mutator takes a ConstructedMolecule and substitutes the building blocks with one chosen at random from a given set.

Examples

import stk

# Create a molecule which is to be mutated.
bb1 = stk.BuildingBlock('NCCN', ['amine'])
bb2 = stk.BuildingBlock('O=CCC=O', ['aldehyde'])
polymer = stk.ConstructedMolecule(
    building_blocks=[bb1, bb2],
    topology_graphs=stk.polymer.Linear('AB', [0, 0], n=3)
)

# Create molecules used to substitute building blocks.
building_blocks = [
    stk.BuildingBlock('NC[Si]CCN', ['amine']),
    stk.BuildingBlock('NCCCCCCCN', ['amine']),
    stk.BuildingBlock('NC1CCCCC1N', ['amine'])
]

# Create the mutator.
random_bb = stk.RandomBuildingBlock(
    building_blocks=building_blocks,
    key=lambda mol: mol.func_groups[0].fg_type.name == 'amine'
)

# Mutate a molecule.
mutant1 = random_bb.mutate(polymer)

# Mutate the molecule a second time.
mutant2 = random_bb.mutate(polymer)

# Mutate a mutant.
mutant3 = random_bb.mutate(mutant1)

Methods

`mutate`(self, mol)	Return a mutant of mol.
`set_cache_use`(self, use_cache)	Set use of the molecular cache on or off.

__init__(self, building_blocks, key, duplicate_building_blocks=False, random_seed=None, use_cache=False)¶

Initialize a RandomBuildingBlock instance.

Parameters

building_blocks (tuple of Molecule) – A group of molecules which are used to replace building blocks in molecules being mutated.
key (function) – A function which takes a Molecule and returns True or False. This function is applied to every building block in the molecule being mutated. Building blocks which returned True are liable for substition by one of the molecules in building_blocks.
duplicate_building_blocks (bool, optional) – Indicates whether the building blocks used to construct the mutant must all be unique.
random_seed (bool, optional) – The random seed to use.
use_cache (bool, optional) – Toggles use of the molecular cache.

mutate(self, mol)¶

Return a mutant of mol.

Parameters: mol (Molecule) – The molecule to be mutated.
Returns: mol – The mutant.
Return type: Molecule

set_cache_use(self, use_cache)¶

Set use of the molecular cache on or off.

Parameters: use_cache (bool) – True if the molecular cache is to be used.
Returns: The calculator.
Return type: EAOperation

class RandomTopologyGraph(topology_graphs, random_seed=None, use_cache=False)¶

Bases: stk.calculators.base_calculators._EAOperation, stk.calculators.ea.mutators.Mutator

Changes topology graphs at random.

Examples

import stk

# Create a molecule which is to be mutated.
bb1 = stk.BuildingBlock('NCCN', ['amine'])
bb2 = stk.BuildingBlock('O=CCC(=O)CC=O', ['aldehyde'])
cage = stk.ConstructedMolecule(
    building_blocks=[bb1, bb2],
    topology_graph=stk.cage.FourPlusSix()
)

# Create topologies used for substition.
topology_graphs = [
    stk.cage.TwoPlusThree(),
    stk.cage.EightPlusTwelve(),
    stk.cage.TwentyPlusThirty()
]

# Create the mutator.
random_topology = stk.RandomTopologyGraph(topology_graphs)

# Mutate a molecule.
mutant1 = random_topology.mutate(cage)

# Mutate the molecule a second time.
mutant2 = random_topology.mutate(cage)

# Mutate a mutant.
mutant3 = random_topology.mutate(mutant1)

Methods

`mutate`(self, mol)	Return a mutant of mol.
`set_cache_use`(self, use_cache)	Set use of the molecular cache on or off.

__init__(self, topology_graphs, random_seed=None, use_cache=False)¶

Initialize a RandomTopology instance.

Parameters

topology_graphs (list of TopologyGraph) – This lists holds the topology instances from which one is selected at random to form a new molecule.
random_seed (bool, optional) – The random seed to use.
use_cache (bool, optional) – Toggles use of the molecular cache.

mutate(self, mol)¶

Return a mutant of mol.

Parameters: mol (Molecule) – The molecule to be mutated.
Returns: mol – The mutant.
Return type: Molecule

set_cache_use(self, use_cache)¶

Set use of the molecular cache on or off.

Parameters: use_cache (bool) – True if the molecular cache is to be used.
Returns: The calculator.
Return type: EAOperation

class SimilarBuildingBlock(building_blocks, key, duplicate_building_blocks, random_seed=None, use_cache=False)¶

Bases: stk.calculators.base_calculators._EAOperation, stk.calculators.ea.mutators.Mutator

Substitutes similar building blocks.

This mutator takes a ConstructedMolecule and substitutes the building blocks with the most similar one from a given set.

Examples

import stk

# Create a molecule which is to be mutated.
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', [0, 0], n=3)
)

# Create molecules used to substitute building blocks.
building_blocks = [
    stk.BuildingBlock('NC[Si]CCN', ['amine']),
    stk.BuildingBlock('NCCCCCCCN', ['amine']),
    stk.BuildingBlock('NC1CCCCC1N', ['amine'])
]

# Create the mutator.
similar_bb = stk.SimilarBuildingBlock(
    building_blocks=building_blocks,
    key=lambda mol: mol.func_groups[0].fg_type.name == 'amine'
)

# Mutate a molecule.
mutant1 = random_bb.mutate(polymer)

# Mutate the molecule a second time.
mutant2 = random_bb.mutate(polymer)

# Mutate a mutant.
mutant3 = random_bb.mutate(mutant1)

Methods

`mutate`(self, mol)	Return a mutant of mol.
`set_cache_use`(self, use_cache)	Set use of the molecular cache on or off.

__init__(self, building_blocks, key, duplicate_building_blocks, random_seed=None, use_cache=False)¶

Initialize a RandomBuildingBlock instance.

Parameters

building_blocks (tuple of Molecule) – A group of molecules which are used to replace building blocks in molecules being mutated.
key (function) – A function which takes a Molecule and returns True or False. This function is applied to every building block of the molecule being mutated. Building blocks which returned True are liable for substition by one of the molecules in building_blocks.
duplicate_building_blocks (bool, optional) – Indicates whether the building blocks used to construct the mutant must all be unique.
random_seed (bool, optional) – The random seed to use.
use_cache (bool, optional) – Toggles use of the molecular cache.

mutate(self, mol)¶

Return a mutant of mol.

Parameters: mol (Molecule) – The molecule to be mutated.
Returns: mol – The mutant.
Return type: Molecule

set_cache_use(self, use_cache)¶

Set use of the molecular cache on or off.

Parameters: use_cache (bool) – True if the molecular cache is to be used.
Returns: The calculator.
Return type: EAOperation