Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .claude/skills/verify-pyprocar/features/fermi3d.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
1 change: 1 addition & 0 deletions .claude/skills/verify-pyprocar/features/parsers.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 Å).
Expand Down
14 changes: 13 additions & 1 deletion pyprocar/core/ebs.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down Expand Up @@ -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"}


Expand Down
27 changes: 21 additions & 6 deletions pyprocar/io/qe/parser.py
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down Expand Up @@ -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:
Expand Down
30 changes: 30 additions & 0 deletions tests/pyprocar/core/test_fermisurface_phases.py
Original file line number Diff line number Diff line change
@@ -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
)
190 changes: 190 additions & 0 deletions tests/pyprocar/io/qe/test_qe_phase_convention.py
Original file line number Diff line number Diff line change
@@ -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
Loading