Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
41 commits
Select commit Hold shift + click to select a range
9cbd997
test: copy fixtures with writable_copy so read-only fixtures work
lllangWV Oct 4, 2026
5ef882e
test(verify-pyprocar): verify.sh locks only fixtures and unlocks only…
lllangWV Oct 4, 2026
59d82f1
feat(verify-pyprocar): make fetched fixtures read-only through one pa…
lllangWV Oct 4, 2026
3252f64
docs(verify-pyprocar): document read-only fixtures and the verify.sh …
lllangWV Oct 4, 2026
51c1d7c
refactor(verify-pyprocar): name the path helpers for what they check …
lllangWV Oct 4, 2026
1f91eed
test: state the writable_copy guard reason as one string
lllangWV Oct 4, 2026
17de47a
test(verify-pyprocar): verify.sh changes nothing outside data/ under …
lllangWV Oct 4, 2026
328f485
fix(verify-pyprocar): act only strictly below the main checkout's data/
lllangWV Oct 4, 2026
8849d35
docs(verify-pyprocar): state the data-root rule and name copies to un…
lllangWV Oct 4, 2026
6d134a3
test: assert the prefix download first and drop guard marks on tests …
lllangWV Oct 4, 2026
70deaaa
test: download_from_hf leaves the shared Hugging Face cache alone
lllangWV Oct 4, 2026
9804504
fix(download): fetch the one archive into a staging dir, not the shar…
lllangWV Oct 4, 2026
d9fe732
refactor(verify-pyprocar): guard deletes like chmods and share the do…
lllangWV Oct 4, 2026
5fcb410
test: take the hub arguments the fake ignores as keywords
lllangWV Oct 4, 2026
547e5d2
test(verify-pyprocar): run refuses a run dir that already exists; doc…
lllangWV Oct 4, 2026
1fe899c
fix(verify-pyprocar): run writes only into a run dir it has just created
lllangWV Oct 4, 2026
336d314
docs(verify-pyprocar): name the Hugging Face ref a download writes, t…
lllangWV Oct 4, 2026
8cdaf45
refactor(verify-pyprocar): scope noclobber to the .pid write and plan…
lllangWV Oct 4, 2026
f6d5cb3
test(verify-pyprocar): decode verify.sh output as UTF-8 and keep cens…
lllangWV Oct 4, 2026
40334f4
test(filter): copy the fixture writable in test_filtered_procar so a …
lllangWV Oct 4, 2026
067a925
test(verify-pyprocar): gc keeps the work of a run whose pid is alive
lllangWV Oct 4, 2026
b0fc705
test(download): download_from_hf stages beside the fixture, not in th…
lllangWV Oct 4, 2026
b6ad00c
test(verify-pyprocar): fetch downloads with hf_xet log cleanup off, t…
lllangWV Oct 4, 2026
6ffeb6c
fix(verify-pyprocar): keep hf_xet's log cleanup off in fetch, run pix…
lllangWV Oct 4, 2026
7129453
test(verify-pyprocar): census also flags fd and & redirects, in-place…
lllangWV Oct 4, 2026
ece0c74
docs(verify-pyprocar): list every write outside data/ and unlock a fi…
lllangWV Oct 4, 2026
3ab171c
docs(verify-pyprocar): name the staging dir hf_xet creates beside its…
lllangWV Oct 4, 2026
b0174e1
docs: only worktree-setup refreshes a git index
lllangWV Oct 4, 2026
ed991c0
test(verify-pyprocar): assert gc's kept and removed work, not its mes…
lllangWV Oct 4, 2026
2beef1c
test: fail when a test copies a fixture path without tests.utils.writ…
lllangWV Oct 4, 2026
7b85d98
test(elk,autobandsplot): copy fixtures with writable_copy so locked f…
lllangWV Oct 4, 2026
da7c2e4
test: make the fixture-copy self-test reach writable_copy with a fixt…
lllangWV Oct 4, 2026
63bc67c
fix(verify-pyprocar): start main-checkout python with PYTHONDONTWRITE…
lllangWV Oct 4, 2026
cb2ce85
test(verify-pyprocar): doctor leaves a stat-dirty git index alone
lllangWV Oct 4, 2026
7569508
test(verify-pyprocar): census flags "${cmd[@]}", "${@}" and if/while …
lllangWV Oct 4, 2026
a07f8a9
docs: list matplotlib's config and font cache among verify.sh's write…
lllangWV Oct 4, 2026
6923f2b
refactor(tests): inline one-caller helpers in the fixture-copy check,…
lllangWV Oct 4, 2026
5222718
fix(tests): type-narrow the fixture-copy scope, keep the Elk calc dir…
lllangWV Oct 4, 2026
5b8b2c9
refactor(verify-pyprocar): export PYTHONDONTWRITEBYTECODE once for ev…
lllangWV Oct 5, 2026
4acf579
refactor(tests): simplify the fixture-copy check (derived shell set, …
lllangWV Oct 5, 2026
bf6b7a1
style(tests): one condition for fixture registration, and keep the ex…
lllangWV Oct 5, 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
26 changes: 22 additions & 4 deletions .claude/skills/verify-pyprocar/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,23 @@ There is nothing to keep alive. "Launch" means the env and fixtures exist:
$H fetch data/examples/bands/non-spin-polarized # idempotent; ~20-35 MB each, into ./data (gitignored)
```

`fetch` downloads a missing fixture, then makes it read-only, so a stray write into a fixture fails with `PermissionError` whatever the code path. Rerun it on an existing fixture to lock it; that needs no download and no env, in a linked worktree too. It takes a fixture root, `data/examples/<category>/<name>` or `data/<name>`, spelled in plain names (letters, digits, `_`, `.` and `-`, not starting with `.` or `-`), and refuses a path whose real location is not a fixture inside `data/`. A download fetches exactly `<relpath>.zip` from the dataset into a staging dir next to the fixture, so a misspelt or partial name fails without downloading. A file with a second hard link stays writable, because its other link may be outside `data/`; `fetch` names each one on stderr. Code that must write next to a fixture works on a writable copy: `$H run` makes one, drivers call `writable_copy` from `verify_steps`, and tests call `writable_copy` from `tests.utils`.

To refresh a locked fixture, the operator unlocks its directories from the main checkout's root, removes it, and fetches it again. `rm -rf` needs write permission on directories only, so the files keep their modes, and a file whose second hard link is outside `data/` is never unlocked:

```bash
find -P data/examples/<category>/<name> -type d -exec chmod u+w {} +
rm -rf data/examples/<category>/<name>
$H fetch data/examples/<category>/<name>
```

`doctor`, `fetch`, `run`, `clean` and `gc` act only inside the data root, apart from the writes listed below, and exit 2 unless `data` resolves to the main checkout's `data/` directory: the directory itself in the main checkout, a symlink to it in a linked worktree (`$H worktree-setup` makes it). `data/verify-runs` must be a directory in it, not a symlink. A `data` symlink in the main checkout, for example to another disk, is refused. Every chmod and delete stays strictly below the data root and never follows a symlink. `run` writes only into a run dir it has just created. These writes fall outside the data root:

- `doctor`, a download in `fetch`, and the driver in `run` import `pyprocar` with the repo root as working directory, and the import appends to `<repo>/pyprocar.log`. The import also loads matplotlib, which creates `~/.config/matplotlib` and writes its font cache `~/.cache/matplotlib/fontlist-v<N>.json` when that file is missing or stale. With `MPLCONFIGDIR` set, both go there instead.
- A download writes `<HF cache>/datasets--lllangWV--pyprocar_test_data/refs/main`, because `huggingface_hub` records the dataset's commit there even with `local_dir`. `hf_xet` also writes a log to `$HF_HOME/xet/logs/` and creates `chunk-cache/` and `staging/` in `$HF_HOME/xet/<endpoint>/` (`HF_HOME` defaults to `~/.cache/huggingface`). `fetch` sets `HF_XET_LOG_DIR_DISABLE_CLEANUP=1`, so the download deletes none of the older logs there.
- In the main checkout, `doctor`, a download in `fetch` and `run` start python with `pixi run --locked -e default`, and `exec` uses `pixi run --locked -e dev`. `--locked` never rewrites `pixi.lock`, but pixi installs or updates the env when it does not match the lock. In a linked worktree they use the main checkout's env as it is. Both set `PYTHONDONTWRITEBYTECODE=1`, so python writes no `__pycache__` in either checkout.
- `worktree-setup` and `exec` write their own worktree's `pyprocar/_version.py`, `.tmp` and `data` link. `worktree-setup`'s `git diff` can refresh that worktree's git index. `doctor` runs `git status` with `GIT_OPTIONAL_LOCKS=0`, so it leaves the index alone.

Fixture relpaths (HF dataset `lllangWV/pyprocar_test_data`): `data/examples/{bands,dos,fermi3d,fermi2d}/{non-spin-polarized,spin-polarized,non-colinear}`, plus `bands/{atomic_levels,auto,compare_bands,ipr,unfolding,2d-bands}`, `fermi2d/bisb_monolayer`, `fermi3d/van-alphen`. All are VASP; Fermi energy for the SrVO3 sets is `5.3017`.

Other codes are already extracted under `data/codes/`: `qe/7.2/SrVO3`, `elk/6.3/SrVO3` and `vasp/6.4/SrVO3` (spin variants), and `abinit/9.6/Fe`. Siesta has no fixture; its tests build synthetic dirs. `features/parsers.md` lists the proven end states. For an independent reference from another code, run it with `pixi exec -s qe` (or `-s abinit`, `-s gfortran`), and keep its inputs and outputs outside any worktree, because `git worktree remove --force` deletes them.
Expand Down Expand Up @@ -51,6 +68,7 @@ It copies `_version.py` from the main checkout and links `data` to the main chec
In every worktree:

- `data/` is shared and holds `.py` files. Give pytest an explicit test path, so it never collects them, and `-p no:cacheprovider`. Write under `data/` only through `$H fetch`, which adds fixtures to the shared cache, and `$H run`, which works on a per-run copy in `data/verify-runs/`.
- Before `git worktree remove --force`, make the read-only copies inside the worktree writable by naming each one, for example `find -P .tmp -type d -exec chmod u+w {} +` for pytest temp copies of locked fixtures, or the removal fails with `Permission denied`. Name the copies only, never `data` or a path through it: in a worktree `data` is the shared fixture store, and a recursive chmod through it unlocks every fixture.
- The `data`-marked tests take 10-12 minutes per checkout. Run the modules for the packages you touch in the background, at your head and at `origin/dev`, so a new failure stands apart from an old one.
- CI has no `data/`. The conftest guard fails an unmarked test that opens or lists `data/`, but a read at import or collection time escapes it: it passes locally and fails in CI. Mark every test that needs a fixture `data`.
- CI runs the lint and format gates on the PR merged into `dev`. Judge `ruff_new_violations.py` on your head merged with current `origin/dev` (in a detached scratch worktree), because on a head behind `dev` it also flags files that only `dev` changed.
Expand All @@ -62,7 +80,7 @@ In every worktree:
$H doctor
```

Read-only. It prints the branch/commit, the count of dirty tracked files, the python/pyprocar/pyvista/vtk versions, the import path (it must be this checkout's `pyprocar/`), and the fixtures present. It is worth driving when pyprocar imports from this repo and the fixture you need is listed. A `dirty` count you didn't cause means someone is mid-edit, so say so before trusting results.
It changes nothing apart from the writes listed under Launch. It prints the branch/commit, the count of dirty tracked files, the python/pyprocar/pyvista/vtk versions, the import path (it must be this checkout's `pyprocar/`), and the fixtures present. `writable fixture paths` counts the files and dirs in each fixture root that still have a write bit, and a root that is a symlink counts its target; above 0, lock those fixtures with `$H fetch <relpath>`. `unlockable fixture roots` lists each entry of `data/` and `data/examples/<category>/` that `fetch` refuses, such as a name with a space or a leading `.`, or a symlink out of `data/`; rename or remove each one. It is worth driving when pyprocar imports from this repo and the fixture you need is listed. A `dirty` count you didn't cause means someone is mid-edit, so say so before trusting results.

## Drive

Expand All @@ -71,8 +89,8 @@ $H run <name> <fixture-relpath> <driver.py>
```

What the harness does:
1. Creates `data/verify-runs/<timestamp>-<name>/`.
2. Copies the fixture to `work/calc` (a reflink copy where the filesystem supports it) and the driver to `evidence/driver.py`.
1. Creates a new `data/verify-runs/<timestamp>-<name>/`. It refuses (exit 2) when anything already has that name, such as a second run with the same name in the same second, so rerun it.
2. Copies the fixture to `work/calc`, following symlinks (a reflink copy where the filesystem supports it), makes the copy writable, and copies the driver to `evidence/driver.py`. `<name>` is one plain name, and the fixture must resolve to a fixture directory inside `data/`.
3. Runs the driver with `TMPDIR=work/tmp`, `CALC=<calc copy>`, `EVIDENCE=<evidence dir>`, `REPO=<repo root>`, `MPLBACKEND=Agg`, `PYVISTA_OFF_SCREEN=true`, and `scripts/lib` on `PYTHONPATH`. pytest puts its `--basetemp` root under `TMPDIR`, so a driver that starts pytest also writes under the run.
4. Records the exit code, `run.log` (stdout+stderr), and `side_effects.txt`, which lists files created or modified inside the calc copy.

Expand Down Expand Up @@ -140,7 +158,7 @@ This removes the `work/` copy of every run that started more than `hours` ago, f
- `scripts/verify.sh`: `doctor | fetch <relpath>... | run <name> <fixture> <driver.py> | clean <run-dir> | gc [hours] | worktree-setup | exec <cmd>...`
- `scripts/examples/bands_plain.py`: the minimal single-call template, which exits 0. Copy it for a one-off driver.
- `scripts/examples/{bands,dos,fermi3d,fermi2d,bs2d,parsers,utilities}.py`: full per-feature drivers. Run them as shown under Drive.
- `scripts/lib/verify_steps.py`: `step`, `png`, `distinct_colors` and `finish` for multi-step drivers. It is importable because the harness puts `scripts/lib` on `PYTHONPATH`.
- `scripts/lib/verify_steps.py`: `step`, `png`, `distinct_colors`, `writable_copy` and `finish` for multi-step drivers. It is importable because the harness puts `scripts/lib` on `PYTHONPATH`.
- `scripts/lib/references/`: independent references (unfolding weights, reduced spin mesh, tiled cut orbits), each with an analytic `validate()` and a `ref_*.py` driver. Compare against one of these before you write your own; `features/README.md` lists them.

Known repo issues that affect verification (as of dev @ d6d4aaa7):
Expand Down
5 changes: 2 additions & 3 deletions .claude/skills/verify-pyprocar/scripts/examples/bands.py
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
# Bands along a k-path: object API (plain/parametric/scatter/quiver/overlay/flip)
# and legacy bandsplot/bandsdosplot.
# Fixture: data/examples/bands/non-spin-polarized
import shutil

import matplotlib.pyplot as plt
import numpy as np
from verify_steps import CALC, EV, REPO, finish, png, step
from verify_steps import CALC, EV, REPO, finish, png, step, writable_copy

import pyprocar
from pyprocar.core.ebs import ElectronicBandStructurePath
Expand Down Expand Up @@ -103,7 +102,7 @@ def _(mode=mode, kw=kw):
@step("legacy_bandsdosplot")
def _():
dos_dir = CALC.parent / "dos_calc"
shutil.copytree(REPO / "data/examples/dos/non-spin-polarized", dos_dir, dirs_exist_ok=True)
writable_copy(REPO / "data/examples/dos/non-spin-polarized", dos_dir)
pyprocar.bandsdosplot(
bands_settings=dict(mode="plain", dirname=str(CALC), fermi=5.3017),
dos_settings=dict(mode="plain", dirname=str(dos_dir), fermi=5.3017),
Expand Down
10 changes: 10 additions & 0 deletions .claude/skills/verify-pyprocar/scripts/lib/verify_steps.py
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@

import json
import os
import shutil
import stat
import sys
import traceback
import warnings
Expand Down Expand Up @@ -47,6 +49,14 @@ def deco(fn):
return deco


def writable_copy(src, dst):
"""Copy a read-only fixture tree into the run; return dst with user write on every entry."""
shutil.copytree(src, dst)
for path in [dst, *dst.rglob("*")]:
path.chmod(path.stat().st_mode | stat.S_IWUSR)
return dst


def png(name, fig=None):
"""Save a matplotlib figure into EVIDENCE; return its byte size."""
p = EV / f"{name}.png"
Expand Down
Loading
Loading