PAOFLOW.projection.do_atwfc_proj#

Attributes#

`comm`
`rank`
`size`
`AUTOA`

Functions#

`read_pswfc_from_upf`(data_controller, atom)	Read pseudopotential wavefunction data from a UPF file for a given atom type.
`radialfft_simpson`(r, f, l, qmesh, volume)	Compute the radial Fourier transform using the spherical Bessel function and Simpson integration.
`assign_jm`(basis)	Assign total-angular-momentum composite index `jm` to spin-orbit basis functions.
`build_pswfc_basis_all`(data_controller)	Construct the pseudopotential wavefunction basis set from UPF files for all atoms.
`build_aewfc_basis`(data_controller)	Construct the all-electron wavefunction basis set from atomic orbital files.
`build_mixed_basis`(data_controller)	Construct a mixed basis: pseudo-atomic wavefunctions + AE polarization.
`fft_wfc_G2R_old`(wfc, igwx, gamma_only, mill, nr1, nr2, ...)	Transform a wavefunction from G-space to real space (deprecated).
`fft_wfc_G2R`(wfc, gkspace, nr1, nr2, nr3, omega)	Transform a wavefunction from G-space to real space via inverse FFT.
`fft_allwfc_G2R`(wfc, gkspace, nr1, nr2, nr3, omega)	Transform multiple wavefunctions from G-space to real space via inverse FFT.
`fft_wfc_R2G`(wfc, igwx, mill, omega)	Transform a wavefunction from real space to G-space via forward FFT.
`read_QE_wfc`(data_controller, ik, ispin)	Read Quantum ESPRESSO wavefunction coefficients from a Fortran binary `wfc*.dat` file.
`calc_ylmg`(k_plus_G, q)	Compute real cubic harmonics for the k+G vectors up to \(l=3\).
`calc_ylmg_complex_0`(ylmg)	Convert real cubic harmonics to complex spherical harmonics.
`calc_ylmg_so`(ylmgc)	Build spinor spherical harmonics from complex spherical harmonics.
`calc_atwfc_k`(basis, gkspace[, dftSO])	Evaluate atomic wavefunctions in G-space at a given k-point.
`ortho_atwfc_k`(atwfc_k)	Orthonormalise atomic wavefunctions at a k-point via symmetric orthogonalisation.
`calc_proj_k`(data_controller, basis, ik, ispin)	Compute projection matrix of crystal wavefunctions onto atomic basis at a k-point.
`calc_gkspace`(data_controller, ik[, gamma_only])	Compute the G-vector set and k+G space parameters for a given k-point.
`read_WAVECAR_header`(data_controller)	Read and validate the VASP WAVECAR file header.
`readBandCoeff`(data_controller[, ispin, ikpt, iband])	Read plane-wave coefficients for one band from the VASP WAVECAR file.
`read_VASP_wfc`(data_controller, ik, ispin)	Read VASP WAVECAR wavefunction and return orthonormalised coefficients with k+G info.
`calc_gvec_VASP`(data_controller[, ikpt])	Compute the G-vector set for a VASP k-point satisfying the energy cutoff.
`tesseral_to_ylm_matrix`(l)	Per-shell unitary mapping real tesseral harmonics to complex Y_lm.
`clebsch_jm_matrix`(l)	Per-shell Clebsch-Gordan map (m_l, sigma) -> (j, m_j).

Module Contents#

PAOFLOW.projection.do_atwfc_proj.comm[source]#

PAOFLOW.projection.do_atwfc_proj.rank[source]#

PAOFLOW.projection.do_atwfc_proj.size[source]#

PAOFLOW.projection.do_atwfc_proj.AUTOA = 0.529177249[source]#

PAOFLOW.projection.do_atwfc_proj.read_pswfc_from_upf(data_controller, atom)[source]#

Read pseudopotential wavefunction data from a UPF file for a given atom type.

Parameters:

data_controller (DataController) – Object providing data_arrays and data_attributes. Required arrays: species (list of (label, pseudo_file) pairs). Required attributes: fpath (directory containing UPF files).
atom (str) – Chemical symbol of the atomic species to match.

Returns:

r (np.ndarray) – Radial grid of the pseudopotential (Bohr).
pswfc (dict) – Pseudopotential wavefunctions keyed by orbital shell label.
pseudo (str) – Filename of the UPF pseudopotential for the matched species.

Raises:

RuntimeError – If no species matching atom is found in data_arrays['species'].

PAOFLOW.projection.do_atwfc_proj.radialfft_simpson(r, f, l, qmesh, volume)[source]#

Compute the radial Fourier transform using the spherical Bessel function and Simpson integration.

Parameters:

r (np.ndarray) – Radial grid (Bohr).
f (np.ndarray) – Radial function values on r.
l (int) – Angular momentum quantum number.
qmesh (np.ndarray) – Reciprocal-space grid on which the transform is evaluated.
volume (float) – Unit-cell volume (Bohr³).

Returns:

Spherical Bessel transform of f evaluated on qmesh, \(f_l(q) = 4\pi/\sqrt{\Omega} \int_0^\infty f(r)\,j_l(qr)\,r\,dr\).

Return type:

np.ndarray, shape (len(qmesh),)

PAOFLOW.projection.do_atwfc_proj.assign_jm(basis)[source]#

Assign total-angular-momentum composite index jm to spin-orbit basis functions.

Parameters:: basis (list of dict) – Atomic basis function records (as built by build_pswfc_basis_all()). Each record must contain at least the key 'l' (angular momentum quantum number 0–3). The function expects consecutive records for each \((l, m_j)\) pair.
Returns:: Each dictionary in basis is modified in place, gaining the key 'jm' whose integer value encodes the \((j, m_j)\) pair used by the spinor spherical-harmonic routines.
Return type:: None

PAOFLOW.projection.do_atwfc_proj.build_pswfc_basis_all(data_controller)[source]#

Construct the pseudopotential wavefunction basis set from UPF files for all atoms.

Parameters:

data_controller (DataController) – Object providing data_arrays and data_attributes. Required arrays: atoms, tau, species. Required attributes: ecutrho, omega, verbose, dftSO, fpath.

Returns:

basis (list of dict) – One record per atomic orbital with keys atom, tau, l, m, label, r, wfc, qmesh, wfc_g (and jm when dftSO is True).
shells (dict) – Maps each atomic species label to a list of angular-momentum quantum numbers for its pseudopotential shells.

Notes

When attr['dftSO'] is True, an extra spinor entry is appended for \(l=0\) shells and assign_jm() is called to set the 'jm' index on every basis entry.

PAOFLOW.projection.do_atwfc_proj.build_aewfc_basis(data_controller)[source]#

Construct the all-electron wavefunction basis set from atomic orbital files.

Parameters:

data_controller (DataController) – Object providing data_arrays and data_attributes. Required arrays: atoms, tau. Required attributes: ecutrho, omega, verbose, dftSO, basispath (directory containing per-element *.dat files).

Returns:

basis (list of dict) – One record per atomic orbital with the same structure as returned by build_pswfc_basis_all().
shells (dict) – Maps each atomic species label to a list of angular-momentum quantum numbers.

PAOFLOW.projection.do_atwfc_proj.build_mixed_basis(data_controller)[source]#

Construct a mixed basis: pseudo-atomic wavefunctions + AE polarization.

The pseudo-atomic wavefunctions read from the UPF are kept as the baseline (they were generated together with the pseudopotential and therefore project the QE valence bands faithfully). On top of that baseline, extra all-electron shells listed in arry['configuration'] are loaded from basispath/<elem>/*.dat and appended.

arry['configuration'] here lists ONLY the augmenting shells (the pseudo shells come from the UPF automatically). An empty or missing entry for a species means “no augmentation for this species” and yields a pure pseudo basis for those atoms.

Parameters:

data_controller (DataController) – Object providing data_arrays and data_attributes. Required arrays: atoms, tau, species, configuration. Required attributes: ecutrho, omega, verbose, dftSO, fpath, basispath.

Returns:

basis (list of dict) – Concatenation of the pseudo and AE basis records (same dict schema as build_pswfc_basis_all()).
shells (dict) – {species: [l, ...]} — angular momenta of the pseudo shells followed by those of the AE augmentation.

Raises:

NotImplementedError – If attr['dftSO'] is True. The spin-orbit jm index assignment in assign_jm() assumes a specific ordering of consecutive (l, m_j) entries that the simple concatenation here does not preserve. Use a pure pseudo or pure AE basis under spin-orbit.

PAOFLOW.projection.do_atwfc_proj.fft_wfc_G2R_old(wfc, igwx, gamma_only, mill, nr1, nr2, nr3, omega)[source]#

Transform a wavefunction from G-space to real space (deprecated).

Deprecated since version Use: fft_wfc_G2R() instead.

Parameters:

wfc (np.ndarray, shape (igwx,), complex) – Plane-wave coefficients in G-space.
igwx (int) – Number of G-vectors.
gamma_only (bool) – If True, apply Hermitian symmetry to fill the conjugate G-vector automatically.
mill (np.ndarray, shape (3, igwx), int) – Miller indices for each G-vector.
nr1 (int) – FFT grid dimensions.
nr2 (int) – FFT grid dimensions.
nr3 (int) – FFT grid dimensions.
omega (float) – Unit-cell volume (Bohr³).

Returns:

Wavefunction on the real-space FFT grid, normalised by \(\sqrt{\Omega}\).

Return type:

np.ndarray, shape (nr1, nr2, nr3), complex

PAOFLOW.projection.do_atwfc_proj.fft_wfc_G2R(wfc, gkspace, nr1, nr2, nr3, omega)[source]#

Transform a wavefunction from G-space to real space via inverse FFT.

Parameters:

wfc (np.ndarray, shape (igwx,), complex) – Plane-wave coefficients in G-space.
gkspace (dict) – G-space descriptor with keys 'igwx' (int), 'gamma_only' (bool), and 'mill' (ndarray, shape (3, igwx)).
nr1 (int) – FFT grid dimensions.
nr2 (int) – FFT grid dimensions.
nr3 (int) – FFT grid dimensions.
omega (float) – Unit-cell volume (Bohr³).

Returns:

Wavefunction on the real-space FFT grid, normalised by \(\sqrt{\Omega}\).

Return type:

np.ndarray, shape (nr1, nr2, nr3), complex

PAOFLOW.projection.do_atwfc_proj.fft_allwfc_G2R(wfc, gkspace, nr1, nr2, nr3, omega)[source]#

Transform multiple wavefunctions from G-space to real space via inverse FFT.

Parameters:

wfc (np.ndarray, complex) – Plane-wave coefficients. Shape (nwx, igwx) for a single spin-component set, or (nox, nwx, igwx) for spinor bands.
gkspace (dict) – G-space descriptor with keys 'igwx', 'gamma_only', 'mill'.
nr1 (int) – FFT grid dimensions.
nr2 (int) – FFT grid dimensions.
nr3 (int) – FFT grid dimensions.
omega (float) – Unit-cell volume (Bohr³).

Returns:

Wavefunctions on the real-space FFT grid, shape (nwx, nr1, nr2, nr3) or (nox, nr1, nr2, nr3).

Return type:

np.ndarray, complex

PAOFLOW.projection.do_atwfc_proj.fft_wfc_R2G(wfc, igwx, mill, omega)[source]#

Transform a wavefunction from real space to G-space via forward FFT.

Parameters:

wfc (np.ndarray, complex) – Wavefunction on the real-space FFT grid.
igwx (int) – Number of G-vectors.
mill (np.ndarray, shape (3, igwx), int) – Miller indices for each G-vector.
omega (float) – Unit-cell volume (Bohr³).

Returns:

Plane-wave coefficients normalised by \(1/\sqrt{\Omega}\).

Return type:

np.ndarray, shape (igwx,), complex

PAOFLOW.projection.do_atwfc_proj.read_QE_wfc(data_controller, ik, ispin)[source]#

Read Quantum ESPRESSO wavefunction coefficients from a Fortran binary wfc*.dat file.

Parameters:

data_controller (DataController) – Object providing data_arrays and data_attributes. Required attributes: nspin, fpath.
ik (int) – Zero-based k-point index.
ispin (int) – Spin index (0 = down, 1 = up for nspin = 2).

Returns:

gkspace (dict) – G-space descriptor with keys 'xk', 'igwx', 'mill', 'bg', 'gamma_only'.
wfc (dict) – Wavefunction data with keys 'wfc' (complex array), 'npol', 'nbnd', 'ispin'.

PAOFLOW.projection.do_atwfc_proj.calc_ylmg(k_plus_G, q)[source]#

Compute real cubic harmonics for the k+G vectors up to \(l=3\).

Parameters:

k_plus_G (np.ndarray, shape (npw, 3)) – Cartesian k+G vectors.
q (np.ndarray, shape (npw,)) – Magnitudes of the k+G vectors (used to normalise the direction).

Returns:

Cubic harmonics for \(l = 0, 1, 2, 3\) (1+3+5+7 = 16 components).

Return type:

np.ndarray, shape (npw, 16), float

PAOFLOW.projection.do_atwfc_proj.calc_ylmg_complex_0(ylmg)[source]#

Convert real cubic harmonics to complex spherical harmonics.

Parameters:: ylmg (np.ndarray, shape (npw, 16)) – Real cubic harmonics from calc_ylmg().
Returns:: Complex spherical harmonics \(Y_l^m\) with Condon-Shortley phase convention.
Return type:: np.ndarray, shape (npw, nylm), complex128

PAOFLOW.projection.do_atwfc_proj.calc_ylmg_so(ylmgc)[source]#

Build spinor spherical harmonics from complex spherical harmonics.

Parameters:: ylmgc (np.ndarray, shape (npw, nylm), complex128) – Complex spherical harmonics from calc_ylmg_complex_0().
Returns:: Spinor spherical harmonics \(\chi_{j,m_j}^{l}\) organised as upper (indices 0:npw) and lower (indices npw:2*npw) spinor components for all \((j, m_j)\) channels.
Return type:: np.ndarray, shape (2*npw, 2*nylm), complex128

PAOFLOW.projection.do_atwfc_proj.calc_atwfc_k(basis, gkspace, dftSO=False)[source]#

Evaluate atomic wavefunctions in G-space at a given k-point.

Parameters:

basis (list of dict) – Atomic basis function records (from build_pswfc_basis_all() or build_aewfc_basis()). Each record must contain at least 'atom', 'tau', 'l', 'm', 'qmesh', 'wfc_g' (and 'jm' when dftSO is True).
gkspace (dict) – G-space descriptor with keys 'xk', 'igwx', 'mill', 'bg', 'gamma_only'.
dftSO (bool, optional) – If True, generate spinor atomic wavefunctions (default False).

Returns:

Atomic wavefunctions at the k-point, shape (natwfc, igwx) (scalar) or (natwfc, 2*igwx) (spinor).

Return type:

np.ndarray, complex

PAOFLOW.projection.do_atwfc_proj.ortho_atwfc_k(atwfc_k)[source]#

Orthonormalise atomic wavefunctions at a k-point via symmetric orthogonalisation.

Parameters:: atwfc_k (np.ndarray, shape (natwfc, igwx), complex) – Atomic wavefunctions from calc_atwfc_k().
Returns:: Orthonormalised wavefunctions satisfying \(\langle i | j \rangle = \delta_{ij}\).
Return type:: np.ndarray, shape (natwfc, igwx), complex
Raises:: RuntimeError – If the orthonormalisation residual exceeds 1e-4.

PAOFLOW.projection.do_atwfc_proj.calc_proj_k(data_controller, basis, ik, ispin)[source]#

Compute projection matrix of crystal wavefunctions onto atomic basis at a k-point.

Parameters:

data_controller (DataController) – Object providing data_arrays and data_attributes. Required attributes: dft ('QE' or 'VASP'), dftSO.
basis (list of dict) – Atomic basis functions.
ik (int) – Zero-based k-point index.
ispin (int) – Spin index.

Returns:

Projections \(\langle\psi_{n\mathbf{k}} | \phi_i\rangle\) for all bands and basis functions.

Return type:

np.ndarray, shape (nbnd, natwfc), complex

PAOFLOW.projection.do_atwfc_proj.calc_gkspace(data_controller, ik, gamma_only=False)[source]#

Compute the G-vector set and k+G space parameters for a given k-point.

Parameters:

data_controller (DataController) – Object providing data_arrays and data_attributes. Required arrays: a_vectors, b_vectors, kgrid. Required attributes: ecutrho, ecutwfc, alat.
ik (int) – Zero-based k-point index.
gamma_only (bool, optional) – If True, use the \(\Gamma\)-only symmetry (default False).

Returns:

G-space descriptor with keys 'xk', 'igwx', 'mill', 'bg', 'gamma_only'. Also stored in data_arrays['gkspace'].

Return type:

dict

PAOFLOW.projection.do_atwfc_proj.read_WAVECAR_header(data_controller)[source]#

Read and validate the VASP WAVECAR file header.

Parameters:

data_controller (DataController) – Object providing data_arrays and data_attributes. Required attributes: nspin, fpath.

Returns:

Stores the following in data_attributes:

recl : int — record length of the WAVECAR file.
wfc_prec : dtype — np.complex64 or np.complex128.
ngrid : np.ndarray, shape (3,) — FFT grid dimensions.

Stores in data_arrays:

nplws : np.ndarray, shape (nkpts,) — number of plane waves per k-point.

Return type:

None

PAOFLOW.projection.do_atwfc_proj.readBandCoeff(data_controller, ispin=0, ikpt=0, iband=0)[source]#

Read plane-wave coefficients for one band from the VASP WAVECAR file.

Parameters:

data_controller (DataController) – Object providing data_arrays and data_attributes. Required attributes: nkpnts, nbnds, recl, wfc_prec, fpath. Required arrays: nplws.
ispin (int, optional) – Spin index (default 0).
ikpt (int, optional) – Zero-based k-point index (default 0).
iband (int, optional) – Zero-based band index (default 0).

Returns:

Plane-wave coefficients for the specified state.

Return type:

np.ndarray, complex

PAOFLOW.projection.do_atwfc_proj.read_VASP_wfc(data_controller, ik, ispin)[source]#

Read VASP WAVECAR wavefunction and return orthonormalised coefficients with k+G info.

Parameters:

data_controller (DataController) – Object providing data_arrays and data_attributes. Required attributes: dftSO, nbnds, nspin, fpath. Required arrays: nplws, b_vectors, kpnts.
ik (int) – Zero-based k-point index.
ispin (int) – Spin index.

Returns:

gkspace (dict) – G-space descriptor with keys 'xk', 'igwx', 'mill', 'bg', 'gamma_only'.
wfc (dict) – Wavefunction data with keys 'wfc' (orthonormalised coefficients), 'npol', 'nbnd', 'ispin'.

PAOFLOW.projection.do_atwfc_proj.calc_gvec_VASP(data_controller, ikpt=0)[source]#

Compute the G-vector set for a VASP k-point satisfying the energy cutoff.

Parameters:

data_controller (DataController) – Object providing data_arrays and data_attributes. Required attributes: ecutwfc, dftSO. Required arrays: kpnts, nplws, b_vectors, ngrid.
ikpt (int, optional) – Zero-based k-point index (default 0).

Returns:

Miller indices of the G-vectors satisfying \(|\mathbf{k}+\mathbf{G}|^2/2 < E_{\rm cut}\).

Return type:

np.ndarray, shape (nplw, 3), int

Raises:

ValueError – If the number of computed G-vectors does not match nplws[ikpt].

PAOFLOW.projection.do_atwfc_proj.tesseral_to_ylm_matrix(l)[source]#

Per-shell unitary mapping real tesseral harmonics to complex Y_lm.

Returns an (2l+1, 2l+1) complex matrix U such that Y_l^m = sum_k U[m_idx, k] * T_l^k where:

T_l^k are the real cubic harmonics in the local order [m=0, 1c, 1s, 2c, 2s, 3c, 3s] truncated to 2l+1 entries (PAOFLOW’s ylmg convention);
Y_l^m are complex spherical harmonics in the local order [m=0, +1, -1, +2, -2, +3, -3] truncated to 2l+1 entries (PAOFLOW’s ylmgc convention).

Derived numerically from calc_ylmg_complex_0() so it inherits the non-standard odd-\(|m|\) signs. l must be <= 3.

PAOFLOW.projection.do_atwfc_proj.clebsch_jm_matrix(l)[source]#

Per-shell Clebsch-Gordan map (m_l, sigma) -> (j, m_j).

Returns an (2(2l+1), 2(2l+1)) complex matrix C such that chi_{j, m_j} = sum_{m_l, sigma} C[jm_idx, (m_l, sigma)] * |Y_l^{m_l}, sigma> where:

the row index jm_idx runs 0..2(2l+1)-1 in assign_jm()’s local order (j=l-1/2 sub-block first, then j=l+1/2, each with increasing m_j);
the column index is (m_l, sigma) flattened as m_l + (2l+1) * sigma with sigma in {0=up, 1=down} and m_l in PAOFLOW’s local Y_lm order [m=0, +1, -1, ...].

Derived numerically from calc_ylmg_so(). l must be <= 3.