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:
- X1X4 stretch: \(r_{14}\)
- X1X4 torsion: \(r_{14}\) (for motion of 2, 3)
- X1X4X2 bend: \(r_{14} \times r_{24}\)
- 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
andx
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
(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
- coord (str) – The coordinate specification, given by function names
in
-
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
- coord (str) – The coordinate specification, given by function names
in
-
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:
-
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:
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.