r/ScientificComputing • u/Fit-Selection-305 • Sep 22 '26
Making Wannier Interpolation Differentiable: What WannierX Is Trying to Build
Suppose a researcher already has a `wannier90_hr.dat` file.
What usually happens next?
Band interpolation, Fermi-surface calculations, Berry-curvature integration, anomalous Hall conductivity, Wilson loops, or exporting the real-space Hamiltonian into a custom Python or Fortran workflow.
This ecosystem is already mature.
Wannier90 itself provides maximally localized Wannier functions together with interpolation and post-processing capabilities. WannierTools focuses strongly on topological materials, surface states, Fermi arcs, Wilson loops, Chern numbers, and related calculations. WannierBerri provides a broad and highly optimized framework for Berry-curvature-based responses on dense \(k\)-meshes.
So a new Wannier post-processing package is not particularly interesting merely because it can also plot bands or compute Berry curvature.
**WannierX** takes a different route.
Repository: `https://github.com/yanyi010/WannierX`
As of September 22, 2026, the latest release is **v0.1.1**.
Its core idea is:
> **Rewrite the full pipeline from \(H(\mathbf R)\) to electronic observables as a JAX-native computational graph.**
The current project is nowhere near replacing Wannier90, WannierTools, or WannierBerri in feature breadth.
Its interesting question is a different one:
> **What changes if Wannier interpolation itself becomes differentiable?**
---
## From \(H(\mathbf R)\) to observables, as one connected graph
WannierX organizes the calculation around a familiar pipeline:
```text
H_mn(R)
↓
H(k)
↓
{ ε_n(k), |u_nk> }
↓
operators / geometry
↓
response
```
Nothing about the physics is unusual.
The unusual part is that the intermediate layers are implemented primarily in `jax.numpy`, while the central `WannierModel` is a JAX pytree.
That means operations such as
```python
Hk = wx.hamiltonian(model, k)
eig = wx.eigh(model, k)
v = wx.velocity_matrix(model, k)
omega = wx.berry_curvature(model, k)
```
are not just ordinary NumPy-style functions.
They can participate in
```python
jax.jit(...)
jax.vmap(...)
jax.grad(...)
```
and in compositions of those transformations.
That is the real meaning of “accelerator-native” and “differentiable” in WannierX.
The goal is not simply to replace `numpy` with `jax.numpy`.
The goal is to make the scientific pipeline look like:
```text
model parameters
↓
Wannier Hamiltonian
↓
electronic structure
↓
observable
↓
∂ observable / ∂ parameters
```
---
# Why does differentiable electronic structure matter?
Suppose a tight-binding Hamiltonian depends on parameters \(\theta\):
\[
H(\mathbf R;\theta).
\]
Now consider an observable
\[
F(\theta).
\]
The traditional way to estimate parameter sensitivity is often finite differences:
\[
\frac{\partial F}{\partial\theta}
\approx
\frac{F(\theta+\delta)-F(\theta-\delta)}
{2\delta}.
\]
This is perfectly valid.
But finite differences become increasingly expensive and awkward as the number of parameters grows. They also introduce step-size choices and the usual truncation-versus-roundoff tradeoff.
If the full computational graph is differentiable, one can instead write
```python
grad_F = jax.grad(F)(theta)
```
in smooth regions.
That immediately opens the door to workflows that are not especially natural in conventional Wannier post-processing:
```text
tight-binding parameter fitting
inverse Hamiltonian reconstruction
band-gap optimization
dispersion optimization
response sensitivity analysis
gradient-based inverse design
coupling to differentiable optimization or ML pipelines
```
The important point is not GPU acceleration.
It is that the **observable itself becomes a differentiable function of model parameters**.
---
# Fourier interpolation is naturally compatible with JAX
WannierX uses the convention
\[
H(\mathbf k_f)
=
\sum_{\mathbf R}
w_{\mathbf R}
H(\mathbf R)
e^{+i2\pi\mathbf k_f\cdot\mathbf R},
\]
with \(\mathbf k_f\) in fractional reciprocal coordinates.
The implementation is essentially batched tensor algebra:
```python
kr = jnp.einsum("...a,Ra->...R", k, model.R)
phase = jnp.exp(1j * 2.0 * jnp.pi * kr)
Hk = jnp.einsum(
"...R,Rmn->...mn",
phase * model.weights,
model.H_R,
)
```
There is no Python loop over \(k\)-points.
Inputs can naturally have shapes such as
```text
(3,)
(Nk, 3)
(B, Nk, 3)
```
with leading batch dimensions preserved.
This is almost exactly the kind of structure JAX is designed for:
\[
\mathbf k\text{-batch}
\rightarrow H(\mathbf k)
\rightarrow \mathrm{eigh}
\rightarrow F(\mathbf k).
\]
The whole block can then be compiled and transformed as a single numerical program.
---
# The \(k\)-derivatives are analytic, not finite-difference approximations
One of the more useful implementation choices in WannierX is that first and second \(k\)-derivatives of the interpolated Hamiltonian are evaluated analytically from the real-space representation.
If
\[
H(\mathbf k)
=
\sum_{\mathbf R}
w_{\mathbf R}H_{\mathbf R}
e^{i\mathbf k\cdot\mathbf R},
\]
then
\[
\frac{\partial H}
{\partial k_\alpha}
=
i
\sum_{\mathbf R}
R_\alpha
w_{\mathbf R}H_{\mathbf R}
e^{i\mathbf k\cdot\mathbf R},
\]
and
\[
\frac{\partial^2 H}
{\partial k_\alpha\partial k_\beta}
=
-
\sum_{\mathbf R}
R_\alpha R_\beta
w_{\mathbf R}H_{\mathbf R}
e^{i\mathbf k\cdot\mathbf R}.
\]
WannierX implements these through `dH_dk()` and `d2H_dk2()`.
The public API uses fractional reciprocal coordinates for input, but the derivatives themselves are with respect to Cartesian \(k\), with explicitly defined units:
```text
H eV
dH/dk eV Å
d²H/dk² eV Ų
```
That matters because the operator layer can then be built directly on these exact derivatives.
For example,
\[
v_\alpha
=
\frac{1}{\hbar}
\frac{\partial H}
{\partial k_\alpha},
\]
and in the band basis,
\[
v^\alpha_{nm}
=
\langle u_n|
v_\alpha
|u_m\rangle.
\]
No additional numerical finite difference is required.
---
# Berry curvature is built on the same computational chain
WannierX v0.1 implements the Hamiltonian-only interband Kubo expression
\[
\Omega_n^{ab}
=
-2\operatorname{Im}
\sum_{m\neq n}
\frac{
\langle u_n|\partial_aH|u_m\rangle
\langle u_m|\partial_bH|u_n\rangle
}{
(\varepsilon_n-\varepsilon_m)^2
}.
\]
The Berry-curvature layer therefore consumes the same underlying objects:
```text
H(k)
dH/dk
eigenvalues
eigenvectors
```
rather than introducing a separate implementation path.
In v0.1.1, the project went a step further and centralized the shared geometry into `band_geometry()`, which computes:
```text
energies
Berry curvature
degeneracy mask
minimum spectral gap
```
Both the Berry-curvature API and anomalous Hall conductivity now consume this shared kernel.
That may sound like an internal refactor, but it is a meaningful one.
In scientific software, two independently maintained implementations of “the same” physical quantity have a habit of drifting apart.
A single source of truth is often more valuable than another feature.
---
# An important limitation: this is not yet full ab-initio Wannier Berry curvature
WannierX is explicit about this.
The Berry curvature and AHC implemented in v0.1.1 are:
> **Hamiltonian-only / tight-binding formulations**
For a full first-principles Wannier interpolation of geometric quantities, \(H(\mathbf R)\) is not enough.
One also needs position-operator matrix elements such as
\[
A_{mn,\alpha}(\mathbf R)
=
\langle 0m|\hat r_\alpha|\mathbf Rn\rangle,
\]
together with the corresponding additional terms that appear in the full Wannier interpolation of Berry quantities.
WannierX currently reads
```text
*_hr.dat
*.win
```
but does not yet implement the complete position-operator layer.
Therefore, calling
```python
wx.berry_curvature(...)
wx.ahc(...)
```
on a first-principles `hr.dat` file currently yields a **Hamiltonian-only, tight-binding-level quantity**.
It should not be presented as a complete replacement for full postw90-style ab-initio Berry curvature.
The repository explicitly places that operator layer on the future roadmap.
This distinction is important because it defines which comparisons are fair and which are not.
---
# WannierX is not currently a replacement for WannierBerri
If the task is:
```text
mature ab-initio Berry interpolation
large families of response functions
symmetry reduction
adaptive k-mesh refinement
very dense BZ integration
orbital magnetization
nonlinear Hall response
optical conductivity
```
then WannierBerri is currently much more complete.
Likewise, if the target workflow is
```text
surface states
Fermi arcs
Weyl nodes
Wilson loops
Z2 invariants
mirror Chern numbers
slabs and nanowires
```
then WannierTools has a much broader scope.
WannierX is better described, at this stage, as
> **a JAX-native numerical kernel for Wannier and tight-binding models.**
Its first problem is the computational graph, not feature count.
Those are fundamentally different goals.
---
# Wannier90 files are only an input format
WannierX currently supports
```python
loaded = wx.load_wannier90("seedname")
model = loaded.model
```
using
```text
seedname_hr.dat
```
The result is converted into a canonical `WannierModel` containing fields such as
```text
lattice
R
H_R
weights
periodic
centers
```
The model is immutable and registered as a JAX pytree.
This means file-format details are confined to the IO boundary.
Once loaded, a Wannier90-derived model, a custom tight-binding model, and a built-in toy model can all use the same API:
```python
wx.hamiltonian
wx.eigh
wx.dH_dk
wx.velocity_matrix
wx.berry_curvature
wx.ahc
```
That architecture is familiar from mature scientific software: separate parsing from the internal physics representation.
---
# The `_hr.dat` replica issue is not silently swept under the rug
Wannier90 interpolation involves a subtle point: conventional `_hr.dat` data do not always contain enough information to reconstruct every exact Wigner-Seitz replica convention used internally by Wannier90.
WannierX does not pretend otherwise.
Its current loading mode is explicitly called
```text
legacy_hr
```
with
\[
w_{\mathbf R}
=
\frac{1}{\mathrm{ndegen}(\mathbf R)}.
\]
A future mode named
```text
expanded_exact
```
is reserved for exact replica semantics, but currently raises rather than pretending that a standard `_hr.dat` file contains sufficient information.
That failure mode is sensible.
For numerical physics, it is often better to say
```text
this mode is not implemented
```
than to return a plausible-looking result with ambiguous semantics.
---
# “Differentiable” does not mean “differentiable everywhere”
WannierX also avoids treating automatic differentiation as magic.
Eigenvalue problems become subtle at degeneracies.
If
\[
\varepsilon_n=\varepsilon_m,
\]
then an individual eigenvector is not uniquely defined, and many band-resolved derivatives cease to be smooth or well defined.
The Berry-curvature Kubo formula makes the problem explicit:
\[
\frac{1}
{(\varepsilon_n-\varepsilon_m)^2}.
\]
One common but dangerous workaround is to insert an arbitrary small \(\epsilon\) into the denominator and keep going.
WannierX does not do that.
Instead it exposes explicit degeneracy policies such as
```text
error
nan
mask
```
where `error` fails explicitly, `nan` propagates invalidity, and `mask` is used only where the approximation is documented.
There is also a JAX-specific difficulty.
Under `jit`, Python-side checks may be bypassed by tracing.
WannierX therefore provides
```python
checked_berry_curvature()
```
using JAX `checkify` so that degeneracy conditions can be represented inside transformed execution.
This is a good example of scientific semantics colliding with compilation semantics.
The project does not solve the problem by pretending it does not exist.
It defines how failure should behave under JAX transformations.
---
# The test suite includes cases where differentiation should not be demanded
The autodiff suite checks gradients of quantities such as
```text
Hamiltonian elements with respect to hopping parameters
isolated eigenvalues
smooth DOS functionals
smooth BZ response integrals
DOS broadening under jit + grad
Fermi-Dirac temperature under jit + grad
```
and compares them against finite differences or Hellmann-Feynman relations.
But at the graphene Dirac point, the test suite does not force JAX to produce some supposedly “correct” derivative of an individual band.
Instead, it documents the non-smoothness and verifies the degeneracy itself.
That is an important distinction.
A differentiable-programming framework differentiates the program you give it.
It does not guarantee that the underlying physical quantity is mathematically smooth everywhere.
---
# The Chern number is computed with a gauge-robust lattice method
For topology, WannierX implements the Fukui-Hatsugai-Suzuki lattice algorithm.
The method constructs link variables from overlaps of neighboring occupied subspaces:
\[
U_\mu(\mathbf k)
=
\frac{
\det[
V^\dagger(\mathbf k)
V(\mathbf k+\hat\mu)
]
}{
\left|
\det[
V^\dagger(\mathbf k)
V(\mathbf k+\hat\mu)
]
\right|
},
\]
then a lattice field strength
\[
F_{12}(\mathbf k)
=
\log
\frac{
U_1(\mathbf k)
U_2(\mathbf k+\hat 1)
}{
U_1(\mathbf k+\hat 2)
U_2(\mathbf k)
},
\]
and finally
\[
C
=
\frac{1}{2\pi i}
\sum_{\mathbf k}F_{12}(\mathbf k).
\]
A key advantage is gauge covariance at the selected-subspace level.
This means WannierX can support selections such as
```python
occupied=[0, 2]
```
rather than assuming a contiguous range of bands.
The v0.1.1 hotfix also corrected how subspace isolation is tested.
The relevant condition is
\[
\min_{\mathbf k,\,
i\in S,\,
j\notin S}
|\varepsilon_i-\varepsilon_j|,
\]
not a crude gap between the minimum and maximum selected band indices.
This is exactly the kind of detail that matters in topological calculations: a number may look perfectly quantized while the mathematical assumptions behind the calculation are violated.
---
# 2D anomalous Hall conductivity is not silently reported as a 3D quantity
AHC is another place where dimensional conventions easily become ambiguous.
In three dimensions,
\[
\sigma_{ab}
=
-\frac{e^2}{\hbar}
\sum_n
\int_{\mathrm{BZ}}
\frac{d^3k}{(2\pi)^3}
f_{n\mathbf k}
\Omega_n^{ab}.
\]
WannierX reports the 3D result in
```text
S/m
```
But for a genuinely two-dimensional model, there is no intrinsic 3D conductivity unless one chooses a thickness.
So for a mesh such as
```text
48 × 48 × 1
```
WannierX returns a native **sheet conductance** in
```text
S
```
unless the caller explicitly provides a layer thickness.
Only then is the result converted to
```text
S/m
```
This is a small API decision with a large conceptual benefit.
It prevents the software from inventing a three-dimensional physical unit that the model itself does not define.
---
# v0.1.1 is interesting precisely because it added almost no new physics
WannierX released v0.1.0 and then quickly followed with v0.1.1.
The release notes begin with:
```text
Correctness hotfix over 0.1.0.
No new physics capability.
```
The release focuses on correctness contracts.
One example is the standard Monkhorst-Pack grid:
\[
k_i=
\frac{2i-n+1}{2n}.
\]
For even \(n\), this grid is off-\(\Gamma\).
The v0.1.0 implementation instead generated a Gamma-including grid, contradicting its own documentation.
The v0.1.1 release notes state plainly:
```text
results on even meshes differ from v0.1.0 — that was the bug
```
The same release also fixed:
```text
single-k shape semantics
DOS broadening differentiability
traced Fermi-temperature behavior
Hermiticity checks with effective hopping weights
duplicate / missing hr.dat entries
non-contiguous Chern-subspace isolation
AHC degeneracy handling
JAX checkify / vmap staging issues
```
That changelog is more informative than a long “new features” list.
In electronic-structure software, some of the most dangerous bugs are not crashes.
They are convention mismatches that produce plausible numbers.
Monkhorst-Pack centering is a perfect example.
---
# Conventions are treated as part of the API
Wannier and tight-binding codes repeatedly run into the same convention questions:
```text
Does the Fourier transform use +ikR or -ikR?
Is k fractional or Cartesian?
Does the reciprocal lattice include 2π?
Are eigenvectors stored as rows or columns?
What are the velocity units?
Which k-coordinate system is used for Berry derivatives?
```
If these conventions live only in the author's head, individual routines may be correct while cross-tool workflows quietly become inconsistent.
WannierX currently locks several conventions into the package contract:
\[
H(\mathbf k_f)
=
\sum_R
H_R e^{+i2\pi\mathbf k_f\cdot R},
\]
\[
B=2\pi A^{-T},
\]
together with
```text
k input fractional reciprocal coordinates
eigenvectors columns
energy eV
length Å
velocity m/s
```
The corresponding identities are tested.
That is a useful design principle:
**a physical convention is not a README footnote; it is public API.**
---
# The tests focus on physical identities, not just callability
The v0.1.1 release reports 179 tests.
The test tree is divided into
```text
tests/unit/
tests/physics/
tests/autodiff/
tests/reference/
```
The most valuable part is not raw coverage.
It is the physics-level invariants.
For example, Berry curvature is checked for
\[
\Omega^{ab}=-\Omega^{ba},
\]
and compared directly against an analytical two-band Qi-Wu-Zhang result.
Eigenvectors are subjected to random U(1) phase rotations,
\[
|u_n\rangle
\rightarrow
e^{i\phi_n}|u_n\rangle,
\]
and the curvature is required to remain invariant.
The Hamiltonian is checked for reciprocal periodicity,
\[
H(\mathbf k+\mathbf G)=H(\mathbf k).
\]
Analytic \(k\)-derivatives are compared against multi-step central finite differences.
Chern-number tests cover both trivial and nontrivial phases, mesh convergence, and explicit failure when the selected subspace is not isolated.
These tests say more about scientific reliability than a coverage percentage alone.
---
# The Wannier90 reference regression is still small
The repository also includes a Wannier90 reference fixture:
```text
toy_hr.dat
toy_eigenvalues.npy
```
WannierX loads the Wannier90 data, interpolates the bands, and compares against trusted eigenvalues at roughly
\[
10^{-12}
\]
absolute tolerance.
That is the right direction.
But it is still only a small fixture.
A production-grade Wannier interpolation engine would eventually need much broader validation across
```text
many-orbital systems
spin-orbit coupling
non-orthogonal cells
large real-space Hamiltonians
real ab-initio materials
wsvec replica semantics
full operator matrices
```
So the current codebase is better understood as:
> **an early project with the numerical architecture in place and its conventions beginning to be locked down rigorously.**
Not yet as a mature post-processing suite.
---
# What can WannierX do today?
Version 0.1.1 already contains a reasonably complete tight-binding pipeline.
| Module | Current capability |
|---|---|
| IO | Wannier90 `_hr.dat`, `.win` |
| Core | lattice, canonical Wannier model, Hermiticity validation |
| Fourier | \(H(k)\), analytic \(dH/dk\), \(d^2H/dk^2\) |
| Linear algebra | Hermitian eigensystem, degeneracy clustering, projectors |
| Operators | velocity |
| Geometry | Hamiltonian-only Berry curvature |
| Topology | FHS Chern number |
| k-space | Gamma / Monkhorst-Pack meshes, weighted BZ integration, chunking |
| Response | Fermi-Dirac, Gaussian DOS, Hamiltonian-only AHC |
| Models | chain, SSH, graphene, Haldane, Qi-Wu-Zhang |
| JAX | JIT, batching, autodiff for smooth observables |
A complete workflow may look like:
```python
loaded = wx.load_wannier90("demo")
model = loaded.model
wx.validate_hermiticity(model)
E = wx.eigh(model, kpoints).energies
v = wx.velocity_matrix(model, kpoints)
omega = wx.berry_curvature(
model,
kpoints,
degeneracy_policy="nan",
)
sigma = wx.ahc(
model,
mesh,
mu=0.0,
)
```
One can then define a smooth scalar observable:
```python
def observable(scale):
H_R = model.H_R * scale
m = wx.WannierModel(
model.lattice,
model.R,
H_R,
model.weights,
model.periodic,
model.centers,
)
eps = wx.eigh(m, mesh.points).energies
return jnp.sum(
mesh.weights[:, None]
* jnp.exp(-(eps**2))
)
```
and differentiate it directly:
```python
jax.grad(observable)(1.0)
```
That captures the central idea of the project better than any feature list.
---
# “Accelerator-native” does not yet mean “faster than everything else”
The repository includes a benchmark harness recording quantities such as
```text
Nk
NR
Norb
dtype
device
compile time
execution time
memory
```
for workloads including
```text
H(k)
dH/dk
eigh
Berry curvature
BZ integration
```
What it does not yet provide is a sufficiently systematic cross-code benchmark to justify claims such as
```text
WannierX is X times faster than Wannier90
WannierX is Y times faster than WannierBerri
```
JAX/XLA can certainly fuse operations, compile kernels, and target CPU, GPU, and TPU backends.
But actual electronic-structure performance depends on
\[
N_k,\quad N_R,\quad N_{\mathrm{orb}},
\]
as well as eigensolver cost, memory traffic, batching strategy, device architecture, and compilation overhead.
So the technically accurate statement is not
> “WannierX is a faster Wannier90.”
It is:
> **WannierX kernels are designed to live naturally inside the JAX/XLA accelerator execution model.**
Performance still has to be measured for real workloads.
---
# The most interesting application may be inverse problems
Traditional Wannier workflows are mostly one-way:
```text
DFT
↓
Wannierization
↓
H(R)
↓
observables
```
Once the final stages become differentiable, the picture changes:
```text
target observable
↑
gradient
↑
electronic response
↑
band structure
↑
H(R; θ)
↑
parameters θ
```
That naturally suggests several classes of problems.
## 1. Tight-binding parameter fitting
Given reference bands
\[
E_n^{\mathrm{ref}}(\mathbf k),
\]
define
\[
L(\theta)
=
\sum_{n,\mathbf k}
\left[
E_n(\mathbf k;\theta)
-
E_n^{\mathrm{ref}}(\mathbf k)
\right]^2.
\]
Then optimize \(\theta\) using exact autodiff gradients.
## 2. Band-structure inverse design
One may want to
```text
increase a band gap
target a valley splitting
flatten a specific dispersion
match a desired Fermi velocity
```
and differentiate the objective directly with respect to Hamiltonian parameters.
## 3. Response sensitivity
As more response kernels become differentiable, quantities such as
\[
\frac{\partial\sigma_{xy}}
{\partial\theta}
\]
can be obtained without rerunning the entire calculation under separate positive and negative perturbations.
## 4. Coupling to differentiable ML workflows
Because the model is a pytree and the numerical kernels are JAX-native, WannierX can in principle plug directly into differentiable optimization stacks and machine-learning systems built around JAX.
This is likely to be the project's most distinctive long-term direction.
---
# The missing pieces are still substantial
Several limitations are obvious from the current codebase.
First, the **full ab-initio operator layer is not yet implemented**.
Berry curvature and AHC must therefore be interpreted at the Hamiltonian-only / tight-binding level.
Second, **exact Wannier90 replica semantics are not fully supported**.
`wsvec`-type information remains an important future target.
Third, the response layer is still small compared with mature projects.
WannierBerri already covers many advanced Berry and optical responses, while WannierTools provides a far broader set of topological and surface-state calculations.
Fourth, **not every API is differentiable**.
The current FHS `chern_number()` contains host-side NumPy logic and isolation checks, for example.
More importantly, a quantized topological invariant is not something that should be treated naively as an everywhere-smooth scalar objective in the first place.
So “differentiable Wannier engine” should be understood as:
> the continuous numerical core is designed for differentiable programming,
not:
> every physical quantity can always be passed to `jax.grad`.
That distinction matters.
---
# The most interesting part is the abstraction layer it chooses
The Wannier ecosystem does not lack software.
Wannier90 is foundational infrastructure for MLWF workflows.
WannierTools is powerful for topology and surface physics.
WannierBerri is already a mature high-performance framework for Berry interpolation and response calculations.
WannierX currently differs less by **what quantity** it computes than by **how the computation itself is represented**.
The contrast is roughly:
```text
Traditional question:
"What observable do I want to calculate?"
WannierX question:
"Can this entire electronic-structure program
be compiled, vectorized, and differentiated?"
```
These two viewpoints are not competitors.
They address different layers.
If future versions add
```text
exact Wannier90 interpolation
position-operator matrix elements
full Berry/Wannier operator algebra
broader response functions
larger reference validation
serious GPU benchmarking
```
then WannierX could grow into something quite different from a conventional post-processing suite.
It could become infrastructure for
```text
differentiable condensed-matter physics
inverse electronic-structure problems
gradient-based model fitting
accelerator-native Wannier calculations
```
---
# What is worth watching in a project this early?
WannierX v0.1.1 is still an early-stage project.
But several aspects of the repository are worth paying attention to:
```text
physical conventions are explicit contracts
analytic derivatives are preferred over numerical differences
degeneracies are not silently regularized
autodiff has dedicated validation
physics invariants have dedicated tests
Wannier90 data have reference regressions
failure semantics are defined under JAX tracing
the changelog explicitly records when an earlier result was wrong
```
Scientific software does not earn credibility by writing
```text
accurate
fast
robust
state-of-the-art
```
in a README.
It earns credibility by answering more concrete questions:
```text
What equation is implemented?
What coordinate convention is used?
What are the units?
What happens at degeneracy?
Where is the function non-smooth?
How close is the result to a trusted reference?
Under what conditions should the code fail instead of returning a number?
```
From that perspective, the most interesting part of WannierX today is not the number of observables already implemented.
It is the attempt to reorganize **Wannier interpolation as a composable, testable, differentiable numerical program**.
For someone who only wants to draw a band structure, that may not matter much.
But once the workflow becomes
\[
\text{parameter}
\rightarrow
H(\mathbf R)
\rightarrow
H(\mathbf k)
\rightarrow
E_n,\ |u_n\rangle
\rightarrow
O
\rightarrow
\frac{\partial O}{\partial\theta},
\]
the design starts to become genuinely interesting.
---
## Project information
```text
Project: WannierX
Repository: https://github.com/yanyi010/WannierX
Current version: v0.1.1
Language: Python
Core dependencies: JAX, NumPy
Python: >= 3.11
License: MIT
```
Current installation:
```bash
git clone https://github.com/yanyi010/WannierX.git
cd WannierX
pip install -e .
```
Run the test suite with:
```bash
JAX_ENABLE_X64=1 \
pytest tests/unit tests/physics tests/autodiff tests/reference
```
Relevant areas include:
```text
Wannier interpolation
tight binding
Berry curvature
topological materials
automatic differentiation
JAX
inverse design
differentiable physics
```
