PAOFLOW.hamiltonian.position_dipoles#

Position dipoles of the PAO basis and the velocity term \(i[H, \mathbf d](\mathbf k)\).

PAOFLOW’s velocity operator in the orthonormal PAO Bloch basis,

\[\mathbf v(\mathbf k) = \partial_{\mathbf k} H(\mathbf k) + i[H(\mathbf k), \boldsymbol\tau],\]

takes the position operator diagonal on the orbital centres \(\boldsymbol\tau_i\) (band_velocities(), the Dnm term of do_gradient()). For orthonormal localised orbitals \(\omega_i\) the exact tight-binding velocity has a third term,

\[\mathbf v(\mathbf k) = \partial_{\mathbf k} H + i[H, \boldsymbol\tau] + i[H, \mathbf d(\mathbf k)], \qquad \mathbf d_{ij}(\mathbf R) = \langle \omega_i(\mathbf r - \boldsymbol\tau_i)\,|\, \mathbf r - \mathbf R - \boldsymbol\tau_j\,|\, \omega_j(\mathbf r - \mathbf R - \boldsymbol\tau_j)\rangle,\]

whose band-basis form \(i(\varepsilon_n - \varepsilon_m)\,d_{nm}\) is the analogue of EPW’s Berry-connection term in vme = 'wannier'. Its largest part is the on-site \(\Delta l = \pm 1\) dipole (\(\langle s|\mathbf r|p\rangle\), \(\langle p|\mathbf r|d\rangle\)) between orbitals of the same atom. It vanishes on the diagonal and inside degenerate blocks, so group velocities (transport, adaptive smearing) are unchanged.

PAOFLOW’s basis functions are the atomic orbitals \(\varphi\) symmetrically (Löwdin) orthogonalised, \(\omega = \varphi\,S^{-1/2}\). With the two-centre tables of the atomic orbitals, the overlap \(S_{ij}(\mathbf R) = \langle\varphi_i|\varphi_j(\mathbf R)\rangle\) and the intrinsic dipole \(X_{ij}(\mathbf R) = \langle\varphi_i(\mathbf r - \boldsymbol\tau_i)| \mathbf r - \boldsymbol\tau_i|\varphi_j(\mathbf r - \mathbf R - \boldsymbol\tau_j)\rangle\) (origin on the bra site), the Bloch-space dipole of the orthonormal basis is

\[\mathbf d(\mathbf k) = S^{-1/2} X S^{-1/2} + S^{-1/2}\boldsymbol\tau S^{1/2} - \boldsymbol\tau + i\,S^{-1/2}\,\partial_{\mathbf k} S^{1/2},\]

all matrices at \(\mathbf k\) (\(S(\mathbf k) = \sum_{\mathbf R} e^{i\mathbf k\cdot\mathbf R} S(\mathbf R)\), likewise \(X\)), with \(\boldsymbol\tau\) the diagonal matrix of orbital centres. The last three terms come from the cell-position operator, which does not commute with \(S^{\pm 1/2}\) (\([\hat{\mathbf R}, M](\mathbf k) = i\,\partial_{\mathbf k} M(\mathbf k)\)), and from the bra-site origin of \(X\); \(\mathbf d(\mathbf k)\) is Hermitian. level='intra-atomic' keeps the textbook approximation \(S \equiv 1\) with the on-site blocks of \(X\) only.

The real-space tables are built with the primitives of PAOFLOW.hamiltonian._two_center (the PAO radial function as bra, \(g(r) = r\,R(r)\) at \(l \pm 1\) for the dipole), vectorised over the orbitals of a site pair in PAOFLOW.hamiltonian.two_center_blocks.

Attributes#

Classes#

PAOPair

One (bra site, ket site, lattice translation) triple of the position tables.

PositionTables

Real-space overlap and intrinsic-dipole blocks of the atomic orbitals.

ProjectorAugmentation

PAW augmentation of the overlap and position matrices of the PAO Bloch basis.

Functions#

enumerate_pao_pairs(pao_catalog, a_vectors_cart, *[, ...])

Enumerate the (bra site, ket site, lattice translation) triples within the orbital cutoffs.

build_position_tables(pao_catalog, pairs, *[, q_max, ...])

Two-centre overlap and intrinsic-dipole blocks for every pair.

assemble_position_kspace(tables, k_points_cart)

Bloch sums of the overlap, its k-derivative and the intrinsic dipole.

assemble_overlap_kspace(tables, k_points_cart)

Bloch overlap \(S(\mathbf k) = \sum_{\Delta\mathbf R} e^{i\mathbf k\cdot\Delta\mathbf R} S(\Delta\mathbf R)\) alone.

on_site_dipoles(tables)

Intra-atomic dipole matrix \(\langle\varphi_i|\mathbf r - \boldsymbol\tau|\varphi_j\rangle\).

overlap_sqrt_and_derivative(overlap_k, overlap_gradient_k)

S^{1/2}, S^{-1/2} and \(\partial_{\mathbf k} S^{1/2}\) from the eigendecomposition.

lowdin_dipole_kspace(overlap_k, overlap_gradient_k, ...)

Position dipoles \(\mathbf d(\mathbf k)\) of the Löwdin-orthonormal PAO basis.

hermiticity_residual(dipole_k)

Largest |d - d^dagger| over k and Cartesian components (bohr).

dipole_velocity_term(hamiltonian_k, dipole_k)

The velocity term \(i[H(\mathbf k), \mathbf d(\mathbf k)]\) in the orbital basis.

tesseral_signs(pao_catalog)

Sign of every PAOFLOW orbital with respect to the orbitals of the tables.

partial_wave_dipole_radial(upf)

Radial dipole integrals of the PAW partial waves, \(\int (u_i u_j - \tilde u_i \tilde u_j)\, r\, dr\).

build_projector_augmentation(data_controller, ...[, ...])

The PAW augmentation of the PAO overlap and position matrices, or None without PAW.

augmentation_kspace(aug, k_points_cart, tau_orbitals)

PAW corrections to S(k), d_k S(k) and X(k) of assemble_position_kspace().

position_dipole_operator(data_controller, bg, alat, *)

Position dipoles of the PAO basis at arbitrary k, in PAOFLOW's orbital conventions.

position_dipoles_on_grid(data_controller, ...[, ...])

Position dipoles \(\mathbf d(\mathbf k)\) on PAOFLOW's k-grid, in the basis of dHksp.

inject_dipole_velocity_into_dHksp(dHksp, energies_k, ...)

Add the position-dipole velocity term to dHksp in place.

Module Contents#

PAOFLOW.hamiltonian.position_dipoles.DIPOLE_LEVELS = ('full', 'intra-atomic')[source]#
class PAOFLOW.hamiltonian.position_dipoles.PAOPair[source]#

One (bra site, ket site, lattice translation) triple of the position tables.

Variables:
  • bra_site (int) – Site of the bra orbitals (home cell).

  • ket_site (int) – Site of the ket orbitals, in the periodic image deltaR_lattice.

  • deltaR_lattice (tuple of int) – Integer lattice translation (n1, n2, n3) of the ket site.

  • deltaR_cart (ndarray, shape (3,)) – The same translation in Cartesian bohr; it carries the Bloch phase \(e^{i\mathbf k\cdot\Delta\mathbf R}\).

  • displacement (ndarray, shape (3,)) – \(\boldsymbol\tau_{\rm ket} + \Delta\mathbf R - \boldsymbol\tau_{\rm bra}\) (bohr).

  • distance (float) – Length of displacement (bohr).

bra_site: int[source]#
ket_site: int[source]#
deltaR_lattice: tuple[source]#
deltaR_cart: numpy.typing.NDArray[numpy.float64][source]#
displacement: numpy.typing.NDArray[numpy.float64][source]#
distance: float[source]#
class PAOFLOW.hamiltonian.position_dipoles.PositionTables[source]#

Real-space overlap and intrinsic-dipole blocks of the atomic orbitals.

Variables:
  • pairs (list of PAOPair) – Pairs of enumerate_pao_pairs().

  • overlap (list of ndarray) – overlap[p] has shape (n_bra, n_ket): \(S_{ij}(\Delta\mathbf R)\).

  • dipole (list of ndarray) – dipole[p] has shape (3, n_bra, n_ket): the intrinsic dipole \(X_{ij}(\Delta\mathbf R)\) with the origin on the bra site (bohr).

  • basis_offsets (list of int) – First global orbital index of every site.

  • orbitals_per_site (list of int) – Number of orbitals of every site.

  • tau_orbitals (ndarray, shape (nawf, 3)) – Centre of every orbital (Cartesian bohr).

  • nawf (int) – Number of PAO orbitals.

pairs: list[source]#
overlap: list[source]#
dipole: list[source]#
basis_offsets: list[source]#
orbitals_per_site: list[source]#
tau_orbitals: numpy.typing.NDArray[numpy.float64][source]#
nawf: int[source]#
PAOFLOW.hamiltonian.position_dipoles.enumerate_pao_pairs(pao_catalog, a_vectors_cart, *, extra_pad=0.0, pao_tol=0.0001)[source]#

Enumerate the (bra site, ket site, lattice translation) triples within the orbital cutoffs.

Parameters:
  • pao_catalog (PAOCatalog) – Loaded by load_pao_orbitals().

  • a_vectors_cart (ndarray, shape (3, 3)) – Cartesian lattice vectors (rows, bohr).

  • extra_pad (float, optional) – Padding added to every pair cutoff \(r_{\rm bra} + r_{\rm ket}\) (bohr).

  • pao_tol (float, optional) – Relative tail threshold of pao_cutoff_radius().

Returns:

Every ordered pair of sites and every image whose centres are closer than the pair cutoff, including the on-site pair (I, I, 0). The list is symmetric: with (I, J, dR) it also holds (J, I, -dR).

Return type:

list of PAOPair

Raises:

ValueError – If a_vectors_cart is not (3, 3).

PAOFLOW.hamiltonian.position_dipoles.build_position_tables(pao_catalog, pairs, *, q_max=20.0, n_q=600, include_dipole=True)[source]#

Two-centre overlap and intrinsic-dipole blocks for every pair.

Parameters:
  • pao_catalog (PAOCatalog) – Loaded by load_pao_orbitals().

  • pairs (list of PAOPair) – Output of enumerate_pao_pairs().

  • q_max (float, int, optional) – Reciprocal-space Simpson grid of the radial Bessel transforms (radial_bessel_transform()).

  • n_q (float, int, optional) – Reciprocal-space Simpson grid of the radial Bessel transforms (radial_bessel_transform()).

  • include_dipole (bool, optional) – False computes the overlap blocks only (the dipole blocks are zero): the input of the Löwdin transformation of the non-local velocity correction, at a third of the cost.

Return type:

PositionTables

Notes

For a pair with displacement \(\mathbf d = \boldsymbol\tau_j + \Delta\mathbf R - \boldsymbol\tau_i\) the blocks are

\[S_{ij} = \int \varphi_i(\mathbf r)\,\varphi_j(\mathbf r - \mathbf d)\,d^3r, \qquad X^\alpha_{ij} = \int \varphi_i(\mathbf r)\, r_\alpha\, \varphi_j(\mathbf r - \mathbf d)\,d^3r,\]

with the origin on the bra orbital. The radial Bessel transforms of every channel (and of the modified bra \(g(r) = r R(r)\) at \(l \pm 1\)) are computed once; every pair is then one vectorised evaluation of two_center_pair_blocks() (all channels, all \(L\) and all magnetic indices at once), which is what makes the tables of a 44-orbital basis a matter of seconds.

PAOFLOW.hamiltonian.position_dipoles.assemble_position_kspace(tables, k_points_cart)[source]#

Bloch sums of the overlap, its k-derivative and the intrinsic dipole.

Parameters:
Returns:

  • overlap_k (ndarray, shape (nk, nawf, nawf), complex) – \(S(\mathbf k) = \sum_{\Delta\mathbf R} e^{i\mathbf k\cdot\Delta\mathbf R} S(\Delta\mathbf R)\).

  • overlap_gradient_k (ndarray, shape (nk, 3, nawf, nawf), complex) – \(\partial_{\mathbf k} S(\mathbf k) = \sum_{\Delta\mathbf R} i\,\Delta\mathbf R\, e^{i\mathbf k\cdot\Delta\mathbf R} S(\Delta\mathbf R)\) (bohr).

  • dipole_k (ndarray, shape (nk, 3, nawf, nawf), complex) – \(X(\mathbf k)\) (bohr).

Notes

The phase carries the lattice translation only, as the Hamiltonian of band_velocities(); the orbital centres enter through \(\boldsymbol\tau\) in lowdin_dipole_kspace().

PAOFLOW.hamiltonian.position_dipoles.assemble_overlap_kspace(tables, k_points_cart)[source]#

Bloch overlap \(S(\mathbf k) = \sum_{\Delta\mathbf R} e^{i\mathbf k\cdot\Delta\mathbf R} S(\Delta\mathbf R)\) alone.

Parameters:
Returns:

The input of lowdin_transform().

Return type:

ndarray, shape (nk, nawf, nawf), complex

PAOFLOW.hamiltonian.position_dipoles.on_site_dipoles(tables)[source]#

Intra-atomic dipole matrix \(\langle\varphi_i|\mathbf r - \boldsymbol\tau|\varphi_j\rangle\).

Parameters:

tables (PositionTables)

Returns:

The (I, I, 0) blocks of PositionTables.dipole (bohr); zero between sites.

Return type:

ndarray, shape (3, nawf, nawf)

PAOFLOW.hamiltonian.position_dipoles.overlap_sqrt_and_derivative(overlap_k, overlap_gradient_k)[source]#

S^{1/2}, S^{-1/2} and \(\partial_{\mathbf k} S^{1/2}\) from the eigendecomposition.

Parameters:
  • overlap_k (ndarray, shape (nk, nawf, nawf), complex) – Hermitian positive-definite overlap \(S(\mathbf k)\).

  • overlap_gradient_k (ndarray, shape (nk, 3, nawf, nawf), complex) – \(\partial_{\mathbf k} S(\mathbf k)\).

Returns:

  • sqrt_k, inverse_sqrt_k (ndarray, shape (nk, nawf, nawf), complex)

  • sqrt_gradient_k (ndarray, shape (nk, 3, nawf, nawf), complex)

Raises:

ValueError – If \(S(\mathbf k)\) is not positive definite (linearly dependent orbitals).

Notes

With \(S = U\Lambda U^\dagger\), the derivative of the matrix square root solves \(S^{1/2}\,\partial S^{1/2} + \partial S^{1/2}\,S^{1/2} = \partial S\), i.e.

\[(U^\dagger\,\partial S^{1/2}\,U)_{ab} = \frac{(U^\dagger\,\partial S\,U)_{ab}}{\sqrt{\lambda_a} + \sqrt{\lambda_b}}.\]
PAOFLOW.hamiltonian.position_dipoles.lowdin_dipole_kspace(overlap_k, overlap_gradient_k, dipole_k, tau_orbitals, *, level='full', on_site=None)[source]#

Position dipoles \(\mathbf d(\mathbf k)\) of the Löwdin-orthonormal PAO basis.

Parameters:
  • overlap_k (ndarray) – Output of assemble_position_kspace().

  • overlap_gradient_k (ndarray) – Output of assemble_position_kspace().

  • dipole_k (ndarray) – Output of assemble_position_kspace().

  • tau_orbitals (ndarray, shape (nawf, 3)) – Orbital centres (Cartesian bohr).

  • level ({'full', 'intra-atomic'}, optional) – 'full': the Löwdin formula of the module docstring. 'intra-atomic': the on-site blocks on_site alone (\(S \equiv 1\)).

  • on_site (ndarray, shape (3, nawf, nawf), optional) – on_site_dipoles(); required for level='intra-atomic'.

Returns:

\(\mathbf d(\mathbf k)\) (bohr), Hermitian at every k up to the quadrature accuracy of the tables.

Return type:

ndarray, shape (nk, 3, nawf, nawf), complex

Raises:

ValueError – For an unknown level or a missing on_site with 'intra-atomic'.

PAOFLOW.hamiltonian.position_dipoles.hermiticity_residual(dipole_k)[source]#

Largest |d - d^dagger| over k and Cartesian components (bohr).

PAOFLOW.hamiltonian.position_dipoles.dipole_velocity_term(hamiltonian_k, dipole_k)[source]#

The velocity term \(i[H(\mathbf k), \mathbf d(\mathbf k)]\) in the orbital basis.

Parameters:
  • hamiltonian_k (ndarray, shape (nk, nawf, nawf), complex) – \(H(\mathbf k)\) (any energy unit).

  • dipole_k (ndarray, shape (nk, 3, nawf, nawf), complex) – \(\mathbf d(\mathbf k)\) (bohr).

Returns:

\(i(H\mathbf d - \mathbf d H)\) in (energy unit) bohr; in the band basis \(i(\varepsilon_n - \varepsilon_m)\,d_{nm}\), zero on the diagonal.

Return type:

ndarray, shape (nk, 3, nawf, nawf), complex

PAOFLOW.hamiltonian.position_dipoles.tesseral_signs(pao_catalog)[source]#

Sign of every PAOFLOW orbital with respect to the orbitals of the tables.

Alias of pao_orbital_signs(), where the convention \((-1)^l (-1)^{|m| \bmod 2}\) is documented.

class PAOFLOW.hamiltonian.position_dipoles.ProjectorAugmentation[source]#

PAW augmentation of the overlap and position matrices of the PAO Bloch basis.

With the projectors \(\tilde p^a_i\) and the partial waves \(\phi^a_i\), \(\tilde\phi^a_i\) of the PAW datasets, a local operator between the all-electron counterparts of two pseudo functions is \(\langle\tilde f|A|\tilde g\rangle + \sum_{a,ij}\langle\tilde f|\tilde p^a_i\rangle [\langle\phi^a_i|A|\phi^a_j\rangle - \langle\tilde\phi^a_i|A|\tilde\phi^a_j\rangle] \langle\tilde p^a_j|\tilde g\rangle\). For \(A = 1\) the bracket is \(q^a_{ij}\) (PP_Q); for \(A = \mathbf r - \boldsymbol\tau_a\) it is the dipole of the partial waves, a radial integral of \((\phi_i\phi_j - \tilde\phi_i\tilde\phi_j)\,r\) times the angular factor \(\langle Y_{l_i m_i}|\hat r_\alpha|Y_{l_j m_j}\rangle\).

Variables:
  • atoms (list of int) – Atom index of every projector block.

  • tau_atoms (ndarray (nat, 3)) – Atom positions (Cartesian bohr).

  • dipole_blocks (q_blocks,) – q^a (np_a, np_a) and Delta r^a (3, np_a, np_a) with the magnetic index resolved (QE order inside every channel), per atom.

  • overlaps (list of tuple) – (atom, site, deltaR_cart, block): \(\langle\tilde p^a_i|\tilde\varphi_\mu (\boldsymbol\tau_\mu + \Delta\mathbf R)\rangle\), block of shape (np_a, n_site).

  • nawf (basis_offsets, orbitals_per_site,)

atoms: list[source]#
tau_atoms: numpy.typing.NDArray[numpy.float64][source]#
q_blocks: list[source]#
dipole_blocks: list[source]#
overlaps: list[source]#
basis_offsets: list[source]#
orbitals_per_site: list[source]#
nawf: int[source]#
PAOFLOW.hamiltonian.position_dipoles.partial_wave_dipole_radial(upf)[source]#

Radial dipole integrals of the PAW partial waves, \(\int (u_i u_j - \tilde u_i \tilde u_j)\, r\, dr\).

Parameters:

upf (UPF) – A PAW dataset with PP_FULL_WFC (aewfc, pswfc_partial).

Returns:

Bohr; zero beyond the projector cutoff by construction (the partial waves coincide).

Return type:

ndarray (nbeta, nbeta)

PAOFLOW.hamiltonian.position_dipoles.build_projector_augmentation(data_controller, pao_catalog, *, q_max=20.0, n_q=600, pao_tol=0.0001)[source]#

The PAW augmentation of the PAO overlap and position matrices, or None without PAW.

Parameters:
Returns:

None when no species carries augmentation charges. Ultrasoft datasets without partial waves (PP_FULL_WFC) are skipped with a warning: their overlap augmentation q_ij is applied, their dipole augmentation is not available.

Return type:

ProjectorAugmentation or None

PAOFLOW.hamiltonian.position_dipoles.augmentation_kspace(aug, k_points_cart, tau_orbitals)[source]#

PAW corrections to S(k), d_k S(k) and X(k) of assemble_position_kspace().

Parameters:
  • aug (ProjectorAugmentation)

  • k_points_cart (ndarray (nk, 3)) – Cartesian inverse bohr (no \(2\pi\)).

  • tau_orbitals (ndarray (nawf, 3)) – Orbital centres (bohr), the bra origin of \(X\).

Returns:

overlap, overlap_gradient, dipole – (nk, nawf, nawf), (nk, 3, nawf, nawf), (nk, 3, nawf, nawf): with \(B^a(\mathbf k) = \sum_{\Delta\mathbf R} e^{i\mathbf k\cdot\Delta\mathbf R} \langle\tilde p^a|\tilde\varphi(\Delta\mathbf R)\rangle\), \(\Delta S = \sum_a B^{a\dagger} q^a B^a\), its k-gradient, and \(\Delta X_\alpha = \sum_a B^{a\dagger}(\Delta r^a_\alpha + \tau_{a\alpha} q^a)B^a - \tau_{\mu\alpha}\Delta S_{\mu\nu}\) (origin on the bra orbital).

Return type:

ndarray

PAOFLOW.hamiltonian.position_dipoles.position_dipole_operator(data_controller, bg, alat, *, level='full', q_max=20.0, n_q=600, pao_tol=0.0001, extra_pad=0.0, augmentation='auto')[source]#

Position dipoles of the PAO basis at arbitrary k, in PAOFLOW’s orbital conventions.

Parameters:
Returns:

K_cryst (nk, 3) -> (nk, 3, nawf, nawf): \(\mathbf d(\mathbf k)\) in bohr, the position_dipoles input of band_velocities().

Return type:

callable

Raises:

NotImplementedError – For fully-relativistic runs (scalar-relativistic bases only).

Notes

The tables are built once; every call Fourier-sums them at the requested k (folded to [-0.5, 0.5)), applies the Löwdin formula, symmetrises the result (\((\mathbf d + \mathbf d^\dagger)/2\) removes the quadrature noise) and restores PAOFLOW’s tesseral signs on both orbital indices (tesseral_signs()).

PAOFLOW.hamiltonian.position_dipoles.position_dipoles_on_grid(data_controller, kgrid_2pi_alat, *, level='full', q_max=20.0, n_q=600, pao_tol=0.001)[source]#

Position dipoles \(\mathbf d(\mathbf k)\) on PAOFLOW’s k-grid, in the basis of dHksp.

Parameters:
Returns:

\(\mathbf d(\mathbf k)\) in bohr with PAOFLOW’s orbital signs, Hermitian; n is nawf for scalar runs, 2 nawf for fully relativistic ones (the scalar matrix rotated to the (j, m_j) basis of dHksp with scalar_to_jm_matrix()) and for the ad-hoc spin-orbit path (block-diagonal in spin).

Return type:

ndarray, shape (nk, 3, n, n), complex

Notes

The input of inject_dipole_velocity_into_dHksp(); the k-grid layout is the caller’s (global, or the rank’s slice under MPI, as in PAOFLOW.PAOFLOW.position_dipole_correction()).

PAOFLOW.hamiltonian.position_dipoles.inject_dipole_velocity_into_dHksp(dHksp, energies_k, eigenvectors_k, dipole_k)[source]#

Add the position-dipole velocity term to dHksp in place.

Parameters:
  • dHksp (ndarray, shape (nk, 3, n, n, nspin), complex) – PAOFLOW’s gradient (eV bohr), which is minus the velocity operator (pksp = -<n|p|m>); modified in place.

  • energies_k (ndarray, shapes (nk, n, nspin) (eV) and (nk, n, n, nspin)) – arrays['E_k'] and arrays['v_k'] of pao_eigh at the same k-points, from which \(H(\mathbf k) = V E V^\dagger\) is rebuilt (do_gradient has overwritten Hksp).

  • eigenvectors_k (ndarray, shapes (nk, n, nspin) (eV) and (nk, n, n, nspin)) – arrays['E_k'] and arrays['v_k'] of pao_eigh at the same k-points, from which \(H(\mathbf k) = V E V^\dagger\) is rebuilt (do_gradient has overwritten Hksp).

  • dipole_k (ndarray, shape (nk, 3, n, n), complex) – position_dipoles_on_grid() (bohr).

Returns:

dHksp gains \(-\,i[H(\mathbf k), \mathbf d(\mathbf k)]\) (eV bohr), i.e. the velocity gains \(+i[H, \mathbf d]\) as in band_velocities().

Return type:

None

Raises:

ValueError – On shape mismatches.