Compound Calculators¶

If
TryCatch
Sequence
Random
RaisingCalculator

Compound calculators are calculators which are initialized with other calculators. They then control how and when those calculators are used.

Compound calculators are special, because they take on the class of the calculators they hold. This means that if you initialize a compound calculator of a certain class it will be indistinguishable from any other calculator of that class. For example, if you initialize a Sequence with Optimizer instances, it will be usable in the same way as any other Optimizer

import stk

sequence = stk.Sequence(
    stk.ETKDG(),
    stk.MMFF(),
)
mol = stk.BuildingBlock('NCCN')
sequence.optimize(mol)

Not all compound calculators can be used with every calculator type. A compound calculator is only compatible with classes with which it shares a base class. So if a compound calculator does not inherit EnergyCalculator, it cannot be used with instances of EnergyCalculator. However, if a compound calculator does inherit EnergyCalculator, it can be initialized with instances of EnergyCalculator and therefore it can also be used wherever an EnergyCalculator is required.

If you really want to build up complexity, compound calculators can hold other compound calculators. For example, this is an Optimizer, which will try to optimize a molecule with one Sequence and if it raises an error, it will try to optimize the molecule with a different Sequence

optimizer = stk.TryCatch(
    try_calculator=stk.Sequence(stk.ETKDG(), stk.MMFF()),
    catch_calculator=stk.Sequence(stk.ETKDG(), stk.UFF()),
)
# Try to optimize with ETKDG followed by MMFF first, and if that
# raises an error, try to optimize with ETKDG followed by
# UFF.
optimizer.optimize(mol)

class If(condition, true_calculator, false_calculator, use_cache=False)¶

Bases: stk.calculators.base_calculators._MoleculeCalculator, stk.calculators.ea.crossers.Crosser, stk.calculators.energy.energy_calculators.EnergyCalculator, stk.calculators.ea.fitness_calculators.FitnessCalculator, stk.calculators.ea.fitness_normalizers.FitnessNormalizer, stk.calculators.ea.mutators.Mutator, stk.calculators.optimization.optimizers.Optimizer, stk.calculators.ea.selectors.Selector

Use a condition to pick a calculator.

Examples

Use ETKDG to optimize the structure of a molecule if it has less than 200 atoms, else use the MMFF force field

import stk

optimizer = stk.If(
    condition=lambda mol: len(mol.atoms) < 200,
    true_calculator=stk.ETKDG(),
    false_calculator=stk.MMFF(),
)

# ETKDG will be run on this molecule.
small_mol = stk.BuildingBlock('NCCN', ['amine'])
optimizer.optimize(small_mol)

# MMFF will be run on polymer.
polymer = stk.ConstructedMolecule(
    building_blocks=[bb],
    topology_graph=stk.polymer.Linear('A', 500),
)
optimizer.optimize(polymer)

Methods

`add_to_cache`(self, mol[, value])	Add a molecule to the cache.
`cross`(self, \*mols)	Cross mols.
`get_cached_value`(self, mol)	Return the value stored in the cache for mol.
`get_energy`(self, mol)	Calculate the energy of mol.
`get_fitness`(self, mol)	Return the fitness value of mol.
`is_caching`(self)	`True` if the calculator has caching turned on.
`is_in_cache`(self, mol)	Return `True` if mol is cached.
`mutate`(self, mol)	Return a mutant of mol.
`normalize`(self, population)	Normalize the fitness values in population.
`optimize`(self, mol)	Optimize mol.
`select`(self, population[, included_batches, …])	Select batches of molecules from population.
`set_cache_use`(self, use_cache)	Toggle use of the cache.

__init__(self, condition, true_calculator, false_calculator, use_cache=False)¶

Initialize a If instance.

Parameters

condition (callable) – A callable which is passed the arguments which are to be passed to the calculators. If it returns True then true_calculator will be used, if False, then false_calculator will be used.
true_calculator (see base classes) – The calculator to use if condition returns True.
false_calculator (see base classes) – The calculator to use if condition returns False.
use_cache (bool, optional) – When If is used as a MoleculeCalculator, this toggles the results cache.

add_to_cache(self, mol, value=None)¶

Add a molecule to the cache.

Parameters

mol (Molecule) – The molecule to be added to the cache.
value (class:object, optional) – The cached value associated with the molecule.

Returns

The calculator.

Return type

MoleculeCalculator

cross(self, *mols)¶

Cross mols.

Parameters: *mols (Molecule) – The molecules on which a crossover operation is performed.
Yields: Molecule – The generated offspring.

get_cached_value(self, mol)¶

Return the value stored in the cache for mol.

Parameters: mol (Molecule) – The molecule whose cached value is to be returned.
Returns: The cached value.
Return type: object

get_energy(self, mol)¶

Calculate the energy of mol.

Parameters: mol (Molecule) – The Molecule whose energy is to be calculated.
Returns: The energy.
Return type: float

get_fitness(self, mol)¶

Return the fitness value of mol.

Parameters: mol (Molecule) – The molecule whose fitness value should be calculated.
Returns: The fitness value of mol.
Return type: object

is_caching(self)¶

True if the calculator has caching turned on.

Returns: True if the calculator has caching turned on.
Return type: bool

is_in_cache(self, mol)¶

Return True if mol is cached.

Parameters: mol (Molecule) – The molecule being checked.
Returns: True if mol is cached.
Return type: bool

mutate(self, mol)¶

Return a mutant of mol.

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

normalize(self, population)¶

Normalize the fitness values in population.

Parameters: population (EAPopulation) – The molecules which need to have their fitness values normalized.
Returns: Maps every molecule in population to its normalized fitness value.
Return type: dict

optimize(self, mol)¶

Optimize mol.

Parameters: mol (Molecule) – The molecule to be optimized.
Returns: None
Return type: NoneType

select(self, population, included_batches=None, excluded_batches=None)¶

Select batches of molecules from population.

Parameters

population (EAPopulation) – A collection of molecules from which batches are selected.
included_batches (set, optional) – The identity keys of batches which are allowed to be yielded, if None all batches can be yielded. If not None only batches included_batches will be yielded.
excluded_batches (class:set, optional) – The identity keys of batches which are not allowed to be yielded. If None, no batch is forbidden from being yielded.

Yields

Batch of Molecule – A batch of selected molecules.

set_cache_use(self, use_cache)¶

Toggle use of the cache.

If used as a MoleculeCalculator this method toggles use of the results cache. If used as a EAOperation, toggles use of the molecular cache.

Parameters: use_cache (bool) – Whether the cache should be used.
Returns: The calculator is returned.
Return type: If

class RaisingCalculator(calculator, fail_chance=0.5, random_seed=None, use_cache=False)¶

Bases: stk.calculators.base_calculators._MoleculeCalculator, stk.calculators.ea.crossers.Crosser, stk.calculators.energy.energy_calculators.EnergyCalculator, stk.calculators.ea.fitness_calculators.FitnessCalculator, stk.calculators.ea.fitness_normalizers.FitnessNormalizer, stk.calculators.ea.mutators.Mutator, stk.calculators.optimization.optimizers.Optimizer

Raise an error at random or use another calculator.

This calculator is mainly used for debugging.

import stk

energy_calculator = stk.RaisingCalculator(stk.UFFEnergy())
mol = stk.BuildingBlock('NCCN')
# 50% chance of getting the energy with UFF and 50% chance
# of raising an error.
energy = energy_calculator.get_energy(mol)

Methods

`add_to_cache`(self, mol[, value])	Add a molecule to the cache.
`cross`(self, \*mols)	Cross mols.
`get_cached_value`(self, mol)	Return the value stored in the cache for mol.
`get_energy`(self, mol)	Calculate the energy of mol.
`get_fitness`(self, mol)	Return the fitness value of mol.
`is_caching`(self)	`True` if the calculator has caching turned on.
`is_in_cache`(self, mol)	Return `True` if mol is cached.
`mutate`(self, mol)	Return a mutant of mol.
`normalize`(self, population)	Normalize the fitness values in population.
`optimize`(self, mol)	Optimize mol.
`set_cache_use`(self, use_cache)	Toggle use of the cache.

__init__(self, calculator, fail_chance=0.5, random_seed=None, use_cache=False)¶

Initialize a RaisingCalculator instance.

Parameters

calculator (see base classes) – The calculator to use when an error is not raised.
fail_chance (float, optional) – The probability of raising an error.
random_seed (int, optional) – The random seed to use for raising an error.
use_cache (bool, optional) – When used as a MoleculeCalculator, this toggles use of the results cache.

add_to_cache(self, mol, value=None)¶

Add a molecule to the cache.

Parameters

mol (Molecule) – The molecule to be added to the cache.
value (class:object, optional) – The cached value associated with the molecule.

Returns

The calculator.

Return type

MoleculeCalculator

cross(self, *mols)¶

Cross mols.

Parameters: *mols (Molecule) – The molecules on which a crossover operation is performed.
Yields: Molecule – The generated offspring.

get_cached_value(self, mol)¶

Return the value stored in the cache for mol.

Parameters: mol (Molecule) – The molecule whose cached value is to be returned.
Returns: The cached value.
Return type: object

get_energy(self, mol)¶

Calculate the energy of mol.

Parameters: mol (Molecule) – The Molecule whose energy is to be calculated.
Returns: The energy.
Return type: float

get_fitness(self, mol)¶

Return the fitness value of mol.

Parameters: mol (Molecule) – The molecule whose fitness value should be calculated.
Returns: The fitness value of mol.
Return type: object

is_caching(self)¶

True if the calculator has caching turned on.

Returns: True if the calculator has caching turned on.
Return type: bool

is_in_cache(self, mol)¶

Return True if mol is cached.

Parameters: mol (Molecule) – The molecule being checked.
Returns: True if mol is cached.
Return type: bool

mutate(self, mol)¶

Return a mutant of mol.

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

normalize(self, population)¶

Normalize the fitness values in population.

Parameters: population (EAPopulation) – The molecules which need to have their fitness values normalized.
Returns: Maps every molecule in population to its normalized fitness value.
Return type: dict

optimize(self, mol)¶

Optimize mol.

Parameters: mol (Molecule) – The molecule to be optimized.
Returns: None
Return type: NoneType

set_cache_use(self, use_cache)¶

Toggle use of the cache.

If used as a MoleculeCalculator this method toggles use of the results cache. If used as a EAOperation, toggles use of the molecular cache.

Parameters: use_cache (bool) – Whether the cache should be used.
Returns: The calculator is returned.
Return type: If

exception RaisingCalculatorError¶

Bases: Exception

__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 Random(*calculators, probabilities=None, random_seed=None, use_cache=False)¶

Bases: stk.calculators.base_calculators._MoleculeCalculator, stk.calculators.ea.crossers.Crosser, stk.calculators.energy.energy_calculators.EnergyCalculator, stk.calculators.ea.fitness_calculators.FitnessCalculator, stk.calculators.ea.fitness_normalizers.FitnessNormalizer, stk.calculators.ea.mutators.Mutator, stk.calculators.optimization.optimizers.Optimizer, stk.calculators.ea.selectors.Selector

Pick a calculator to use at random.

Examples

Pick a random mutation operation

mutator = stk.Random(
    stk.RandomBuildingBlock(...),
    stk.RandomTopologyGraph(...),
)
mol = stk.ConstructedMolecule(...)

# Mutate mol with either RandomBuildingBlock or
# RandomTopologyGraph, at random.
mutant = mutator.mutate(mol)

Methods

`add_to_cache`(self, mol[, value])	Add a molecule to the cache.
`cross`(self, \*mols)	Cross mols.
`get_cached_value`(self, mol)	Return the value stored in the cache for mol.
`get_energy`(self, mol)	Calculate the energy of mol.
`get_fitness`(self, mol)	Return the fitness value of mol.
`is_caching`(self)	`True` if the calculator has caching turned on.
`is_in_cache`(self, mol)	Return `True` if mol is cached.
`mutate`(self, mol)	Return a mutant of mol.
`normalize`(self, population)	Normalize the fitness values in population.
`optimize`(self, mol)	Optimize mol.
`select`(self, population[, included_batches, …])	Select batches of molecules from population.
`set_cache_use`(self, use_cache)	Toggle use of the cache.

__init__(self, *calculators, probabilities=None, random_seed=None, use_cache=False)¶

Initialize a Random instance.

Parameters

calculators (see base classes) – The calculator, one of which is picked at random each time a calculation is requested.
probabilities (tuple of float, optional) – The probability of picking each calculator in calculators. If None, all calculators have an equal chance of being picked.
random_seed (int, optional) – The random seed for picking the calculator.
use_cache (bool, optional) – When used as a MoleculeCalculator, this toggles use of the results cache.

add_to_cache(self, mol, value=None)¶

Add a molecule to the cache.

Parameters

mol (Molecule) – The molecule to be added to the cache.
value (class:object, optional) – The cached value associated with the molecule.

Returns

The calculator.

Return type

MoleculeCalculator

cross(self, *mols)¶

Cross mols.

Parameters: *mols (Molecule) – The molecules on which a crossover operation is performed.
Yields: Molecule – The generated offspring.

get_cached_value(self, mol)¶

Return the value stored in the cache for mol.

Parameters: mol (Molecule) – The molecule whose cached value is to be returned.
Returns: The cached value.
Return type: object

get_energy(self, mol)¶

Calculate the energy of mol.

Parameters: mol (Molecule) – The Molecule whose energy is to be calculated.
Returns: The energy.
Return type: float

get_fitness(self, mol)¶

Return the fitness value of mol.

Parameters: mol (Molecule) – The molecule whose fitness value should be calculated.
Returns: The fitness value of mol.
Return type: object

is_caching(self)¶

True if the calculator has caching turned on.

Returns: True if the calculator has caching turned on.
Return type: bool

is_in_cache(self, mol)¶

Return True if mol is cached.

Parameters: mol (Molecule) – The molecule being checked.
Returns: True if mol is cached.
Return type: bool

mutate(self, mol)¶

Return a mutant of mol.

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

normalize(self, population)¶

Normalize the fitness values in population.

Parameters: population (EAPopulation) – The molecules which need to have their fitness values normalized.
Returns: Maps every molecule in population to its normalized fitness value.
Return type: dict

optimize(self, mol)¶

Optimize mol.

Parameters: mol (Molecule) – The molecule to be optimized.
Returns: None
Return type: NoneType

select(self, population, included_batches=None, excluded_batches=None)¶

Select batches of molecules from population.

Parameters

population (EAPopulation) – A collection of molecules from which batches are selected.
included_batches (set, optional) – The identity keys of batches which are allowed to be yielded, if None all batches can be yielded. If not None only batches included_batches will be yielded.
excluded_batches (class:set, optional) – The identity keys of batches which are not allowed to be yielded. If None, no batch is forbidden from being yielded.

Yields

Batch of Molecule – A batch of selected molecules.

set_cache_use(self, use_cache)¶

Toggle use of the cache.

If used as a MoleculeCalculator this method toggles use of the results cache. If used as a EAOperation, toggles use of the molecular cache.

Parameters: use_cache (bool) – Whether the cache should be used.
Returns: The calculator is returned.
Return type: If

class Sequence(*calculators, use_cache=False, num_batches=None)¶

Bases: stk.calculators.base_calculators._MoleculeCalculator, stk.calculators.optimization.optimizers.Optimizer, stk.calculators.ea.fitness_normalizers.FitnessNormalizer, stk.calculators.ea.selectors.Selector

Use calculators in sequence.

Examples

First use ETKDG to optimize a molecule and then use UFF

import stk

optimizer = stk.Sequence(
    stk.ETKDG(),
    stk.UFF(),
)

mol = stk.BuildingBlock('NCCN')
optimizer.optimize(mol)

Methods

`add_to_cache`(self, mol[, value])	Add a molecule to the cache.
`get_cached_value`(self, mol)	Return the value stored in the cache for mol.
`is_caching`(self)	`True` if the calculator has caching turned on.
`is_in_cache`(self, mol)	Return `True` if mol is cached.
`normalize`(self, population)	Normalize the fitness values in population.
`optimize`(self, mol)	Optimize mol.
`select`(self, population[, included_batches, …])	Select batches of molecules from population.
`set_cache_use`(self, use_cache)	Set cache use on or off.

__init__(self, *calculators, use_cache=False, num_batches=None)¶

Initialize a Sequence instance.

Parameters

calculators (see base classes) – The calculators to be applied in sequence.
use_cache (bool, optional) – When used as a MoleculeCalculator, this toggles use of the results cache.
num_batches (int, optional) – The maximum number of batches to yield across the sequence. If None, will yield forever or until exhausted. This option is only used when used as a Selector.

add_to_cache(self, mol, value=None)¶

Add a molecule to the cache.

Parameters

mol (Molecule) – The molecule to be added to the cache.
value (class:object, optional) – The cached value associated with the molecule.

Returns

The calculator.

Return type

MoleculeCalculator

get_cached_value(self, mol)¶

Return the value stored in the cache for mol.

Parameters: mol (Molecule) – The molecule whose cached value is to be returned.
Returns: The cached value.
Return type: object

is_caching(self)¶

True if the calculator has caching turned on.

Returns: True if the calculator has caching turned on.
Return type: bool

is_in_cache(self, mol)¶

Return True if mol is cached.

Parameters: mol (Molecule) – The molecule being checked.
Returns: True if mol is cached.
Return type: bool

normalize(self, population)¶

Normalize the fitness values in population.

Parameters: population (EAPopulation) – The molecules which need to have their fitness values normalized.
Returns: Maps every molecule in population to its normalized fitness value.
Return type: dict

optimize(self, mol)¶

Optimize mol.

Parameters: mol (Molecule) – The molecule to be optimized.
Returns: None
Return type: NoneType

select(self, population, included_batches=None, excluded_batches=None)¶

Select batches of molecules from population.

Parameters

population (EAPopulation) – A collection of molecules from which batches are selected.
included_batches (set, optional) – The identity keys of batches which are allowed to be yielded, if None all batches can be yielded. If not None only batches included_batches will be yielded.
excluded_batches (class:set, optional) – The identity keys of batches which are not allowed to be yielded. If None, no batch is forbidden from being yielded.

Yields

Batch of Molecule – A batch of selected molecules.

set_cache_use(self, use_cache)¶

Set cache use on or off.

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

class TryCatch(try_calculator, catch_calculator, catch_type=<class 'Exception'>, use_cache=True)¶

Bases: stk.calculators.base_calculators._MoleculeCalculator, stk.calculators.ea.crossers.Crosser, stk.calculators.energy.energy_calculators.EnergyCalculator, stk.calculators.ea.fitness_calculators.FitnessCalculator, stk.calculators.ea.fitness_normalizers.FitnessNormalizer, stk.calculators.ea.mutators.Mutator, stk.calculators.optimization.optimizers.Optimizer

Try one calculator and if it raises an error use another.

Examples

Try using the MMFF force field to optimize a molecule and if it fails use the UFF force field

import stk

optimizer = stk.TryCatch(
    try_calculator=stk.MMFF(),
    catch_calculator=stk.UFF(),
)
mol = stk.BuildingBlock('NCCN')
optimizer.optimize(mol)

Try using the MMFF force field to calculate energy and if it fails use the UFF force field

energy_calculator = stk.TryCatch(
    try_calculator=stk.MMFFEnergy(),
    catch_calculator=stk.UFFEnergy(),
)
mol = stk.BuildingBlock('NCCN')
energy = energy_calculator.get_energy(mol)

Methods

`add_to_cache`(self, mol[, value])	Add a molecule to the cache.
`cross`(self, \*mols)	Cross mols.
`get_cached_value`(self, mol)	Return the value stored in the cache for mol.
`get_energy`(self, mol)	Calculate the energy of mol.
`get_fitness`(self, mol)	Return the fitness value of mol.
`is_caching`(self)	`True` if the calculator has caching turned on.
`is_in_cache`(self, mol)	Return `True` if mol is cached.
`mutate`(self, mol)	Return a mutant of mol.
`normalize`(self, population)	Normalize the fitness values in population.
`optimize`(self, mol)	Optimize mol.
`set_cache_use`(self, use_cache)	Toggle use of the cache.

__init__(self, try_calculator, catch_calculator, catch_type=<class 'Exception'>, use_cache=True)¶

Initialize a TryCatch instance.

Parameters

try_calculator (see base classes) – The calculator to try using first.
catch_calculator (see base classes) – The calculator to use if try_calculator raises an error.
catch_type (Exception) – The catch_calculator will only be run if the try_calculator raises an exception of this type.
use_cache (bool, optional) – When used as a MoleculeCalculator, this toggles use of the results cache.

add_to_cache(self, mol, value=None)¶

Add a molecule to the cache.

Parameters

mol (Molecule) – The molecule to be added to the cache.
value (class:object, optional) – The cached value associated with the molecule.

Returns

The calculator.

Return type

MoleculeCalculator

cross(self, *mols)¶

Cross mols.

Parameters: *mols (Molecule) – The molecules on which a crossover operation is performed.
Yields: Molecule – The generated offspring.

get_cached_value(self, mol)¶

Return the value stored in the cache for mol.

Parameters: mol (Molecule) – The molecule whose cached value is to be returned.
Returns: The cached value.
Return type: object

get_energy(self, mol)¶

Calculate the energy of mol.

Parameters: mol (Molecule) – The Molecule whose energy is to be calculated.
Returns: The energy.
Return type: float

get_fitness(self, mol)¶

Return the fitness value of mol.

Parameters: mol (Molecule) – The molecule whose fitness value should be calculated.
Returns: The fitness value of mol.
Return type: object

is_caching(self)¶

True if the calculator has caching turned on.

Returns: True if the calculator has caching turned on.
Return type: bool

is_in_cache(self, mol)¶

Return True if mol is cached.

Parameters: mol (Molecule) – The molecule being checked.
Returns: True if mol is cached.
Return type: bool

mutate(self, mol)¶

Return a mutant of mol.

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

normalize(self, population)¶

Normalize the fitness values in population.

Parameters: population (EAPopulation) – The molecules which need to have their fitness values normalized.
Returns: Maps every molecule in population to its normalized fitness value.
Return type: dict

optimize(self, mol)¶

Optimize mol.

Parameters: mol (Molecule) – The molecule to be optimized.
Returns: None
Return type: NoneType

set_cache_use(self, use_cache)¶

Toggle use of the cache.

If used as a MoleculeCalculator this method toggles use of the results cache. If used as a EAOperation, toggles use of the molecular cache.

Parameters: use_cache (bool) – Whether the cache should be used.
Returns: The calculator is returned.
Return type: If