Repository navigation
fix(fermi): draw and cut Fermi surfaces in a reduced basis on sheared reciprocal lattices - #317
Conversation
… basis (#302) snap_normal built its candidates with indices up to 4 in the given real basis, so a sheared basis of the same lattice could not snap a typed (111) normal and counted one orbit twice. Build them in the Delaunay-reduced real basis, shared with zone_face_steps through reduced_basis_steps, and keep reporting the indices in the given basis.
…nd clips bands away (#302)
…t and reuse two_band_mesh (#302)
…histogram peaks (#302)
…ich is what it does
…fted, unequal and 2D grids (#302)
…o its measured noise floor (#302)
…over the whole zone (#302) periodic_grid reads a Mesh's full uniform grid once and re-indexes it in a reduced basis of the k-point lattice; drawn_mesh gathers the stored samples onto the zone's bounding box plus one point. A reduced basis whose pad already covers the zone keeps today's pad bit for bit. fs.reciprocal_lattice is the user's basis; fs.ebs and its transforms are the drawn frame.
…'s limits (#302) _periodic_grid imports the Mesh for typing only, so it adds no import cycle; fs.reciprocal_lattice is an ndarray; the unused transformation_matrix argument to BrillouinZone is gone.
…attice reads the drawn mesh typed
… its row lengths (#302) The BiSb fixture's hexagonal rows differ by 3.2e-6 relative, so 1e-6 re-indexed it into the 120 degree setting; 1e-4 draws it as given.
…ies the gather discards (#302) The identity map runs the general path; n is one lcm over gcds; _take shares the arrays it replaces; expand_single_dimension widens the fresh drawn mesh in place; from_ebs seeds _periodic_grid with the grid it already parsed. Tests reuse drawn(), sphere and grid_fracs.
…s orbits (#302) C1: the cylinder cut that spans more than 16 given cells closes. B1: the fcc band given in b2' = b2 + 3 b1 cuts the reduced build's orbits. B2: an unequal grid on a sheared basis cuts one closed orbit. K1: a grid without a small reduced period says why orbits are not joined. R2 guards dev's cut on reduced bases, float for float.
periodic_bands tiles each band from the surface's PeriodicGrid into PeriodicBands: plane_orbits translates the tile by its lattice, a reduced basis of the k-grid, so MAX_REACH counts reduced cells, and takes the zone and the translate dedupe from the user's reciprocal lattice. A tile above CUT_TILE_BUDGET grids falls back to slice loops, and the area text says why. fs_plot.periodic_source is gone; the parse and GRID_TOLERANCE live in _periodic_grid. C1, B2 and K1 pass. B1 still fails: the fcc shear is drawn in another reduced basis, fixed next.
…duced bases tie (#302) b2' = b2 + 3 b1 of an fcc basis is 3 index steps from both (b1, b2, b3) and (b1, b1 + b2 + b3, b3), and the parallel-rows tie-break chose the second, so the surface and its cuts differed from the unsheared build by up to 1.5%. Ties now go first to the fewest changed entries. B1 passes (2.8e-17).
Fix round for item F (
|
| Test | at 88c0b92 | at e86ee21 | on dev c13166c |
|---|---|---|---|
test_standard_cells_snap_every_direction_with_given_indices_up_to_4: 578 directions on SrVO3, Au (POSCAR basis), fcc, bcc and two hexagonal cells, each turned 1e-4 rad |
fails: Au and fcc miss index-4 directions | passes | passes (guards dev) |
test_snapped_directions_do_not_depend_on_the_basis_or_the_orientation: 102 normals typed to 4 digits, plus 5 random normals, on each cell × {given, a3+6a1, doubly sheared, a2-2a1/a3+a1+2a2} × {as given, rotated} |
fails: 50 misses, the first Au fcc (3, 3, -1) in the given basis | passes | fails (first miss: SrVO3 cubic under a shear) |
test_fcc_cut_typed_near_cubic_113_or_223_counts_the_gamma_orbit_once, verifier's [113] repro |
snap None, [4.137121, 4.137122] |
snap (3, 3, -1), [4.1373050] |
passes (guards dev) |
| same test, [223] typed to 4 digits | snap None, [6.7138483] |
snap (3, 3, 1), [6.7139492], the area of the exact normal |
passes (guards dev) |
The verifier's scripts at e86ee21:
snaprot.py, 12 random rotations: [113], [223], [111] and [311] each give 1 orbit and 0 open curves, 12 of 12.snapreg.py: 578/578 directions snap on fcc-real, bcc-real, hexagonal and cubic. Before this fix the fcc-real case snapped 434/578.
Spacing and cost
-
SNAP_ANGLEstays at 3e-4. Distinct candidates are at least this far apart:Cell Smallest angle (rad) hexagonal, c/a = 1.633 4.41e-3 (15 × SNAP_ANGLE)fcc 7.13e-3 bcc 7.52e-3 cubic 9.01e-3 hexagonal, c/a = 3 2.39e-3 hexagonal, c/a = 4 1.64e-3 -
Rounding any candidate to 4 significant digits turns it by at most 8.4e-5 rad.
-
Long cells crowd the candidates: 5.7e-4 at c/a = 8 and 1.9e-4 at c/a = 15. The docstring and the PR body's Not verified section now say this.
-
snap_normalcosts 0.7 to 1.7 ms per call on these cells and up to c/a = 4. It builds 6k to 14k candidates and does not cache them.
Verify driver and docs
ref_orbits.pynow finds the successive minima by brute force in the given basis, with no spglib or pyprocar. It then lists the ball from there.features/fermi3d.mdstates the new rule.$H run ref-orbits data/examples/fermi3d/van-alphen: exit 0, 25 of 25 cuts agree. Worst area difference 4.95e-5, worst frequency difference 1.49e-6 relative. Run dirdata/verify-runs/20261009-183506-ref-orbits.
Gates at e86ee21
Run as ci.yml runs them, with base origin/dev = c13166c:
ruff_new_violations.py check exit 0
ruff F821,F822,F823,NPY201 exit 0
ruff_new_violations.py format exit 0
basedpyright (lock mode) exit 0 (0 errors, 0 warnings; baseline unchanged)
pytest -m "not data" exit 0 (2358 passed, 4 skipped)
red_green.py origin/dev exit 0 (63 added or changed tests)
test_cross_section_area.py -m data exit 0 (10 passed)
/simplify cleanups are in e86ee21:
_snap_candidatesusesbox_indicesfrom_periodic_grid.- The test file has one turn helper and one index helper.
- The cleanup skipped a per-lattice cache. It would save about 0.9 ms per slicer move and about 8 s of test time.
|
VERDICT: FAIL Reviewed SHA: The prior FAIL is fixed: fcc [113] and [223] snap again, in every orientation. A new case with the same failure remains: the rhombohedral primitive cell of Bi2Se3, Bi2Te3 and Sb2Te3. Why FAIL1. Snap regression on acute rhombohedral primitive cellsThe new candidate set keeps dev's set only on a cell given in a reduced basis. The rhombohedral primitive cell of the Bi2X3 topological insulators is not reduced: its rows are 9.84 Å long, and its successive minima are 4.14, 4.14 and 9.84 Å. Head drops 48 of the 578 directions dev snaps there. The lowest-index ones are hexagonal [1 0 3], [0 1 3], [1 1 3] and their symmetry partners. Each is 86.0-86.2 Å long, against head's radius of 4 Σλ = 72.5 Å. These are index-3 directions of the conventional hexagonal cell, just as cubic [113] was for fcc in the last round. A normal along one of them typed to 4 digits does not snap, and the cut counts one orbit twice. Smallest repro (synthetic, Gamma-centred
The predicate it fails: "the typed normal gives the exact normal's single orbit through Gamma". At 12 random orientations of the same cell, head gives 2 orbits in 13 of 13 cases and dev gives 1 in 13 of 13. In a sweep of hex [1 0 3], [1 1 3], [0 1 3] and [-1 0 3] at 7 isovalues and 4 offsets, typed and turned 1.5e-4 rad, head differs from the exact normal's orbit count in 17 rows. Dev differs in 0. Both trees double-count on hex [2 1 3], which neither snaps. Scope:
2. The cut depends on the cell's row order and on 1e-16 noise in the reciprocal lattice (code not touched by the fix round)Same cell, band and isovalue. Results along exact hex [1 0 3], at offset 0 and at offset 0.01 along the normal:
At 24^3, row order (2,0,1) at offset 0.01 gives At 32^3, head (all 4 row orders) and dev agree: one orbit, 0.2823 at offset 0 and 0.2825 at offset 0.01. I take that as the converged value, but I did not compute it independently. At 16^3 and 24^3, dev gives one orbit within 0.6% of it for every orientation and row order. My flood-fill plane reference is not a valid check for this cut. It matches an analytic sphere to 4e-4 and the [0 0 1] cut to 1%, but in the [1 0 3] plane the region inside the isovalue percolates, so these orbits are hole islands the flood fill does not measure. The total surface does not change with row order (0.092922 for all 4 orders at 16^3), so the difference is in the cut. Head's surface is also the better one here: dev's total area falls from 0.091 to 0.064 to 0.053 at 16^3, 24^3 and 32^3, which is the truncation this PR fixes, while head's converges (0.0929, 0.0922, 0.0920). The prior FAIL, rerun
Elongated cells: can the disclosed limit hurt a user?Slab cells with vacuum (hex c/a 5, 8 and 10, tetragonal c/a 8) and the Bi2Se3 hexagonal cell (c/a 6.9). The band is quasi-2D on a 24x24x4 grid. I typed 107 normals per cell to 4 digits: an angle sweep θ = 0-60° at φ = 0, 17 and 30°, 8 lattice directions, and 60 random normals. I compared head, dev, and head with SNAP_ANGLE = 0.
Judgement: up to c/a 10 the limit does not hurt, and it gives up at most 1.2e-4 relative area on angle sweeps. The cost is a note. Other checks
Claim status
Notes
|
…n dev snaps and counts the [1 0 3] orbit once (#302)
…beside the lattice's ball (#302)
… given indices up to 4 and the ball (#302)
…12 relative, not bit for bit (#302)
…ic area in every row order and under rounding (#302)
… move the drawn basis (#302)
…drawn-basis ties on integers only (#302)
…teger tie-break (#302)
…only usable drawn bases (#302)
… drawn as given (#302)
Fix round for the FAIL at e86ee21 (head 293a3cb)1. Snap candidates keep dev's set on cells that are not reducedThe candidates are now the union of dev's set (indices up to 4 in the given basis) and the basis-invariant ball (primitive lattice vectors no longer than 4 times the sum of the successive minima). So the set contains dev's set on every cell, and it is the same in every basis for everything inside the ball.
Red c8f4c38, green 54695e5. The existing invariance and fcc [113]/[223] tests stay green. Re-measured candidates (the 2. Drawn basis on the Bi2Se3 cell: root cause and fixRoot cause: marching cubes on that grid. There is no defect in the tiling, the joining or the dedupe.
Acceptance sweep (
Tests: 12 row-order x turn cases (red 15ff848: 4 failed with 0.3570-0.3572 against 0.2828), 3 sign cases, and 1 rounding-noise case. Every existing test in 3. CI flake
Gates and fixtures
Not done
|
|
VERDICT: PASS+NOTES Reviewed SHA: Both earlier FAILs are fixed. The Selling rule changes the drawing only for cells that are not reduced. On those cells, head matches dev wherever dev's pad covered the zone, and recovers the surface wherever dev's pad truncated it. The disclosed sheared-Bi2Se3 limit is far better than dev on that input class. It is worse than dev on 5 of 294 cut values (details below), and I judge that a note, not a regression. The earlier FAILs, rerun
Independent reference for the cuts ( Independent reference for areas ( Snap: invariance and the dev superset (lattices the tests do not use)18 lattices: tetragonal, orthorhombic, bct, rhombohedral at 75 and 40 degrees, monoclinic at 105 and 125 degrees, triclinic, base- and face-centred orthorhombic, hex c/a 1, 5 and 8, an orthorhombic slab, Bi2Se3, calcite, Bi, and fcc. Each lattice is given in its own basis and in 9 random unimodular bases (6 steps, entries up to ±3, permutations), each randomly rotated:
The Selling rule: which cells change path
What the move does, on nearest-image spheres (analytic 4 pi r^2, and cuts at 0.96 pi r^2) at 12^3 and 20^3:
The earlier wins still hold:
The disclosed sheared-Bi2Se3 limit, against dev and the referenceThe Bi2Se3 lattice given in 14 sheared real bases: the test's a3+6a1, a2-a1, a3-a1-a2, a double shear, and 10 random 4-step shears. Each runs at 16^3, 24^3 and 32^3, with 7 cuts per row ([1 0 3] at 0, 0.01 and 0.02; [0 0 1] at 0 and 0.01; [1 0 0] at 0 and 0.01) and the total area, all against the references above:
The 5:
On those same rows, dev's surface area is off by -1.2% (a2-a1, 16^3), -14% and -46% (a3-a1-a2, 16^3 and 24^3), and both shears reach -57% and -63% at 32^3. At 32^3, head is right on every cut in all 14 shears, apart from the [1 0 3] 0.02 case below, which the given cell shares with dev. The limit is real but narrower than dev's breakage on the same input: head is the better answer for that input in 157 of 162 places where they differ. Nothing else moved
Claim status (fix-round comment)
Notes
|
|
API note recorded after merge. Two changes in this PR break outside callers.
Default: no alias and no deprecation shim. To restore the old name for one release, add |
…ontract, and a check against local copies (#1) ## Why The fix for #49 (upstream PR `romerogroup#317`) failed independent verification twice. Each time, `snap_normal` or the drawn grid broke on a cell that dev handled. The builder's tests used only two or three sheared cubic cells. Seven test files each built their own small set of lattices, so a new test copied the nearest file and never met fcc primitive cells, acute rhombohedral cells, row reordering or 1e-16 noise. This PR gives tests one shared set of lattices, a contract that checks every basis-dependent result over all of them, and a check that blocks local copies. ## What changed - `tests/utils/lattices.py` is the only place test lattices are defined. It has 10 standard cells (including fcc and bcc primitive, hexagonal, Au, Bi2Se3 rhombohedral, an obtuse rhombohedral cell, monoclinic and triclinic) and `basis_variants()`. That generator yields 18 versions of each cell: shears, row orders, negated rows, a rotation and 1e-16 rounding noise. Seven test files now import from it, and every moved constant is bitwise unchanged. - `tests/pyprocar/core/test_basis_invariance.py` checks the contract over every cell and every variant (580 cases). It covers `snap_normal`, the drawn k-grid steps of `periodic_grid`, and the Brillouin zone against scipy's Voronoi cell. Expected values come from the cell itself, not from the code under test. - `tests/test_shared_lattices.py` is an AST check. It fails when a test defines its own copy of a shared cell, shear, `TURN` or lattice helper, and names the constant to import. CLAUDE.md gets a matching row in its rules table. ## Scope - This PR changes tests and CLAUDE.md only. No library code changes. - It does not fix the defect described below. That fix needs one deterministic way to pick the reduced basis, tracked on #59. ## Blast Radius Only the test suite changes. It adds about 6 s to the non-data run with `-n auto`, or 20 s run serially. A test that defines its own copy of a shared lattice now fails, which is the intended behaviour. ## Verification The new contract fails on both commits that failed verification on upstream `romerogroup#317`, and passes at the head. Each run was in a detached worktree, with only the two new test files copied in: ``` $H exec pytest tests/pyprocar/core/test_basis_invariance.py -n auto -p no:cacheprovider 88c0b92 (first FAIL): 95 failed, 479 passed fcc primitive misses cubic [223] and [113]; 122 of 578 directions lost e86ee21 (second FAIL): 18 failed, 556 passed Bi2Se3 misses 48 directions; drawn 6^3 grid moves with row order, a rotation and 1e-16 noise b08f930 (this PR): 575 passed, 8 xfailed ``` The lattice check fails with 47 hits across 7 files on dev's tree before the migration, and passes at the head. Its own tests keep dev's pre-migration lattice definitions as cases it must flag. They also keep cases it must not flag: a parser lattice, an identity matrix, 2π·I, sign triples and fractional coordinates. The CI gates all pass locally at `b08f9303`: - non-data pytest: 2958 passed, 4 skipped, 8 xfailed - both ruff new-violation gates and `ruff --select F821,F822,F823,NPY201`: clean - basedpyright in lock mode: clean, with no baseline changes - `red_green.py`: ok **A defect found on dev, not fixed here:** on the obtuse (110°) rhombohedral cell, the drawn k-grid depends on the order and signs of the cell's rows, because `_nearest_identity` breaks ties on index entries. Negating one row moves one band's Fermi surface area from 0.1304 to 0.1267 at 6³ (2.8%), and by 0.5% at 16³. These 8 cases are `xfail(strict=True)`, so they will fail loudly once the library is fixed. Recorded on #59. ## Not verified - I ran the `data`-marked tests only for the 7 changed test files (10 passed), not the whole data suite. CI does not run data tests.
Why
On a sheared reciprocal basis, pyprocar drew only part of the Fermi surface and cut cross sections into open curves. A
[0,1)grid on a hexagonal lattice lost the zone corners the same way. The k-points form one lattice of samples in any basis. This PR reads that lattice once, picks a reduced basis of it, and draws, cuts, and slices in that basis. It also fixes the smaller geometry bugs that #302 lists.Resolves #302
What changed
pyprocar/core/_periodic_grid.pyholdsperiodic_grid(ebs), which re-indexes the k-grid in a reduced basis of the k-point lattice. A given basis that is already reduced, or Selling-reduced (its rows, with some signs, and minus their sum meet pairwise at obtuse angles, as on the Bi2Se3 rhombohedral primitive cell), is drawn as given. Among equally near reduced bases the choice uses integers only, so 1e-16 of rounding in the reciprocal lattice cannot change it.PeriodicGrid.drawn_meshcopies the stored samples onto the box around the zone, andPeriodicGrid.tilegives the cut one period.FermiSurface.from_ebs,BandStructure2D.from_ebs, and_periodic_cut.periodic_bandsread it. No value is interpolated.shift_kpoints_to_fbzmoves k-points into the Wigner-Seitz zone. The old helperkpoints.wrap_to_first_zoneis nowkpoints.wrap_to_unit_cell, which names what it does.auto_orient_normals.brillouin_zone.clip_to_zonereplacesclip_surface, and a band clipped to nothing is dropped with a warning that names it.snap_normalsnaps to the directions with indices up to 4 in the given basis (dev's set) and to the primitive real-space lattice vectors no longer than 4 times the sum of the lattice's successive minima (from spglib's Niggli cell). The second set depends on the lattice only, so every basis and orientation of a lattice snaps it; the first keeps every direction dev snapped, also on cells that are not reduced.How it works
If the given basis is already reduced and dev's pad covers the zone,
drawn_meshreturnsebs.pad(padding)unchanged. That keeps every reduced fixture on dev's code path.Scope
Mesh.is_fbz,is_ibz, andget_kgridstay public.is_fbzandis_ibznow compare against the known grid size.Tradeoffs
MAX_REACHin tile cells.fs.ebs,fs.grid, andfs.transform_matrix_*describe the drawn frame.fs.reciprocal_latticeand the integer steps a user passes, such as toextend_surface, stay in the given basis.Blast Radius
Reduced bases whose pad covers the zone keep dev's output byte for byte. A Selling-reduced basis whose pad misses the zone, such as the Bi2Se3 rhombohedral primitive cell, is drawn in that basis on a box that covers the zone. Any grid whose 10-point pad misses the zone gets a new drawn box: sheared bases,
[0,1)grids with an axis above 20 points, fcc and bcc[0,1)grids from 16 points, and dense centred fcc and bcc grids. On a reduced basis this moves areas by about 1e-8 or restores truncated pockets. A bcc corner pocket goes from 0.180 to 0.251, against 0.283 analytic (verifier). A sheared basis gets the areas of the reduced basis.ElectronicBandStructureMesh.shift_kpoints_to_fbznow raises, because moved points break the grid. No library code calls it, and every caller ofwrap_to_unit_cellmoved with the rename.generate_band_isosurfaceschanges signature, and onlyFermiSurface.from_ebscalls it.Verification
The pairs come from one driver run with
verify.sh exec pythonon dev c13166c and on 77b940d, with synthetic Meshes only. The left label reads "main (before)" but showsdev. Each pair's setup is also a test in this PR.A. The surface on a sheared basis is complete. The sphere
|k|^2 = 0.1on the cubic lattice given with b2 = (3,1,0), on a 16x48x16[0,1)grid, has area 0.8273 on dev and 1.2424 at 77b940d. Dev draws 1.2424 when the same grid is given in the cubic basis with centred coordinates. Testtest_sphere_on_a_sheared_unequal_grid_has_the_reduced_area.D. A
[0,1)hexagonal grid draws the whole zone. K and K' cylinders on a 60x60x20[0,1)grid have area 0.2849 on dev and 1.3584 at 77b940d. Dev's centred grid gives 1.3584 too. Testtest_hexagonal_k_columns_on_a_unit_cell_grid_match_the_centred_grid.C. An orbit longer than 16 given cells closes. The plane through Gamma with n_z = 0.0953 cuts the cylinder
kx^2 + ky^2 = 0.1, given in b2 = (3,1,0), b3 = (-2,2,1). Dev reports 2 open curves. 77b940d reports one orbit of 3.2577, the same as dev in the cubic basis. Testtest_sheared_basis_closes_an_orbit_longer_than_sixteen_given_cells.B. Cross sections on a real DFT grid match the reduced basis. The proof script takes Au band 5 from the
fermi3d/van-alphenfixture (15^3 k-points), gives it in b2' = b2 + 3 b1, and cuts it with six random planes. On dev the sheared areas differ from the reduced build by up to 1.34. At 77b940d they agree within 3e-17, with equal open counts. Three of the six planes:Reduced inputs are unchanged. The
fermi3d.pyverify driver gives a byte-identicalsummary.jsonand 5 PNGs on dev and 77b940d. Thebs2d.pydriver onbands/2d-bandsgives a byte-identicalsummary.jsonand 3 PNGs.ref_orbits.pyonfermi3d/van-alphengives the same text for 25 of 25 cuts as at 69b9768, and no area differs from its reference by more than 1e-4.E to I. Each test below fails on dev and passes at 77b940d.
shift_kpoints_to_fbzlands in the Wigner-Seitz zone:test_shifted_points_lie_in_the_first_zone.snap_normaldoes not depend on the basis or orientation:test_doubly_sheared_basis_snaps_every_direction_with_cubic_indices_up_to_2,test_snapped_directions_do_not_depend_on_the_basis_or_the_orientation. Two tests guard dev's behaviour and pass on dev:test_standard_cells_snap_every_direction_with_given_indices_up_to_4(578 directions on 6 standard cells and the Bi2Se3 rhombohedral primitive cell) andtest_fcc_cut_typed_near_cubic_113_or_223_counts_the_gamma_orbit_once(one orbit, 4.137305, on the fcc primitive basis).test_2d_zone_face_normals_point_out_of_the_prism_at_any_energy,test_clipping_to_the_zone_keeps_graphene_bands_at_any_energy.test_a_band_crossing_only_outside_the_zone_is_dropped_with_a_warning.test_kgrid_is_the_known_grid_past_the_histogram_limit.CI gates at 77b940d, run as
.github/workflows/ci.ymlruns them:The
data-marked tests oftest_fermisurface.py,test_bandstructure2d.py,test_cross_section_area.py,test_surface_get_property.py, andtest_one_call_functions.pypass at 77b940d (112 passed, exit 0).Not verified
CUT_TILE_BUDGET = 16on a real DFT grid. A grid coprime to its shear that needs a larger tile gets unjoined slice loops and a note.bands/2d-bands, has a reduced basis, so it does not show the difference.SNAP_ANGLE= 3e-4. There, a normal typed far from any low-index direction can snap to a high-index one, turning it by at most 3e-4 rad.snap_normalbuilds its candidates on every call: about 1 ms up to c/a = 4 and on the Bi2Se3 cell, 8-10 ms at c/a = 8 and 15.