Skip to content

fix(zone): reduce the reciprocal basis before building the Brillouin zone - #295

Merged
lllangWV merged 13 commits into
devfrom
fix/286-reduced-basis
Oct 4, 2026
Merged

lllangWV merged 13 commits into
devfrom
fix/286-reduced-basis

Conversation

@lllangWV

@lllangWV lllangWV commented Oct 4, 2026 •

Copy link
Copy Markdown
Member

Why

A user whose reciprocal basis is sheared (for example b2 = (3, 1, 0) for a cubic lattice) saw a drawn Brillouin zone up to 5 times too large. Cross-section areas and van Alphen frequencies counted orbits outside the first zone or missed orbits inside it, and Fermi-velocity arrows came out up to 57 times too long. Every zone builder searched a fixed integer window of the basis it was given, and that window holds all zone faces only for a reduced basis. The fix reduces the basis with spglib.delaunay_reduce (already a dependency) before it picks the zone faces, so every caller gets the reduced zone.

What changed

  • zone_face_steps (pyprocar/core/brillouin_zone.py:16) picks the face vectors from the 5^3 block of the Delaunay-reduced basis. plane_orbits uses it in place of the fixed _ZONE_STEPS (pyprocar/plotter/_periodic_cut.py:338).
  • _wigner_seitz (brillouin_zone.py:37) adds the face vectors outside the 3^3 block to the Voronoi input. It returns only the vertices of the origin's cell. Before, it returned every Voronoi vertex, so BrillouinZone.points and .bounds spanned outer cells too, and FermiPlotter.plot sized its arrows from them (fs_plot.py:199).
  • plane_orbits starts its orbit search in every cell the zone reaches (_start_steps, _periodic_cut.py:283). Before, it searched cells -2 to 2 only, so an orbit at a zone corner 6 cells out was never found. It raises ValueError when the zone spans more than MAX_REACH = 16 cells of the given basis (_periodic_cut.py:291).

The orbit search itself is unchanged from origin/dev: a curve grows until it closes or reaches 16 cells of the given basis (_periodic_cut.py:315).

Known limit (not fixed here)

A heavily sheared basis has long, thin cells, so 16 of its cells cover less of k-space than 16 reduced cells. An orbit that reaches past that limit, near a far zone corner or as an ellipse several zones long, can come back as an open curve where the reduced basis closes it. origin/dev has the same limit. This PR does not claim that a sheared basis closes the same orbits as the reduced basis. The reach limit is tracked in #302.

An earlier round of this PR counted the reach in reduced cells. The live verifier showed that this broke sheared bases (closed orbits through the zone came back open on a sheared fcc basis, about half of random shears raised, and one hexagonal shear took 4 minutes per cut), so this round reverts it.

Scope

  • Covers the 4 checklist items of Brillouin zone and cross-section zone are wrong for non-reduced reciprocal bases #286: the cross-section zone, the drawn zone, the reduction before the zone is built, and a direct test of the face selection against scipy.spatial.Voronoi on a monoclinic and a triclinic cell plus sheared versions.
  • Leaves out the drawn Fermi surface on a sheared basis. ebs.pad adds 10 grid points in fractional coordinates, which do not cover the zone, so the clipped surface misses pieces, on origin/dev and here (visible in the SrVO3 image below). Tracked in Sheared reciprocal bases: Fermi surface padding, coarse-grid cross sections and basis-dependent helpers #302.
  • Leaves out, as separate pre-existing items: the orbit reach above, cross sections on sheared bases from coarse DFT grids (the sheared grid's marching-cubes mesh can differ a lot from the reduced one and adds orbits below 1e-3), ebs.shift_kpoints_to_fbz, the basis dependence of snap_normal, and _fix_normals_direction.

Blast radius

  • Reduced cells, cross sections. plane_orbits output is bit-identical to origin/dev on 352 of 352 cuts on 22 reduced cells, including hexagonal, bcc and rhombohedral cells.
  • Reduced cells, BrillouinZone. The geometry is unchanged: the face polygons are bit-identical to origin/dev's on 22 of 22 cells. .points now holds only the zone's vertices. Cubic, tetragonal and SrVO3 keep identical arrays. Other cells lose the outer vertices: fcc 48 to 24, bcc 24 to 14, triclinic 48 to 24. One random triclinic cell had a stray vertex at 1e16. So the longest FermiPlotter.plot arrow is now a tenth of the zone's extent, which fix(plotter): draw every surface's arrows, scaled by |v| and sized to the Brillouin zone #273 intended. On Au (van-alphen fixture) it goes from 0.0969 to 0.0509 1/Å.
  • BrillouinZone2D. The output changes for bulk reduced cells (fcc, bcc, rhombohedral, triclinic, the Au lattice), because it now stretches its own vertices. Only layered prisms (graphene, BiSb) stay bit-identical. Neither version gives a prism on a bulk cell. On a hexagonal slab with c tilted by 1 to 6 Å, this branch gives the correct prism (hull volume 3 A) and origin/dev does not (measured by the round 1 audit).
  • Tilted-c slabs. On a slab whose c is tilted by 3 Å or more, origin/dev's BrillouinZone itself was wrong (volume 7.636e-3 against |det B| = 7.632e-3 at 3 Å), because the face vector b1 + 2 b3 lies outside the 3^3 block. This branch fixes it (found by the round 1 audit).
  • New errors.
    • spglib.delaunay_reduce returns None on extreme cells (vector-length ratio near 900), and zone_face_steps then raises ValueError("spglib cannot Delaunay-reduce the reciprocal lattice ..."). I kept that loud, explicit error rather than catching it. The round 1 verifier saw it on 5 of 100 skewed cells. Such cells are not realistic, and slab-like cells work up to aspect 1e4.
    • plane_orbits raises when the zone spans more than 16 cells of a very sheared basis, as above.
  • Warnings. spglib.delaunay_reduce emits one DeprecationWarning (Set OLD_ERROR_HANDLING to false ...) per process. I left spglib's global error mode alone, because switching it would change error handling for structure.py's spglib calls too.

Verification

Tests of this PR, run at this head (f95aa6c) and against the origin/dev library (f243254), with this head's test files:

test origin/dev this head
test_brillouin_zone_matches_voronoi_for_any_basis_of_the_lattice (no .clean()), 6 cases 6 fail (hull volume 354 vs 1.17, 2.38 vs 0.929, ...) pass
test_longest_arrow_is_a_tenth_of_the_brillouin_zone_extent [cubic, sheared-cubic, fcc] cubic passes; 2.1 vs 0.1, 0.4 vs 0.2 pass
test_shifted_grid_finds_the_line_through_a_zone_corner_below_the_start_cells ([], 2) == ([], 1) pass
test_sheared_basis_finds_the_orbit_at_a_zone_corner_six_cells_out 0.2317 vs 0.054 pass

The shifted-grid test covers the - 1 in _start_steps' low. Dropping it fails the test with assert ([], 0) == ([], 1) (rerun at this head). A translate of the period covers [s + shift/n, s + 1 + shift/n], so the margin matters only on a shifted grid, where the cut meets the zone only in the translate below floor(min).

Round 1 tests: on origin/dev 15 failed and 3 passed (the unsheared guards).

The round 2 verifier's sheared fcc case: basis S @ B with S = [[-1,4,-4],[0,4,-5],[1,1,-2]] and B = 0.5 [[-1,1,1],[1,-1,1],[1,1,-1]], tight-binding band on a 220x220x97 grid, two planes through the pocket.

plane reduced basis origin/dev round 2 (ee0bfaa) this head
3 [0.1187], 0 open [0.113, 0.115], 0 open [], 1 open [0.1185], 0 open
7 [0.1319], 0 open [], 0 open [], 1 open [0.1314], 0 open

Comparisons (scripts in the owner's scratchpad, rerunnable):

  • Reduced cells against origin/dev. On 22 cells, plane_orbits is bit-identical on 352 of 352 cuts (348 with orbits or open curves), and the BrillouinZone face polygons on 22 of 22.
  • Zone points, bounds and arrows against round 2 (ee0bfaa). BrillouinZone.points, .bounds and faces on the 22 reduced cells and on 88 random unimodular shears (entries -3 to 3) of them, BrillouinZone2D, and the FermiPlotter.plot arrow length on cubic, sheared cubic and fcc are all bit-identical. The sheared points equal the reduced cell's zone vertices.
  • _periodic_cut.py is byte-identical to the round 1 head (e57378e).

Gates on tree dd088b13 (this head f95aa6c; first run on 195f51c, which has the same tree):

  • pytest tests -m "not data" -n 4: 1948 passed, 2 skipped, exit 0.
  • pytest tests -m data -n 4: 382 passed, 1 skipped, exit 0 (the same 382 pass at origin/dev f243254).
  • basedpyright --project pyrightconfig.json: 0 errors, 0 warnings.
  • ruff_new_violations.py check origin/dev and format origin/dev: 5 changed files, ok.
  • ruff check --select F821,F822,F823,NPY201 .: all checks passed.

Arrows from FermiPlotter.plot(fs, vectors_data="fermi_velocity") (round 2 images; the zone code that sizes them is unchanged since):

round 1 head (e57378e) this branch
SrVO3, basis sheared by b2 + 3 b1 before after
Au (van-alphen), own basis before after

The drawn zone for the sheared SrVO3 basis (round 1):

origin/dev this branch
before after

The blue box is the true SrVO3 zone. The black wireframe is BrillouinZone for the sheared basis.

Closes #286

@lllangWV
lllangWV force-pushed the fix/286-reduced-basis branch from afc5443 to e57378e Compare October 4, 2026 17:21
@lllangWV

lllangWV commented Oct 4, 2026

Copy link
Copy Markdown
Member Author

VERDICT: FAIL

Reviewed SHA: e57378e (the branch has not moved). Base: origin/dev bf65596, which is also the merge base, and git merge-tree is clean. Lane: audit and regression (independent verifier).

One defect is in scope and makes a caller's output worse. Everything else checks out, and the fix is small.

Finding (blocking)

On a sheared basis, BrillouinZone.points and .bounds still describe a much larger region than the zone, and FermiPlotter.plot uses that size for its arrow length. pyprocar/core/brillouin_zone.py:37-45: _wigner_seitz adds the far face vectors to the Voronoi input and returns every Voronoi vertex, including the vertices of the outer, unbounded cells. The drawn faces are correct. But fs_plot.py:199-200 sets the longest arrow to ARROW_ZONE_FRACTION * max(ptp(fermi_surface.brillouin_zone.points)), and for a sheared basis that length now moves further from the reduced cell's value.

cubic lattice, basis n_points (used) ptp(points) glyph_length bz.bounds z
reduced, B = I (base = head) 8 (8) 1 0.1 ±0.5
b2+3b1, origin/dev 16 (8) 7 0.7 ±0.5
b2+3b1, head 32 (8) 8 0.8 ±3.5
b2+3b1, b3-2b1+2b2, origin/dev 36 (10) 21 2.1 ±10.5
b2+3b1, b3-2b1+2b2, head 74 (8) 57 5.7 ±28.5

fcc and hexagonal behave the same way. Under the same double shear, ptp(points) is 80 for fcc where the zone is 2, and 107 for hexagonal where the zone is 1.15. The rendered wireframe is fine, because VTK's renderer bounds are ±0.5 and the drawn wireframe spans the same 345×366 px as the reduced cell's in a 400 px window. So the drawn zone is correct, but the claim that "every caller gets it" (item 3) fails for the one library caller that reads points.

Smallest repro: np.ptp(BrillouinZone(np.array([[1,0,0],[3,1,0],[-2,2,1.]])).points, axis=0).max() returns 57.0. The reduced cell gives 1.0, and origin/dev gives 21.0.

Suggested fix: when zone_face_steps returns a step outside the 3^3 block, build the Voronoi from the 3^3 block of the reduced basis (_NEIGHBOURS @ M, where M = rint(reduced @ inv(unit))) instead of from the given basis plus the extra face vectors. Reduced inputs keep their bit-for-bit output, and a sheared input then gets the reduced cell's point set. Alternatively, return only the origin cell's vertices on that path. Add a test that compares ptp(points) with the reduced cell's.

Commands and key numbers

  • -m data suite (pytest tests -c .config/.pytest.toml --rootdir . -n 12 -m data -q -p no:cacheprovider): head 381 passed, 1 skipped, exit 0. origin/dev 381 passed, 1 skipped, exit 0.
  • Zone-related modules at head (test_brillouin_zone, test_cross_section_area, test_bandstructure2d, test_bs_2d_plot, test_kpoints): 220 passed.
  • gh pr checks 295: format, lint, test and typecheck all pass.
  • Fixture regression at origin/dev and at head, with private copies of the fixtures. Inputs: 4 fermi3d fixtures (non-spin-polarized, spin-polarized, non-colinear, van-alphen), 4 fermi2d fixtures (the 3 SrVO3 sets and bisb_monolayer) and both 2d-bands fixtures (graphene, bisb_monolayer). Compared: BrillouinZone points, faces, face_normals and centers; BrillouinZone2D; and FermiSurface.from_ebs (n_points, n_cells, area, every point). Also 7 cross_section_areas cuts per Fermi-surface fixture (49 cuts), the area and van Alphen text from FermiPlotter.add_slicer, and BS2DPlotter.plot(show_brillouin_zone=True, clip_brillouin_zone=True). All identical bit for bit. bisb_monolayer fermi2d raises "No Fermi surfaces were generated" in both checkouts.
  • Independent zone reference: scipy Voronoi of the 9^3 block of the cell that generated the basis. I validated it on simple cubic (8 vertices, V = 1) and on the truncated octahedron (24 vertices). A cell was used only when the reference volume equalled |det|. Inputs: 283 random triclinic cells (scale 0.2 to 3) under random unimodular shears with entries up to 145. Head: volume, vertices, outward normals and clip_surface correctness on 283 of 283. origin/dev: wrong on 244 of 283.
  • _start_steps and zone_face_steps on simple cubic, rhombic dodecahedron, truncated octahedron, hexagonal, a 30 Å slab, a needle cell, a left-handed cell, cells scaled by 1e-3 and 1e3, and shears of 3, 10 and 20 cells: no extra start cells on any reduced cell. b2+40b1 raises the first zone spans more than 16 cells, as the PR says.

Acceptance items (#286)

  1. Cross-section zone on non-reduced bases: done. plane_orbits takes its faces from zone_face_steps. Reduced fixtures are unchanged (49 of 49 cuts). I did not re-derive the sheared-orbit areas; that belongs to the red/green lane.
  2. Drawn BrillouinZone on sheared bases: done for the geometry. Volume equals |det B| and the vertices match Voronoi on 283 of 283. The points/bounds attribute still differs from the reduced cell's (see the finding).
  3. Reduction before building the zone, so that every caller gets it: claimed but partly false. The cross-section, drawn-zone, clipping and BS2D callers get the reduced zone. FermiPlotter.plot's arrow length does not.
  4. Direct test against scipy Voronoi on monoclinic and triclinic cells plus sheared versions: done (test_zone_faces_match_voronoi_for_any_basis_of_the_lattice and test_brillouin_zone_matches_voronoi_...; the cells really are monoclinic and triclinic).

Notes (not blocking)

  • BrillouinZone2D's new vertex stretch (brillouin_zone.py:185-187) changes the output on reduced cells that are not prisms: bcc, fcc, rhombohedral, triclinic and the van-alphen fixture's lattice. The PR's "reduced cells are unchanged bit for bit" covers BrillouinZone and layered prisms only. Neither version gives a prism on those cells. On origin/dev nothing is stretched, so the zone keeps its k extent along z (±2π for bcc) whatever e_min and e_max are. Head stretches only the extreme vertices. On the realistic case, a hexagonal slab with c tilted by 1, 3 or 6 Å, head gives the correct prism (hull volume 22.5985 = 3·A) and origin/dev does not (1.89). So this is an improvement where BrillouinZone2D is meaningful.
  • On a tilted-c slab (tx ≥ 3 Å), origin/dev's BrillouinZone itself was wrong (vol 7.636e-3 at tx = 3 Å, 7.785e-3 at tx = 6 Å, against |det B| = 7.632e-3), because the face vector b1+2b3 lies outside the 3^3 block. Head fixes it. This real-world beneficiary of the PR is not mentioned in it.
  • The PR says the padding gap ("Leaves out the drawn Fermi surface on a sheared basis … Reported for a separate issue") is reported, but no issue exists yet (open issues go up to Documented-calls check: **kwargs keywords, three rst comment shapes, docstring examples #296).
  • Pre-existing, out of scope: ebs.shift_kpoints_to_fbz (ebs.py:1183) wraps fractional coordinates, which is not the first zone for an oblique cell. snap_normal's _DIRECTION_INDICES window of -4 to 4 (_surface_plot.py:33) depends on the basis. _fix_normals_direction decides from face 0 only. Head gave outward normals on 283 of 283.
  • spglib.delaunay_reduce adds one DeprecationWarning (OLD_ERROR_HANDLING) per process. Once spglib switches error handling, the reduced is None branch becomes dead code and a SpglibError is raised instead, which is still a loud failure.
  • No baseline edits, no narrating comments.

@lllangWV

lllangWV commented Oct 4, 2026

Copy link
Copy Markdown
Member Author

VERDICT: PASS+NOTES

Reviewed SHA: e57378e (base origin/dev bf65596, which is also the merge base, so the PR is not behind dev; git merge-tree is clean)
Lane: live + red/green + gates (independent verifier, did not write the PR)

Gates (all exit 0)

  • pytest tests -m "not data": 1924 passed, 2 skipped.
  • basedpyright --project pyrightconfig.json: 0 errors, 0 warnings.
  • ruff_new_violations.py check origin/dev and format origin/dev: 4 changed files, ok. ruff check --select F821,F822,F823,NPY201 .: all checks passed.
  • -m data suite: 381 passed, 1 skipped at the head, and the same 381 passed at origin/dev.
  • gh pr checks 295: format, lint, test and typecheck all pass.

Red/green and mutation

  • The 18 new tests, run against the origin/dev library: 15 fail and 3 pass (the 3 unsheared guards). All 18 pass at the head.
    • 9 of the 15 fail for the reason the PR states: zone volume 3.49 vs 1.17 and 38.6 vs 1.17, 2 orbits counted instead of 1, and only 1 of the 2 orbits found at the corner case.
    • The other 6 fail on ImportError: zone_face_steps, because that API is new.
  • I mutated the head and ran the new tests against each mutant:
Mutation Tests failing
No basis reduction in zone_face_steps 13
_start_steps returns only _START_STEPS 1 (the corner test)
BrillouinZone2D heights taken from all Voronoi vertices 1
_wigner_seitz uses only the 3^3 neighbours 5
plane_orbits region uses the old 5^3 candidates of the given basis 4
zone_face_steps returns None 64
low = floor(min) - 1 changed to floor(min) 0 (the mutant survives)

Independent reference and live checks

The reference is my own Wigner-Seitz cell. It is the scipy Voronoi cell of every lattice point within radius R, and R grows until R >= 2.1 x the cell's circumradius. It uses no reduction and no candidate window.

  • I validated it on analytic cells first. Volume and face count match for cubic (1, 6), fcc (0.25, 12), bcc (0.5, 14) and hexagonal (1.3856, 8).
  • Its domain is wider than the PR's tests: 12 random unimodular shears with entries -5..5 (inverse entries up to 36), against -3..3 in the PR's own sweep.

Drawn zone and face selection:

  • BrillouinZone and zone_face_steps, 14 cells x 13 bases = 182 cases. The cells are cubic, fcc, bcc, hexagonal, monoclinic, triclinic, 6 random triclinic, SrVO3 and the Au van Alphen lattice.
    • Head: 182/182 match the reference in vertex set, volume and face set.
    • origin/dev: fails all 168 sheared cases, plus 1 unsheared random cell that is not reduced (the head fixes it).
  • The face-coefficient claim: over 316 lattices (generic, anisotropic, near-degenerate, and shears with entries up to ±12), the largest face coefficient in the Delaunay-reduced basis is 1. The docstring's "-2 to 2" therefore holds, and the 5^3 block is conservative.
    • The 66 face-count differences from my reference are all on cells perturbed by 1e-6. There the head keeps faces whose area is about eps^2, which my reference's area cutoff drops. The volumes are identical.

Reduced cells against origin/dev:

  • BrillouinZone: bit-identical on all 12 reduced cells.
  • plane_orbits: bit-identical on 150/150 cuts (6 reduced cells, tight-binding bands, 470 orbits, 103 open curves).
  • BrillouinZone2D: bit-identical on graphene and BiSb. It is not bit-identical on bulk 3D cells (note 3).

2D zone:

  • On the head, BrillouinZone2D gives the same volume for every basis of every cell (zero spread).
  • On graphene and BiSb sheared by b2+3b1 and b2-5b1, the prism volume equals 5 x the in-plane area. origin/dev gives 9.3x, 17.3x, 4.1x and 11.1x.

Real fixtures through the public API (FermiSurface.from_ebs, fs.brillouin_zone, cross_section_areas, FermiPlotter.plot(show_brillouin_zone=True)), on the same k-points re-expressed in the sheared basis:

  • SrVO3, zone volume / |det B| for the shears b2+3b1, u4 and u13: head 1.000000 for all three; origin/dev 5.0, 29.7 and 53.0.
  • Au: head 1.000000 for all three; origin/dev 4.0, 70.7 and 30.0.
  • The render shows the correct cube on the head and a 5x slab on origin/dev.

Cross sections on sheared bases, closed pockets only (4 cells x 15 shears x 8 planes, compared with the reduced basis at 64^3):

  • For shears the guard accepts: head matches 289/352 cuts, origin/dev 148/352. The remaining head misses are note 1, plus mesh coarseness.
  • At a 4x Fourier-interpolated grid, the sheared and reduced bases agree within about 5%.

MAX_REACH raise:

  • Cubic with b2 + k b1 raises from k = 30; k = 20 runs.
  • About 1 in 3 of the random -5..5 shears raises.

Notes (none blocking; origin/dev shares the mechanism in 1, 2 and 5)

  1. _periodic_cut.py:291 (_start_steps): the guard has no margin. A zone that spans 13-15 cells passes the guard. Orbits that meet the zone near its far corners then hit the growth limit at MAX_REACH, and are reported as open with no exception.
    • Smallest repro: cubic, shear [[0,-1,4],[2,-2,-5],[1,-2,2]], start window -14..12.
    • The reduced basis gives [0.18, 0.2325] with 0 open curves.
    • The head gives [0.1793] with 1 open curve.
    • With MAX_REACH = 30 the head gives [0.1793, 0.2322] with 0 open curves. The hexagonal cell shows the same.
    • origin/dev is also wrong on these cuts.
    • Fix: raise when the window plus a margin passes MAX_REACH, or let curves grow MAX_REACH cells past the window.
  2. brillouin_zone.py:44 (_wigner_seitz) passes every Voronoi vertex into the PolyData. The extra face vectors add far-away vertices that no face uses.
    • On SrVO3, .points / .bounds span 8x the zone for b2+3b1 and 75x for u13. The clean zone is ±0.13; .bounds reach ±1.04 and ±9.75.
    • fs_plot.py:200 sets glyph_length from ptp(brillouin_zone.points), so arrows on a sheared basis come out that much too long. origin/dev gives 7x and 27x on the same bases.
    • Camera framing is not affected. Reduced cells are unchanged.
    • Fix: keep only the vertices that the faces use.
  3. brillouin_zone.py:185: BrillouinZone2D now takes its heights from the cell's own vertices.
    • This changes the 2D zone of bulk reduced cells (fcc 0.25 -> 0.417, bcc, triclinic, Au 0.055 -> 0.265). The PR body's bit-identical claim covers only layered cells, which do stay identical.
    • The new behaviour is arguably the intended one.
  4. spglib.delaunay_reduce returns None on extreme cells, so zone_face_steps raises a new ValueError.
    • It happened for 5 of 100 skewed cells with a vector-length ratio near 900.
    • It also gives a wrong zone at aspect 1e5 when sheared.
    • Slab-like cells are fine up to aspect 1e4. These cells are not realistic.
  5. On the real 15^3 and 21^3 DFT grids, sheared-basis cross sections differ from the own-basis answer by much more than mesh noise.
    • Example: Au with b2+3b1 gives 0.41 vs 0.55 and 0.32 vs 0.89 on 2 of 6 planes.
    • Many spurious orbits below 1e-3 also appear. They appear on origin/dev too.
    • The new features/fermi3d.md line says the orbits "differ ... only by the coarser marching-cubes mesh". That is right in kind, but the difference can be large.
  6. The - 1 in low (_periodic_cut.py:288) is not covered by any test (the surviving mutant above).
  7. Performance on heavily sheared bases: plane_orbits is up to about 9x slower than origin/dev, because the start window is larger. One case took 321 s vs 35 s for 8 planes on a 220x203x132 grid. Reduced cells are unaffected.

Acceptance (#286)

  1. Cross-section zone on non-reduced bases (b2 = (3,1,0) and random shears give the reduced cell's zone): confirmed. The face sets match the reference on 168/168 shears.
  2. Drawn BrillouinZone for sheared bases (volume |det B|, same zone as the reduced cell): confirmed, including SrVO3 and Au through the public API. .points still carries extra vertices (note 2).
  3. Reduction happens before the zone is built, so every caller gets it: confirmed. BrillouinZone, BrillouinZone2D and plane_orbits all go through zone_face_steps.
  4. Direct test against scipy.spatial.Voronoi on a monoclinic and a triclinic cell, plus sheared versions: present, and it fails on origin/dev.

lllangWV added a commit that referenced this pull request Oct 4, 2026
@lllangWV

lllangWV commented Oct 4, 2026

Copy link
Copy Markdown
Member Author

VERDICT: PASS+NOTES

Reviewed SHA: ee0bfaa (round 2; the branch has not moved). Lane: audit and regression (independent verifier). Base: origin/dev bf65596, the merge base. Trunk has since moved to 3ae5842 (#300: a CI red-green script, a conftest marker and docs). git merge-tree is clean, and I re-ran the tests below on the head merged with it.

Round 1 finding: fixed

_wigner_seitz now returns only the vertices of the origin's cell. Each face is re-indexed into that list with searchsorted over the sorted used indices, so faces keep their vertex order and orientation.

  • Sheared bases. For the cubic, fcc and hexagonal lattices, under b2+3b1 and under b2+3b1 with b3-2b1+2b2, n_points and ptp(points) now equal the reduced cell's: 8 and 1.0, 24 and 2.0, 12 and 1.155. bz.bounds is ±0.5 on the cubic double shear (round 1: ±28.5). The FermiPlotter.plot arrow (glyph_len) is 0.1 there. Round 1 head gave 5.7 and origin/dev 2.1.
  • Random sheared bases. 283 random triclinic cells, with random unimodular shears whose entries reach 145, checked against my independent reference. The reference is scipy Voronoi of the 9^3 block of the generating cell. I validated it on simple cubic (V = 1, 8 vertices) and on the truncated octahedron (24 vertices), and kept a cell only when the reference volume equalled |det|. Results: volume 283 of 283, vertex set 283 of 283, outward normals 283 of 283, clip_surface correct on 283 of 283.
  • Reduced cells. The geometry is unchanged against origin/dev, compared in my harness on 13 canonical cells and every fixture lattice: the face polygons by coordinates (in the same face order), face_normals and centers are identical. Only points, the face indices and the arrow length change, in two cases:
    • Cells where origin/dev's points held outer vertices: fcc and triclinic 48 to 24, bcc and rhombohedral 24 to 14, hexagonal and monoclinic 16 to 12, BiSb 48 to 24, Au (van-alphen) 48 to 24.
    • The arrow length on those cells: Au 0.0969 to 0.0509 1/Å, fcc 0.4 to 0.2, hexagonal 0.2 to 0.115. This now matches ARROW_ZONE_FRACTION's documented "fraction of the Brillouin zone's largest extent", and the PR body states it.
    • SrVO3 and simple cubic are identical arrays.

Callers of points, bounds and vertex order

I grepped pyprocar/, examples/, docs/ and scripts/. The only reader of zone .points is fs_plot.py:199-200 (the arrow length, above). Nothing reads bounds. Nothing indexes the old vertex list outside BrillouinZone and BrillouinZone2D themselves. clip_surface, clip_to_zone, kpoints.plot and ebs.plot_kpath use face_normals, centers or the mesh, which are unchanged.

BrillouinZone2D now takes min and max over its own vertices, so it behaves as in round 1. Graphene and BiSb produce identical geometry (bz2_normals equal), and BS2DPlotter.plot(show_brillouin_zone=True, clip_brillouin_zone=True) is identical on both 2d-bands fixtures.

_PACK 64 to 1024 and result order

  • No overflow. Keys are edge * 2^30 + pack and -(pack + 1), built from np.unique inverses (int64), with an edge-count headroom of about 8.6e9.
  • Order preserved. Packing is lexicographic in (class, c0, c1, c2) for any _PACK larger than the cell range, so the order of names, and hence of curves and areas, cannot change for cells the old keys could hold.
  • Checked on the fixtures. The unsorted area lists are identical to origin/dev's on all 49 fixture cuts.
  • Range check. _PACK_REACH = 510 bounds every step: the reach check is MAX_REACH times the largest column sum of |R|, and tri_off plus _NEAR_VERTEX stay inside the 512 offset. The boundary matches the PR: on a cubic lattice, b2+30b1 runs and b2+31b1 raises orbits within 16 reduced cells reach 512 cells … more than the 510.

Regression run: origin/dev against ee0bfaa

  • -m data suite (pytest tests -c .config/.pytest.toml --rootdir . -n 4 -m data -q -p no:cacheprovider): head 381 passed, 1 skipped, exit 0. origin/dev 381 passed, 1 skipped, exit 0.
  • Fixtures, from private copies:
    • Fermi-surface fixtures: fermi3d non-spin-polarized, spin-polarized, non-colinear and van-alphen, plus fermi2d non-spin-polarized, spin-polarized and non-colinear. On each I compared FermiSurface.from_ebs (n_points, n_cells, area, every point), 7 cross_section_areas cuts in returned order, and the area and van Alphen text from FermiPlotter.add_slicer. All bit-identical.
    • fermi2d/bisb_monolayer: raises "No Fermi surfaces were generated" in both checkouts.
    • 2d-bands graphene and bisb_monolayer: BS2D clip is identical, and the BrillouinZone2D geometry is identical.
  • Head merged with trunk 3ae5842: test_brillouin_zone, test_cross_section_area, test_fs_plot_property_api, test_bandstructure2d, test_bs_2d_plot, test_kpoints and test_fermisurface give 277 passed (-n 4).
  • gh pr checks 295: format, lint, red-green, test and typecheck all pass. The red-green log reports every changed test as failing on base.

Acceptance items (#286)

  1. Cross-section zone on non-reduced bases: done (the zone comes from zone_face_steps; the reach is now in reduced cells).
  2. Drawn BrillouinZone on sheared bases, with volume |det B| and the reduced cell's zone: done, now including points and bounds.
  3. Reduction before the zone is built, so every caller gets it: done. The cross-section, drawn-zone, clipping, BS2D and arrow-length callers all get the reduced zone.
  4. Direct test against scipy Voronoi on monoclinic and triclinic cells plus sheared versions: done. It is now stricter, without .clean().

Notes (not blocking)

  • The reduced-cell claim misses real hexagonal inputs. The claim is "A basis no longer than its reduced basis keeps its own cells, so reduced cells search exactly as before". The _reach_basis tolerance ((1 + 1e-9), _periodic_cut.py:301) is tighter than POSCAR rounding. On the graphene and BiSb fixture lattices (60.0000° and 59.9998° reciprocal bases), the sums of |b|² match to 6 digits (relative differences 1.1e-7 and 3.1e-6). Yet _reach_basis returns spglib's {b3, b1-b2, b1} instead of the identity, so the 16-cell reach region for these hexagonal cells changes shape: the reach along second-neighbour directions swaps between 27.7|b| and 13.9|b|. The textbook triclinic cell [[1,.1,.05],[.3,1.2,0],[.2,.35,.8]] also switches, because its sum is 3.345 against 3.1875. No fixture output changed. Only orbits longer than about 14 zone widths are affected, and the old region was just as asymmetric. A looser tolerance (about 1e-6, or comparing sorted lengths) would make the claim true.
  • BrillouinZone2D on bulk, non-prism cells changes against origin/dev, as noted in round 1 and stated in the PR. Layered prisms are identical, and tilted-c slabs now give the correct prism (hull volume 22.5985 = 3A, against 1.89 on origin/dev).
  • The PR body says the ebs.pad sheared-basis gap is "to be filed". It is still not filed.
  • The spglib.delaunay_reduce DeprecationWarning (OLD_ERROR_HANDLING) is unchanged from round 1 and stated in the PR.
  • No baseline edits, no narrating comments.

@lllangWV

lllangWV commented Oct 4, 2026

Copy link
Copy Markdown
Member Author

VERDICT: PASS+NOTES

Reviewed SHA: f95aa6c (round 3; the branch has not moved). Lane: audit and regression (independent verifier). Base: origin/dev f243254, which is also the merge base, so the head already includes #299 and #297.

Setup followed the brief's new SAFETY rule: no symlinks. Each worktree got a private data/ directory, reflink-copied on btrfs, and its own _version.py. Nothing under the shared data/ was touched.

Diff against current origin/dev

Six files changed: brillouin_zone.py (zone faces from the Delaunay-reduced basis, plus vertices of the origin cell only), _periodic_cut.py, three test files and features/fermi3d.md.

  • _periodic_cut.py is byte-identical to the round 1 head e57378e.
  • The tree is identical to 195f51c.
  • Beyond round 1, only the zone-vertex change, its tests (test_longest_arrow_is_a_tenth_of_the_brillouin_zone_extent, the shifted-grid margin test, no more .clean()) and the docs remain.
  • The round 2 reach rule and its tests are gone.

Interaction with #299

#299 adds kpoints.wrap_to_first_zone, a fractional wrap into (-1/2, 1/2], and uses it in shift_kpoints_to_fbz, generate_gamma_centered_kpoints and ibz2fbz. None of these touch BrillouinZone, zone_face_steps or plane_orbits, and this PR does not touch them. The name "first zone" for a fractional-cell wrap is a pre-existing item (round 1 note), not caused by this PR.

Callers of BrillouinZone points and bounds

The callers are the same as in round 2: ebs.brillouin_zone, kpoints.brillouin_zone, FermiSurface.get_brillouin_zone, from_ebs clipping, BandStructure2D.get_2d_brillouin_zone and plane_orbits. The only reader of zone .points is fs_plot.py:200 (the arrow length). Nothing reads .bounds, and nothing indexes the old vertex list.

Arrow length and bounds now track the zone in any basis. Cubic, fcc and hexagonal lattices under b2+3b1 and under b2+3b1 with b3-2b1+2b2 give spreads of 1.0, 2.0 and 1.155. The cubic double shear gives bounds ±0.5 and an arrow of 0.1 (origin/dev: 2.1). The drawn wireframe has the same pixel extent as the reduced cell's.

My independent scipy Voronoi reference covers 283 random sheared triclinic cells, with shear entries up to 145. I validated the reference on simple cubic and on the truncated octahedron, and kept a cell only when the reference volume equalled |det|. Volume, vertices, outward normals and clip_surface are correct on 283 of 283.

Regression run: origin/dev f243254 against f95aa6c

  • -m data suite (pytest tests -c .config/.pytest.toml --rootdir . -n 4 -m data -q -p no:cacheprovider): head 382 passed, 1 skipped, exit 0. origin/dev 382 passed, 1 skipped, exit 0.
  • Fixtures: fermi3d non-spin-polarized, spin-polarized, non-colinear and van-alphen; fermi2d non-spin-polarized, spin-polarized and non-colinear; fermi2d/bisb_monolayer; and 2d-bands graphene and bisb_monolayer.
    • Bit-identical: FermiSurface.from_ebs (n_points, n_cells, area, every point), 49 cross_section_areas cuts in returned order, the area and van Alphen text from FermiPlotter.add_slicer, and the BS2DPlotter.plot(show_brillouin_zone=True, clip_brillouin_zone=True) meshes.
    • Zone geometry identical on every fixture lattice and every reduced canonical cell: face polygons by coordinates, face_normals, centers, and BrillouinZone2D normals for the 2d-bands lattices.
    • Changed only where intended: points, face indices and arrow length on cells that had outer vertices (Au 0.0969 to 0.0509), BrillouinZone2D on bulk non-prism cells, and the sheared canonical cells, which are now correct.
  • Zone-related modules at head (test_brillouin_zone, test_cross_section_area, test_fs_plot_property_api, test_bandstructure2d, test_bs_2d_plot, test_kpoints, test_fermisurface): 275 passed (-n 4).
  • gh pr checks 295: format, lint, red-green, test and typecheck all pass. Red-green reports that all 7 added tests fail on base f243254, each for its stated reason.

Acceptance items (#286)

  1. Cross-section zone on non-reduced bases: done (faces from zone_face_steps). The orbit reach limit in sheared cells is scoped out to Sheared reciprocal bases: Fermi surface padding, coarse-grid cross sections and basis-dependent helpers #302, and the PR body and docs say so.
  2. Drawn BrillouinZone on sheared bases, with volume |det B| and the reduced cell's zone, including points and bounds: done.
  3. Reduction before the zone is built, so every caller gets the reduced zone: done.
  4. Direct test against scipy Voronoi on monoclinic and triclinic cells plus sheared versions: done.

Commit messages (squash-merge uses them)

No message claims that a sheared basis closes the same orbits as the reduced basis. Two statements are contradicted by runs. Neither is a code defect, but both should be reworded before the squash:

  • f5cd5a2 "fix(zone): keep only the zone's own vertices in BrillouinZone" says "cells whose vertices are all used (cubic, tetragonal, layered prisms) keep the same arrays". Hexagonal layered prisms do not: graphene's BrillouinZone2D points go from 16 to 12 and BiSb's from 48 to 24. Their geometry, normals and BS2D clip are identical. Rectangular prisms do keep their arrays.
    • The PR body's "Only layered prisms (graphene, BiSb) stay bit-identical" has the same error.
    • Suggested wording: "cubic, tetragonal and rectangular layered cells keep the same arrays; other cells, including hexagonal ones such as graphene and BiSb, lose only their outer vertices".
  • 1593b30 "fix(zone): pick the zone faces from the Delaunay-reduced basis" says "Reduced cells keep the same Voronoi input, so their zone is unchanged bit for bit". That was true at that commit, but in a squashed message it reads as a claim about the final state, which changes .points on most reduced cells. Suggested: "… so their zone geometry is unchanged".

Notes (not blocking)

  • BrillouinZone2D on bulk non-prism cells changes against origin/dev, as the PR states. Tilted-c slabs now give the correct prism: hull volume 22.5985 = 3A at tilts of 1, 3 and 6 Å, against 1.89 on origin/dev.
  • The ebs.pad sheared-basis gap is still "to be filed". The reach limit is filed as Sheared reciprocal bases: Fermi surface padding, coarse-grid cross sections and basis-dependent helpers #302.
  • spglib.delaunay_reduce emits one DeprecationWarning (OLD_ERROR_HANDLING) per process, as stated in the PR.
  • No baseline edits, no narrating comments.

@lllangWV

lllangWV commented Oct 4, 2026

Copy link
Copy Markdown
Member Author

VERDICT: PASS+NOTES

Reviewed SHA: f95aa6c (round 3). It is rebased onto origin/dev f243254, which is the merge base, so the PR is not behind dev.
Lane: live + red/green + gates (independent verifier)

My round-2 FAIL is resolved

  • The round-2 reach rule is gone. pyprocar/plotter/_periodic_cut.py is byte-identical to the round-1 head e57378e (git diff e57378e5 f95aa6c6 -- pyprocar/plotter/_periodic_cut.py is empty).
  • My sheared-fcc repro gives round 1's answers again. The basis is S B with S = [[-1,4,-4],[0,4,-5],[1,1,-2]] and B = 0.5 [[-1,1,1],[1,-1,1],[1,1,-1]], with the tight-binding band on a 220x220x97 grid:
Plane Reduced basis This head Round 2
3 [0.1187], 0 open [0.1185], 0 open [], 1 open
7 [0.1319], 0 open [0.1314], 0 open [], 1 open
  • No claim remains that sheared bases close the same orbits.

Gates at the head (all exit 0)

  • pytest tests -m "not data" -n 4: 1948 passed, 2 skipped.
  • -m data -n 4: 382 passed, 1 skipped at the head, and the same 382 passed at origin/dev f243254.
  • basedpyright: 0 errors, 0 warnings.
  • ruff_new_violations.py check origin/dev and format origin/dev: 5 changed files, ok. ruff check --select F821,F822,F823,NPY201 .: all checks passed.
  • red_green.py origin/dev: 7 added test functions, all fail on the base.
  • gh pr checks 295: format, lint, red-green, test and typecheck all pass.

Mutants at the head (new tests plus the existing zone, cross-section and fs_plot tests; 121 tests)

Mutant Tests failing
No basis reduction 15
Start window replaced by _START_STEPS 2
All Voronoi vertices kept 9
3^3 neighbours only 6
- 1 margin dropped from low 1 (the shifted-grid test), killed
Old 5^3 candidate region 5
zone_face_steps returns None 68
Zone-span guard removed (if False) 0, survives

Live checks against my independent reference

The reference is the scipy Voronoi cell of every lattice point within a growing radius, with no reduction. I validated it first on analytic cells: cubic, fcc, bcc and hexagonal volume and face count.

Zone, points and arrow length

  • 182 bases: 14 cells (including SrVO3, Au and 6 random triclinic) times 13 bases (identity plus 12 random unimodular shears with entries -5..5).
    • Head: 182/182 match the reference in vertices, volume and faces.
    • No point is left unused by a face.
    • In every case, the extent of .points equals the extent in the unsheared basis of the same lattice.
    • origin/dev fails 169 of the 182: all 168 sheared cases, plus 1 random triclinic cell that is not reduced.
  • Real fixtures, sheared through the public API (FermiSurface.from_ebs, fs.brillouin_zone).
    • SrVO3 and Au with the shears I, b2+3b1, u4 and u13: zone volume / |det B| = 1.000000 for all of them.
    • .points has 8 points (SrVO3) and 24 (Au) in every basis.
    • The arrow scale ptp(points) is 0.25998 (SrVO3) and 0.50855 (Au) in every basis, the same as the reduced cell.

Reduced cells against origin/dev

  • plane_orbits: bit-identical on 150/150 cuts across 6 cells (470 orbits, 103 open curves).
  • BrillouinZone: the face polygons are bit-identical on 13/13 reduced cells.
    • Only the vertices that no face uses are gone: fcc lattice 24 -> 14, bcc and triclinic 48 -> 24, hexagonal and monoclinic 16 -> 12. Cubic and SrVO3 keep the same arrays.

Notes (non-blocking)

  1. The zone-span ValueError in _start_steps (_periodic_cut.py:291, round 1's guard) is not covered by any test; the removed-guard mutant survives.
  2. BrillouinZone2D changes from origin/dev on bulk reduced cells, for example fcc 0.25 -> 0.417 and Au 0.055 -> 0.265. Layered prisms (graphene, BiSb) and cubic keep identical face geometry. The PR body states this.
  3. Orbit reach on sheared bases, coarse-grid mesh differences, and spglib failing at vector-length ratios near 900 are all documented as known limits. The reach goes to Sheared reciprocal bases: Fermi surface padding, coarse-grid cross sections and basis-dependent helpers #302.

Acceptance (#286)

  1. Cross-section zone on non-reduced bases: done. Faces match the reference on 168/168 shears.
  2. Drawn BrillouinZone on sheared bases: done. Volume is |det B|, and the points equal the reduced cell's.
  3. Reduction before the zone is built, so every caller gets it: done.
  4. Direct test against scipy Voronoi on a monoclinic and a triclinic cell, plus sheared versions: done. It fails on origin/dev.

@lllangWV
lllangWV force-pushed the fix/286-reduced-basis branch from f95aa6c to c1c3914 Compare October 4, 2026 21:20
@lllangWV

lllangWV commented Oct 4, 2026

Copy link
Copy Markdown
Member Author

VERDICT: FAIL

Reviewed SHA: f5cbb87 (head of #295, based on origin/dev 5d6ae01, so head and head merged with dev are the same tree).
Lanes: both lanes (live + red/green + gates, and audit + regression), scoped to the rebase and the new commit f5cbb87. The rest of the PR already holds two verdicts at f95aa6c.

Blocking finding (one line to fix): the repo's red-green job fails on the new test, and the CLAUDE.md rule it enforces is broken.

  • tests/pyprocar/core/test_brillouin_zone.py:417 test_building_a_zone_emits_no_warnings passes on the base, because dev's BrillouinZone never calls spglib. CI run 37236029497, job red-green, logs passes on base ... FAIL: make it fail without the fix, or, if it guards behaviour the base already has, mark it @pytest.mark.guards_existing_behaviour(reason="...") and ends with red/green: FAILED / exit code 1. gh pr checks still shows the job as pass only because it is continue-on-error: true.
  • Rule in CLAUDE.md: "A new or changed test fails on the base code for the reason it names ... A test that guards existing behaviour says so with @pytest.mark.guards_existing_behaviour(reason=...)". The test is a valid guard: it fails at head with the fix reverted (see below). Fix: add @pytest.mark.guards_existing_behaviour(reason="dev builds the zone without spglib; this guards the delaunay_reduce call this PR adds"). Everything else below passes.

Rebase c1c3914. git range-diff 5884b801..f95aa6c6 origin/dev..c1c3914c: every commit is = except 2715154, whose only change is diff context (the from tests.utils.user_warning import user_warning line that #294 added) in tests/pyprocar/plotter/test_fs_plot_property_api.py. The other difference is #297 (f243254), which is now in dev instead of in the range.

The filter in f5cbb87 (pyprocar/core/brillouin_zone.py:28-32). I checked it with a probe that wraps spglib.delaunay_reduce and the C extension.

  • Scope. warnings.filters is identical before and after a zone build. Warnings emitted inside the filtered call all still come through: another DeprecationWarning, a DeprecationWarning whose message contains but does not start with "Set OLD_ERROR_HANDLING", a UserWarning with the same text, and a plain UserWarning. Only the exact spglib message (re.match prefix + DeprecationWarning) is dropped.
  • Real spglib errors still surface. With the old error handling and a failing C call, spglib emits two copies of the message (both dropped) and returns None, and the code raises ValueError: spglib cannot Delaunay-reduce .... With SPGLIB_OLD_ERROR_HANDLING=0, SpglibError: Generic Spglib error propagates unchanged.
  • A user filter simplefilter("error", DeprecationWarning) still builds the zone, and that error filter is active again afterwards.
  • spglib 2.7.0 source: _set_no_error() (error.py:128) warns on every call while OLD_ERROR_HANDLING is on, and _set_or_throw_error warns again on failure. Both use exactly this message.
  • Thread safety is acceptable. catch_warnings swaps the process-global filter list on Python 3.12, so a concurrent thread can, at worst, lose this one spglib message, or leak this narrow ignore filter. pyprocar/ has no threads and no other catch_warnings, filterwarnings or simplefilter call (grep), so nothing in the library races with it.

Red/green. I reverted only brillouin_zone.py to c1c3914 in my worktree, then restored it with git status clean:

Public API. FermiHandler(code="vasp", dirname=<private copy of data/examples/fermi3d/non-spin-polarized>, fermi=5.3017).plot_fermi_surface(mode="plain", show=False) under simplefilter("always") records 0 warnings on origin/dev, 2 spglib DeprecationWarnings (reduce.py:68) at head without the fix, and 0 at head.

#294's test_warn_user at head (all exit 0, 12 passed each).

  • 10 runs alone with -n 0, plus 3 with -n 8.
  • File orders: bz → wu, wu → bz, fermi_handler_save → fs_plot_property_api → bz → wu and its reverse.
  • Test functions in reversed order, and in 5 seeded shuffles (pytest-randomly is not installed, so I passed node ids in permuted order).
  • The fermi test alone, before test_the_default_filter_shows_a_warning_once_per_line and after it.
  • tests/pyprocar/{core,utils,plotter,scripts} -m "not data" -n 4: 737 passed, 1 skipped.

Gates at f5cbb87 (verify.sh exec; the main checkout's pixi.lock differs from dev's, so CI is the final gate):

  • pytest tests -n 8 -m "not data": 1975 passed, 2 skipped, exit 0
  • pytest tests -n 4 -m data: 382 passed, 1 skipped, exit 0
  • basedpyright --project pyrightconfig.json: 0 errors, 0 warnings, exit 0
  • ruff_new_violations.py check origin/dev and format origin/dev: 5 changed files, ok
  • ruff --select F821,F822,F823,NPY201 .: all checks passed
  • CI on f5cbb87: format, lint, test and typecheck pass. red-green shows "pass" but its log says FAILED, as above.

Notes (non-blocking):

  • The commit message says "Users saw the DeprecationWarning on every Fermi-surface plot". Under Python's default filters the warning is hidden, because it is attributed to spglib/reduce.py, not __main__. I confirmed it is silent with plain python and shown with python -X dev, so it reached users only under -X dev, -W default or pytest. The fix is still right.
  • Pre-existing and out of scope: Structure calls spglib.get_symmetry_dataset unfiltered (pyprocar/core/structure.py:456,471,493,586), which emits the same deprecation under spglib 2.7. spglib 2.8 flips the default to raising, which will turn the zone's ValueError path into a SpglibError. Both are still loud.

plane_orbits selected the Wigner-Seitz faces inline. Move that selection,
unchanged, into pyprocar.core.brillouin_zone.zone_face_steps so it can be
tested against scipy.spatial.Voronoi and shared with BrillouinZone.

Refs #286
Compare zone_face_steps and BrillouinZone with the Voronoi cell of a
7^3 block of a monoclinic and a triclinic cell, for the cell itself and
two sheared bases of the same lattice. Check BrillouinZone2D against the
regular hexagon of a hexagonal lattice, and the cross-section of a sphere
inside the cubic zone through the basis b2 = (3, 1, 0).

The sheared cases fail: faces are lost, the drawn zone is too large, and
the cut counts orbits outside the first zone.

Refs #286
zone_face_steps searched for face vectors among coefficients -2 to 2 of
the given basis, and BrillouinZone took the Voronoi cell of the 3^3
block of the given basis. A sheared basis of the same lattice, such as
b2 = (3, 1, 0) for the cubic lattice, has face vectors outside both
blocks, so the cross-section zone lost faces and the drawn zone was too
large.

zone_face_steps now takes its candidates from the 5^3 block of the
basis that spglib.delaunay_reduce returns. That basis is 3 of the 7 face
vector pairs of an obtuse superbase, so every face vector has
coefficients -2 to 2 in it. BrillouinZone and BrillouinZone2D add the
face vectors outside their 3^3 block to the Voronoi input, and
BrillouinZone2D stretches the zone by the heights of its own vertices
only. Reduced cells keep the same Voronoi input, so their zone is
unchanged bit for bit.

Refs #286
With b2 = (3, 1, 0) and b3 = (-2, 2, 1), the zone corner (0.5, 0.5, -0.5)
lies in the cell (-5, 1, -1) of the basis. plane_orbits starts its search
in cells -2 to 2 only, so the orbit around that corner is never found.

Refs #286
…ches

plane_orbits cut the band in cells -2 to 2 of the given basis first and
grew only from open curve ends, so in a sheared basis an orbit around a
zone corner several cells out was never found. Add the cells that the
zone's bounding box covers in fractional coordinates, from the zone
corners that scipy's HalfspaceIntersection gives, after cells -2 to 2.
A reduced cell's zone stays inside cells -2 to 2, so its cut is
unchanged. A zone that spans more than MAX_REACH cells raises.

Refs #286
…heared bases

BrillouinZone.points must be the zone's vertices for any basis of the
lattice, and FermiPlotter.plot's longest arrow a tenth of the zone's
extent (fails on the cubic lattice sheared by b2+3b1, b3-2b1+2b2: 5.7
instead of 0.1, and on fcc in its own basis: 0.4 instead of 0.2).

A cut on a grid shifted along b1 meets the zone only in the translate
below floor(min) of the zone's fractional box; it passes before the
next commit and fails when the "- 1" in _start_steps' low is dropped.

Refs #286
_wigner_seitz returned every Voronoi vertex of the 3^3 block plus the
far face vectors, including the vertices of the outer cells. The faces
were right, but .points and .bounds spanned up to 57 times the zone on
a sheared basis and twice the zone on fcc in its own basis, and
FermiPlotter.plot sizes its arrows from .points. It now returns the
vertices the origin's cell uses, re-indexed in their Voronoi order, so
cells whose vertices are all used (cubic, tetragonal, layered prisms)
keep the same arrays. BrillouinZone2D takes its heights from all
vertices again, which are now its own.

Refs #286
…utput

Every zone build called spglib.delaunay_reduce, which warns on each call
while spglib's process-wide OLD_ERROR_HANDLING is on. Users saw the
DeprecationWarning on every Fermi-surface plot, and #294's FermiHandler
line test recorded it. The call now ignores exactly that message; the None
check below it is the error handling spglib asks for.
@lllangWV
lllangWV force-pushed the fix/286-reduced-basis branch from f5cbb87 to 3c18b0c Compare October 4, 2026 21:42
@lllangWV
lllangWV merged commit 4de5cc0 into dev Oct 4, 2026
5 checks passed
@lllangWV
lllangWV deleted the fix/286-reduced-basis branch October 4, 2026 21:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant