While computing currently represents roughly 0.5% of the world’s energy consumption, that percentage is projected to grow beyond 2% in the coming years, which will entail a significant rise in global CO2 emissions if not done properly. Given this increase, it is important to quantify and track the extent and origin of this energy usage, and to minimize the emissions incurred as much as possible.

For this purpose, we created Emissions Tracker, a Python package for tracking the carbon emissions produced by various kinds of computer programs, from straightforward algorithms to deep neural networks.

By taking into account your computing infrastructure, location, usage and running time, Emissions Tracker can provide an estimate of how much CO₂ you produced, and give you some comparisons with common modes of transporation to give you an order of magnitude.

Our hope is that this package will be used widely for estimating the carbon footprint of computing, and for establishing best practices with regards to the disclosure and reduction of this footprint.

Follow the steps below to set up the package and don't hesitate to open an issue if you need help!

Create a virtual environment using conda for easier management of dependencies and packages. For installing conda, follow the instructions on the official conda website

conda create --name codecarbon python=3.6 conda activate codecarbon pip install . 

codecarbon will now be installed in your the local environment

This is the most straightforward usage of the package, which is possible if you have access to the Internet, which is necessary to gather information regarding your geographical location.

from codecarbon import EmissionsTracker tracker = EmissionsTracker() tracker.start() # GPU Intensive code goes here tracker.stop()

You can also use the decorator:

from codecarbon import track_emissions @track_emissions def training_loop(): pass

This mode can be used in setups without internet access, but requires a manual specification of your country code. A complete list of country ISO codes can be found on Wikipedia.

The offline tracker can be used as follows:

from codecarbon import OfflineEmissionsTracker tracker = OfflineEmissionsTracker(country_iso_code="CAN") tracker.start() # GPU Intensive code goes here tracker.stop()

or by using the decorator:

from codecarbon import track_emissions @track_emissions(offline=True, country_iso_code="CAN") def training_loop(): pass

As a simple illustration of using the package, we use a built-in example using TensorFlow for digit classification on the MNIST dataset:

First, install Tensorflow 2.0:

pip install tensorflow 

Then, run the examples in the examples/ folder, which will call the online version of the Emissions tracker by default:

python examples/mnist.py python examples/mnist_decorator.py 

This will create a .csv file with information about the energy that you used to carry out the classification task, and an estimate of the CO₂ that you generated, complete with comparisons to common modes of transportation to give you a better idea of the order of magnitude of your emissions.

We are hoping that the open-source community will help us edit our code and make it better! If you want to contribute, make sure that the tox package is available to run tests and debug:

pip install tox 

You can run tests by simply entering tox in the terminal when in the root package directory, and it will run the predefined tests.

tox 

In order to contribute a change to our code base, please submit a pull request (PR) via GitHub and someone from our team will go over it and accept it.

No software is complete without great documentation! To make generating documentation easier, install the sphinx package and use it to edit and improve the existing documentation:

pip install -U sphinx sphinx_rtd_theme cd docs/edit make docs 

In order to make changes, edit the .rst files that are in the /docs/edit folder, and then run:

make docs 

to regenerate the html files.

To track the evolution of your CO₂ emissions or just to see some nice graphs and charts, you can use the visualization tool that we created. As input, it takes a .csv file in the format generated by the Emissions Tracker, and it generates a visualization of the emissions incurred.

You can run try it out on a sample data file such as the one in examples/emissions.csv, and run it with the following command:

python codecarbon/viz/carbonboard.py --filepath="examples/emissions.csv" 

Once you have generated your own .csv file based on your computations, you can feed that into the visualization tool to see a more visual representation of your own emissions.

You can also see the carbon intensity of different regions and countries:

As well as the relative carbon intensity of different compute regions of cloud providers: