<no title>

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

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__(self, id_, fgs)¶: Initialize self. See help(type(self)) for accurate signature.

exception ChargedMolError(mol_file, msg)¶

Bases: Exception

__init__(self, mol_file, msg)¶: 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 LazyAttr(func)¶

Bases: object

A descriptor for creating lazy attributes.

__init__(self, func)¶: Initialize self. See help(type(self)) for accurate signature.

class MAEExtractor(run_name, n=1)¶

Bases: object

Extracts the lowest energy conformer from a .maegz file.

Macromodel conformer searches produce -out.maegz files containing all of the conformers found during the search and their energies and other data.

Initializing this class with a ConstructedMolecule finds the -out.maegz file of that ConstructedMolecule and converts it to a .mae file. It then creates and additional .mae file holding only the lowest energy conformer found.

maegz_path¶

The path to the -out.maegz file generated by the macromodel conformer search.

Type: str

mae_path¶

The path to the .mae file holding the conformers generated by the macromodel conformer search.

Type: str

content¶

The content of the .mae file hodling all the conformers from the macromodel conformer search. This holds other data such as their energies too.

Type: str

energies¶

The list has the form

energies = [(0, 231.0), (1, 144.4), ...]

Each tuple holds the id and energy of every conformer in the .mae file, respectively.

Type: list

min_energy¶

The minimum energy found in the .mae file.

Type: float

path¶

The full path of the .mae file holding the extracted lowest energy conformer.

Type: str

Methods

`extract_conformers`(self, n)	Creates `.mae` files holding the lowest energy conformers.
`extract_energy`(self, block)	Extracts the energy value from a `.mae` energy data block.
`lowest_energy_conformers`(self, n)	Returns the id and energy of the lowest energy conformers.
`maegz_to_mae`(self)	Converts the .maegz file to a .mae file.

__init__(self, run_name, n=1)¶: Initialize self. See help(type(self)) for accurate signature.

extract_conformers(self, n)¶

Creates .mae files holding the lowest energy conformers.

Parameters: n (int) – The number of conformers to extract.
Returns: None
Return type: NoneType

extract_energy(self, block)¶

Extracts the energy value from a .mae energy data block.

Parameters: block (str) – An .mae energy data block.
Returns: The energy value extracted from block or None if one is not found.
Return type: float

lowest_energy_conformers(self, n)¶

Returns the id and energy of the lowest energy conformers.

Parameters

n (int) – The number of lowest energy conformers to return.

Returns

A list of the form

returned = [(23, 123.3), (1, 143.89), (12, 150.6), ...]

Where each tuple holds the id and energy of the n lowest energy conformers, respectively.

Return type

list

maegz_to_mae(self)¶

Converts the .maegz file to a .mae file.

Returns: None
Return type: NoneType

exception MolFileError(mol_file, msg)¶

Bases: Exception

__init__(self, mol_file, msg)¶: 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 PopulationSizeError(msg)¶

Bases: Exception

__init__(self, msg)¶: 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 XTBExtractor(output_file)¶

Bases: object

Extracts properties from GFN-xTB output files.

output_file¶

Output file to extract properties from.

Type: str

output_lines¶

list of all lines in as str in the output file.

Type: list : str

total_energy¶

The total energy in the output_file as float. The energy is in units of a.u..

Type: float

homo_lumo_gap¶

The HOMO-LUMO gap in the output_file as float. The gap is in units of eV.

Type: float

fermi_level¶

The Fermi level in the output_file as float in units of eV.

Type: float

qonly_dipole_moment¶

Components of the Q only dipole moment in units of Debye in list of the form [x, y, z].

Type: list

full_dipole_moment¶

Components of the full dipole moment in units of Debye in list of the form [x, y, z, total].

Type: list

qonly_quadrupole_moment¶

Components of the Q only traceless quadrupole moment in units of Debye in list of the form [xx, xy, xy, xz, yz, zz].

Type: list

qdip_quadrupole_moment¶

Components of the Q+Dip traceless quadrupole moment in units of Debye in list of the form [xx, xy, xy, xz, yz, zz].

Type: list

full_quadrupole_moment¶

Components of the full traceless quadrupole moment in units of Debye in list of the form [xx, xy, xy, xz, yz, zz].

Type: list

homo_lumo_occ¶

dict of list containing the orbital number, energy in eV and occupation of the HOMO and LUMO orbitals in the output_file.

Type: dict

total_free_energy¶

The total free energy in the output_file as float. The free energy is in units of a.u. and calculated at 298.15K.

Type: float

frequencies¶

list of the vibrational frequencies as float in the output_file. Vibrational frequencies are in units of wavenumber and calculated at 298.15K.

Type: list

__init__(self, output_file)¶

Initializes XTBExtractor

Parameters: output_file (str) – Output file to extract properties from.

exception XTBInvalidSolventError¶

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.

archive_output()¶

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

dedupe(iterable, key=None, seen=None)¶

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

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

Transforms an nested iterable into a flat one.

For example

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

becomes

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

If a type is found in excluded_types it will not be yielded from. For example if str is in excluded_types

a = ["abcd", ["efgh"]]

“abcd” and “efgh” are yielded if a is passed to iterable. If str was not in excluded_types then “a”, “b”, “c”, “d”, “e”, “f”, “g” and “h” would all be yielded individually.

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.

is_valid_xtb_solvent(gfn_version, solvent)¶

Check if solvent is valid for the given GFN version.

Parameters

gfn_version (int) – GFN parameterization version. Can be: 0, 1 or 2.
solvent (str) – Solvent being tested [1].

Returns

True if solvent is valid.

Return type

bool

References

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

kabsch(coords1, coords2)¶

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

kill_macromodel()¶

Kills any applications left open as a result running MacroModel.

Applications that are typically left open are jserver-watcher.exe and jservergo.exe.

Returns: None
Return type: NoneType

matrix_centroid(matrix)¶

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

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

mol_from_mol_file(mol_file)¶

Creates a rdkit molecule from a .mol (V3000) file.

Parameters

mol_file (str) – The full of the .mol file from which an rdkit molecule should be instantiated.

Returns

An rdkit instance of the molecule held in mol2_file.

Return type

rdkit.Mol

Raises

ChargedMolError – If an atom row has more than 8 coloumns it is usually because there is a 9th coloumn indicating atomic charge. Such molecules are not currently supported, so an error is raised.
MolFileError – If the file is not a V3000 .mol file.

move_generated_macromodel_files(basename, output_dir)¶

normalize_vector(vector)¶

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

quaternion(u)¶

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

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

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

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.

Returns

A 3x3 array representing a rotation matrix.

Return type

numpy.ndarray

tar_output()¶

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

Returns: None
Return type: NoneType

time_it()¶

Times the code executed within the indent.

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

with time_it():
    something1()
    something2()
    something3()

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

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

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