CATS: the Climate-Aware Task Scheduler

A lightweight Python-based tool that calculates the optimal time to run a compute job to minimise its carbon intensity enabling environmentally-conscious scheduling.
https://github.com/GreenScheduler/cats

Category: Emissions
Sub Category: Carbon Intensity and Accounting

Keywords

carbon carbon-footprint climate computing electricity electricity-consumption energy energy-consumption job-scheduler scheduling

Keywords from Contributors

sustainability climate-change earth-system-model

Last synced: about 17 hours ago
JSON representation

Repository metadata

🐈 CATS: the Climate-Aware Task Scheduler 🌍

Host: GitHub
URL: https://github.com/GreenScheduler/cats
Owner: GreenScheduler
License: mit
Created: 2023-05-04T09:16:56.000Z (over 3 years ago)
Default Branch: main
Last Pushed: 2026-11-02T21:21:56.000Z (4 days ago)
Last Synced: 2026-11-06T13:01:37.373Z (about 17 hours ago)
Topics: carbon, carbon-footprint, climate, computing, electricity, electricity-consumption, energy, energy-consumption, job-scheduler, scheduling
Language: Python
Homepage: https://cats.readthedocs.io
Size: 9.41 MB
Stars: 82
Watchers: 6
Forks: 22
Open Issues: 39
Releases: 6
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff

README.md

CATS: Climate-Aware Task Scheduler

CATS logo

Category	Links (click badges)
Paper & DOI
Documentation
Repository
Testing & CI
Package
Quality
Community
Licence

CATS is a Climate-Aware Task Scheduler. It schedules cluster jobs to minimize predicted carbon intensity of running the process. It was created as part of the 2023 Collaborations Workshop.

The Climate-Aware Task Scheduler is a lightweight Python package designed to schedule tasks based on the estimated carbon intensity of the electricity grid at any given moment. This tool uses real-time carbon intensity data from the National Grid ESO via their API to estimate the carbon intensity of the electricity grid, and schedules tasks at times when the estimated carbon intensity is lowest. This helps to reduce the carbon emissions associated with running computationally intensive tasks, making it an ideal solution for environmentally conscious developers.

Demo showing CATS scheduling a 30 minute job using the at scheduler
CATS animated usage example

[!NOTE]
Currently CATS only works by default in the Great Britain (using National Grid data) or elsewhere in Europe using data from the wattnet.eu project. If you are aware of APIs for realtime grid carbon intensity data in other countries please open an issue and let us know. Several providers also serve other metrics, selected with --metric: energy-charts.info and octopus.energy can schedule for lowest electricity cost instead of carbon, carbonintensity.org.uk and energy-charts.info can schedule for highest renewable share, and wattnet.eu also serves a water footprint, a water stress footprint and an environmental score. Run cats --list-providers to see all available providers and their metrics.

Rather than blending price into that weighted score, where it could dominate the schedule if given enough weight, CATS can instead treat price as a hard constraint on top of whichever metric is actually being optimised, via --max-price (absolute cap) or --max-price-increase-pct (cap relative to running the job right now), and always reports the price impact of the chosen schedule when price data is available, whether or not either flag is given.

Features

Estimates the carbon intensity of the electricity grid in real-time
Schedules tasks based on the estimated carbon intensity, minimizing carbon emissions
Provides a simple and intuitive API for developers
Lightweight and easy to integrate into existing workflows
Supports Python 3.11+

Brief example with plot to illustrate

To find the minimal carbon intensity window for a 3 hour (180 minute duration) job running
at the RG1 postcode and show visually the carbon intensity curve and optimal window with
the --plot argument:

$ cats --duration 180 --location "RG1" --plot
...

The.____ ..... __ .... ________ . ______...
.. /  __)...../  \....(__    __).)  ____)....
..|  /......./    \......|  |...(  (___........
..| |limate./  ()  \ware.|  |ask.\___  \cheduler
..|  \__...|   __   |....|  |....____)  )....
...\    )..|  (..)  |....|  |...(      (..


Best job start time                       = 2026-01-22 10:10:31
Carbon intensity if job started now       = 217.41 gCO2eq/kWh
Carbon intensity at optimal time          = 118.65 gCO2eq/kWh

which produced at the time run (Tue 20 Jan 15:40:21 GMT 2026) a forecast minimum of
118.65 gCO2eq/kWh for job start time 2026-01-22 10:10:31 as reported in the STDOUT above and
illustrated by the resulting plot of:

CATS command run plot example output for RG1 and 3 hour job

Installation

Install via pip as follows:

pip install climate-aware-task-scheduler

To install the development version:

pip install git+https://github.com/GreenScheduler/cats

Documentation

Documentation is available at https://cats.readthedocs.io

We recommend the
quickstart
if you are new to CATS. CATS can optionally display carbon footprint
savings
using a configuration file.

Contributing

We welcome contributions from the community! If you find a bug or have an idea for a new feature, please open an issue on our GitHub repository or submit a pull request.

License

MIT License

Citation (CITATION.cff)

cff-version: "1.2.0"
authors:
- family-names: Bartholomew
  given-names: Sadie L.
  orcid: "https://orcid.org/0000-0002-6180-3603"
- family-names: Colling
  given-names: Lincoln
  orcid: "https://orcid.org/0000-0002-3572-7758"
- family-names: Dasgupta
  given-names: Abhishek
  orcid: "https://orcid.org/0000-0003-4420-0656"
- family-names: Greenberg
  given-names: Anthony J.
  orcid: "https://orcid.org/0000-0003-3296-5811"
- family-names: Lannelongue
  given-names: Loïc
  orcid: "https://orcid.org/0000-0002-9135-1345"
- family-names: Lestang
  given-names: Thibault
  orcid: "https://orcid.org/0000-0001-6770-2638"
- family-names: Martinez-Ortiz
  given-names: Carlos
  orcid: "https://orcid.org/0000-0001-5565-7577"
- family-names: Sauzé
  given-names: Colin
  orcid: "https://orcid.org/0000-0001-5368-9217"
- family-names: Walker
  given-names: Andrew M.
  orcid: "https://orcid.org/0000-0003-3121-3255"
- family-names: Ward
  given-names: Adam Stuart
  orcid: "https://orcid.org/0009-0008-3463-2694"
contact:
- family-names: Walker
  given-names: Andrew M.
  orcid: "https://orcid.org/0000-0003-3121-3255"
doi: 10.5281/zenodo.15753041
message: If you use this software, please cite our article in the
  Journal of Open Source Software.
preferred-citation:
  authors:
  - family-names: Bartholomew
    given-names: Sadie L.
    orcid: "https://orcid.org/0000-0002-6180-3603"
  - family-names: Colling
    given-names: Lincoln
    orcid: "https://orcid.org/0000-0002-3572-7758"
  - family-names: Dasgupta
    given-names: Abhishek
    orcid: "https://orcid.org/0000-0003-4420-0656"
  - family-names: Greenberg
    given-names: Anthony J.
    orcid: "https://orcid.org/0000-0003-3296-5811"
  - family-names: Lannelongue
    given-names: Loïc
    orcid: "https://orcid.org/0000-0002-9135-1345"
  - family-names: Lestang
    given-names: Thibault
    orcid: "https://orcid.org/0000-0001-6770-2638"
  - family-names: Martinez-Ortiz
    given-names: Carlos
    orcid: "https://orcid.org/0000-0001-5565-7577"
  - family-names: Sauzé
    given-names: Colin
    orcid: "https://orcid.org/0000-0001-5368-9217"
  - family-names: Walker
    given-names: Andrew M.
    orcid: "https://orcid.org/0000-0003-3121-3255"
  - family-names: Ward
    given-names: Adam Stuart
    orcid: "https://orcid.org/0009-0008-3463-2694"
  date-published: 2025-07-08
  doi: 10.21105/joss.08251
  issn: 2475-9066
  issue: 111
  journal: Journal of Open Source Software
  publisher:
    name: Open Journals
  start: 8251
  title: "CATS: The Climate Aware Task Scheduler"
  type: article
  url: "https://joss.theoj.org/papers/10.21105/joss.08251"
  volume: 10
title: "CATS: The Climate Aware Task Scheduler"

Owner metadata

Name: GreenScheduler
Login: GreenScheduler
Email:
Kind: organization
Description:
Website:
Location:
Twitter:
Company:
Icon url: https://avatars.githubusercontent.com/u/132558689?v=4
Repositories: 1
Last ynced at: 2026-11-06T05:52:25.825Z
Profile URL: https://github.com/GreenScheduler

GitHub Events

Total

Create event: 12
Delete event: 21
Fork event: 5
Issue comment event: 69
Issues event: 28
Pull request event: 36
Pull request review comment event: 28
Pull request review event: 31
Push event: 80
Release event: 1
Watch event: 21

Last Year

Create event: 2
Delete event: 1
Issue comment event: 8
Issues event: 3
Pull request event: 3
Pull request review comment event: 8
Pull request review event: 5
Push event: 18

Committers metadata

Last synced: 1 day ago

Total Commits: 592
Total Committers: 20
Avg Commits per committer: 29.6
Development Distribution Score (DDS): 0.78

Commits in past year: 181
Committers in past year: 11
Avg Commits per committer in past year: 16.455
Development Distribution Score (DDS) in past year: 0.597

Name	Email	Commits
Andrew Walker	a**r@e**k	130
Thibault Lestang	t**g@i**k	108
Abhishek Dasgupta	a**a@d**k	102
Sadie L. Bartholomew	s**w@n**k	97
Loïc Lannelongue	l**e@p**t	44
Colin Sauze	c**e@n**k	27
Adam Ward	a**a@n**k	17
Jaime Iglesias Blanco	j**s@o**m	15
Lincoln Colling	l**n@c**z	13
pre-commit-ci[bot]	6****]	10
Tony Greenberg	i**o@b**g	6
Ali - Mac	e**n@g**m	5
isofinly	i**y@i**m	5
Rayhan Ali	2****4	3
Ali - Mac	8****1	3
Carlos Martinez	c**z@e**l	2
spr7a	s**5@g**m	2
Andy Turner	a**r@e**k	1
James Byrne	j**n@g**m	1
Nicolas Payette	n**e@g**m	1

Committer domains:

Issue and Pull Request metadata

Last synced: 1 day ago

Total issues: 120
Total pull requests: 161
Average time to close issues: 5 months
Average time to close pull requests: 21 days
Total issue authors: 12
Total pull request authors: 24
Average comments per issue: 1.54
Average comments per pull request: 1.94
Merged pull request: 121
Bot issues: 0
Bot pull requests: 3

Past year issues: 35
Past year pull requests: 44
Past year average time to close issues: 2 months
Past year average time to close pull requests: 7 days
Past year issue authors: 5
Past year pull request authors: 14
Past year average comments per issue: 1.54
Past year average comments per pull request: 2.02
Past year merged pull request: 27
Past year bot issues: 0
Past year bot pull requests: 3

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/GreenScheduler/cats

Top Issue Authors

andreww (34)
abhidg (32)
sadielbartholomew (23)
colinsauze (9)
mkbane (7)
Llannelongue (6)
LiamPattinson (3)
tlestang (2)
elichad (1)
ip2location (1)
jaimeib (1)
thomasferte (1)

Top Pull Request Authors

andreww (51)
abhidg (42)
tlestang (17)
sadielbartholomew (12)
Llannelongue (6)
dalexdavis (5)
alierguney1 (4)
pre-commit-ci[bot] (3)
danielskatz (2)
nicolaspayette (2)
aturner-epcc (2)
jaimeib (2)
colinsauze (2)
c-martinez (1)
ocoodo (1)

Top Issue Labels

enhancement (30)
documentation (21)
good first issue (8)
refactoring (5)
testing (4)
carbonIntensityAPI (4)
catsV2 (4)
question (4)
bug (4)
carbonFootprint (3)
plotting (2)
timeOptimiser (2)
JOSS requirement (1)
RFC (1)
wrapper (1)

Top Pull Request Labels

documentation (9)
enhancement (4)
refactoring (2)
bug (1)
testing (1)
good first issue (1)
release/packaging (1)

Package metadata

Total packages: 1
Total downloads:
- pypi: 116 last-month
Total dependent packages: 0
Total dependent repositories: 0
Total versions: 5
Total maintainers: 2

pypi.org: climate-aware-task-scheduler

Climate aware task scheduler

Homepage: https://github.com/GreenScheduler/cats
Documentation: https://cats.readthedocs.io/
Licenses: MIT License
Latest release: 1.2.1 (published about 1 month ago)
Last Synced: 2026-11-05T12:43:22.269Z (1 day ago)
Versions: 5
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 116 Last month
Rankings:
- Dependent packages count: 10.607%
- Average: 35.17%
- Dependent repos count: 59.732%
Maintainers (2)
- abhidg
- andreww

Dependencies

.github/workflows/tests.yml actions

actions/checkout v3 composite
actions/setup-python v4 composite

pyproject.toml pypi

PyYAML >=6.0
requests-cache >=1.0

.github/workflows/cluster-tests.yml actions

actions/checkout v4 composite
docker/login-action v3 composite

.github/workflows/publish.yml actions

actions/checkout 1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 composite
actions/setup-python v5 composite
pypa/gh-action-pypi-publish ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e composite

.github/workflows/zizmor.yml actions

actions/checkout 1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 composite
zizmorcore/zizmor-action e639db99335bc9038abc0e066dfcd72e23d26fb4 composite

cluster/docker-compose.yml docker

ghcr.io/greenscheduler/slurm-docker-cluster latest
mariadb 10.11

Score: 12.553908640801701

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Open Sustainable Technology