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 the PeriodicTable
and Units
classes 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
andPT
.
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_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()
andget_connectors()
.

classmethod
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
(alsoc
)electron_charge
(alsoe
)Avogadro_constant
(alsoNA
)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
,cm1
K
,Kelvin
dipole moment:
au
,a.u.
Cm
Debye
,D
forces:
All energy units divided by angstrom or bohr, for example
eV/angstrom
hartree/bohr
hessian:
All energy units divided by angstrom^2 or bohr^2, for example
eV/angstrom^2
hartree/bohr^2
pressure:
All energy units divided by angstrom^3 or bohr^3, for example
eV/angstrom^3
hartree/bohr^3
And some more:
Pa
GPa
bar
atm
Example:
>>> print(Units.constants['speed_of_light']) 299792458 >>> print(Units.constants['e']) 1.6021766208e19 >>> 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

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 ifscipy
is present, otherwise falls back to slightly slowernumpy
loop. Arguments should be 2dimensionalnumpy
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 nonnegative, measures the angle clockwise (looking along p2p3 vector) and is expressed in unit.
File format conversion tools¶
A small module for converting VASP output to AMSlike output, and for converting ASE .traj trajectory files to the .rkf format.

traj_to_rkf
(trajfile, rkftrajectoryfile, task=None, timestep=0.25)[source]¶ Convert ase .traj file to .rkf file. NOTE: The order of atoms (or the number of atoms) cannot change between frames!
 trajfilestr
path to a .traj file
 rkftrajectoryfilestr
path to the output .rkf file (will be created)
 taskstr
Which task to write. If None it is autodetermined.
 timestep: float
Which timestep to write when task == ‘moleculardynamics’
 Returns2tuple (coords, cell)
The final coordinates and cell in angstrom

vasp_output_to_ams
(vasp_folder, wdir=None, overwrite=False, write_engine_rkf=True, task=None, timestep=0.25)[source]¶ Converts VASP output (OUTCAR, …) to AMS output (ams.rkf, vasp.rkf)
Returns: a string containing the directory where ams.rkf was written
 vasp_folderstr
path to a directory with an OUTCAR, INCAR, POTCAR etc. files
 wdirstr or None
directory in which to write the ams.rkf and vasp.rkf files If None, a subdirectory “AMSJob” of vasp_folder will be created
 overwritebool
if False, first check if wdir already contains ams.rkf and vasp.rkf, in which case do nothing if True, overwrite if exists
 write_engine_rkfbool
If True, also write vasp.rkf alongside ams.rkf. The vasp.rkf file will only contain an AMSResults section (energy, gradients, stress tensor). It will not contain the DOS or the band structure.
 taskstr
Which task to write to ams.rkf. If None it is autodetermined (probably set to ‘geometryoptimization’)
 timestepfloat
If task=’moleculardynamics’, which timestep (in fs) between frames to write

qe_output_to_ams
(qe_outfile, wdir=None, overwrite=False, write_engine_rkf=True)[source]¶ Converts a qe .out file to ams.rkf and qe.rkf.
Returns: a string containing the directory where ams.rkf was written
If the filename ends in .out, check if a .results directory exists. In that case, place the AMSJob subdirectory in the .results directory.
Otherwise, create a new directory called filename.AMSJob
 qe_outfilestr
path to the qe output file

gaussian_output_to_ams
(outfile, wdir=None, overwrite=False, write_engine_rkf=True)[source]¶ Converts a Gaussian .out file to ams.rkf and gaussian.rkf.
Returns: a string containing the directory where ams.rkf was written
If the filename ends in .out, check if a .results directory exists. In that case, place the AMSJob subdirectory in the .results directory.
Otherwise, create a new directory called filename.AMSJob
 outfilestr
path to the gaussian output file

rkf_to_ase_traj
(rkf_file, out_file, get_results=True)[source]¶ Convert an ams.rkf trajectory to a different trajectory format (.xyz, .traj, anything supported by ASE)
 rkf_file: str
Path to an ams.rkf file
 out_file: str
Path to the .traj or .xyz file that will be created. If the file exists it will be overwritten. If a .xyz file is specified it will use the normal ASE format (not the AMS format).
 get_results: bool
Whether to include results like energy, forces, and stress in the trajectory.

rkf_to_ase_atoms
(rkf_file, get_results=True)[source]¶ Convert an ams.rkf trajectory to a list of ASE atoms
 rkf_file: str
Path to an ams.rkf file
 out_file: str
Path to the .traj or .xyz file that will be created. If the file exists it will be overwritten. If a .xyz file is specified it will use the normal ASE format (not the AMS format).
 get_results: bool
Whether to include results like energy, forces, and stress in the trajectory.
Returns: a list of all the ASE Atoms objects.
Plotting tools¶
See also
Tools for creating plots with matplotlib.

plot_band_structure
(x, y_spin_up, y_spin_down=None, labels=None, fermi_energy=None, zero=None, show=False)[source]¶ Plots an electronic band structure from DFTB or BAND with matplotlib.
To control the appearance of the plot you need to call
plt.ylim(bottom, top)
,plt.title(title)
, etc. manually outside this function. x: list of float
Returned by AMSResults.get_band_structure()
 y_spin_up: 2D numpy array of float
Returned by AMSResults.get_band_structure()
 y_spin_down: 2D numpy array of float. If None, the spin down bands are not plotted.
Returned by AMSResults.get_band_structure()
 labels: list of str
Returned by AMSResults.get_band_structure()
 fermi_energy: float
Returned by AMSResults.get_band_structure(). Should have the same unit as
y
. zero: None or float or one of ‘fermi’, ‘vbmax’, ‘cbmin’
Shift the curves so that y=0 is at the specified value. If None, no shift is performed. ‘fermi’, ‘vbmax’, and ‘cbmin’ require that the
fermi_energy
is not None. Note: ‘vbmax’ and ‘cbmin’ calculate the zero as the highest (lowest) eigenvalue smaller (greater) than or equal tofermi_energy
. This is NOT necessarily equal to the valence band maximum or conduction band minimum as calculated by the compute engine. show: bool
If True, call plt.show() at the end