Skip to content

fix(qe): unfold QE phases and f orbitals with the core's harmonics - #305

Merged
lllangWV merged 10 commits into
devfrom
qe-sign-convention
Oct 4, 2026
Merged

lllangWV merged 10 commits into
devfrom
qe-sign-convention

Conversation

@lllangWV

@lllangWV lllangWV commented Oct 4, 2026 •

Copy link
Copy Markdown
Member

Why

A user who loads a symmetry-reduced QE calculation as a mesh (ElectronicBandStructureMesh.from_code("qe", ...), as the Fermi-surface plots do) gets two warnings on dev. The phases are dropped and the f shell is not rotated, so orbital-resolved d and f weights at the unfolded k-points are wrong. Against a QE nosym run, V eg weights are off by 0.30 and La f weights by 1.0.

There are two causes:

  • Unknown f labels. Since fix(core): check projection axes against bands and structure, and give every parser its orbital names #298 the QE parser names orbitals as projwfc.x prints them. ORBITAL_ALIASES (pyprocar/core/ebs.py:2096) does not map the three f labels fzx2-zy2, fx3-3xy2 and f3yx2-y3. As a result, unrotated_orbitals reports f as a partial shell, and ibz2fbz drops the phases (ebs.py:2324).
  • Harmonic signs. QE's real harmonics carry the sign (-1)^|m|, and the core's carry none. The parser passes the phases on unchanged (pyprocar/io/qe/parser.py:690), so once the phases are kept they unfold with wrong signs. QE 7.5 upflib/ylmr2.f90 sets the sign at line 78 (ylm(ig,4) = -sent/sqrt(2)) and line 94 (the minus sign in the Q(l,l) recursion). Lines 125 and 129 multiply by cos(m phi) and sin(m phi). projwfc.x's m = 1, 2, 3, ... is |m| = 0, 1, 1, 2, 2, ..., so px, py, dxz, dyz, fxz2, fyz2, fx3-3xy2 and f3yx2-y3 have the opposite sign.

What changed

  • ORBITAL_ALIASES maps the three QE f labels to the core's fzx2, fx3 and fy3x2.
  • QEParser.position_gauge_phase multiplies the phases by the harmonic signs (_core_harmonic_signs) and the Bloch factor in one pass. The Bloch factor still applies when no projwfc.x orbitals are known.
  • ElectronicBandStructureMesh.pad drops projected_phase. Kept QE phases made the Fermi-surface path pad them (generate_band_isosurfaces, pyprocar/core/fermisurface.py:1016, and BandStructure2D.from_ebs, pyprocar/core/bandstructure2D.py:549), and nothing reads phases on a padded mesh. The padded copies were also wrong: phases with exp(i k.(R + tau)) Bloch sums are not periodic in k, so a copy at k + G needs exp(-2 pi i G.tau). The mesh from ElectronicBandStructureMesh.from_code and the original_ebs of a FermiSurface keep their phases.

Scope

  • Collinear QE meshes now keep their phases. ibz2fbz rotates s, p, d and f on every QE mesh, non-collinear included.
  • Non-collinear QE phases are still dropped by design (spd_phase is None for spinors).
  • The Abinit PROCAR phase sign convention is not checked here.

Fermi-surface memory

Peak RSS (resource.getrusage(RUSAGE_SELF).ru_maxrss, GiB) and wall time of FermiSurface.from_code("qe", data/codes/qe/7.2/SrVO3/<mag>/fermi), 3 runs each, one job at a time, inside bwrap with the data read-only:

fixture origin/dev 4de5cc0 round 1 ed5c0ab this head
spin-polarized-colinear 3.60 GiB, 2.90 s 9.23 GiB, 6.6 to 7.0 s 3.78 to 3.79 GiB, 3.4 to 3.8 s
non-spin-polarized 2.01 GiB, 0.97 to 1.03 s 4.85 GiB, 2.85 to 2.92 s 2.11 to 2.12 GiB, 1.22 s

Memory spread across runs is under 0.01 GiB. The round-1 times ran under a load average of about 8; the dev and head rows ran back to back at about 3. All three builds draw the same surfaces (sha256 of fs.points equal, 3000 and 1540 points).

What is left against dev is the work this PR adds on purpose. ElectronicBandStructureMesh.from_code takes 0.47 s against 0.18 s on non-spin-polarized, and cProfile puts the difference in _turn_projections (0.43 s against 0.04 s), which now mixes phases into the d weights. FermiSurface.from_ebs takes 0.79 s on both. The 0.10 and 0.18 GiB of extra memory match the phase array the unpadded mesh keeps (complex128 [4096, 25, nspin, 5, 16], 0.12 and 0.24 GiB).

Blast Radius

The sign and alias changes touch only QE phases and names that no other parser uses. VASP names (fy3x2, fx3, fzx2) are not affected. Weights from QE path calculations do not change, because the flip changes only signs, and weights are |c|^2. The pad change applies to every code: a padded mesh (the ebs of a FermiSurface or BandStructure2D) has no projected_phase, which also saves memory on VASP LORBIT=12 meshes.

Verification

  • Independent reference. I made QE 7.5 runs of SrVO3 and spin-polarized LaVO3 at 6x6x6: one IBZ run (48 operations, 20 k-points) and one nosym run (216 k-points) from the same SCF density. The runs, the scripts and the results are in ~/Documents/lllangWV-Projects/DFT/pyprocar-293-qe-sign. validate.py checks the reference without pyprocar:

    • At the IBZ k-points the IBZ and nosym band energies agree to 1.1e-12 eV (SrVO3) and 4.8e-10 eV (LaVO3). At their symmetry images they agree to 5.5e-6 eV and 1.3e-5 eV, the nscf convergence. (Round 1 said 1e-9 eV for both: validate.py converted the Rydberg energies of atomic_proj.xml with the Hartree factor and compared only the IBZ k-points. Both are fixed there.)
    • projwfc.x's printed weights match atomic_proj.xml to its print precision.
    • Under all 48 cubic operations, the nosym shell weights are symmetric to 1.8e-4 (SrVO3) and 3.3e-4 (LaVO3).
  • Unfolded IBZ against nosym (compare_all.sh). The table gives the maximum absolute difference over all degenerate-band groups (1 meV) below the top four bands: bands 1 to 26 of 30 for SrVO3 and 1 to 31 of 34 for LaVO3 (TOP_MARGIN=3 gives the same numbers). With LaVO3's band 32 included (TOP_MARGIN=2 python compare.py lavo3 head_top2), the all atom-pair figure is 2.5e-3. The top of a truncated band set is unconverged, and the LaVO3 nosym nscf ran with conv_thr = 1e-8 against 1e-10 for the IBZ nscf; the SrVO3 inputs differ only in nosym and noinv. The weight and intra-atom columns list s, p, d and f.

    system code phases weights intra-atom phase products all atom-pair phase products
    SrVO3 dev dropped, 2 warnings 5.5e-7, 1.8e-5, 0.29, 0 dropped dropped
    SrVO3 this PR kept, no warning 5.5e-7, 1.8e-5, 3.0e-5, 0 5.5e-7, 1.8e-5, 3.0e-5, 0 3.0e-5
    LaVO3 dev dropped, 2 warnings 3.9e-5, 2.9e-4, 0.30, 1.0 dropped dropped
    LaVO3 this PR kept, no warning 3.9e-5, 2.9e-4, 2.3e-4, 2.1e-4 3.9e-5, 2.9e-4, 2.3e-4, 2.1e-4 2.9e-4
    LaVO3 this PR without the flip kept same as this PR 3.9e-5, 1.4, 0.82, 0.95 1.4
    LaVO3 this PR without the aliases same as dev

    Without the flip the weights still match, because cubic operations only permute signed orbitals. The phases do not match.

  • Tests. test_qe_phase_convention.py::test_qe_phases_unfold_to_the_coefficients_at_each_grid_point goes through QEParser.ebs with QE-signed coefficients of a known field on a 4x4x4 cubic grid.

    • On dev it fails with UserWarning: projected_phase is dropped (the red-green job agrees).
    • With the flip removed, it fails with a phase-product difference of 0.48.
    • With the aliases removed, it fails as on dev.
    • Without the Bloch-factor fix, the existing test_ebs_phases_use_bloch_sums_over_atom_positions fails.

    The data test test_qe_mesh_rotates_every_orbital_and_keeps_collinear_phases loads the three QE SrVO3 fermi meshes. On dev it fails on the two warnings. With this PR there is no user warning, and the two collinear meshes keep their phases.

    The data test test_qe_mesh_bands_are_eigenvectors_of_their_little_group guards the flip on the real fixtures. On the two collinear meshes, each nondegenerate band (gap over 1e-3 eV) with V weight over 0.05 must be an eigenvector of the orbital rotation of every cubic operation that fixes its k-point. V maps onto itself up to a lattice vector, so the Bloch factor is one common phase. At this head the max residual is 3.6e-4 (non-spin-polarized) and 4.2e-4 (spin-polarized) over 52466 and 104884 non-identity checks. With _core_harmonic_signs returning ones it is 1.0 and both cases fail. On dev the phases are dropped, so it fails on projected_phase is None.

    test_fermisurface_phases.py::test_fermi_surface_pads_the_projections_but_not_the_phases builds a 10x10x10 mesh with phases and calls FermiSurface.from_ebs(ebs, padding=2). The padded mesh has projected of shape (14**3, 1, 1, 1, 1) and no projected_phase, and the input mesh keeps exp(2 pi i kx). At ed5c0ab it fails: the padded mesh holds a (2744, 1, 1, 1, 1) phase.

  • Gates at 8e35d37 (verify.sh exec): pytest -m "not data" -n 8 2010 passed, 2 skipped; pytest -m data -n 4 408 passed, 1 skipped (origin/dev: 403 passed; the 5 extra are this PR's data cases); basedpyright 0 errors; ruff_new_violations.py check and format ok; ruff F821/F822/F823/NPY201 ok.

Refs #293

@lllangWV
lllangWV force-pushed the qe-sign-convention branch from 55391e3 to ed5c0ab Compare October 4, 2026 22:17
@lllangWV

lllangWV commented Oct 4, 2026

Copy link
Copy Markdown
Member Author

VERDICT: PASS+NOTES

Reviewed SHA: ed5c0abacfa75cb119276debdd2a9aec46aea02e (base origin/dev 4de5cc0, which is also the merge base, so the merge with current dev is trivial). Lane: Audit + regression. Neither branch moved during the review.

What I ran

I used detached worktrees at the head, at origin/dev, and at the middle commit 85c30d1, each set up with verify.sh worktree-setup and run on the shared dev env. Every library run happened inside bwrap --ro-bind / /, with only the worktree's .tmp (or the worktree itself) writable, so the shared data/ was read-only.

  • Full -m data suite (pytest tests -c .config/.pytest.toml --rootdir . -n 4 -m data -q -p no:cacheprovider): head 406 passed, 1 skipped, exit 0; origin/dev 403 passed, 1 skipped, exit 0. The +3 are the new parametrized data test. No new failure.

  • gh pr checks 305: format, lint, red-green, test and typecheck all pass.

  • Every QE fixture (data/codes/qe/7.2/SrVO3/{non-spin-polarized,spin-polarized-colinear,non-colinear}/{bands,dos,fermi}) went through get_parser("qe") (spd_phase, position_gauge_phase, spd, orbital_names, orbital_shells) and from_code (Path for bands, Mesh for fermi, DOS for dos). I compared head and origin/dev array by array.

    • spd_phase, spd, bands, kpoints, all DOS arrays, path projected, and all non-collinear arrays: identical (max diff 0). The orbital names and orbital_shells (s, p, d, f) are also identical.
    • position_gauge_phase and path projected_phase: they differ by up to 2.31, but max|head - dev * (-1)^(m//2)| = 0 exactly. The only change is the intended sign flip on px, py, dxz, dyz, fxz2, fyz2, fx3-3xy2 and f3yx2-y3.
    • Collinear fermi meshes: on dev, projected_phase was dropped with 2 warnings. At head it is kept, [4096,25,1|2,5,16] complex128, with no warnings. |phase|^2 == projected to 1e-15. Mesh projected changes only in dz2 and dx2-y2, by up to 0.308 (the eg fix). s, p, t2g and f are unchanged (<1.4e-15), and every shell sum is unchanged (<1.8e-15). The SrVO3 fixture has zero f weight, so it does not exercise the f rotation; only the synthetic unit test covers f.
    • Non-collinear fermi mesh: identical arrays. The f "not rotated" warning is gone, and the phase stays None as designed.
  • Independent sign check (not using the PR's reference). At every IBZ k of both collinear fermi fixtures, for every non-identity cubic operation that fixes k, I took each nondegenerate band (gap >1e-3 eV) with V p or d weight >0.05. Its V coefficients must be an eigenvector of the core's orbital_rotation. V sits at the cell centre, so lattice and Bloch factors reduce to one common phase.

    • Head convention: 2988 + 5976 tests, max residual 3.6e-4, and none above 0.05.
    • Dev convention (QE signs): max residual 1.0, with 254 and 508 failures respectively.
    • So the flip is right, and the check can tell the two conventions apart.
  • VASP, Abinit and Elk unchanged. I loaded the following at head and dev:

    • codes/vasp/6.4/SrVO3/*/fermi and non-spin-polarized/bands
    • examples/fermi3d/{non-spin-polarized,spin-polarized}
    • examples/bands/unfolding/supercell, the only fixture with phases (projected_phase [150,80,1,24,9])
    • codes/abinit/9.6/Fe/*/bands
    • codes/elk/6.3/SrVO3/*/bands

    All bands, projected, projected_phase, names and shells are identical (max diff 0), with no warnings changed.

  • Alias collisions. Only pyprocar/io/qe/projwfc/projwfc_out.py:31 emits fzx2-zy2, fx3-3xy2 and f3yx2-y3. VASP, Abinit and procarparser use fy3x2/fxyz/fyz2/fz3/fxz2/fzx2/fx3, Elk uses Y{l}{m}, and Lobster uses p_y, d_xy and so on. None of these overlap the alias keys. ORBITAL_ALIASES is read only by _canonical_orbital_names (ibz2fbz). orbital_shells and shell-letter selection (atomic_orbital_index.py, scripts/_selection.py) do not use it and did not change.

  • Unfold on QE paths. The unfolder pairs only equal orbital indices, so a per-orbital sign cancels. On real 2x1x1 (10 atoms) and 2x2x2 (40 atoms) SrVO3 supercells with random phases, the weights are identical under the flip (max diff 0.0).

  • Data test is read-only. The PR's test file passes inside the sandbox with data/ read-only: 4 passed. I compared a snapshot of data/codes and data/examples (path, mtime, size, mode; 2100 entries) taken before both data suites and all my runs with one taken after: no difference. No pkl files were written.

  • Red side. The PR's test file against origin/dev's library: 4 failed. The unit test fails on UserWarning: projected_phase is dropped. The data cases fail on the warning list.

  • Commit messages. The ed5c0ab claim holds: at 85c30d1, test_qe_parser.py::test_ebs_phases_use_bloch_sums_over_atom_positions fails (1/4 mismatched), and it passes at head. The other messages match the diff and my numbers (eg off by about 0.3 on dev).

Findings (none blocking)

  1. Memory and time regression in the QE Fermi-surface path (non-blocking, significant). Kept collinear phases now flow through generate_band_isosurfaces → ebs.pad(padding=10, inplace=False) (pyprocar/core/fermisurface.py:1016, core/ebs.py:1850). That step deep-copies and pads every property, the complex phases included. After ibz2fbz, nothing on a mesh reads projected_phase: its consumers are ibz2fbz and the path-only Unfolder.
    • FermiSurface.from_code("qe", .../spin-polarized-colinear/fermi) peak RSS goes from 3.77 GB (dev) to 9.68 GB (head), and time from 3.1 s to 7.4 s.
    • On non-spin-polarized it goes from 2.10 to 5.08 GB, and 1.0 to 3.1 s.
    • FermiHandler(...).plot_fermi_surface(mode="parametric") shows the same 3.77 → 9.68 GB. The PNGs are identical.
    • Larger QE meshes that fit on dev can run out of memory at head. VASP LORBIT=12 meshes already pay this cost.
    • Suggested fix (here or as a follow-up): drop projected_phase before pad, or after ibz2fbz in the mesh from_code.
  2. Owner note, semicore cross terms (pre-existing, out of scope). QEParser.spd_phase adds the amplitudes of radial channels with the same (l, m) (pyprocar/io/qe/parser.py:688). On non-spin-polarized/bands, |c_4s + c_5s|^2 differs from projwfc.x's sum |c|^2 by up to 0.48 (Sr s), 0.36 (Sr p) and 0.24 (V s). Dev has the same weights. The PR keeps them consistent: images get the coherent rotation of the same summed amplitude. This is worth filing separately.
  3. Owner note, position-gauge phases are not k-periodic. pad and expand_kpoints_to_supercell_by_axes copy phases to k+G without the exp(-2πi G·τ) factor, so padded mesh phases are wrong. No consumer reads them today; finding 1's fix would remove them.
  4. Owner note, Abinit phase signs. Not checked. No Abinit fixture has phases, and the diff does not touch the Abinit path.
  5. Test coverage. test_qe_mesh_rotates_every_orbital_and_keeps_collinear_phases checks only warnings, that phases are present, and n_kpoints. It would still pass with the sign flip reverted. Only the synthetic unit test guards the flip.
  6. Pre-existing, unrelated (same on dev): ebs.unfold on the spin-polarized QE path raises operands could not be broadcast together with shapes (155,25,2,80) (155,25,1,2). The cause is norm[:, :, None] in pyprocar/utils/unfolder.py:61. Also, unmatched translations default to basis 0 (trans_indices initialized to zeros), so a non-supercell input gives wrong weights silently.

@lllangWV

lllangWV commented Oct 4, 2026

Copy link
Copy Markdown
Member Author

VERDICT: PASS+NOTES

Reviewed SHA ed5c0ab (origin/dev 4de5cc0 is an ancestor, so head equals head merged with dev). Lane: Live + red/green + gates. Independent verifier; I did not write this PR.

Sign convention against QE source. I fetched upflib/ylmr2.f90 from gitlab.com/QEF/q-e at tag qe-7.5; it is byte-identical to the copy in the owner's reference dir, and PP/src/projwfc.f90 (label table, line 301) is identical too. I ported ylmr2 line by line to numpy and evaluated it at 400 random unit vectors (all directions, wider than the test's 4x4x4 grid). For every l = 0..3 orbital, QE's harmonic divided by the core's real_harmonics (via ORBITAL_ALIASES) is a constant: -1 for px, py, dxz, dyz, fxz2, fyz2, fx3-3xy2, f3yx2-y3 and +1 for the other 8. The residual is under 1.3e-15. This equals (-1)**(m // 2) in all 16 cases, and the three new aliases map to the right core harmonics (fzx2-zy2 = z(x^2-y^2) = fzx2, fx3-3xy2 = fx3, f3yx2-y3 = fy3x2).

Reference validated from raw atomic_proj.xml, without pyprocar. I used my own code on a copy that leaves out the wavefunctions.

  • IBZ eigenvalues vs nosym eigenvalues at every image R k of the 48 cubic operations. The stars cover 216/216. Max |dE| is 5.5e-6 eV for SrVO3 and 1.3e-5 eV for LaVO3 over bands 1 to 33. LaVO3's top band 34 differs by 0.08 eV because the top of the band set is truncated.
  • Transformation law on the nosym run alone. P(Rk) = U P(k) U^+ per degenerate group (10 meV grouping), where U is the atom permutation, the rotation of my own textbook real harmonics, and the position-gauge factor exp(+2 pi i G.tau). Over 48 operations and 216 k:
    • With QE coefficients times (-1)^(m//2), the residual is 1.5e-4 (SrVO3) and 2.9e-4 (LaVO3).
    • With raw QE coefficients it is 1.0 (SrVO3) and 0.98 (LaVO3), so the flip is required.
    • Control: raw coefficients rotated with ylmr2's own harmonics give 1.5e-4 and 2.9e-4.
    • Without the position gauge it is 0.89 and 0.83.
      The real data therefore confirm the flip independently of ibz2fbz.

Public API, unfolded IBZ vs nosym. My own script (not compare.py) calls ElectronicBandStructureMesh.from_code("qe", ...) on private copies. It matches k mod G with c(k+G) = exp(-2 pi i G.tau) c(k) and compares group-summed density matrices over 10 meV groups. Groups that touch the top three bands are left out (see note 2). Weights and intra-atom columns list s, p, d, f.

system build warnings weights intra-atom all atom pairs
SrVO3 dev 2, phase dropped 5.5e-7, 1.8e-5, 0.29, 0 n/a n/a
SrVO3 head none 5.5e-7, 1.8e-5, 3.0e-5, 0 same 3.0e-5
SrVO3 head without flip none same as head 5.5e-7, 1.3, 0.83, 0 1.3
SrVO3 head without aliases 2, as dev as dev n/a n/a
LaVO3 dev 2, phase dropped 3.9e-5, 2.4e-5, 0.30, 1.0 n/a n/a
LaVO3 head none 3.9e-5, 2.4e-5, 2.3e-4, 2.1e-4 same 2.3e-4
LaVO3 head without flip none same as head 3.9e-5, 1.4, 0.82, 0.95 1.4
LaVO3 head without aliases 2, as dev as dev n/a n/a

The head residuals are within the reference's own symmetry spread (2.9e-4). Running pyprocar wrote no files into the calc copies.

Red/green and mutants.

  • The new test file on origin/dev's library has 4 failures. The synthetic test fails on UserWarning: projected_phase is dropped, and the 3 data cases fail on the 2 warnings.
  • At head, the new file plus tests/pyprocar/io/qe and test_ibz2fbz.py give 22 passed.
  • No flip: the synthetic test fails, phase-product max diff 0.4775.
  • No aliases: the synthetic test and all 3 data cases fail.
  • No Bloch factor without projwfc output: test_ebs_phases_use_bloch_sums_over_atom_positions fails, diff 1.414.
  • Two extra mutants are also caught: (-1)**m in place of (-1)**(m//2), and position_gauge_phase returning None.

Gates at head. All of these ran through verify.sh exec with -n 4.

  • pytest -m "not data": 2009 passed, 2 skipped.
  • -m data: 406 passed at head, 403 at dev (the 3 new cases make the difference), no new failure.
  • basedpyright: 0 errors.
  • ruff_new_violations check and format vs origin/dev: ok.
  • ruff F821/F822/F823/NPY201: ok.
  • red_green.py origin/dev: ok.
  • gh pr checks: format, lint, red-green, test and typecheck pass.

Notes (none blocking).

  1. PR body, "The IBZ and full-grid band energies agree to 1e-9 eV". This holds only at the IBZ k-points themselves. At symmetry images the independently computed nosym eigenvalues differ by up to 1.3e-5 eV. validate.py converts atomic_proj.xml energies, which are in Ry (Fermi 1.1945 Ry = 16.25 eV), with the Hartree factor 27.211. The script is outside the repo.
  2. The LaVO3 figure of 2.9e-4 in the body and in features/parsers.md holds only below the top three bands. With band 32 of 34 included, all-pairs reaches 2.5e-3. The same 2.5e-3 appears at the IBZ k-points with no rotation, so it is reference noise, not this PR. The LaVO3 nosym nscf also used conv_thr = 1e-8 against 1e-10 for the IBZ run; SrVO3's inputs differ only in nosym/noinv.
  3. The synthetic test checks phase products only within each shell on one atom. Inter-atom gauge coverage comes from the existing Bloch-sum test and the data tests.
  4. Environment. The main checkout's pixi.lock differs from origin/dev's, so local gates ran on a drifted env. CI is green.

@lllangWV

lllangWV commented Oct 4, 2026

Copy link
Copy Markdown
Member Author

VERDICT: PASS+NOTES

Reviewed SHA: 8e35d37e4305377bae3a197b060f83bc5d0e5569. Lanes: round-2 delta, both lanes (audit + regression, and live + red/green + gates). The delta is 72ddce2..8e35d37. origin/dev is 4de5cc01, an ancestor of the head, and git merge-tree is clean. The branch did not move during the review. I did not write this PR.

Setup

I used detached worktrees at the head, at ed5c0aba (round 1) and at origin/dev, plus a fourth at the head for mutants. Each was set up with verify.sh worktree-setup and runs on the shared dev env. Every library run happened inside bwrap --ro-bind / /, with only the worktree (or its .tmp) writable, so the shared data/ was read-only.

Callers of pad and readers of projected_phase (audit)

  • pad has two callers, generate_band_isosurfaces (pyprocar/core/fermisurface.py:1016) and BandStructure2D.from_ebs (pyprocar/core/bandstructure2D.py:549). Both use inplace=False.
  • In the library, projected_phase is read only by ibz2fbz (core/ebs.py:2319), which runs inside the mesh from_code before any pad, and by the path-only Unfolder (utils/unfolder.py:51, through ebs.unfold and scriptUnfold.py:162). No plotter, FermiSurface or BandStructure2D method reads it. FermiSurface.save does not store the ebs.
  • The only way to reach the padded phases was fs.get_property("projected_phase") or the same call on a BandStructure2D. At ed5c0aba, on the QE meshes, both raise ValueError: Complex data must be single dimensional. On dev they raise the same error for any mesh that has phases. At head they raise KeyError, the same as for any absent property. So no working user path is lost.
  • expand_kpoints_to_supercell_by_axes still copies phases to k+G without the exp(-2 pi i G.tau) factor. It has no caller in pyprocar/.

User paths, origin/dev vs ed5c0aba vs head (QE SrVO3 fermi, spin-polarized-colinear and non-spin-polarized)

  • Mesh from ElectronicBandStructureMesh.from_code. It keeps projected_phase at head, [4096,25,2|1,5,16]. It is identical to ed5c0aba (max diff 0, and projected also max diff 0).
  • FermiSurface.from_ebs and BandStructure2D.from_ebs(normal=(0,0,1)). original_ebs is the input mesh, and it keeps its phases. The input mesh's phases are unchanged after both calls. The padded ebs has no phase at head, and it had one at ed5c0aba.
  • Head vs ed5c0aba, max diff 0 on both fixtures for these arrays:
    • FS points
    • projected_sum (total, V d, V eg)
    • fermi_speed and fermi_velocity
    • BS2D points and projected_sum
  • Head vs dev. FS and BS2D points and speeds are identical. The surface projections agree to 1.2e-15. The mesh projected differs by 0.308 in eg only, which is the round-1 fix.
  • VASP with phases (data/examples/bands/unfolding/supercell, projected_phase [150,80,1,24,9]). I compared ebs.unfold weights and pyprocar.unfold PNGs (plain/both and parametric/thickness). Dev and head give the same sha256 for all of them.
  • Synthetic VASP-style mesh (12^3 grid, 2 bands, 2 atoms, 9 orbitals, random phases) through FermiSurface.from_ebs and BandStructure2D.from_ebs. Points, projected_sum, V d, fermi_speed, and the padded projected and bands are identical between dev and head (max diff 0). Only the padded phase is gone. The input mesh and original_ebs keep the phases bit for bit.

Peak memory and time of FermiSurface.from_code("qe", .../fermi)

I measured ru_maxrss and wall time in sequential single jobs, interleaved across builds.

fixture origin/dev ed5c0ab head
spin-polarized-colinear, peak 3.595 to 3.596 GiB 9.229 to 9.235 GiB 3.782 to 3.786 GiB
non-spin-polarized, peak 2.005 to 2.009 GiB 4.845 to 4.848 GiB 2.114 to 2.117 GiB
spin-polarized, time (load about 8) 2.94 to 3.00 s 6.62 to 6.85 s 3.59 to 3.74 s
non-spin-polarized, time (load about 8) 0.96 to 0.97 s 2.77 to 3.22 s 1.39 to 1.68 s
  • Surfaces are identical across all three builds. The points sha256 is 80fef54c… (3000 points) and 02de5a9e… (1540 points), and the faces sha256 match too.
  • FermiSurface.from_ebs alone takes 0.78 to 0.80 s on dev and on head (non-spin-polarized) and 2.56 to 2.63 s (spin-polarized), so the remaining difference is in from_code, which is round-1 work.
  • A first pass at load about 20 gave the same memory and slower times.

Red/green and mutants

  • test_fermisurface_phases.py::test_fermi_surface_pads_the_projections_but_not_the_phases:
    • Fails on dev's library and on ed5c0aba's library, with assert Property(name=projected_phase, value=(2744, 1, 1, 1, 1)…) is None.
    • Passes at head.
    • Mutant that drops the phase from self before the deepcopy: the test fails on assert ebs.projected_phase is not None.
  • test_qe_mesh_bands_are_eigenvectors_of_their_little_group[both]:
    • Fails on dev's library (projected_phase is None).
    • Passes at ed5c0aba and at head.
    • Mutant with _core_harmonic_signs returning ones (flip reverted): both cases fail, with max residual 0.99999 and 0.99997.
    • Mutant with (-1)**m in place of (-1)**(m//2): both cases fail too.
  • My replica of the test, with the identity skipped, gives max residual 3.59e-4 over 52466 checks (non-spin-polarized) and 4.16e-4 over 104884 (spin-polarized). This matches the body.
  • red_green.py origin/dev: ok. The 2 non-data added tests fail on base for the stated reasons.

Gates at head (verify.sh exec, -n 4)

  • pytest -m "not data": 2010 passed, 2 skipped, exit 0.
  • -m data: head 408 passed, 1 skipped, exit 0. origin/dev 403 passed, 1 skipped, exit 0. The +5 are this PR's data cases.
  • basedpyright: 0 errors, 0 warnings, exit 0.
  • ruff_new_violations.py check and format vs origin/dev: ok.
  • ruff F821/F822/F823/NPY201: all checks passed.
  • gh pr checks 305: format, lint, red-green, test and typecheck pass, on run 37241870465 with headSha 8e35d37.

PR body claims

  • pad drops phases; from_code mesh and original_ebs keep them: confirmed.
  • Memory table: confirmed to 0.01 GiB.
  • Times: confirmed for dev, ed5c0aba and head spin-polarized. Head non-spin-polarized measured 1.39 to 1.68 s against the stated 1.22 s, under load (see note 2).
  • Same surfaces, 3000 and 1540 points: confirmed.
  • from_ebs 0.79 s on both: confirmed.
  • Little-group test (residuals, check counts, 1.0 without the flip, fails on dev): confirmed.
  • Pad test fails at ed5c0aba with a (2744,1,1,1,1) phase: confirmed.
  • Gates (2010/2, 408/1 vs 403, basedpyright 0, ruff ok): confirmed.
  • IBZ vs nosym energies. I parsed both runs' atomic_proj.xml independently, with Ry to eV and the 48 cubic operations. The images give 5.53e-6 eV (SrVO3) and 1.31e-5 eV (LaVO3): confirmed. At the IBZ k-points, 1.1e-12 and 4.8e-10 eV hold only for bands 1 to 26 and 1 to 30 (see note 1).
  • The rest of the body is round-1 content. The round-1 verdicts already cover it, and the delta does not change it.

Notes (none blocking)

  1. Band windows of the IBZ k-point energy figures. The body's "4.8e-10 eV (LaVO3)" holds for bands 1 to 30. Band 31, which is inside the body's own 1 to 31 window, differs by 2.0e-8 eV, and band 32 by 4.1e-6 eV. SrVO3's 1.1e-12 holds for bands 1 to 26; bands 28 to 30 reach 2.1e-11. features/parsers.md says "5e-10 eV at the IBZ k-points" and names no window. Suggested fix: state the window, or quote 4.1e-6 eV for LaVO3 bands 1 to 33.
  2. Head non-spin-polarized time. I measured 1.39 to 1.68 s at load about 8, against the stated 1.22 s. The difference is inside from_code, and from_ebs is equal on dev and head, so the round-2 change does not cause it.
  3. pad's default inplace=True now deletes projected_phase from the caller's own mesh. No library caller uses inplace=True, and the docstring says so. A user who calls ebs.pad() directly loses phases that were already wrong after a pad.
  4. expand_kpoints_to_supercell_by_axes still pads phases without the G.tau factor. It is dead code in pyprocar/ (round-1 note 3, remainder).
  5. Round-1 note 5 is resolved. The new data test guards the flip on the real fixtures.
  6. Round-1 notes 2, 4 and 6 are unchanged and out of scope. They cover semicore cross terms, Abinit phase signs, and the QE spin-polarized unfold broadcast error.
  7. Environment. The main checkout's pixi.lock differs from origin/dev's, so local gates ran on a drifted env. CI is green.

After #299, a QE mesh dropped its phases and left the f shell unrotated,
because the f labels projwfc.x prints are not the core's names; eg weights
then lost their interference. QE's harmonics also carry the sign (-1)^m.

Refs #293
Since #298 the QE parser names its orbitals as projwfc.x prints them.
ibz2fbz did not know the three f labels fzx2-zy2, fx3-3xy2 and f3yx2-y3,
so it dropped a QE mesh's phases and left f unrotated. Against QE 7.5
nosym runs, V eg weights were off by 0.30 and La f by 1.0.
ORBITAL_ALIASES now maps the three labels.

QE's real harmonics carry the sign (-1)^|m| (upflib/ylmr2.f90), and the
core's carry none. The parser now writes the phases over the core's
harmonics. Without that the kept phases unfold with wrong signs on px,
py, dxz, dyz, fxz2, fyz2, fx3-3xy2 and f3yx2-y3, and phase products are
off by up to 1.4.

Refs #293
The harmonic sign flip needs projwfc.x's orbital list. When spd_phase is
set without it, position_gauge_phase returned the phases with no
exp(-2 pi i k.tau) factor, so test_ebs_phases_use_bloch_sums_over_atom_positions
failed. Now the parser skips only the flip, and the Bloch factor always
applies. The signs and the Bloch factor are combined first and applied in
one multiply, so the parser no longer makes a second full-size copy of
the phase array.

Refs #293
QE meshes keep their phases since the sign fix, and the Fermi-surface
path padded them: 9.2 GiB peak on the spin-polarized SrVO3 fermi
fixture. Nothing reads phases on a padded mesh, and copies at k + G
would be wrong because position-gauge phases are not periodic in k.

Refs #293
The data test checked only warnings and that phases were kept, so it
passed with the sign flip reverted. Each nondegenerate band with V
weight must be an eigenvector of the orbital rotation of every operation
that fixes its k-point: max residual 3.6e-4 and 4.2e-4 over 52466 and
104884 checks by non-identity operations, against 1.0 without the flip.

Refs #293
…he QE reference

The 2.9e-4 LaVO3 figure holds over bands 1 to 31 of 34, and the 1e-9 eV
energy agreement only at the IBZ k-points. Note the pad memory figure.

Refs #293
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