pyef

A package for calculating electric fields and electrostatics in molecular systems.

Subpackages

• pyef.resources

Submodules

• pyef.analysis
• pyef.cli
• pyef.constants
• pyef.fchk_interface
• pyef.geometry
• pyef.manage
• pyef.multiwfn_interface
• pyef.normal_mode
• pyef.run
• pyef.utility
• pyef.validation

Package Contents

Functions

parse_geometry(fchk_path)	Parse reference geometry from fchk (Gaussian or Q-Chem).
parse_normal_modes(fchk_path)	Parse normal mode frequencies and eigenvectors from a Gaussian fchk.
get_mode(fchk_path, mode_index[, mode_vectors])	Retrieve a single normal mode vector.
detect_format(fchk_path)	Return 'gaussian' if Vib-Modes section present, else 'qchem'.
kabsch_rotation(P, Q)	Find the rotation matrix R that best superposes P onto Q (both centred).
align_to_reference(current_coords, ref_coords[, ...])	Compute the Kabsch rotation R that maps the QM reference geometry
project_efield_onto_mode(per_atom_efields, ...)	Project per-atom electric field vectors onto a (rotated) normal mode.
per_atom_efield_from_charges(solute_coords, ...[, box])	Compute the Coulomb electric field at each solute atom from environment.
get_heavy_atom_indices(atomic_numbers)	Return 0-based indices of non-hydrogen atoms.

parse_geometry(fchk_path)

Parse reference geometry from fchk (Gaussian or Q-Chem).

Returns:

• atomic_numbers (np.ndarray shape (n_atoms,) int)

• coords (np.ndarray shape (n_atoms, 3) float, Angstroms)

parse_normal_modes(fchk_path)

Parse normal mode frequencies and eigenvectors from a Gaussian fchk.

Returns:

• frequencies (np.ndarray shape (n_modes,) cm⁻¹)

• modes (np.ndarray shape (n_modes, n_atoms, 3)) – Each row is one normalised eigenvector in Cartesian space.

Raises:

ValueError if the file is Q-Chem format (no Vib-Modes section). –

get_mode(fchk_path, mode_index, mode_vectors=None)

Retrieve a single normal mode vector.

Parameters:

• fchk_path (str path to .fchk file) –

• mode_index (int 1-based mode number (as printed by Q-Chem / Gaussian)) –

• mode_vectors (np.ndarray or None) – If provided, shape (n_modes, n_atoms, 3) or (n_atoms, 3). Required for Q-Chem fchk; ignored for Gaussian fchk.

Returns:

• freq (float or None frequency in cm⁻¹ (None for Q-Chem))

• vector (np.ndarray shape (n_atoms, 3) normalised displacement)

detect_format(fchk_path)

Return ‘gaussian’ if Vib-Modes section present, else ‘qchem’.

kabsch_rotation(P, Q)

Find the rotation matrix R that best superposes P onto Q (both centred).

Parameters:

• P (np.ndarray shape (N, 3) — must already be mean-centred) –

• Q (np.ndarray shape (N, 3) — must already be mean-centred) –

Returns:

R – Rotation such that Q_approx = P @ R.T (i.e. R @ p_i ≈ q_i).

Return type:

np.ndarray shape (3, 3)

align_to_reference(current_coords, ref_coords, align_indices=None)

Compute the Kabsch rotation R that maps the QM reference geometry onto the current (MD/QM cluster) geometry.

Parameters:

• current_coords (np.ndarray shape (n_atoms, 3) current frame coords) –

• ref_coords (np.ndarray shape (n_atoms, 3) QM reference coords (Å)) –

• align_indices (array-like or None) – Atom indices used for the fit (default: all atoms).

Returns:

R – Rotation mapping QM frame → current frame.

Return type:

np.ndarray shape (3, 3)

project_efield_onto_mode(per_atom_efields, mode_vector, rotation)

Project per-atom electric field vectors onto a (rotated) normal mode.

Parameters:

• per_atom_efields (np.ndarray shape (n_solute, 3)) – Electric field at each solute atom from the environment (V/Å).

• mode_vector (np.ndarray shape (n_solute, 3)) – Normal mode displacement eigenvector in the QM reference frame.

• rotation (np.ndarray shape (3, 3)) – Kabsch rotation R mapping QM reference frame → current frame.

Returns:

F_mode

Return type:

float projected field in V/Å

per_atom_efield_from_charges(solute_coords, env_coords, env_charges, box=None)

Compute the Coulomb electric field at each solute atom from environment.

Parameters:

• solute_coords (np.ndarray shape (n_solute, 3) Å) –

• env_coords (np.ndarray shape (n_env, 3) Å) –

• env_charges (np.ndarray shape (n_env,) elementary charge units) –

• box (np.ndarray shape (3,) or None) – Periodic box lengths in Å. None → no PBC.

Returns:

efields

Return type:

np.ndarray shape (n_solute, 3) V/Å

get_heavy_atom_indices(atomic_numbers)

Return 0-based indices of non-hydrogen atoms.