Matrix Elements¶

Bases: object

Dataclass to store matrix elements

h_pq_kin: ndarray | None = None¶: Kinetic energy part of the one-electron matrix elements

h_pq_pp: ndarray | None = None¶: Pseudopotential part of the one-electron matrix elements

h_pq_core: ndarray | None = None¶: Effective single-particle potential from the frozen core approximation part of the one-electron matrix elements

h_pqrs: ndarray | None = None¶: Two-electron matrix elements (electron-electron interaction) defined as

\[h_{pqrs} = \iint \psi^*_p(r_1)\,\psi^*_q(r_2)\,\psi_r(r_2)\,\psi_s(r_1)\, \frac{1}{\lvert r_1 - r_2 \rvert}\,dr_1\,dr_2\]

h_pq_ewald: ndarray | None = None¶: Nuclear-nuclear interaction energy multiplied with the overlap matrix as one-electron matrix elements

energy_frozen_core: float | None = None¶: Frozen core energy

energy_ewald: float | None = None¶: Nuclear-nuclear interaction energy

energy_e_self: float | None = None¶: Electron self-energy

transform_matrix: ndarray | None = None¶: Transformation matrix to transform matrix elements into a different basis. Used for Wannier transformations

property h_pq: ndarray¶

h_pq = h_pq_kin + h_pq_pp + h_pq_core. h_pq is transformed with transform_matrix if transform_matrix is not None. Transformation is done with dopyqo.transform_one_body_matrix function.

Type:: One-electron matrix elements

dopyqo.iTj(p: ndarray, c_ip: ndarray) → ndarray[source]¶

Calculate kinetic energy matrix in Hartree units in the Kohn-Sham basis

Parameters:

p (np.ndarray) – Array of momentum vectors, shape (#waves, 3)
c_ip (np.ndarray) – Array of coefficients describing the Kohn-Sham orbitals in the plane wave basis, shape (#bands, #waves)

Returns:

Kinetic energy matrix

Return type:

np.ndarray

dopyqo.nuclear_repulsion_energy_ewald(atom_positions: ndarray, atomic_numbers: ndarray, lattice_vectors: ndarray, lattice_vectors_reciprocal: ndarray, cell_volume: float, gcut: float, sigma: float | None = None, rust_impl: bool = True) → ndarray[source]¶

Calculate the nuclear repulsion energy \(E\) between all nuclei in a periodic lattice, i.e.,

\[E = \frac{1}{2} \sum_I \sum_J \sum_{T}{}' \frac{Z_I Z_J}{\lvert R_I - R_J - T \rvert}\]

where \('\) denotes that the term \(T=0, I=J\) is omitted, \(Z_I\) are the charges of the nuclei and \(R_I\) their positions, and \(T\) are all possible lattice translation vectors. This is equivalent to

\[E = \frac{1}{2} \sum_I Z_I \Phi_I(R_I)\]

where \(\Phi_I(r)\) is the electrostatic potential generated by all periodic nuclei EXCEPT the nucleus \(Z_I\) at position \(R_I\) (its periodic images are still included). To calculate \(\Phi_I(r)\) we define charge densities and solve the Poisson equation in real- and reciprocal-space. The nuclei \(Z_I\) are modelled by delta distributions at positions \(R_I + T\). Additionally, Ewald’s method is used, i.e., we add and subtract Gaussian charge distributions at all \(R_I + T\), and subtract a homogeneous background charge simulating the electron charges. A short-ranged term including all delta distributions minus all Gaussian charges (except the term where \(T=0\) and \(I=J\)) can be calculated in real-space. A long-ranged term including all Gaussian charges at \(R_I + T\) minus the constant background charge can be calculated in reciprocal-space. The term describing the subtraction of the Gaussian charge at \(R_I\) is calculated in real-space and is the so-called self-energy term. The \(G \to 0\) limit in the reciprocal space calculation is also calculated separately and is called the charged-system term. The value \(\sigma\) determining the splitting between the real-space and reciprocal-space term is calculated as done in Quantum ESPRESSO (see PW/src/ewald.f90: https://github.com/QEF/q-e/blob/de3035747f5d8f2ec9a67869827341ebb43f5b12/PW/src/ewald.f90)

We calculate \(E = E_S + E_L + E_{\text{self}} + E_{\text{charged}}\) with:

Short-ranged term calculated in real-space:

\[E_S = \frac{1}{2} \sum_{T}{}' \sum_I \sum_J \frac{Z_I Z_J}{\lvert R_I - R_J - T \rvert} \operatorname{erfc}\!\left(\lvert R_I - R_J - T \rvert \sqrt{\sigma}\right)\]

where \('\) denotes that the term \(T=0, I=J\) is omitted.

Long-ranged term calculated in reciprocal-space:

\[E_L = \frac{2\pi}{V} \sum_{k \neq 0} \sum_I \sum_J \frac{Z_I Z_J}{\lvert k \rvert^2} e^{i k \cdot (R_I - R_J)} e^{-\lvert k \rvert^2 / (4\sigma)}\]

Self-energy from subtracting the Gaussian charge at position \(R_I\) (in real-space):

\[E_{\text{self}} = -\sum_I Z_I^2 \sqrt{\frac{\sigma}{\pi}}\]

Charged-system term from the \(G=0\) term in the reciprocal-space sum:

\[E_{\text{charged}} = -\frac{\pi}{2 V \sigma} \left(\sum_I Z_I\right)^2\]

Notes: - When pseudopotentials are used, \(Z_I\) are the valence charges, i.e. the charge of the

nucleus not modelled by the pseudopotential.

This function should calculate the same Ewald energy as Quantum ESPRESSO, called “ewald contribution” in the pw.x output file and “ewald” in the total_energy section in the output-xml.
Equivalent to the Ewald calculation in PySCF via pyscf.pbc.gto.cell.ewald.

References: - Kittel, Appendix B: http://metal.elte.hu/~groma/Anyagtudomany/kittel.pdf - PhysRevB.53.1814, equation (16): https://journals.aps.org/prb/pdf/10.1103/PhysRevB.53.1814 - https://courses.physics.illinois.edu/phys466/sp2013/projects/2003/Team2/ewald_text.htm - S. W. de Leeuw et al. Proc. R. Soc. Lond. A 1980 373, 27-56, doi: 10.1098/rspa.1980.0135, equation (1.5) - M. P. Allen and D. J. Tildesley “Computer Simulation of Solids”, equation (5.20) - http://micro.stanford.edu/mediawiki/images/4/46/Ewald_notes.pdf - https://homepages.uc.edu/~becktl/tlb_ewald.pdf - Quantum ESPRESSO source code in q-e/PW/src/ewald.f90

Parameters:

atom_positions (np.ndarray) – Array of the coordinates \(R_I\) of every atom. Shape (#atoms, 3)
atomic_numbers (np.ndarray) – 1D array of atomic number of each atom. Shape (#atoms,)
lattice_vectors (np.ndarray) – 2D array of lattice vectors. Each row is one lattice vector. Shape (3, 3)
lattice_vectors_reciprocal (np.ndarray) – 2D array of reciprocal lattice vectors. Each row is one reciprocal lattice vector. Shape (3, 3)
cell_volume (float) – Cell volume of the computational real space cell.
gcut (float) – Cutoff of the reciprocal space sum in \(E_L\), i.e., \(\lvert k \rvert < G_{\text{cut}}\). In Quantum ESPRESSO the G-cutoff of the density is used.
sigma (float | None, optional) –
Value for \(\sigma\) in the Ewald summation to split real- and reciprocal-space sums. If None, computed to satisfy

\[\sum_I 2 Z_I \sqrt{\frac{\sigma}{\pi}} \operatorname{erfc}\!\left( \sqrt{\frac{(4 G_{\text{cut}})^2}{4\sigma}} \right) \leq 10^{-7}\]

Defaults to None.

Raises:

RuntimeError – If \(\sigma\) could not be calculated.

Returns:

Ewald energy

Return type:

float

dopyqo.check_symmetry_one_body_matrix(matrix: ndarray)[source]¶

Check if given matrix satisfies the symmetries of one-body matrices (hermitian)

Parameters:: matrix (np.ndarray) – Matrix to check symmetries of
Returns:: Bool specifying of symmetry is satisfied
Return type:: bool

dopyqo.check_symmetry_two_body_matrix(matrix: ndarray)[source]¶

Check if given matrix satisfies the symmetries of ERIs

Parameters:: matrix (np.ndarray) – Matrix to check symmetries of
Returns:: Bools specifying if following symmetries are satisfied: swap symmetry, hermitian symmetry, hermitian+swap symmetry
Return type:: tuple[bool, bool, bool]

dopyqo.calc_pps(p: ndarray, c_ip: ndarray, cell_volume: float, atom_positions: ndarray, atomic_numbers: ndarray, pseudopots: list[Pseudopot], save_filename: str | None = None, rust_impl: bool = True, n_threads: int = 1) → ndarray[source]¶

Calculate sum of all pseudopotentials in Hartree atomic units. Calls v_nl and v_loc after checking arguments.

Parameters:

p (np.ndarray) – Array of momentum vectors. Shape (#waves, 3)
c_ip (np.ndarray) – Array of coefficients describing the Kohn-Sham orbitals in the plane wave basis. Shape (#bands, #waves)
atom_positions (np.ndarray) – 2D array of positions of each atom. Shape (#atoms, 3)
atomic_numbers (np.ndarray) – 1D array of atomic number of each atom. Shape (#atoms,)
cell_volume (float) – Cell volume of the computationen real space cell.
pseudopot (list[Pseudopot]) – Pseudopotential objects for all atom types

Returns:

Nuclear interaction matrix

Return type:

np.ndarray