Skip to content

fix(fermi): draw and cut Fermi surfaces in a reduced basis on sheared reciprocal lattices - #317

Merged
lllangWV merged 66 commits into
devfrom
fix/302-sheared-basis
Oct 9, 2026
Merged

lllangWV merged 66 commits into
devfrom
fix/302-sheared-basis

Conversation

@lllangWV

@lllangWV lllangWV commented Oct 9, 2026 •

Copy link
Copy Markdown
Member

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

  • The new private module pyprocar/core/_periodic_grid.py holds periodic_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_mesh copies the stored samples onto the box around the zone, and PeriodicGrid.tile gives the cut one period. FermiSurface.from_ebs, BandStructure2D.from_ebs, and _periodic_cut.periodic_bands read it. No value is interpolated.
  • The Mesh stores its grid size instead of a guess from histogram peaks. shift_kpoints_to_fbz moves k-points into the Wigner-Seitz zone. The old helper kpoints.wrap_to_first_zone is now kpoints.wrap_to_unit_cell, which names what it does.
  • Zone normals come from pyvista's auto_orient_normals. brillouin_zone.clip_to_zone replaces clip_surface, and a band clipped to nothing is dropped with a warning that names it. snap_normal snaps 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

flowchart LR
  M["Mesh: k-points and bands in the given basis B"] --> G["periodic_grid(ebs): parse the grid once, pick a reduced basis of the k-point lattice"]
  G -->|"drawn_mesh(padding)"| D["drawn Mesh: samples copied onto the zone box"]
  D --> FS["FermiSurface.from_ebs: marching cubes, clip_to_zone"]
  D --> BS["BandStructure2D.from_ebs"]
  G -->|"tile(bands)"| T["one period of each band"]
  T --> P["PeriodicBands: lattice = tile, reciprocal_lattice = B"]
  P --> O["plane_orbits: translate by the tile, take zone and dedupe from B"]
Loading

If the given basis is already reduced and dev's pad covers the zone, drawn_mesh returns ebs.pad(padding) unchanged. That keeps every reduced fixture on dev's code path.

Scope

Tradeoffs

  • We rejected a pad by the zone's extent in the given basis. The box grows to 58 periods per axis, and marching cubes still runs on long thin cells. In the design round, sphere areas stayed off by 1.5% to 61%.
  • We rejected the fix(zone): reduce the reciprocal basis before building the Brillouin zone #295 round-2 attempt, which counted orbit reach in reduced cells and filtered each translate by its origin. It dropped translates that still cross the zone. Here the cut tiles the bands in the reduced basis and counts MAX_REACH in tile cells.
  • On sheared input, fs.ebs, fs.grid, and fs.transform_matrix_* describe the drawn frame. fs.reciprocal_lattice and the integer steps a user passes, such as to extend_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_fbz now raises, because moved points break the grid. No library code calls it, and every caller of wrap_to_unit_cell moved with the rename. generate_band_isosurfaces changes signature, and only FermiSurface.from_ebs calls it.

Verification

The pairs come from one driver run with verify.sh exec python on dev c13166c and on 77b940d, with synthetic Meshes only. The left label reads "main (before)" but shows dev. 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.1 on 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. Test test_sphere_on_a_sheared_unequal_grid_has_the_reduced_area.

dev (before) and PR (after): the sphere on a sheared basis loses a slab on dev and is whole in the PR

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. Test test_hexagonal_k_columns_on_a_unit_cell_grid_match_the_centred_grid.

dev (before) and PR (after): two of six K/K' columns on dev, all six in the PR

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. Test test_sheared_basis_closes_an_orbit_longer_than_sixteen_given_cells.

dev (before) and PR (after): the slicer reports 2 open curves on dev and one closed orbit in the PR

B. Cross sections on a real DFT grid match the reduced basis. The proof script takes Au band 5 from the fermi3d/van-alphen fixture (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:

plane  dev, sheared basis        reduced basis (dev and PR)   PR, sheared basis
0      0.1444 + 0.2114           0.3220                       0.3220
2      0.2901                    0.2114                       0.2114
5      1.3829                    0.0477 + 0.0462, 1 open      0.0477 + 0.0462, 1 open

Reduced inputs are unchanged. The fermi3d.py verify driver gives a byte-identical summary.json and 5 PNGs on dev and 77b940d. The bs2d.py driver on bands/2d-bands gives a byte-identical summary.json and 3 PNGs. ref_orbits.py on fermi3d/van-alphen gives 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.

  • E, shift_kpoints_to_fbz lands in the Wigner-Seitz zone: test_shifted_points_lie_in_the_first_zone.
  • F, snap_normal does 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) and test_fcc_cut_typed_near_cubic_113_or_223_counts_the_gamma_orbit_once (one orbit, 4.137305, on the fcc primitive basis).
  • G, zone normals point outward, so BS2D below 0 eV draws bands: test_2d_zone_face_normals_point_out_of_the_prism_at_any_energy, test_clipping_to_the_zone_keeps_graphene_bands_at_any_energy.
  • H, one empty band no longer aborts the surface: test_a_band_crossing_only_outside_the_zone_is_dropped_with_a_warning.
  • I, the Mesh reports its known grid size: test_kgrid_is_the_known_grid_past_the_histogram_limit.

CI gates at 77b940d, run as .github/workflows/ci.yml runs them:

ruff new-violation check and format    exit 0
ruff F821,F822,F823,NPY201             exit 0
basedpyright                           exit 0 (0 errors, 0 warnings)
pytest -m "not data"                   exit 0 (2354 passed, 4 skipped)
red_green.py origin/dev                exit 0 (60 added or changed tests, 45 fail on dev)

The data-marked tests of test_fermisurface.py, test_bandstructure2d.py, test_cross_section_area.py, test_surface_get_property.py, and test_one_call_functions.py pass at 77b940d (112 passed, exit 0).

Not verified

  • The first repro of C (9 of 40 near-corner cuts on U = [[0,-1,4],[2,-2,-5],[1,-2,2]] come back open) did not reproduce on dev, so no test pins it.
  • A general shear can land on a reduced basis other than the one the user means. Cut areas then agree only to marching-cubes accuracy, about 0.2% at 15^3 in the design round. A shear of a reduced basis returns to it exactly. On the Bi2Se3 lattice its three reduced bases are congruent, and marching cubes on them at 16^3 cuts the hexagonal [1 0 3] orbit as 0.357, or 0.01 above Gamma as two orbits, against one of 0.2828 on the analytic band; the given rhombohedral basis gives 0.281. A sheared Bi2Se3 basis lands on a reduced one. On isotropic pockets the reduced cells are about 25% more accurate than the rhombohedral one (mean 6.0% against 8.2% at 16^3).
  • No test runs CUT_TILE_BUDGET = 16 on a real DFT grid. A grid coprime to its shear that needs a larger tile gets unjoined slice loops and a note.
  • An unclipped BS2D on a sheared basis pads one reduced period, not dev's pad strip in the given basis. The only BS2D fixture, graphene in bands/2d-bands, has a reduced basis, so it does not show the difference.
  • On long cells the snap candidates crowd together: distinct ones are 4.4e-3 rad apart at hexagonal c/a = 1.633, 1.6e-3 at c/a = 4, and 1.9e-4 at c/a = 15, below 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_normal builds 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.
  • On dense centred fcc and bcc grids, the drawn box holds 1.571 times the points. Memory with projections was not measured.

… 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.
…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.
… 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).
@lllangWV

lllangWV commented Oct 9, 2026

Copy link
Copy Markdown
Member Author

Fix round for item F (snap_normal), after the FAIL verdict

The FAIL came from the snap candidates: indices up to 4 in spglib's Delaunay-reduced basis. fcc and some other lattices have several equally reduced bases, and spglib picks one based on the basis it is given. As a result, on the fcc primitive basis a normal typed near cubic [113] or [223] no longer snapped, and the cut through Gamma counted one orbit twice.

New rule. The candidates are every primitive real-space lattice vector t with |t| <= 4 (λ1 + λ2 + λ3), where λ1, λ2 and λ3 are the lattice's successive minima. These are the lengths of spglib's Niggli cell, the three shortest independent lattice vectors. I checked those lengths against a brute-force search on 300 random lattices: 0 mismatches.

Why this set:

  • It is fixed by the lattice alone, so a unimodular change of basis or a rotation leaves it unchanged.
  • In a reduced basis the basis vectors have lengths λ1, λ2 and λ3. By the triangle inequality, every direction with indices up to 4 in that basis is no longer than 4 Σλ. So on a standard cell, dev's whole candidate set is inside the new one.

The code is _snap_candidates and SNAP_REACH in pyprocar/plotter/_surface_plot.py, plus niggli_basis_steps in pyprocar/core/brillouin_zone.py.

Red and green

Tests in tests/pyprocar/plotter/test_cross_section_area.py. The test commit is 9d41b74 and the fix is 1b60b6d.

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_ANGLE stays 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_normal costs 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.py now 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.md states 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 dir data/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_candidates uses box_indices from _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.

@lllangWV

lllangWV commented Oct 9, 2026

Copy link
Copy Markdown
Member Author

VERDICT: FAIL

Reviewed SHA: e86ee2101be0cf24481be86e3e7bc0a46564f9d2. Base and current origin/dev are both c13166ce, and git merge-tree is clean. I ran everything in detached worktrees of e86ee210 and c13166ce, set up with verify.sh worktree-setup.

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 FAIL

1. Snap regression on acute rhombohedral primitive cells

The 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 [0,1) grid):

  • Real rows (Å), the textbook Bi2Se3 primitive cell (a = 9.841, α = 24.27°): [[2.068734, -1.194384, 9.546678], [0, 2.388768, 9.546678], [-2.068734, -1.194384, 9.546678]]. B = inv(real).T, grid 16x16x16.
  • Band: -Σ cos(2π k·h) over the in-plane steps h ∈ {r1-r2, r2-r3, r3-r1}, minus 0.35 Σ cos(2π k·r_i). Isovalue 0.8.
  • Normal: hex [1 0 3] (r1 - r2 + 3(r1 + r2 + r3)) typed to 4 digits, [0.024, -0.0417, 0.9988]. Origin 0.
  • Call: cross_section_areas(FermiSurface.from_ebs(mesh), normal, 0, B).
snap orbits (typed) orbits (exact normal)
dev (4, 2, 3) [0.280799] [0.280799]
head None [0.280857, 0.280858] [0.28087]

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:

  • Bi2Se3, Bi2Te3 and Sb2Te3 (α ≈ 23-24°) each lose 48/578 directions.
  • A synthetic α = 40° cell loses 6.
  • Calcite, LiNbO3, Al2O3 and Bi lose none.
  • The PR body's wording ("on a cell given in a reduced basis") is accurate. The fix-round comment's "on a standard cell, dev's whole candidate set is inside the new one" is contradicted.

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. _periodic_grid.periodic_grid picks the drawn basis with the _nearest_identity tie-break, and the 3-fold axis gives it equivalent choices. Taking B as inv(real @ R.T).T instead of B0 @ R.T changes B by 1.1e-16, the noise of rotating a POSCAR. That moves to_source from [[1,0,0],[0,1,0],[1,1,1]] to [[1,1,1],[0,1,0],[0,0,1]].

Results along exact hex [1 0 3], at offset 0 and at offset 0.01 along the normal:

Input, 16^3 grid head, offset 0 head, offset 0.01
exact B [0.28087] [0.28106]
B with 1.1e-16 noise [0.35718] [0.10501, 0.21311]
rows reordered (1,2,0) [0.35698] [0.10495, 0.21302]
rows reordered (2,0,1) [0.28075] [0.10478]

At 24^3, row order (2,0,1) at offset 0.01 gives [0.10514, 0.17698].

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

Check Outcome
fcc minimal repro ([113] turned 1.5e-4 rad) head snaps (3, 3, -1) and gives [4.137305], the same as dev. All 25 rows of snapeff.py match dev.
snaprot.py, 12 rotations [113], [223], [111] and [311]: 1 orbit and 0 open curves, 12 of 12, the same as dev.
snapreg.py 578/578 on fcc-real, bcc-real, hexagonal and cubic, the same as dev.
snapfam.py (fcc, cubic index up to 3) head 290/290, dev 188/290. Head loses none of dev's directions.
98-direction shear sweep (zone_snap.py) 98/98 under U and U2 on fcc, bcc, hexagonal and triclinic (6 misses before).
My invariance check 14 lattices the tests do not use (tetragonal, orthorhombic, bct, two rhombohedral, two monoclinic, triclinic, base- and face-centred orthorhombic, hex c/a 1, 5 and 8, an orthorhombic slab), each under 12 random unimodular changes of basis (6 steps, entries up to ±3, permutations) with random rotations. The Cartesian candidate sets are equal in every case. 480 snap calls per lattice agree on the Cartesian result and on the named indices: 0 mismatches.
Dev's set kept on standard cells Holds on 13 of those 14. The α = 40° rhombohedral cell loses 6 (see item 1).

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.

  • The orbit count never changed between head and dev, or between head and no-snap.

  • On c/a 5, 8 and 10, head snaps 2-3 sweep normals that dev does not. Each lands on a real rational direction near the typed angle: θ = 35°, φ = 0 goes to [7 0 2], and θ = 30°, φ = 30° to [10 5 3]. The area moves 1.1e-6 to 1.2e-4 relative, below the grid's marching-cubes error. Tetragonal c/a 8 and Bi2Se3 c/a 6.9 match dev exactly.

  • On hex cells from c/a 1.6 to 30, every direction with indices up to 4, typed to 4 digits, snaps to itself: 0 wrong, 0 unsnapped. Random 4-digit normals snap 0-2 times in 400.

  • Cost of snap_normal per call. Dev is 0.03 ms at every c/a.

    c/a 1.6 5 8 10 12 15 20 30
    head (ms) 0.9 2.2 4.1 5.1 7.2 10.9 16 44
  • The slicer's _slice_callback calls it on every plane-widget event, with no cache. A whole cut costs 11-14 ms at c/a 5-10, and mesh.slice 0.7-0.8 ms. Up to c/a 10 the slicer stays within a 16 ms frame. Past c/a 20 the snap alone exceeds a frame.

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

Check Outcome
CI gates as ci.yml runs them ($H exec, base origin/dev) ruff new-violation check exit 0 (21 files). Ruff F821/F822/F823/NPY201 exit 0. Ruff format exit 0. basedpyright: 0 errors, 0 warnings. pytest -m "not data": exit 0, 2358 passed, 4 skipped. red_green.py: exit 0.
-m data: fermisurface, cross_section_area, bandstructure2d, ebs, ibz2fbz, surface_get_property, one_call_functions head: 116 passed, exit 0. dev: 116 passed, exit 0. test_cross_section_area.py -m data alone: 10 passed, exit 0.
Real-fixture digests, one build at a time SrVO3 nsp/sp/nc, Au van-alphen and BS2D (graphene, both modes): digest.json is byte-identical between dev and head. This covers points, faces, drawn mesh, band areas, projected_sum, fermi_velocity, fermi_speed and 6 cuts each.
verify-pyprocar drivers fermi3d.py and bs2d.py: evidence identical. fermi2d.py: identical apart from the run path, with the same pre-existing step failing at both.
ref_orbits.py on van-alphen Exit 0, every section ok. 25 cuts: worst area difference 4.95e-5, worst frequency difference 1.49e-6 relative. Head's driver gives an identical cuts.json on dev and on head. Its random normals are at least 2.2e-3 rad from any lattice direction, so it never exercises the snap.

Claim status

  • Prior FAIL (fcc [113] and [223], rotations, sheared directions): confirmed fixed.
  • Snap candidates "fixed by the lattice alone", basis- and rotation-invariant: confirmed on 14 lattices x 12 random bases and rotations.
  • Dev's set kept "on a cell given in a reduced basis" (PR body): confirmed on reduced cells. The fix-round comment's "on a standard cell": contradicted on acute rhombohedral cells (item 1).
  • Spacing and cost numbers in the fix-round comment: consistent with my timings and with the "Not verified" entry. Typed directions with indices up to 4 still snap to themselves up to c/a 30.
  • ref_orbits 25/25, gates, and the 10 data tests: confirmed at e86ee210.
  • Reduced inputs unchanged: confirmed byte for byte on every real fixture.
  • Items A-E and G-I from the last round: the fix round touches only the snap and a rename (_box_indices to box_indices). The data tests and digests are unchanged, so I did not rerun the synthetic A-E and G-I scripts.

Notes

  • FAIL: snap regression on acute rhombohedral primitive cells (Bi2Se3, Bi2Te3, Sb2Te3); repro in item 1.
  • FAIL: the drawn-basis tie-break makes cuts on the Bi2Se3 primitive cell depend on row order and on 1e-16 noise in the reciprocal lattice, by up to 27% in area and in orbit count at 16^3 and 24^3; repro in item 2.
  • snap_normal rebuilds the candidates on every call: 2-5 ms at c/a 5-10, 44 ms at c/a 30, against 0.03 ms on dev.
  • pre-existing: fermi2d.py step obj_slice_scalars_data_property fails at both dev and head.
  • pre-existing: FermiSurface.from_code on fermi2d/bisb_monolayer raises "No Fermi surfaces were generated" at both dev and head.

…n dev snaps and counts the [1 0 3] orbit once (#302)
…ic area in every row order and under rounding (#302)
@lllangWV

lllangWV commented Oct 9, 2026

Copy link
Copy Markdown
Member Author

Fix round for the FAIL at e86ee21 (head 293a3cb)

1. Snap candidates keep dev's set on cells that are not reduced

The 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.

Check (Bi2Se3 rhombohedral primitive cell, a = 9.841 Å, alpha = 24.27°) e86ee21 293a3cb
dev's 578 directions, typed 1e-4 rad off, that snap under their own name 530 (48 missed) 578
hexagonal [1 0 3] typed to 4 digits, cut through Gamma, given basis [0.3572, 0.3572] one orbit, equal to the exact normal's
the same with the cell turned [0.2809, 0.2809] one orbit

Red c8f4c38, green 54695e5. The existing invariance and fcc [113]/[223] tests stay green.

Re-measured candidates (the SNAP_ANGLE docstring is updated). Bi2Se3: 9940 candidates, minimum spacing 3.4e-3 rad, 1.2 ms per call. cubic, fcc, bcc and hex c/a 1.633: same spacings as before (9.0e-3, 7.1e-3, 7.5e-3, 4.4e-3), 0.9 to 1.2 ms. c/a 8 and 15: 7.7 and 9.8 ms. Rounding to 4 digits turns a Bi2Se3 candidate by at most 7.8e-5 rad. ref_orbits.py and features/fermi3d.md use the same union (a22a574).

2. Drawn basis on the Bi2Se3 cell: root cause and fix

Root cause: marching cubes on that grid. There is no defect in the tiling, the joining or the dedupe.

  • Independent reference: the analytic band in the [1 0 3] plane. I sampled the plane's 2D lattice cell on an 800 x 800 grid, labelled the components with scipy.ndimage, filled the holes, and kept the orbits that meet the zone. No pyprocar code is involved. Result: one orbit of 0.2828 at offset 0 and 0.2830 at offset 0.01 (0.2829 and 0.2830 at 400 x 400). On [0 0 1] the same reference agrees with the code (0.0533 and 0.1047).
  • The given basis converges to that reference in 3D: 0.28215, 0.28256 and 0.28268 at offset 0 for 32^3, 48^3 and 64^3 (0.28227, 0.28273 and 0.28285 at offset 0.01).
  • All 144 reduced bases of this lattice have one cell shape. They make 3 distinct grids, (b1+b2+b3) plus two of the b_i, and the 3-fold axis permutes them. At 16^3 the [1 0 3] cut at offsets 0 and 0.01 is 0.2808/0.2809 on one grid, 0.2809/[0.1048 + 1 open] on the second, and 0.3572/[0.105, 0.2131] on the third.
  • VTK's own slice of the tiled marching-cubes surface gives the same 0.3572 and 0.105/0.2131 (rawslice.py, which uses no _periodic_cut code). So the cut faithfully reproduces a surface whose neck the third grid mis-resolves.
  • Across 14 hexagonal directions x 3 offsets, compared with the analytic reference: the given basis has 2/42 orbit-count mismatches at 16^3 (a 0.005 sliver) and a worst area error of 1.0%. At 24^3 it has 0/42 and 0.8%. Each reduced grid has 5-6/42 mismatches at 16^3, 1-2/42 at 24^3, and worst errors of 13-63%.
  • The compactness rule the brief suggested does not help here. The reduced grids are the more compact ones: edge sum 0.667 against 0.844, and a shorter longest face and body diagonal. All three are equally compact, so any compactness rule still lands on the bad one for some row orders. Trade-off: on isotropic pockets (nearest-image spheres r = 0.045 and 0.07) the reduced cells are about 25% more accurate (mean 6.0% against 8.2% at 16^3), and no grid miscounts orbits there.

Fix (5101048, 137434a):

  • A given basis that is Selling-reduced is drawn as given, like a Minkowski-reduced one. Selling-reduced means that with some signs on the rows, the rows and minus their sum meet pairwise at angles with cosine below -1e-4. The given Bi2Se3 cell has that form (the smallest margin is cos = -0.12), and every row order, orientation and sign pattern of it keeps that form.
  • _nearest_identity now breaks ties on the integer entries instead of the cosine. Rounding noise cannot change the choice: on a rhombohedral cell with alpha = 110°, the old tie-break flipped under TURN's 1e-16 rounding and the new one does not (red 44ee4e5).
  • The sign case comes from the /simplify altitude review. With (-b1, b2, b3), a cut still gave 0.3568 (red 61d9822).

Acceptance sweep (accept.py): 13 orientations (identity plus 12 random), 6 row orders, B = inv(rotated, permuted real).T, the exact [1 0 3] direction, offsets 0 and 0.01:

grid e86ee21 293a3cb
16^3 10/156 orbit-count mismatches, worst 63%, 3 drawn grids 0/156, worst 0.86%, 1 drawn grid
24^3 25/156, worst 12.7%, 3 drawn grids 0/156, worst 0.41%, 1 drawn grid

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 test_fermisurface_drawn_mesh.py and test_cross_section_area.py passes with its literals unchanged.

3. CI flake

test_reduced_basis_cut_is_unchanged now compares the areas at rel 1e-12 and checks that the open counts and orbit counts are equal. The guard marker stays (a5d3e6d).

Gates and fixtures

Check Result
ruff new violations, check and format against origin/dev exit 0, 0 (21 files)
ruff F821/F822/F823/NPY201 exit 0
basedpyright exit 0, 0 errors, 0 warnings, no baseline change
pytest -m "not data" exit 0, 2376 passed, 4 skipped (at 137434a; since then only a marker changed)
red_green.py origin/dev exit 0 at 293a3cb
data: test_cross_section_area, test_fermisurface, test_bandstructure2d, each run alone 10, 16 and 31 passed, each exit 0
fermi3d driver run 20261009-192946-fermi3d-r2b: summary.json, 5 PNGs and exit_code byte-identical to 20261009-163340-fermi3d-u2-after-final
ref_orbits (van-alphen) run 20261009-193000-ref-orbits-r2b: exit 0, 25 cuts, worst area diff 4.95e-5, worst frequency 1.49e-6; cuts.json identical to 20261009-183506-ref-orbits

Not done

  • snap_normal still rebuilds its candidates on every call; no cache.
  • A sheared basis of the Bi2Se3 lattice still re-indexes onto a reduced grid, and so can give the 0.357 cut on this band.

@lllangWV

lllangWV commented Oct 9, 2026

Copy link
Copy Markdown
Member Author

VERDICT: PASS+NOTES

Reviewed SHA: 293a3cb0cc2f580bcb1b4fd2164b6a28ed30d02c. Base and current origin/dev are both c13166ce, and git merge-tree is clean. I ran everything in detached worktrees of 293a3cb0, c13166ce (dev) and e86ee210 (the last FAIL), each set up with verify.sh worktree-setup.

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

Check e86ee21 293a3cb dev
fcc [113]/[223]: snapeff (25 rows), snaprot (12 rotations), snapreg, snapfam pass identical to e86, byte for byte snapeff identical to head
Bi2Se3/Bi2Te3/Sb2Te3/calcite/LiNbO3/Al2O3/Bi: dev's 578 directions, typed to 4 digits, that head leaves unsnapped 48/578 on Bi2X3 0/578 on all 7 n/a
Bi2Se3 hex [1 0 3] typed to 4 digits, cut through Gamma, 13 orientations 2 orbits in 13/13 snap (4, 2, 3), [0.280799] in 13/13 same as head
[1 0 3] cut, 4 row orders, 16^3 0.357 or 2 orbits on 2 of 4 orders [0.2808]..[0.28095] at offset 0, [0.2806]..[0.2807] at 0.01, every order identical to head
Same at 24^3 and 32^3 0.319 or 2 orbits at 24^3 one orbit within 0.4% at 24^3 and 0.2% at 32^3 identical to head
B with 1.1e-16 rounding noise (exact/noisy B, exact/noisy band values) 0.357 and 2 orbits all 4 identical, [0.2808]/[0.28064] identical
Drawn basis under 1e-16 noise: 6 lattices x 6 shears x 4 rotations moved in 11/144 0/144 n/a
Orbit count against the exact normal, bise_cut2 (200 rows) 0 differ 0 differ

Independent reference for the cuts (planeref3.py, numpy and scipy only). It samples one cell of the plane's 2D lattice and labels the components of both phases, periodically on a 5x5 tiling. It keeps the bounded ones, fills their holes, and flags the classes that meet the first zone (Wigner-Seitz test). Validation: on nearest-image disks it gives the analytic set of disk areas on 14 random lattices with random directions and offsets, plus the Bi2Se3 lattice along [1 0 3], with the orbit count right every time. On the Bi2Se3 band, the orbits that meet the zone are: [1 0 3] 0.2828 (offset 0), 0.2830 (0.01) and 0.1050 (0.02); [0 0 1] 0.0533 and 0.1047; [1 0 0] 0.0039 and 0.0041. These are stable from M = 300 to 600 and agree with the PR's 0.2828/0.2830.

Independent reference for areas (arearef.py): the coarea formula with a Gaussian delta. On spheres in 4 random lattices it matches 4 pi r^2 to 8.5e-9 at n = 200. Bi2Se3 band: 0.09159 to 0.09164 (n = 400 to 520).

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:

  • Dev's given-basis directions missing from head's candidates: 0.
  • Ball directions (reduced indices up to 3) missing in some basis: 0.
  • Those directions typed to 4 digits or turned 1.5e-4 rad (104,076 cases): 0 left unsnapped, 0 snapped to a wrong direction.
  • 300 random normals per lattice, compared across the 10 bases: 0 snap differently (48,600 calls). The given-basis extras never captured a random normal.
  • Cost: 9,940 candidates and 1.3 ms per call on Bi2Se3, 1.0 ms on hex c/a 1.633, 3.9 ms at c/a 8, 9.5 ms at c/a 15 and 41 ms at c/a 30.

The Selling rule: which cells change path

periodic_grid's to_source on 46 cells (16^3, plus 16x16x1 for six 2D cells), compared with e86ee21:

  • Unchanged: every reduced cell. That covers cubic, fcc (2 primitive forms), bcc (2 forms), hex at 60 and 120 degrees with c/a 0.6, 1.62 and 5, tetragonal, orthorhombic, base-centred orthorhombic, monoclinic at 95 and 105 degrees, C-monoclinic, 3 triclinic cells, rhombohedral at 60, 75, 90, 100 and 109.47 degrees, and 5 of the 6 2D cells. is_reduced_basis comes first in the or, so the Selling test never runs on them. Cells that are not reduced and not Selling-reduced (bct, body-centred orthorhombic, monoclinic at 125 degrees) also keep e86's basis.
  • Now drawn as given (Selling-reduced, not reduced): every acute rhombohedral primitive cell I tried. Those are Sb2Te3, Bi2Te3 and Bi2Se3 (including 2 sign patterns), a 33-degree cell, a 40-degree cell, calcite, Al2O3, LiNbO3 and Bi. A 2D oblique basis that is Selling-reduced but not Gauss-reduced also moves (not measured further).
  • Moved by the integer tie-break alone: face-centred orthorhombic and rhombohedral cells at 110 and 115 degrees. Sphere areas and cuts there move by 1e-4 relative at most.

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:

  • Head equals dev to every printed digit on all of these cells wherever dev's pad covered the zone, and it fixes dev's truncation elsewhere. At 20^3, off-centre spheres: Bi head -1.0% vs dev -27.6%, calcite -1.1% vs -20.2%, LiNbO3 -1.0% vs -19.9%.
  • Against e86's reduced drawing: equal or better at alpha >= 33 degrees (Bi -0.43% vs -0.45%, calcite -0.49% vs -0.70%, 40 degrees -0.33% vs -0.92%). Worse at alpha 23-24 degrees: Bi2Se3 at 20^3 gives an area of +5.0% vs -2.4% and a worst cut of 4.3% vs 3.4%. Off-centre, it gives +12.6% vs -5.2%.
  • Bi2Se3 band against the 0.0916 reference: head +7.0%, +3.5% and +2.4% at 16^3, 24^3 and 32^3. e86 gives +1.4%, +0.7% and +0.4%. Dev gives -0.4%, -30% and -42%; at 16^3 dev's truncation cancels the same marching-cubes excess.
  • Unequal grids on Bi2Se3, (12,16,20), (20,16,12) and (16,16,32): head's cuts equal dev's exactly, and e86 gave only open curves on the [1 0 3] cut.

The earlier wins still hold:

  • A, C and B (tight-binding), shifted grids, unequal grids and reduced bit identity: syn.py output is byte-identical between head and e86.
  • D, G, H and I: extra.py output is identical apart from the worktree paths.
  • E: zone_snap gives 0 Wigner-Seitz violations, and 98/98 snaps under both shears on 4 lattices.
  • B, Au fixture given in my shear U_F: au_shear.json is identical between head and e86. The area agrees with the given basis to 5.6e-9 and 8 cuts agree with diff 0.0. Dev cannot build it ("can not be converted to a 3d mesh").

The disclosed sheared-Bi2Se3 limit, against dev and the reference

The 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:

head dev
Cuts with one orbit within 3% (294) 217 65
Area within 3% (42 rows) 40 (+1.4%, +0.6% and +0.3% at 16, 24 and 32) 3 (-63% to +247%)
Head right, dev wrong 157
Dev right, head wrong 5

The 5:

  • a2-a1, 16^3, [1 0 3] at 0: head 0.357, dev 0.2801.
  • a3-a1-a2, [1 0 3] at 0.01: at 16^3 head gives [0.1048, 1 open] and dev 0.2804. At 24^3 head gives [0.177, 0.105] and dev 0.2819.
  • a3-a1-a2, 16^3, [1 0 0]: 0.00377 vs 0.00393 and 0.00397 vs 0.00404, which is 3.3% against 1.5%: grid error.

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

Check Outcome
CI gates as ci.yml runs them ($H exec, base origin/dev) ruff new-violation check exit 0. Ruff F821/F822/F823/NPY201 exit 0. Ruff format exit 0. basedpyright exit 0 (0 errors, 0 warnings). pytest -m "not data" exit 0 (2376 passed, 4 skipped). red_green.py exit 0.
-m data: fermisurface, cross_section_area, bandstructure2d, ebs, ibz2fbz, surface_get_property, one_call_functions head: 116 passed, exit 0. dev: 116 passed, exit 0.
Real-fixture digests, one build at a time SrVO3 nsp/sp/nc, Au van-alphen and BS2D on graphene (both modes): digest.json is byte-identical between dev and head. This covers points, faces, drawn mesh, areas, projected_sum, fermi_velocity, fermi_speed and 6 cuts each.
verify-pyprocar drivers fermi3d.py and bs2d.py: evidence identical. fermi2d.py: identical apart from the run path and timing, with the same pre-existing step failing at both.
ref_orbits.py head's driver gives exit 0 and every section ok: 25 cuts, worst area difference 4.95e-5, worst frequency difference 1.49e-6. Head's driver run on dev gives an identical cuts.json.
Side effects 0 files written into the calc copy in all 22 runs (+3 Au shear runs).
test_reduced_basis_cut_is_unchanged (CI flake) Now pytest.approx(rel=1e-12) with open counts equal; passes.

Claim status (fix-round comment)

  • Union candidates contain dev's set on every cell and are basis-invariant inside the ball: confirmed (18 lattices x 10 bases).
  • The Bi2Se3 table (578, one orbit given and turned): confirmed.
  • 9,940 candidates and 1.2 ms on Bi2Se3: confirmed (1.3 ms). Minimum spacing 3.4e-3 rad and 7.8e-5 rounding turn: not checked. c/a 8 and 15 at 7.7 and 9.8 ms: I measured 3.9 and 9.5 ms.
  • Reference 0.2828/0.2830 and [0 0 1] 0.0533/0.1047: confirmed with my own validated reference.
  • Convergence on the given basis: confirmed at 32^3 (0.28215). 48^3 and 64^3 not checked.
  • Three distinct reduced grids, and VTK's own slice agreeing at 0.357: not checked. Head reproduces 0.357 on the reduced grid that a sheared input lands on.
  • The Selling form is kept under row order, orientation and signs: confirmed for 4 row orders, 13 orientations and 2 sign patterns.
  • The integer tie-break is noise-proof: confirmed, 0/144 against e86's 11/144.
  • "Reduced cells about 25% more accurate on isotropic pockets": confirmed in direction. I measured larger gaps on Bi2X3 (about 2x at 20^3) and none at alpha >= 33 degrees.
  • Acceptance sweep 0/156: consistent with my subset (4 orders x 13 orientations x 2 offsets, one orbit in each). I did not run accept.py.
  • Gates, data tests, fermi3d driver and ref_orbits: confirmed at 293a3cb.
  • Not done (no cache; sheared Bi2Se3 can give 0.357): confirmed, and quantified above.

Notes

  • Judgement call: on sheared bases of the Bi2Se3 lattice, head is wrong where dev is right on 3 cut values beyond grid error. They come from 2 mild shears (a2-a1 and a3-a1-a2) at 16^3 and 24^3, against 157 where dev is wrong and head is right. Dev's surface on those rows is 1-46% short, and 57-63% short at 32^3. I class it as the disclosed limit, not a regression. A reader who weighs single cut values over the surface would call it a FAIL.
  • On alpha ≈ 23-24 degree rhombohedral cells (Bi2Se3, Bi2Te3, Sb2Te3), the Selling rule trades e86's surface-area accuracy for row-order and noise independence. Those cells now carry dev's marching-cubes error: Bi2Se3 band +2.4% at 32^3 against e86's +0.4%. Cells with alpha >= 33 degrees lose nothing.
  • The 2D path also moves: a 2D oblique basis that is Selling-reduced but not Gauss-reduced is now drawn as given. I did not measure it.
  • snap_normal rebuilds its candidates on every call: 41 ms at c/a 30.
  • pre-existing: on the given Bi2Se3 cell, the [1 0 3] cut at offset 0.02 reports [0.1043, 2 open] at 16-32^3 on both dev and head (reference: one orbit, 0.1050). On unequal grids the [1 0 3] cut at 0.01 gives 2 orbits on both.
  • pre-existing: the fermi2d.py step obj_slice_scalars_data_property fails at both dev and head.
  • pre-existing: FermiSurface.from_code on fermi2d/bisb_monolayer raises "No Fermi surfaces were generated" at both dev and head.

@lllangWV
lllangWV merged commit 2e875c8 into dev Oct 9, 2026
5 checks passed
lllangWV added a commit that referenced this pull request Oct 9, 2026
Resolve interpolate's conflict with #317: keep this branch's k-points and
spacing, and carry #317's stored grid size as fft_interpolated_shape of
the old size, so a single-point axis stays one point.
@lllangWV

Copy link
Copy Markdown
Member Author

API note recorded after merge. Two changes in this PR break outside callers.

  • pyprocar.core.kpoints.wrap_to_first_zone is renamed wrap_to_unit_cell, with no alias. The old name described a Wigner-Seitz reduction the function never did. Nothing in this repo calls the old name.
  • ElectronicBandStructureMesh.shift_kpoints_to_fbz now raises ValueError. Moving grid points into the first zone breaks the Mesh's box grid. On a plain ElectronicBandStructure it now does a true Wigner-Seitz reduction.

Default: no alias and no deprecation shim. To restore the old name for one release, add wrap_to_first_zone = wrap_to_unit_cell plus a DeprecationWarning in pyprocar/core/kpoints.py.

lllangWV added a commit to lllangWV/pyprocar that referenced this pull request Oct 10, 2026
…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.
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