Contributing to AQUA

We welcome contributions to the AQUA project! Whether you’re reporting bugs, suggesting new features, or contributing code, your involvement helps make AQUA better for everyone. This guide outlines the process for contributing to AQUA.

Reporting Bugs

If you encounter any bugs or issues while using AQUA, please report them on the project’s issue tracker on GitHub:

Navigate to the AQUA GitHub repository.
Click on the “Issues” tab.
Click the “New issue” button.
Choose to provide a detailed description of the issue, including steps to reproduce, expected behavior, and any relevant error messages.

Suggesting Features

We’d love to hear from you if you have an idea for a new feature or enhancement in AQUA! To suggest a feature, follow these steps:

Navigate to the AQUA GitHub repository.
Click on the “Issues” tab.
Click the “New issue” button.
Provide a detailed description of the proposed feature, including use cases, benefits, and potential challenges.

Contributing Code

We welcome contributions to the AQUA codebase, both to the framework and to the diagnostics.

To contribute code to AQUA, follow these general steps:

If you don’t already have it, ask the development team to grant you access to the AQUA repository.
Create an issue in the github repository to discuss your proposed changes.
Clone the repository to your local machine.
Create a new branch for your feature or bugfix (e.g., git checkout -b my-feature).
Commit your changes
When ready, push your branch to the github repository.
Create a pull request in the AQUA repository, describing your changes and referencing any related issues.
In the pull request on GitHub, you can run tests by adding the run tests label to the pull request. This will trigger the CI/CD pipeline to run the tests. Please do this only if needed, as the github action hours are limited.
Add a line to the CHANGELOG.md file in the Unreleased section, describing your changes.
Once your pull request is approved, it will be merged into the main branch by the development team.

Warning

Please do not merge pull requests into the main branch yourself and never, ever, commit any changes directly to the main branch!

A more detailed guide on these steps can be found in the CONTRIBUTING.md file in the AQUA repository root folder.

Please note that all contributed codes must be licensed under the same terms as AQUA.

Documentation and Tutorials

We also welcome contributions to the AQUA documentation and tutorials. If you have suggestions for improvements, want to help maintain the documentation, or have ideas for new tutorials, please create an issue on the GitHub repository and/or submit a pull request with your proposed changes.

Testing

Testing is an essential part of developing and maintaining a robust Python package. Our package uses pytest, a widely-used testing framework in the Python ecosystem, for writing and running tests.

Continuous Integration/Continuous Deployment (CI/CD) is currently handled by GitHub Actions, which runs the test suite on various Python versions whenever changes are pushed to the repository. In the future (CI/CD) will also be run on HPC systems.

Running Tests Locally

Before running tests locally, ensure you have installed all the necessary dependencies, including pytest. To run the test suite, navigate to the root directory of the project and run the following:

./download_data_for_tests.sh

Warning

Since September 2025, AQUA data used in the tests is stored and versioned using DVC (Data Version Control). The current script still point to the older archive on SWIFT but it will be deprecated in the near future.

This will download the data needed for the tests and change the catalog name in the config/config-aqua.yaml to ci. Remember to change it to your catalog name after the tests are finished.

Then, run the following command:

pytest -m aqua

This will run the basic test suite and print the results to the terminal. Have a look at the tests directory for more tests.

Note

The -m aqua flag is used to run only the tests that are marked with the aqua marker. More markers are available such as slow and graphics. To run the graphics tests, you will need to download the teleconnections data by running the tests/teleconnections/download_data_for_tests.sh script.

Running Tests in Parallel

To speed up test execution, AQUA supports parallel testing using the pytest-xdist plugin. This allows tests to run on multiple CPU cores simultaneously, significantly reducing the total test runtime.

To run the tests in parallel, use the -n flag followed by the number of cores you want to use.

pytest -n 4

This will run the test suite using 4 parallel workers. You can adjust this number based on your available CPU cores. For more control over parallel execution, you can also use the --max-worker-restart option to automatically restart workers that fail:

pytest -n 4 --max-worker-restart=3

Note

Some tests in AQUA use the xdist_group marker to ensure they run on the same worker process. This is necessary for tests that perform operations that could conflict when run in parallel, such as Dask operations or diagnostic setup. These groups include:

dask_operations: Tests that perform distributed computing operations
diagnostic_setup_class: Tests that set up diagnostic classes with shared state

You don’t need to worry about these groups when running tests - pytest will automatically handle them.

Writing Tests

Tests for our package are written using the pytest framework. Here’s a basic template for a test function:

def test_function_name():
    # setup code
    result = function_to_test(argument1, argument2)
    expected_result = ...  # what you expect the result to be
    assert result == expected_result, "optional error message"

Remember to follow these guidelines when writing tests:

Each test function should focus on one small aspect of a function’s behavior.
Test functions should be named descriptively, so it’s clear what they’re testing.
Use assertions to check that the function’s actual output matches the expected output.