Nexus: Installable as a Python package

[brockdyer03]

Proposed changes

This PR is designed to make Nexus available to install via a package manager such as pip or uv.

The general changes include:

• Adding a pyproject.toml file with minimum supported versions
• Creating a build of Nexus with uv
• Rewriting the Nexus README (now in markdown, name changed to README.md)
• Rewriting the Nexus install instructions to add install methods via a package manager (will not remove previous install instructions)

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

• New feature
• Refactoring (no functional changes, no api changes)
• Documentation or build script changes

Does this introduce a breaking change?

• Yes
• No

What systems has this change been tested on?

Laptop running Fedora 43 with uv 0.9.24 and Python 3.14.2
Docker container of Ubuntu 18.04 with pip 21.3.1 and Python 3.6
Note: The default install of pip on Ubuntu 18.04 is pip 9.1, which does not work to install via GitHub links. The minimum version of pip that will do this is 10.0.0. I have tested and can confirm that running python3 -m pip install -U pip with Python 3.6 will update pip to version 21.3.1, which does work.

Checklist

• • I have read the pull request guidance and develop docs
• • This PR is up to date with the current state of 'develop'
• • Documentation has been added (if appropriate)

[prckent]

Thanks Brock. Q. Are you done with updates including updating the readme and install instructions? If so, please add the [x] to the 3rd and 4th bullets in the PR description and I will take a look.

[brockdyer03]

I'm not quite done. After a chat with @jtkrogel yesterday I realized that perhaps there should be some additional clarification for users, and most likely a note about selecting a branch to install.

The current default is @develop, however it may be prudent to switch that to @main, although that becomes complicated because @main won't be available until the next release.

Additionally, I still need to update the Nexus docs, since that will likely be where people go for install instructions, not the readme.

[prckent]

I was wondering when the issue of Nexus versioning would arise in this effort, since package managers will rightly need to version the package. For git+python package manger installation, clearly most users should install the version corresponding to the version of QMCPACK they are using, or simply the last tagged version. Folks should only use develop if they know they need it (new feature, bug fix, adventurous spirit). Based on recent errors we clearly can not yet guarantee that develop will work. Imminent changes to the testing will get us to the point needed but we are not there yet.

The instructions should have variants of pip install git+https://github.com/QMCPACK/qmcpack.git@v4.1.0 for a specific version of @ main branch if they don't know otherwise (there is no 'latest' tag). List develop last.

[prckent]

Note that a key lesson from the QMCPACK documentation is to not put too much in the README.md and to direct users to specific parts of readthedocs documentation. This avoids the documentation becoming scattered, potentially duplicative, and/or potentially out of sync. A single source of truth is ideal. (The QMCPACK docs are still in the process of migrating all to readthedocs - the readme is too long and there are some remnant wiki entries to copy over.)

[brockdyer03]

Minor q: What is making the qmcpack_manual.* that you added to the .gitignore?

I'm not sure why the diff shows that I added that, those files have been in the .gitignore for 8 years. The files I added are .python-version, .coverage, .venv, and uv.lock.

Speaking of the uv.lock file though, I think that probably should get removed from the .gitignore and it should be added into the QMCPACK or Nexus directory. That file is essentially a list of the Python versions and every package version (with download links) that are compatible with Nexus. Currently the uv.lock file that is in my local QMCPACK clone lists every package (with a version number for every version of Python), their dependencies and their dependencies' version numbers, URLs for package wheels on every platform (e.g. Linux, Windows x86, Windows ARM, MacOS ARM, MacOS x86, etc.), SHA256 hashes for the package data for each wheel URL, wheel size in bytes, and the upload timestamp of the wheel. It's a grand total of ~750 kB, about 3000 lines long.

Here's what it looks like for version 4.4.6 of PyCifRW (which happens to only be available on Linux):

[[package]]
name = "pycifrw"
version = "4.4.6"
source = { registry = "https://pypi.org/simple" }
dependencies = [
    { name = "numpy", version = "1.19.5", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.7'" },
    { name = "numpy", version = "1.21.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.7.*'" },
    { name = "numpy", version = "1.24.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.8.*'" },
    { name = "numpy", version = "2.0.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.9.*'" },
    { name = "numpy", version = "2.2.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version == '3.10.*'" },
    { name = "numpy", version = "2.4.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
    { name = "ply" },
]
sdist = { url = "https://files.pythonhosted.org/packages/57/08/e0811d3a6bd0895fef98a0341ba2bd4556c8bbc7287ea01f1a8db96214f6/PyCifRW-4.4.6.tar.gz", hash = "sha256:02bf5975e70ab71540bff62fbef3e8354ac707a0f0ab914a152047962891ef15", size = 1073183, upload-time = "2023-11-01T06:13:01.259Z" }
wheels = [
    { url = "https://files.pythonhosted.org/packages/6e/b6/b429e4f48960b19480111ed3812e0cd53be810f190a1f8c652e99149d47a/PyCifRW-4.4.6-cp311-cp311-manylinux_2_5_x86_64.whl", hash = "sha256:a89844ed5811700f995d1913a248d29d5745078ffd0f957b7e0574d74a48d0df", size = 160036, upload-time = "2023-11-01T06:13:38.088Z" },
]

[brockdyer03]

I updated the text in installation.rst

One thing I noticed in your changes that I am not a fan of is hard-wrapping lines (i.e. manual line breaks at some column number). The main reason is a practical one; when you add something into the document and need to shift your lines to enforce whatever the preferred line length is, you end up needing to bump a lot of lines in that paragraph, which can yield a diff that shows a lot more line changes than were actually changed.

On a less practical, more subjective note, soft-wrapping makes the docs far easier to work with in the wide range of text editor widths. For example, in VS Code if I am editing the docs at my default zoom level I see this:

---

---

As you can see, the hard-wrapping is causing a lot of unexpected line breaks. In contrast, soft-wrapping lines (i.e. letting your text editor handle it) will adapt to the editor width no matter its width:

---

---

[prckent]

Word wrap: unfortunately this is currently a no win situation, with both routes having advantages and disadvantages. E.g. until the GitHub website gains better wrapping support itself, there will always be a vote for shorter lines since diffs on long lines are impractical to read and review.

[prckent]

Q. Is there anything in the installation part of the README.md that is not in the installation docs? To avoid duplication, I would like to just have a pointer to these docs there.

[brockdyer03]

I recommend git diff --color-words [commit] for that. It makes reading commits for docs much nicer.

I also think that while diff readability is important, code readability is more important. It's a matter of opinion, but naturally I'm biased and think my opinion is the correct one :)

[brockdyer03]

Q. Is there anything in the installation part of the README.md that is not in the installation docs? To avoid duplication, I would like to just have a pointer to these docs there.

I don't think there is anything in the README.md that isn't in the docs, but I think it would not be a good idea to only have a pointer to the docs in there. If someone is downloading QMCPACK onto an HPC system they might find it easier to read the README than to follow a link to a website. It enables offline accessibility, which is important for some users. I do think it should be kept pretty minimal, and most likely should only include a few words. Check out the README that I put in my own package; I think it would be a good model for the Nexus README.

[prckent]

@jtkrogel or @ye-luo please can you proof read and check that this version is OK in your view. Then I think we can finally merge this.

[ye-luo]

Slightly hard to follow. better to have recommended one first

a) user level. recommended.
...
b) system level. not recommended.
...
Then common bits.

[brockdyer03]

I'll leave that rephrasing to @prckent

[ye-luo]

To avoid conflict with your downstream changes, there is no need to address it in this PR. I just want to raise my concern.

[prckent]

I have revised the order, putting the recommend routes first and making them clearer.

[prckent]

Updated. I believe all the requests for updates have been addressed.

[ye-luo]

LGTM

[jtkrogel]

I deleted references to the install script, which was inadvertently removed and not allowed back in.

[jtkrogel]

Approved

[prckent]

Thanks all. Merging.

[prckent]

Test this please