Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
198 lines (137 loc) · 7.1 KB

CONTRIBUTING.md

File metadata and controls

198 lines (137 loc) · 7.1 KB
Raw

Contributing to ALPS

Thank you for your interest in ALPS (Algorithms and Libraries for Physics Simulations). ALPS is a community-driven, open-source ecosystem for numerical simulations of correlated quantum systems. Contributions at every level — from a one-line bug report to a new simulation method — are welcome and valued.

Table of contents

Ways to contribute

Contributions fall into four broad levels. You do not need to start at the bottom — jump in wherever your skills fit.

Level What this looks like
1 — Feedback Install ALPS, try a tutorial, open an issue when something is unclear or broken
2 — Documentation & tutorials Improve or extend tutorials on the ALPS website, fix documentation errors, add examples
3 — Maintenance Fix bugs, improve tests, update dependencies, respond to community questions on Discord
4 — New code Contribute a new algorithm, library, or simulation application

All contributions require agreeing to release your work under the MIT License.

Reporting bugs and requesting features

Use the GitHub issue tracker. Choose the template that best fits:

  • Bug report — something is broken or produces wrong results
  • Feature request — you would like new functionality
  • Simulation help — you need help setting up a specific model, lattice, or method
  • Website help — problems with the alps.comp-phys.org website

Before opening a new issue, please search existing issues to avoid duplicates.

Getting started with the code

Prerequisites

  • CMake ≥ 3.18
  • A C++17-capable compiler (GCC, Clang, Intel, or Fujitsu)
  • Boost (bundled copy included; or provide your own with -DALPS_USE_SYSTEM_BOOST=ON)
  • For Fortran bindings: gfortran (or compatible Fortran compiler)
  • For Python bindings: Python ≥ 3.9, plus numpy and scipy

See the installation page for full platform-specific instructions.

Fork and clone

  1. Fork the repository on GitHub.
  2. Clone your fork locally: 
    git clone https://github.com/<your-username>/ALPS.git
cd ALPS
  3. Add the upstream remote so you can stay up to date: 
    git remote add upstream https://github.com/ALPSim/ALPS.git

Build

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

To build with Python bindings:

pip install scikit-build-core numpy scipy
pip install --no-build-isolation -e .

Run the tests

From the build directory:

ctest --output-on-failure

All tests must pass before submitting a pull request.

Making a change

  1. Sync with upstream before starting work:

    git fetch upstream
git checkout master
git merge upstream/master

  2. Create a branch named after what you are doing:

    git checkout -b fix/alea-overflow
git checkout -b feature/dmrg-excited-states
git checkout -b docs/tutorial-heisenberg

  3. Make your changes. Keep commits focused and self-contained. Write commit messages in the imperative mood:

    fix: prevent integer overflow in alea accumulator
feat: add excited-state targeting to DMRG
docs: add Heisenberg chain tutorial

  4. Add or update tests for any changed behaviour. New simulation methods should include at least one regression test comparing output against a known result.

Submitting a pull request

  1. Push your branch to your fork:

    git push origin fix/alea-overflow

  2. Open a pull request against the master branch of ALPSim/ALPS.

  3. Fill in the pull request template, including:

    • What problem this solves and why
    • How to test the change
    • Any known limitations or follow-up work

  4. Ensure CI passes (build + tests on Linux and macOS).

For substantial changes — new simulation applications, new libraries, significant API modifications — we encourage you to open an issue or start a discussion first to get early feedback before investing significant time.

Review process

ALPS uses a consensus-based review model:

  • Pull requests are reviewed by maintainers (at least one per simulation code) and core maintainers.
  • A pull request is accepted if all active reviewers approve, or if no objections are raised within six weeks of submission.
  • Controversial changes can be escalated to the Governing Council.

Core maintainers are responsible for validating that code compiles, tests pass, and results are physically correct. Please be responsive to review comments; PRs with no author activity for eight weeks may be closed.

If you are contributing a new simulation application or library, the Governing Council will discuss a maintenance commitment with you — typically a few hours per month for bug fixes, dependency updates, and community support.

Code style

C++

  • Target C++17.
  • Match the style of the surrounding code. ALPS does not enforce a single formatter, but keeps consistent conventions within each subdirectory.
  • Avoid undefined behaviour and compiler warnings. New code should compile cleanly with -Wall -Wextra on GCC and Clang.
  • Prefer standard library and Boost facilities over hand-rolled implementations.

Python

  • Follow PEP 8.
  • Type annotations are encouraged for new public functions.

CMake

  • CMake ≥ 3.18 features are acceptable.
  • Use target-based linking (target_link_libraries, target_include_directories) rather than directory-level commands.

Recognition

ALPS releases are accompanied by a publication in a peer-reviewed journal. Active contributors are added as co-authors. The Governing Council decides the author list for each release, taking into account contributions to code, documentation, tutorials, testing, and community support.

Contributing documentation, tutorials, or code (Level 2 — improving or extending tutorials and website documentation — or above) with sustained effort is the typical threshold for co-authorship consideration.

Getting help

Channel Use it for
Discord Questions about using ALPS, development discussion, meeting the community
GitHub Issues Bug reports, feature requests, concrete problems with the code
ALPS website Documentation, tutorials, governance, events
Governing Council Onboarding for new simulation codes, co-authorship, major contributions

We look forward to your contribution!