Nexus: `PseudoSet` user guide by brockdyer03 · Pull Request #6165 · QMCPACK/qmcpack

brockdyer03 · 2026-08-26T03:26:57Z

Proposed changes

This PR adds several examples to the Nexus user guide for using PseudoSet, and additionally adds a migration guide to switch from ppset to generate_pseudoset.

A quick set of changes were also made to pseudoset.py which do not affect existing functionality, but do make the output of various functions more consistent.

What type(s) of changes does this code introduce?

Documentation or build script changes

Does this introduce a breaking change?

No

What systems has this change been tested on?

Desktop, Fedora Linux 43 (KDE Plasma Desktop Edition)
AMD Ryzen 9 7900X (12 cores, 24 logical processors)

Python        3.14.5
uv            0.12.3
cif2cell      2.1.0
coverage      7.15.4
h5py          3.16.0
matplotlib    3.11.1
numpy         2.5.2
pycifrw       4.4.6
pydot         4.0.1
pytest        9.1.1
pytest-cov    7.1.0
pytest-order  1.5.0
scipy         1.18.0
seekpath      2.2.1
spglib        2.7.0
sphinx        9.1.0

Checklist

- I have read the pull request guidance and develop docs
- This PR is up to date with the current state of 'develop'
- Code added or changed in the PR has been clang-formatted
- This PR adds tests to cover any new code, or to catch a bug that is being fixed
- Documentation has been added (if appropriate)

jtkrogel

First: this is far too long for the feature it covers. +40 pages to the user manual is way too much (at least 800+ lines in the rst file). This should cover the most common (1-3?) use cases. Maybe 5 pages max.

Second: the UI is via generate_pseudoset alone as we have discussed at length previously. If you want to start alternative class-based docs at the end of the manual, that is your choice.

brockdyer03 · 2026-08-26T15:16:39Z

First: this is far too long for the feature it covers. +40 pages to the user manual is way too much (at least 800+ lines in the rst file). This should cover the most common (1-3?) use cases. Maybe 5 pages max.

I am not sure where you get this 40 page metric, the actual rendered docs are quite short and to the point. Yes, the rST files are long, but that is because I included examples for each case. Roughly half the lines in the file are just the printout from the Python code snippets, which I think is important for users to see. It also means that the code would be testable through doctest in the future.

Second: the UI is via generate_pseudoset alone as we have discussed at length previously. If you want to start alternative class-based docs at the end of the manual, that is your choice.

I think all routes should be explicitly accessible for users. I will make the function interface the default in the docs, but I think there is no reason to hide a class-based interface at the end of the documentation.

jtkrogel · 2026-08-26T15:19:31Z

Yes, they will be accessible. The primary UI is input file like -- user's should not have to be exposed to detailed classes, calling many functions, etc.

If they want to dig deeper, that is fine -- but the main UI to Nexus, as established over its entire existence, is not going to change.

…_pseudoset`

jtkrogel

See comments

jtkrogel · 2026-08-31T13:00:20Z

+        :func:`ppset` has been replaced by :func:`generate_pseudoset` because
+        the labeling system that :func:`ppset` requires checks for the existence
+        of the label at runtime, whereas :func:`generate_pseudoset` returns an
+        object with a name, and if that name is misspelled then Python will not


"object with a name as other generate functions do." Remove the rest.

jtkrogel · 2026-08-31T13:01:29Z

                raise ValueError(msg) from None

-        return pseudos
+        sorted_pseudos = {k: v for k, v in sorted(pseudos.items(), key=lambda x: x[0])}


Remind me what the keys are

jtkrogel · 2026-08-31T13:04:31Z

+=================================
+
+Nexus currently has several utilities for discovering, parsing, and copying pseudopotential files.
+The latest and most complete method is through the :py:class:`~.PseudoSet` class and its associated builder :py:func:`~.generate_pseudoset`, and is recommended for most users.


Don't discuss the class in the main user-facing documentation. What they need to know is how to use generate_pseudoset, not how it is implemented behind the scenes. Remember, many (most?) of our users do not know object-oriented programming, nor should they in order to understand the UI and use Nexus effectively.

jtkrogel · 2026-08-31T13:05:27Z

+Nexus currently has several utilities for discovering, parsing, and copying pseudopotential files.
+The latest and most complete method is through the :py:class:`~.PseudoSet` class and its associated builder :py:func:`~.generate_pseudoset`, and is recommended for most users.
+
+All objects returned by the methods described here can be passed into a generate function (e.g. :py:func:`~.generate_pwscf`), but require that you also pass the system to be simulated as a :py:class:`~.PhysicalSystem` object using the ``system`` keyword argument, which you can create with :py:func:`~.generate_physical_system`.


Remove mention of "objects" and the PhysicalSystem class.

jtkrogel · 2026-08-31T13:10:50Z

+
+.. _pseudoset-usage:
+
+Using :py:func:`~.generate_pseudoset` and :py:class:`~.PseudoSet`


Don't reference the class

jtkrogel · 2026-08-31T13:22:51Z

+
+The following sections provide examples for how to use :py:class:`~.PseudoSet` for a variety of situations, primarily focused on the layout of a user's pseudopotential files.
+You can switch between a class-based interface and an interface based on :py:func:`~.generate_pseudoset` by clicking on each code block below.
+Each example has the output of the ``tree`` command in the pseudopotential directory to start.


Example 1 should show the settings(pseudo_dir=...) + generate_pwscf(pseudos=[...],...) route. They need to know that the way they have traditionally specified pseudopotential locations still works.

This and other examples should be illustrated within a user script environment, consistent with the rest of the documentation in the manual. This is important because this is how they will use it -- and this is what they need to know.

jtkrogel · 2026-08-31T13:29:36Z

+#. Unlike the single-code example which used :py:meth:`~.PseudoSet.from_dir`, the multi-code example uses :py:meth:`~.PseudoSet.from_mixed_dir`, which can automatically filter pseudos for specific codes.
+    - The function :py:meth:`~.PseudoSet.from_dir` works well with directories containing pseudopotentials only for one code, e.g. if you have only a single set of ``.upf`` pseudopotentials. It can auto-detect the codes that *could* use those pseudopotentials (it can be more than one since, for example, both QE and RMG can also read UPF-formatted pseudopotentials)
+
+Example 2 - Unstructured Directory


"Example 4: Searching via inclusion pattern matching"

jtkrogel · 2026-08-31T13:30:46Z

+            )
+
+
+Multi-code workflows become more complex since we need to specify which files to include.


This one is redundant with the "select by extension" example above. Remove one of them.

jtkrogel · 2026-08-31T13:32:24Z

+
+As with the single-code example, you can change out ``include`` to match different pseudopotential sets.
+
+Example 3 - VASP Pseudopotentials


"Example X: searching via exclusion pattern matching"

jtkrogel · 2026-08-31T13:33:34Z

+
+.. _legacy-ppset:
+
+Migrating from :py:func:`~.ppset`


OK, this is the stuff that needs to go at the top. generate_pseudoset is put forward as the replacement. The "replacement" form (this) needs to be given to them first.

brockdyer03 added 2 commits August 25, 2026 21:38

Nexus: Add user guide for using PseudoSet and generate_pseudoset

e0d6f4d

Nexus: Add migration guide from ppset to generate_pseudoset

e9d98e1

brockdyer03 self-assigned this Aug 26, 2026

github-actions Bot added nexus documentation python Pull requests that update python code labels Aug 26, 2026

jtkrogel requested changes Aug 26, 2026

View reviewed changes

Nexus: Make function-based interface the default.

e311261

brockdyer03 requested a review from jtkrogel August 27, 2026 13:53

Nexus: Add link to user guide for migrating from ppset to `generate…

f5fb5c9

…_pseudoset`

jtkrogel requested changes Aug 31, 2026

View reviewed changes


		.. _pseudoset-usage:

		Using :py:func:`~.generate_pseudoset` and :py:class:`~.PseudoSet`

		)


		Multi-code workflows become more complex since we need to specify which files to include.


		As with the single-code example, you can change out ``include`` to match different pseudopotential sets.

		Example 3 - VASP Pseudopotentials

Uh oh!

Conversation

brockdyer03 commented Aug 26, 2026

Proposed changes

What type(s) of changes does this code introduce?

Does this introduce a breaking change?

What systems has this change been tested on?

Checklist

Uh oh!

jtkrogel left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

brockdyer03 commented Aug 26, 2026

Uh oh!

jtkrogel commented Aug 26, 2026

Uh oh!

jtkrogel left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jtkrogel left a comment •

edited

Loading