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

vector1 (numpy.ndarray) – The first vector.
vector2 (numpy.ndarray) – The second vector.

Returns

The angle between vector1 and vector2 in radians.

Return type

float