# Utilities¶

Presented here is a small set of useful utility tools that can come handy in various contexts in your scripts. They are simple, standalone objects always present in the main namespace.

What is characteristic for objects described below is that they are meant to be used in a bit different way than all other PLAMS classes. Usually one takes a class (like DiracJob), creates an instance of it (myjob = DiracJob(...)) and executes some of its methods (r = myjob.run()). In contrast, utility classes are designed in a way similar to so called singleton design pattern. That means it is not possible to create any instances of these classes. The class itself serves for “one and only instance” and all methods should be called using the class as the calling object:

>>> x = PeriodicTable()
PTError: Instances of PeriodicTable cannot be created
>>> s = PeriodicTable.get_symbol(20)
>>> print(s)
Ca


## Periodic Table¶

class PeriodicTable[source]

A singleton class for the periodic table of elements.

For each element the following properties are stored: atomic symbol, atomic mass, atomic radius and number of connectors.

Atomic mass is, strictly speaking, atomic weight, as present in Mathematica’s ElementData function.

Atomic radius and number of connectors are used by guess_bonds(). Note that values of radii are neither atomic radii nor covalent radii. They are somewhat “emprically optimized” for the bond guessing algorithm.

Note

This class is visible in the main namespace as both PeriodicTable and PT.

__init__()[source]

Initialize self. See help(type(self)) for accurate signature.

classmethod get_atomic_number(symbol)[source]

Convert atomic symbol to atomic number.

classmethod get_symbol(atnum)[source]

Convert atomic number to atomic symbol.

classmethod get_mass(arg)[source]

Convert atomic symbol or atomic number to atomic mass.

classmethod get_radius(arg)[source]

Convert atomic symbol or atomic number to radius.

classmethod get_connectors(arg)[source]

Convert atomic symbol or atomic number to number of connectors.

classmethod get_metallic(arg)[source]

Convert atomic symbol or atomic number to number of connectors.

classmethod get_electronegative(arg)[source]

Convert atomic symbol or atomic number to number of connectors.

classmethod set_mass(element, value)[source]

Set the mass of element to value.

classmethod set_radius(element, value)[source]

Set the radius of element to value.

classmethod set_connectors(element, value)[source]

Set the number of connectors of element to value.

classmethod _get_property(arg, prop)[source]

Get property of element described by either symbol or atomic number. Skeleton method for get_radius(), get_mass() and get_connectors().

## Units¶

class Units[source]

A singleton class for unit converter.

All values are based on 2014 CODATA recommended values.

The following constants and units are supported:

• constants:
• speed_of_light (also c)
• electron_charge (also e)
• Avogadro_constant (also NA)
• Bohr_radius
• distance:
• Angstrom, A
• Bohr, au, a.u.
• nm
• pm
• reciprocal distance:
• 1/Angstrom, 1/A, Angstrom^-1, A^-1,
• 1/Bohr, Bohr^-1
• angle:
• degree, deg,
• radian, rad,
• grad
• circle
• energy:
• au, a.u., Hartree
• eV
• kcal/mol
• kJ/mol
• cm^-1, cm-1
• dipole moment:
• au, a.u.
• Cm
• Debye, D

Example:

>>> print(Units.constants['speed_of_light'])
299792458
>>> print(Units.constants['e'])
1.6021766208e-19
>>> print(Units.convert(123, 'angstrom', 'bohr'))
232.436313431
>>> print(Units.convert([23.32, 145.0, -34.7], 'kJ/mol', 'kcal/mol'))
[5.573613766730401, 34.655831739961755, -8.293499043977056]
>>> print(Units.conversion_ratio('kcal/mol', 'kJ/mol'))
4.184

__init__()[source]

Initialize self. See help(type(self)) for accurate signature.

classmethod conversion_ratio(inp, out)[source]

Return conversion ratio from unit inp to out.

classmethod convert(value, inp, out)[source]

Convert value from unit inp to out.

value can be a single number or a container (list, tuple, numpy.array etc.). In the latter case a container of the same type and length is returned. Conversion happens recursively, so this method can be used to convert, for example, a list of lists of numbers, or any other hierarchical container structure. Conversion is applied on all levels, to all values that are numbers (also numpy number types). All other values (strings, bools etc.) remain unchanged.

## Geometry tools¶

A small module with simple functions related to 3D geometry operations.

rotation_matrix(vec1, vec2)[source]

Calculate the rotation matrix rotating vec1 to vec2. Vectors can be any containers with 3 numerical values. They don’t need to be normalized. Returns 3x3 numpy array.

axis_rotation_matrix(vector, angle, unit='radian')[source]

Calculate the rotation matrix rotating along the vector by angle expressed in unit.

vector can be any container with 3 numerical values. They don’t need to be normalized. A positive angle denotes counterclockwise rotation, when looking along vector. Returns 3x3 numpy array.

distance_array(array1, array2)[source]

Calculates distance between each pair of points in array1 and array2. Returns 2D numpy array.

Uses fast cdist function if scipy is present, otherwise falls back to slightly slower numpy loop. Arguments should be 2-dimensional numpy arrays with the same second dimension. If array1 is A x N and array2 is B x N, the returned array is A x B.

angle(vec1, vec2, result_unit='radian')[source]

Calculate an angle between vectors vec1 and vec2.

vec1 and vec2 should be iterable containers of length 3 (for example: tuple, list, numpy array). Values stored in them are expressed in Angstrom. Returned value is expressed in result_unit.

This method requires all atomic coordinates to be numerical values, TypeError is raised otherwise.

dihedral(p1, p2, p3, p4, unit='radian')[source]

Calculate the value of diherdal angle formed by points p1, p2, p3 and p4 in a 3D space. Arguments can be any containers with 3 numerical values, also instances of Atom. Returned value is always non-negative, measures the angle clockwise (looking along p2-p3 vector) and is expressed in unit.

cell_shape(lattice)[source]

Converts lattice vectors to lengths and angles Sets internal cell size data, based on set of cell vectors.

cellvectors is list containing three cell vectors (a 3x3 matrix)