Skip to content

Contributing to quatrex#

This guide provides some information for contributing to quatrex. It covers setting up a development environment, coding standards, testing, and the contribution workflow.

Setting up a development environment#

It is recommended to use pixi to set up a development environment for quatrex, as described in the installation instructions.

pixi install --environment=dev

The dev environment includes tools for development, testing, and linting:

Additionally, pre-commit is used to manage pre-commit hooks for linting and formatting code. Install the pre-commit hooks with:

pixi run --environment=dev pre-commit install

pixi also allows the definition of a few custom commands to simplify common development tasks. You can list the available tasks with:

pixi task list

Besides other common Python development tools available in IDEs, astral's ty language server is worth giving a try, as it may offer better performance on somewhat larger Python codebases.

General guidelines#

  • Follow PEP 8 style guidelines for all Python code. We are using black for automatic code formatting and ruff for linting.
  • Write clear and concise docstrings for all functions and classes in accordance with the NumPy documentation style. You can use standard markdown syntax for formatting and $...$/$$...$$ delimiters for in-line/block-level mathematical expressions. These are rendered using mathjax.
  • It is always a good idea to include new unit tests for additional features and bug fixes.
  • Ensure that all tests pass locally before submitting a pull request and that the code is properly linted and formatted. We use pre-commit to manage pre-commit hooks.

Development flow#

  • Open an issue on GitHub describing the feature or bug you want to address.
  • Create a new branch for your feature or bugfix.
  • Make your changes and commit them with clear commit messages.
  • New features should be accompanied by new unit tests and documentation updates and (if applicable) a few words on the methodology behind the feature.
  • Push your branch to GitHub and open a pull request, explaining your changes.
  • To have at least a second pair of eyes on your changes, request a review.

Example configurations#

As mentioned in the installation instructions, we provide several example configurations, input files, and reference outputs that we use for testing and development. This data is tracked using Git LFS. We do not use GitHub's built-in large file storage, as it has some bandwidth limitations. Instead, we use ETH Zürich's GitLab instance to host the LFS files in this project.

To update the LFS files, you will need to have write access to the GitLab project. Contact current project maintainers for access. The files can be read without authentication.

Automated linting and testing#

We use GitHub actions for most of the automated testing and linting. We run linting and formatting with ruff, black, and isort and single-rank and distributed tests with pytest and pytest-mpi. Since the default GitHub runners do not have GPUs, we only run the CPU tests on GitHub. These runners have only 4 CPU cores, so we run the distributed tests with just 3 ranks.

We also run the full test suite on Alps' GPUs. See the CSCS CI/CD documentation for reference. If you have the necessary permissions, you can trigger the Alps pipeline manually on pull requests by posting a comment starting with cscs-ci run.

Documentation#

The documentation is built using the Zensical framework. The mkdocstrings-python plugin is used to automatically generate API reference documentation from the docstrings in the code. The griffe plugin is used to automatically generate the simulation parameter reference pages from the pydantic model definitions.

All documentation is built and deployed automatically on GitHub pages whenever changes are pushed to the default branch.

To build and view the documentation locally, you can use the pixi task:

pixi run docs serve

For more information on writing documentation, see, e.g., the section on authoring in the Zensical documentation.