Adaptive Second Chern

Adaptive integration tools for computing second Chern numbers of the 4D lattice Dirac model.

The main workflow is:

1. Sweep the Dirac mass parameter m.
2. Integrate the numerical second-Chern density over the Brillouin zone.
3. Save the phase diagram as a binary NumPy .npz file.

The saved data can optionally be plotted as C_2 against m.

Install

From the repository root, install the package in editable mode:

python -m pip install -e .

For development tools, including tests, Ruff, and coverage:

python -m pip install -e ".[dev]"

For plotting support:

python -m pip install -e ".[plot]"

Test

python -m pytest -q

Run tests with coverage:

python -m pytest --cov=adaptive_second_chern

Continuous Integration

GitHub Actions runs the same development checks on every push to main and on pull requests:

python -m ruff check .
python -m ruff format --check .
python -m pytest --cov=adaptive_second_chern

Compute a Phase Diagram

The phase-diagram command uses the numerical density by default and skips the gap-closing masses m = -4, -2, 0, 2, 4. If the requested mass grid contains one of those values, the output file will contain fewer rows than --num-masses.

adaptive-second-chern-phase-diagram \
  --m-min -5 \
  --m-max 5 \
  --num-masses 81 \
  --tol 1e-4 \
  --max-refinements 10000 \
  --batch-size 10 \
  --output phase_diagram.npz

You can also run the module directly:

python -m adaptive_second_chern.phase_diagram --m-min -5 --m-max 5 --num-masses 81

Plot

Plotting requires the optional plotting dependencies:

python -m pip install -e ".[plot]"

adaptive-second-chern-plot phase_diagram.npz --output phase_diagram.png

Load Results

import numpy as np

data = np.load("phase_diagram.npz")
m = data["m"]
chern_number = data["chern_number"]
estimated_error = data["estimated_error"]

The saved arrays are:

m
chern_number
estimated_error
n_refined
n_boxes
time_s
gap_closing_mass

Demo

Run one adaptive integration at the default gapped mass m = -1:

adaptive-second-chern-demo

Acknowledgement

This project was inspired by the adaptive-refinement strategy introduced in Xiang Liu, Xiao-Xia Yi, Zheng-Rong Liu, Rui Chen, and Bin Zhou, Efficient evaluation of the (k)-space second Chern number in four dimensions, arXiv:2603.26505 (2026).

The implementation here is independent and does not contain code from the paper.