👉 There are many different flavours of HPC setups, so no doubt you'll find some bugs...Please let us know what you find so that we can make it work for more people!
GA4HPC is a user-facing, terminal-based tool that generates an energy usage and carbon footprint report for your computational workloads. It implements the Green Algorithms Methodology directly on High Performance Computing (HPC) clusters. The tool currently supports SLURM clusters only, with an aim to expand it for other workload managers in the future.
It works by pulling usage statistics directly from the logs recorded by the workload manager and estimating the user's carbon footprint based on this usage. It reports a range of statistics such as energy usage, carbon footprints, compute use, memory efficiency, and impact of failed jobs.
By default, the output gets displayed in the terminal (example below). --output='html' can be used to get the output as an html report instead.
This tool is intended for individual HPC users who want to generate carbon footprint and energy usage reports for their own computational workloads.
Note
Looking for automated, ongoing reporting across teams or departments? Check out the Green Algorithms Dashboard. It automatically track aggregated usage and carbon emissions via an interactive Grafana interface. Unlike GA4HPC, which any user can run directly, the Dashboard requires setup and maintenance by a system administrator.
- Quick start
- Limitations to keep in mind
- Full list of options
- Installation guide
- Contributing
- FAQ
- Getting help
- About us
- Licence
Note
We recommend installing GA4HPC in a shared directory to avoid every user having to install it for themselves. Don't worry, even when installed in a shared directory, each user will only ever see their own usage.
--outputDir below to change this).
This is assuming it's been installed already of course, either by you or someone else. So check with people around you and your sys admins first: if it's already installed, you can run it straight away to get your own carbon footprint, no need to reinstall it. If it isn't installed yet, see the Installation guide below.
Assuming it's installed under shared_directory, run the following on the SLURM cluster to get your carbon footprint between two dates:
shared_directory/myCarbonFootprint.sh --startDay 2024-01-10 --endDay 2024-08-15The full list of options is documented below, but the ones you'll use most often are:
-S, --startDay/-E, --endDay: restrict the logs considered, formatted asYYYY-MM-DD.-o, --output:terminalfor terminal output (default) orhtmlfor an HTML report. When using the HTML report, a subdirectory is created for it — by default underGreenAlgorithms4HPC/outputs/, though this can be changed.--outputDir: path to export any output to.
- The workload manager doesn't always log exact CPU usage time; when this information is missing, we assume all cores are used at 100%.
- GPUs are currently assumed to be used at 100%, as the information needed for more accurate measurement isn't available. (Both of these assumptions may lead to slightly overestimated carbon footprints, although the order of magnitude should still be correct.)
- Conversely, wasted energy due to memory over-allocation may be largely underestimated, as the information needed for this isn't always logged.
usage: __init__.py [-h] [-S STARTDAY] [-E ENDDAY] [-o OUTPUT] [--outputDir OUTPUTDIR] [--filterCWD] [--filterJobIDs FILTERJOBIDS] [--filterAccount FILTERACCOUNT]
[--customSuccessStates CUSTOMSUCCESSSTATES] [--reportBug | --reportBugHere] [--useCustomLogs USECUSTOMLOGS]
Calculate your carbon footprint on the server.
options:
-h, --help show this help message and exit
-S STARTDAY, --startDay STARTDAY
The first day to take into account, as YYYY-MM-DD (default: 2026-01-01)
-E ENDDAY, --endDay ENDDAY
The last day to take into account, as YYYY-MM-DD (default: today)
-o OUTPUT, --output OUTPUT
How to display the results, one of 'terminal' or 'html' (default: terminal)
--outputDir OUTPUTDIR
Export path for the output (default: under `output/`). Only used with `--output html`.
--filterCWD Only report on jobs launched from the current location.
--filterJobIDs FILTERJOBIDS
Comma separated list of Job IDs you want to filter on. (default: "all")
--filterAccount FILTERACCOUNT
Only consider jobs charged under this account
--customSuccessStates CUSTOMSUCCESSSTATES
Comma-separated list of job states. By default, only jobs that exit with status CD or COMPLETED are considered successful (PENDING, RUNNING and REQUEUD
are ignored). Jobs with states listed here will be considered successful as well (best to list both 2-letter and full-length codes. Full list of job
states: https://slurm.schedmd.com/squeue.html#SECTION_JOB-STATE-CODES
--reportBug In case of a bug, this flag exports the jobs logs so that you/we can investigate further. The debug file will be stored in the shared folder where this
tool is located (under /outputs), to export it to your home folder, user `--reportBugHere`. Note that this will write out some basic information about
your jobs, such as runtime, number of cores and memory usage.
--reportBugHere Similar to --reportBug, but exports the output to your home folder.
--useCustomLogs USECUSTOMLOGS
This bypasses the workload manager, and enables you to input a custom log file of your jobs. This is mostly meant for debugging, but can be useful in
some situations. An example of the expected file can be found at `example_files/example_sacctOutput_raw.txt`.
👉 This only needs to be installed once per cluster — check first that someone else hasn't already installed it!
- Python 3.11+
- See requirements.txt for full dependencies.
- Clone this repository into a shared directory on your cluster:
$ cd shared_directory
$ git clone https://github.com/Llannelongue/GreenAlgorithms4HPC.git- Tell the script how to load Python on your cluster. For this, edit
myCarbonFootprint.sh: Find the line that creates the virtual environment; it's marked with the comment# EDIT ME: this line needs updating to load python on your server. The default line is:
/usr/bin/python3.8 -m venv GA_env
Replace it with whatever loads Python 3.11+ on your server, for example:
module load python/3.11.7
python -m venv GA_env
- Make the bash script executable:
$ chmod +x shared_directory/GreenAlgorithms4HPC/myCarbonFootprint.sh-
Tell the tool what hardware is used on your cluster. This is the most demanding step of installation (but only needs to be done once!). Edit
data/cluster_info.yamlto plug in the values corresponding to your cluster's hardware specs. Ask your HPC team, and check the Green Algorithms GitHub for useful reference values: https://github.com/Cambridge-Sustainable-Computing-Lab/Green-Algorithms-data -
Run the script once to set things up. This checks that the correct version of Python is available and creates the virtual environment with the required packages, based on requirements.txt:
$ shared_directory/GreenAlgorithms4HPC/myCarbonFootprint.shMore elegant solutions welcome! Discussion here.
Important
Before updating, make sure you've saved a copy of your custom cluster_info.yaml and noted how you loaded Python 3.11+ during the initial installation.
git reset --hard— removes local changes to files (hence the need for a backup above!)git pull- Re-apply your
cluster_info.yamlandmyCarbonFootprint.shedits as described in Step-by-step. chmod +x myCarbonFootprint.shto make it executable again.- Test
myCarbonFootprint.sh.
Contributions and improvements are welcome! Here is how to do it:
Important
Small edits can be done by simply opening a pull request. For larger, more significant, changes, please open an issue to discuss it first so that you're not working for nothing!
- Fork the repository and clone your fork locally.
- Create a new branch off
mainfor your change:
git checkout main
git checkout -b feature/<your-feature-name>-<your-username>- Make your changes, then run
pytest .to make sure nothing's broken. - Commit your changes with a clear message, push to your fork, and open a Pull Request against
main.
Yes it can! The tool uses Green-Algorithms-core to pull logs from workload managers like SLURM. Please create an issue so that our team can help you implement it for your workload manager.
If you have questions, run into issues, or want to share feedback, please open a thread in GitHub Discussions. This is the best place to get support from the development team and the wider community.
This tool is built and maintained by the Cambridge Sustainable Computing Lab at the University of Cambridge, UK.
This work is licensed under the GNU General Public License v3.0.