ADR 0003: Use First-Brillouin-Zone Coordinates For K-Point Meshes

ADR 0003: Use First-Brillouin-Zone Coordinates For K-Point Meshes#

Status#

Accepted

Context#

K-point mesh generation, path construction, and symmetry reduction are used by band, DOS, SCC, transport, and export workflows. Historically, related helpers lived in dptb.utils.make_kpoints and dptb.utils.ksampling, with overlapping responsibilities and different assumptions about how fractional k-points should be represented.

Gamma-centered meshes previously exposed points in a [0, 1) fractional-coordinate convention in some utility paths. Symmetry reduction, especially time-reversal reduction, needs to compare k and -k while handling Brillouin-zone boundary points such as 0.5 and -0.5. Keeping multiple conventions in active implementation code makes boundary handling easy to get wrong.

Decision#

Core k-point implementation lives in dptb.kpoints, split by responsibility:

  • dptb.kpoints.mesh for mesh generation;

  • dptb.kpoints.path for high-symmetry paths;

  • dptb.kpoints.reduction for symmetry and time-reversal reduction;

  • dptb.kpoints.sampling for higher-level sampling.

Mesh k-points should be wrapped to the first-Brillouin-zone fractional-coordinate convention [-0.5, 0.5). For example, a Gamma-centered [4, 1, 1] mesh is represented as:

0.00, 0.25, -0.50, -0.25

rather than:

0.00, 0.25, 0.50, 0.75

These are equivalent modulo reciprocal lattice vectors (0.75 == -0.25, 0.50 == -0.50), but [-0.5, 0.5) is the canonical representation inside DeePTB k-point utilities.

dptb.utils.make_kpoints and dptb.utils.ksampling remain compatibility wrappers. New code should import from dptb.kpoints directly.

Consequences#

  • Symmetry reduction has one canonical coordinate convention for comparing equivalent k-points.

  • Time-reversal reduction can treat Brillouin-zone boundary points consistently.

  • Physical calculations that consume k-points through periodic Hamiltonian evaluation should be unchanged by this representation choice.

  • User code that assumes Gamma-centered mesh coordinates are non-negative or lie in [0, 1) may observe different raw k-point arrays and should wrap or compare k-points modulo reciprocal lattice vectors.

  • Regression tests should cover both dptb.kpoints core functions and the compatibility wrappers under dptb.utils.

  • AI-assisted refactors should not reintroduce duplicated mesh or reduction logic in downstream modules.