opan.hess¶

Module implementing imports of Hessian data from external computations.

The abstract superclass SuperOpanHess defines a common initializer and common method(s) for use by subclasses importing Hessian data from external computational packages.

Implemented Subclasses

OrcaHess – Imports ‘.hess’ files from ORCA

Requirements

The import for each external software package SHOULD have its own subclass.

Each subclass MUST implement a _load(**kwargs) method as the entry point for import of Hessian data.

The Hessian data MUST be stored:

In the instance member self.hess

As a two-dimensional np.array

With dtype descended from np.float

In units of Hartrees per Bohr-squared \(\left(\frac{\mathrm{E_h}}{\mathrm B^2}\right)\)

With elements arranged as:

\[\begin{split}\left[ \begin{array}{ccccccc} \frac{\partial^2 E}{\partial x_1^2} & \frac{\partial^2 E}{\partial x_1\partial y_1} & \frac{\partial^2 E}{\partial x_1\partial z_1} & \frac{\partial^2 E}{\partial x_1\partial x_2} & \dots & \frac{\partial^2 E}{\partial x_1\partial y_N} & \frac{\partial^2 E}{\partial x_1\partial z_N} \\ \frac{\partial^2 E}{\partial y_1\partial x_1} & \frac{\partial^2 E}{\partial y_1^2} & \frac{\partial^2 E}{\partial y_1\partial z_1} & \frac{\partial^2 E}{\partial y_1\partial x_2} & \dots & \frac{\partial^2 E}{\partial y_1\partial y_N} & \frac{\partial^2 E}{\partial y_1\partial z_N} \\ \frac{\partial^2 E}{\partial z_1\partial x_1} & \frac{\partial^2 E}{\partial z_1\partial y_1} & \frac{\partial^2 E}{\partial z_1^2} & \frac{\partial^2 E}{\partial z_1\partial x_2} & \dots & \frac{\partial^2 E}{\partial z_1\partial y_N} & \frac{\partial^2 E}{\partial z_1\partial z_N} \\ \frac{\partial^2 E}{\partial x_2\partial x_1} & \frac{\partial^2 E}{\partial x_2\partial y_1} & \frac{\partial^2 E}{\partial x_2\partial z_1} & \frac{\partial^2 E}{\partial x_2^2} & \dots & \frac{\partial^2 E}{\partial x_2\partial y_N} & \frac{\partial^2 E}{\partial x_2\partial z_N} \\ \vdots & \vdots & \vdots & \vdots & \ddots & \vdots & \vdots \\ \frac{\partial^2 E}{\partial y_N\partial x_1} & \frac{\partial^2 E}{\partial y_N\partial y_1} & \frac{\partial^2 E}{\partial y_N\partial z_1} & \frac{\partial^2 E}{\partial y_N\partial x_2} & \dots & \frac{\partial^2 E}{\partial y_N^2} & \frac{\partial^2 E}{\partial y_N\partial z_N} \\ \frac{\partial^2 E}{\partial z_N\partial x_1} & \frac{\partial^2 E}{\partial z_N\partial y_1} & \frac{\partial^2 E}{\partial z_N\partial z_1} & \frac{\partial^2 E}{\partial z_N\partial x_2} & \dots & \frac{\partial^2 E}{\partial z_N\partial y_N} & \frac{\partial^2 E}{\partial z_N^2} \\ \end{array} \right]\end{split}\]

Note

The Hessian is elsewhere assumed to be symmetric (real-Hermitian), and thus MUST be returned as such here. Symmetric character is NOT explicitly checked, however!

The geometry data MUST be stored:

In the instance member self.geom

As a one-dimensional np.array

With dtype descended from np.float

In units of Bohrs \(\left(\mathrm B\right)\)

With elements ordered as:

\[\begin{split}\left[ \begin{array}{cccccccc} x_1 & y_1 & z_1 & x_2 & y_2 & \dots & y_N & z_N \\ \end{array} \right]\end{split}\]

The atoms list MUST be stored:

In the instance member self.atom_syms

As a list of str, with each atom specified by an all-caps atomic symbol (opan.const.atom_sym may be helpful)

Subclasses MAY define an unlimited number of methods, class variables, and/or instance variables in addition to those defined above, of unrestricted type.

Superclass

class opan.hess.SuperOpanHess(**kwargs)¶

Abstract superclass of Hessian import classes.

Performs the following actions:

Ensures that the abstract superclass is not being instantiated, but instead a subclass.
Calls the _load() method on the subclass, passing all kwargs through unmodified.
Typechecks the self.hess, self.geom, and self.atom_syms required members for existence, proper data type, and properly matched lengths/dimensions.

The checks performed in step 3 are primarily for design-time member and type enforcement during development of subclasses for new external software packages, rather than run-time data checking. It is RECOMMENDED to include robust data validity checking inside each subclass, rather than relying on these tests.

Methods

check_geom(coords, atoms[, tol])¶

Check for consistency of Hessian geometry with input coords/atoms.

The cartesian coordinates associated with a Hessian object are considered consistent with the input coords and atoms if each component matches to within tol and all atoms are identical. If coords or atoms vectors are passed that are of different length than those stored in the instance, a False value is returned, rather than an exception raised.

Parameters:	coords – length-3N `np.float_` – Vector of stacked ‘lab-frame’ Cartesian coordinates atoms – length-N `str` or `int` – Vector of atom symbols or atomic numbers tol – `float`, optional – Tolerance for acceptable deviation of each passed geometry coordinate from that in the instance to still be considered matching. Default value is `DEF.HESS_COORD_MATCH_TOL`

See opan.utils.check_geom for details on return values and exceptions raised.

Subclasses

class opan.hess.OrcaHess(path='...')¶

Container for HESS data generated by ORCA.

Initialize by passing the path to the file to be loaded as the path keyword argument.

Information contained includes the Hessian matrix, the number of atoms, the atomic symbols, the atomic weights, and the geometry, as reported in the .hess file. See ‘Instance Variables’ below for a full list. For variables marked “required”, a HessError is raised if the block is not found, whereas for variables marked “optional” a None value is stored. For either type, if the data is malformed or invalid in some fashion, a HessError is raised with an appropriate typecode.

Zero frequencies corresponding to translation/rotation are not excised from the frequencies list, normal modes, IR spectrum, Raman spectrum, etc.

The precision of the geometry is less than that reported in an .xyz file, and thus should not be used for generation of subsequent computations.

Output units:

Hessian : Hartrees per Bohr-squared \(\left(\frac{\mathrm{E_h}}{\mathrm{B}^2}\right)\)

Frequencies : Wavenumbers \(\left(\frac{\mathrm{cyc}}{\mathrm{cm}}\right)\)

IR intensities (\(T^2\) values) : \(\frac{\mathrm{km}}{\mathrm{mol}}\)

Raman activities : \(\frac{\mathring{\mathrm{A}}^4}{\mathrm u}\)

Dipole derivatives : (???)

Polarizability derivatives : (???)

Eigenvalues of the mass-weighted Hessian : \(\frac{\mathrm{E_h}}{\mathrm{u\,B^2}}\)

Eigenvectors of the mass-weighted Hessian : (dimensionless)

Methods

_load(**kwargs)¶

Initialize OrcaHess Hessian object from .hess file

Searches indicated file for data blocks within the .hess file. The geometry, Hessian block, frequencies, and normal modes must be present and will be retrieved; other blocks will be imported if present, or ignored if absent (stored as None in the resulting object). If malformed/inaccurate data is found in any block that is present, some flavor of HessError will be raised.

Parameters:	path – `str` – kwargs parameter specifying complete path to the .hess file to be read.
Raises:	`HessError` – (various typecodes) If indicated Hessian file is malformed in some fashion. `KeyError` – If invalid atomic symbol appears in .hess file. `IOError` – If the indicated file does not exist or cannot be read.

Class Variables

class Pat¶

re.compile() patterns for data parsing.

at_block¶: Captures the entire block of atom IDs & weights, as well as the geometry data.

at_line¶: Retrieves individual lines within the atom / geometry specification block.

dipder_block¶: Captures the entire dipole derivatives block.

dipder_line¶: Retrieves individual lines in the dipole derivatives block.

eigvals_block¶: Captures the entire mass-weighted Hessian eigenvalues block.

eigvals_line¶: Retrieves individual lines of the mass-weighted hessian eigenvalues block.

eigvecs_block¶: Captures the entire set of mass-weighted Hessian eigenvectors blocks.

eigvecs_sec¶: Extracts sections (individual blocks) of the mass-weighted Hessian eigenvectors blocks.

eigvecs_line¶: Retrieves individual lines of a mass-weighted Hessian eigenvectors block.

energy¶: Retrieves the energy reported in the .hess file.

freq_block¶: Captures the entire vibrational frequencies block.

freq_line¶: Retrieves individual lines of the frequencies block.

hess_block¶: Captures the entire set of Hessian blocks.

hess_sec¶: Extracts full-height, 3- or 6-column sections (individual blocks) of the set of Hessian blocks.

hess_line¶: Retrieves individual lines within a Hessian block.

jobs_block¶: Captures the entire job list block.

jobs_line¶: Retrieves individual lines of the job list block.

ir_block¶: Captures the entire IR spectrum block

ir_line¶: Retrieves individual lines of the IR spectrum block

modes_block¶: Captures the entire set of (weighted, column-normalized) normal modes blocks

modes_sec¶: Extracts full-height, 3- or 6-column sections (individual blocks) of the set of normal modes blocks

modes_line¶: Retrieves individual lines within a normal modes block

polder_block¶: Captures the polarizability derivatives block

polder_line¶: Retrieves individual lines in the polarizability derivatives block

raman_block¶: Captures the Raman spectrum block

raman_line¶: Retrieves individual lines in the Raman spectrum block

temp¶: Retrieves the ‘actual temperature’ field (sometimes is spuriously zero)

Instance Variables

atom_masses¶: length-N list of np.float_ – List of atom masses as reported in the .hess file

atom_syms¶: length-N list of str – List of uppercase atomic symbols

dipders¶: 3N x 3 np.float_ – Matrix of dipole derivatives

energy¶: float – Electronic energy reported in the Hessian file

freqs¶: length-3N np.float_ – Vibrational frequencies in \(\mathrm{cyc\over cm}\), as reported in the Hessian file

geom¶: length-3N np.float_ – Geometry vector

hess¶: 3N x 3N np.float_ – Cartesian Hessian matrix

hess_path¶: str – Complete path/filename from which the Hessian data was retrieved

in_str¶: str – Complete contents of the imported .hess file

ir_comps¶: 3N x 3 np.float_ – \(\left(T_x, T_y, T_z\right)\) components of the transition dipole for each normal mode

ir_mags¶: length-3N np.float_ – \(T^2\) values (squared-magnitudes) of the transition dipole for each mode

joblist¶: N x 3 bool – Completion status for each displacement in calculation of the Hessian

modes¶: 3N x 3N np.float_ – Rotation- and translation-purified, mass-weighted vibrational normal modes, with each mode (column vector) separately normalized by ORCA.

mwh_eigvals¶: length-3N np.float_ – Eigenvalues of the mass-weighted Hessian, in \(\mathrm{E_h \over u\,B^2}\)

mwh_eigvecs¶: 3N x 3N np.float_ – Eigenvectors of the mass-weighted Hessian, as column vectors: the eigenvector of eigenvalue \(i\) would be retrieved with mwh_eigvecs[:,i]

num_ats¶: int – Number of atoms in the system

polders¶: 3N x 6 np.float_ – Matrix of Cartesian polarizability derivatives

raman_acts¶: length-3N np.float_ – Vector of Raman activities

raman_depols¶: length-3N np.float_ – Vector of Raman depolarization factors

temp¶: float – “Actual temperature” reported in the .hess file. Occasionally stored by ORCA as a meaningless zero value instead of the temperature used.