[](https://grace-hpc.readthedocs.io/en/latest/?badge=latest)
# GRACE-HPC
**G**reen **R**esource for **A**ssessing **C**arbon & **E**nergy in **HPC**
`gracehpc` is a lightweight Python package designed to enable users and operators of SLURM-based HPC systems to estimate and analyse the carbon footprint of their computational workloads. It calculates and displays **energy consumption, Scope 2 (operational)** and **Scope 3 (embodied)** carbon emissions for your jobs ran on the system, using SLURM accounting logs and user-specified parameters.
## Documentation
For a complete guide to the methodology, installation, and usage of GRACE-HPC, please visit the [**Official Documentation here**](https://grace-hpc.readthedocs.io/en/latest/).
# How to use it?
The package prioritises user experience, accessibility, and flexibility by offering three usage modes designed to accommodate a wide range of users.
1. **Command-line Interface**
The tool can be used directly from the command line of your HPC system with simple commands and a wide range of arguments. Ideal for quick analyses for users more comfortable with a lower-level interface and output.
2. **Python Function Call**
The same core engine can be called via a function in a Python Script (.py) or a Jupyter Notebook (.ipynb). This mode is ideal for workflow integration and automation, allowing the tool to be embedded into larger Python applications. It also returns the raw datasets produced by the tool for further exploration and user-led analysis afterwards. If you want flexibility, this is the mode for you.
3. **Interactive Jupyter Interface**
A simple, widget-based interface can be launched from a Jupyter Notebook (.ipynb) displaying a rich output containing HTML text boxes and interactive plots. This mode allows users to experiment with different parameters without any coding, visualising interesting plots instantly within a single .ipynb notebook. Ideal for users wanting a higher-level, interactive experience.
# Key Features
- **Flexible Job Selection:** Specify a date range to process jobs for, individual Job IDs, or both.
<br>
- **Job Log Extraction:** Extracts and processes job details (such as runtime, resource allocation, and usage) using SLURM's sacct command.
<br>
- **Energy Consumption:** Calculates energy consumption using both usage data and system energy counters (if available).
<br>
- **Scope 2 Emissions:** Estimates scope 2 (operational) emissions produced by the jobs using **real-time, region-specific carbon intensity data** from the [National Grid ESO Carbon Intensity API](https://carbonintensity.org.uk).
<br>
- **Scope 3 Emissions:** Includes Scope 3 (embodied) emissions estimates for a few HPC systems that have undergone a lifecycle assessment and calculated a per node-hour scope 3 emissions factor (Isambard 3, Isambard-AI, Archer 2).
<br>
- **Contextual Equivalents:** Results include CO₂e equivalents such as the driving, tree-months and flying to help users interpret and understand the scale of the environmental impact.
<br>
- **Rich Output Options:** View results in the terminal, export to CSV, load as DataFrames, or display interactively in notebooks with instant plots.
<br>
The overall goal of this tool is not to serve as a definitive energy and carbon cluster monitoring tool, but rather to provide accessible estimates that inform and raise awareness about the environmental impact of HPC workloads - promoting more sustainable, carbon-aware practices.
Raw data
{
"_id": null,
"home_page": "https://github.com/Elliot-Ayliffe/GRACE-HPC",
"name": "gracehpc",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.11",
"maintainer_email": null,
"keywords": "HPC, carbon, emissions, SLURM, sustainability, energy, GRACE",
"author": "Elliot Ayliffe",
"author_email": "Elliot.ayliffe@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/fb/96/ddcbdb5d81d52cece59de5746664a26a06429729314215f6f94826f90067/gracehpc-0.1.0.tar.gz",
"platform": null,
"description": "\n\n\n[](https://grace-hpc.readthedocs.io/en/latest/?badge=latest)\n\n# GRACE-HPC\n\n**G**reen **R**esource for **A**ssessing **C**arbon & **E**nergy in **HPC**\n\n`gracehpc` is a lightweight Python package designed to enable users and operators of SLURM-based HPC systems to estimate and analyse the carbon footprint of their computational workloads. It calculates and displays **energy consumption, Scope 2 (operational)** and **Scope 3 (embodied)** carbon emissions for your jobs ran on the system, using SLURM accounting logs and user-specified parameters.\n\n## Documentation \n\nFor a complete guide to the methodology, installation, and usage of GRACE-HPC, please visit the [**Official Documentation here**](https://grace-hpc.readthedocs.io/en/latest/).\n\n# How to use it?\n\nThe package prioritises user experience, accessibility, and flexibility by offering three usage modes designed to accommodate a wide range of users.\n\n1. **Command-line Interface**\n\nThe tool can be used directly from the command line of your HPC system with simple commands and a wide range of arguments. Ideal for quick analyses for users more comfortable with a lower-level interface and output.\n\n2. **Python Function Call**\n\nThe same core engine can be called via a function in a Python Script (.py) or a Jupyter Notebook (.ipynb). This mode is ideal for workflow integration and automation, allowing the tool to be embedded into larger Python applications. It also returns the raw datasets produced by the tool for further exploration and user-led analysis afterwards. If you want flexibility, this is the mode for you.\n\n3. **Interactive Jupyter Interface**\n\nA simple, widget-based interface can be launched from a Jupyter Notebook (.ipynb) displaying a rich output containing HTML text boxes and interactive plots. This mode allows users to experiment with different parameters without any coding, visualising interesting plots instantly within a single .ipynb notebook. Ideal for users wanting a higher-level, interactive experience.\n\n\n# Key Features \n\n- **Flexible Job Selection:** Specify a date range to process jobs for, individual Job IDs, or both.\n<br>\n\n- **Job Log Extraction:** Extracts and processes job details (such as runtime, resource allocation, and usage) using SLURM's sacct command.\n<br>\n\n- **Energy Consumption:** Calculates energy consumption using both usage data and system energy counters (if available).\n<br>\n\n- **Scope 2 Emissions:** Estimates scope 2 (operational) emissions produced by the jobs using **real-time, region-specific carbon intensity data** from the [National Grid ESO Carbon Intensity API](https://carbonintensity.org.uk).\n<br>\n\n- **Scope 3 Emissions:** Includes Scope 3 (embodied) emissions estimates for a few HPC systems that have undergone a lifecycle assessment and calculated a per node-hour scope 3 emissions factor (Isambard 3, Isambard-AI, Archer 2).\n<br>\n\n- **Contextual Equivalents:** Results include CO\u2082e equivalents such as the driving, tree-months and flying to help users interpret and understand the scale of the environmental impact.\n<br>\n\n- **Rich Output Options:** View results in the terminal, export to CSV, load as DataFrames, or display interactively in notebooks with instant plots.\n<br>\n\nThe overall goal of this tool is not to serve as a definitive energy and carbon cluster monitoring tool, but rather to provide accessible estimates that inform and raise awareness about the environmental impact of HPC workloads - promoting more sustainable, carbon-aware practices.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "HPC energy and carbon emissions toolkit - calculate your computational carbon footprint for HPC through CLI, Jupyter, and script-based workflows.",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://grace-hpc.readthedocs.io/en/latest/",
"Homepage": "https://github.com/Elliot-Ayliffe/GRACE-HPC",
"Issues": "https://github.com/Elliot-Ayliffe/GRACE-HPC/issues",
"Repository": "https://github.com/Elliot-Ayliffe/GRACE-HPC"
},
"split_keywords": [
"hpc",
" carbon",
" emissions",
" slurm",
" sustainability",
" energy",
" grace"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8ea77f81bcc733875c179a6c519518a479109848b605b2533e9cb22f36607c0f",
"md5": "244844a9fe2668385b9d4d1b52c352b8",
"sha256": "38f400ee87bc3be16d35b343e9111f974b3a3e22d7621c59afd48ad50e824e26"
},
"downloads": -1,
"filename": "gracehpc-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "244844a9fe2668385b9d4d1b52c352b8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.11",
"size": 52247,
"upload_time": "2025-07-22T08:31:20",
"upload_time_iso_8601": "2025-07-22T08:31:20.790903Z",
"url": "https://files.pythonhosted.org/packages/8e/a7/7f81bcc733875c179a6c519518a479109848b605b2533e9cb22f36607c0f/gracehpc-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fb96ddcbdb5d81d52cece59de5746664a26a06429729314215f6f94826f90067",
"md5": "87c566787534378afd703f1196b05cbe",
"sha256": "29dd1135d2a9c5ade10c7a07ed0614866dac1291cee5b30357c214219bab16cc"
},
"downloads": -1,
"filename": "gracehpc-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "87c566787534378afd703f1196b05cbe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.11",
"size": 44680,
"upload_time": "2025-07-22T08:31:22",
"upload_time_iso_8601": "2025-07-22T08:31:22.207847Z",
"url": "https://files.pythonhosted.org/packages/fb/96/ddcbdb5d81d52cece59de5746664a26a06429729314215f6f94826f90067/gracehpc-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-22 08:31:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Elliot-Ayliffe",
"github_project": "GRACE-HPC",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "gracehpc"
}
JSON
