From f9fe150cc2f6c2c2584578a921b0d93124243d49 Mon Sep 17 00:00:00 2001 From: Logan Lang Date: Sun, 4 Oct 2026 16:56:35 -0400 Subject: [PATCH 01/10] test(qe): QE phases unfold to the coefficients at each grid point 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 --- .../io/qe/test_qe_phase_convention.py | 144 ++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 tests/pyprocar/io/qe/test_qe_phase_convention.py diff --git a/tests/pyprocar/io/qe/test_qe_phase_convention.py b/tests/pyprocar/io/qe/test_qe_phase_convention.py new file mode 100644 index 00000000..3301eac5 --- /dev/null +++ b/tests/pyprocar/io/qe/test_qe_phase_convention.py @@ -0,0 +1,144 @@ +"""QE phases unfold to the full k grid with the orbital rotations of the core. + +QE's real harmonics (upflib/ylmr2.f90) carry the Condon-Shortley sign (-1)^m, so px, py, +dxz, dyz, fxz2, fyz2, fx3-3xy2 and f3yx2-y3 have the opposite sign to the core's. The +synthetic band below has the coefficients Y_lm(v(k)) of the standard real harmonics at +v(k) = sin(2 pi k), a field each cubic operation carries along, so its coefficients at +every k of the full grid are known without unfolding. +""" + +import warnings +from pathlib import Path + +import numpy as np +import pytest + +from pyprocar.core.ebs import ElectronicBandStructureMesh +from pyprocar.io.qe.parser import QEParser +from tests.pyprocar.core.test_ebs_unfold_exact_grid import CUBIC_OPERATIONS +from tests.pyprocar.core.test_ibz2fbz import gamma_grid, gamma_info, key, single_site, wedge +from tests.utils import DATA_DIR + +# projwfc.x's labels (PP/src/projwfc.f90, lm_label_global_frame) +QE_NAMES = ["s", "pz", "px", "py", "dz2", "dxz", "dyz", "dx2-y2", "dxy"] + [ + "fz3", + "fxz2", + "fyz2", + "fzx2-zy2", + "fxyz", + "fx3-3xy2", + "f3yx2-y3", +] +QE_SIGNED = {"px", "py", "dxz", "dyz", "fxz2", "fyz2", "fx3-3xy2", "f3yx2-y3"} +SHELLS = [slice(0, 1), slice(1, 4), slice(4, 9), slice(9, 16)] +CUBIC = np.array(CUBIC_OPERATIONS, dtype=float) +STATES = "\n".join( + f" state #{i + 1:4d}: atom 1 (X ), wfc {deg + 1:2d} (l={deg} m={m:2d})" + for i, (deg, m) in enumerate((deg, m) for deg in range(4) for m in range(1, 2 * deg + 2)) +) +PROJWFC_OUT = f""" + Program PROJWFC v.7.5 starts on 1Jan2026 at 12: 0: 0 + + Atomic states used for projection + (read from pseudopotential files): + +{STATES} + + natomwfc = 16 + nbnd = 1 + nspin = 1 + +=------------------------------------------------------------------------------= + JOB DONE. +=------------------------------------------------------------------------------= +""" + + +def real_harmonics(v: np.ndarray) -> np.ndarray: + """Standard real harmonics times r^l, in projwfc.x's order s, pz px py, dz2 ... dxy, fz3 ...""" + x, y, z = v.T + r2 = x**2 + y**2 + z**2 + d, f = np.sqrt(15 / np.pi), np.sqrt(35 / (2 * np.pi)) + return np.stack( + [ + np.full_like(x, 0.5 / np.sqrt(np.pi)), + np.sqrt(3 / (4 * np.pi)) * z, + np.sqrt(3 / (4 * np.pi)) * x, + np.sqrt(3 / (4 * np.pi)) * y, + np.sqrt(5 / np.pi) / 4 * (3 * z**2 - r2), + d / 2 * x * z, + d / 2 * y * z, + d / 4 * (x**2 - y**2), + d / 2 * x * y, + np.sqrt(7 / np.pi) / 4 * z * (5 * z**2 - 3 * r2), + np.sqrt(21 / (2 * np.pi)) / 4 * x * (5 * z**2 - r2), + np.sqrt(21 / (2 * np.pi)) / 4 * y * (5 * z**2 - r2), + np.sqrt(105 / np.pi) / 4 * z * (x**2 - y**2), + np.sqrt(105 / np.pi) / 2 * x * y * z, + f / 4 * x * (x**2 - 3 * y**2), + f / 4 * y * (3 * x**2 - y**2), + ], + axis=-1, + ) + + +def field(k: np.ndarray) -> np.ndarray: + return np.sin(2 * np.pi * np.asarray(k, dtype=float)) + + +def test_qe_phases_unfold_to_the_coefficients_at_each_grid_point( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + (tmp_path / "projwfc.out").write_text(PROJWFC_OUT) + ibz = np.asarray(wedge(gamma_grid((4, 4, 4)), CUBIC), dtype=float) + qe_signs = np.array([-1.0 if name in QE_SIGNED else 1.0 for name in QE_NAMES]) + qe_phase = (real_harmonics(field(ibz)) * qe_signs).astype(complex) + qe_phase = qe_phase[:, np.newaxis, np.newaxis, np.newaxis, :] + + parser = QEParser(tmp_path) + monkeypatch.setattr(QEParser, "kpoints", property(lambda _: ibz)) + parser.__dict__.update( + spd_phase=qe_phase, + spd=np.abs(qe_phase) ** 2, + bands=np.zeros((len(ibz), 1, 1)), + fermi=0.0, + reciprocal_lattice=np.eye(3), + structure=single_site(rotations=CUBIC), + kpath=None, + kgrid_info=gamma_info((4, 4, 4)), + ) + with warnings.catch_warnings(): + warnings.simplefilter("error") + ebs = parser.ebs + + assert ebs is not None and ebs.projected is not None and ebs.projected_phase is not None + assert ebs.orbital_names == QE_NAMES + expected = real_harmonics(field(ebs.kpoints)) + assert len({key(k) for k in ebs.kpoints}) == 64 + np.testing.assert_allclose(ebs.projected.to_array()[:, 0, 0, 0], expected**2, atol=1e-12) + unfolded = ebs.projected_phase.to_array()[:, 0, 0, 0] + for shell in SHELLS: + np.testing.assert_allclose( + np.einsum("ki,kj->kij", unfolded[:, shell], unfolded[:, shell].conj()), + np.einsum("ki,kj->kij", expected[:, shell], expected[:, shell]), + atol=1e-12, + ) + + +@pytest.mark.data +@pytest.mark.parametrize( + ("mag", "keeps_phase"), + [("non-spin-polarized", True), ("spin-polarized-colinear", True), ("non-colinear", False)], +) +def test_qe_mesh_rotates_every_orbital_and_keeps_collinear_phases( + mag: str, keeps_phase: bool +) -> None: + calc = DATA_DIR / f"codes/qe/7.2/SrVO3/{mag}/fermi" + + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter("always") + ebs = ElectronicBandStructureMesh.from_code("qe", str(calc)) + + assert [str(w.message) for w in caught if issubclass(w.category, UserWarning)] == [] + assert (ebs.projected_phase is not None) == keeps_phase + assert ebs.n_kpoints == 16**3 From 970d8fb7cda65707fca809592dc72f74c6fe0039 Mon Sep 17 00:00:00 2001 From: Logan Lang Date: Sun, 4 Oct 2026 16:57:45 -0400 Subject: [PATCH 02/10] fix(qe): unfold QE phases and f orbitals with the core's harmonics 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 --- .../verify-pyprocar/features/parsers.md | 1 + pyprocar/core/ebs.py | 8 +++++++- pyprocar/io/qe/parser.py | 19 ++++++++++++++++--- 3 files changed, 24 insertions(+), 4 deletions(-) diff --git a/.claude/skills/verify-pyprocar/features/parsers.md b/.claude/skills/verify-pyprocar/features/parsers.md index a64a87c4..7888a3fd 100644 --- a/.claude/skills/verify-pyprocar/features/parsers.md +++ b/.claude/skills/verify-pyprocar/features/parsers.md @@ -26,6 +26,7 @@ The proven end state (1f36aae1; `vasp` and `qe` re-driven at d6d4aaa7): - `qe` (`data/codes/qe/7.2/SrVO3/non-spin-polarized/bands`): `bands_shape` is `[155, 25, 1]`, ticks are `Γ X M Γ R X`, and `ebs_fermi` is 12.5491. - The cell is cubic, so a private copy with `K_POINTS crystal_b` changed to `tpiba_b` must give the same 155 k-points and ticks (proven at #262). `tpiba_c` and `crystal_c` give `kpath` `None`; only the synthetic tests in `tests/pyprocar/io/qe/test_qe_parser.py` cover them. - `qe` non-collinear (`data/codes/qe/7.2/SrVO3/non-colinear/bands`, #293): `projected` is `[155, 50, 4, 5, 16]` (total, Sx, Sy, Sz on projwfc.x's real (l, m) orbitals `s pz px py dz2 dxz dyz dx2-y2 dxy ...`), and `bands` keeps 1 channel. At Gamma, band 41 has V t2g 0.984 and eg 0.000, and band 47 has t2g 0.000 and eg 0.833, matching the j-state weights in `kpdos.out`. A wrong spinor transform moves weight between dxy and dx2-y2. Every parser passes orbital names; a PROCAR that `pyprocar.filter` rewrote keeps its `o0` header name and label (`Bi-(o0)` on `data/examples/bands/auto`). +- `qe` meshes (`data/codes/qe/7.2/SrVO3/*/fermi`, #293): ibz2fbz rotates s, p, d and f with no warning, and the two collinear meshes keep `projected_phase`. ibz2fbz knows projwfc.x's f labels through `ORBITAL_ALIASES`, and the parser turns QE's (-1)^|m| harmonic signs (`upflib/ylmr2.f90`) into the core's. The independent reference is QE 7.5 IBZ and nosym 6x6x6 runs of SrVO3 and spin-polarized LaVO3 in `~/Documents/lllangWV-Projects/DFT/pyprocar-293-qe-sign` (`compare_all.sh` reruns the check). Unfolded weights, intra-atom phase products and all atom-pair phase products match nosym to 2.9e-4, within the reference's own symmetry spread of 3.3e-4. Without the f aliases the phases drop and V eg is off by 0.30 and La f by 1.0; without the sign flip the weights still match (cubic operations only permute signed orbitals) but phase products are off by up to 1.4. - `elk` structure: all four `data/codes/elk/6.3/SrVO3/*` dirs give a 3.841244 Angstrom cubic lattice, through `GEOMETRY.OUT` or, in `non-spin-polarized/bands`, the `elk.in` fallback. Their `structure.pkl` files hold the pre-#242 Bohr lattice (7.2589), so do not compare against them. - `get_parser` writes nothing into the dir. - `abinit` (`data/codes/abinit/9.6/Fe/*/bands`, #255): `kpath` ticks are `Γ(0) H(50) N(100) Γ(150) P(200) H|P(250) N(300)`, and `ebs` is an `ElectronicBandStructurePath`. Abinit writes each segment boundary once, so a wrong segmentation shows as 3 ticks `Γ(0) H|H(250) N(300)`. With Cartesian x-distances, Γ–H is `1/a` = 0.3521 Å⁻¹ (a = 2.84 Å). diff --git a/pyprocar/core/ebs.py b/pyprocar/core/ebs.py index 59a09057..3c180e89 100755 --- a/pyprocar/core/ebs.py +++ b/pyprocar/core/ebs.py @@ -2073,7 +2073,13 @@ def _cell_keys(kpoints: np.ndarray) -> np.ndarray: for name in names } IDENTITY = 0 -ORBITAL_ALIASES = {"dx2-y2": "x2-y2", "dx2": "x2-y2"} +ORBITAL_ALIASES = { + "dx2-y2": "x2-y2", + "dx2": "x2-y2", + "fzx2-zy2": "fzx2", + "fx3-3xy2": "fx3", + "f3yx2-y3": "fy3x2", +} SHELL_SUMS = {"p", "d", "f", "tot"} diff --git a/pyprocar/io/qe/parser.py b/pyprocar/io/qe/parser.py index b02a03fb..5c534677 100644 --- a/pyprocar/io/qe/parser.py +++ b/pyprocar/io/qe/parser.py @@ -32,6 +32,15 @@ user_logger = logging.getLogger("user") +def to_core_harmonics(phase: np.ndarray, orbitals: list[dict[str, int]]) -> np.ndarray: + """Coefficients over QE's real harmonics written over the core's. + + QE's real harmonics (upflib/ylmr2.f90) carry the Condon-Shortley sign (-1)^m, where projwfc.x's + m = 1, 2, 3, ... is |m| = 0, 1, 1, 2, 2, ...; the core's harmonics carry no such sign. + """ + return phase * np.array([(-1.0) ** (orbital["m"] // 2) for orbital in orbitals]) + + class QEParser(BaseParser): """Auto-detects Quantum ESPRESSO files in a directory and exposes lazy parser properties and computed objects (EBS, DOS, Structure). @@ -688,13 +697,17 @@ def spd_phase(self) -> np.ndarray | None: @cached_property def position_gauge_phase(self) -> np.ndarray | None: - """spd_phase in the core's convention, Bloch sums with exp(i k.(R + tau)). + """spd_phase in the core's convention: its real harmonics, and Bloch sums with + exp(i k.(R + tau)). QE's atomic wavefunctions carry exp(i k.R) alone, so each atom's coefficient takes the factor exp(-2 pi i k.tau). """ - phase, structure, kpoints = self.spd_phase, self.structure, self.kpoints - if phase is None or structure is None or kpoints is None or len(kpoints) != len(phase): + if self.spd_phase is None or self.projwfc_out is None: + return self.spd_phase + phase = to_core_harmonics(self.spd_phase, self.projwfc_out.orbitals) + structure, kpoints = self.structure, self.kpoints + if structure is None or kpoints is None or len(kpoints) != len(phase): return phase tau = np.asarray(structure.fractional_coordinates, dtype=float) bloch = np.exp(-2j * np.pi * np.asarray(kpoints) @ tau.T) From 13fa045218711282670e5815c59da86928da2a8d Mon Sep 17 00:00:00 2001 From: Logan Lang Date: Sun, 4 Oct 2026 16:59:23 -0400 Subject: [PATCH 03/10] fix(qe): keep the Bloch factor when the parser has no projwfc.x orbitals 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 --- pyprocar/io/qe/parser.py | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/pyprocar/io/qe/parser.py b/pyprocar/io/qe/parser.py index 5c534677..79ece507 100644 --- a/pyprocar/io/qe/parser.py +++ b/pyprocar/io/qe/parser.py @@ -32,13 +32,13 @@ user_logger = logging.getLogger("user") -def to_core_harmonics(phase: np.ndarray, orbitals: list[dict[str, int]]) -> np.ndarray: - """Coefficients over QE's real harmonics written over the core's. +def _core_harmonic_signs(orbitals: list[dict[str, int]]) -> np.ndarray: + """The sign that writes a coefficient over QE's real harmonic over the core's. QE's real harmonics (upflib/ylmr2.f90) carry the Condon-Shortley sign (-1)^m, where projwfc.x's m = 1, 2, 3, ... is |m| = 0, 1, 1, 2, 2, ...; the core's harmonics carry no such sign. """ - return phase * np.array([(-1.0) ** (orbital["m"] // 2) for orbital in orbitals]) + return np.array([(-1.0) ** (orbital["m"] // 2) for orbital in orbitals]) class QEParser(BaseParser): @@ -703,15 +703,17 @@ def position_gauge_phase(self) -> np.ndarray | None: QE's atomic wavefunctions carry exp(i k.R) alone, so each atom's coefficient takes the factor exp(-2 pi i k.tau). """ - if self.spd_phase is None or self.projwfc_out is None: - return self.spd_phase - phase = to_core_harmonics(self.spd_phase, self.projwfc_out.orbitals) - structure, kpoints = self.structure, self.kpoints - if structure is None or kpoints is None or len(kpoints) != len(phase): - return phase - tau = np.asarray(structure.fractional_coordinates, dtype=float) - bloch = np.exp(-2j * np.pi * np.asarray(kpoints) @ tau.T) - return phase * bloch[:, np.newaxis, np.newaxis, :, np.newaxis] + phase, structure, kpoints = self.spd_phase, self.structure, self.kpoints + if phase is None: + return None + factor = np.ones(phase.shape[-1]) + if self.projwfc_out is not None: + factor = _core_harmonic_signs(self.projwfc_out.orbitals) + if structure is not None and kpoints is not None and len(kpoints) == len(phase): + tau = np.asarray(structure.fractional_coordinates, dtype=float) + bloch = np.exp(-2j * np.pi * np.asarray(kpoints) @ tau.T) + factor = bloch[:, np.newaxis, np.newaxis, :, np.newaxis] * factor + return phase * factor @cached_property def spd(self) -> np.ndarray | None: From def3f9bbf28d6056eb5bd05117a789668d4a37fb Mon Sep 17 00:00:00 2001 From: Logan Lang Date: Sun, 4 Oct 2026 18:43:11 -0400 Subject: [PATCH 04/10] test(fermi): the Fermi-surface mesh pads projections but not phases Refs #293 --- .../pyprocar/core/test_fermisurface_phases.py | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 tests/pyprocar/core/test_fermisurface_phases.py diff --git a/tests/pyprocar/core/test_fermisurface_phases.py b/tests/pyprocar/core/test_fermisurface_phases.py new file mode 100644 index 00000000..37c72d83 --- /dev/null +++ b/tests/pyprocar/core/test_fermisurface_phases.py @@ -0,0 +1,37 @@ +import numpy as np + +from pyprocar.core.ebs import ElectronicBandStructureMesh +from pyprocar.core.fermisurface import FermiSurface +from pyprocar.core.kpoints import KGRID_MODE, KGridInfo + +N_K = 10 +PADDING = 2 + + +def test_fermi_surface_pads_the_projections_but_not_the_phases() -> None: + frac = np.arange(N_K) / N_K + kpoints = np.stack(np.meshgrid(frac, frac, frac, indexing="ij"), axis=-1).reshape(-1, 3) + centred = (kpoints + 0.5) % 1.0 - 0.5 + energies = np.sum(centred**2, axis=1) - 0.1 + ebs = ElectronicBandStructureMesh( + kgrid_info=KGridInfo( + kgrid=(N_K, N_K, N_K), kgrid_mode=KGRID_MODE.GAMMA, kshift=(0.0, 0.0, 0.0) + ), + kpoints=kpoints, + bands=energies.reshape(-1, 1, 1), + projected=np.ones((len(kpoints), 1, 1, 1, 1)), + projected_phase=np.exp(2j * np.pi * kpoints[:, 0]).reshape(-1, 1, 1, 1, 1), + orbital_names=["s"], + fermi=0.0, + reciprocal_lattice=np.eye(3), + ) + + fs = FermiSurface.from_ebs(ebs, padding=PADDING) + + assert fs.ebs.projected_phase is None + assert fs.ebs.projected is not None + assert fs.ebs.projected.value.shape == (14**3, 1, 1, 1, 1) + assert ebs.projected_phase is not None + np.testing.assert_allclose( + ebs.projected_phase.value.ravel(), np.exp(2j * np.pi * ebs.kpoints[:, 0]), atol=1e-12 + ) From 0cb87c2d971abd7b572add3c995ed775ad6c7647 Mon Sep 17 00:00:00 2001 From: Logan Lang Date: Sun, 4 Oct 2026 18:43:11 -0400 Subject: [PATCH 05/10] fix(ebs): drop projected_phase when padding a mesh 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 --- pyprocar/core/ebs.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/pyprocar/core/ebs.py b/pyprocar/core/ebs.py index 3c180e89..c255d1f5 100755 --- a/pyprocar/core/ebs.py +++ b/pyprocar/core/ebs.py @@ -1808,11 +1808,17 @@ def get_property_mesh(self, key, **kwargs): return property_mesh def pad(self, padding=10, order="F", inplace=True): + """Wrap the grid by ``padding`` k-points in each direction with more than one point. + + ``projected_phase`` is dropped: phases with exp(i k.(R + tau)) Bloch sums are not + periodic in k, so copies at k + G would be wrong. + """ logger.info(f"Padding kpoints by {padding} in all directions") if inplace: ebs = self else: ebs = copy.deepcopy(self) + ebs.remove_property("projected_phase") padding_dims = [] for i, n in enumerate(ebs.kgrid): From 11e20d31f58d732c9ce0a6b0a0df6165f04b2ed2 Mon Sep 17 00:00:00 2001 From: Logan Lang Date: Sun, 4 Oct 2026 18:50:56 -0400 Subject: [PATCH 06/10] test(qe): unfolded QE bands are eigenvectors of their little group 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 --- .../io/qe/test_qe_phase_convention.py | 40 ++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/tests/pyprocar/io/qe/test_qe_phase_convention.py b/tests/pyprocar/io/qe/test_qe_phase_convention.py index 3301eac5..22160428 100644 --- a/tests/pyprocar/io/qe/test_qe_phase_convention.py +++ b/tests/pyprocar/io/qe/test_qe_phase_convention.py @@ -13,7 +13,7 @@ import numpy as np import pytest -from pyprocar.core.ebs import ElectronicBandStructureMesh +from pyprocar.core.ebs import ElectronicBandStructureMesh, orbital_rotation from pyprocar.io.qe.parser import QEParser from tests.pyprocar.core.test_ebs_unfold_exact_grid import CUBIC_OPERATIONS from tests.pyprocar.core.test_ibz2fbz import gamma_grid, gamma_info, key, single_site, wedge @@ -142,3 +142,41 @@ def test_qe_mesh_rotates_every_orbital_and_keeps_collinear_phases( assert [str(w.message) for w in caught if issubclass(w.category, UserWarning)] == [] assert (ebs.projected_phase is not None) == keeps_phase assert ebs.n_kpoints == 16**3 + + +@pytest.mark.data +@pytest.mark.parametrize("mag", ["non-spin-polarized", "spin-polarized-colinear"]) +def test_qe_mesh_bands_are_eigenvectors_of_their_little_group(mag: str) -> None: + """A nondegenerate band at k is an eigenvector of each orbital rotation whose R fixes k. + + Every cubic operation maps V onto itself up to a lattice vector, so lattice and Bloch factors + are one common phase. QE's harmonic signs break this wherever an operation mixes a signed + orbital with an unsigned one. + """ + ebs = ElectronicBandStructureMesh.from_code( + "qe", str(DATA_DIR / f"codes/qe/7.2/SrVO3/{mag}/fermi") + ) + assert ebs.projected_phase is not None and ebs.structure is not None + vanadium = [str(atom) for atom in ebs.structure.atoms].index("V") + phases = np.asarray(ebs.projected_phase.value)[:, :, :, vanadium] + gaps = np.diff(np.asarray(ebs.bands.value), axis=1) + lower = np.pad(gaps, ((0, 0), (1, 0), (0, 0)), constant_values=np.inf) + upper = np.pad(gaps, ((0, 0), (0, 1), (0, 0)), constant_values=np.inf) + norms = np.linalg.norm(phases, axis=-1) + selected = (np.minimum(lower, upper) > 1e-3) & (norms**2 > 0.05) + + residuals = [] + for rotation in CUBIC: + steps = ebs.kpoints @ rotation.T - ebs.kpoints + fixed = np.all(np.abs(steps - np.round(steps)) < 1e-6, axis=1) + coefficients = phases[fixed][selected[fixed]] + turned = coefficients @ orbital_rotation(ebs.orbital_names, rotation).T + overlap = np.sum(coefficients.conj() * turned, axis=-1) / np.sum( + np.abs(coefficients) ** 2, axis=-1 + ) + residual = turned - overlap[:, np.newaxis] * coefficients + residuals.append(np.linalg.norm(residual, axis=-1) / norms[fixed][selected[fixed]]) + residuals = np.concatenate(residuals) + + assert len(residuals) > 1000 + assert residuals.max() < 0.05 From 9d0f9293667af47c8d990ab8e3710c43f3e1272f Mon Sep 17 00:00:00 2001 From: Logan Lang Date: Sun, 4 Oct 2026 18:51:58 -0400 Subject: [PATCH 07/10] docs(verify-pyprocar): state the band windows and image energies of the 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 --- .claude/skills/verify-pyprocar/features/fermi3d.md | 1 + .claude/skills/verify-pyprocar/features/parsers.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.claude/skills/verify-pyprocar/features/fermi3d.md b/.claude/skills/verify-pyprocar/features/fermi3d.md index a8bd88d5..b48fc952 100644 --- a/.claude/skills/verify-pyprocar/features/fermi3d.md +++ b/.claude/skills/verify-pyprocar/features/fermi3d.md @@ -35,6 +35,7 @@ The proven end state (SrVO3, non-spin-polarized, d6d4aaa7): - `obj_scalars_projected_sum`: about 16.6k distinct colors. - `legacy_handler_plain`: about 290 distinct colors, a single-color set of cylinders along the axes inside the BZ. `legacy_handler_parametric` and `legacy_handler_fermi_speed`: more than 16k distinct colors each. - `side_effects.txt` is empty. +- Peak memory (#305): `ebs.pad` drops `projected_phase`, which nothing reads on a padded mesh. `FermiSurface.from_code("qe", data/codes/qe/7.2/SrVO3/spin-polarized-colinear/fermi)` peaks at 3.8 GiB (`ru_maxrss`); padding the kept QE phases took it to 9.2 GiB. ## Gotchas diff --git a/.claude/skills/verify-pyprocar/features/parsers.md b/.claude/skills/verify-pyprocar/features/parsers.md index 7888a3fd..d3fef25e 100644 --- a/.claude/skills/verify-pyprocar/features/parsers.md +++ b/.claude/skills/verify-pyprocar/features/parsers.md @@ -26,7 +26,7 @@ The proven end state (1f36aae1; `vasp` and `qe` re-driven at d6d4aaa7): - `qe` (`data/codes/qe/7.2/SrVO3/non-spin-polarized/bands`): `bands_shape` is `[155, 25, 1]`, ticks are `Γ X M Γ R X`, and `ebs_fermi` is 12.5491. - The cell is cubic, so a private copy with `K_POINTS crystal_b` changed to `tpiba_b` must give the same 155 k-points and ticks (proven at #262). `tpiba_c` and `crystal_c` give `kpath` `None`; only the synthetic tests in `tests/pyprocar/io/qe/test_qe_parser.py` cover them. - `qe` non-collinear (`data/codes/qe/7.2/SrVO3/non-colinear/bands`, #293): `projected` is `[155, 50, 4, 5, 16]` (total, Sx, Sy, Sz on projwfc.x's real (l, m) orbitals `s pz px py dz2 dxz dyz dx2-y2 dxy ...`), and `bands` keeps 1 channel. At Gamma, band 41 has V t2g 0.984 and eg 0.000, and band 47 has t2g 0.000 and eg 0.833, matching the j-state weights in `kpdos.out`. A wrong spinor transform moves weight between dxy and dx2-y2. Every parser passes orbital names; a PROCAR that `pyprocar.filter` rewrote keeps its `o0` header name and label (`Bi-(o0)` on `data/examples/bands/auto`). -- `qe` meshes (`data/codes/qe/7.2/SrVO3/*/fermi`, #293): ibz2fbz rotates s, p, d and f with no warning, and the two collinear meshes keep `projected_phase`. ibz2fbz knows projwfc.x's f labels through `ORBITAL_ALIASES`, and the parser turns QE's (-1)^|m| harmonic signs (`upflib/ylmr2.f90`) into the core's. The independent reference is QE 7.5 IBZ and nosym 6x6x6 runs of SrVO3 and spin-polarized LaVO3 in `~/Documents/lllangWV-Projects/DFT/pyprocar-293-qe-sign` (`compare_all.sh` reruns the check). Unfolded weights, intra-atom phase products and all atom-pair phase products match nosym to 2.9e-4, within the reference's own symmetry spread of 3.3e-4. Without the f aliases the phases drop and V eg is off by 0.30 and La f by 1.0; without the sign flip the weights still match (cubic operations only permute signed orbitals) but phase products are off by up to 1.4. +- `qe` meshes (`data/codes/qe/7.2/SrVO3/*/fermi`, #293): ibz2fbz rotates s, p, d and f with no warning, and the two collinear meshes keep `projected_phase`. ibz2fbz knows projwfc.x's f labels through `ORBITAL_ALIASES`, and the parser turns QE's (-1)^|m| harmonic signs (`upflib/ylmr2.f90`) into the core's. The independent reference is QE 7.5 IBZ and nosym 6x6x6 runs of SrVO3 and spin-polarized LaVO3 in `~/Documents/lllangWV-Projects/DFT/pyprocar-293-qe-sign` (`compare_all.sh` reruns the check). Unfolded weights, intra-atom phase products and all atom-pair phase products match nosym to 3.0e-5 (SrVO3, bands 1 to 26 of 30) and 2.9e-4 (LaVO3, bands 1 to 31 of 34), within the reference's own symmetry spread of 1.8e-4 and 3.3e-4. LaVO3's band 32 raises the all-pairs figure to 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. The nosym energies equal the IBZ run's to 5e-10 eV at the IBZ k-points but only to 5.5e-6 eV (SrVO3) and 1.3e-5 eV (LaVO3) at their symmetry images. Without the f aliases the phases drop and V eg is off by 0.30 and La f by 1.0; without the sign flip the weights still match (cubic operations only permute signed orbitals) but phase products are off by up to 1.4. On the fixtures, each nondegenerate band with V weight is an eigenvector of the orbital rotation of every operation fixing its k (max residual 4.2e-4, against 1.0 without the flip). - `elk` structure: all four `data/codes/elk/6.3/SrVO3/*` dirs give a 3.841244 Angstrom cubic lattice, through `GEOMETRY.OUT` or, in `non-spin-polarized/bands`, the `elk.in` fallback. Their `structure.pkl` files hold the pre-#242 Bohr lattice (7.2589), so do not compare against them. - `get_parser` writes nothing into the dir. - `abinit` (`data/codes/abinit/9.6/Fe/*/bands`, #255): `kpath` ticks are `Γ(0) H(50) N(100) Γ(150) P(200) H|P(250) N(300)`, and `ebs` is an `ElectronicBandStructurePath`. Abinit writes each segment boundary once, so a wrong segmentation shows as 3 ticks `Γ(0) H|H(250) N(300)`. With Cartesian x-distances, Γ–H is `1/a` = 0.3521 Å⁻¹ (a = 2.84 Å). From 141b2010644c1d60014a0058a544d5b0cd3d9a6a Mon Sep 17 00:00:00 2001 From: Logan Lang Date: Sun, 4 Oct 2026 18:53:55 -0400 Subject: [PATCH 08/10] test: reuse the sphere mesh helpers and index each little group once Refs #293 --- .../pyprocar/core/test_fermisurface_phases.py | 17 +++++------------ .../io/qe/test_qe_phase_convention.py | 19 ++++++++++--------- 2 files changed, 15 insertions(+), 21 deletions(-) diff --git a/tests/pyprocar/core/test_fermisurface_phases.py b/tests/pyprocar/core/test_fermisurface_phases.py index 37c72d83..d0d07abd 100644 --- a/tests/pyprocar/core/test_fermisurface_phases.py +++ b/tests/pyprocar/core/test_fermisurface_phases.py @@ -2,21 +2,14 @@ from pyprocar.core.ebs import ElectronicBandStructureMesh from pyprocar.core.fermisurface import FermiSurface -from pyprocar.core.kpoints import KGRID_MODE, KGridInfo - -N_K = 10 -PADDING = 2 +from tests.pyprocar.core.test_fermisurface_without_projections import N_K, _sphere_energies +from tests.pyprocar.core.test_ibz2fbz import gamma_info def test_fermi_surface_pads_the_projections_but_not_the_phases() -> None: - frac = np.arange(N_K) / N_K - kpoints = np.stack(np.meshgrid(frac, frac, frac, indexing="ij"), axis=-1).reshape(-1, 3) - centred = (kpoints + 0.5) % 1.0 - 0.5 - energies = np.sum(centred**2, axis=1) - 0.1 + kpoints, energies = _sphere_energies() ebs = ElectronicBandStructureMesh( - kgrid_info=KGridInfo( - kgrid=(N_K, N_K, N_K), kgrid_mode=KGRID_MODE.GAMMA, kshift=(0.0, 0.0, 0.0) - ), + kgrid_info=gamma_info((N_K, N_K, N_K)), kpoints=kpoints, bands=energies.reshape(-1, 1, 1), projected=np.ones((len(kpoints), 1, 1, 1, 1)), @@ -26,7 +19,7 @@ def test_fermi_surface_pads_the_projections_but_not_the_phases() -> None: reciprocal_lattice=np.eye(3), ) - fs = FermiSurface.from_ebs(ebs, padding=PADDING) + fs = FermiSurface.from_ebs(ebs, padding=2) assert fs.ebs.projected_phase is None assert fs.ebs.projected is not None diff --git a/tests/pyprocar/io/qe/test_qe_phase_convention.py b/tests/pyprocar/io/qe/test_qe_phase_convention.py index 22160428..204caeed 100644 --- a/tests/pyprocar/io/qe/test_qe_phase_convention.py +++ b/tests/pyprocar/io/qe/test_qe_phase_convention.py @@ -159,23 +159,24 @@ def test_qe_mesh_bands_are_eigenvectors_of_their_little_group(mag: str) -> None: assert ebs.projected_phase is not None and ebs.structure is not None vanadium = [str(atom) for atom in ebs.structure.atoms].index("V") phases = np.asarray(ebs.projected_phase.value)[:, :, :, vanadium] - gaps = np.diff(np.asarray(ebs.bands.value), axis=1) - lower = np.pad(gaps, ((0, 0), (1, 0), (0, 0)), constant_values=np.inf) - upper = np.pad(gaps, ((0, 0), (0, 1), (0, 0)), constant_values=np.inf) + gaps = np.pad( + np.diff(np.asarray(ebs.bands.value), axis=1), + ((0, 0), (1, 1), (0, 0)), + constant_values=np.inf, + ) norms = np.linalg.norm(phases, axis=-1) - selected = (np.minimum(lower, upper) > 1e-3) & (norms**2 > 0.05) + selected = (np.minimum(gaps[:, :-1], gaps[:, 1:]) > 1e-3) & (norms**2 > 0.05) residuals = [] for rotation in CUBIC: steps = ebs.kpoints @ rotation.T - ebs.kpoints fixed = np.all(np.abs(steps - np.round(steps)) < 1e-6, axis=1) - coefficients = phases[fixed][selected[fixed]] + mask = selected & fixed[:, np.newaxis, np.newaxis] + coefficients, norm = phases[mask], norms[mask] turned = coefficients @ orbital_rotation(ebs.orbital_names, rotation).T - overlap = np.sum(coefficients.conj() * turned, axis=-1) / np.sum( - np.abs(coefficients) ** 2, axis=-1 - ) + overlap = np.sum(coefficients.conj() * turned, axis=-1) / norm**2 residual = turned - overlap[:, np.newaxis] * coefficients - residuals.append(np.linalg.norm(residual, axis=-1) / norms[fixed][selected[fixed]]) + residuals.append(np.linalg.norm(residual, axis=-1) / norm) residuals = np.concatenate(residuals) assert len(residuals) > 1000 From f2d10ecb9adaf7d05aa3d0150211c1aa1746f2f4 Mon Sep 17 00:00:00 2001 From: Logan Lang Date: Sun, 4 Oct 2026 18:55:45 -0400 Subject: [PATCH 09/10] test(qe): narrow the optional mesh fields for basedpyright Refs #293 --- .../pyprocar/io/qe/test_qe_phase_convention.py | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/tests/pyprocar/io/qe/test_qe_phase_convention.py b/tests/pyprocar/io/qe/test_qe_phase_convention.py index 204caeed..e00738c0 100644 --- a/tests/pyprocar/io/qe/test_qe_phase_convention.py +++ b/tests/pyprocar/io/qe/test_qe_phase_convention.py @@ -156,11 +156,18 @@ def test_qe_mesh_bands_are_eigenvectors_of_their_little_group(mag: str) -> None: ebs = ElectronicBandStructureMesh.from_code( "qe", str(DATA_DIR / f"codes/qe/7.2/SrVO3/{mag}/fermi") ) - assert ebs.projected_phase is not None and ebs.structure is not None - vanadium = [str(atom) for atom in ebs.structure.atoms].index("V") - phases = np.asarray(ebs.projected_phase.value)[:, :, :, vanadium] + phase, bands, structure, names = ( + ebs.projected_phase, + ebs.bands, + ebs.structure, + ebs.orbital_names, + ) + assert phase is not None and bands is not None and structure is not None + assert structure.atoms is not None and names is not None + vanadium = [str(atom) for atom in structure.atoms].index("V") + phases = np.asarray(phase.value)[:, :, :, vanadium] gaps = np.pad( - np.diff(np.asarray(ebs.bands.value), axis=1), + np.diff(np.asarray(bands.value), axis=1), ((0, 0), (1, 1), (0, 0)), constant_values=np.inf, ) @@ -173,7 +180,7 @@ def test_qe_mesh_bands_are_eigenvectors_of_their_little_group(mag: str) -> None: fixed = np.all(np.abs(steps - np.round(steps)) < 1e-6, axis=1) mask = selected & fixed[:, np.newaxis, np.newaxis] coefficients, norm = phases[mask], norms[mask] - turned = coefficients @ orbital_rotation(ebs.orbital_names, rotation).T + turned = coefficients @ orbital_rotation(names, rotation).T overlap = np.sum(coefficients.conj() * turned, axis=-1) / norm**2 residual = turned - overlap[:, np.newaxis] * coefficients residuals.append(np.linalg.norm(residual, axis=-1) / norm) From 514b6eea91e6185bd3a96bce9c12f4691395fcf3 Mon Sep 17 00:00:00 2001 From: Logan Lang Date: Sun, 4 Oct 2026 19:21:54 -0400 Subject: [PATCH 10/10] docs(verify-pyprocar): state the band windows of the IBZ energy figures --- .claude/skills/verify-pyprocar/features/parsers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/skills/verify-pyprocar/features/parsers.md b/.claude/skills/verify-pyprocar/features/parsers.md index d3fef25e..b7b162c8 100644 --- a/.claude/skills/verify-pyprocar/features/parsers.md +++ b/.claude/skills/verify-pyprocar/features/parsers.md @@ -26,7 +26,7 @@ The proven end state (1f36aae1; `vasp` and `qe` re-driven at d6d4aaa7): - `qe` (`data/codes/qe/7.2/SrVO3/non-spin-polarized/bands`): `bands_shape` is `[155, 25, 1]`, ticks are `Γ X M Γ R X`, and `ebs_fermi` is 12.5491. - The cell is cubic, so a private copy with `K_POINTS crystal_b` changed to `tpiba_b` must give the same 155 k-points and ticks (proven at #262). `tpiba_c` and `crystal_c` give `kpath` `None`; only the synthetic tests in `tests/pyprocar/io/qe/test_qe_parser.py` cover them. - `qe` non-collinear (`data/codes/qe/7.2/SrVO3/non-colinear/bands`, #293): `projected` is `[155, 50, 4, 5, 16]` (total, Sx, Sy, Sz on projwfc.x's real (l, m) orbitals `s pz px py dz2 dxz dyz dx2-y2 dxy ...`), and `bands` keeps 1 channel. At Gamma, band 41 has V t2g 0.984 and eg 0.000, and band 47 has t2g 0.000 and eg 0.833, matching the j-state weights in `kpdos.out`. A wrong spinor transform moves weight between dxy and dx2-y2. Every parser passes orbital names; a PROCAR that `pyprocar.filter` rewrote keeps its `o0` header name and label (`Bi-(o0)` on `data/examples/bands/auto`). -- `qe` meshes (`data/codes/qe/7.2/SrVO3/*/fermi`, #293): ibz2fbz rotates s, p, d and f with no warning, and the two collinear meshes keep `projected_phase`. ibz2fbz knows projwfc.x's f labels through `ORBITAL_ALIASES`, and the parser turns QE's (-1)^|m| harmonic signs (`upflib/ylmr2.f90`) into the core's. The independent reference is QE 7.5 IBZ and nosym 6x6x6 runs of SrVO3 and spin-polarized LaVO3 in `~/Documents/lllangWV-Projects/DFT/pyprocar-293-qe-sign` (`compare_all.sh` reruns the check). Unfolded weights, intra-atom phase products and all atom-pair phase products match nosym to 3.0e-5 (SrVO3, bands 1 to 26 of 30) and 2.9e-4 (LaVO3, bands 1 to 31 of 34), within the reference's own symmetry spread of 1.8e-4 and 3.3e-4. LaVO3's band 32 raises the all-pairs figure to 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. The nosym energies equal the IBZ run's to 5e-10 eV at the IBZ k-points but only to 5.5e-6 eV (SrVO3) and 1.3e-5 eV (LaVO3) at their symmetry images. Without the f aliases the phases drop and V eg is off by 0.30 and La f by 1.0; without the sign flip the weights still match (cubic operations only permute signed orbitals) but phase products are off by up to 1.4. On the fixtures, each nondegenerate band with V weight is an eigenvector of the orbital rotation of every operation fixing its k (max residual 4.2e-4, against 1.0 without the flip). +- `qe` meshes (`data/codes/qe/7.2/SrVO3/*/fermi`, #293): ibz2fbz rotates s, p, d and f with no warning, and the two collinear meshes keep `projected_phase`. ibz2fbz knows projwfc.x's f labels through `ORBITAL_ALIASES`, and the parser turns QE's (-1)^|m| harmonic signs (`upflib/ylmr2.f90`) into the core's. The independent reference is QE 7.5 IBZ and nosym 6x6x6 runs of SrVO3 and spin-polarized LaVO3 in `~/Documents/lllangWV-Projects/DFT/pyprocar-293-qe-sign` (`compare_all.sh` reruns the check). Unfolded weights, intra-atom phase products and all atom-pair phase products match nosym to 3.0e-5 (SrVO3, bands 1 to 26 of 30) and 2.9e-4 (LaVO3, bands 1 to 31 of 34), within the reference's own symmetry spread of 1.8e-4 and 3.3e-4. LaVO3's band 32 raises the all-pairs figure to 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. At the IBZ k-points the nosym energies equal the IBZ run's to 1e-12 eV (SrVO3, bands 1 to 26) and 5e-10 eV (LaVO3, bands 1 to 30; band 32 differs by 4e-6 eV), but at their symmetry images only to 5.5e-6 eV (SrVO3) and 1.3e-5 eV (LaVO3) at their symmetry images. Without the f aliases the phases drop and V eg is off by 0.30 and La f by 1.0; without the sign flip the weights still match (cubic operations only permute signed orbitals) but phase products are off by up to 1.4. On the fixtures, each nondegenerate band with V weight is an eigenvector of the orbital rotation of every operation fixing its k (max residual 4.2e-4, against 1.0 without the flip). - `elk` structure: all four `data/codes/elk/6.3/SrVO3/*` dirs give a 3.841244 Angstrom cubic lattice, through `GEOMETRY.OUT` or, in `non-spin-polarized/bands`, the `elk.in` fallback. Their `structure.pkl` files hold the pre-#242 Bohr lattice (7.2589), so do not compare against them. - `get_parser` writes nothing into the dir. - `abinit` (`data/codes/abinit/9.6/Fe/*/bands`, #255): `kpath` ticks are `Γ(0) H(50) N(100) Γ(150) P(200) H|P(250) N(300)`, and `ebs` is an `ElectronicBandStructurePath`. Abinit writes each segment boundary once, so a wrong segmentation shows as 3 ticks `Γ(0) H|H(250) N(300)`. With Cartesian x-distances, Γ–H is `1/a` = 0.3521 Å⁻¹ (a = 2.84 Å).