PAOFLOW.elphon.phonon_assisted_absorption#
Phonon-assisted (indirect) optical absorption from the PAO electron-phonon route.
Second-order (photon + phonon) absorption of an indirect-gap semiconductor,
following EPW’s lindabs (indabs.f90; Noffsinger et al., Phys. Rev. Lett.
108, 167402 (2012)), with every ingredient interpolated in the PAO basis:
the electron-phonon vertex
g(R_e, R_p)built from EPW’s coarse Bloch couplings (prepare_dense_vertex());the electrons and the velocity matrix elements on the dense k-grid (
precompute_dense_electrons(),band_velocities()), in the same gauge as the band-basis coupling (band_vertex()), so the two second-order paths interfere correctly;the phonons on the dense q-grid (EPW force constants).
The direct (vertical) absorption of EPW’s dirabs is computed alongside, on the
same velocities. All quantities are in Rydberg atomic units internally; the
public driver takes and returns electron-volts.
Attributes#
Functions#
|
Fermi-Dirac occupation |
|
Bose-Einstein occupation |
|
Normalised Gaussian |
|
Normalised Lorentzian |
|
Phonon-assisted |
|
Direct (vertical) |
|
Charge-neutral (intrinsic) Fermi level at each temperature. |
|
Temperature-dependent band gap of the Varshni form. |
|
Varshni temperature dependence as a rigid shift of a Hamiltonian's own gap. |
|
Rigid conduction-band shift at each temperature. |
|
Velocity matrix elements of the scissor-corrected Hamiltonian. |
|
Apply a scissor to an independent-particle dielectric function. |
|
Indirect and direct gaps of a PAO Hamiltonian on a dense k-grid. |
|
Absorption coefficient |
|
Phonon-assisted and direct optical absorption with dense k and q interpolation. |
|
Spectral and total hemispherical emissivity of a slab at each temperature. |
|
Shift (eV) of an external direct dielectric function at each temperature. |
|
Onset of an absorption spectrum: lowest energy where |
|
Warn when an external direct dielectric function does not match the Hamiltonian's direct gap. |
|
Real refractive index of a dielectric function, |
|
Read the diagonal dielectric function written by PAOFLOW's |
|
Write the thermal-emissivity spectra and totals. |
|
Write the absorption spectra in EPW's file layout plus an |
Module Contents#
- PAOFLOW.elphon.phonon_assisted_absorption.EPW_ETAS_EV = (0.001, 0.002, 0.005, 0.01, 0.02, 0.05, 0.1, 0.2, 0.5)[source]#
- PAOFLOW.elphon.phonon_assisted_absorption.fermi_occupation(energy, temperature)[source]#
Fermi-Dirac occupation
1 / (1 + exp(e / T))(EPWwgauss(-e/T, -99)).- Parameters:
energy (ndarray) – Energies relative to the Fermi level (same units as
temperature).temperature (float) –
k_B T;0gives a step function.
- Returns:
Occupations, same shape as
energy.- Return type:
ndarray
- PAOFLOW.elphon.phonon_assisted_absorption.bose_occupation(energy, temperature)[source]#
Bose-Einstein occupation
1 / (exp(w / T) - 1)for positiveenergy.- Parameters:
energy (ndarray) – Phonon energies (same units as
temperature), positive.temperature (float) –
k_B T;0gives zero occupation.
- Returns:
Occupations, same shape as
energy.- Return type:
ndarray
- PAOFLOW.elphon.phonon_assisted_absorption.gaussian_delta(x, sigma)[source]#
Normalised Gaussian
exp(-(x/sigma)^2) / (sigma sqrt(pi))(EPWw0gauss).
- PAOFLOW.elphon.phonon_assisted_absorption.lorentzian_delta(x, sigma)[source]#
Normalised Lorentzian
(sigma / pi) / (sigma^2 + x^2).
- PAOFLOW.elphon.phonon_assisted_absorption.indirect_absorption_kernel(energy_k, energy_kq, velocity_k, velocity_kq, coupling, phonon_energy, temperatures, photon_energy, etas, degauss, fsthick, eps_acoustic, weight=1.0, spin_degeneracy=2.0, occupation_tol=1e-12, pair_block=2048, fermi_levels=None)[source]#
Phonon-assisted
Im eps(omega)from one block of(k, k+q)pairs at one q.- Parameters:
energy_k (ndarray, shape
(nk, nband)) – Band energies atkandk+qrelative to the Fermi level (Ry).energy_kq (ndarray, shape
(nk, nband)) – Band energies atkandk+qrelative to the Fermi level (Ry).velocity_k (ndarray, shape
(nk, 3, nband, nband), complex) – Velocity matrix elements<m|v_alpha|n>atkandk+q(Ry bohr), in the gauge ofcoupling.velocity_kq (ndarray, shape
(nk, 3, nband, nband), complex) – Velocity matrix elements<m|v_alpha|n>atkandk+q(Ry bohr), in the gauge ofcoupling.coupling (ndarray, shape
(nk, nmode, nband, nband), complex) –g_{mn,nu} = <m, k+q|dV_{q nu}|n, k>without \(1/\sqrt{2\omega}\) (Rydberg units;band_vertex()).phonon_energy (ndarray, shape
(nmode,)) – Phonon energies at q (Ry); modes beloweps_acousticare skipped.temperatures (sequence of float) –
k_B Tvalues (Ry).photon_energy (ndarray, shape
(nomega,)) – Photon energies (Ry), positive.etas (sequence of float) – Imaginary broadenings of the intermediate-state denominators (Ry).
degauss (float or ndarray, shape
(nk, nband, nband)) – Smearing of the energy-conserving delta (Ry): one value, or one per(k, i, j)pair (adaptive smearing,pair_widths()).fsthick (float) – Only states with
|e| < fsthickenter as initial or final states (Ry).eps_acoustic (float) – Phonon-energy threshold (Ry).
weight (float, optional) – Multiplies the block sum, e.g.
w_q / (N_k Omega).spin_degeneracy (float, optional) – 2 without spin-orbit coupling (EPW’s
16 pi^2prefactor), 1 with it.occupation_tol (float, optional) – Pairs whose occupation factors
f_i (1 - f_j) + (1 - f_i) f_jstay below this at every temperature are skipped (0keeps all, as EPW).pair_block (int, optional) – Number of
(k, i, j)pairs processed at once (memory control).fermi_levels (sequence of float, optional) – Fermi level of each temperature (Ry) on the energy scale of
energy_k, which only sets the occupations (default 0 for all; thefsthickwindow stays centred on 0).
- Returns:
eps2_gaussian, eps2_lorentzian – Diagonal components of
Im epswith a Gaussian and a Lorentzian delta.- Return type:
ndarray, shape
(ntemp, neta, 3, nomega)
Notes
For an initial state \(i\) at \(\mathbf{k}\), a final state \(j\) at \(\mathbf{k}+\mathbf{q}\) and a phonon \(\nu\), the two time orderings (photon first, phonon first) give the amplitudes
\[S^{a/e}_{1,\alpha} = \sum_m \frac{g_{jm,\nu}\, v^{\alpha}_{mi}(\mathbf{k})} {\varepsilon_{m\mathbf{k}} - \varepsilon_{j\mathbf{k}+\mathbf{q}} \pm \omega_{\mathbf{q}\nu} + i\eta}, \qquad S^{a/e}_{2,\alpha} = \sum_m \frac{v^{\alpha}_{jm}(\mathbf{k}+\mathbf{q})\, g_{mi,\nu}} {\varepsilon_{m\mathbf{k}+\mathbf{q}} - \varepsilon_{i\mathbf{k}} \mp \omega_{\mathbf{q}\nu} + i\eta},\]for phonon absorption (\(a\), upper signs) and emission (\(e\)), and
\[\mathrm{Im}\,\varepsilon_{\alpha\alpha}(\omega) \mathrel{+}= w\, \frac{8\pi^2 g_s}{\omega^2} \sum_{ij\nu} P^{a/e}\, \frac{|S^{a/e}_{1,\alpha} + S^{a/e}_{2,\alpha}|^2}{2\omega_{\mathbf{q}\nu}}\, \delta(\varepsilon_{j\mathbf{k}+\mathbf{q}} - \varepsilon_{i\mathbf{k}} - \omega \mp \omega_{\mathbf{q}\nu}),\]with \(P^a = n f_i (1 - f_j) - (n + 1)(1 - f_i) f_j\) and \(P^e = (n + 1) f_i (1 - f_j) - n (1 - f_i) f_j\) (\(n\) Bose, \(f\) Fermi occupations). \(8\pi^2 g_s = 8\pi^2 e^2\) in Rydberg units for \(g_s = 2\), EPW’s
cfac. As in EPW, a(pair, mode, omega)term is kept when either delta lies within six smearings, and the intermediate states \(m\) run over the bands of the window.
- PAOFLOW.elphon.phonon_assisted_absorption.direct_absorption_kernel(energy_k, velocity_k, temperatures, photon_energy, degauss, fsthick, weight=1.0, spin_degeneracy=2.0, fermi_levels=None, pair_block=2048)[source]#
Direct (vertical)
Im eps(omega)from one block of k-points (EPWdirabs).- Parameters:
energy_k (ndarray, shape
(nk, nband)) – Band energies relative to the Fermi level (Ry).velocity_k (ndarray, shape
(nk, 3, nband, nband), complex) – Velocity matrix elements (Ry bohr).temperatures (sequence of float) –
k_B Tvalues (Ry).photon_energy (ndarray, shape
(nomega,)) – Photon energies (Ry).degauss (float or ndarray, shape
(nk, nband, nband)) – Smearing of the delta (Ry): one value, or one per(k, i, j)pair (adaptive smearing,pair_widths()with a zero q spacing). Smearing of the energy-conserving delta (Ry).fsthick (float) – Energy window around the Fermi level (Ry).
weight (float, optional) – Multiplies the block sum, e.g.
1 / (N_k Omega).spin_degeneracy (float, optional) – 2 without spin-orbit coupling, 1 with it.
fermi_levels (sequence of float, optional) – Fermi level of each temperature (Ry), as in
indirect_absorption_kernel().pair_block (int, optional) – Transitions per batch: the delta functions are
(pair_block, nomega)arrays, which bounds the memory of wide photon grids and many bands.
- Returns:
eps2_gaussian, eps2_lorentzian
- Return type:
ndarray, shape
(ntemp, 3, nomega)
Notes
\[\mathrm{Im}\,\varepsilon_{\alpha\alpha}(\omega) \mathrel{+}= w\, \frac{8\pi^2 g_s}{\omega^2} \sum_{ij} (f_i - f_j)\, |v^{\alpha}_{ji}|^2\, \delta(\varepsilon_j - \varepsilon_i - \omega),\]keeping a term when the delta lies within six smearings, as EPW.
- PAOFLOW.elphon.phonon_assisted_absorption.intrinsic_fermi_levels(energies, temperatures, nelec, spin_degeneracy=2.0, niter=200)[source]#
Charge-neutral (intrinsic) Fermi level at each temperature.
- Parameters:
energies (ndarray, shape
(nk, nband)) – Band energies of all bands on a uniform k-grid (any energy unit).temperatures (sequence of float) –
k_B Tvalues, same unit asenergies(positive).nelec (float) – Valence electrons per cell.
spin_degeneracy (float, optional) – 2 without spin-orbit coupling, 1 with it.
niter (int, optional) – Bisection steps.
- Returns:
Fermi levels \(\mu(T)\) on the scale of
energies.- Return type:
ndarray, shape
(ntemp,)
Notes
Solves the charge neutrality
\[\frac{g_s}{N_k} \sum_{n\mathbf{k}} f\left(\frac{\varepsilon_{n\mathbf{k}} - \mu}{k_B T}\right) = N_{el}\]by bisection, so the thermally excited electrons and holes balance; in a semiconductor \(\mu(T)\) moves from mid-gap toward the band with the smaller density of states.
- PAOFLOW.elphon.phonon_assisted_absorption.varshni_gap(e0_ev, alpha_ev_per_k=0.000473, beta_k=636.0)[source]#
Temperature-dependent band gap of the Varshni form.
- Parameters:
- Returns:
T (K) -> E_g(T)in eV, thetarget_gap_evofphonon_assisted_absorption_dense_q().- Return type:
callable
Notes
\[E_g(T) = E_0 - \frac{\alpha T^2}{T + \beta}.\]
- PAOFLOW.elphon.phonon_assisted_absorption.varshni_shift(alpha_ev_per_k=SILICON_VARSHNI[1], beta_k=SILICON_VARSHNI[2])[source]#
Varshni temperature dependence as a rigid shift of a Hamiltonian’s own gap.
- Parameters:
- Returns:
T (K) -> Delta(T)in eV, thescissor_evofphonon_assisted_absorption_dense_q()andcarrier_scattering_dense_q().- Return type:
callable
Notes
\[\Delta(T) = -\frac{\alpha T^2}{T + \beta}, \qquad \Delta(0) = 0,\]i.e.
varshni_gap()with \(E_0 = 0\). Use it when the Hamiltonian already has the 0 K gap (an eACBN0 PAO Hamiltonian): the band energies then follow \(E_g^{H} + \Delta(T)\) without a 0 K scissor.
- PAOFLOW.elphon.phonon_assisted_absorption.scissor_per_temperature(temps_k, dft_gap_ev, scissor_ev=None, target_gap_ev=None)[source]#
Rigid conduction-band shift at each temperature.
- Parameters:
temps_k (sequence of float) – Temperatures (K).
dft_gap_ev (float) – Indirect gap of the PAO spectrum on the dense grid (eV).
scissor_ev (float or callable, optional) – Explicit shift (eV), the same at every temperature, or
T (K) -> Delta(T)(varshni_shift()) relative to the Hamiltonian’s own gap.target_gap_ev (float or callable, optional) – Gap to reproduce (eV), fixed or
T (K) -> E_g(T)(varshni_gap()).
- Returns:
Scissor \(\Delta(T) = E_g^{target}(T) - E_g^{DFT}\) (eV); zeros when neither
scissor_evnortarget_gap_evis given.- Return type:
ndarray, shape
(ntemp,)- Raises:
ValueError – If both
scissor_evandtarget_gap_evare given.
- PAOFLOW.elphon.phonon_assisted_absorption.scissor_velocities(velocity, energies, scissor, conduction, mode='renormalized')[source]#
Velocity matrix elements of the scissor-corrected Hamiltonian.
- Parameters:
velocity (ndarray, shape
(nk, 3, nband, nband), complex) – Kohn-Sham (PAO) band velocities.energies (ndarray, shape
(nk, nband)) – Kohn-Sham band energies (same unit asscissor).scissor (float) – Rigid shift of the conduction bands.
conduction (ndarray of bool, shape
(nband,)) – Conduction-band mask.mode ({'renormalized', 'ks'}, optional) –
'renormalized'(default) applies the Levine-Allan factor below;'ks'keeps the Kohn-Sham velocities (EPW’sscissor).
- Returns:
Velocities to use with the shifted energies.
- Return type:
ndarray, shape
(nk, 3, nband, nband), complex- Raises:
ValueError – For an unknown
mode.
Notes
A scissor operator \(H_\Delta = H + \Delta\, P_c\) (\(P_c\) the conduction projector) leaves the position matrix elements unchanged, so the velocity \(i[H_\Delta, \mathbf r]\) of a valence-conduction pair scales with its transition energy (Levine and Allan, Phys. Rev. Lett. 63, 1719 (1989); Del Sole and Girlanda, Phys. Rev. B 48, 11789 (1993)):
\[v^{\Delta}_{mn} = v_{mn}\, \frac{\varepsilon_m - \varepsilon_n \pm \Delta}{\varepsilon_m - \varepsilon_n},\]while intraband and within-manifold elements (e.g. the free-carrier velocities) are unchanged. The direct absorption then shifts rigidly.
- PAOFLOW.elphon.phonon_assisted_absorption.scissor_shift_dielectric(omega_ev, eps1, eps2, scissor_ev, mode='renormalized', onset_ev=None)[source]#
Apply a scissor to an independent-particle dielectric function.
- Parameters:
omega_ev (ndarray, shape
(nomega,)) – Uniform photon-energy grid (eV).eps1 (ndarray, shape
(nomega,)) – Real (vacuum 1 included) and imaginary parts.eps2 (ndarray, shape
(nomega,)) – Real (vacuum 1 included) and imaginary parts.scissor_ev (float) – Rigid conduction-band shift (eV).
mode ({'renormalized', 'ks'}, optional) – Velocity convention of
scissor_velocities().onset_ev (float, optional) – Absorption onset (direct gap) of the unshifted spectrum, used with
mode='ks'and a negative scissor (defaultdielectric_onset_ev()ofeps2).
- Returns:
eps1, eps2 – Scissor-corrected real and imaginary parts.
- Return type:
ndarray, shape
(nomega,)- Raises:
ValueError – For an unknown
mode, or a negative scissor that closes the direct gap (mode='ks').
Notes
With renormalized velocities the interband spectrum shifts rigidly, \(\varepsilon_2^\Delta(\omega) = \varepsilon_2(\omega - \Delta)\); with Kohn-Sham velocities it is also scaled by \((\omega - \Delta)^2/\omega^2\). The real part changes by the Kramers-Kronig transform of the change of \(\varepsilon_2\) (so the contribution of the spectrum beyond the grid is kept); weight shifted past the end of the grid is dropped.
The Kohn-Sham factor is the ratio of the transition energies before and after the shift, exact for the transitions themselves. Below the onset only the broadening tail of the spectrum remains (Drude-Lorentz
deltaofdielectric_tensor); for a negative scissor the factor would diverge there as \(\omega \to 0\), so below the shifted onset \(E_{on} + \Delta\) the tail is scaled like the edge transitions that produce it, by \(E_{on}^2/(E_{on} + \Delta)^2\). Positive scissors keep the plain factor (it is bounded).
- PAOFLOW.elphon.phonon_assisted_absorption.pao_band_gaps(HRs, at, nk_dense, nelec, orbital_positions=None, spin_degeneracy=2.0, ispin=0)[source]#
Indirect and direct gaps of a PAO Hamiltonian on a dense k-grid.
- Parameters:
HRs (ndarray, shape
(nawf, nawf, n1, n2, n3, nspin), complex) – PAO Hamiltonian (eV), e.g. of an eACBN0 (DFT+U+V, ortho-atomic) run.at (ndarray, shape
(3, 3)) – Direct lattice vectors (rows, alat units).nk_dense (int) – Dense grid per axis (Wigner-Seitz interpolation, as the absorption).
nelec (float) – Valence electrons.
orbital_positions (ndarray, shape
(nawf, 3), optional) – PAO orbital centres (pair-resolved Wigner-Seitz sums).spin_degeneracy (float, optional) – 2 without spin-orbit coupling, 1 with it.
ispin (int, optional) – Spin channel.
- Returns:
indirect_gap_ev,direct_gap_ev,vbm_ev,cbm_ev(on the energy scale ofHRs). Thetarget_gap_evof a scissor-correctedphonon_assisted_absorption_dense_q()isindirect_gap_evof the reference Hamiltonian.- Return type:
- PAOFLOW.elphon.phonon_assisted_absorption.absorption_coefficient(photon_energy_ev, eps2, refractive_index=3.4)[source]#
Absorption coefficient
alpha = omega Im eps / (n_r c)in cm^-1.- Parameters:
photon_energy_ev (ndarray, shape
(nomega,)) – Photon energies (eV).eps2 (ndarray, shape
(..., nomega)) – Imaginary part of the dielectric function.refractive_index (float or ndarray, shape
(nomega,), optional) – Real refractive index (default 3.4, the constant of the EPW tutorial for Si).
- Returns:
Absorption coefficient (cm^-1).
- Return type:
ndarray, shape
(..., nomega)
- PAOFLOW.elphon.phonon_assisted_absorption.phonon_assisted_absorption_dense_q(A, HRs, kpts_cryst, bg, at, alat, cell_volume, coupling_dir, qgrid_coarse, ng, *, masses_amu, nelec, nk_dense=12, nq_dense=6, omega_ev=(0.05, 3.0, 0.05), temps_k=(300.0,), degauss_ev=0.05, adaptive_smearing=None, min_degauss_ev=0.001, fsthick_ev=4.0, fermi_energy_ev=None, etas_ev=EPW_ETAS_EV, eps_acoustic_cm=0.1, refractive_index=3.4, nonlocal_velocity=None, position_dipoles=None, position_dipole_level='full', kk_omega_max_ev=None, kk_degauss_ev=0.1, scissor_ev=None, target_gap_ev=None, scissor_velocity='renormalized', screening_eps=None, screening_eps_dft=None, spin_degeneracy=2.0, sym_rots=None, tau_cryst=None, species=None, orbital_positions=None, ispin=0, kblock=512, comm=None, allow_missing_long_range=False, coupling_source='epw', save_dir=None, pseudo_dir=None, prefix=None, basis='auto', unfold='full', basis_shells=None, unfold_tol=1e-06, cache_dir=None, cache_tag=None, long_range=None)[source]#
Phonon-assisted and direct optical absorption with dense k and q interpolation.
- Parameters:
A (ndarray, shape
(nbnd, nawf, nk), complex) – PAO projections on the coarse (EPW nscf) k-grid.HRs (ndarray, shape
(nawf, nawf, n1, n2, n3, nspin), complex) – PAO Hamiltonian (eV).kpts_cryst (ndarray, shape
(nk, 3)) – Coarse k-points (crystal coordinates).bg (ndarray, shape
(3, 3)) – Reciprocal (rows, 2 pi/alat) and direct (rows, alat) lattice vectors.at (ndarray, shape
(3, 3)) – Reciprocal (rows, 2 pi/alat) and direct (rows, alat) lattice vectors.alat (float) – Lattice parameter (bohr).
cell_volume (float) – Unit-cell volume (bohr^3).
coupling_dir (str) – EPW directory with the
.epbfiles.qgrid_coarse (sequence of int) – Coarse (ph.x) q-grid.
ng (sequence of int) – Coarse k-grid.
masses_amu (ndarray, shape
(nat,)) – Atomic masses (amu), one per atom.nelec (float) – Valence electrons (locates the gap for the mid-gap Fermi level).
nk_dense (int, optional) – Dense k- and q-grids per axis;
nk_densemust be a multiple ofnq_dense(EPW tutorial: 12 and 6).nq_dense (int, optional) – Dense k- and q-grids per axis;
nk_densemust be a multiple ofnq_dense(EPW tutorial: 12 and 6).omega_ev (tuple(float, float, float), optional) – Photon energies
(min, max, step)(eV), EPWomegamin/omegamax/omegastep.temps_k (sequence of float, optional) – Temperatures (K).
degauss_ev (float, optional) – Smearing of the energy-conserving delta (eV), EPW
degaussw.adaptive_smearing (float, optional) – Adaptive smearing (Yates et al.; 0.7 is the usual Gaussian prefactor): the width of every
(k, i, j)pair isadaptive_smearing * sqrt(|v_i(k) - v_j(k+q)|^2 dk^2 + |v_j(k+q)|^2 dq^2), floored atmin_degauss_ev, from the group velocities and the spacings of the dense k- and q-grids (pair_widths()); the direct term uses the k part alone.Nonekeeps the fixeddegauss_ev; the Kramers-Kronig direct term keepskk_degauss_ev.min_degauss_ev (float, optional) – Floor of the adaptive widths (eV).
fsthick_ev (float, optional) – Window around the Fermi level for initial, final and intermediate states (eV), EPW
fsthick.fermi_energy_ev (float or 'intrinsic', optional) – Fermi level on the energy scale of
HRs(eV);Noneputs it mid-gap (EPWefermi_read) and'intrinsic'uses the charge-neutral level of each temperature (intrinsic_fermi_levels()), which sets the density of thermally excited carriers (free-carrier absorption). Thefsthickwindow stays centred mid-gap either way.etas_ev (sequence of float, optional) – Intermediate-state broadenings (eV); EPW’s nine values by default.
eps_acoustic_cm (float, optional) – Phonons below this energy (cm^-1) are skipped (EPW
eps_acoustic).refractive_index (float, ndarray, (omega_ev, n) pair or None, optional) – Real refractive index of
alpha = omega Im eps / (n c): a constant (default 3.4, the EPW tutorial value for Si;Nonemeans the same),non the photon grid, or a pair(omega_ev, n)interpolated on it, e.g.external_refractive_index()of thedielectric_tensorrun that providesdirect_dielectric. The emissivity does not use it (it works with the full dielectric function).nonlocal_velocity (None) – Removed (October 2026): the non-local pseudopotential term double counts \(V_{\rm NL}\), which the PAO Hamiltonian already contains; any value other than
Noneraises.position_dipoles (DataController, optional) – When given, adds the position dipoles of the PAO orbitals to the velocity operator, \(i[H, \mathbf d(\mathbf k)]\) (
position_dipole_operator()): the intra-atomic \(s\)-\(p\), \(p\)-\(d\) dipoles that \(\partial_{\mathbf k} H\) lacks, e.g. the direct transitions between the conduction bands of doped Si.position_dipole_level ({'full', 'intra-atomic'}, optional) – Löwdin-orthogonalised dipoles of the whole basis (default) or the on-site blocks of the atomic orbitals only.
kk_omega_max_ev (float, optional) – Also compute the direct
Im epsover all PAO bands on[0, kk_omega_max_ev](same step), the input of the Kramers-Kronig real part used bythermal_emissivity(). About 10 eV: the PAO spectrum above that includes transitions into poorly projected (shifted) bands that violate the f-sum rule (checkf_sum_ratioofthermal_emissivity()).kk_degauss_ev (float, optional) – Smearing (eV) of that wide-range direct term (default 0.1). The real part is smooth, but the Kramers-Kronig transform of an under-sampled, weakly smeared spectrum oscillates (even below zero) and spoils the reflectivity; it also smooths the direct term the emissivity uses above the gap.
scissor_ev (float or callable, optional) – Rigid shift (eV) of the conduction bands (scissor operator), or
T (K) -> Delta(T)(varshni_shift()): the Varshni temperature dependence on top of the Hamiltonian’s own gap, for aHRsthat already has the 0 K gap (eACBN0 electrons, see Notes).target_gap_ev (float or callable, optional) – Indirect gap (eV) to reproduce instead of the DFT one: a number (e.g. the experimental gap, or the dense-grid gap of an eACBN0 PAO Hamiltonian from
pao_band_gaps()) orT (K) -> E_g(T)(varshni_gap()). The scissor is \(\Delta(T) = E_g^{target}(T) - E_g^{DFT}\); the coupling and the wavefunctions stay those of the DFT (DFPT) calculation.scissor_velocity ({'renormalized', 'ks'}, optional) – Velocities of the scissor-corrected Hamiltonian (
scissor_velocities()): Levine-Allan renormalized (default) or the Kohn-Sham ones (EPW’sscissor).screening_eps (float, optional) – Static dielectric constant that should screen the coupling (e.g. the measured one, 11.94 for Si). When given, every matrix element is rescaled by \(\epsilon^{DFT}(|q|)/\epsilon^{target}(|q|)\) (Poncé et al. 2018, Resta model;
coupling_screening).None(default) keeps the DFPT screening.screening_eps_dft (float, optional) – Dielectric constant of the DFPT run that screened the coupling;
Nonetakes the isotropic average of the tensor in the.epbfiles.spin_degeneracy (float, optional) – 2 without spin-orbit coupling, 1 with it.
sym_rots (optional) – Point-group rotations (
read_nscf's_cryst'), atomic positions and labels; fold the dense q-grid to its irreducible wedge. Only the polarisation average is then exact, and it is returned in all three components ofeps2_indirect; passsym_rots=Nonefor the resolved diagonal components.tau_cryst (optional) – Point-group rotations (
read_nscf's_cryst'), atomic positions and labels; fold the dense q-grid to its irreducible wedge. Only the polarisation average is then exact, and it is returned in all three components ofeps2_indirect; passsym_rots=Nonefor the resolved diagonal components.species (optional) – Point-group rotations (
read_nscf's_cryst'), atomic positions and labels; fold the dense q-grid to its irreducible wedge. Only the polarisation average is then exact, and it is returned in all three components ofeps2_indirect; passsym_rots=Nonefor the resolved diagonal components.orbital_positions (ndarray, shape
(nawf, 3), optional) – PAO orbital centres (pair-resolved Wigner-Seitz sums and the intersite position term of the velocity);tau_crystis then required.ispin (int, optional) – Spin channel of
HRs.kblock (int, optional) – Dense k-points per task.
comm (mpi4py communicator, optional) –
MPI.COMM_WORLDby default; the(q, k-block)tasks are distributed over its ranks.allow_missing_long_range (bool, optional) – Run a polar material without the long-range dipole term instead of raising.
coupling_source ({'epw', 'dfpt'}, optional) –
'epw'reads EPW’s.epbfiles fromcoupling_dir;'dfpt'computes the coarse vertex from theph.xoutputs incoupling_dirand the nscf wavefunctions ofsave_dir(prepare_dense_vertex()).save_dir –
coupling_source='dfpt'and cache options ofprepare_dense_vertex().pseudo_dir –
coupling_source='dfpt'and cache options ofprepare_dense_vertex().prefix –
coupling_source='dfpt'and cache options ofprepare_dense_vertex().basis –
coupling_source='dfpt'and cache options ofprepare_dense_vertex().unfold –
coupling_source='dfpt'and cache options ofprepare_dense_vertex().basis_shells –
coupling_source='dfpt'and cache options ofprepare_dense_vertex().unfold_tol –
coupling_source='dfpt'and cache options ofprepare_dense_vertex().cache_dir –
coupling_source='dfpt'and cache options ofprepare_dense_vertex().cache_tag –
coupling_source='dfpt'and cache options ofprepare_dense_vertex().long_range (LongRangeModel, optional) – Polar crystals: subtract the analytic dipole/quadrupole coupling on the coarse grid and restore it at every dense q (
LongRangeModel); the phonons must be built with the same model (phonon_at_q=Noneorphonon_interp_from_dyn()withlong_range).
- Returns:
omega_ev(nomega,);eps2_indirectandeps2_indirect_lorentz(ntemp, neta, 3, nomega);eps2_directandeps2_direct_lorentz(ntemp, 3, nomega);alpha_cm(ntemp, neta, nomega)(direct + indirect, polarisation averaged, Gaussian delta);fermi_energy_ev,indirect_gap_ev,direct_gap_ev,etas_ev,temps_k,nk_dense,nq_dense,bands(window band indices),fermi_levels_ev(ntemp,),scissor_ev,indirect_gap_ev_t,direct_gap_ev_t(ntemp,)(scissor-corrected; the scalarindirect_gap_ev/direct_gap_evare those of the first temperature and*_gap_dft_evthe uncorrected ones),scissor_velocity,coupling_screening('none'or'ponce-resta', then also thescreening_*constants and factors ofsummary()); withkk_omega_max_evalsoomega_kk_evandeps2_direct_wide(ntemp, 3, nomega_kk).- Return type:
- Raises:
ValueError – If the grids are incommensurate or no gap is found for the mid-gap Fermi level, or
screening_epsis given for couplings without a dielectric tensor and noscreening_eps_dft.
Notes
The workflow mirrors EPW’s
lindabs:build
g(R_e, R_p)and the phonon interpolator from the coarse EPW data;diagonalise the PAO Hamiltonian on the dense k-grid and evaluate the band velocities there (one copy per node);
for every irreducible dense q (star-weighted) and every block of dense k, interpolate the coupling, take
k+qon the grid, and accumulateindirect_absorption_kernel();add the direct term,
direct_absorption_kernel(), once.
The irreducible-q reduction leaves the polarisation-averaged spectrum unchanged, but not the individual components (each star is represented by a single orientation of q), so with
sym_rotsthe indirect components are replaced by their average.With
screening_epsthe coupling at each dense q is multiplied by \(\epsilon^{DFT}(|\mathbf q|)/\epsilon^{target}(|\mathbf q|)\), with \(|\mathbf q|\) the shortest image of q. The factor depends on \(|\mathbf q|\) only, so the irreducible-q reduction stays exact. For Si (12.97 -> 11.94) \(|g|^2\) grows by 18 % at \(\Gamma\) and 2 % at X.
- PAOFLOW.elphon.phonon_assisted_absorption.thermal_emissivity(results, thickness_m, angles_deg=(0.0, 30.0, 60.0), ntheta=90, eta_ev=0.05, taper_ev=0.1, direct_dielectric=None, direct_scissor='same')[source]#
Spectral and total hemispherical emissivity of a slab at each temperature.
- Parameters:
results (dict) – Output of
phonon_assisted_absorption_dense_q(), run withfermi_energy_ev='intrinsic'and eitherkk_omega_max_ev(keysomega_kk_ev,eps2_direct_wide) or together withdirect_dielectric.thickness_m (float) – Slab thickness (m);
infgives the opaque half-space.angles_deg (sequence of float, optional) – Emission angles (degrees) of the directional spectra.
ntheta (int, optional) – Polar-angle samples of the hemispherical integral.
eta_ev (float, optional) – Intermediate-state broadening of the phonon-assisted term (closest computed value).
taper_ev (float, optional) – Width (eV) of the cosine taper that switches the phonon-assisted term off just below the direct gap.
direct_dielectric (tuple of ndarray, optional) –
(omega_ev, eps1, eps2)of the direct (independent-particle) dielectric function from a separate, better-converged calculation: PAOFLOW’sdielectric_tensoron the extended basis with the non-local velocity (read_direct_dielectric()).eps1/eps2have shape(nomega_d,)or(ncomp, nomega_d)(averaged);eps1includes the vacuum 1 and the grid (uniform) must coverresults['omega_ev']. When given, the wide-range direct term ofresultsis not used. A scissor ofresults(scissor_ev,scissor_velocity) is applied to it too (scissor_shift_dielectric()), as set bydirect_scissor.direct_scissor ({'same', 'thermal', 'none'}, float or sequence of float, optional) –
Rigid shift of
direct_dielectricat each temperature:'same'(default): the scissorDelta(T)of the run, when the external spectrum shares the gap error of the Hamiltonian (PBE optics with PBE electrons);'thermal': only its temperature-dependent partDelta(T) - Delta(0)(results['scissor_0k_ev']), when the external spectrum already has the right 0 K direct gap and the scissor corrects the indirect gap only (eACBN0 Si: direct gap 3.44 eV, indirect gap 0.22 eV too high);'none': no shift;explicit shifts (eV), one value or one per temperature.
The taper below the direct gap always follows the run’s own (scissor-corrected) direct gap
direct_gap_ev_t, where its phonon-assisted term diverges.
- Returns:
omega_ev(nomega,),temps_k(ntemp,),eps1,eps2,hemispherical_slab,hemispherical_opaque(ntemp, nomega),directional_slab(ntemp, nangle, nomega),total_slab,total_opaque,planck_coverage(ntemp,),thickness_m,angles_deg,eta_ev,direct_source('external'or'kramers-kronig'), withdirect_dielectricalsodirect_scissor(the mode) anddirect_scissor_ev(ntemp,)(the shifts applied to it),direct_onset_ev,direct_gap_h_ev, and, whenresultscarriesnelecandcell_volume_bohr3,f_sum_ratio(ntemp,): the f-sum \(\int \omega\, \varepsilon_2\, d\omega\) of the direct spectrum divided by \(\pi \omega_p^2 / 2\) of all valence electrons (close to 1 for a complete, physical spectrum).- Return type:
- Raises:
NotImplementedError – For a metal (no gap): the intraband (Drude) term is not included.
KeyError – If neither a wide-range direct term nor
direct_dielectricis given, ordirect_scissor='thermal'withoutresults['scissor_0k_ev'].ValueError – If
direct_dielectricdoes not cover the photon-energy grid, or for an unknowndirect_scissor.
Notes
For every temperature \(T\) the polarisation-averaged dielectric function is assembled from a direct part and the phonon-assisted \(\varepsilon_2^{ind}(\omega, T)\), which is tapered off by \(w(\omega)\) just below the direct gap, where its second-order amplitude diverges.
Without
direct_dielectric: \(\varepsilon_2 = \varepsilon_2^{dir} + w\,\varepsilon_2^{ind}\), with the direct term over all PAO bands, and \(\varepsilon_1\) by Kramers-Kronig (kramers_kronig_eps1()).With
direct_dielectric(\(\varepsilon^{ext} = \varepsilon_1^{ext} + i\varepsilon_2^{ext}\)):\[\begin{split}\varepsilon_2 &= w\,(\varepsilon_2^{dir} + \varepsilon_2^{ind}) + (1 - w)\,\varepsilon_2^{ext}, \\ \varepsilon_1 &= \varepsilon_1^{ext} + \mathrm{KK}[w\,\varepsilon_2^{ind}] - 1,\end{split}\]i.e. the external spectrum above the direct gap and for the real part, and this run’s direct term (Gaussian, window bands) plus the phonon-assisted term below it. The broadening tails of the external spectrum (Drude-Lorentz,
deltaofdielectric_tensor) would otherwise add a sub-gap absorption orders of magnitude larger than the phonon-assisted and free-carrier one; \(\varepsilon_1\) is insensitive to that broadening.
The slab absorptance (
slab_directional_absorptance()) is the emissivity by Kirchhoff’s law; its hemispherical average and the Planck-weighted total at the same temperature,\[\varepsilon(T) = \frac{\int \varepsilon(\omega, T)\, B(\omega, T)\, d\omega} {\int B(\omega, T)\, d\omega},\]are taken over the photon-energy grid;
planck_coverageis the fraction of the blackbody spectrum that the grid covers.
- PAOFLOW.elphon.phonon_assisted_absorption.direct_scissor_shifts(results, direct_scissor='same', scissors=None)[source]#
Shift (eV) of an external direct dielectric function at each temperature.
- Parameters:
results (dict) – Output of
phonon_assisted_absorption_dense_q()(scissor_ev,temps_kand, for'thermal',scissor_0k_ev).direct_scissor ({'same', 'thermal', 'none'}, float or sequence of float, optional) – See
thermal_emissivity().scissors (ndarray, optional) – The run’s scissor per temperature (default
results['scissor_ev']).
- Returns:
Shifts (eV);
'same'returns the run’s scissor unchanged.- Return type:
ndarray, shape
(ntemp,)- Raises:
KeyError – For
'thermal'whenresultshas noscissor_0k_ev(outputs of older runs: pass the shifts explicitly,scissor_ev - Delta(0)).ValueError – For an unknown mode or a wrong number of explicit shifts.
- PAOFLOW.elphon.phonon_assisted_absorption.dielectric_onset_ev(omega_ev, eps2, fraction=0.05)[source]#
Onset of an absorption spectrum: lowest energy where
eps2reaches a fraction of its maximum.- Parameters:
omega_ev (ndarray, shape
(nomega,)) – Photon energies (eV).eps2 (ndarray, shape
(nomega,)) – Imaginary part of the dielectric function.fraction (float, optional) – Threshold relative to
max(eps2)(default 5 %: on PAOFLOW’s Si spectra, Drude-Lorentzdelta = 0.1eV, it lands on the direct gap within 0.04 eV).
- Returns:
The onset energy (eV);
nanifeps2has no positive value.- Return type:
- PAOFLOW.elphon.phonon_assisted_absorption.check_direct_dielectric_gap(results, direct_dielectric, tol_ev=0.3, fraction=0.05)[source]#
Warn when an external direct dielectric function does not match the Hamiltonian’s direct gap.
- Parameters:
results (dict) – Output of
phonon_assisted_absorption_dense_q()(usesdirect_gap_dft_ev, the unshifted direct gap of the Hamiltonian, ordirect_gap_evwhen the former is absent).direct_dielectric (tuple of ndarray) –
(omega_ev, eps1, eps2)as read byread_direct_dielectric()(eps2may be(ncomp, nomega); its average is used).tol_ev (float, optional) – Largest accepted difference between the onset of
eps2and the gap.fraction (float, optional) – Onset threshold of
dielectric_onset_ev()(5 % of the maximum: on PAOFLOW’s Si spectrum, Drude-Lorentzdelta = 0.1eV, this lands on the direct gap within 0.01 eV).
- Returns:
onset_ev,direct_gap_evandconsistent(bool).- Return type:
Notes
The external spectrum is shifted only by the scissor \(\Delta(T)\) of the run. A
dielectric_tensorrun of another functional than the one behindHRs(PBE optics with eACBN0 electrons, or the reverse) would be placed at the wrong energy: the gap difference between the two functionals is not a scissor of the run. The Drude-Lorentz tails of the external spectrum make the onset approximate, hence the generous tolerance and a warning rather than an error.
- PAOFLOW.elphon.phonon_assisted_absorption.external_refractive_index(direct_dielectric)[source]#
Real refractive index of a dielectric function,
(omega_ev, n).- Parameters:
direct_dielectric (tuple of ndarray) –
(omega_ev, eps1, eps2)as read byread_direct_dielectric()(eps1/eps2of shape(nomega,)or(ncomp, nomega), averaged).- Returns:
omega_ev, n – Photon energies and \(n = \mathrm{Re}\sqrt{\varepsilon_1 + i\varepsilon_2}\), the
refractive_indexinput ofphonon_assisted_absorption_dense_q().- Return type:
ndarray, shape
(nomega,)
- PAOFLOW.elphon.phonon_assisted_absorption.read_direct_dielectric(outdir, components=('xx', 'yy', 'zz'))[source]#
Read the diagonal dielectric function written by PAOFLOW’s
dielectric_tensor.- Parameters:
outdir (str) – Output directory of the
dielectric_tensorrun (filesepsr_<c>.datandepsi_<c>.dat, photon energy in eV in the first column). Typically a separate run on the extended basis withgradient_and_momenta(position_dipoles=True).components (sequence of str, optional) – Diagonal components to read (default
xx,yy,zz).
- Returns:
omega_ev, eps1, eps2 – Photon energies
(nomega,)and the real (vacuum 1 included) and imaginary parts(ncomp, nomega), thedirect_dielectricinput ofthermal_emissivity().- Return type:
ndarray
- Raises:
ValueError – If the components use different energy grids.
- PAOFLOW.elphon.phonon_assisted_absorption.write_emissivity_outputs(emissivity, outdir)[source]#
Write the thermal-emissivity spectra and totals.
- Parameters:
emissivity (dict) – Output of
thermal_emissivity().outdir (str) – Output directory (created if missing).
- Returns:
Paths written: per temperature
eps_<T>K.dat(photon energy, Re and Im eps),emish_<T>K.dat(photon energy, slab and opaque hemispherical emissivity) andemis_th<deg>_<T>K.dat(photon energy, directional slab emissivity), plusemist.dat(temperature, total slab and opaque emissivity, Planck coverage) andemissivity.npz.- Return type:
- PAOFLOW.elphon.phonon_assisted_absorption.write_absorption_outputs(results, outdir)[source]#
Write the absorption spectra in EPW’s file layout plus an
.npzarchive.- Parameters:
results (dict) – Output of
phonon_assisted_absorption_dense_q().outdir (str) – Output directory (created if missing).
- Returns:
Paths written: per temperature
epsilon2_indabs_<T>K.datandepsilon2_indabs_lorenz<T>K.dat(photon energy, polarisation-averagedIm epsfor each eta),epsilon2_dirabs_<T>K.dat(photon energy,Im epsalong x, y, z and their average, Gaussian and Lorentzian) andalpha_<T>K.dat(photon energy, absorption coefficient in cm^-1 for each eta), plusabsorption.npz.- Return type: