opan.grad

Module implementing imports of gradient data from external computations.

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


Implemented Subclasses

OrcaEngrad – Imports ‘.engrad’ files from ORCA


Requirements

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

  • Each subclass MUST implement a _load(self, **kwargs) instance method as the entry point for import of gradient data.

  • The gradient data MUST be stored:

    • In the instance member self.gradient
    • As a one-dimensional np.array
    • With dtype descended from np.float
    • In units of Hartrees per Bohr \(\left(\frac{\mathrm{E_h}}{\mathrm B}\right)\)
    • With elements ordered as:
    \[\begin{split}\left[ \begin{array}{cccccccc} \frac{\partial E}{\partial x_1} & \frac{\partial E}{\partial y_1} & \frac{\partial E}{\partial z_1} & \frac{\partial E}{\partial x_2} & \frac{\partial E}{\partial y_2} & \dots & \frac{\partial E}{\partial y_N} & \frac{\partial E}{\partial z_N} \\ \end{array} \right]\end{split}\]

  • 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 of unrestricted type, in addition to those defined above.


Superclass

class opan.grad.SuperOpanGrad(**kwargs)

Abstract superclass of gradient import classes.

Performs the following actions:

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

The checks performed in step 3 are primarily for design-time member- and type-enforcement during development of subclasses for newly implemented 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 gradient geometry with input coords/atoms.

The cartesian coordinates associated with a gradient object are considered consistent with the input coords if each component matches to within tol. 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.GRAD_COORD_MATCH_TOL

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


Subclasses

class opan.grad.OrcaEngrad(path='...')

Container for gradient data generated by ORCA.

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

Key information contained includes the gradient, the energy, the number of atoms, the geometry, and the atom IDs. For ORCA, the precision of the geometry is inferior to that in an XYZ file.


Methods

_load(**kwargs)

Initialize OrcaEngrad object from .engrad file

Searches indicated file for energy, geometry, gradient, and number of atoms and stores in the corresponding instance variables.

Parameters:

path – str – Complete path to the .engrad file to be read.
Raises:

  • GradError – Typecode OVERWRITE – If OrcaEngrad instance has already been instantiated.

    Various typecodes – If indicated gradient file is malformed in some fashion

  • IOError – If the indicated file does not exist or cannot be read

Class Variables

class Pat

re.compile() patterns for data parsing.


atblock

Captures the entire block of atom ID & geometry data.

atline

Extracts single lines from the atom ID / geometry block.

energy

Captures the electronic energy.

gradblock

Captures the gradient data block.

numats

Retrieves the stand-along ‘number of atoms’ field.


Instance Variables

atom_syms

length-N list of str – Uppercased atomic symbols for the atoms in the system.

energy

float – Single-point energy for the geometry.

geom

length-3N np.float_ – Vector of the atom coordinates in \(\mathrm B\).

gradient

length-3N np.float_ – Vector of the Cartesian gradient in \(\frac{\mathrm{E_h}}{\mathrm B}\).

in_str

str – Complete text of the ENGRAD file read in to generate the OrcaEngrad instance.

num_ats

int – Number of atoms in the geometry (‘N’)