Repository navigation
fix(zone): reduce the reciprocal basis before building the Brillouin zone - #295
Conversation
afc5443 to
e57378e
Compare
|
VERDICT: FAIL Reviewed SHA: e57378e (the branch has not moved). Base: origin/dev bf65596, which is also the merge base, and 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,
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 Smallest repro: Suggested fix: when Commands and key numbers
Acceptance items (#286)
Notes (not blocking)
|
|
VERDICT: PASS+NOTES Reviewed SHA: e57378e (base origin/dev bf65596, which is also the merge base, so the PR is not behind dev; Gates (all exit 0)
Red/green and mutation
Independent reference and live checksThe 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.
Drawn zone and face selection:
Reduced cells against origin/dev:
2D zone:
Real fixtures through the public API (
Cross sections on sheared bases, closed pockets only (4 cells x 15 shears x 8 planes, compared with the reduced basis at 64^3):
Notes (none blocking; origin/dev shares the mechanism in 1, 2 and 5)
Acceptance (#286)
|
|
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). Round 1 finding: fixed
Callers of
|
195f51c to
f95aa6c
Compare
|
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 Diff against current origin/devSix files changed:
Interaction with #299#299 adds Callers of
|
|
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. My round-2 FAIL is resolved
Gates at the head (all exit 0)
Mutants at the head (new tests plus the existing zone, cross-section and fs_plot tests; 121 tests)
Live checks against my independent referenceThe 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
Reduced cells against origin/dev
Notes (non-blocking)
Acceptance (#286)
|
f95aa6c to
c1c3914
Compare
|
VERDICT: FAIL Reviewed SHA: f5cbb87 (head of #295, based on origin/dev 5d6ae01, so head and head merged with dev are the same tree). 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.
Rebase c1c3914. The filter in f5cbb87 (
Red/green. I reverted only
Public API. #294's test_warn_user at head (all exit 0, 12 passed each).
Gates at f5cbb87 (
Notes (non-blocking):
|
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.
f5cbb87 to
3c18b0c
Compare
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_orbitsuses 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, soBrillouinZone.pointsand.boundsspanned outer cells too, andFermiPlotter.plotsized its arrows from them (fs_plot.py:199).plane_orbitsstarts 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 raisesValueErrorwhen the zone spans more thanMAX_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
scipy.spatial.Voronoion a monoclinic and a triclinic cell plus sheared versions.ebs.padadds 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.ebs.shift_kpoints_to_fbz, the basis dependence ofsnap_normal, and_fix_normals_direction.Blast radius
plane_orbitsoutput is bit-identical to origin/dev on 352 of 352 cuts on 22 reduced cells, including hexagonal, bcc and rhombohedral cells.BrillouinZone. The geometry is unchanged: the face polygons are bit-identical to origin/dev's on 22 of 22 cells..pointsnow 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 longestFermiPlotter.plotarrow 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).BrillouinZoneitself 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).spglib.delaunay_reducereturns None on extreme cells (vector-length ratio near 900), andzone_face_stepsthen raisesValueError("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_orbitsraises when the zone spans more than 16 cells of a very sheared basis, as above.spglib.delaunay_reduceemits oneDeprecationWarning(Set OLD_ERROR_HANDLING to false ...) per process. I left spglib's global error mode alone, because switching it would change error handling forstructure.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_brillouin_zone_matches_voronoi_for_any_basis_of_the_lattice(no.clean()), 6 casestest_longest_arrow_is_a_tenth_of_the_brillouin_zone_extent[cubic, sheared-cubic, fcc]test_shifted_grid_finds_the_line_through_a_zone_corner_below_the_start_cells([], 2) == ([], 1)test_sheared_basis_finds_the_orbit_at_a_zone_corner_six_cells_outThe shifted-grid test covers the
- 1in_start_steps'low. Dropping it fails the test withassert ([], 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.
Comparisons (scripts in the owner's scratchpad, rerunnable):
plane_orbitsis bit-identical on 352 of 352 cuts (348 with orbits or open curves), and theBrillouinZoneface polygons on 22 of 22.BrillouinZone.points,.boundsand faces on the 22 reduced cells and on 88 random unimodular shears (entries -3 to 3) of them,BrillouinZone2D, and theFermiPlotter.plotarrow length on cubic, sheared cubic and fcc are all bit-identical. The sheared points equal the reduced cell's zone vertices._periodic_cut.pyis 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/devandformat 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):The drawn zone for the sheared SrVO3 basis (round 1):
The blue box is the true SrVO3 zone. The black wireframe is
BrillouinZonefor the sheared basis.Closes #286