Say what a rejected pseudo_library label means

[elinsc-bot]

Problem

Setting pseudo_library to a label koopmans does not recognize — say my-gaas-fr, a full-relativistic family a user built by hand — failed with

Unrecognized pseudo family format: 'my-gaas-fr'. Expected 'PseudoDojo/version/functional/relativistic/protocol/format', 'SSSP/version/functional/protocol', or 'SG15/version/functional/relativistic'.

That sends the reader to fix their label's format, and implies only three families are possible. Neither is true. Any family already installed is used as it stands, under whatever label it carries; the label is only parsed when nothing is installed under it. So the real situation is that no installed family had that label and koopmans could not download one — a mistyped label, or a family not installed yet.

Hand-built families are the supported route for pseudopotentials koopmans cannot fetch, such as the full-relativistic LDA sets that spin-orbit work needs. This message is what those users hit first.

Changes

• The error now states what was actually checked — no installed family carries the label, and koopmans cannot download one — and gives both ways forward: install the pseudopotentials yourself, or name one of the three formats koopmans can fetch. The formats stay, framed as what koopmans downloads rather than as the set of valid labels.

• The self-install route is a plain family, and the cutoffs come from the input file. Since Take the cutoffs from the input when the pseudo family has none #127 and Install SG15 as a family that recommends no cutoffs #136, aiida-pseudo install family <directory> <label> with no flag is enough, and calculator_parameters.ecutwfc alone is a complete statement — ecutrho follows at four times it. This is scoped to families that publish no recommended cutoffs; a PseudoDojo or SSSP family still supplies its own, and an input naming none still builds on them.

• pseudo_library's help text pointed at koopmans pseudos list, which is not a command; it now describes both routes and renders into the input-file reference.

• The installation page gains a Pseudopotentials section. The docs previously never mentioned pseudopotentials — neither that koopmans downloads them for you, nor that a family you install yourself works.

• Two fixture docstrings left stale by Install SG15 as a family that recommends no cutoffs #136 are corrected: one described a cutoffs family as "the shape _install_sg15_family produces", which it no longer is, and one claimed the protocol machinery accepts only SSSP, PseudoDojo or a cutoffs family, which the patched aiida-quantumespresso no longer restricts.

The new message:

No installed pseudopotential family has the label 'my-gaas-fr', and koopmans cannot download one under that label.
Install the pseudopotentials yourself, from a directory holding one file per element:
    aiida-pseudo install family <directory> my-gaas-fr
A family installed this way publishes no recommended cutoffs, so set `calculator_parameters.ecutwfc` in your input file; `ecutrho` follows at four times it.
Alternatively, name a family koopmans can download for you, as 'PseudoDojo/version/functional/relativistic/protocol/format', 'SSSP/version/functional/protocol', or 'SG15/version/functional/relativistic'.

It now matches require_cutoffs_for_family's wording, so a user who meets both messages reads the same instruction twice.

Testing

• Reinstating the old advice fails the suite: one test pins the install command with a trailing newline, so a trailing -F ... breaks it, and another asserts -F, pseudo.family.cutoffs and cutoffs set are all absent. Run as a negative control, both failed on exactly those assertions.

• The suite is measured against the patched aiida-quantumespresso the repo now clones. The same pseudo modules give 3 failures against upstream main and 15 passes against patched, which is what establishes the tests are exercising the intended dependency rather than the local checkout.

• Docs build under sphinx -W, and the rendered output was checked rather than assumed: the Pseudopotentials section shows the single plain-family command, and the extended pseudo_library description reaches the input-file reference.

[read-the-docs-community]

Documentation build overview

📚 koopmans-dev | 🛠️ Build #33963832 | 📁 Comparing c2d1ba9 against latest (81be694)

  🔍 Preview build  

7 files changed · ± 7 modified

± Modified

• cli.html
• genindex.html
• input_schema.html
• installation.html
• _modules/koopmans/input_file.html
• _modules/koopmans/input_file/pw.html
• _modules/koopmans/input_file/workflow.html

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.87%. Comparing base (b635ce2) to head (c2d1ba9).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #109      +/-   ##
==========================================
+ Coverage   81.81%   81.87%   +0.05%     
==========================================
  Files          44       44              
  Lines        3464     3464              
  Branches      543      543              
==========================================
+ Hits         2834     2836       +2     
+ Misses        494      493       -1     
+ Partials      136      135       -1     

☔ 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.

[elinsc-bot]

Holding: the pseudo_library field description this PR rewrites is about to be rewritten again by #125, which adds the koopmans pseudos command the description should point at. Merging now means changing the same lines twice.

Marked draft to record the hold; nothing here is wrong, it just wants to land alongside #125 and #126.