Optimizers¶

Optimizers are objects used to optimize molecules. Each optimizer is initialized with some settings and can optimize a molecule with optimize().

import stk

mol = stk.BuildingBlock('NCCCN', ['amine'])
mmff = stk.MMFF()
mmff.optimize(mol)

# Optimizers also work with ConstructedMolecule objects.
polymer = stk.ConstructedMolecule(
    building_blocks=[mol],
    topology_graph=stk.polymer.Linear('A', [0], n=3)
)
etkdg = stk.ETKDG()
etkdg.optimize(polymer)

Sometimes it is desirable to chain multiple optimizations, one after another. For example, before running an optimization, it may be desirable to embed a molecule first, to generate an initial structure. Sequence may be used for this.

# Create a new optimizer which chains the previously defined
# mmff and etkdg optimizers.
optimizer_sequence = stk.Sequence(etkdg, mmff)

# Run each optimizer in sequence.
optimizer_sequence.optimize(polymer)

By default, running Optimizer.optimize() twice on the same molecule will perform an optimization a second time on a molecule. If we want to skip optimizations on molecules which have already been optimized we can use the use_cache flag.

caching_etkdg = stk.ETKDG(use_cache=True)
# First optimize call runs an optimization.
caching_etkdg.optimize(polymer)
# Second call does nothing.
caching_etkdg.optimize(polymer)

Caching is done on a per Optimizer basis. Just because the molecule has been cached by one Optimizer instance does not mean that a different Optimizer instance will no longer optimize the molecule.

Making New Optimizers¶

New optimizers can be made by simply making a class which inherits the Optimizer class. This is an abstract base class and its virtual methods must be implemented.

class CageOptimizerSequence(num_expected_windows, optimizers, use_cache=False)¶

Bases: stk.calculators.base_calculators._MoleculeCalculator, stk.calculators.optimization.optimizers.Optimizer

Applies Optimizer objects to a cage.

Before each Optimizer in the sequence is applied to the cage, it is checked to see if it is collapsed. If it is collapsed, the optimization sequence ends immediately.

Examples

Let’s say we want to embed a cage with ETKDG first and then minimize it with the MMFF force field.

import stk

bb1 = stk.BuildingBlock('NCCNCCN', ['amine'])
bb2 = stk.BuildingBlock('O=CC(C=O)C=O', ['aldehyde'])
cage = stk.ConstructedMolecule(
    building_blocks=[bb1, bb2],
    topology_graph=stk.cage.FourPlusSix()
)
optimizer = stk.CageOptimizerSequence(
    num_expected_windows=4,
    optimizers=(stk.ETKDG(), stk.MMFF()),
)
optimizer.optimize(cage)

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.
`optimize`(self, mol)	Optimize mol.
`set_cache_use`(self, use_cache)	Set cache use on or off.

__init__(self, num_expected_windows, optimizers, use_cache=False)¶

Initialize a CageOptimizerSequence instance.

Parameters

num_expected_windows (class:int) – The number of windows expected if the cage is not collapsed.
optimizers (tuple of Optimizer) – The Optimizers used in sequence to optimize cage molecules.
use_cache (bool, optional) – If True optimize() will not run twice on the same molecule.

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

optimize(self, mol)¶

Optimize mol.

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

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 ETKDG(random_seed=12, use_cache=False)¶

Bases: stk.calculators.base_calculators._MoleculeCalculator, stk.calculators.optimization.optimizers.Optimizer

Uses the ETKDG 1 v2 algorithm to find an optimized structure.

Examples

import stk

mol = stk.BuildingBlock('NCCNCCN', ['amine'])
etkdg = stk.ETKDG()
etkdg.optimize(mol)

References

1: http://pubs.acs.org/doi/pdf/10.1021/acs.jcim.5b00654

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.
`optimize`(self, mol)	Optimize mol.
`set_cache_use`(self, use_cache)	Set cache use on or off.

__init__(self, random_seed=12, use_cache=False)¶

Initialize a ETKDG instance.

Parameters

random_seed (int, optional) – The random seed to use.
use_cache (bool, optional) – If True optimize() will not run twice on the same molecule.

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

optimize(self, mol)¶

Optimize mol.

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

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 MMFF(use_cache=False)¶

Bases: stk.calculators.base_calculators._MoleculeCalculator, stk.calculators.optimization.optimizers.Optimizer

Use the MMFF force field to optimize molecules.

Examples

import stk

mol = stk.BuildingBlock('NCCNCCN', ['amine'])
mmff = stk.MMFF()
mmff.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.
`optimize`(self, mol)	Optimize mol.
`set_cache_use`(self, use_cache)	Set cache use on or off.

__init__(self, use_cache=False)¶

Initialize the Calculator.

Parameters: use_cache (bool, optional) – If True, a calculation will not be performed on the same molecule twice.

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

optimize(self, mol)¶

Optimize mol.

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

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 NullOptimizer(use_cache=False)¶

Bases: stk.calculators.base_calculators._MoleculeCalculator, stk.calculators.optimization.optimizers.Optimizer

Does not perform optimizations.

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.
`optimize`(self, mol)	Optimize mol.
`set_cache_use`(self, use_cache)	Set cache use on or off.

__init__(self, use_cache=False)¶

Initialize the Calculator.

Parameters: use_cache (bool, optional) – If True, a calculation will not be performed on the same molecule twice.

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

optimize(self, mol)¶

Optimize mol.

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

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 Optimizer¶

Bases: stk.calculators.base_calculators.MoleculeCalculator

An abstract base class for optimizers.

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.
`optimize`(self, mol)	Optimize mol.
`set_cache_use`(self, use_cache)	Set cache use on or off.

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

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

Raises

NotImplementedError – This is a virtual method and needs to be implemented in a subclass.

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
Raises: NotImplementedError – This is a virtual method and needs to be implemented in a subclass.

is_caching(self)¶

True if the calculator has caching turned on.

Returns: True if the calculator has caching turned on.
Return type: bool
Raises: NotImplementedError – This is a virtual method and needs to be implemented in a subclass.

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
Raises: NotImplementedError – This is a virtual method and needs to be implemented in a subclass.

optimize(self, mol)¶

Optimize mol.

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

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
Raises: NotImplementedError – This is a virtual method and needs to be implemented in a subclass.

class UFF(use_cache=False)¶

Bases: stk.calculators.base_calculators._MoleculeCalculator, stk.calculators.optimization.optimizers.Optimizer

Use the UFF force field to optimize molecules.

Examples

import stk

mol = stk.BuildingBlock('NCCNCCN', ['amine'])
uff = stk.UFF()
uff.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.
`optimize`(self, mol)	Optimize mol.
`set_cache_use`(self, use_cache)	Set cache use on or off.

__init__(self, use_cache=False)¶

Initialize the Calculator.

Parameters: use_cache (bool, optional) – If True, a calculation will not be performed on the same molecule twice.

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

optimize(self, mol)¶

Optimize mol.

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

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 XTB(xtb_path, gfn_version=2, output_dir=None, opt_level='normal', max_runs=2, calculate_hessian=True, num_cores=1, electronic_temperature=300, solvent=None, solvent_grid='normal', charge=0, num_unpaired_electrons=0, unlimited_memory=False, use_cache=False)¶

Bases: stk.calculators.base_calculators._MoleculeCalculator, stk.calculators.optimization.optimizers.Optimizer

Uses GFN-xTB [R5a3ee434ea59-1] to optimize molecules.

Notes

When running optimize(), this calculator changes the present working directory with os.chdir(). The original working directory will be restored even if an error is raised, so unless multi-threading is being used this implementation detail should not matter.

If multi-threading is being used an error could occur if two different threads need to know about the current working directory as XTB can change it from under them.

Note that this does not have any impact on multi-processing, which should always be safe.

Furthermore, optimize() will check that the structure is adequately optimized by checking for negative frequencies after a Hessian calculation. max_runs can be provided to the initializer to set the maximum number of optimizations which will be attempted at the given opt_level to obtain an optimized structure. However, we outline in the examples how to iterate over opt_levels to increase convergence criteria and hopefully obtain an optimized structure. The presence of negative frequencies can occur even when the optimization has converged based on the given opt_level.

incomplete¶

A set of molecules passed to optimize() whose optimzation was incomplete.

Type: set of Molecule

Examples

Note that for ConstructedMolecule objects constructed by stk, XTB should usually be used in a Sequence. This is because xTB only uses xyz coordinates as input and so will not recognize the long bonds created during construction. An optimizer which can minimize these bonds should be used before XTB.

import stk

bb1 = stk.BuildingBlock('NCCNCCN', ['amine'])
bb2 = stk.BuildingBlock('O=CCCC=O', ['aldehyde'])
polymer = stk.ConstructedMolecule(
    building_blocks=[bb1, bb2],
    topology_graph=stk.polymer.Linear("AB", [0, 0], 3)
)

xtb = stk.Sequence(
    stk.UFF(),
    stk.XTB(xtb_path='/opt/gfnxtb/xtb', unlimited_memory=True)
)
xtb.optimize(polymer)

By default, all optimizations with xTB are performed using the --ohess flag, which forces the calculation of a numerical Hessian, thermodynamic properties and vibrational frequencies. optimize() will check that the structure is appropriately optimized (i.e. convergence is obtained and no negative vibrational frequencies are present) and continue optimizing a structure (up to max_runs times) until this is achieved. This loop, by default, will be performed at the same opt_level. The following example shows how a user may optimize structures with tigher convergence criteria (i.e. different opt_level) until the structure is sufficiently optimized. Furthermore, the calculation of the Hessian can be turned off using max_runs to 1 and calculate_hessian to False.

# Use crude optimization with max_runs=1 because this will
# not achieve optimization and rerunning it is unproductive.
xtb_crude = stk.XTB(
    xtb_path='/opt/gfnxtb/xtb',
    output_dir='xtb_crude',
    unlimited_memory=True,
    opt_level='crude',
    max_runs=1,
    calculate_hessian=True
)
# Use normal optimization with max_runs == 2.
xtb_normal = stk.XTB(
    xtb_path='/opt/gfnxtb/xtb',
    output_dir='xtb_normal',
    unlimited_memory=True,
    opt_level='normal',
    max_runs=2
)
# Use vtight optimization with max_runs == 2, which should
# achieve sufficient optimization.
xtb_vtight = stk.XTB(
    xtb_path='/opt/gfnxtb/xtb',
    output_dir='xtb_vtight',
    unlimited_memory=True,
    opt_level='vtight',
    max_runs=2
)

optimizers = [xtb_crude, xtb_normal, xtb_vtight]
for optimizer in optimizers:
    optimizer.optimize(polymer)
    if polymer not in optimizer.incomplete:
        break

References

R5a3ee434ea59-1: https://xtb-docs.readthedocs.io/en/latest/setup.html

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.
`optimize`(self, mol)	Optimize mol.
`set_cache_use`(self, use_cache)	Set cache use on or off.

__init__(self, xtb_path, gfn_version=2, output_dir=None, opt_level='normal', max_runs=2, calculate_hessian=True, num_cores=1, electronic_temperature=300, solvent=None, solvent_grid='normal', charge=0, num_unpaired_electrons=0, unlimited_memory=False, use_cache=False)¶

Initialize a XTB instance.

Parameters

xtb_path (str) – The path to the xTB executable.
gfn_version (int, optional) – Parameterization of GFN to use in xTB. For details see https://xtb-docs.readthedocs.io/en/latest/basics.html.
output_dir (str, optional) – The name of the directory into which files generated during the optimization are written, if None then uuid.uuid4() is used.
opt_level (str, optional) – Optimization level to use. Can be one of 'crude', 'sloppy', 'loose', 'lax', 'normal', 'tight', 'vtight' or 'extreme'. For details see https://xtb-docs.readthedocs.io/en/latest/optimization.html .
max_runs (int, optional) – Maximum number of optimizations to attempt in a row.
calculate_hessian (bool, optional) – Toggle calculation of the hessian and vibrational frequencies after optimization. True is required to check that the structure is completely optimized. False will drastically speed up the calculation but potentially provide incomplete optimizations and forces max_runs to be 1.
num_cores (int, optional) – The number of cores xTB should use.
electronic_temperature (int, optional) – Electronic temperature in Kelvin.
solvent (str, optional) – Solvent to use in GBSA implicit solvation method. For details see https://xtb-docs.readthedocs.io/en/latest/gbsa.html.
solvent_grid (str, optional) – Grid level to use in SASA calculations for GBSA implicit solvent. Can be one of 'normal', 'tight', 'verytight' or 'extreme'. For details see https://xtb-docs.readthedocs.io/en/latest/gbsa.html.
charge (int, optional) – Formal molecular charge.
num_unpaired_electrons (int, optional) – Number of unpaired electrons.
unlimited_memory – If True optimize() will be run without constraints on the stack size. If memory issues are encountered, this should be True, however this may raise issues on clusters.
use_cache (bool, optional) – If True optimize() will not run twice on the same molecule.

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

optimize(self, mol)¶

Optimize mol.

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

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

exception XTBConvergenceError¶

Bases: stk.calculators.optimization.optimizers.XTBOptimizerError

__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.

exception XTBOptimizerError¶

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.