Eco2AI
About Eco2AI :clipboard:
The Eco2AI is a python library for CO2 emission tracking. It monitors energy consumption of CPU & GPU devices and estimates equivalent carbon emissions taking into account the regional emission coefficient.
The Eco2AI is applicable to all python scripts and all you need is to add the couple of strings to your code. All emissions data and information about your devices are recorded in a local file.
Every single run of Tracker() accompanies by a session description added to the log file, including the following elements:
- project_name
- experiment_description
- start_time
- duration(s)
- power_consumption(kWTh)
- CO2_emissions(kg)
- CPU_name
- GPU_name
- OS
- country
Installation
To install the eco2AI library, run the following command:
pip install eco2ai
pip install does not ask questions. eco2ai with no arguments prints the settings folder and the results folder for this worktree and writes nothing. eco2ai --settings-dir C:/Users/User/.eco2ai stores that directory in .eco2ai/config.json. The first country lookup and the first CPU socket count are written to config.json inside the settings folder, as country, region, and cpu_sockets. With no settings_dir, that folder is ~/.eco2ai. Tracker(alpha_2_code=..., region=..., cpu_sockets=...) overrides those values for one run and does not change the file. project_name, experiment_description, and file_name stay Tracker arguments and set_params values: the first two are columns in the results CSV, and file_name is that CSV. One file holds many experiments. A relative file_name is written in the process working directory. eco2ai --results-dir D:/project/results sends every relative results file in this worktree to that directory. An absolute file_name is used as given.
Accelerators are read from the driver already on the machine. eco2ai installs no GPU package. NVIDIA is read from the driver NVML library, with nvidia-smi as a power fallback. AMD, Intel discrete GPUs, Huawei Ascend, and Google TPU are read from rocm-smi or amd-smi, xpu-smi, npu-smi, and tpu-info when those tools shipped with the device.
Use examples
Example usage eco2AI 
You can also find eco2AI tutorial on youtube 
The eco2AI interface is quite simple. Here is the simplest usage example:
import eco2ai
tracker = eco2ai.Tracker(project_name="YourProjectName", experiment_description="training the <your model> model")
tracker.start()
<your gpu &(or) cpu calculations>
tracker.stop()
# The same run as a context manager. Leaving the block stops the tracker.
with eco2ai.Tracker(project_name="YourProjectName", experiment_description="training the <your model> model") as tracker:
<your gpu &(or) cpu calculations>
The eco2AI also supports decorators. As soon as the decorated function is executed, the information about the emissions will be written to the emission.csv file:
from eco2ai import track
@track
def train_func(model, dataset, optimizer, epochs):
...
train_func(your_model, your_dataset, your_optimizer, your_epochs)
@track(project_name="Malevich", file_name="run.csv")
def train_named(model, epochs):
...
train_named(model, 2)
The same run can be a context manager. Leaving the block stops the tracker:
import eco2ai
with eco2ai.Tracker(project_name="Malevich", file_name="run.csv") as tracker:
<your gpu &(or) cpu calculations>
A callable passed as callback receives each row after it is written. Lightning users can pass Eco2AICallback to Trainer. That import needs Lightning (pip install lightning) and is not loaded by import eco2ai.
import lightning.pytorch as L
from eco2ai.lightning import Eco2AICallback
trainer = L.Trainer(callbacks=[
Eco2AICallback(project_name="Malevich", file_name="fit.csv")
])
trainer.fit(model)
# One row per training epoch. Fit end stops the tracker.
# The open interval after the last epoch is written only when it used energy.
Arguments passed to Tracker apply only to that instance. Persistent defaults are written by set_params and read by the next Tracker that omits those arguments. For example:
import eco2ai
tracker = eco2ai.Tracker(
project_name="YourProjectName",
experiment_description="training <your model> model",
file_name="emission.csv"
)
tracker.start()
<your gpu &(or) cpu calculations>
tracker.stop()
...
# The names above were not saved. A Tracker with no names uses set_params
# defaults, or the built-in defaults when set_params was never called.
tracker = eco2ai.Tracker()
tracker.start()
<your gpu &(or) cpu calculations>
tracker.stop()
You can also set parameters using the set_params() function, as in the example below:
from eco2ai import set_params, Tracker
set_params(
project_name="My_default_project_name",
experiment_description="We trained...",
file_name="my_emission_file.csv"
)
tracker = Tracker()
# now, it's equivelent to:
# tracker = Tracker(
# project_name="My_default_project_name",
# experiment_description="We trained...",
# file_name="my_emission_file.csv"
# )
tracker.start()
<your code>
tracker.stop()
A second run with another experiment_description and the same file_name appends another row. eco2ai --results-dir changes only where a relative file_name is written:
eco2ai --results-dir D:/project/results
with eco2ai.Tracker(project_name="demo", experiment_description="baseline", file_name="emission.csv"):
train()
# writes D:/project/results/emission.csv
Omit results_dir and emission.csv stays in the process working directory. eco2ai prints (working directory) in that case.
Important note
If for some reasons it is not possible to define country, then emission coefficient is set to 458.490 kg/MWh, the 2025 world average. Country rows and this world fallback use Ember Yearly Electricity Data, CO2 intensity (gCO2/kWh, direct CO2, not CO2e). gCO2/kWh and kg/MWh are the same number. Each row records that intensity in Emission intensity, kg/MWh, plus the data year and a reference key. The keys are in eco2ai/data/SOURCES.md.
Ember Yearly Electricity Data
Regional rows, where they exist, use the sources in eco2ai/data/SOURCES.md. The country row for that nation stays the Ember value.
For proper calculation of gpu and cpu power consumption, you should create a “Tracker” before any gpu or CPU usage.
Create a new “Tracker” for every new calculation.
Usage of Eco2AI
An example of using the library is given in the publication. It the paper we presented experiments of tracking equivalent CO2 emissions using eco2AI while training ruDALL-E models with with 1.3 billion (Malevich, ruDALL-E XL 1.3B) and 12 billion parameters (Kandinsky, ruDALL-E XL 12B). These are multimodal pre-trained transformers that learn the conditional distribution of images with by some string of text capable of generating arbitrary images from a russian text prompt that describes the desired result.
Properly accounted carbon emissions and power consumption Malevich and Kandinsky fine-tuning Malevich and Kandinsky on the Emojis dataset is given in the table below.
| Model |
Train time |
Power, kWh |
CO2, kg |
GPU |
CPU |
Batch Size |
| Malevich |
4h 19m |
1.37 |
0.33 |
A100 Graphics, 1 |
AMD EPYC 7742 64-Core |
4 |
| Kandinsky |
9h 45m |
24.50 |
5.89 |
A100 Graphics, 8 |
AMD EPYC 7742 64-Core |
12 |
Also we presented results for training of Malevich with optimized variation of GELU activation function. Training of the Malevich with the 8-bit version of GELU allows us to spent about 10% less energy and, consequently, produce less equivalent CO2 emissions.
Citing Eco2AI
The Eco2AI is licensed under a Apache licence 2.0.
Please consider citing the following paper in any research manuscript using the Eco2AI library:
@article{eco2AI,
title={eco2AI: Carbon Emissions Tracking of Machine Learning Models as the First Step Towards Sustainable AI},
url={https://doi.org/10.1134/S1064562422060230}, DOI={10.1134/S1064562422060230},
journal={Doklady Mathematics},
author={Budennyy, S. A. and Lazarev, V. D. and Zakharenko, N. N. and Korovin, A. N. and Plosskaya, O. A. and Dimitrov, D. V. and Akhripkin, V. S. and Pavlov, I. V. and Oseledets, I. V. and Barsola, I. S. and Egorov, I. V. and Kosterina, A. A. and Zhukov, L. E.}, year={2023}, month=jan, language={en}}
In collaboration with
.png?v=3)
评论