mat-epw-mobility

name	mat-epw-mobility
description	Compute phonon-limited carrier mobility and mode-resolved electron-phonon coupling in 2D materials from first principles with Quantum ESPRESSO and EPW.
category	materials

mat-epw-mobility

Goal

To compute the intrinsic phonon-limited carrier mobility $\mu(T)$ of a 2D semiconductor in the Self-Energy Relaxation Time Approximation (SERTA), together with the mode-resolved electron-phonon coupling matrix elements $|g(k, q, \nu)|$, from first principles using the Quantum ESPRESSO + EPW pipeline. The route interpolates the electron-phonon vertex onto dense fine grids via maximally localized Wannier functions and applies the 2D Frohlich long-range kernel needed for polar monolayers.

Background

Carrier mobility limited by phonon scattering requires the electron-phonon matrix elements $g_{mn\nu}(k, q)$ on grids far denser than any tractable DFPT calculation. EPW solves this by computing $g$ on a coarse q-grid with DFPT, transforming to a maximally localized Wannier basis, and interpolating to fine k/q meshes. For 2D polar materials, the long-range Frohlich part of $g$ diverges as $1/q$ near the zone centre and must be treated with a 2D-truncated Coulomb kernel (lpolar, system_2d), otherwise $\mu$ collapses by a factor of ~3.

Unlike the DFT+AMSET route in mat-dft-electronic-transport, which uses a momentum-relaxation-time approximation on VASP band structures, this skill computes the full first-principles electron-phonon vertex. It is complementary to mat-dft-electron-phonon (which targets temperature-dependent bandgap renormalization) and to mat-phonon (MLIP phonons).

The pipeline is a DAG. Steps 3 and 5 are optional (a standalone dielectric check and a DFPT $|g|$ benchmark); the transport path is 1 -> 2 -> 4 -> 6 -> 7 -> 9.

                       1 SCF
           +-------------+--------------+
           v             v              v
      3 DFPT-Gamma   4 DFPT          2 NSCF
      (eps_inf, Z*)  uniform-q       (explicit k)
      (optional)         |               |
                         v               |
                    6 pp.py gather       |
                         |    \          |
                         |     v         v
                         |   7 Wannierize
                         |     |     |
                         v     v     v
                    9 EPW    8 EPW  (8 also <- 5 DFPT single-q
                    SERTA    prtgkk      benchmark, optional)
                    mu(T)    |g|

The worked example below runs the whole pipeline end-to-end on a ZrS2 monolayer and validates EPW-interpolated $|g|$ against the DFPT reference to 0.05% on the gauge-invariant sum.

Instructions

[!IMPORTANT] Quantum ESPRESSO (pw.x, ph.x) and EPW (epw.x, pp.py) are external compiled MPI binaries, exactly as VASP is in mat-dft-vasp. This skill was validated on a source build of QE 7.4.1 / EPW 5.8.1 with ONCV SG15 PBE v1.2 pseudopotentials. The # Env: base-agent annotations apply only to the Python parser scripts. Reference input decks for every step are in resources/inputs/.

1. Ground-state SCF

Compute the charge density and Kohn-Sham orbitals every later step consumes. For 2D materials, assume_isolated = '2D' truncates the out-of-plane Coulomb tail and must be mirrored in ph.x and EPW. Use the deck resources/inputs/scf.in.

# Requires: Quantum ESPRESSO 7.4.1 (external MPI build)
mpirun -np <ranks> pw.x -in scf.in > scf.out

Confirm convergence has been achieved. For ZrS2 the total energy is -136.1241 Ry and the VBM (HOMO) is -6.4435 eV.

2. NSCF on an explicit uniform k-grid

EPW folds Bloch orbitals on an explicit uniform k-grid into Wannier functions. Use K_POINTS crystal with the full list, never automatic (any compression desynchronises EPW's k-indexing). Generate the list and stage the NSCF into its own tmp/ so it does not overwrite the SCF save tree that DFPT needs. Deck: resources/inputs/nscf.in.

# Env: base-agent
python .agents/skills/mat-epw-mobility/scripts/gen_kpoints.py 12 12 1

# Requires: Quantum ESPRESSO 7.4.1 (external MPI build)
mpirun -np <ranks> pw.x -in nscf.in > nscf.out

nbnd must cover the disentanglement window (30 for ZrS2 = 6 occupied + 24 empty). For ZrS2 the gap is 1.1724 eV (CBM -5.2711 eV).

3. (Optional) Gamma DFPT for dielectric tensor and Born charges

Compute $\varepsilon_\infty$ and Born effective charges $Z^*$ as a fast standalone sanity check (EPW itself reads them from step 4's Gamma irrep). A non-symmetric or non-positive-definite $\varepsilon_\infty$ signals an upstream error. Deck: resources/inputs/ph_gamma.in.

# Requires: Quantum ESPRESSO 7.4.1 (external MPI build)
mpirun -np <ranks> ph.x -in ph_gamma.in > ph_gamma.out

For ZrS2: $\varepsilon_\infty^{xx}$ = 2.973, $Z^*_{xx}(\mathrm{Zr})$ = +7.003.

4. DFPT on a coarse uniform q-grid

The dynamical matrices and self-consistent perturbation potentials (dvscf) EPW interpolates from. This is the most expensive step; set recover = .true. so a timeout only loses the in-progress q. fildvscf is required or EPW has no long-range kernel data. nq1/nq2/nq3 must match the coarse nk* EPW reads later. Deck: resources/inputs/ph_uniform.in.

# Requires: Quantum ESPRESSO 7.4.1 (external MPI build)
mpirun -np <ranks> ph.x -in ph_uniform.in > ph_uniform.out

For ZrS2 (6x6x1) this yields 7 irreducible q and phonons in 16.9-337.6 cm^-1 with no imaginary modes.

5. (Optional) Single-q DFPT reference for |g|

The ground-truth $|g(k, q, \nu)|$ at one finite q, against which the EPW interpolation (step 8) is benchmarked. q must not be (0, 0, 0) (the Frohlich cusp diverges); use e.g. crystal (0.005, 0, 0). Stage the NSCF tmp/ (not SCF) so the CBM band is present. Deck: resources/inputs/ph_single_q.in.

# Requires: Quantum ESPRESSO 7.4.1 (external MPI build)
mpirun -np <ranks> ph.x -in ph_single_q.in > ph_q.out

# Env: base-agent
python .agents/skills/mat-epw-mobility/scripts/parse_prt.py ph_q.out --fermi -5.655843

Compare on rank-sorted $|g|$ or the gauge-invariant $\sum |g|^2$ over the degenerate LO/TO quartet, never on the raw mode index.

6. Gather the EPW save/ tree

Collect the distributed dvscf and phsave files from step 4 into the save/ layout EPW expects, using pp.py (bundled with EPW). pp.py reads the prefix from stdin.

# Requires: EPW pp.py (bundled with Quantum ESPRESSO 7.4.1)
printf 'zrs2\n' | python3 pp.py

This produces save/zrs2.dvscf_q*, save/zrs2.dyn_q*, and save/zrs2.phsave/.

7. Wannierization (EPW write stage)

Build maximally localized Wannier functions and write the EPW archive the interpolation reads. This is the single strongest predictor of downstream quality. guiding_centres = .true. is required in long-vacuum 2D cells, or WF centres fold to a wrong z-image and the total spread explodes ~100x. The projections, nbndsub, and exclude_bands are material-specific. Deck: resources/inputs/epw_write.in.

# Requires: EPW 5.8.1 (external MPI build)
mpirun -np <ranks> epw.x -npool <ranks> -in epw_write.in > epw_write.out

# Env: base-agent
python .agents/skills/mat-epw-mobility/scripts/parse_wout.py zrs2.wout

-npool N with N = ranks is mandatory (EPW aborts in < 1 s otherwise). For ZrS2, num_wann = 9, $\Omega_I$ = 18.5 A^2, $\Omega_{total}/\Omega_I$ ~ 1.05.

8. (Optional) Mode-resolved interpolated |g|

Print EPW-interpolated $|g(k, q, \nu)|$ on an explicit (k, q) list and compare to the step-5 DFPT reference. Use explicit filkf + filqf (not a uniform fine grid with an arbitrary q, which aborts in kpmq_map). Note that the coordinate list files (kpoints.dat and qpoints.dat) require a header line specifying coordinate type and count (e.g., 1 crystal followed by coordinate lines), otherwise the Fortran parser fails. Deck: resources/inputs/epw_prtgkk.in.

# Requires: EPW 5.8.1 (external MPI build)
mpirun -np <ranks> epw.x -npool <ranks> -in epw_prtgkk.in > epw_prtgkk.out

# Env: base-agent
python .agents/skills/mat-epw-mobility/scripts/parse_epw_prtgkk.py epw_prtgkk.out --fermi -5.655843

9. SERTA carrier mobility

Compute $\mu(T)$ in the semiconductor SERTA branch on production fine meshes. lpolar = .true. and system_2d must match step 7 exactly.

[!WARNING] Setting etf_mem = 3 turns on lfast_kmesh = .true. to save memory, which silently bypasses the standard SERTA drift mobility print statements. For printing the drift mobility table and producing zrs2_elcond_e, use etf_mem = 1. If you encounter Out-Of-Memory (OOM) errors on large grids, run on a single core (to avoid MPI pool k-point splitting problems) using etf_mem = 0 and epmatkqread = .true. to read pre-computed binary .epb files.

Deck: resources/inputs/epw_mob.in.

# Requires: EPW 5.8.1 (external MPI build)
mpirun -np <ranks> epw.x -npool <ranks> -in epw_mob.in > epw_mob.out

Read $\mu_{xx}$ from the last column of zrs2_elcond_e. Converge in order of impact: nkf (= nqf) first, then fsthick (wide enough to cover the band-edge carriers), then degaussw (fixed-smearing branch only). For ZrS2 at 1e13 cm^-2 electron doping and 300 K, $\mu$ lands near 195 cm^2/V/s at a 100x100 fine mesh.

Examples

See examples/zrs2-monolayer/ for the full end-to-end run on a ZrS2 1T monolayer, including expected values at every step and the DFPT-vs-EPW $|g|$ validation against the gauge-invariant reference.

Constraints

• External codes: requires an MPI build of Quantum ESPRESSO 7.4.1 with EPW and Wannier90; the Python parsers run in base-agent. Validated with ONCV SG15 PBE v1.2 pseudopotentials. Version pins reflect what was tested, not a claim that other versions are broken.
• 2D truncation: assume_isolated = '2D' in pw.x and ph.x, and lpolar = .true. with system_2d in EPW, must all be set and consistent, or the 2D Frohlich kernel is dropped and $\mu$ collapses by ~3x.
• No q = (0, 0, 0) for electron-phonon coupling in polar 2D systems: the Frohlich $1/q$ cusp diverges. Use q >= (0.005, 0, 0) crystal (steps 5, 8).
• fildvscf is required in ph.x (steps 4, 5), even for single-q prt; omitting it causes a silent MPI abort at high rank count.
• guiding_centres = .true. is required for Wannierization in long-vacuum 2D cells (step 7).
• -npool N (N = rank count) is mandatory for every EPW run.
• MPI layout is machine-dependent: on the validated build, DFT/DFPT ran at -np 32 (higher counts aborted DFPT silently). If a DFPT or EPW step aborts via MPI with no Fortran trace, re-run at a lower rank count to expose the error.
• Material-specific inputs: ecutwfc, nbnd, projections, nbndsub, and exclude_bands are set for ZrS2 in the decks and must be adapted to your material and band manifold.
• Gauge invariance: benchmark $|g|$ on rank-sorted values or $\sum |g|^2$ over the degenerate LO/TO quartet, never on the raw mode index.
• Disk: etf_mem = 3 checkpoints interpolated $|g|$ to disk; for a 100x100 x 100x100 grid this can exceed 100 GB.

References

• S. Ponce, E. R. Margine, C. Verdi, F. Giustino, "EPW: Electron-phonon coupling, transport and superconducting properties using maximally localized Wannier functions", Comput. Phys. Commun. 209, 116 (2016). DOI
• H. Lee, S. Ponce, et al., "Electron-phonon physics from first principles using the EPW code", npj Comput. Mater. 9, 156 (2023). DOI
• C. Verdi, F. Giustino, "Frohlich Electron-Phonon Vertex from First Principles", Phys. Rev. Lett. 115, 176401 (2015). DOI
• T. Sohier, M. Calandra, F. Mauri, "Two-dimensional Frohlich interaction in transition-metal dichalcogenide monolayers: Theoretical modeling and first-principles calculations", Phys. Rev. B 94, 085415 (2016). DOI
• G. Pizzi, et al., "Wannier90 as a community code: new features and applications", J. Phys. Condens. Matter 32, 165902 (2020). DOI
• P. Giannozzi, et al., "Advanced capabilities for materials modelling with Quantum ESPRESSO", J. Phys. Condens. Matter 29, 465901 (2017). DOI

---

Author: cz2014 Contact: GitHub @cz2014