PAOFLOW.projection.do_atwfc_proj#

Attributes#

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_basis_from_sources(data_controller, pseudo_labels)

Basis with the shells of arry['configuration'] taken from two sources, atom by atom.

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[, orthonormalize])

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

loewdin_orthonormalize(wfc)

Symmetric (Loewdin) orthonormalisation of the DFT bands, (S^-1/2)^* wfc.

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.

loewdin_factor(ovp)

The matrix X that Loewdin-orthonormalises functions with Gram matrix ovp.

ortho_atwfc_k(atwfc_k[, overlap])

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

augmented_proj_k(data_controller, augmentation, basis, ...)

Projections and atomic-orbital overlap at a k-point in the augmented metric.

calc_proj_k(data_controller, basis, ik, ispin)

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

calc_proj_and_ovlp_k(data_controller, basis, ik, ispin)

Compute projections and the raw (pre-orthogonalisation) overlap 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[, orthonormalize])

Read VASP WAVECAR wavefunction coefficients with the k+G info of the k-point.

read_dft_wfc(data_controller, ik, ispin[, orthonormalize])

Wavefunction coefficients of one k-point and spin from the DFT code of the run.

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 (list of dict) – Pseudo-orbitals (label, occ, wfc) of the UPF (QE) or of the POTCAR dataset (VASP, PAOFLOW.inputs.pseudopotentials).

  • pseudo (str) – Filename of the UPF pseudopotential (QE) or title of the POTCAR dataset (VASP).

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_basis_from_sources(data_controller, pseudo_labels)[source]#

Basis with the shells of arry['configuration'] taken from two sources, atom by atom.

The shells listed in pseudo_labels[element] come from the PP_PSWFC pseudo-orbitals of the UPF (the pseudo-atom’s own solutions, consistent with the augmented metric of ultrasoft / PAW pseudopotentials), the others from basispath/<elem>/<shell>.dat. The records are ordered atom by atom in the order of arry['configuration'][element], as the symmetry expansion (pao_sym) and arry['shells'] require. When a species mixes the two sources its pseudo-orbitals are resampled (cubic spline) on the radial mesh of its tables, so that every shell of a species shares one mesh (the position-dipole tables of hamiltonian/position_dipoles.py require it).

Parameters:
  • data_controller (DataController) – Required arrays: atoms, tau, species, configuration; attributes ecutrho, omega, verbose, dftSO, fpath, basispath.

  • pseudo_labels (dict) – {element: [shell labels taken from the UPF]}.

Returns:

Raises:

NotImplementedError – With spin-orbit coupling (the jm bookkeeping of a mixed set is not implemented).

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, orthonormalize=True)[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).

  • orthonormalize (bool, optional) – Loewdin-orthonormalise the bands with the plain plane-wave overlap (default). Pass False when the overlap operator of the pseudopotentials is applied explicitly (ultrasoft / PAW, PAOFLOW.projection.augmentation): the stored coefficients are then used as they are, since they are orthonormal in the augmented metric.

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.loewdin_orthonormalize(wfc)[source]#

Symmetric (Loewdin) orthonormalisation of the DFT bands, (S^-1/2)^* wfc.

Parameters:

wfc (array_like, shape (nbnd, npw)) – Plane-wave coefficients (rows = bands).

Returns:

Orthonormal rows spanning the same space.

Return type:

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

Notes

The overlap is a single Hermitian GEMM rather than an nbnd**2 Python loop, and the inverse square root reuses the eigendecomposition instead of calling sqrtm (~13x faster overall at nbnd = 400). See ortho_atwfc_k() for the same identity: solve(sqrtm(ovp).T, wfc) == (ovp^-1/2).conj() @ wfc for Hermitian ovp.

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.loewdin_factor(ovp)[source]#

The matrix X that Loewdin-orthonormalises functions with Gram matrix ovp.

Parameters:

ovp (np.ndarray, shape (n, n), complex) – Hermitian overlap matrix \(O_{ij} = \langle i | j \rangle\) (plain or augmented).

Returns:

X = (O^{-1/2})^*: with the functions as rows of f, X @ f are the orthonormal combinations \(\tilde f_i = \sum_j (O^{-1/2})_{ji} f_j\), whose Gram matrix X^* @ ovp @ X^T is the identity.

Return type:

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

Notes

Symmetric (Loewdin) orthogonalisation via eigh on the Hermitian overlap, which is faster and more stable than scipy.linalg.sqrtm on a general complex matrix. The original behaviour is oatwfc = solve(X.T, atwfc) with X = sqrtm(ovp); for a Hermitian X this equals (ovp^{-1/2}).conj() @ atwfc, built from the eigendecomposition as ovp^{-1/2} = U Λ^{-1/2} U^H and (ovp^{-1/2})^* = U^* Λ^{-1/2} U^T.

PAOFLOW.projection.do_atwfc_proj.ortho_atwfc_k(atwfc_k, overlap=None)[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().

  • overlap (np.ndarray, shape (natwfc, natwfc), optional) – Gram matrix to orthonormalise with instead of the plain plane-wave one, e.g. the augmented \(\langle\phi_i|S|\phi_j\rangle\) of ultrasoft / PAW pseudopotentials.

Returns:

Orthonormalised wavefunctions satisfying \(\langle i | j \rangle = \delta_{ij}\) in the metric of overlap.

Return type:

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

Raises:

RuntimeError – If the orthonormalisation residual exceeds 1e-4.

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

Projections and atomic-orbital overlap at a k-point in the augmented metric.

The ultrasoft / PAW analogue of calc_proj_k(): the stored pseudo-wavefunctions are used as they are (they are orthonormal in the metric S), the atomic orbitals are Loewdin-orthonormalised with \(\langle\phi|S|\phi\rangle\) and the projections are \(\langle\tilde\phi_i|S|\psi_n\rangle\), as in projwfc.x.

Parameters:
Returns:

  • proj_k (np.ndarray, shape (nbnd, natwfc), complex) – Projections \(\langle\psi_{n\mathbf k}|S|\tilde\phi_i\rangle^*\) (same layout as calc_proj_k()).

  • Sk (np.ndarray, shape (natwfc, natwfc), complex) – Augmented overlap of the raw atomic orbitals, \(\langle\phi_\mu|S|\phi_\nu\rangle\).

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_proj_and_ovlp_k(data_controller, basis, ik, ispin)[source]#

Compute projections and the raw (pre-orthogonalisation) overlap at a k-point.

Identical to calc_proj_k() but additionally returns the non-orthogonal atomic-orbital overlap matrix

\[S_{\mu\nu}(\mathbf{k}) = \langle \phi_\mu(\mathbf{k}) | \phi_\nu(\mathbf{k}) \rangle\]

computed from the raw (un-orthogonalised) atomic wavefunctions in G-space. This is the same overlap that projwfc.x writes to atomic_proj.xml when lwrite_overlaps = .true. (with ultrasoft / PAW pseudopotentials both are taken in the augmented metric, see augmented_proj_k()).

Parameters:
Returns:

  • proj_k (np.ndarray, shape (nbnd, natwfc), complex) – Projections \(\langle \psi_{n\mathbf{k}} | \phi_i \rangle\).

  • Sk (np.ndarray, shape (natwfc, natwfc), complex) – Raw (non-orthogonal) atomic-orbital overlap matrix.

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, orthonormalize=True)[source]#

Read VASP WAVECAR wavefunction coefficients with the k+G info of the k-point.

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.

  • orthonormalize (bool, optional) – Loewdin-orthonormalise the bands with the plain plane-wave overlap (default). Pass False when the PAW overlap operator of the POTCAR datasets is applied explicitly (PAOFLOW.projection.augmentation): the stored coefficients are then used as they are, since VASP writes them orthonormal in the augmented metric.

Returns:

  • gkspace (dict) – G-space descriptor with keys 'xk', 'igwx', 'mill', 'bg', 'gamma_only'.

  • wfc (dict) – Wavefunction data with keys 'wfc' (coefficients, rows = bands; with spin-orbit coupling the two spinor components are concatenated, upper then lower), 'npol', 'nbnd', 'ispin'.

PAOFLOW.projection.do_atwfc_proj.read_dft_wfc(data_controller, ik, ispin, orthonormalize=True)[source]#

Wavefunction coefficients of one k-point and spin from the DFT code of the run.

Parameters:
  • data_controller (DataController) – Required attribute dft ('QE' or 'VASP') and what read_QE_wfc() or read_VASP_wfc() need.

  • ik (int) – Zero-based k-point index.

  • ispin (int) – Spin index.

  • orthonormalize (bool, optional) – Loewdin-orthonormalise the bands with the plain overlap (default); False keeps the stored coefficients (augmented metric).

Returns:

gkspace, wfc – As read_QE_wfc() ('xk', 'bg' in bohr^-1, 'mill' of shape (3, npw) for both codes).

Return type:

dict, dict

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.