gimbal package

Submodules

gimbal.bonding module

Module for determining bonded atoms and natural coordinates.

The distance between N elements (atoms) in a set of cartesian coordinates can be determined by taking the norm of the outer difference of the coordinate array. An N x N adjacency matrix can then be formed by comparing the distance matrix to an upper (and lower) threshold.

For an adjacency matrix A, the elements connected by k links (bonds) is given by the matrix \(\mathbf{A}^k\). In molecular geometries, this can be used to find all sets of bonds (\(k = 1\)), angles (\(k = 2\)) and dihedral angles (\(k = 3\)).

Small rings can be measured from the eigenvectors of A. For example, if \(\mathbf{B} = \mathrm{eig}(\mathbf{A})\), the number of three-membered rings is given by \(\sum_{ij} \mathbf{B}_{ij}^3 / 6\).

gimbal.bonding.build_adjmat(elem, xyz, error=0.56, lothresh=0.4)

Returns an adjacency matrix from a set of atoms.

At present, thresholds are set to the Rasmol defaults of covalent radius + 0.56 and covalent radius - 0.91.

Parameters:
  • elem ((N,) array_like) – List of atomic symbols.
  • xyz ((N, 3) array_like) – Array of cartesian atomic positions.
  • error (float, optional) – The allowable error for the upper bound of bond lengths in Angstroms. Default is 0.56 based on JMol.
  • lothresh (float, optional) – The lower bound for all bond lengths. Default is 0.4 based on JMol.
Returns:

The adjacency matrix, an N x N array of ones at off-diagonal elements where two atoms are bonded, zeros otherwise.

Return type:

(N, N) ndarray

gimbal.bonding.num_loops(adjmat, k)

Returns the number of loops of length k.

Only works for 3-loops and 4-loops at the moment.

Parameters:
  • adjmat ((N, N) array_like) – The adjacency matrix.
  • k (int) – The desired number of atoms in the loop.
Returns:

The number of loops with k atoms.

Return type:

int

gimbal.bonding.num_neighbours(adjmat, k)

Returns the number of atoms k atoms away from each atom.

Parameters:
  • adjmat ((N, N) array_like) – The adjacency matrix.
  • k (int) – The desired path length
Returns:

A vector of length N with the number of path of length k for each atom.

Return type:

(N,) ndarray

gimbal.bonding.path_len(adjmat, k)

Returns the matrix of paths of length k from an adjacency matrix.

Ideally, all elements should be unity unless loops are present. Loops are not fully accounted for at the moment. They should lead to nonzero diagonal elements.

Parameters:
  • adjmat ((N, N) array_like) – The adjacency matrix.
  • k (int) – The desired path length.
Returns:

The matrix of elements connected by k bonds.

Return type:

(N, N) ndarray

gimbal.bonding.power(mat, k)

Returns the kth power of a square matrix.

The elements \((\mathbf{A}^k)_{ij}\) of the k-th power of an adjacency matrix represent the number of k-length paths from element i to element j, including repetitions.

Parameters:
  • mat ((N, N) array_like) – The input square matrix, A.
  • k (int) – The power of the matrix.
Returns:

The input matrix to the power k, A^k.

Return type:

(N, N) ndarray

gimbal.constants module

Constant molecular properties to be used in other modules.

Arrays are ordered by atomic number for convenience. Atomic symbols are case sensitive. This module should not depend on other modules.

Unit types

Length: Angstrom (ang), Bohr (bohr), picometre (pm), nanometre (nm)

Angle: radian (rad), degree (deg)

Time: femtosecond (fs), picosecond (ps), atomic unit (au)

Mass: atomic mass unit (amu), electron mass (me), proton mass (mp), kilogram (kg)

Energy: electron volt (ev), Hartree (har), kilocalorie per mole (kcm), kilojoule per mole (kjm), reciprocal centimetre (cm)

For all types, ‘auto’ will give the default unit.

gimbal.constants.sym

List of atomic symbols up to Krypton. The ordering (with the exception of deuterium) yields the correct atomic number from sym.index(elem).

Type:ndarray
gimbal.constants.mass

List of atomic masses corresponding to the elements in sym.

Type:ndarray
gimbal.constants.covrad

List of covalent radii corresponding to the elements in sym.

Type:ndarray
gimbal.constants.lenunits

Dictionary of units of length and their conversions from the default (angstroms).

Type:dict
gimbal.constants.angunits

Dictionary of units of angle and their conversions from the default (radians).

Type:dict
gimbal.constants.timunits

Dictionary of units of time and their conversions from the default (femtoseconds).

Type:dict
gimbal.constants.masunits

Dictionary of units of mass and their conversions from the default (atomic mass units).

Type:dict
gimbal.constants.eneunits

Dictionary of units of energy and their conversion from the default (electron volts).

Type:dict
gimbal.constants.arccos(val)

Returns the arccosine of an angle allowing for numerical errors.

NumPy’s arccos function is defined for the range [-1, 1], but returns NaN for \(|x| = 1 + \delta\), where \(\delta\) is small. This can be avoided by checking for limiting cases with numpy.isclose.

Parameters:val (float) – The x-coordinate on the unit circle.
Returns:The angle intersecting the unit circle at x = val.
Return type:float
gimbal.constants.conv(old='auto', new='auto')

Returns conversion factor from old units to new units.

Parameters:
  • old (str, optional) – The units to be converted from. See different units types for defaults.
  • new (str, optional) – The units to be converted to. See different units types for defaults.
Returns:

The conversion factor, new_units / old_units.

Return type:

float

gimbal.constants.get_covrad(elem)

Returns covalent radius from atomic symbol.

Parameters:elem (str of array_like) – The atomic symbol(s) to be parsed.
Returns:The atomic covalent radii corresponding to each symbol.
Return type:float or ndarray
gimbal.constants.get_mass(elem)

Returns atomic mass from atomic symbol.

Parameters:elem (str of array_like) – The atomic symbol(s) to be parsed.
Returns:The atomic masses corresponding to each symbol.
Return type:float or ndarray
gimbal.constants.get_num(elem)

Returns atomic number from atomic symbol.

Takes advantage of the fact that sym indices match atomic numbers.

Parameters:elem (str or array_like) – The atomic symbol(s) to be parsed.
Returns:The atomic numbers corresponding to each symbol.
Return type:int or ndarray
gimbal.constants.unit_vec(v)

Returns a unit vector aligned with a given vector.

Parameters:v (array_like) – The input, un-normalized vector.
Returns:The normalized (unit) vector.
Return type:ndarray

gimbal.displace module

Routines for displacing a molecular geometry by translation or proper/improper rotation.

  1
  |
  4
 / \
2   3

Example axes for displacements:

  1. X1X4 stretch: \(r_{14}\)
  2. X1X4 torsion: \(r_{14}\) (for motion of 2, 3)
  3. X1X4X2 bend: \(r_{14} \times r_{24}\)
  4. X1 out-of-plane: \(r_{24} - r_{34}\) or \((r_{24} \times r_{34}) \times r_{14}\)

Each internal coordinate measurement has the option of changing the units (see the constants module) or taking the absolute value.

class gimbal.displace.VectorParser(xyz=None)

Bases: object

An object for defining and evaluating vector operations on a cartesian geometry.

A new VectorParser instance takes a cartesian geometry as an optional input. The instance can be called with a vector (no action), 3x3 array (cross product) or string, parsed according to the syntax in generate_parser().

xyz

The cartesian geometry which defines the indices in parsed expressions. If None, only expressions without indices can be parsed.

Type:(N, 3) array_like, optional
unop

A dictionary which defines unary operations.

Type:dict
bnadd

A dictionary which defines binary addition operations.

Type:dict
bnmul

A dictionary which defines binary multiplication operations.

Type:dict
bnop

A dictionary which defines all binary operations.

Type:dict
axes

A dictionary which defines cartesian axis labels.

Type:dict
expr

A pyparsing grammar used to evaluate expressions. Automatically generated when xyz is set.

Type:pyparsing.Forward
generate_parser(xyz=None)

Creates the pyparsing expression based on geometry.

The syntax is as follows:

  • i+ are indices of xyz and return vectors.
  • i+.j are floating point numbers (j optional).
  • i[j] is the j-th (scalar) element of xyz[i].
  • X, Y, Z are unit vectors along x, y and z axes (uppercase only).
  • + and - are addition/subtraction of vectors or scalars.
  • * and / are multiplication/division of vectors and scalars (elementwise).
  • o and x are scalar/vector products of vectors only.
  • ^ is the power of a vector/scalar by a scalar (elementwise).
  • ( and ) specify order of operation.
  • [i, j, k] gives a vector with scalar elements i, j and k.
Parameters:xyz ((N, 3), array_like, optional) – The cartesian geometry used in index expressions. If not provided, strings containing indices will raise an error.
Returns:A pyparsing grammar definition.
Return type:pyparsing.Forward
xyz

Gets the value of xyz.

gimbal.displace.align_axis(xyz, test_ax, ref_ax, ind=None, origin=array([0., 0., 0.]))

Rotates a set of atoms such that two axes are parallel.

Parameters:
  • xyz ((N, 3) array_like) – The atomic cartesian coordinates.
  • test_crd ((3,) array_like) – Cartesian coordinates of the original axis.
  • test_crd – Cartesian coordinates of the final axis.
  • ind (array_like, optional) – List of atomic indices to specify which atoms are displaced. If ind == None (default) then all atoms are displaced.
  • origin ((3,) array_like, optional) – The origin of rotation. Default is the cartesian origin.
Returns:

The atomic cartesian coordinates of the displaced molecule.

Return type:

(N, 3) ndarray

gimbal.displace.align_pos(xyz, test_crd, ref_crd, ind=None)

Translates a set of atoms such that two positions are coincident.

Parameters:
  • xyz ((N, 3) array_like) – The atomic cartesian coordinates.
  • test_crd ((3,) array_like) – Cartesian coordinates of the original position.
  • test_crd – Cartesian coordinates of the final position.
  • ind (array_like, optional) – List of atomic indices to specify which atoms are displaced. If ind == None (default) then all atoms are displaced.
Returns:

The atomic cartesian coordinates of the displaced molecule.

Return type:

(N, 3) ndarray

gimbal.displace.angax(rotmat, units='rad')

Returns the angle, axis of rotation and determinant of a rotational matrix.

Based on the form of R, it can be separated into symmetric and antisymmetric components with \((r_{ij} + r_{ji})/2\) and \((r_{ij} - r_{ji})/2\), respectively. Then,

\[ \begin{align}\begin{aligned}r_{ii} = \cos(a) + u_i^2 (\det(\mathbf{R}) - \cos(a)),\\\cos(a) = (-\det(\mathbf{R}) + \sum_j r_{jj}) / 2 = (\mathrm{tr}(\mathbf{R}) - \det(\mathbf{R})) / 2.\end{aligned}\end{align} \]

From the expression for \(r_{ii}\), the magnitude of \(u_i\) can be found

\[|u_i| = \sqrt{\frac{1 + \det(\mathbf{R}) [2 r_{ii} - \mathrm{tr}(\mathbf{R})])}{3 - \det(\mathbf{R}) \mathrm{tr}(\mathbf{R})}},\]

which satisfies \(u \cdot u = 1\). Note that if \(\det(\mathbf{R}) \mathrm{tr}(\mathbf{R}) = 3\), the axis is arbitrary (identity or inversion). Otherwise, the sign can be found from the antisymmetric component of R.

\[ \begin{align}\begin{aligned}u_i \sin(a) = (r_{jk} - r_{kj}) / 2, \quad i \neq j \neq k,\\\mathrm{sign}(u_i) = \mathrm{sign}(r_{jk} - r_{kj}),\end{aligned}\end{align} \]

since \(\sin(a)\) is positive in the range 0 to \(\pi\). \(i\), \(j\) and \(k\) obey the cyclic relation 3 -> 2 -> 1 -> 3 -> …

This fails when \(det(\mathbf{R}) \mathrm{tr}(\mathbf{R}) = -1\), in which case the symmetric component of R is used

\[ \begin{align}\begin{aligned}u_i u_j (\det(\mathbf{R}) - \cos(a)) = (r_{ij} + r_{ji}) / 2,\\\mathrm{sign}(u_i) \mathrm{sign}(u_j) = \det(\mathbf{R}) \mathrm{sign}(r_{ij} + r_{ji}).\end{aligned}\end{align} \]

The signs can then be found by letting \(\mathrm{sign}(u_3) = +1\), since a rotation of \(pi\) or a reflection are equivalent for antiparallel axes. See http://scipp.ucsc.edu/~haber/ph251/rotreflect_17.pdf

Parameters:
  • rotmat ((3, 3) array_like) – The rotational matrix.
  • units (str, optional) – The output units for the angle. Default is radians.
Returns:

  • ang (float) – The angle of rotation.
  • u ((3,) ndarray) – The axis of rotation as a 3D vector.
  • det (int) – The determinant of the rotation matrix.

Raises:

ValueError – When the absolute value of the determinant is not equal to 1.

gimbal.displace.centre_mass(elem, xyz)

Returns xyz with centre of mass at the origin.

If an index list is provided to inds, only the centre of mass of atoms at those indices will be used.

Parameters:
  • elem ((N,) array_like) – The atomic symbols.
  • xyz ((N, 3) array_like) – The atomic cartesian coordinates.
Returns:

The atomic cartesian coordinates of the displaced molecule.

Return type:

(N, 3) ndarray

gimbal.displace.get_centremass(elem, xyz)

Returns centre of mass of a set of atoms.

Parameters:
  • elem ((N,) array_like) – The atomic symbols.
  • xyz ((N, 3) array_like) – The atomic cartesian coordinates.
Returns:

The position of the centre of mass.

Return type:

(3,) ndarray

gimbal.displace.rotate(xyz, ang, axis, ind=None, origin=array([0., 0., 0.]), det=1, units='rad')

Rotates a set of atoms about a given vector.

An origin can be specified for rotation about a specific point. If no indices are specified, all atoms are displaced. Setting det=-1 leads to an improper rotation.

Parameters:
  • xyz ((N, 3) array_like) – The atomic cartesian coordinates.
  • ang (float) – The angle of rotation.
  • axis (array_like or str) – The axis of rotation, parsed by VectorParser.
  • ind (array_like, optional) – List of atomic indices to specify which atoms are displaced. If ind is None (default) then all atoms are displaced.
  • origin ((3,) array_like, optional) – The origin of rotation, parsed by VectorParser. Default is the cartesian origin.
  • det (float, optional) – The determinant of the rotation. 1 (default) is a proper rotation and -1 is an improper rotation (rotation + reflection).
  • units (str, optional) – The units of length for displacement. Default is angstroms.
Returns:

The atomic cartesian coordinates of the displaced molecule.

Return type:

(N, 3) ndarray

gimbal.displace.rotmat(ang, u, det=1, units='rad', xyz=None)

Returns the rotational matrix based on an angle and axis.

A general rotational matrix in 3D can be formed given an angle and an axis by

\[\mathbf{R} = \cos(a) \mathbf{I} + (\det(\mathbf{R}) - \cos(a)) \mathbf{u} \otimes \mathbf{u} + \sin(a) [\mathbf{u}]_\times\]

for identity matrix I, angle a, axis u, outer product \(\otimes\) and cross-product matrix \([\mathbf{u}]_\times\). Determinants of +1 and -1 give proper and improper rotation, respectively. Thus, \(\det(\mathbf{R}) = -1\) and \(a = 0\) is a reflection along the axis. Action of the rotational matrix occurs about the origin. See en.wikipedia.org/wiki/Rotation_matrix and http://scipp.ucsc.edu/~haber/ph251/rotreflect_17.pdf

Parameters:
  • ang (float) – The angle of rotation.
  • u (array_like or str) – The axis of rotation, converted to a unit vector.
  • det (int, optional) – The determinant of the matrix (1 or -1) used to specify proper and improper rotations. Default is 1.
  • units (str, optional) – The units of angle for the rotation. Default is radians.
  • xyz ((N, 3) array_like, optional) – The cartesian coordinates used in axis specification.
Returns:

The rotational matrix of the given angle and axis.

Return type:

(3, 3) ndarray

Raises:

ValueError – When the absolute value of the determinant is not equal to 1.

gimbal.displace.translate(xyz, amp, axis, ind=None, units='ang')

Translates a set of atoms along a given vector.

Parameters:
  • xyz ((N, 3) array_like) – The atomic cartesian coordinates.
  • amp (float) – The distance for translation.
  • axis (array_like or str) – The axis of translation, parsed by VectorParser.
  • ind (array_like, optional) – List of atomic indices to specify which atoms are displaced. If ind is None (default) then all atoms are displaced.
  • units (str, optional) – The units of length for displacement. Default is angstroms.
Returns:

The atomic cartesian coordinates of the displaced molecule.

Return type:

(N, 3) ndarray

gimbal.fileio module

File input/output functions for molecular geometry files.

Can support XYZ, COLUMBUS and Z-matrix formats. Input and output both require an open file to support multiple geometries. Only 3D geometries are currently supported.

gimbal.fileio.convert(inflist, outfile, infmt='auto', outfmt='auto', inunits=None, outunits=None, hasvec=False, hascom=False)

Reads a file in format infmt and writes to a file in format outfmt.

Input (and output) may have multiple geometries. Z-matrix index ordering is not conserved.

Parameters:
  • inflist (array_like) – The open input files or filenames.
  • outfile (file or str) – The open output file or filename.
  • infmt (str, optional) – The input file format. Default is auto (i.e. read_auto()).
  • outfmt (str, optional) – The input file format. Default is auto (i.e. write_auto()).
  • inunits (str, optional) – The input distance units. If None (default), the default units of the read function are used.
  • outunits (str, optional) – The output distance units. If None (default), the default units of the write function are used.
  • hasvec (bool, optional) – Specifies if a vector should be read from the input file.
  • hascom (bool, optional) – Specifies if a comment line should be read from the input file.
gimbal.fileio.get_optarg(arglist, *opts, default=False)

Gets an optional command line argument and returns its value.

If default is not set, the flag is treated as boolean. Note that that setting default to None or ‘’ will still take an argument after the flag.

Parameters:
  • arglist (array_like) – The command line argument list to be parsed.
  • opts (list) – The arguments searched for in arglist.
  • default (str or bool) – The default value if opts are not found in arglist. If default is False (default), then True is returned if opts are found.
Returns:

The argument value in arglist or its default value.

Return type:

str or bool

gimbal.fileio.read_auto(infile, hasvec=False, hascom=False, **kwargs)

Reads a molecular geometry file and determines the format.

Parameters:
  • infile (file) – The open input file.
  • hasvec (bool, optional) – Specifies if a vector should be read from the input file.
  • hascom (bool, optional) – Specifies if a comment line should be read from the input file.
  • kwargs (dict, optional) – Additional keyword arguments for the read functions.
Returns:

  • elem ((N,) ndarray) – The atomic symbols.
  • xyz ((N, 3) ndarray) – The atomic cartesian coordinates.
  • vec ((N, 3) ndarray) – The vector cartesian coordinates.
  • comment (str) – The comment line.

Raises:

IOError – When the geometry format is not recognized by the input parser.

gimbal.fileio.read_col(infile, units='bohr', hasvec=False, hascom=False)

Reads input file in COLUMBUS format.

COLUMBUS geometry files are in the format:

A nA X1 Y1 Z1 mA
B nB X2 Y2 Z2 mB
...

where A and B are atomic labels, nA and nB are corresponding atomic numbers, mA and mB are corresponding atomic masses and X, Y and Z are cartesian coordinates (in Bohrs).

COLUMBUS geometry files do not provide the number of atoms in each geometry. A comment line (or blank line) must be used to separate molecules.

For the time being, vector input is not supported for the COLUMBUS file format.

Parameters:
  • infile (file) – The open input file.
  • units (str, optional) – The units of length of the cartesian coordinates. Default is Bohr.
  • hasvec (bool, optional) – Specifies if a vector should be read from the input file. If False (default), vec is a zero array.
  • hascom (bool, optional) – Specifies if a comment line should be read from the input file. If False (default), comment is a blank string.
Returns:

  • elem ((N,) ndarray) – The atomic symbols.
  • xyz ((N, 3) ndarray) – The atomic cartesian coordinates.
  • vec ((N, 3) ndarray) – The vector cartesian coordinates.
  • comment (str) – The comment line.

gimbal.fileio.read_gdat(infile, units='bohr', hasvec=False, hascom=False)

Reads input file in FMS90 Geometry.dat format.

Geometry.dat files are in the format:

comment
natm
A X1 Y1 Z1
B X2 Y2 Z2
...
Vx1 Vy1 Vz1
Vx2 Vy2 Vz2
...

where comment is a comment line, natm is the number of atoms, A and B are atomic labels, X, Y and Z are cartesian coordinates and Vq are vectors for cartesian coordinates q. The vectors are only read if hasvec = True.

Parameters:
  • infile (file) – The open input file.
  • units (str, optional) – The units of length of the cartesian coordinates. Default is Bohr.
  • hasvec (bool, optional) – Specifies if a vector should be read from the input file. If False (default), vec is a zero array.
  • hascom (bool, optional) – Specifies if a comment line should be read from the input file. If False (default), comment is a blank string.
Returns:

  • elem ((N,) ndarray) – The atomic symbols.
  • xyz ((N, 3) ndarray) – The atomic cartesian coordinates.
  • vec ((N, 3) ndarray) – The vector cartesian coordinates.
  • comment (str) – The comment line.

Raises:

IOError – When geometry is not in the correct format (natm can’t be read).

gimbal.fileio.read_multiple(inflist, fmt='auto', **kwargs)

Reads multiple files or multiple geometries into lists of data.

Parameters:
  • inflist (array_like) – The open input files or filenames.
  • fmt (str, optional) – The file format. Default is auto (i.e. read_auto()).
  • kwargs (dict, optional) – Additional keyword arguments for the read functions.
Returns:

The outputs of the read function for each file in inflist.

Return type:

list

Raises:

IOError – When no geometries are found in the input file list.

gimbal.fileio.read_single(infile, fmt='auto', **kwargs)

Reads a single geometry from an input file.

Unlike read_auto(), infile can be a string or open file.

Parameters:
  • infile (file or str) – The open input file or filename.
  • fmt (str, optional) – The file format. Default is auto (i.e. read_auto()).
  • kwargs (dict, optional) – Additional keyword arguments for the read function.
Returns:

The output of the read function (elem, xyz, vec, comment).

Return type:

tuple

gimbal.fileio.read_traj(infile, units='bohr', hasvec=False, hascom=False, elem=None, time=None, autocom=False)

Reads input file in FMS/nomad trajectory format

trajectory files are in the format:

T1 X1 Y1 Z1 X2 Y2 ... Vx1 Vy1 Vz1 Vx2 Vy2 ... G Re(A) Im(A) |A| S
T2 X1 Y1 Z1 X2 Y2 ... Vx1 Vy1 Vz1 Vx2 Vy2 ... G Re(A) Im(A) |A| S
...

where T is the time, Vq are the vectors (momenta) for cartesian coordinates q, G is the phase, A is the amplitude and S is the state label. The vectors are only read if hasvec = True.

Trajectory files do not contain atomic labels. If not provided, they are set to dummy atoms which may affect calculations involving atomic properties. A time should be provided, otherwise the first geometry in the file is used.

Parameters:
  • infile (file) – The open input file.
  • units (str, optional) – The units of length of the cartesian coordinates. Default is Bohr.
  • hasvec (bool, optional) – Specifies if a vector should be read from the input file. If False (default), vec is a zero array.
  • hascom (bool, optional) – Specifies if a comment line should be read from the input file. If False (default), comment is a blank string.
  • elem ((N,) array_like, optional) – A list of the atomic symbols. If elem is None (default), the symbols will all be set to ‘X’.
  • time (float, optional) – The desired time of the trajectory. If time is None (default), the first geometry in the buffer is parsed. Otherwise, the file is read until the specified time is found.
  • autocom (bool, optional) – Specifies if a comment line should be automatically generated with time, state and squared amplitude. Default is False.
Returns:

  • elem ((N,) ndarray) – The atomic symbols.
  • xyz ((N, 3) ndarray) – The atomic cartesian coordinates.
  • vec ((N, 3) ndarray) – The vector cartesian coordinates.
  • comment (str) – The comment line.

Raises:

IOError – When the geometry is not in the correct format (empty line or incorrect number of columns).

gimbal.fileio.read_xyz(infile, units='ang', hasvec=False, hascom=False)

Reads input file in XYZ format.

XYZ files are in the format:

natm
comment
A X1 Y1 Z1 [Vx1 Vy1 Vz1]
B X2 Y2 Z2 [Vx2 Vy2 Vz2]
...

where natm is the number of atoms, comment is a comment line, A and B are atomic labels and X, Y and Z are cartesian coordinates (in Angstroms). The vectors Vx, Vy and Vz are optional and will only be read if hasvec = True.

Due to the preceding number of atoms, multiple XYZ format geometries can easily be read from a single file.

Parameters:
  • infile (file) – The open input file.
  • units (str, optional) – The units of length of the cartesian coordinates. Default is Angstroms.
  • hasvec (bool, optional) – Specifies if a vector should be read from the input file. If False (default), vec is a zero array.
  • hascom (bool, optional) – Specifies if a comment line should be read from the input file. If False (default), comment is a blank string.
Returns:

  • elem ((N,) ndarray) – The atomic symbols.
  • xyz ((N, 3) ndarray) – The atomic cartesian coordinates.
  • vec ((N, 3) ndarray) – The vector cartesian coordinates.
  • comment (str) – The comment line.

Raises:

IOError – When geometry is not in the correct format (natm can’t be read).

gimbal.fileio.read_zmt(infile, units='ang', hasvec=False, hascom=False)

Reads input file in Z-matrix format.

Z-matrix files are in the format:

A
B 1 R1
C indR2 R2 indA2 A2
D indR3 R3 indA3 A3 indT3 T3
E indR4 R4 indA4 A4 indT4 T4
...

where A, B, C, D, E are atomic labels, indR, indA, indT are reference atom indices, R are bond lengths (in Angstroms), A are bond angles (in degrees) and T are dihedral angles (in degrees). For example, E is a distance R from atom indR with an E-indR-indA angle of A and an E-indR-indA-indT dihedral angle of T. Alternatively, values can be assigned to a list of variables after the Z-matrix (preceded by a blank line).

Although the number of atoms is not provided, the unique format of the first atom allows multiple geometries to be read without separation by a comment line.

For the time being, vector input is not supported for the Z-matrix file format.

Parameters:
  • infile (file) – The open input file.
  • units (str, optional) – The units of length of the cartesian coordinates. Default is Angstroms.
  • hasvec (bool, optional) – Specifies if a vector should be read from the input file. If False (default), vec is a zero array.
  • hascom (bool, optional) – Specifies if a comment line should be read from the input file. If False (default), comment is a blank string.
Returns:

  • elem ((N,) ndarray) – The atomic symbols.
  • xyz ((N, 3) ndarray) – The atomic cartesian coordinates.
  • vec ((N, 3) ndarray) – The vector cartesian coordinates.
  • comment (str) – The comment line.

Raises:

IOError – When geometry is not in the correct format (no atoms found).

gimbal.fileio.write_auto(outfile, elem, xyz, vec=None, comment='', **kwargs)

Writes geometry to an output file based on the filename extension.

Extensions are not case sensitive. If the extension is not recognized, the default format is XYZ.

Parameters:
  • outfile (file) – The open output file.
  • elem ((N,) array_like) – The atomic symbols.
  • xyz ((N, 3) array_like) – The atomic cartesian coordinates.
  • vec ((N, 3) array_like, optional) – The atomic cartesian vectors. Default is None.
  • comment (str, optional) – The comment line. Default is a blank string.
  • kwargs (dict, optional) – Additional keyword arguments for the write functions.
gimbal.fileio.write_col(outfile, elem, xyz, vec=None, comment='', units='bohr')

Writes geometry to an output file in COLUMBUS format.

For the time being, vector output is not supported for the COLUMBUS file format.

Parameters:
  • outfile (file) – The open output file.
  • elem ((N,) array_like) – The atomic symbols.
  • xyz ((N, 3) array_like) – The atomic cartesian coordinates.
  • vec ((N, 3) array_like, optional) – The atomic cartesian vectors. If vec is None (default), it is not written to the output file.
  • comment (str, optional) – The comment line. Default is a blank string.
  • units (str, optional) – The units of the cartesian coordinates. Default is Bohr.
gimbal.fileio.write_gdat(outfile, elem, xyz, vec=None, comment='', units='bohr')

Writes geometry to an output file in Geometry.dat format.

Parameters:
  • outfile (file) – The open output file.
  • elem ((N,) array_like) – The atomic symbols.
  • xyz ((N, 3) array_like) – The atomic cartesian coordinates.
  • vec ((N, 3) array_like, optional) – The atomic cartesian vectors. If vec is None (default), the vectors are replaced by zeros.
  • comment (str, optional) – The comment line. Default is a blank string.
  • units (str, optional) – The units of the cartesian coordinates. Default is Bohr.
gimbal.fileio.write_multiple(outfile, moldat, fmt='auto', **kwargs)

Writes multiple geometries into a single output file.

Parameters:
  • outfile (file or str) – The open output file or filename.
  • moldat (list) – A list of the inputs of the write function for each molecule.
  • fmt (str, optional) – The file format. Default is auto (i.e. write_auto()).
  • kwargs (dict, optional) – Additional keyword arguments for the write functions.
gimbal.fileio.write_single(outfile, moldat, fmt='auto', **kwargs)

Writes a single geometry to an output file.

Unlike write_auto(), outfile can be a string or open file.

Parameters:
  • outfile (file or str) – The open output file or filename.
  • moldat (tuple) – The inputs of the write function.
  • fmt (str, optional) – The file format. Default is auto (i.e. write_auto()).
  • kwargs (dict, optional) – Additional keyword arguments for the write functions.
gimbal.fileio.write_traj(outfile, elem, xyz, vec=None, comment='', units='bohr', time=0.0, phase=0.0, ramp=0.0, iamp=0.0, state=0.0)

Writes geometry to an output file in FMS/nomad trajectory format.

Parameters:
  • outfile (file) – The open output file.
  • elem ((N,) array_like) – The atomic symbols.
  • xyz ((N, 3) array_like) – The atomic cartesian coordinates.
  • vec ((N, 3) array_like, optional) – The atomic cartesian vectors. If vec is None (default), the vectors are written as zeros.
  • comment (str, optional) – The comment line. Default is a blank string.
  • units (str, optional) – The units of the cartesian coordinates. Default is Bohr.
  • time (float, optional) – The time of the trajectory. Default is zero.
  • phase (float, optional) – The phase of the trajectory. Default is zero.
  • ramp (float, optional) – The real amplitude of the trajectory. Default is zero.
  • iamp (float, optional) – The imaginary amplitude of the trajectory. Default is zero.
  • state (float, optional) – The state of the trajectory. Default is zero.
gimbal.fileio.write_xyz(outfile, elem, xyz, vec=None, comment='', units='ang')

Writes geometry to an output file in XYZ format.

Parameters:
  • outfile (file) – The open output file.
  • elem ((N,) array_like) – The atomic symbols.
  • xyz ((N, 3) array_like) – The atomic cartesian coordinates.
  • vec ((N, 3) array_like, optional) – The atomic cartesian vectors. If vec is None (default), it is not written to the output file.
  • comment (str, optional) – The comment line. Default is a blank string.
  • units (str, optional) – The units of the cartesian coordinates. Default is Angstroms.
gimbal.fileio.write_zmt(outfile, elem, xyz, vec=None, comment='', units='ang')

Writes geometry to an output file in Z-matrix format.

At present, each atom uses the previous atoms in order as references. This could be made ‘smarter’ using the bonding module.

For the time being, vector output is not supported for the Z-matrix file format.

Parameters:
  • outfile (file) – The open output file.
  • elem ((N,) array_like) – The atomic symbols.
  • xyz ((N, 3) array_like) – The atomic cartesian coordinates.
  • vec ((N, 3) array_like, optional) – The atomic cartesian vectors. If vec is None (default), it is not written to the output file.
  • comment (str, optional) – The comment line. Default is a blank string.
  • units (str, optional) – The units of the bond distances. Default is Angstroms.
gimbal.fileio.write_zmtvar(outfile, elem, xyz, vec=None, comment='', units='ang')

Writes geometry to an output file in Z-matrix format with variable assignments.

For the time being, vector output is not supported for the Z-matrix file format.

Parameters:
  • outfile (file) – The open output file.
  • elem ((N,) array_like) – The atomic symbols.
  • xyz ((N, 3) array_like) – The atomic cartesian coordinates.
  • vec ((N, 3) array_like, optional) – The atomic cartesian vectors. If vec is None (default), it is not written to the output file.
  • comment (str, optional) – The comment line. Default is a blank string.
  • units (str, optional) – The units of the bond distances. Default is Angstroms.

gimbal.kabsch module

Module for aligning similar molecular geometries using the Kabsch algorithm.

For a reference and test set of three dimensional vectors, the Kabsch algorithm determines the optimal rotation matrix to minimize the RMSD between each vector pair.

After translating the vector sets of centroids, the covariance matrix A is calculated by \(\mathbf{A} = \mathbf{P}^T \mathbf{Q}\). Then, using singular value decomposition, \(\mathbf{V S W}^T = \mathbf{A}\). The scaling component S is discarded. The handedness of the coordinate system is determined by \(d = \mathrm{sign}(\det(\mathbf{W V}^T))\). The rotation matrix is then found by

\[\begin{split}\mathbf{U} = \mathbf{W} \begin{bmatrix} 1 & 0 & 0 \\ 0 & 1 & 0 \\ 0 & 0 & d \end{bmatrix} \mathbf{V}^T\end{split}\]

(See en.wikipedia.org/wiki/Kabsch_algorithm)

The best match for multiple references can be found by the minimum RMSD. Sets of equivalent vectors (atoms) can be permuted as well.

gimbal.kabsch.kabsch(test, ref, wgt=None, refl=True)

Returns the Kabsch rotational matrix to map a test geometry onto a reference.

If weights are provided, they are used to weight the test vectors before forming the covariance matrix. This minimizes the weighted RMSD between the two geometries. If refl=True, improper rotations are also permitted.

Parameters:
  • test ((N, 3) array_like) – The cartesian test geometry.
  • ref ((N, 3) array_like) – The cartesian reference geometry.
  • wgt ((N,) array_like, optional) – The atomic weights for computing the RMSD. If None (default), all weights are unity.
  • refl (bool, optional) – Specifies if reflections (improper rotations) are permitted. Default is True.
Returns:

The rotational matrix that optimally maps test to ref.

Return type:

(3, 3) ndarray

gimbal.kabsch.map_onto(elem, test, ref, wgt=None, ind=None, cent=None)

Returns the optimal mapping of a test geometry onto a reference using the Kabsch algorithm.

The centre of mass of both test and ref are subtracted by default. If an index or list of indices is provided for cent, only the centre of mass of the provided atoms is subtracted. Alternatively, ind can be provided to only map a subset of atoms.

Parameters:
  • elem ((N,) array_like) – The atomic symbols.
  • test ((N, 3) array_like) – The cartesian test geometry.
  • ref ((N, 3) array_like) – The cartesian reference geometry.
  • wgt ((N,) array_like, optional) – The atomic weights for computing the RMSD. If None (default), all weights are unity.
  • ind (int or array_like, optional) – Indices of test to be mapped onto ref. If None (default), all atoms are used.
  • cent (int or array_like, optional) – Indices used to specify the centre of mass as the origin of rotation. If None (default), the centre of mass is calculated for all atoms.
Returns:

The test geometry optimally mapped onto the ref geometry.

Return type:

(N, 3) ndarray

gimbal.kabsch.opt_multi(elem, testlist, reflist, **kwargs)

Determines the optimal geometries of a set of test geometries against a set of reference geometries.

Parameters:
  • elem ((N,) array_like) – The atomic symbols.
  • testlist ((L, N, 3) array_like) – The cartesian test geometries.
  • reflist ((M, N, 3) array_like) – The cartesian reference geometries.
  • kwargs (dict, optional) – Additional keyword arguments used in opt_permute().
Returns:

geomlist – The test geometries optimally mapped onto each ref geometry with the minimum RMSD. The L test geometries are sorted into to the M reference geometries.

Return type:

(M,..) list

gimbal.kabsch.opt_permute(elem, test, ref, plist=None, equiv=None, wgt=None, ind=None, cent=None)

Determines optimal permutation of test geometry indices for mapping onto reference.

Parameters:
  • elem ((N,) array_like) – The atomic symbols.
  • test ((N, 3) array_like) – The cartesian test geometry.
  • ref ((N, 3) array_like) – The cartesian reference geometry.
  • plist (list, optional) – A list of sets of atomic positions that can be permuted, parsed by _permute_elmnt().
  • equiv (array_like, optional) – A list of sets of indices that are symmetrically equivalent and interchangeable, parsed by _permute_group().
  • wgt ((N,) array_like, optional) – The atomic weights for computing the RMSD. If None (default), all weights are unity.
  • ind (int or array_like, optional) – Indices of test to be mapped onto ref. If None (default), all atoms are used.
  • cent (int or array_like, optional) – Indices used to specify the centre of mass as the origin of rotation. If None (default), the centre of mass is calculated
Returns:

  • geom ((N, 3) ndarray) – The test geometry optimally mapped onto the ref geometry including atomic permutations.
  • err (float) – The root mean squared deviation between test and ref.

gimbal.kabsch.opt_ref(elem, test, reflist, **kwargs)

Determines optimal reference geometry for a given test geometry.

Parameters:
  • elem ((N,) array_like) – The atomic symbols.
  • test ((N, 3) array_like) – The cartesian test geometry.
  • reflist ((M, N, 3) array_like) – The cartesian reference geometries.
  • kwargs (dict, optional) – Additional keyword arguments used in opt_permute().
Returns:

  • geom ((N, 3) ndarray) – The test geometry optimally mapped onto the ref geometry with the minimum RMSD.
  • ind (int) – The index of the optimal ref geometry.

gimbal.kabsch.rmsd(test, ref, wgt=None)

Returns the root mean squared deviation of a test geometry with respect to a reference.

Weights can be provided (e.g. atomic masses) with the optional variable wgt.

Parameters:
  • test ((N, 3) array_like) – The cartesian test geometry.
  • ref ((N, 3) array_like) – The cartesian reference geometry.
  • wgt ((N,) array_like, optional) – The atomic weights for computing the RMSD. If None (default), all weights are unity.
Returns:

The root mean squared deviation between test and ref.

Return type:

float

gimbal.measure module

Routines for measuring internal coordinate values from a cartesian geometry.

gimbal.measure.bend(xyz, *inds, units='rad')

Returns bending angle for 3 atoms in a chain based on index.

Parameters:
  • xyz ((N, 3) array_like) – The atomic cartesian coordinates.
  • inds (list) – The indices for which the bond angle is measured.
  • units (str, optional) – The units of angle for the output. Default is radians.
Returns:

The bond angle.

Return type:

float

gimbal.measure.edgetors(xyz, *inds, units='rad', absv=False)

Returns the torsional angle based on the vector difference of the two external atoms (1-2 and 5-6) to the central 3-4 bond.

Parameters:
  • xyz ((N, 3) array_like) – The atomic cartesian coordinates.
  • inds (list) – The indices for which the edge dihedral angle is measured.
  • units (str, optional) – The units of angle for the output. Default is radians.
  • absv (bool, optional) – Specifies if the absolute value is returned.
Returns:

The edge dihedral angle.

Return type:

float

gimbal.measure.oop(xyz, *inds, units='rad', absv=False)

Returns out-of-plane angle of atom 1 connected to atom 4 in the 2-3-4 plane.

Contains an additional sign convention such that rotation of the out-of-plane atom over (under) the central plane atom gives an angle greater than \(\pi/2\) (less than \(-\pi/2\)).

Parameters:
  • xyz ((N, 3) array_like) – The atomic cartesian coordinates.
  • inds (list) – The indices for which the out-of-plane angle is measured.
  • units (str, optional) – The units of angle for the output. Default is radians.
  • absv (bool, optional) – Specifies if the absolute value is returned.
Returns:

The out-of-plane angle.

Return type:

float

gimbal.measure.planeang(xyz, *inds, units='rad', absv=False)

Returns the angle between the 1-2-3 and 4-5-6 planes.

Parameters:
  • xyz ((N, 3) array_like) – The atomic cartesian coordinates.
  • inds (list) – The indices for which the plane angle is measured.
  • units (str, optional) – The units of angle for the output. Default is radians.
  • absv (bool, optional) – Specifies if the absolute value is returned.
Returns:

The plane angle.

Return type:

float

gimbal.measure.planetors(xyz, *inds, units='rad', absv=False)

Returns the plane angle with the central bond projected out.

Parameters:
  • xyz ((N, 3) array_like) – The atomic cartesian coordinates.
  • inds (list) – The indices for which the plane dihedral angle is measured.
  • units (str, optional) – The units of angle for the output. Default is radians.
  • absv (bool, optional) – Specifies if the absolute value is returned.
Returns:

The plane dihedral angle.

Return type:

float

gimbal.measure.stre(xyz, *inds, units='ang')

Returns bond length based on index.

Parameters:
  • xyz ((N, 3) array_like) – The atomic cartesian coordinates.
  • inds (list) – The indices for which the bond distance is measured.
  • units (str, optional) – The units of length for the output. Default is Angstroms.
Returns:

The bond length.

Return type:

float

gimbal.measure.tors(xyz, *inds, units='rad', absv=False)

Returns dihedral angle for 4 atoms in a chain based on index.

Parameters:
  • xyz ((N, 3) array_like) – The atomic cartesian coordinates.
  • inds (list) – The indices for which the dihedral angle is measured.
  • units (str, optional) – The units of angle for the output. Default is radians.
  • absv (bool, optional) – Specifies if the absolute value is returned.
Returns:

The dihedral angle.

Return type:

float

gimbal.molecule module

The Molecule and MoleculeBundle objects and tools for generating and querying molecular geometries.

Molecule creates a saved copy of the geometry after input for reversion after an operation. Can add/remove individual atoms or groups or set the full geometry.

Likewise, MoleculeBundle creates a saved copy of a set molecular geometries. Input files with multiple geometries can be read to a bundle.

class gimbal.molecule.BaseMolecule(elem=[], xyz=array([], shape=(0, 3), dtype=float64), vec=None, comment='')

Bases: object

Basic object containing molecular geometry and functions for setting and changing the geometry.

All methods of BaseMolecule involve setting and saving the molecular geometry. There are no dependencies to other modules.

elem

The atomic symbols.

Type:(N,) ndarray
xyz

The atomic cartesian coordinates.

Type:(N, 3) ndarray
vec

The atomic cartesian vectors.

Type:(N, 3) ndarray
comment

The comment line.

Type:str
natm

The number of atoms N. Automatically set during initialization.

Type:int
print_vec

Specifies if the vectors should be printed/written. Automatically set to False if vec is None (default).

Type:bool
save_elem

The saved atomic symbols.

Type:(N,) ndarray
save_xyz

The saved atomic cartesian coordinates.

Type:(N, 3) ndarray
save_vec

The saved atomic cartesian vectors.

Type:(N, 3) ndarray
save_comment

The saved comment line.

Type:str
save_print_vec

Specifies if the vectors should be printed/written. Automatically set to False if vec is None (default).

Type:bool
saved

Specifies if the save_... values are up to date.

Type:bool
add_atoms(new_elem, new_xyz, new_vec=None)

Adds atoms(s) to molecule.

Parameters:
  • new_elem ((n,) array_like) – The new atomic symbols to be added to the current symbol list.
  • new_xyz ((n, 3) array_like) – The new atomic cartesian coordinates to be added to the current coordinate list.
  • new_vec ((n, 3) array_like, optional) – The new atomic cartesian vectors to be added to the current vector list. If None (default), zeros are added to match new_xyz.
comment

Gets the value of comment.

copy(comment=None)

Creates a copy of the BaseMolecule object.

Parameters:comment (str) – A comment line for the copied BaseMolecule. If None (default), self._comment is used.
Returns:A copy of the BaseMolecule instance.
Return type:BaseMolecule
elem

Gets the value of elem.

rearrange(new_ind, old_ind=None)

Moves atom(s) from old_ind to new_ind.

Parameters:
  • new_ind (array_like) – New indices for the atoms.
  • old_ind (array_like, optional) – Old indices for the atoms. If None (default), new_ind must include all atoms.
revert()

Reverts properties to save_ variables.

rm_atoms(ind)

Removes atom(s) from molecule by index.

Parameters:ind (int or array_like) – Index or indices of atoms to be removed.
save()

Saves molecular properties to save_ variables.

vec

Gets the value of vec.

xyz

Gets the value of xyz.

class gimbal.molecule.Molecule(elem=[], xyz=array([], shape=(0, 3), dtype=float64), vec=None, comment='')

Bases: gimbal.molecule.BaseMolecule

More advanced Molecule object which inherits from BaseMolecule.

A dummy atom XM is added to index 0 at the centre of mass of the molecule. Indices thus match the regular definition. Accessor methods get_elem and get_xyz return the geometry without the index 0 dummy atom.

Molecule can also read from and write to input files given by a filename or an open file object. Other methods are derived from different modules.

elem

The atomic symbols.

Type:(N+1,) ndarray
xyz

The atomic cartesian coordinates.

Type:(N+1, 3) ndarray
vec

The atomic cartesian vectors.

Type:(N+1, 3) ndarray
comment

The comment line.

Type:str
natm

The number of atoms N. Automatically set during initialization.

Type:int
print_vec

Specifies if the vectors should be printed/written. Automatically set to False if vec is None (default).

Type:bool
centre_mass()

Places the centre of mass at the origin.

copy(comment=None)

Creates a copy of the Molecule object.

Parameters:comment (str) – A comment line for the copied Molecule. If None (default), self._comment is used.
Returns:A copy of the Molecule instance.
Return type:Molecule
get_formula()

Gets the atomic formula based on the element list.

Returns:The molecular atomic formula as a string.
Return type:str
get_mass()

Returns atomic masses.

Returns:The array of atomic masses.
Return type:ndarray
match_to_ref(ref_bundle, **kwargs)

Tests the molecule against a set of references in a bundle.

At the moment, vectors are not properly rotated.

Parameters:
  • ref_bundle (MoleculeBundle) – A molecule bundle object containing the set of reference geometries.
  • kwargs (dict) – Additional keyword arguments used in kabsch.opt_permute().
Returns:

The index of the optimal ref geometry.

Return type:

int

measure(coord, *inds, **kwargs)

Returns a coordinate based on its indices in the molecule.

Parameters:
  • coord (str) – The coordinate specification, given by function names in measure.
  • inds (list) – The indices used in the coordinate function.
  • kwargs (dict, optional) – Additional keyword arguments for the measure functions.
Returns:

The value of the specified coordinate.

Return type:

float

read(infile, fmt='auto', **kwargs)

Reads single geometry from input file in provided format.

Parameters:
  • infile (file or str) – The open input file or filename.
  • fmt (str, optional) – The file format. Default is auto (i.e. fileio.read_auto()).
  • kwargs (dict, optional) – Additional keyword arguments for the read function.
rearrange(new_ind, old_ind=None)

Moves atom(s) from old_ind to new_ind.

Parameters:
  • new_ind (array_like) – New indices for the atoms.
  • old_ind (array_like, optional) – Old indices for the atoms. If None (default), new_ind must include all atoms except for the dummy atom (index 0).
rotate(amp, axis, ind=None, origin=array([0., 0., 0.]), det=1, units='rad')

Rotates the molecule about a given axis from a given origin.

If vectors are non-zero, they will be rotated about the same origin. Reflections and improper rotations can be done by setting det=-1.

Parameters:
  • amp (float) – The angle of rotation.
  • axis (array_like or str) – The axis of rotation, parsed by displace._parse_axis().
  • ind (array_like, optional) – List of atomic indices to specify which atoms are displaced. If ind is None (default) then all atoms are displaced.
  • origin ((3,) array_like, optional) – The origin of rotation. Default is the cartesian origin.
  • det (float, optional) – The determinant of the rotation. 1 (default) is a proper rotation and -1 is an improper rotation (rotation + reflection).
  • units (str, optional) – The units of length for displacement. Default is angstroms.
subst(lbl, isub, ibond=None, pl=None)

Replaces an atom or set of atoms with a substituent.

Parameters:
  • lbl (str) – The substituent label.
  • isub (int or list) – The atomic index (or indices) to be replaced by the substituent.
  • ibond (int, optional) – The atomic index of the atom bonded to position isub. If None (default), the nearest atom is chosen.
  • pl (int or array_like, optional) – The atomic index or vector defining the xz-plane of the substituent. See substitute.subst() for more details.
translate(amp, axis, ind=None, units='ang')

Translates the molecule along a given axis.

Momenta are difference vectors and are not translated.

Parameters:
  • amp (float) – The distance for translation.
  • axis (array_like or str) – The axis of translation, parsed by displace._parse_axis().
  • ind (array_like, optional) – List of atomic indices to specify which atoms are displaced. If ind is None (default) then all atoms are displaced.
  • units (str, optional) – The units of length for displacement. Default is angstroms.
write(outfile, fmt='auto', **kwargs)

Writes geometry to an output file in provided format.

Parameters:
  • outfile (file or str) – The open output file or filename.
  • fmt (str, optional) – The file format. Default is auto (i.e. fileio.write_auto()).
  • kwargs (dict, optional) – Additional keyword arguments for the write function.
class gimbal.molecule.MoleculeBundle(molecules=[])

Bases: object

Object containing a set of molecules in the form of Molecule objects.

molecules

The array of Molecule objects.

Type:ndarray
nmol

The number of molecules, set automatically during initialization.

Type:int
save_molecules

The saved array of Molecule objects.

Type:ndarray
saved

Specifies if the save_molecules value is up to date.

Type:bool
add_molecules(new_molecules)

Adds molecule(s) to the bundle.

Parameters:new_molecules ((n,) array_like) – The new Molecule objects to be added to the current molecule list.
copy()

Returns a copy of the MoleculeBundle object.

Returns:A copy of the MoleculeBundle instance.
Return type:MoleculeBundle
match_to_ref(ref_bundle, plist=None, equiv=None, wgt=None, ind=None, cent=None)

Tests the molecules in the current bundle against a set of references in another bundle.

Returns a set of bundles corresponding to the reference indices.

Parameters:
  • ref_bundle (MoleculeBundle) – A molecule bundle object containing the set of reference geometries.
  • kwargs (dict) – Additional keyword arguments used in kabsch.opt_permute().
Returns:

The indices of the optimal ref geometries for each molecule.

Return type:

ndarray

measure(coord, *inds, **kwargs)

Returns a list of coordinates based on index in molecules.

Parameters:
  • coord (str) – The coordinate specification, given by function names in measure.
  • inds (list) – The indices used in the coordinate function.
  • kwargs (dict, optional) – Additional keyword arguments for the measure functions.
Returns:

The values of the specified coordinate for each molecule.

Return type:

ndarray

molecules

Gets the value of molecules.

read(inflist, fmt='auto', **kwargs)

Reads all geometries from input file in provided format.

Parameters:
  • infile (array_like) – The open input files or filenames.
  • fmt (str, optional) – The file format. Default is auto (i.e. fileio.read_auto()).
  • kwargs (dict, optional) – Additional keyword arguments for the read function.
rearrange(new_ind, old_ind=None)

Moves molecule(s) from old_ind to new_ind in bundle.

Parameters:
  • new_ind (array_like) – New indices for the molecules.
  • old_ind (array_like, optional) – Old indices for the molecules. If None (default), new_ind must include all molecules.
revert()

Reverts each molecule in the bundle to the saved variables.

rm_molecules(ind)

Removes molecule(s) from the bundle by index.

Parameters:ind (int or array_like) – Index or indices of molecules to be removed.
save()

Saves all molecules in the bundle and sets save_molecules.

write(outfile, fmt='auto', **kwargs)

Writes geometries to an output file in provided format.

Parameters:
  • outfile (file or str) – The open output file or filename.
  • fmt (str, optional) – The file format. Default is auto (i.e. fileio.write_auto()).
  • kwargs (dict, optional) – Additional keyword arguments for the write function.
gimbal.molecule.import_bundle(fnamelist, fmt='auto', **kwargs)

Imports geometries in provided format to MoleculeBundle object.

The fnamelist keyword can be a single filename or a list of filenames. If fmt=’auto’, different files may have different formats.

Parameters:
  • fnamelist (array_like) – The open input files or filenames.
  • fmt (str, optional) – The file format. Default is auto (i.e. fileio.read_auto()).
  • kwargs (dict, optional) – Additional keyword arguments for the read function.
Returns:

The imported MoleculeBundle object.

Return type:

MoleculeBundle

gimbal.molecule.import_molecule(fname, fmt='auto', **kwargs)

Imports geometry in provided format to Molecule object.

Parameters:
  • fname (file or str) – The open input file or filename.
  • fmt (str, optional) – The file format. Default is auto (i.e. fileio.read_auto()).
  • kwargs (dict, optional) – Additional keyword arguments for the read function.
Returns:

The imported Molecule object.

Return type:

Molecule

gimbal.substitute module

Substitution of molecular geometries with functional groups.

Given a cartesian geometry and element labels, a substituent can be added knowing (a) the substituent identity (b) the desired position to substitute and (c) the bond axis for substitution.

This requires some default information, such as the default structure and orientation of the substituent (relative to an axis) and the bond length of the substituent. For now, only single bonds are treated.

class gimbal.substitute.SubLib

Bases: object

Object containing a library of substituent geometries.

syn

A dictionary of synonyms used to find the appropriate substituents.

Type:dict
elem

A dictionary of atomic symbols for each substituent.

Type:dict
xyz

A dictionary of atomic cartesian coordinates for each substituent.

Type:dict
add_subs(*lbls, inds=-1)

Returns the element list and cartesian geometry from a combination of substituents.

Parameters:
  • lbls (list) – A list of substituent labels to be combined.
  • inds (int or array_like, optional) – The indices for substitution between substituents. Setting inds=-1 (default) makes the last atom the subtituted atom. Otherwise a list of indices can be given for the first of each pair of substituents.
Returns:

  • elem ((N,) ndarray) – The atomic symbols of the combined substituent.
  • xyz ((N, 3) ndarray) – The atomic cartesian coordinates of the combined substituent.

get_sub(label)

Returns the element list and cartesian geometry of a substituent.

Parameters:label (str) – The substituent label of the desired substituent.
Returns:
  • elem ((N,) ndarray) – The atomic symbols of the substituent.
  • xyz ((N, 3) ndarray) – The atomic cartesian coordinates of the substituent.
gimbal.substitute.import_sub(label)

Returns the element list and cartesian geometry of a substituent given its label.

Parameters:label (str) – The substituent label.
Returns:
  • elem ((N,) ndarray) – The atomic symbols of the substituent.
  • xyz ((N, 3) ndarray) – The atomic cartesian coordinates of the substituent.
gimbal.substitute.subst(elem, xyz, sublbl, isub, ibond=None, pl=None, vec=None)

Returns a molecular geometry with an specified atom replaced by substituent.

Labels are case-insensitive. The index isub gives the position to be substituted. If specified, ibond gives the atom bonded to the substituent. Otherwise, the nearest atom to isub is used. The orientation of the substituent can be given as a vector (the plane normal) or an index (the plane containing isub, ibond and pl).

If isub is given as a list, the entire list of atoms is removed and the first index is treated as the position of the substituent.

Parameters:
  • elem ((N,) array_like) – The atomic symbols of the unsubstituted molecule.
  • xyz ((N, 3) array_like) – The atomic cartesian coordinates of the unsubstituted molecule.
  • sublbl (str) – The substituent label.
  • isub (int or list) – The atomic index (or indices) to be replaced by the substituent.
  • ibond (int, optional) – The atomic index of the atom bonded to position isub. If None (default), the nearest atom is chosen.
  • pl (int or array_like, optional) – The atomic index or vector defining the xz-plane of the substituent. If an index is given, the plane normal to the isub-ibond-pl plane is used. If None (default), the plane is arbitrarily set to [1, 1, 1] and the bond axis is projected out.
  • vec ((N, 3) array_like, optional) – The atomic cartesian vectors of the unsubstitued molecule. Default is None.
Returns:

  • new_elem ((N,) ndarray) – The atomic symbols of the substituted molecule.
  • new_xyz ((N, 3) ndarray) – The atomic cartesian coordinates of the substituted molecule.
  • new_vec ((N, 3) ndarray) – The atomic cartesian vectors of the substituted molecule. Substituent atoms are all set of zero. If vec is None, new_vec is all zeros.

gimbal.symmetry module

Routines to detect, symmetrize and generate symmetric geometries.

The symmetric axes are automatically found by the principal axes of rotation for convenience. As a result, some axes need to be rearranged to match normal conventions depending on the type of rotor.

gimbal.symmetry.assign_rotor(moms)

Returns the type of rotor based on the moments of inertia.

gimbal.symmetry.cart_jumble(xyz, thresh=0.001)

Moves cartesian coordinates by random amounts up to a given threshold.

Parameters:
  • xyz ((N, 3) array_like) – The set of atomic cartesian coordinates.
  • thresh (float, optional) – The maximum random cartesian displacement.
Returns:

The randomly displaced cartesian coordinates.

Return type:

(N, 3) ndarray

gimbal.symmetry.principal_axes(elem, xyz)

Returns the moments of inertia and corresponding principal axes of a geometry.

The moments of inertia are found by diagonalizing the inertia tensor,

\[\mathbf{A} = (\mathbf{r} \cdot \mathbf{r}) \mathbf{I} - \mathbf{r} \otimes \mathbf{r}\]

where I is the identity and \(\otimes\) is an open product. The coordinates r are mass weighted cartesian coordinates, \(r_i = m_i^{1/2} q_i\)

Parameters:
  • elem ((N,) array_like) – The atomic element list.
  • xyz ((N, 3) array_like) – The cartesian coordinates of each atom.
Returns:

  • (3,) ndarray – The magnitudes of principal moments of inertia.
  • (3, 3) ndarray – The principal axes of inertia.

gimbal.symmetry.symmetrize(elem, xyz, thresh=0.001)

Returns a geometry and its point group with symmetry defined by a geometric threshold.

The output geometry is rotated to have symmetry elements along cartesian axes if possible.

Parameters:
  • elem ((N,) array_like) – The atomic element list.
  • xyz ((N, 3) array_like) – The cartesian coordinates of each atom.
  • thresh (float, optional) – The tolerance threshold for symmetry recognition.
Returns:

The cartesian coordinates of the symmetrized molecule.

Return type:

(N, 3) ndarray

Module contents

Gimbal – Properties and transformations of 3D molecular geometries.