Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
36 commits
Select commit Hold shift + click to select a range
ca81311
test(core): projections whose axes disagree with bands, total or stru…
lllangWV Oct 4, 2026
e8ac1a1
fix(core): check projection axes against the bands, total DOS and str…
lllangWV Oct 4, 2026
f9588ae
test(qe): non-collinear band structures carry total, Sx, Sy and Sz pe…
lllangWV Oct 4, 2026
c97b9c0
fix(qe): give non-collinear band structures total, Sx, Sy and Sz per …
lllangWV Oct 4, 2026
4c21914
test(io): every parser names the orbitals it projects
lllangWV Oct 4, 2026
1a58797
fix(io): pass the orbital names each parser projects
lllangWV Oct 4, 2026
ea00289
test: type the layout and QE spinor test inputs for basedpyright
lllangWV Oct 4, 2026
d7dac49
refactor(qe): parse projwfc states into a SpinorState before the spin…
lllangWV Oct 4, 2026
a99b8f3
docs(claude): state what check_projected_layout now enforces
lllangWV Oct 4, 2026
2e6d975
style(abinit): name the angular momentum ang
lllangWV Oct 4, 2026
f19c92d
test(abinit): a non-collinear DOS carries total, Sx, Sy and Sz
lllangWV Oct 4, 2026
023e7e4
fix(abinit): give a non-magnetic spinor DOS total, Sx, Sy and Sz chan…
lllangWV Oct 4, 2026
a3e5634
refactor(io): simplify the #293 parser changes and pass the structure…
lllangWV Oct 4, 2026
c94ee3b
docs(verify-pyprocar): record the QE non-collinear projection end state
lllangWV Oct 4, 2026
5af318a
test: filtered PROCARs load, group rows and name orbitals as their he…
lllangWV Oct 4, 2026
4774cc7
fix(vasp): load a PROCAR filtered by atoms as groups of atoms and lab…
lllangWV Oct 4, 2026
0f9ef0a
fix(scripts): raise a clear error for a single orbital selected by name
lllangWV Oct 4, 2026
a5f4cc0
chore(basedpyright): drop the two resolver comparisons the atom_group…
lllangWV Oct 4, 2026
e2437bb
docs(filter): say what the rows and columns of a filtered PROCAR mean…
lllangWV Oct 4, 2026
cd23593
test(scripts): a shell name selects the columns a filtered PROCAR's h…
lllangWV Oct 4, 2026
233108a
fix(scripts): resolve shell names from the orbital names, as labels do
lllangWV Oct 4, 2026
7427caa
test(scripts): a shell letter selects the column a filtered PROCAR na…
lllangWV Oct 4, 2026
21594b1
fix(scripts): a column named s, p, d or f is that shell for selections
lllangWV Oct 4, 2026
ef82221
docs(verify-pyprocar): record the filtered PROCAR end states
lllangWV Oct 4, 2026
183f807
test: mark the accepted spin layouts as guarding existing behaviour
lllangWV Oct 4, 2026
db7f801
test: a selection without atoms sums every row, a part shell is no sh…
lllangWV Oct 4, 2026
74cf642
test: an empty atom selection raises instead of summing nothing
lllangWV Oct 4, 2026
4c7076c
fix(core): a selection without atoms resolves to every atom row
lllangWV Oct 4, 2026
ae4296a
fix(ebs): refuse to unfold an atom-filtered PROCAR from irreducible k…
lllangWV Oct 4, 2026
843f2bd
chore: annotate the resolver row count and type the filter groups in …
lllangWV Oct 4, 2026
0299653
test: name n_atoms in the guard reason of the selection label test
lllangWV Oct 4, 2026
6694ee4
test: keep the guard reason within the line limit
lllangWV Oct 4, 2026
a16f163
refactor: check atom groups before ibz2fbz copies any property, and r…
lllangWV Oct 4, 2026
cb03e31
test: an empty spin selection raises instead of summing nothing
lllangWV Oct 4, 2026
79efb00
fix(core): an empty spin selection raises, as an empty atom selection…
lllangWV Oct 4, 2026
ea94998
fix: send the abinit spinor-DOS and VASP atom-group warnings through …
lllangWV Oct 4, 2026
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
16 changes: 0 additions & 16 deletions .basedpyright/baseline.json
Original file line number Diff line number Diff line change
Expand Up @@ -779,22 +779,6 @@
"lineCount": 1
}
},
{
"code": "reportUnnecessaryComparison",
"range": {
"startColumn": 50,
"endColumn": 71,
"lineCount": 1
}
},
{
"code": "reportUnnecessaryComparison",
"range": {
"startColumn": 47,
"endColumn": 71,
"lineCount": 1
}
},
{
"code": "reportUnreachable",
"range": {
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 @@ -24,6 +24,7 @@ The proven end state (1f36aae1; `vasp` and `qe` re-driven at d6d4aaa7):
- That 4.9992 is the nscf vasprun value. It is not the SCF value 5.3017 that the examples pass as `fermi=`, so object-API plots are shifted by 4.9992.
- `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`).
- `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
1 change: 1 addition & 0 deletions .claude/skills/verify-pyprocar/features/utilities.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ The proven end state (SrVO3, non-spin-polarized, d6d4aaa7, driven 2026-10-04):
- `repair`: 2,363,890 bytes, with a valid `PROCAR lm decomposed` header.
- `cat` of the PROCAR with itself: one header with `# of k-points: 400`.
- `generate2dkmesh(-0.5,-0.5,0.5,0.5,0,5,4)`: shape `[20, 3]`, and `Kgrid.dat` starts `Generated by PyProcar / 20 / Reciprocal`.
- A filtered PROCAR plots (#293, `tests/pyprocar/scripts/test_filtered_procar.py`). With `atoms=[[0],[1],[2,3,4]]` the PROCAR has 3 rows next to the 5-atom POSCAR. The parser warns and sets `ebs.atom_groups = 3`. `bandsplot(mode='parametric', atoms=[2])` draws the same colours as `atoms=[2,3,4]` on the unfiltered PROCAR. Species selections (`atoms=['O']`, `overlay_species`, `items`) raise `Cannot select species 'O'`. With `orbitals=[[0],[1,2,3]]` the columns are labelled `o0` and `o1`, and `orbitals=['p']` raises `hold no whole p shell`. On the irreducible k-points of `data/examples/fermi2d/non-spin-polarized`, `fermi2D` of an atom-filtered PROCAR raises `filtered by atoms cannot be unfolded`, because ibz2fbz (#299) permutes atoms between rows the file no longer names. A structure-less DOS (every Lobster DOS) sums every atom row when a selection names no atoms: `dosplot(code='lobster', mode='parametric', orbitals=[1,2,3])` colours by the p weight of all atoms.
- `side_effects.txt`: `KPOINTS_pyprocar`, `PROCAR_bands_1_5`, `PROCAR_repaired`, `PROCAR_merged`, `Kgrid.dat`. `bandgap` writes nothing.

## Gotchas
Expand Down
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ When a reviewer corrects a mistake, fix it and add its rule here. If the rule is
| Code runs on the declared floor, Python 3.12. | ruff `target-version` and basedpyright `pythonVersion`; `tests/test_python_floor.py` keeps those, `pyproject.toml` and `pixi.toml` equal |
| Physical constants come from `pyprocar/utils/units.py`. | `tests/test_unit_constants.py` |
| `pixi.toml` tasks name only defined tasks, environments and files. | `tests/test_pixi_manifest.py` |
| Parsers hand the core projections as `(k, band, spin, atom, orbital)` for bands and `(energy, spin, atom, orbital)` for DOS, with one orbital name per orbital. | `check_projected_layout` in the `ElectronicBandStructure` and `DensityOfStates` constructors |
| Parsers hand the core projections as `(k, band, spin, atom, orbital)` for bands and `(energy, spin, atom, orbital)` for DOS. The leading axes match the bands or total DOS, the atom axis matches the structure (or the `atom_groups` count of a PROCAR filtered by atoms), and there are 1, 2 or 4 spin channels (non-collinear is total, Sx, Sy, Sz, with 1 or 4 band channels). Every parser passes one name per orbital it projects. | `check_projected_layout` in the `ElectronicBandStructure` and `DensityOfStates` constructors; `tests/pyprocar/io/test_orbital_names.py` |
| Scripts, notebooks and docs call `pyprocar.*` with its current signature, and every `ebs.<member>` they name exists. | `tests/test_documented_calls.py` |
| Tests never write `data/`; a test that reads it is marked `data`. | audit hook in `tests/conftest.py` |
| A message the user must see or act on is a `UserWarning` from `warn_user` (`pyprocar/utils/log_utils.py`), which names the user's line; the `user` logger carries only info and debug progress. Tests assert a warning with `tests/utils/user_warning.py`, which also checks the line it names. | `tests/test_user_warnings.py`. In `pyprocar/` it fails on `.warning`, `.error`, `.critical`, `.exception`, `.fatal`, `.warn`, or `.log` with a constant or named level of WARNING or above, called on `getLogger("user")`, on a name bound to it in the same function or module, on a `self.` attribute bound to it in the same class, or on a name imported from another module that binds it; and on `warn` or `warn_explicit` from the `warnings` module outside `log_utils.py`. In `tests/` it fails on `caplog.at_level` or `set_level` with logger `"user"`, on `setLevel` on the user logger, and on `pytest.warns(UserWarning, ...)` outside the helper. |
Expand Down
17 changes: 17 additions & 0 deletions docs/source/user-guide/filter.rst
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,10 @@ If you want to select only :math:`p_x` orbitals, just use ``orbitals=[[3]]``.

In the same way to plot the projection of total :math:`p`-orbitals use ``orbitals=[[1,2,3]]`` (i.e. :math:`px+py+pz`). Same goes for other orbitals.

Each new column is named by ``orbital_names``, which defaults to ``o0``, ``o1``, and so on. PyProcar reads these names from the header of the new file, so plots label the columns ``o0`` and ``o1``. In the new file, orbital index ``i`` selects the ``i``-th column, so ``orbitals=[1]`` selects the :math:`p` sum of the example above. Pass ``orbital_names=['s','p']`` to label the columns ``s`` and ``p``.

A shell name such as ``orbitals=['p']`` selects the column named ``p``, or the columns whose names make up the whole :math:`p` shell, for example ``py``, ``pz`` and ``px``. Columns named ``o0`` and ``o1`` make up no shell, so select them by index.

===================================
To filter selected :math:`k`-points
===================================
Expand Down Expand Up @@ -57,5 +61,18 @@ Usage::

PyProcar counts each row of ions in PROCAR file starting from 0. Keep in mind: ``atoms=0`` does not define the atom_type, rather it defines only the first ion in the POSCAR. So if you have more than one ion of the same element, use ``atoms = [[0,1,2,3,...]]``.

Each group in ``atoms`` becomes one row of the new PROCAR, the sum of the rows of its atoms. For a SrVO3 calculation with the POSCAR order Sr, V, O, O, O::

pyprocar.filter('PROCAR','PROCAR-filtered_atoms', atoms=[[0],[1],[2,3,4]])

writes 3 rows: Sr, V, and the sum of the three O atoms. To plot the new file, rename it to ``PROCAR`` in the calculation directory. When the PROCAR has fewer or more rows than the POSCAR has atoms, PyProcar warns that the PROCAR was filtered by atoms and treats each row as a group:

- Atom index ``i`` selects the ``i``-th group, so ``atoms=[2]`` selects the three O atoms. Plots label a selection by its group indices, not by a species.
- A plot with no ``atoms`` sums every group.
- A selection by species raises an error, because a group can hold atoms of several species. This includes ``atoms=['O']`` and the ``overlay_species`` mode. Select groups by index instead.
- A Fermi surface or other k-point mesh needs the full k grid. Unfolding the irreducible k-points moves atoms between rows, and the filtered file does not say which atoms a row holds, so PyProcar raises an error. Filter the PROCAR of a calculation on the full k grid (``ISYM = -1``), or plot the unfiltered PROCAR and select atoms there.

PyProcar cannot detect a filtered PROCAR that has exactly as many rows as the POSCAR has atoms. It then labels each row with the species of the POSCAR atom at the same index.

.. automodule:: pyprocar.scripts.scriptFilter
:members:
73 changes: 58 additions & 15 deletions pyprocar/core/atomic_orbital_index.py
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,43 @@
}


_SHELL_LETTERS = "spdf"
_LETTER_ORBITAL_NAME = re.compile(r"\d*([spdf])[_xyz0-9^()\- ]*")
_ELK_ORBITAL_NAME = re.compile(r"Y(\d)-?\d+")


def _angular_momentum(orbital_name: str) -> int | None:
"""The l of an orbital name a parser writes (``px``, ``d_z^2``, ``x2-y2``, Elk's ``Y1-1``)."""
if orbital_name == "x2-y2":
return 2
if elk := _ELK_ORBITAL_NAME.fullmatch(orbital_name):
return int(elk[1])
if letter := _LETTER_ORBITAL_NAME.fullmatch(orbital_name):
return _SHELL_LETTERS.index(letter[1])
return None


def orbital_shells(orbital_names: Sequence[str] | None) -> tuple[tuple[str, tuple[int, ...]], ...]:
"""The whole s, p, d and f shells among the orbitals, as (letter, orbital indices).

Without names the slots of the conventional table stand. With names, shell l is
the 2l+1 orbitals whose names have angular momentum l, so a filtered PROCAR's
``o0`` or a spin-orbit ``l1_j1.5_m0.5`` state is in no shell.
"""
if not orbital_names:
return PRIMARY_ORBITAL_GROUPS
by_l: dict[int, list[int]] = {}
for index, name in enumerate(orbital_names):
ang = _angular_momentum(name)
if ang is not None:
by_l.setdefault(ang, []).append(index)
return tuple(
(letter, tuple(by_l[ang]))
for ang, letter in enumerate(_SHELL_LETTERS)
if len(by_l.get(ang, ())) == 2 * ang + 1
)


def _normalize_indices(indices: Iterable[int] | None) -> list[int]:
if indices is None:
return []
Expand Down Expand Up @@ -304,12 +341,12 @@ def _build_label_tokens(
return []

if is_non_colinear and (orbital_names is None or len(orbital_names) == 0):
return [self._format_soc_label(idx) for idx in normalized]
return [self.soc_label(idx) for idx in normalized]

remaining = set(normalized)
tokens: list[str] = []
if prefer_groups:
for group_name, group_indices in PRIMARY_ORBITAL_GROUPS:
for group_name, group_indices in orbital_shells(orbital_names):
group_set = set(group_indices)
if group_set and group_set <= remaining:
tokens.append(group_name)
Expand Down Expand Up @@ -406,7 +443,7 @@ def _build_index_map(self, list_a: Sequence[str], list_b: Sequence[str]) -> dict
mapping[i] = list_b.index(orb)
return mapping

def _format_soc_label(self, index: int) -> str:
def soc_label(self, index: int) -> str:
if 0 <= index < len(self.flat_soc_order):
entry = self.flat_soc_order[index]
l = entry.get("l")
Expand Down Expand Up @@ -838,11 +875,13 @@ def __init__(
self,
*,
label_builder: ProjectionLabelBuilder,
n_atom_rows: int,
orbital_names: Sequence[str] | None = None,
is_non_colinear: bool = False,
) -> None:
self.label_builder = label_builder
self.atom_indexer = label_builder.atom_indexer
self.n_atom_rows: int = n_atom_rows
self.orbital_names = orbital_names
self.is_non_colinear = is_non_colinear

Expand Down Expand Up @@ -910,18 +949,18 @@ def resolve(
atoms_set = set()
for specie in species_list:
atoms_set.update(self._atoms_for_species(specie))
elif atoms_set is None:
if self.atom_indexer is None:
raise ValueError(
"Atom indexer is required when atoms and species selections are omitted"
)
species_map = self.atom_indexer.species_atom_map()
species_list = list(species_map.keys())
atoms_set = {idx for indices in species_map.values() for idx in indices}
else:
elif atoms_set is not None:
species_list = self._species_from_atoms(sorted(atoms_set))
elif self.atom_indexer is not None:
species_list = list(self.atom_indexer.species_atom_map().keys())

atoms_tuple = tuple(sorted(atoms_set)) if atoms_set is not None else tuple()
atoms_tuple = (
tuple(sorted(atoms_set)) if atoms_set is not None else tuple(range(self.n_atom_rows))
)
if not atoms_tuple:
raise ValueError("The selection names no atoms; select at least one atom or species")
if spins_set is not None and not spins_set:
raise ValueError("The selection names no spins; omit spins to select every channel")
orbitals_tuple = (
tuple(sorted(orbitals_set))
if orbitals_set is not None and len(orbitals_set) > 0
Expand All @@ -931,7 +970,7 @@ def resolve(
species_tuple = tuple(species_list) if species_list is not None else tuple()

labels = self.label_builder.build_components(
atoms=atoms_tuple if atoms_tuple else None,
atoms=atoms_tuple,
orbitals=orbitals_tuple,
spins=spins_tuple,
species=species_tuple,
Expand Down Expand Up @@ -990,7 +1029,11 @@ def _ensure_mapping(mapping: Mapping) -> Mapping:

def _atoms_for_species(self, specie: str) -> tuple[int, ...]:
if self.atom_indexer is None:
raise ValueError("Species selections require atom indexing information")
raise ValueError(
f"Cannot select species {specie!r}: the projections name no species per atom row,"
+ " because there is no structure or because each row is a group of atoms"
+ " (a PROCAR filtered by atoms). Select rows by index with atoms=[...]."
)
mapping = self.atom_indexer.species_atom_map([specie])
if specie not in mapping:
raise ValueError(f"Species '{specie}' not found in atom index")
Expand Down
13 changes: 4 additions & 9 deletions pyprocar/core/dos.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@

from pyprocar.core.atomic_orbital_index import ProjectionSelectionResolver
from pyprocar.core.projection import (
DOS_PROJECTIONS,
NormMode,
build_property,
check_projected_layout,
Expand Down Expand Up @@ -201,6 +202,8 @@ def _units_divide(u_input: str, u_norm: str | None) -> str:
class DensityOfStates(PointSet):
"""Data-centric representation of a density of states calculation."""

atom_groups: int | None = None

def __init__(
self,
energies: npt.ArrayLike,
Expand Down Expand Up @@ -245,7 +248,7 @@ def __init__(
if projected is not None:
projected_array = self._validate_projected(projected)
check_projected_layout(
projected_array, orbital_names, ("n_energies", "n_spins", "n_atoms", "n_orbitals")
projected_array, orbital_names, DOS_PROJECTIONS, total_array, structure
)
self.add_property(
name="projected",
Expand Down Expand Up @@ -1584,14 +1587,6 @@ def _validate_projected(self, projected: npt.ArrayLike) -> npt.NDArray[np.float6
if projected_array.ndim == 3:
projected_array = projected_array[:, np.newaxis, :, :]

if projected_array.ndim != 4:
raise ValueError(
"Projected DOS must have shape (n_energies, n_spins, n_atoms, n_orbitals)"
)

if projected_array.shape[0] != self.n_energies:
raise ValueError("Projected DOS must align with the energy grid")

return projected_array

@cached_property
Expand Down
Loading
Loading