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,
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,
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
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#
One (bra site, ket site, lattice translation) triple of the position tables. |
|
Real-space overlap and intrinsic-dipole blocks of the atomic orbitals. |
|
PAW augmentation of the overlap and position matrices of the PAO Bloch basis. |
Functions#
|
Enumerate the (bra site, ket site, lattice translation) triples within the orbital cutoffs. |
|
Two-centre overlap and intrinsic-dipole blocks for every pair. |
|
Bloch sums of the overlap, its k-derivative and the intrinsic dipole. |
|
Bloch overlap \(S(\mathbf k) = \sum_{\Delta\mathbf R} e^{i\mathbf k\cdot\Delta\mathbf R} S(\Delta\mathbf R)\) alone. |
|
Intra-atomic dipole matrix \(\langle\varphi_i|\mathbf r - \boldsymbol\tau|\varphi_j\rangle\). |
|
|
|
Position dipoles \(\mathbf d(\mathbf k)\) of the Löwdin-orthonormal PAO basis. |
|
Largest |
|
The velocity term \(i[H(\mathbf k), \mathbf d(\mathbf k)]\) in the orbital basis. |
|
Sign of every PAOFLOW orbital with respect to the orbitals of the tables. |
Radial dipole integrals of the PAW partial waves, \(\int (u_i u_j - \tilde u_i \tilde u_j)\, r\, dr\). |
|
|
The PAW augmentation of the PAO overlap and position matrices, or |
|
PAW corrections to |
|
Position dipoles of the PAO basis at arbitrary k, in PAOFLOW's orbital conventions. |
|
Position dipoles \(\mathbf d(\mathbf k)\) on PAOFLOW's k-grid, in the basis of |
|
Add the position-dipole velocity term to |
Module Contents#
- 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).
- 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.
- 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:
- Raises:
ValueError – If
a_vectors_cartis 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) –
Falsecomputes 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:
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:
tables (PositionTables) – Output of
build_position_tables().k_points_cart (ndarray, shape
(nk, 3)) – k-points in Cartesian inverse bohr (no \(2\pi\) factor).
- 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\) inlowdin_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:
tables (PositionTables) – Output of
build_position_tables()(include_dipole=Falseis enough).k_points_cart (ndarray, shape
(nk, 3)) – k-points in Cartesian inverse bohr.
- 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 ofPositionTables.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 blockson_sitealone (\(S \equiv 1\)).on_site (ndarray, shape
(3, nawf, nawf), optional) –on_site_dipoles(); required forlevel='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
levelor a missingon_sitewith'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:
tau_atoms (ndarray
(nat, 3)) – Atom positions (Cartesian bohr).dipole_blocks (q_blocks,) –
q^a(np_a, np_a)andDelta 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\),blockof shape(np_a, n_site).nawf (basis_offsets, orbitals_per_site,)
- 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
Nonewithout PAW.- Parameters:
data_controller (DataController) –
arrays['species'],arrays['atoms'],arrays['tau'](bohr),attr['fpath'](andattr['potcar_dir']for VASP: the partial waves and projectors then come from the POTCAR datasets,PAOFLOW.inputs.pseudopotentials).pao_catalog (PAOCatalog) – The PAO orbitals (
load_pao_orbitals()).q_max (optional) – As in
build_position_tables()/enumerate_pao_pairs().n_q (optional) – As in
build_position_tables()/enumerate_pao_pairs().pao_tol (optional) – As in
build_position_tables()/enumerate_pao_pairs().
- Returns:
Nonewhen no species carries augmentation charges. Ultrasoft datasets without partial waves (PP_FULL_WFC) are skipped with a warning: their overlap augmentationq_ijis 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)andX(k)ofassemble_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:
data_controller (DataController) – PAOFLOW data after
projections(PAO basis, species, UPF files,a_vectors).bg (ndarray, shape
(3, 3)) – Reciprocal lattice vectors (rows, \(2\pi/a\) units).alat (float) – Lattice parameter (bohr).
level ({'full', 'intra-atomic'}, optional) – See
lowdin_dipole_kspace().q_max (optional) – Table parameters of
build_position_tables()andenumerate_pao_pairs().n_q (optional) – Table parameters of
build_position_tables()andenumerate_pao_pairs().pao_tol (optional) – Table parameters of
build_position_tables()andenumerate_pao_pairs().extra_pad (optional) – Table parameters of
build_position_tables()andenumerate_pao_pairs().augmentation ({'auto', True, False}, optional) – PAW augmentation of the overlap and of the position matrix (
ProjectorAugmentation): the PAO orbitals are pseudo functions whose all-electron counterparts carry the partial-wave corrections inside the augmentation spheres.'auto'applies it when a species is ultrasoft / PAW (thelevel='full'Löwdin formula only);Falsegives the plain tables.
- Returns:
K_cryst (nk, 3) -> (nk, 3, nawf, nawf): \(\mathbf d(\mathbf k)\) in bohr, theposition_dipolesinput ofband_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:
data_controller (DataController) – PAOFLOW data after
projections(PAO basis, species, UPF files,a_vectors,alat,dftSO,adhoc_SO). The tables are cached under'_PD_tables'/'_PD_on_site'so repeated calls (MPI slices) are cheap.kgrid_2pi_alat (ndarray, shape
(3, nk)or(nk, 3)) – Cartesian k-points in units of \(2\pi/a\) (PAOFLOW’sarrays['kgrid']).level ({'full', 'intra-atomic'}, optional) – See
lowdin_dipole_kspace().q_max (optional) – Table parameters (
build_position_tables(),enumerate_pao_pairs()).n_q (optional) – Table parameters (
build_position_tables(),enumerate_pao_pairs()).pao_tol (optional) – Table parameters (
build_position_tables(),enumerate_pao_pairs()).
- Returns:
\(\mathbf d(\mathbf k)\) in bohr with PAOFLOW’s orbital signs, Hermitian;
nisnawffor scalar runs,2 nawffor fully relativistic ones (the scalar matrix rotated to the(j, m_j)basis ofdHkspwithscalar_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 inPAOFLOW.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
dHkspin 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']andarrays['v_k']ofpao_eighat the same k-points, from which \(H(\mathbf k) = V E V^\dagger\) is rebuilt (do_gradienthas overwrittenHksp).eigenvectors_k (ndarray, shapes
(nk, n, nspin)(eV) and(nk, n, n, nspin)) –arrays['E_k']andarrays['v_k']ofpao_eighat the same k-points, from which \(H(\mathbf k) = V E V^\dagger\) is rebuilt (do_gradienthas overwrittenHksp).dipole_k (ndarray, shape
(nk, 3, n, n), complex) –position_dipoles_on_grid()(bohr).
- Returns:
dHkspgains \(-\,i[H(\mathbf k), \mathbf d(\mathbf k)]\) (eV bohr), i.e. the velocity gains \(+i[H, \mathbf d]\) as inband_velocities().- Return type:
None
- Raises:
ValueError – On shape mismatches.