PAOFLOW.hamiltonian.nonlocal_velocity#

Non-local pseudopotential velocity correction (Kleinman–Bylander form).

This module assembles the data needed to evaluate

\[\Delta p^{\mathrm{PAO}}_\alpha(\mathbf{k}) = \frac{m}{i\hbar}\,\sum_I\!\left[ P_I^{\dagger}\,D^I\,P^{\alpha}_I - (P^{\alpha}_I)^{\dagger}\,D^I\,P_I \right](\mathbf{k}),\]

the non-local contribution to the velocity (momentum) matrix elements that is otherwise missing from PAOFLOW’s dH^{PAO}/dk operator (see TODOs/nonlocal_velocity_correction.md §2 for the derivation).

This file currently provides Phase 3a/3b loader infrastructure only. The real-space overlap tables and k-space assembly are added in subsequent phases.

Phase 3 covers norm-conserving pseudopotentials only. Ultrasoft and PAW augmentation contributions (the \(Q_{ij}\) charges) are deferred to a later phase.

Attributes#

RYDBERG_IN_EV

Classes#

`BetaSpeciesData`	Per-species Kleinman--Bylander projector data extracted from a UPF.
`BetaSiteData`	One entry per atomic site in the unit cell.
`BetaCatalog`	Top-level container for the loaded KB projector data.
`PAOChannelData`	One radial PAO channel from a UPF (per species, per shell).
`PAOSpeciesData`	Per-species PAO radial channels.
`PAOOrbitalEntry`	One real-spherical-harmonic PAO basis function on a given site.
`PAOSiteData`	Per-atom mapping into the PAO basis.
`PAOCatalog`	Top-level container for the loaded PAO atomic-orbital data.
`NLPair`	One real-space pair entering the non-local velocity tables.
`NLRealSpaceTables`	Real-space ⟨β\|φ⟩ and ⟨β\|r_α\|φ⟩ tables on a list of `NLPair`.

Functions#

`load_beta_projectors`(data_controller)	Load Kleinman--Bylander projectors and per-site mapping.
`qe_m_index_to_std`(qe_m, l)	Convert Quantum-ESPRESSO 1-indexed real-Y_lm `m` to the standard
`load_pao_orbitals`(data_controller)	Load PAO atomic radial functions and the per-site basis mapping.
`pao_cutoff_radius`(channel, r[, tol])	Return the numerical real-space cutoff of a PAO channel.
`site_beta_cutoff`(site)	Largest β-projector cutoff radius on a given site.
`site_pao_cutoff`(site[, tol])	Largest PAO radial cutoff on a given site (via `pao_cutoff_radius()`).
`enumerate_nl_pairs`(beta_catalog, pao_catalog, ...[, ...])	Enumerate (β-site, PAO-site, ΔR) triples within their pair cutoff.
`n_beta_lm`(site)	Number of LM-decomposed β projectors on a site (`Σ_i (2 l_i + 1)`).
`iter_beta_lm`(site)	Yield `(local_lm_index, channel_index, l, m_std, qe_m)` for the LM
`build_nl_real_space_tables`(beta_catalog, pao_catalog, ...)	Build per-pair ⟨β\|φ⟩ and ⟨β\|r_α\|φ⟩ blocks.
`assemble_beta_projections_k`(beta_catalog, pao_catalog, ...)	Fourier-sum the real-space ⟨β\|φ⟩ and ⟨β\|r_α\|φ⟩ tables to k-space.
`build_nonlocal_velocity_kspace`(beta_catalog, ...[, units])	Assemble \(\Delta p_\alpha(\mathbf{k})\) in the PAO basis.
`assemble_beta_projections_jm`(beta_catalog, ...)	Fourier-sum the real-space overlaps to k-space in the
`build_nonlocal_velocity_jm_kspace`(beta_catalog, ...[, ...])	Assemble \(\Delta p_\alpha(\mathbf{k})\) in the relativistic
`compute_nonlocal_velocity_jm_on_grid`(beta_catalog, ...)	Driver-facing wrapper around `build_nonlocal_velocity_jm_kspace()`.
`compute_nonlocal_velocity_on_grid`(beta_catalog, ...[, ...])	Driver-facing wrapper around `build_nonlocal_velocity_kspace()`.
`inject_into_dHksp`(dHksp, delta_pksp, *[, units, sign])	Add the non-local velocity correction into `dHksp` in place.
`build_jm_transformation_matrix`(atomic_basis_rel, ...)	Assemble the (n_r, 2 n_s) rotation from spinor-doubled scalar PAO
`rotate_dp_to_jm`(delta_p_scalar, T)	Rotate scalar Delta_p into the relativistic \(\|j, m_j\rangle\) basis.

Module Contents#

class PAOFLOW.hamiltonian.nonlocal_velocity.BetaSpeciesData[source]#

Per-species Kleinman–Bylander projector data extracted from a UPF.

Variables:

label (str) – Species label as it appears in data_arrays['species'].
pseudo_file (str) – UPF filename (basename), as recorded by Quantum ESPRESSO.
upf (UPF) – Parsed UPF object. Beta/D data live in UPF.beta and UPF.dion (the latter already in Hartree).
r (np.ndarray, shape (npoints,)) – Radial mesh (Bohr).
rab (np.ndarray, shape (npoints,)) – Radial integration weights.
nproj (int) – Number of KB projectors \(\beta_i(r)\) (no \(m\) index).
lchannels (list of int) – Angular momentum \(l_i\) of each projector (length nproj).
dion (np.ndarray, shape (nproj, nproj)) – Coupling matrix \(D_{ij}\) in Hartree.
jbeta (list of (float or None)) – Total angular momentum \(j_i\) of each projector (length nproj) for fully-relativistic UPFs, or None for each entry when the pseudopotential is scalar-relativistic.
has_spinorbit (bool) – True when the UPF carries a PP_SPIN_ORB block (i.e. the jbeta entries are populated).

label: str[source]#

pseudo_file: str[source]#

upf: PAOFLOW.inputs.read_upf.UPF[source]#

r: numpy.ndarray[source]#

rab: numpy.ndarray[source]#

nproj: int[source]#

lchannels: list[int][source]#

dion: numpy.ndarray[source]#

jbeta: list[float | None] = [][source]#

has_spinorbit: bool = False[source]#

class PAOFLOW.hamiltonian.nonlocal_velocity.BetaSiteData[source]#

One entry per atomic site in the unit cell.

Variables:

index (int) – Site index I (0-based), matching data_arrays['tau'].
label (str) – Species label.
tau (np.ndarray, shape (3,)) – Cartesian position \(\boldsymbol{\tau}_I\) (Bohr).
species (BetaSpeciesData) – Reference to the per-species KB data (shared across sites of the same species).

index: int[source]#

label: str[source]#

tau: numpy.ndarray[source]#

species: BetaSpeciesData[source]#

class PAOFLOW.hamiltonian.nonlocal_velocity.BetaCatalog[source]#

Top-level container for the loaded KB projector data.

Variables:

species (dict[str, BetaSpeciesData]) – Per-species data, keyed by species label.
sites (list of BetaSiteData) – Per-atom entries (length natoms).
total_nproj_radial (int) – \(\sum_I n_\beta^I\), ignoring the \(m\) (orientation) index. The full number of (β,m) basis functions is \(\sum_I \sum_i (2 l_{I,i} + 1)\); see total_nproj_lm.
total_nproj_lm (int) – \(\sum_I \sum_i (2 l_{I,i} + 1)\) – the dimension of the atom-resolved projector block used to build \(P_I(\mathbf{k})\).

species: dict[str, BetaSpeciesData][source]#

sites: list[BetaSiteData] = [][source]#

total_nproj_radial: int = 0[source]#

total_nproj_lm: int = 0[source]#

PAOFLOW.hamiltonian.nonlocal_velocity.load_beta_projectors(data_controller)[source]#

Load Kleinman–Bylander projectors and per-site mapping.

Parses each species’ UPF (via PAOFLOW.inputs.read_upf.UPF) once, then resolves the per-atom mapping using data_arrays['atoms'] and data_arrays['tau']. This is the Phase 3a loader for the non-local velocity correction (see TODOs/nonlocal_velocity_correction.md §2.5).

Parameters:

data_controller (DataController) –

Provider of data_arrays / data_attributes. Required:

arrays['species']: list of (label, pseudo_file).
arrays['atoms']: per-site list of species labels.
arrays['tau']: (natoms, 3) Cartesian positions (Bohr).
attributes['fpath']: directory containing the UPF files (typically <prefix>.save).

Returns:

Loaded species data and per-site mapping.

Return type:

BetaCatalog

Raises:

RuntimeError – If any species’ UPF is non-norm-conserving (USPP or PAW) – Phase 3 is NC only.
RuntimeError – If a species in arrays['atoms'] has no entry in arrays['species'].

PAOFLOW.hamiltonian.nonlocal_velocity.qe_m_index_to_std(qe_m, l)[source]#

Convert Quantum-ESPRESSO 1-indexed real-Y_lm m to the standard \(m \in \{-l, \dots, +l\}\) convention used by PAOFLOW.hamiltonian._two_center.

QE orders the \(2l+1\) real spherical harmonics as (Y_{l,0}, Y_{l,+1}, Y_{l,-1}, Y_{l,+2}, Y_{l,-2}, \\dots) indexed by qe_m = 1, 2, 3, .... The mapping is:

qe_m = 1 \(\\to\) m = 0
qe_m = 2k \(\\to\) m = +k (k = 1, \\dots, l)
qe_m = 2k+1 \(\\to\) m = -k (k = 1, \\dots, l)

class PAOFLOW.hamiltonian.nonlocal_velocity.PAOChannelData[source]#

One radial PAO channel from a UPF (per species, per shell).

Variables:

label (str) – UPF shell label (e.g. '2S', '3P', '3D').
l (int) – Angular momentum.
R_radial (np.ndarray, shape (npoints,)) – Pseudo-wavefunction radial part \(R(r) = (r\,R(r))/r\) (UPF’s r\,R divided by r with the r=0 end-point extrapolated for l=0 – see _upf_wfc_to_radial()).
wfc (np.ndarray, shape (npoints,)) – Original UPF array \(r\,R(r)\) (kept verbatim for callers that prefer the UPF convention, e.g. matching PAOFLOW.projection.do_atwfc_proj.radialfft_simpson()).
occupation (float) – UPF occupation attribute (non-negative; zero for unoccupied but available shells).

label: str[source]#

l: int[source]#

R_radial: numpy.ndarray[source]#

wfc: numpy.ndarray[source]#

occupation: float[source]#

class PAOFLOW.hamiltonian.nonlocal_velocity.PAOSpeciesData[source]#

Per-species PAO radial channels.

Variables:

label (str) – Species label as it appears in data_arrays['species'].
pseudo_file (str) – UPF filename.
upf (UPF) – Parsed UPF object (shared with BetaSpeciesData when both catalogs are loaded for the same species).
r (np.ndarray, shape (npoints,)) – Radial mesh (Bohr).
rab (np.ndarray, shape (npoints,)) – Radial integration weights.
channels (list[PAOChannelData]) – Radial channels in UPF order (one per occupied PSWFC shell).

label: str[source]#

pseudo_file: str[source]#

upf: PAOFLOW.inputs.read_upf.UPF[source]#

r: numpy.ndarray[source]#

rab: numpy.ndarray[source]#

channels: list[PAOChannelData][source]#

class PAOFLOW.hamiltonian.nonlocal_velocity.PAOOrbitalEntry[source]#

One real-spherical-harmonic PAO basis function on a given site.

Variables:

basis_index (int) – Position in the global PAOCatalog.basis list – matches the PAOFLOW orbital index 0..nawf-1 produced by PAOFLOW.projection.do_atwfc_proj.build_pswfc_basis_all().
site_index (int) – Site index J (matches data_arrays['tau']).
channel_index (int) – Index into PAOSpeciesData.channels.
l (int) – Angular momentum.
m (int) – Standard real-Y_lm magnetic quantum number \(m \in [-l, +l]\) (converted from QE’s 1-indexed qe_m via qe_m_index_to_std()).
qe_m (int) – Original QE 1-indexed magnetic index (preserved for cross-checks against build_pswfc_basis_all and the QE projection matrices).
label (str) – UPF shell label.

basis_index: int[source]#

site_index: int[source]#

channel_index: int[source]#

l: int[source]#

m: int[source]#

qe_m: int[source]#

label: str[source]#

class PAOFLOW.hamiltonian.nonlocal_velocity.PAOSiteData[source]#

Per-atom mapping into the PAO basis.

Variables:

index (int) – Site index J.
label (str) – Species label.
tau (np.ndarray, shape (3,)) – Cartesian position \(\boldsymbol{\tau}_J\) (Bohr).
species (PAOSpeciesData) – Reference to the per-species PAO data.
orbitals (list[PAOOrbitalEntry]) – Real-Y_lm basis functions belonging to this site, in PAOFLOW basis order (channel-major, m sweeps inside each channel).
basis_offset (int) – Index in the global PAO basis where this site’s block starts.

index: int[source]#

label: str[source]#

tau: numpy.ndarray[source]#

species: PAOSpeciesData[source]#

orbitals: list[PAOOrbitalEntry][source]#

basis_offset: int[source]#

class PAOFLOW.hamiltonian.nonlocal_velocity.PAOCatalog[source]#

Top-level container for the loaded PAO atomic-orbital data.

Variables:

species (dict[str, PAOSpeciesData]) – Per-species data, keyed by species label.
sites (list[PAOSiteData]) – Per-atom entries (length natoms).
basis (list[PAOOrbitalEntry]) – Flat PAO basis in PAOFLOW order; len(basis) == nawf.
total_nlm (int) – \(\sum_J \sum_\text{channels} (2l+1)\) – the dimension of the PAO basis.

species: dict[str, PAOSpeciesData][source]#

sites: list[PAOSiteData] = [][source]#

basis: list[PAOOrbitalEntry] = [][source]#

total_nlm: int = 0[source]#

PAOFLOW.hamiltonian.nonlocal_velocity.load_pao_orbitals(data_controller)[source]#

Load PAO atomic radial functions and the per-site basis mapping.

Phase 3b/3c loader for the non-local velocity correction.

When data_arrays['atomic_basis'] is present (PAOFLOW stashes it inside PAOFLOW.projections() after the projector basis has been built), the catalog is reconstructed from those records so that Δp operates on exactly the orbitals that produced dHksp. This is required when the production run uses an AE / extended basis (BASIS/<elem>/*.dat) whose orbital count and radial mesh do not match the UPF pswfc set.

Falls back to parsing upf.pswfc directly when atomic_basis is not present (legacy / unit-test path).

Parameters:

data_controller (DataController) –

Required:

arrays['species']: list of (label, pseudo_file).
arrays['atoms']: per-site list of species labels.
arrays['tau']: (natoms, 3) Cartesian positions (Bohr).
attributes['fpath']: directory containing the UPF files.

Optional:

arrays['atomic_basis']: per-orbital dicts (see PAOFLOW.projection.do_atwfc_proj.build_pswfc_basis_all()) with keys atom, tau, l, m, label, r, wfc.

Returns:

Loaded species data, per-site mapping, and flat PAO basis.

Return type:

PAOCatalog

Raises:

RuntimeError – On non-NC pseudos, missing species, a tau/atoms shape mismatch, or when atomic_basis records for the same species disagree on the radial mesh.

PAOFLOW.hamiltonian.nonlocal_velocity.pao_cutoff_radius(channel, r, tol=0.0001)[source]#

Return the numerical real-space cutoff of a PAO channel.

The pseudo-wavefunction \(r\,R(r)\) (stored as PAOChannelData.wfc) decays smoothly to zero outside the core. This helper returns the smallest r_c such that \(|r R(r)| < \mathrm{tol} \times \max_r |r R(r)|\) for every grid point \(r > r_c\).

Parameters:

channel (PAOChannelData) – PAO radial channel.
r (np.ndarray, shape (npoints,)) – Radial mesh from PAOSpeciesData.r.
tol (float, optional) – Relative threshold (default 1e-4).

Returns:

Cutoff radius in Bohr. r[-1] is returned if the tail never drops below tol × peak.

Return type:

float

PAOFLOW.hamiltonian.nonlocal_velocity.site_beta_cutoff(site)[source]#: Largest β-projector cutoff radius on a given site.

PAOFLOW.hamiltonian.nonlocal_velocity.site_pao_cutoff(site, tol=0.0001)[source]#: Largest PAO radial cutoff on a given site (via pao_cutoff_radius()).

class PAOFLOW.hamiltonian.nonlocal_velocity.NLPair[source]#

One real-space pair entering the non-local velocity tables.

Represents the displacement \(\mathbf{d} = (\boldsymbol{\tau}_J + \Delta\mathbf{R}) - \boldsymbol{\tau}_I\) between the β-projector center on site I (home cell) and the PAO orbital center on site J in the periodic image ΔR.

Variables:

beta_site (int) – Site index I (β projector, home cell).
pao_site (int) – Site index J (PAO orbital).
deltaR_lattice (tuple[int, int, int]) – Integer lattice translation (n1, n2, n3) so that \(\Delta\mathbf{R} = n_1 \mathbf{a}_1 + n_2 \mathbf{a}_2 + n_3 \mathbf{a}_3\).
deltaR_cart (np.ndarray, shape (3,)) – Cartesian translation (Bohr).
displacement (np.ndarray, shape (3,)) – \(\mathbf{d} = \boldsymbol{\tau}_J + \Delta\mathbf{R} - \boldsymbol{\tau}_I\) (Bohr).
distance (float) – \(\|\mathbf{d}\|\) (Bohr).
cutoff_used (float) – Pair cutoff \(r^\beta_I + r^\varphi_J + \text{pad}\) that kept this pair in the list.

beta_site: int[source]#

pao_site: int[source]#

deltaR_lattice: tuple[source]#

deltaR_cart: numpy.ndarray[source]#

displacement: numpy.ndarray[source]#

distance: float[source]#

cutoff_used: float[source]#

PAOFLOW.hamiltonian.nonlocal_velocity.enumerate_nl_pairs(beta_catalog, pao_catalog, a_vectors_cart, *, extra_pad=0.0, pao_tol=0.0001, distance_tol=1e-08)[source]#

Enumerate (β-site, PAO-site, ΔR) triples within their pair cutoff.

For every ordered pair (β-site I, PAO-site J) and every integer Bravais translation ΔR, the displacement \(\mathbf{d} = \boldsymbol{\tau}_J + \Delta\mathbf{R} - \boldsymbol{\tau}_I\) is checked against the pair cutoff \(r^\beta_I + r^\varphi_J + \text{pad}\). Surviving triples are returned as NLPair.

The search box is automatically sized from the largest pair cutoff via _lattice_search_bounds(), so the caller need only supply the catalogs and the Cartesian lattice (Bohr).

Parameters:

beta_catalog (BetaCatalog) – Loaded by load_beta_projectors().
pao_catalog (PAOCatalog) – Loaded by load_pao_orbitals().
a_vectors_cart (np.ndarray, shape (3, 3)) – Cartesian lattice vectors (Bohr). Row i is \(\mathbf{a}_i\). For PAOFLOW’s data layout this is arry['a_vectors'] * attr['alat'].
extra_pad (float, optional) – Extra padding added to every pair cutoff (Bohr).
pao_tol (float, optional) – Tolerance forwarded to pao_cutoff_radius().
distance_tol (float, optional) – Pairs with |d| < distance_tol are still emitted (they are the on-site I == J and ΔR = 0 contributions, important for the non-local velocity).

Returns:

Pair list (no particular order beyond the outer I, J loop).

Return type:

list[NLPair]

Raises:

RuntimeError – If the β and PAO catalogs have differing numbers of sites (they must come from the same crystal).

PAOFLOW.hamiltonian.nonlocal_velocity.n_beta_lm(site)[source]#: Number of LM-decomposed β projectors on a site (Σ_i (2 l_i + 1)).

PAOFLOW.hamiltonian.nonlocal_velocity.iter_beta_lm(site)[source]#

Yield (local_lm_index, channel_index, l, m_std, qe_m) for the LM decomposition of the KB projectors on site.

Ordering matches the PAO convention used by load_pao_orbitals(): channel-major, with qe_m = 1..2l+1 sweeping inside each channel. m_std is the standard real-Y_lm magnetic index (via qe_m_index_to_std()).

class PAOFLOW.hamiltonian.nonlocal_velocity.NLRealSpaceTables[source]#

Real-space ⟨β|φ⟩ and ⟨β|r_α|φ⟩ tables on a list of NLPair.

For each pair k linking β-site I (home cell) to PAO-site J in image ΔR:

S_bp [k] is shape (n_beta_lm(I), n_pao(J)) and stores \(S^{(k)}_{i m_\beta,\,\mu} = \langle \beta_{I,i,m_\beta} \,|\, \varphi_{J,\mu}(\cdot - \Delta\mathbf{R})\rangle\).
S_rbp [k] is shape (3, n_beta_lm(I), n_pao(J)) and stores the Cartesian dipole-weighted overlap \(\langle \beta_{I,i,m_\beta} \,|\, r_\alpha \,|\, \varphi_{J,\mu}(\cdot - \Delta\mathbf{R})\rangle\), already including the geometry term M_α(d) + (τ_I)_α · S^{(k)}_{i m_\beta, \mu}.

Both arrays are real (everything is on the real-tesseral basis).

Variables:

pairs (list[NLPair]) – Pair list this table was built on (same order).
S_bp (list[np.ndarray]) – Per-pair overlap blocks.
S_rbp (list[np.ndarray]) – Per-pair dipole-weighted overlap blocks (axis 0 = Cartesian α).
beta_lm_per_site (list[int]) – n_beta_lm(I) for I = 0..nsites-1.
pao_per_site (list[int]) – len(pao_site.orbitals) for each site.

pairs: list[source]#

S_bp: list[source]#

S_rbp: list[source]#

beta_lm_per_site: list[source]#

pao_per_site: list[source]#

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

Build per-pair ⟨β|φ⟩ and ⟨β|r_α|φ⟩ blocks.

Loops over the (β-site, PAO-site, ΔR) triples in pairs and, for each LM-decomposed β projector and each PAO orbital on the corresponding sites, evaluates the two-center primitives from PAOFLOW.hamiltonian._two_center.

Parameters:

beta_catalog (BetaCatalog) – Loaded by load_beta_projectors().
pao_catalog (PAOCatalog) – Loaded by load_pao_orbitals().
pairs (list[NLPair]) – Output of enumerate_nl_pairs().
q_max (float, int) – Radial Bessel transform quadrature parameters forwarded to two_center_overlap() and two_center_dipole_overlap().
n_q (float, int) – Radial Bessel transform quadrature parameters forwarded to two_center_overlap() and two_center_dipole_overlap().
include_dipole (bool, optional) – If False, NLRealSpaceTables.S_rbp is a list of empty arrays. Useful for cheap diagnostic builds.

Return type:

NLRealSpaceTables

Notes

Uses a precomputed radial-Bessel-transform cache: for each species and radial channel the transform \(J(q) = \int R(r)\,j_l(qr)\,r^2\,dr\) is computed exactly once on a shared q_grid (likewise for the modified bra \(g(r) = r\,R(r)\) at the parity-allowed \(L' = l \pm 1\) needed by the dipole). All subsequent pair evaluations reuse these cached \(J\)’s, cutting cost by roughly two orders of magnitude versus naive recomputation.

PAOFLOW.hamiltonian.nonlocal_velocity.assemble_beta_projections_k(beta_catalog, pao_catalog, tables, k_points_cart)[source]#

Fourier-sum the real-space ⟨β|φ⟩ and ⟨β|r_α|φ⟩ tables to k-space.

For each β-host site \(I\) and each k-point, build

\[P_I(\mathbf{k})_{i m_\beta,\,\mu} = \sum_{\Delta\mathbf{R}} e^{i\mathbf{k}\cdot\Delta\mathbf{R}}\, \langle \beta_{I,i,m_\beta}\,|\, \varphi_{J(\mu),\mu}(\cdot - \Delta\mathbf{R})\rangle,\]

where the sum runs over the pairs in tables.pairs that have beta_site == I. The dipole variant \(P^{\alpha}_I(\mathbf{k})\) is built analogously from tables.S_rbp and includes the geometry term already baked in by build_nl_real_space_tables().

Parameters:

beta_catalog (BetaCatalog, PAOCatalog)
pao_catalog (BetaCatalog, PAOCatalog)
tables (NLRealSpaceTables) – Output of build_nl_real_space_tables(). Must have been built with include_dipole=True.
k_points_cart (np.ndarray, shape (nk, 3)) – k-points in Cartesian inverse Bohr (no implicit 2\pi factor; the phase used is exp(i k · ΔR) with ΔR in Bohr).

Returns:

P_list (list of np.ndarray) – P_list[I] has shape (nk, n_beta_lm(I), nawf) complex.
Palpha_list (list of np.ndarray) – Palpha_list[I] has shape (nk, 3, n_beta_lm(I), nawf) complex.

PAOFLOW.hamiltonian.nonlocal_velocity.build_nonlocal_velocity_kspace(beta_catalog, pao_catalog, tables, k_points_cart, *, units='hartree')[source]#

Assemble \(\Delta p_\alpha(\mathbf{k})\) in the PAO basis.

Computes

\[\Delta p_\alpha(\mathbf{k}) = \frac{m}{i\hbar}\,\sum_I\!\left[ P_I^{\dagger}(\mathbf{k})\,D^I\,P^{\alpha}_I(\mathbf{k}) - (P^{\alpha}_I(\mathbf{k}))^{\dagger}\,D^I\,P_I(\mathbf{k}) \right]\]

in the real-tesseral PAO basis (no spin). The bracket is anti-Hermitian, so the result is Hermitian at every k.

Parameters:

beta_catalog (BetaCatalog, PAOCatalog)
pao_catalog (BetaCatalog, PAOCatalog)
tables (NLRealSpaceTables) – Built with include_dipole=True.
k_points_cart (np.ndarray, shape (nk, 3)) – Cartesian inverse Bohr.
units ({'hartree', 'rydberg'}, optional) – Output units. The stored \(D^I\) is in Hartree, so in atomic Hartree units (\(m = \hbar = 1\)) the prefactor \(m/(i\hbar) = -i\). Selecting 'rydberg' returns the same operator scaled by 2 to match the Rydberg-based convention used internally by do_gradient / do_momentum.

Returns:

dP

Return type:

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

PAOFLOW.hamiltonian.nonlocal_velocity.assemble_beta_projections_jm(beta_catalog, pao_catalog, tables, k_points_cart)[source]#

Fourier-sum the real-space overlaps to k-space in the \((j, m_j)\) spinor basis.

Like assemble_beta_projections_k(), but transforms both the β index (to \((j_\beta, m_{j\beta})\), restricted to each channel’s physical j-block) and the PAO index (to the global relativistic \((j, m_j)\) basis of dimension 2 × total_nlm).

Returns:

P_list (list of np.ndarray) – P_list[I] has shape (nk, n_beta_jm(I), n_rel) complex.
Palpha_list (list of np.ndarray) – Palpha_list[I] has shape (nk, 3, n_beta_jm(I), n_rel) complex.

PAOFLOW.hamiltonian.nonlocal_velocity.build_nonlocal_velocity_jm_kspace(beta_catalog, pao_catalog, tables, k_points_cart, *, units='hartree')[source]#

Assemble \(\Delta p_\alpha(\mathbf{k})\) in the relativistic \((j, m_j)\) PAO basis (Option A).

Computes

\[\Delta p_\alpha(\mathbf{k}) = \frac{m}{i\hbar}\,\sum_I\!\left[ P_I^{\dagger}\,D^{jm}_I\,P^{\alpha}_I - (P^{\alpha}_I)^{\dagger}\,D^{jm}_I\,P_I \right](\mathbf{k})\]

directly in the 2 × total_nlm spinor basis used by dHksp for dftSO=True. No scalar \(\Delta p\) is formed and no spin trace is taken, so the j-dependence of the NL operator is preserved.

Returns:: dP
Return type:: np.ndarray, shape (nk, 3, n_rel, n_rel), complex

PAOFLOW.hamiltonian.nonlocal_velocity.compute_nonlocal_velocity_jm_on_grid(beta_catalog, pao_catalog, tables, kgrid_2pi_alat, alat, *, units='rydberg')[source]#

Driver-facing wrapper around build_nonlocal_velocity_jm_kspace().

Mirrors compute_nonlocal_velocity_on_grid() but returns the correction in the relativistic (j, m_j) basis (shape (nktot, 3, n_rel, n_rel) with n_rel = 2 × total_nlm).

PAOFLOW.hamiltonian.nonlocal_velocity.compute_nonlocal_velocity_on_grid(beta_catalog, pao_catalog, tables, kgrid_2pi_alat, alat, *, units='rydberg')[source]#

Driver-facing wrapper around build_nonlocal_velocity_kspace().

Accepts the PAOFLOW-native k-grid representation (Cartesian in units of \(2\pi/\mathrm{alat}\), the convention written by PAOFLOW.utils.get_K_grid_fft.get_K_grid_fft()) and converts it to inverse Bohr internally before calling build_nonlocal_velocity_kspace().

Parameters:

beta_catalog – Outputs of load_beta_projectors(), load_pao_orbitals(), build_nl_real_space_tables().
pao_catalog – Outputs of load_beta_projectors(), load_pao_orbitals(), build_nl_real_space_tables().
tables – Outputs of load_beta_projectors(), load_pao_orbitals(), build_nl_real_space_tables().
kgrid_2pi_alat (np.ndarray) – Shape (3, nktot) or (nktot, 3) — Cartesian k-points in units of \(2\pi/\mathrm{alat}\) (PAOFLOW’s arry['kgrid'] is the (3, nktot) layout).
alat (float) – Lattice parameter in Bohr.
units ({'hartree', 'rydberg'}) – Forwarded to build_nonlocal_velocity_kspace().

Returns:

dP

Return type:

np.ndarray, complex, shape (nktot, 3, nawf, nawf)

PAOFLOW.hamiltonian.nonlocal_velocity.RYDBERG_IN_EV = 13.605693122994[source]#

PAOFLOW.hamiltonian.nonlocal_velocity.inject_into_dHksp(dHksp, delta_pksp, *, units='rydberg', sign=+1)[source]#

Add the non-local velocity correction into dHksp in place.

Sign + prefactor calibrated against epsilon.x for Cu (see example17_Cu_epsilon); after the Y_lm convention fix on the PAO indices of \(\Delta p\) (see build_nonlocal_velocity_kspace()), cubic isotropy of \(\varepsilon_{\alpha\alpha}\) is restored with sign=+1 and the d→p peak position/height of the QE reference is recovered. Convention:

\[\mathrm{dHksp}[k,\alpha,n,m,\sigma] \mathrel{+}= \mathrm{sign} \cdot \lambda \cdot \Delta p_\alpha(k)_{nm}\]

with \(\lambda = 13.605693122994\) eV/Ry for units='rydberg' or \(2\lambda\) eV/Ha for units='hartree'.

The correction is broadcast across the spin axis (NC pseudos are spin-diagonal at the projector level).

Parameters:

dHksp (np.ndarray, shape (nktot, 3, nawf, nawf, nspin), complex) – Modified in place.
delta_pksp (np.ndarray, shape (nktot, 3, nawf, nawf), complex) – Output of compute_nonlocal_velocity_on_grid().
units ({'hartree', 'rydberg'}) – Unit of delta_pksp.
sign (int) – +1 (default, calibrated) or -1. Override only when debugging sign conventions.

Raises:

ValueError – On bad units, bad sign, mismatched shapes, or non-complex dHksp.

PAOFLOW.hamiltonian.nonlocal_velocity.build_jm_transformation_matrix(atomic_basis_rel, atomic_basis_scalar)[source]#

Assemble the (n_r, 2 n_s) rotation from spinor-doubled scalar PAO to the relativistic \(|j, m_j\rangle\) PAO basis.

Parameters:

atomic_basis_rel (sequence of mapping) – Relativistic basis (dftSO=True) as produced by PAOFLOW.projection.do_atwfc_proj.build_aewfc_basis(). Each record must contain 'atom', 'label', 'l' and appear in assign_jm order: contiguous shells of size 2(2l+1) per (atom, label, l).
atomic_basis_scalar (sequence of mapping) – Scalar (dftSO=False) basis matching atomic_basis_rel shell-by-shell. Each record must contain 'atom', 'label', 'l' and have shells of size 2l+1.

Returns:

T – Block-diagonal in (atom, shell) unitary mapping the spinor-doubled scalar PAO vector (laid out as [up_0..up_{n_s-1}, down_0..down_{n_s-1}]) to the relativistic basis (assign_jm order).

Return type:

np.ndarray, shape (n_r, 2 * n_s), complex

Raises:

RuntimeError – On any shell mismatch between the two bases or on size inconsistency (n_r != 2 * n_s).

PAOFLOW.hamiltonian.nonlocal_velocity.rotate_dp_to_jm(delta_p_scalar, T)[source]#

Rotate scalar Delta_p into the relativistic \(|j, m_j\rangle\) basis.

Given delta_p_scalar of shape (..., n_s, n_s) and the transformation T of shape (n_r, 2 n_s) from build_jm_transformation_matrix(), returns

\[\Delta p_\mathrm{rel} = T_\uparrow\,\Delta p\,T_\uparrow^\dagger + T_\downarrow\,\Delta p\,T_\downarrow^\dagger\]

where T_up = T[:, :n_s] and T_down = T[:, n_s:]. This is the block-diagonal spinor extension Delta_p_spinor = diag(Delta_p, Delta_p) followed by the rotation T (...) T^H, written out without materialising the full (2 n_s, 2 n_s) block-diagonal matrix.

Parameters:

delta_p_scalar (np.ndarray, shape (..., n_s, n_s)) – Scalar non-local velocity correction; the leading axes are broadcast (typical: (nk, 3)).
T (np.ndarray, shape (n_r, 2 n_s)) – Per-shell block-diagonal unitary from build_jm_transformation_matrix().

Return type:

np.ndarray, shape (..., n_r, n_r), complex