Utilities

This module defines general-purpose objects, functions and classes.

Functions, classes, etc. defined here should not depend on any other part of stk. They must be completely self-sufficient.

class Cell(id_, fgs)[source]

Bases: object

Represents an individual cell in a supercell.

Parameters
  • id (list of int) – A 3 member list holding the x, y and z index of the cell within the supercell.

  • fgs (dict) – Maps the fgs in the original unit cell to the equivalent fgs in the cell.

id

A 3 member array holding the x, y and z index of the cell within the supercell.

Type

numpy.ndarray of int

fgs

Maps the fgs in the original unit cell to the equivalent fgs in the cell.

Type

dict

__init__(id_, fgs)[source]
exception ChargedMolError(mol_file, msg)[source]

Bases: Exception

__init__(mol_file, msg)[source]
args
with_traceback()

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

class LazyAttr(func)[source]

Bases: object

A descriptor for creating lazy attributes.

__init__(func)[source]
exception MolFileError(mol_file, msg)[source]

Bases: Exception

__init__(mol_file, msg)[source]
args
with_traceback()

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

exception PopulationSizeError(msg)[source]

Bases: Exception

__init__(msg)[source]
args
with_traceback()

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

archive_output()[source]

Places the output folder into stk_ea_runs.

This function assumes that the output folder is in the current working directory.

Returns

None

Return type

NoneType

cap_absolute_value(value, max_absolute_value=1)[source]

Returns value with absolute value capped at max_absolute_value.

Particularly useful in passing values to trignometric functions where numerical errors may result in an argument > 1 being passed in.

This code is modified from the pymatgen source code [1].

Parameters
  • value (float) – Value to cap.

  • max_absolute_value (float, optional) – Absolute value to cap value at. Defaults to 1.

Returns

value capped at max_absolute_value with sign preserved.

Return type

float

References

1

https://pymatgen.org/pymatgen.util.num.html

dedupe(iterable, key=None, seen=None)[source]

Yields items from iterable barring duplicates.

If seen is provided it contains elements which are not to be yielded at all.

Parameters
  • iterable (iterable) – An iterable of elements which are to be yielded, only once.

  • key (callable) – A function which gets applied to every member of iterable. The return of this function is checked for duplication rather than the member itself.

  • seen (set, optional) – Holds items which are not to be yielded.

Yields

object – Element in iterable which is not in seen and has not been yielded before.

dice_similarity(mol1, mol2, fp_radius=3)[source]

Return the chemical similarity between two molecules.

Parameters
  • mol1 (Molecule) – The first molecule.

  • mol2 (Molecule) – The second molecule.

  • fp_radius (int, optional) – The radius of the Morgan fingerprint used to calculate similarity.

Returns

The similarity.

Return type

float

flatten(iterable, excluded_types=None)[source]

Transforms an nested iterable into a flat one.

Examples

Flattening a Deeply Nested Structure

import stk

nested = [[1, 2, 3], [[4], [5], [[6]], 7]]
print(list(stk.flatten(nested)))

gives

[1, 2, 3, 4, 5, 6, 7]

Avoiding Flattening of Some Types

If a type is found in excluded_types it will not be yielded from. For example, str is in excluded_types by default, so

import stk

nested = ['abcd', ['efgh']]
print(list(stk.flatten(nested)))

gives

['abcd', 'efgh']

instead of

['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h']
Parameters
  • iterable (iterable) – The iterable which is to be flattened

  • excluded_types (set, optional) – Holds container types which are not be flattened.

Yields

object – A nested element of iterable.

get_acute_vector(reference, vector)[source]
get_plane_normal(points)[source]
get_projection(start, target)[source]

Get the projection of start onto target.

kabsch(coords1, coords2)[source]

Return a rotation matrix to minimize dstance between 2 coord sets.

This is essentially an implementation of the Kabsch algorithm. Given two sets of coordinates, coords1 and coords2, this function returns a rotation matrix. When the rotation matrix is applied to coords1 the resulting coordinates have their rms distance to coords2 minimized.

Parameters
  • coords1 (numpy.ndarray) – This array represents a matrix hodling coordinates which need to be rotated to minimize their rms distance to coordinates in coords2. The matrix is n x 3. Each row of the matrix holds the x, y and z coordinates of one point, respectively. Here n is the number of points.

  • coords2 (numpy.ndarray) – This array represents a matrix which holds the coordinates of points the distance to which should be minimized. The matrix is n x 3. Each row of the matrix holds the x, y and z coordinates of one point, respectively. Here n is the number of points.

Returns

A rotation matrix. This will be a 3 x 3 matrix.

Return type

numpy.ndarray

References

http://nghiaho.com/?page_id=671 https://en.wikipedia.org/wiki/Kabsch_algorithm

matrix_centroid(matrix)[source]

Returns the centroid of the coordinates held in matrix.

Parameters

matrix (np.ndarray) – A n x 3 matrix. Each row holds the x, y and z coordinate of some point, respectively.

Returns

A numpy array which holds the x, y and z coordinates of the centroid of the coordinates in matrix.

Return type

numpy.ndarray

mol_from_mae_file(mae_path)[source]

Creates a rdkit molecule from a .mae file.

Parameters

mol2_file (str) – The full path of the .mae file from which an rdkit molecule should be instantiated.

Returns

An rdkit instance of the molecule held in mae_file.

Return type

rdkit.Mol

normalize_vector(vector)[source]

Normalizes the given vector.

A new vector is returned, the original vector is not modified.

Parameters

vector (np.ndarray) – The vector to be normalized.

Returns

The normalized vector.

Return type

np.ndarray

orthogonal_vector(vector)[source]
quaternion(u)[source]

Returns a translation + rotation quaternion.

Parameters

u (list of float) – A list of length 3 holding the parameter for the quarternion.

References

K. Shoemake, Uniform random rotations, Graphics Gems III, pages 124-132. Academic, New York, 1992.

remake(mol)[source]

Remakes a molecule from scratch.

Parameters

mol (rdkit.Mol) – The molecule to be remade.

Returns

The remade molecule.

Return type

rdkit.Mol

rotation_matrix(vector1, vector2)[source]

Returns a rotation matrix which transforms vector1 to vector2.

Multiplying vector1 by the rotation matrix returned by this function yields vector2.

Parameters
  • vector1 (numpy.ndarray) – The vector which needs to be transformed to vector2.

  • vector2 (numpy.ndarray) – The vector onto which vector1 needs to be transformed.

Returns

A rotation matrix which transforms vector1 to vector2.

Return type

numpy.ndarray

References

http://tinyurl.com/kybj9ox http://tinyurl.com/gn6e8mz

rotation_matrix_arbitrary_axis(angle, axis)[source]

Returns a rotation matrix of angle radians about axis.

Parameters
  • angle (float) – The size of the rotation in radians.

  • axis (numpy.ndarray) – A 3 element aray which represents a vector. The vector is the axis about which the rotation is carried out. Must be of unit magnitude.

Returns

A 3x3 array representing a rotation matrix.

Return type

numpy.ndarray

tar_output()[source]

Places all the content in the output folder into a .tgz file.

Returns

None

Return type

NoneType

time_it(output=<function _printer>)[source]

Times the code executed within the indent.

Parameters

output (callable, optional) – A function which takes the time taken for the code block to execute as its only input. Can be used to redirect or format the output.

Examples

Timing the Execution of a Function

This is a context manager so it should be used as:

import stk

with stk.time_it():
    print('a')
    print('b')
    print('c')

After all 3 functions are finished and the nested block is exited the time taken to process the entire block is printed.

translation_component(q)[source]

Extracts translation vector from quaternion.

Parameters

q (numpy.ndarray) – A length 4 quaternion.

Returns

The translation vector encoded within q.

Return type

numpy.ndarray

vector_angle(vector1, vector2)[source]

Returns the angle between two vectors in radians.

Parameters
Returns

The angle between vector1 and vector2 in radians.

Return type

float