Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
261 lines (174 loc) · 12.9 KB

CONTRIBUTING.md

File metadata and controls

261 lines (174 loc) · 12.9 KB
Raw

Contributing

Thank you for your interest in contributing to the QMCPy library! This library is the product of many hours of labor from many contributors. Join team communications by reaching out to us at qmc-software@googlegroups.com.

Good Practices

To preserve the integrity of this library, we have instituted some good practices for developing features, improving performance, and fixing bugs. Please read this document to acquaint yourself with them.

AI-Assisted Contributions

QMCPy welcomes AI assistance, but contributors and reviewers remain responsible for correctness, reproducibility, licensing, and citations. If AI affects your code, tests, demos, documentation, or pull request text, follow the AI-assisted contributions policy and disclose that use in your pull request.

Issues

All improvements to QMCPy should be connected to an issue using a template from .github/ISSUE_TEMPLATE/.

  • If you are looking for a way to contribute, search the issues and contact the person who started the issue, if you would like to help.

  • If you identify an improvement that is not in an issue, you may submit an issue yourself.

Feature Branches

If you have not yet installed the QMCPy library, see Installation below.

You should do all your work on a feature branch that is created from the develop branch; see Branches below. Once you have something ready, submit a pull request (PR) to the develop branch and request reviews from at least two team members. Tools such as GitHub Copilot may provide supplemental feedback, but they do not replace human review or approval. It may help to have a brief PR review Zoom meeting with the code reviewers to walk them through the changes.

After a feature branch has been approved by two code reviewers, you may merge it into develop. After a successful merge, it is best practice to delete your feature branch on GitHub. This action keeps the repository tidy and prevents the accumulation of stale branches.

We periodically release the contents of develop to master. Contact the team for the next release date. Plan to submit your pull request to develop at least one week before the release date. If your contribution does not make it into the next release, we hope that it will make it into the one after that.

Blogs

Blog prose is maintained in QMCSoftware/QMCSoftware.github.io, not in this repository's MkDocs documentation site. Propose and publish blog posts there; published articles appear on the QMCSoftware Blog.

Runnable examples remain in this repository. For every article backed by a notebook:

  1. Keep the executable notebook under demos/ as the reproducible source and link the article to that exact repository path. Moving the article prose to the website is not a reason to delete its notebook.
  2. Edit and execute the notebook in the QMCPy development environment, from its containing directory when it uses relative imports or helper files.
  3. Add or update the matching test/booktests/tb_*.py test and run that focused test before updating the website article. See test/booktests/README.md for commands.
  4. Update the website article separately, then verify that its source-notebook link still resolves.
  5. If the article had a page on this repository's MkDocs site, do not just delete it: add a redirect_maps entry for its old path under the redirects plugin in mkdocs.yml, then confirm with make check_removed_urls.

Installation

In a git enabled terminal (e.g. bash for Windows) with miniconda installed and C compilers enabled (Windows users may need to install Microsoft C++ Build Tools), run

git clone https://github.com/QMCSoftware/QMCSoftware.git
cd QMCSoftware
git checkout develop
conda create --name qmcpy python=3.13
conda activate qmcpy
pip install -e .[dev]

While dev contains the most complete set of install dependencies, a number of other install dependency groups can be found in our pyproject.toml file. If running in the zsh terminal you may need to use

pip install -e ".[dev]"

The dev extra includes QMCPy's PyPI-hosted MPMC dependencies. MPMC additionally requires a platform-specific pyg_lib wheel that is not available from PyPI. After installing dev, let the QMCPy installer select the wheel page matching the installed PyTorch build:

qmcpy-install-mpmc

For an MPMC installation without the complete development environment, use:

pip install -e ".[mpmc]"
qmcpy-install-mpmc

Minimum Python Version by Role

requires-python covers a bare install; the optional dependency groups in pyproject.toml raise it. Each row shows the strictest floor among that role's pinned dependencies. Rows marked + add a capability to the Application-user install; unmarked rows are self-contained role profiles.

Role Install command Binding constraint Minimum Python
Application user pip install qmcpy QMCPy support policy 3.9
+ torch / GP features pip install "qmcpy[torch,gpytorch]" inherits the QMCPy floor 3.9
+ MPMC pip install "qmcpy[mpmc]", then qmcpy-install-mpmc torch >= 2.10.0 3.10
+ Bayesian optimization pip install "qmcpy[botorch]" botorch >= 0.10.0 3.9
Course instructor (class) pip install -e ".[class]" arviz >= 0.17, matplotlib >= 3.9.0, statsmodels >= 0.14.3 3.9
Test developer pip install -e ".[test]" pytest >= 9.0.3, parsl >= 2026.01.05 3.10
Documentation developer pip install -e ".[docs]" inherits test; pylint >= 4.0.5 3.10
Release / core developer pip install -e ".[dev]" inherits docs / test 3.10

Using qmcpy needs Python 3.9+; contributing code, running tests, or building docs needs 3.10+. We recommend 3.13 for development.

Python 3.9 is a deliberate QMCPy support-policy floor, not a claim about source syntax or qmctoolscl's declared floor. It is the oldest interpreter whose current runtime stack QMCPy commits to support and test; earlier versions are outside that policy even if a particular toolchain can install them.

CI measures the lower tier rather than assuming it: unittests.yml's core-tests job builds the QMCPy wheel on Python 3.9 on Linux, macOS, and Windows, installs it with no extras, checks its dependencies, and imports it from outside the source tree. The 3.9 claim is OS-independent, and qmctoolscl ships only one wheel (cp312, win_amd64), so every leg builds it from its source distribution. It then runs make unittests_core with the slim test_core extra and no notebook stack. Its main tests job runs the full suite on 3.10-3.14, each version on one operating system. Every conda matrix asserts the running interpreter before any test runs. Test modules self-skip via pytest.importorskip when an optional stack (torch, gpytorch, PyG) is absent, so each interpreter runs what applies to it.

📚 Using qmcpy In Courses (class Extra)

qmcpy provides a class optional dependency group that installs a complete teaching environment (JupyterLab, plotting, statistics, and utilities) in addition to qmcpy itself.

For a typical course setup, you can do:

git clone https://github.com/QMCSoftware/QMCSoftware.git
cd QMCSoftware
pip install -e ".[class]"

or for a heavy-duty version

pip install -e ".[class,dev]"

Branches

For Main Repository Collaborators

Branch directly from develop inside the QMCSoftware/ repository. This allows other team members to easily review your work by checking out your branch with

git fetch origin
git checkout <branch-name>

For External Contributors (Forks)

Fork the repository to your personal account and create your branch there. Main repository collaborators can review or test your forked branch without having to clone your repo. For example, say a main repository collaborator wants to check out the develop branch on the git@github.com:MyGitHubUsername/QMCSoftware.git fork. The main repository contributor may call this remote fork the MyGitHubUsername-fork and call the branch name MyGitHubUsername-develop within our repo to avoid conflict with the origin develop branch. The following commands accomplish this.

# Add the fork as a remote source
git remote add MyGitHubUsername-fork git@github.com:MyGitHubUsername/QMCSoftware.git

# Download the fork's branch data
git fetch MyGitHubUsername-fork

# Create your local branch tracking the fork's branch
git checkout -b MyGitHubUsername-develop MyGitHubUsername-fork/develop

When new changes are pushed to the develop branch on the fork git@github.com:MyGitHubUsername/QMCSoftware.git, the main repo collaborator may then run

# 1. Switch to the local branch tracking your fork
git checkout MyGitHubUsername-develop

# 2. Pull the new changes directly from your fork's branch
git pull MyGitHubUsername-fork develop

Tests

Doctests and unittests take a few minutes to run with

pip install -e ".[dev,docs,test]"
make tests_no_docker

Optionally, you may install Docker and then run all tests with

make tests

Please see the targets in the makefile for more granular control over tests.

Documentation

Ensure pyreverse Is On Your PATH

pyreverse must be available as a command-line tool. If it is not, verify your PATH as below.

  • MacOS / Linux
conda activate qmcpy
# check that pyreverse is found
which pyreverse || echo "pyreverse not found"
pyreverse --help

Alternative:

	# add user scripts dir to PATH (zsh example; use ~/.bashrc for bash)
	echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
	# preferred: open a new terminal so the new PATH is picked up
	source ~/.zshrc
  • Windows (cmd or PowerShell)
conda activate qmcpy
# check that pyreverse is found
where pyreverse
pyreverse --help

If where pyreverse cannot find the command, ensure your Python Scripts directory is on your PATH. A common way to locate it is:

python -m site --user-base
# then add "<that-path>\Scripts" to your PATH

You can update PATH via System settings or in your PowerShell profile ($PROFILE).

Build the Documentation

On MacOS / Linux (and on Windows via Git Bash, WSL, or any environment with make):

make doc

Download PDF Documentation

In the built HTML documentation:

  1. Navigate to the “Printable Docs” section.
  2. Use your browser’s print dialog:
    • Windows / Linux: Ctrl+P
    • MacOS: Cmd+P
  3. Choose “Save as PDF” and save to your preferred location.

Demos

Demos are Jupyter notebooks under demos/. To open one:

jupyter-lab                                              # or: make open_notebook NOTEBOOK=demos/quickstart.ipynb
make open_colab_notebook NOTEBOOK=demos/quickstart.ipynb # in Colab, from your current (pushed) branch
make open_colab_notebook_gist NOTEBOOK=demos/quickstart.ipynb  # in Colab, from your uncommitted working copy (needs the gh CLI)

open_colab_notebook uses the branch version only when the notebook is new or differs from develop, otherwise the develop version. See docs/tests.md for details.

Note: make format runs make harden_colab_notebook, so it will insert a Colab badge and bootstrap cell into any unclassified demos/*.ipynb and add it to scripts/colab_notebooks_manifest.json (and fail if a notebook cannot be hardened automatically).

Other Developer Tools

The Developers Tools page on qmcpy.org documents additional tools we have found helpful for mathematical software development and presentation.

VSCode Tips

VSCode (Visual Studio Code) is the IDE of choice for many of our developers. Here we compile some helpful notes regarding additional setup for VSCode.

  • Run CMD+p then > Python: Select Interpreter then select the ('qmcpy') choice from the dropdown to link the qmcpy environment into your workspace. Now when you open a terminal, your command line should read (qmcpy) username@... which indicates the qmcpy environment has been automatically activated. Also, when debugging the qmcpy environment will be automatically used.
  • Go to File and click Save Workspace as... to save a qmcpy workspace for future development.

Some VSCode extensions we found useful include

  • Python
  • Jupyter
  • Markdown Preview Enhanced
  • eps-preview, which requires
    • Postscript Language
    • pdf2svg
  • Git Graph
  • Code Spell Checker