Source code for strainjedi.jedi

import warnings
from pathlib import Path

import ase.units
import ase.vibrations
import numpy as np
from numpy.typing import NDArray
from typing_extensions import Any, deprecated

from strainjedi.io.json_jedi import jsonable
from strainjedi import bmatrix, constants, reporting, rics, utils
from strainjedi.visualization import ColorMapper, MatplotlibVisualizer, VMDVisualizer


[docs] @jsonable("jedi") class Jedi: def __init__( self, atoms0: ase.atoms.Atoms, atomsF: ase.atoms.Atoms, modes: ase.vibrations.VibrationsData, epot: NDArray | None = None, ): """ atoms0: class Atoms object of relaxed structure with calculated energy. atomsF: class Atoms object of strained structure with calculated energy. modes: class ase.vibrations.VibrationsData object with hessian of relaxed structure. epot: np.array or None Vector containing (f - i) endiff., final, initial energy or None. Default: None. """ # validate the Hessian's atom order (must match atoms0); if not, permute Hessian to match. hessian, ok = utils.validate_hessian(modes, atoms0) if not ok: warnings.warn( "Atoms in ase.vibrations.VibrationsData object were not fitting atoms0. " "I have reordered your Hessian to match, but you may wish to check it." ) # Internal state (name-mangled attributes only) self.__H = hessian / (ase.units.Hartree / ase.units.Bohr**2) self.__atoms0 = atoms0 # ref state self.__atomsF = atomsF # strained state self.__covf = constants.COVALENCY_FACTOR self.__vdwf = constants.VAN_DER_WAALS_FACTOR self.__indices = np.arange(0, len(self.__atoms0)) self.__custom_bonds = None # list of custom added bonds self.__rim_list = rics.intersect( rics.calculate(self.__atoms0, self.__indices, self.__custom_bonds), rics.calculate(self.__atomsF, self.__indices, self.__custom_bonds), ) self.__B = bmatrix.calculate(self.__atoms0, self.__rim_list) self.__q0, self.__qF, self.__delta_q = rics.subtract(self.__atoms0, self.__atomsF, self.__rim_list) self.__energies = epot # optional energies of the geometries (legacy) self.__deltaE = self.get_deltaE() # energy difference between geometries self.__proc_E_RIMs = None # list of percentual energy stored in single RIMs self.__part_rim_list = None # rim list for election of atoms (legacy/unused) self.__E_RIMs = None # list of energies stored in the rims self.__E_RIMs_total = None # sum of E_rims self.__proc_geom_RIMs = None self.__visualization_data = None # last visualization dataset @property def H(self): return self.__H @property def atoms0(self): return self.__atoms0 @property def atomsF(self): return self.__atomsF @property def rics0(self): return rics.calculate(self.__atoms0, self.__indices, self.__custom_bonds) @property def ricsF(self): return rics.calculate(self.__atomsF, self.__indices, self.__custom_bonds) @property def covf(self): return self.__covf @property def vdwf(self): return self.__vdwf @property def indices(self): return self.__indices @property def custom_bonds(self): return self.__custom_bonds @property def rim_list(self): return self.__rim_list @property def B(self): return self.__B @property def q0(self): return self.__q0 @property def qF(self): return self.__qF @property def delta_q(self): return self.__delta_q @property def energies(self): return self.__energies @property def deltaE(self): return self.__deltaE @property def proc_E_RIMs(self): return self.__proc_E_RIMs @property def part_rim_list(self): return self.__part_rim_list @property def E_RIMs(self): return self.__E_RIMs @property def E_RIMs_total(self): return self.__E_RIMs_total @property def proc_geom_RIMs(self): return self.__proc_geom_RIMs @property def visualization_data(self): return self.__visualization_data
[docs] def todict(self) -> dict[str, Any]: """Make Jedi state savable as JSON with .write()""" return { "atoms0": self.__atoms0, "atomsF": self.__atomsF, "energies": self.__energies, "hessian": self.__H, "bmatrix": self.__B, "delta_q": self.__delta_q, "rim_list": self.__rim_list, "custom_bonds": self.__custom_bonds, "indices": self.__indices, "E_RIMs": self.__E_RIMs, "proc_E_RIMs": self.__proc_E_RIMs, "E_RIMs_total": self.__E_RIMs_total, "deltaE": self.__deltaE, "proc_geom_RIMs": self.__proc_geom_RIMs, }
[docs] @classmethod def fromdict(cls, data: dict[str, Any]) -> "Jedi": """ Reconstruct a Jedi object from a dictionary. Raises ValueError if required fields are missing or have incorrect types. Make Jedi state readable from JSON with Jedi.read() """ atoms0 = data["atoms0"] atomsF = data["atomsF"] # Try to reconstruct ase.vibrations.VibrationsData if possible if "modes" in data and isinstance(data["modes"], ase.vibrations.VibrationsData): modes = data["modes"] elif "hessian" in data: hessian = data["hessian"] indices = data.get("indices", None) n_atoms = len(atoms0) if hessian.shape == (3 * n_atoms, 3 * n_atoms): modes = ase.vibrations.VibrationsData.from_2d(atoms0, data["hessian"]) elif indices is not None: modes = ase.vibrations.VibrationsData.from_2d(atoms0, data["hessian"], indices) else: raise ValueError("Hessian has wrong shape.") else: raise ValueError("No valid vibration data ('modes' or 'hessian') found in the dictionary!") epot = data.get("energies", None) cl = cls(atoms0, atomsF, modes, epot=epot) # Fill additional attributes if present for attr, key in [ ("_Jedi__energies", "energies"), ("_Jedi__H", "hessian"), ("_Jedi__B", "bmatrix"), ("_Jedi__delta_q", "delta_q"), ("_Jedi__rim_list", "rim_list"), ("_Jedi__custom_bonds", "custom_bonds"), ("_Jedi__indices", "indices"), ("_Jedi__E_RIMs", "E_RIMs"), ("_Jedi__proc_E_RIMs", "proc_E_RIMs"), ("_Jedi__E_RIMs_total", "E_RIMs_total"), ("_Jedi__deltaE", "deltaE"), ("_Jedi__proc_geom_RIMs", "proc_geom_RIMs"), ]: if key in data and data[key] is not None: setattr(cl, attr, data[key]) return cl
[docs] def get_deltaE(self) -> float: """ Returns the difference in potential energies of self.atoms0 and self.atomsF. """ e0 = self.__atoms0.get_potential_energy() # [eV] eF = self.__atomsF.get_potential_energy() # [eV] return (eF - e0) / ase.units.Hartree
[docs] def run(self, indices=None, ase_units=False, printout: bool = True): """Runs the analysis. Calls all necessary functions to get the needed values. Args: indices: list of indices of a substructure if desired ase_units: boolean flag to get eV for energies, Å for lengths and degree for angles, otherwise it is kcal/mol, Bohr and radians Returns: Indices, strain, energy in every RIM """ # get necessary data if len(self.__atoms0) != self.__H.shape[0] / 3: raise ValueError( "Hessian has not the fitting shape, possibly a partial hessian. Please try partial_analysis" ) ( self.__proc_E_RIMs, self.__E_RIMs, self.__E_RIMs_total, self.__proc_geom_RIMs, self.__delta_q, ) = jedi_analysis( self.__atoms0, self.__rim_list, self.__B, self.__H, self.__delta_q, self.__deltaE, use_ase_units=ase_units, ) if indices: # get only rims of interest self.post_process(indices) self.__E_RIMs_total = float(np.sum(self.__E_RIMs)) self.__proc_geom_RIMs = 100 * (float(np.sum(self.__E_RIMs)) - self.__deltaE) / self.__deltaE if printout: reporting.jedi_printout( self.__atoms0, self.__rim_list, self.__delta_q, self.__deltaE, self.__E_RIMs_total, self.__proc_geom_RIMs, self.__proc_E_RIMs, self.__E_RIMs, ase_units=ase_units, )
[docs] def visualize( self, visualizer="mpl", colormap="green_red", output_dir: Path | str = "visualization", single_mode: str | None = None, man_strain: float | None = None, show: bool = False, show_indices: bool = False, box: bool = False, split_bonds: bool = True, ase_units: bool = False, ): """ Args: visualizer: ('mpl' or 'vmd') Defines visualizer used for visualization. colormap: (str or matplotlib Colormap object) Color scheme for strain energy mapping. Built-in options are 'green_red', 'cyan_red', 'magma', or any matplotlib colormap name (e.g. 'viridis', 'inferno'). Alternatively, a custom matplotlib Colormap object can be passed directly. default: 'green_red' output_dir: (str or Path) Directory to save the visualization output files. default: 'visualization' single_mode: (str or None) Restrict visualization to a single mode. Options are 'bl' (bond lengths), 'ba' (bond angles), 'da' (dihedral angles), or 'all' (combined). If None, all modes are generated. default: None man_strain: (float or None) Manual reference value for the maximum of the color scale. If None, the maximum strain energy in the data is used. default: None show: (bool) Display the plot interactively. Only works with the Matplotlib visualizer. default: False show_indices: (bool) Display atom indices. Only works with the Matplotlib visualizer. split_bonds: (bool) Display PBC bonds as half-bonds at each side of the unit cell. box: (bool) Draw the unit cell box. Only applies to periodic structures. default: False ase_units: (bool) Whether to use Angstrom and eV instead of kcal/mol and Bohr. default: False """ if self.__proc_E_RIMs is None or len(self.__proc_E_RIMs) == 0: raise ValueError("Analysis has not been run. Jedi.run() must be called before Jedi.visualize()") if show and visualizer != "mpl": warnings.warn("'show=True' only works for the Matplotlib Visualizer and will be ignored.", UserWarning) if show_indices and visualizer != "mpl": warnings.warn( "'show_indices=True' only works for the Matplotlib Visualizer and will be ignored.", UserWarning, ) if split_bonds and visualizer != "mpl": warnings.warn( "'split_bonds=True' only works for the Matplotlib Visualizer. " "Set 'split_bonds=False' to be sure, all bonds are visualized.", UserWarning, ) energy_unit = "eV" if ase_units else "kcal/mol" valid_modes = ["bl", "ba", "da", "all"] if not single_mode: mode_list = valid_modes elif single_mode in valid_modes: mode_list = [single_mode] else: raise ValueError(f"Unknown mode '{single_mode}'. single_mode must be in: {valid_modes} or None") mapper = ColorMapper(self, ase_units) self.__visualization_data = mapper.get_visualization_data(mode_list, colormap, man_strain, split_bonds) if visualizer == "mpl": vis = MatplotlibVisualizer(self.__visualization_data, mapper, output_dir, energy_unit) vis.run(show, show_indices, box) elif visualizer == "vmd": vis = VMDVisualizer(self.__visualization_data, mapper, output_dir, energy_unit) vis.write_inputs(box) else: raise ValueError("Unknown visualizer. Visualizer must be 'mpl' or 'vmd'.")
[docs] @deprecated("Use Jedi.visualize(visualizer='vmd') instead.") def vmd_gen( self, _des_colors: dict | None = None, _box: bool = False, man_strain: float | None = None, modus: str | None = None, _colorbar: bool = True, label: Path | str = "vmd", incl_coloring: str | None = None, ): """ .. deprecated:: 1.1.0 Use :meth:`Jedi.visualize` with ``visualizer="vmd"`` instead. Args: des_colors: (dict) key: order number, value: [R,G,B] box: boolean True: draw box False: ignore box man_strain: float reference value for the strain energy used in the color scale default: 'None' modus: str defines where to use the man_strain default: 'None' colorbar: boolean draw colorbar or not label: string or pathlib.Path name of folder for the created files incl_coloring: str 2 inclusive coloring options, otherwise green to red gradient "cyan": cyan to red gradient "magma": matplotlib magma gradient default: 'None' """ if not incl_coloring: incl_coloring = "green_red" self.visualize( visualizer="vmd", colormap=incl_coloring, output_dir=label, single_mode=modus, man_strain=man_strain, )
[docs] def partial_analysis(self, indices, ase_units=False): """ Analyse a substructure with given indices. Args: indices: list of indices of atoms in desired substructure """ # for calculation with partial hessian if 3 * len(indices) < len(self.__H): raise ValueError("to little indices for the given hessian") has_custom_bonds = False if self.__custom_bonds is not None: old_custom_bonds = self.__custom_bonds.copy() has_custom_bonds = True self.__custom_bonds = self.__custom_bonds[np.isin(self.__custom_bonds, indices).all(axis=1)] rim_list = rics.calculate(self.__atoms0, self.__indices, self.__custom_bonds) if len(rim_list) == 0: raise ValueError("Chosen indexlist has no rims") self.__B = bmatrix.calculate(self.__atoms0, rim_list, indices=self.__indices) # set B matrix values of not considered atoms to 0 self.__B = bmatrix.restrict(self.__B, indices) self.__q0, self.__qF, self.__delta_q = rics.subtract(self.__atoms0, self.__atomsF, rim_list) ( self.__proc_E_RIMs, self.__E_RIMs, self.__E_RIMs_total, self.__proc_geom_RIMs, self.__delta_q, ) = jedi_analysis( self.__atomsF, rim_list, self.__B, self.__H, self.__delta_q, self.__deltaE, use_ase_units=ase_units, ) # get values of rims inside the substructure self.post_process(indices) self.__E_RIMs_total = float(np.sum(self.__E_RIMs)) self.__proc_geom_RIMs = 100 * (float(np.sum(self.__E_RIMs)) - self.__deltaE) / self.__deltaE reporting.jedi_printout( self.__atoms0, self.__rim_list, self.__delta_q, self.__deltaE, self.__E_RIMs_total, self.__proc_geom_RIMs, self.__proc_E_RIMs, self.__E_RIMs, ase_units=ase_units, ) if has_custom_bonds: self.__custom_bonds = old_custom_bonds # restore the user input
[docs] def post_process(self, indices): """ Get only the values of RICs inside a defined substructure. Args: indices: list of indices of atoms in desired substructure Returns: Values for analyzed RIMs in the defined substructure """ # get rims with only the considered atoms self.__indices = indices rim_list = self.__rim_list cbonds_flag = False if self.__custom_bonds is not None: custom_bonds = self.__custom_bonds.copy() cbonds_flag = True self.__custom_bonds = self.__custom_bonds[np.isin(self.__custom_bonds, indices).all(axis=1)] rim_p = rics.intersect( rics.calculate(self.__atoms0, indices, self.__custom_bonds), rics.calculate(self.__atomsF, indices, self.__custom_bonds), ) ind = [] rim_list_c = [] # preparing for stacking rim_list to be able to use np.unique for i in range(4): # rim_list is always of length 4 if rim_list[i].shape == (0,): rim_list_c.append([]) else: if rim_p[i].shape[0] > 0: rim_list_c.append(np.vstack((rim_list[i], rim_p[i]))) else: rim_list_c.append(rim_list[i]) _, z = np.unique(rim_list_c[-1], return_counts=True, axis=0) ind.append(np.where(z > 1)[0]) # get indices where ric is in both sets for i in range(4): ind[i] = ind[i] + np.sum([p.shape[0] for p in rim_list[0:i]]) # get correct indices for the stacked array ind = np.hstack(ind).astype(int) # Keep rim_list aligned with filtered E_RIMs/delta_q. # ind is a "flat" index over the concatenation of rim_list[0], rim_list[1], rim_list[2], rim_list[3] counts = [0 if getattr(rim_list[i], "size", 0) == 0 else rim_list[i].shape[0] for i in range(4)] offsets = np.cumsum([0] + counts) # length 5 new_rim_list = [] for i in range(4): if counts[i] == 0: new_rim_list.append(np.array([])) continue mask = (ind >= offsets[i]) & (ind < offsets[i + 1]) local_ind = ind[mask] - offsets[i] new_rim_list.append(rim_list[i][local_ind]) # Side-effect: keep internal rim_list aligned to filtered arrays self.__rim_list = new_rim_list self.__E_RIMs = np.array(self.__E_RIMs)[ind] self.__delta_q = self.__delta_q[ind] E_RIMs_total = float(np.sum(self.__E_RIMs)) self.__proc_E_RIMs = np.array(self.__E_RIMs) / E_RIMs_total * 100 if cbonds_flag: self.__custom_bonds = custom_bonds # restore the user input
[docs] def add_custom_bonds(self, bonds: NDArray) -> None: """Add custom bonds for non-covalent interactions after creating the object. Args: bonds: 1D or 2Darray with atom indices, [[i,j]...] """ bonds = np.atleast_2d(bonds) # sort bonds array bonds = np.sort(bonds, axis=1) idx = np.lexsort((bonds[:, 1], bonds[:, 0])) bonds = bonds[idx] self.__custom_bonds = bonds # recalculate rim_list, B and delta_q self.__rim_list = rics.intersect( rics.calculate(self.__atoms0, self.__indices, self.__custom_bonds), rics.calculate(self.__atomsF, self.__indices, self.__custom_bonds), ) self.__B = bmatrix.calculate(self.__atoms0, self.__rim_list) self.__q0, self.__qF, self.__delta_q = rics.subtract(self.__atoms0, self.__atomsF, self.__rim_list)
[docs] def set_bond_params(self, covf=constants.COVALENCY_FACTOR, vdwf=constants.VAN_DER_WAALS_FACTOR): """ Args: covf: float factor for covalent radii to determine covalent bonds vdwf: float factor for vdw radii to get the upper limit of the custom bond lengths """ self.__covf = covf self.__vdwf = vdwf
def jedi_analysis( atoms: ase.atoms.Atoms, rim_list: list, B: np.ndarray, H_cart: np.ndarray, delta_q: np.ndarray, deltaE: float, printout: bool | None = None, use_ase_units: bool = False, ): """ Analysis of strain energy stored in redundant internal coordinates. Parameters ---------- atoms: class An ASE Atoms object to determine the atomic species of the indices. rim_list: list A list of 4 numpy 2D arrays the first array containing bonds, second custom bonds, third bond angles, fourth dihedrals. B: np array B matrix. H_cart: np array Hessian in cartesian coordinates. delta_q: np array Array of deformations along the RICs. self._deltaE: float Energy difference between the geometries. printout: bool Flag to print the output. ase_units: bool Flag to get eV for energies å fo lengths and degree for angles otherwise it is kcal/mol, Bohr and radians. Returns: Analysis of RIMs. """ # Matrix Calculations via bmatrix module H_q = bmatrix.hessian_to_ric(B, H_cart) # Energy calculations E_RIMs_total = 0.5 * delta_q.T.dot(H_q).dot(delta_q) if B.ndim == 1: E_RIMs = np.array([0.5 * delta_q[0] * H_q * delta_q[0]]) else: E_RIMs = np.sum(0.5 * (delta_q * H_q).T * delta_q, axis=1) proc_E_RIMs = 100 * E_RIMs / E_RIMs_total proc_geom_RIMs = 100 * (E_RIMs_total - deltaE) / deltaE if printout: reporting.jedi_printout( atoms, rim_list, delta_q, deltaE, E_RIMs_total, proc_geom_RIMs, proc_E_RIMs, E_RIMs, ase_units=use_ase_units, ) return proc_E_RIMs, E_RIMs, E_RIMs_total, proc_geom_RIMs, delta_q @deprecated("Use strainjedi.utils.get_hbonds instead.") def get_hbonds(mol, covf=constants.COVALENCY_FACTOR, vdwf=constants.VAN_DER_WAALS_FACTOR): """ .. deprecated 1.1.0 Use :func:`strainjedi.utils.get_hbonds` instead. Get all hbonds in a structure. Hbonds are defined as the HY bond inside X-H···Y where X and Y can be O, N, F and the angle XHY is larger than 90° and the distance between HY is shorter than 0.9 times the sum of the vdw radii of H and Y. Parameters ---------- mol: class Structure of which the hbonds should be determined. Returns: 2D array of indices. """ from strainjedi.utils import get_hbonds return get_hbonds(mol, covf=covf, vdwf=vdwf)