pyef.normal_mode

Normal mode electric field projection utilities.

Provides Kabsch alignment and projection of per-atom electric field vectors onto a normal mode eigenvector.

The projected field is:

F_mode = Σ_i F_i · (R @ L_i)

where:

F_i : electric field vector at solute atom i (V/Å, shape (3,)) L_i : QM normal mode displacement for atom i (shape (3,)) R : 3×3 Kabsch rotation mapping the QM reference frame to the

current molecular frame

This is the standard Stark-tuning projection used in vibrational Stark effect spectroscopy.

Module Contents

Functions

get_heavy_atom_indices(atomic_numbers)

Return 0-based indices of non-hydrogen atoms.

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)[source]

Return 0-based indices of non-hydrogen atoms.

kabsch_rotation(P, Q)[source]

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)[source]

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)[source]

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)[source]

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/Å