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 a64a87c4..b7b162c8 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 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 Å). diff --git a/pyprocar/core/ebs.py b/pyprocar/core/ebs.py index 59a09057..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): @@ -2073,7 +2079,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..79ece507 100644 --- a/pyprocar/io/qe/parser.py +++ b/pyprocar/io/qe/parser.py @@ -32,6 +32,15 @@ user_logger = logging.getLogger("user") +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 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,17 +697,23 @@ 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): - 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] + 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: diff --git a/tests/pyprocar/core/test_fermisurface_phases.py b/tests/pyprocar/core/test_fermisurface_phases.py new file mode 100644 index 00000000..d0d07abd --- /dev/null +++ b/tests/pyprocar/core/test_fermisurface_phases.py @@ -0,0 +1,30 @@ +import numpy as np + +from pyprocar.core.ebs import ElectronicBandStructureMesh +from pyprocar.core.fermisurface import FermiSurface +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: + kpoints, energies = _sphere_energies() + ebs = ElectronicBandStructureMesh( + 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)), + 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=2) + + 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 + ) 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..e00738c0 --- /dev/null +++ b/tests/pyprocar/io/qe/test_qe_phase_convention.py @@ -0,0 +1,190 @@ +"""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, 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 +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 + + +@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") + ) + 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(bands.value), axis=1), + ((0, 0), (1, 1), (0, 0)), + constant_values=np.inf, + ) + norms = np.linalg.norm(phases, axis=-1) + 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) + mask = selected & fixed[:, np.newaxis, np.newaxis] + coefficients, norm = phases[mask], norms[mask] + 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) + residuals = np.concatenate(residuals) + + assert len(residuals) > 1000 + assert residuals.max() < 0.05