carbon

Estimates carbon emissions of compute jobs run on high-performance computing clusters.

The tool estimates the energy consumption of a job using information gathered from the workload scheduler. Since it has been developed for use at Imperial College London, it is currently set up to communicate with the scheduler in use on Imperial's clusters, PBS Professional v2024.1. However, the structure of the code has been designed with the view of potential extension for use on other clusters and with other workload schedulers.

By default, the tool requires an internet connection in order to request data from the NESO's carbon intensity API. If required, this request can be skipped in favour of a configurable carbon intensity value using the --average-intensity flag.

For developers

This is a Python application that uses uv for packaging and dependency management. It also provides pre-commit hooks for various linters and formatters and automated tests using pytest and GitHub Actions. Pre-commit hooks are automatically kept updated with a dedicated GitHub Action.

To get started:

1. Download and install uv following the instructions for your OS.

2. Clone this repository and make it your working directory

3. Set up the virtual environment:

   uv sync
   

4. Install the git hooks:

   uv run pre-commit install
   

5. Activate the virtual environment (alternatively, you can prefix any Python-related command with uv run):

   source .venv/bin/activate
   

6. Specify the location of your cluster configuration file:

   export CARBON_CONFIG=/path/to/config.yaml
   

7. Run the main app:

   carbon <job ID>