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]

I believe this is ready for review.

Current PR

The most recent changes are:

• Update README.md for Nexus to be up-to-date
• Nearly complete rewrite of the docs page on installing Nexus, including warnings and notes and tips for users as well as instructions for installing Nexus through a package manager.

Some notable changes from the initial PR idea:

• The Nexus version has gone from 2.1.0 to 2.2.0
• The files requirements.txt and requirements_minimal.txt have been updated to reflect testing done on minimum versions.

Future work

After some digging, I think it is possible to include the various scripts in nexus/bin in a package so that users can access them in addition to the lib. This is beneficial because it removes one of the big downsides of using a package manager, that being that you can't access any of those scripts. This will require, however, another small restructure to Nexus's file structure that moves bin into nexus/nexus which will have its own associated challenges.

Another thing is that currently Nexus is not actually built and distributed in QMCPACK, so technically none of the instructions that I've added are strictly correct. I'll be chatting with @prckent later this week to work out the details, and it is possible that this PR will need to wait to be merged until after the next release of QMCPACK. For now though, I could in theory build Nexus locally and just put a distribution wheel into this PR, but that won't be automatically updated with new pull requests.

[prckent]

Quick note to record: *** Do not merge prior to 4.2.0 release ***

[prckent]

Good to address the version numbering.

@jtkrogel Can we please adopt the same versioning scheme as for QMCPACK, using patch number .9 for development? E.g. 2.1.9 is a development version and 2.2.[0-8] are released versions? This allows us to distinguish between runs with versioned releases and development versions that could have any number of changes. We (I) change the version numbers during the release process.

[jtkrogel]

Adopting QMCPACK versioning practices is fine

[prckent]

Reminder to myself that significant updates to the .rst is will be needed, plus the existing installer script needs looking at.

[jtkrogel]

Note: no blockers w.r.t. Python version here (supports Python 3.6).