WFDX

Wannier Function Decomposition of Excitons

Overview

The WFDX package transforms Bethe-Salpeter equation (BSE) exciton eigenvectors from the Bloch electron-hole basis to a Wannier electron-hole basis. It decomposes Bloch excitons into products of electron- and hole-like maximally localized Wannier functions (MLWFs), yielding real-space exciton coefficients that can be used to analyze the orbital and spatial character of excitons, complementing conventional reciprocal-space analyses. The current implementation is based on the exciton wave functions generated by BerkeleyGW and the MLWFs generated by wannier90.

Features

• Bloch-to-Wannier decomposition: Transform exciton eigenvectors into an electron-hole MLWF product basis.
• Orbital-transition analysis: Group contributions by user-defined Wannier orbital types.
• Real space electron-hole separation analysis: Compute transition-resolved electron-hole separations and their corresponding probabilities.
• Plotting: Visualize the decomposition using arrow plots to better understand the real-space character of the excitons.

Installation

git clone https://github.com/BerkeleyGW/WFDX.git
cd WFDX
pip install -e .

Usage

Decompose an Exciton

from WFDX import WFDXDecomposer

# Create WFDX object
wfdx = WFDXDecomposer(
    fname_wfn_fi_h5="path_to_wfn_fi/wfn.h5",
    path_to_eigenvectors_h5="path_to_exciton_eigenvectors.h5",
    seedname_mlwf="seedname_mlwf",
    dirname_mlwf="path_to_mlwf",
)

# Decompose the exciton into electron-hole MLWFs product
wfdx.decompose_xct(write_to_h5=True)

This writes xct_coeff.h5 in the current working directory, this file contains information of the real-space coeffcient of excitons.

Notice: To maintain gauge consistency of the single-particle Bloch functions, the fine-grid wave functions used to solve the Bethe-Salperte equation, which define the Bloch electron-hole basis in eigenvectors.h5, must be the same as those used as input to wannier90 for generating the MLWFs. For implementation reasons, the k-grid list used for the fine-grid wave functions and the wannierization must also be the same and in the same order.

Analyze Transition Contributions

from WFDX import AnalyzeXct

# Group the MLWFs into different orbital types
# based on their shapes, and analyze the spatial
# and orbital character of the excitons.
analyze_xct = AnalyzeXct(
    fname_xct_coeff="xct_coeff.h5",
    mlwf_seedname="mlwf_seedname",
    mlwf_dirname="path_to_mlwf",
    # An example for grouping Wannier orbitals
    wannier_types={
        "F p": [0, 1, 2],
        "Li s": [3],
        "Li p": [4, 5, 6],
    },
)

# Print out the orbital transition information 
# for a selected exciton state (S=0, Q=0).
analyze_xct.print_transtion_data(iS=0, iQ=0)

Theory

WFDX expands an exciton state in an electron-hole MLWF product basis:

$$ \Psi_{S\mathbf{Q}}(\mathbf{r}_e,\mathbf{r}_h) = \frac{1}{\sqrt{N_{\mathbf{k}}}} \sum_{\mathbf{R}} e^{i\mathbf{Q}\cdot\mathbf{R}} \left[ \sum_{ai\Delta\mathbf{R}} A^{S\mathbf{Q}}_{ai\Delta\mathbf{R}} w_{a \mathbf{R}+\Delta\mathbf{R}}(\mathbf{r}_e) w^{*}_{i \mathbf{R}}(\mathbf{r}_h) \right]. $$

The coefficients $A^{S\mathbf{Q}}_{ai\Delta\mathbf{R}}$ describe the contribution of a transition from a hole-like Wannier function $i$ to an electron-like Wannier function $a$ at relative separation $\Delta\mathbf{R}$, defined as the displacement between the electron and hole Wannier centers. Here, $a$ labels electron-like, virtual/unoccupied orbitals, while $i$ labels hole-like, occupied orbitals, following the conventional notation used in quantum chemistry.

For details, see:

Z. Tao, J. B. Haber, and J. B. Neaton, J. Chem. Theory Comput. 22, 588 (2026).

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contact

For questions or support, please contact:

• Jonah Haber: jbhaber@stanford.edu
• Zui Tao: taozui@berkeley.edu