Mat Wannier Tight Binding

mat-wannier-tight-binding

Goal

Construct maximally localized Wannier functions (MLWFs) and a real-space Hamiltonian from DFT, or analyze an existing Wannier90 model. Validate numerical interpolation separately from its accuracy against independent DFT. This skill covers Quantum ESPRESSO → Wannier90 and Python analysis; the bundled examples reuse official tutorial DFT matrices.

Background

The standard Marzari–Vanderbilt method minimizes

$$\Omega=\sum_n(\langle r^2\rangle_n-|\langle\mathbf r\rangle_n|^2) =\Omega_I+\Omega_D+\Omega_{OD}.$$

At fixed subspace, $\Omega_I$ is gauge invariant; both diagonal and off-diagonal gauge-dependent parts are minimized by localization. $\Omega_D$ is not a displacement from inversion centers. For entangled bands, the Souza–Marzari–Vanderbilt step first selects a smooth subspace. If $V(\mathbf k)=U^{dis}(\mathbf k)U(\mathbf k)$, where $U^{dis}$ is rectangular, then

$$H(\mathbf R)=\frac1{N_k}\sum_{\mathbf k}e^{-i2\pi\mathbf k\cdot\mathbf R} V^\dagger(\mathbf k),\mathrm{diag}(\epsilon_{j\mathbf k}),V(\mathbf k).$$

The scripts read standard folded Wannier90 v4.0.3 exports. Interpolation applies both the lattice degeneracy $N_R$ and orbital-pair shifts $\mathbf T$ from _wsvec.dat:

$$H_{mn}(\mathbf k)=\sum_\mathbf R\frac{H_{mn}(\mathbf R)}{N_R} \frac1{N_{T,mn\mathbf R}}\sum_\mathbf T e^{i2\pi\mathbf k\cdot(\mathbf R+\mathbf T)}.$$

Wannier90 has enabled use_ws_distance=true by default since v3.0. Preserve the sidecar with the Hamiltonian. The unshifted expression is supported only for explicitly identified legacy output. See the official interpolation notes and method definitions.

Instructions

1. Select the starting point and runtime

• Existing _hr.dat, _wsvec.dat, .win and .wout: start at step 5.
• A reproducible teaching example: use GaAs or silicon; neither requires QE or a pseudopotential download.
• New DFT calculation: use steps 2–4. Obtain a relaxed/converged structure and choose the target energy manifold first; mat-dft-vasp covers the alternative VASP route, whose interface settings differ.

${CLAUDE_SKILL_DIR} denotes this skill's absolute directory. The launcher and script paths below work from any working directory; calculation paths are relative to the current directory. The example READMEs also provide commands for use from the repository root. wannier90.x, pw.x and pw2wannier90.x are external executables, not installed by the cpu environment. Use an existing working Wannier90 installation, or build the pinned release with existing compiler/BLAS/LAPACK dependencies:

bash ${CLAUDE_SKILL_DIR}/scripts/build_wannier90.sh
export PATH="${CLAUDE_SKILL_DIR}/../../.agents/test/wannier90-build/install/bin:$PATH"
wannier90.x -v

The builder defaults to an isolated installation under .agents/test, verifies the requested source tag, installs through CMake and checks execution. WANNIER_BUILD_DIR, WANNIER_PREFIX, WANNIER_REF, BUILD_JOBS, FC, BLAS_LIBRARIES and LAPACK_LIBRARIES are optional overrides. No system package installation is performed.

2. Prepare consistent SCF, NSCF and Wannier inputs

Templates provide a silicon starting point with identical explicit cells and atoms, plus all 64 NSCF k-points. They are not a reproduction of the bundled tutorial matrices: the pseudopotential, cutoff, lattice constant and energy zero are separate choices.

Copy template_scf.in, template_nscf.in, template.win and template.pw2wan into the calculation directory as scf.in, nscf.in, silicon.win and silicon.pw2wan. Supply the named pseudopotential in pseudo/ and record its source/hash, XC functional, cutoffs, occupations, spin/SOC settings and mesh convergence.

The NSCF calculation must provide a full uniform mesh, with reciprocal basis, shift and ordering matching .win. Explicit points with nosym=true and noinv=true are the supplied QE convention. Automatic grids can also work if their actual full output mesh and ordering are matched; the keyword itself is not prohibited. Shifted meshes are valid when both sides use the same shift.

To change the mesh consistently:

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/generate_kmesh.py \
  --grid 6 6 6 --shift 0 0 0 --output-dir research/wannier/mesh

Replace the complete NSCF K_POINTS card and Wannier mp_grid/kpoints block using the two generated files. The SCF mesh may differ from the NSCF Wannier mesh. See QE input conventions.

3. Choose projections and energy windows

Choose num_wann and initial projectors for the intended orbitals. Set num_bands >= num_wann; disentanglement needs additional bands. Frozen/outer energies are in eV on the DFT eigenvalue energy zero, not automatically relative to the Fermi energy. Replace the templates' provisional 6.4/17.0 eV windows after inspecting the new eigenvalues.

At every mesh point require

$$N_{\rm frozen}(\mathbf k)\le N_{\rm wann}\le N_{\rm outer}(\mathbf k).$$

Freeze states needed for the target observable. Not every model must include all occupied bands. Record lower as well as upper window bounds when excluding deep states. Check orbital character and sensitivity to windows/projections; small spreads alone do not guarantee a physically useful subspace. For spinor calculations use consistent noncollinear/SOC wavefunctions, spinors=true and spinor projector counts; the provided examples are nonmagnetic scalar calculations.

4. Generate matrices, localize and export

Run in the calculation directory, adjusting MPI ranks and executables for the installation:

pw.x -in scf.in > scf.out
pw.x -in nscf.in > nscf.out
wannier90.x -pp silicon
pw2wannier90.x -in silicon.pw2wan > pw2wan.out
wannier90.x silicon

Check each program's termination before proceeding. The interface writes .mmn (overlaps), .amn (trial projections) and .eig (eigenvalues). Eigenvalues are written automatically; write_eig is not an accepted QE interface input. Keep the DFT save directory and matching .nnkp through matrix generation. Changing cell, mesh, bands, spin settings or trial projectors requires regenerating the affected matrices.

Use write_hr=true, use_ws_distance=true, bands_plot=true and a defined kpoint_path for Hamiltonian and path export. Set explicit localization and disentanglement convergence tolerances/windows, with sufficient iteration limits. write_hr is the supported keyword; its replacement of hr_plot predates v4.

5. Check final-state completeness and iterative convergence

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/parse_wout.py \
  research/wannier/silicon.wout --require-converged --output-dir research/wannier/analysis

The parser requires a complete final state, consistent spread sums and normal termination. It distinguishes localization and disentanglement convergence. --max-omega-tot and --max-omega-d are optional system-specific localization bounds, not convergence tests. For historical fixed-iteration examples, omit --require-converged only deliberately; the report then says CONVERGENCE_NOT_ESTABLISHED if native convergence is not documented.

6. Inspect Hamiltonian elements and distances

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/parse_hr.py \
  research/wannier/silicon_hr.dat --win research/wannier/silicon.win \
  --wout research/wannier/silicon.wout --threshold 1e-4 \
  --output-dir research/wannier/analysis

Outputs are tb_hamiltonian.json and tb_hoppings.csv. On-site energies and raw folded matrix elements are gauge/energy-zero dependent. The CSV retains Fourier degeneracies separately; it is not an already-expanded sparse Hamiltonian. With cell and centres, distances use $|(\mathbf R+\mathbf T)A+\tau_n-\tau_m|$ in Å. With cell alone they are explicitly labeled lattice-translation distances. Without a cell, no spatial decay profile is claimed. The threshold filters the table only; it does not truncate the interpolated model.