Add koopmans pseudos to list the valid pseudo libraries

[elinsc-bot]

Problem

koopmans pseudos listed the pseudopotential libraries koopmans can install, but it built the SG15 labels by crossing {1.0, 1.2} with {SR, FR} rather than from what the archive publishes. Two consequences:

• SG15/1.2/PBE/FR was offered and cannot be installed. No member of the archive matches it. Asking for it downloads 6 MB and then fails with "No UPF files matched … The archive layout may have changed".
• SG15/1.1 was never offered, though the archive carries it. It is the only source of fully relativistic Si, P, S, Cl, As, Se, Sb, Te, I, Xe, Ar and Sn — so spin-orbit work on any of those had no SG15 route at all.

The accompanying note also told users that "SG15/1.0 carries only H and O". It carries all 69 elements, the same set as 1.2. That claim came from a hand-built family on a developer machine, not from the archive.

Changes

• koopmans pseudos lists the libraries koopmans can install, with a note per library.

• The SG15 versions and variants come from one table of what the archive publishes — 1.0: SR, FR, 1.1: SR, FR, 1.2: SR — which both the listing and the installer read. SG15/1.2/PBE/FR is no longer offered, and asking for it is refused before the download rather than after it, naming what 1.2 does carry.

• SG15/1.1 becomes installable, composed over 1.0. SG15 published 1.1 as a delta revising 17 elements, so the label installs the 1.0 files with the 1.1 ones over them — a complete set, not the delta. Composed, SG15/1.1/PBE/FR is the maximal fully relativistic SG15 set at 64 elements and puts FR Si and FR O under one label; a run mixing them previously needed two families. Ba, Be, Bi, Li and Ne stay uncovered at every version.

• The notes say what the archive contains: 1.2 and 1.0 both cover all 69 elements at different revisions, 1.1 is composed and says so, and there is no fully relativistic set at 1.2.

• Installed pseudopotentials keep their archive filenames (Si_ONCV_PBE-1.1.upf, not Si.upf), which is what makes a composed family self-describing on disk.

• Cutoffs: the note asks for ecutwfc alone, since ecutrho follows at four times it.

• The SSSP refusal said SSSP "mixes ultrasoft and PAW". It also carries norm-conserving entries for some elements, so the refusal now names all three.

• Say what a rejected pseudo_library label means #109 (merged since) listed SSSP among the families koopmans downloads, in the error message, the help text and the docs — two branches above the code that refuses it. All three places now offer only the norm-conserving PseudoDojo and SG15 families, with SSSP kept as the example of a refused library.

• The unrecognized-label message closes by pointing at koopmans pseudos instead of quoting the label grammars. The listing cannot go stale (PseudoDojo labels come from get_valid_labels()), and the grammar ended in /format while only upf is accepted — following it verbatim produced a label the installer refuses.

• Self-installed families are now verified norm-conserving from their UPF headers (upf-tools), at use time, on the elements the structure uses. The download routes need no such sweep: PseudoDojo publishes its PAW sets as jthxml only, so the UPF-only filter already guarantees every offered label is ONCV; SSSP stays refused by name, before any download. The check refuses on positive evidence only.

• The header read is ~40 lines of our own, not a dependency: aiida-pseudo parses only the element and z_valence, and upf-tools' XML reader rejects every PSlibrary pseudopotential whose PP_INFO embeds a Fortran namelist (the bare & breaks XML) — including three of aiida-core's own ultrasoft fixtures, which an accept-on-unreadable rule would then wave through. Validated against 75 real pseudopotentials: 6 non-norm-conserving refused, 69 accepted, none wrong.

• pseudos.py became a pseudos/ package: one module per library exposing available_labels/install, a registry keyed on the label's first segment, and the header check as shared plumbing. Pure move in its own commit.

• The hard-coded set_default_stringency("normal") stays, now with a comment: aiida-pseudo promotes only a family's first stringency to default, so dropping the call would leave every koopmans-installed PseudoDojo family on low, and normal matches aiida-pseudo's own CLI default.

Testing

• The element counts come from enumerating the checksummed 2020-02-06 tarball with the module's own filename pattern, after verifying its SHA-256 against the pinned value. 219 files, all matching; nothing was inferred from an installed family.

• Reinstating the old notes and the {1.0, 1.2} × {SR, FR} cross product fails five of the new tests, one per claim — the H-and-O note, the fully relativistic coverage, the ecutrho ask, the set of offered labels, and the pre-download guard. That control is what makes the new assertions load-bearing rather than restatements.

• The discriminating pair for composition: composed 1.1/FR contains Si and O while pure 1.0/FR lacks Si, and the composed SR family carries 1.1's Si content beside 1.0's O — so dropping composition, leaking it into 1.0, or flipping the overlay precedence each fail a different assertion.

• Run against the patched aiida-quantumespresso the repo clones, confirmed at runtime rather than assumed.

[read-the-docs-community]

Documentation build overview

📚 koopmans-dev | 🛠️ Build #33993722 | 📁 Comparing 4e8393c against latest (81be694)

  🔍 Preview build  

9 files changed · ± 9 modified

± Modified

• cli.html
• genindex.html
• input_schema.html
• installation.html
• _modules/koopmans/input_file.html
• _modules/koopmans/input_file/ml.html
• _modules/koopmans/input_file/pw.html
• _modules/koopmans/input_file/workflow.html
• tutorials/orbital_energies/ozone/automatically.html

[codecov]

Codecov Report

❌ Patch coverage is 97.07113% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.85%. Comparing base (815c65d) to head (4e8393c).

Files with missing lines	Patch %	Lines
...c/koopmans/aiida/setup/pseudos/_norm_conserving.py	92.30%	4 Missing and 1 partial ⚠️
src/koopmans/aiida/setup/pseudos/_sg15.py	97.01%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #128      +/-   ##
==========================================
+ Coverage   81.86%   83.85%   +1.99%     
==========================================
  Files          44       47       +3     
  Lines        3462     3581     +119     
  Branches      542      561      +19     
==========================================
+ Hits         2834     3003     +169     
+ Misses        493      450      -43     
+ Partials      135      128       -7     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[elinscott]

Can we do a more systematic check here? We could check the pseudo headers to see if they are ultrasoft/paw using upf-tools?

[elinscott]

Or some in-built AiiDA functionality?

[elinsc-bot]

Good call — dropped the dependency. Nothing inbuilt reads the field, though: aiida-pseudo has no notion of NC/US/PAW at all (its UpfData parses the element and z_valence), and aiida-core's parse_upf gets the version and element. So it is ~40 lines here instead, reading the v2 attributes and falling back to the v1 fixed-format block.

That turned out better than upf-tools rather than merely lighter. Its v2 reader is an XML parser, and every PSlibrary pseudopotential that embeds its generation input has a Fortran namelist in PP_INFO whose bare & makes the file invalid XML — it raises ParseError on three of aiida-core's own ultrasoft test fixtures, which under a "cannot tell, so accept" rule would have let real ultrasoft pseudopotentials straight through. Scanning the header alone does not care about the rest of the file.

Validated against 75 real pseudopotentials — the SG15 tarball, aiida-core's fixtures, and a few from the QE library: all 6 non-norm-conserving refused, all 69 norm-conserving accepted. The real files also settled details a synthetic fixture would not have: PSlibrary writes is_ultrasoft="true" where SG15 writes "F", a PAW file raises the ultrasoft flag too, and its pseudo_type is USPP rather than US. Those headers are now test fixtures. 4e8393c.

[elinscott]

Do we want this hard-coded?

[elinsc-bot]

Checked, and it turns out to be load-bearing rather than decorative. install_pseudo_dojo sets low, normal and high in that order, and set_cutoffs makes a stringency the default only while it is the family's only one — so dropping this call leaves every family on low, quietly.

"normal" is not our invention either: aiida-pseudo's own install pseudo-dojo command defaults to it and calls set_default_stringency right after the same function we call. So this reproduces upstream's behaviour rather than overriding it.

That leaves no schema question — a run wanting high states calculator_parameters.ecutwfc, which takes precedence over any recommendation. Comment added saying all this; the call stays. d25a3b2.

[elinscott]

Is it worthwhile splitting pseudos.py to a module with pseudos.pseudodojo and pseudos.sg15?

[elinsc-bot]

Done. pseudos/ is now a package: _pseudodojo.py and _sg15.py each expose available_labels, install and (for SG15) NOTES, and __init__.py keeps every public name and dispatches through a registry keyed on the label's first segment — adding a library touches no shared code. The move is its own commit with no content change; the norm-conserving check went into a third module alongside them. 2d031e1.