ENH: addition of carbon trackers to estimate compute costs

[nikhil153]

Changes proposed in this pull request

1. Addition of carbontracker feature to estimate carbon emissions incurred by processing workflows.
2. Addition of CodeCarbon dependency.

This PR is in reference to #2481 issue.

Documentation that should be reviewed

All the code changes and additions are described in this README. In summary, following files are to be reviewed:

Files modified:

1. setup.cfg (CodeCarbon dependency.)
2. parser.py
3. run.py
4. config.py

Files added

1. fmriprep/carbontracker

├── emissions_demo.csv
├── emissions_visual_demo.ipynb
├── figs
│   ├── CodeCarbon_example_emissions.png
│   ├── CodeCarbon_example_global.png
│   ├── fmriprep_carbontracker.jpg
│   └── sea-sig_logo.png
├── fmriprep_with_carbon_trackers.def
├── README.rst
├── requirements.txt
├── run_fmriprep_patch.sh

Usage

Carbon tracker feature can be used by specifying two optional arguments:
--track-carbon
--country-code "CAN"

[welcome]

Thanks for opening this pull request! It looks like this is your first time contributing to fMRIPrep. 😄
We invite you to list yourself as an fMRIPrep contributor. To learn more about what that entails and how we credit our contributors, please check out the contributing guidelines. If your name is not already on the list, please insert it, in alphabetical order, into the contributors.json file. Example:

   "name": "Contributor, New FMRIPrep",
   "affiliation": "Department of fMRI prep'ing, Open Science Made-Up University",
   "orcid": "<your id>"
}, ```

Of course, if you want to opt-out this time there is no problem at all with adding your name later. You will be always welcome to add it in the future whenever you feel it should be listed.

[pep8speaks]

Hello @nikhil153! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

There are currently no PEP 8 issues detected in this Pull Request. Cheers! 🍻

Comment last updated at 2022-08-10 01:32:44 UTC

[nikhil153]

Hi @effigies - finally got a chance to wrap-up this ENH we talked about at the brainhack! Let me know if you think of any improvements for simplifying usage. Thanks!

[effigies]

@nikhil153 Thanks! I plan to look at this later this week for some initial feedback, but please bug me on Tuesday (holiday Monday) if I fail.

[nikhil153]

Hi @effigies - bugging you as asked :) Any updates?

[nikhil153]

Hi @effigies - I am seeing a couple of new conflicts on this thread. Any suggestions / comments?

[effigies]

Resolved conflicts. Had a quick read-through, and this seems reasonably constrained. We'll probably want to push the dependencies into an extra (they'll get installed in the Docker image, but they shouldn't be required to install the package). I'm running some unrelated tests, and I can take the opportunity to patch this in while running them to get a sense of how it works.

[nikhil153]

Hi @effigies, sounds good, thanks so much!

[effigies]

Running with fmriprep-docker -u $UID (user mode instead of root), I see:

[codecarbon ERROR @ 16:30:00] Unable to read Intel RAPL files for CPU power, we will use a constant for your CPU power. Please view https://github.com/mlco2/codecarbon/issues/244 for workarounds : [Errno 13] Permission denied: '/sys/class/powercap/intel-
rapl/intel-rapl:1/energy_uj'                                                                                                                                                                                                                                  
[codecarbon ERROR @ 16:30:00] Unable to read Intel RAPL files for CPU power, we will use a constant for your CPU power. Please view https://github.com/mlco2/codecarbon/issues/244 for workarounds : [Errno 13] Permission denied: '/sys/class/powercap/intel-
rapl/intel-rapl:0/energy_uj'                                                                                                                                                                                                                                  
[codecarbon INFO @ 16:30:00] Tracking Intel CPU via RAPL interface                                                                                                                                                                                            
[codecarbon ERROR @ 16:30:01] Unable to read Intel RAPL files for CPU power, we will use a constant for your CPU power. Please view https://github.com/mlco2/codecarbon/issues/244 for workarounds : [Errno 13] Permission denied: '/sys/class/powercap/intel-
rapl/intel-rapl:1/energy_uj'                                                                                                                                                                                                                                  
[codecarbon ERROR @ 16:30:01] Unable to read Intel RAPL files for CPU power, we will use a constant for your CPU power. Please view https://github.com/mlco2/codecarbon/issues/244 for workarounds : [Errno 13] Permission denied: '/sys/class/powercap/intel-
rapl/intel-rapl:0/energy_uj'      
[codecarbon INFO @ 16:30:01] >>> Tracker's metadata:                                                                                                                                                                                                          
[codecarbon INFO @ 16:30:01]   Platform system: Linux-5.15.0-43-generic-x86_64-with-glibc2.31                                                                                                                                                                 
[codecarbon INFO @ 16:30:01]   Python version: 3.9.12                                                                                                                                                                                                         
[codecarbon INFO @ 16:30:01]   Available RAM : 62.544 GB                                                                                                                                                                                                      
[codecarbon INFO @ 16:30:01]   CPU count: 20                                                                                                                                                                                                                  
[codecarbon INFO @ 16:30:01]   CPU model: Intel(R) Core(TM) i9-10900 CPU @ 2.80GHz                                                                                                                                                                            
[codecarbon INFO @ 16:30:01]   GPU count: None                                                                                                                                                                                                                
[codecarbon INFO @ 16:30:01]   GPU model: None 
...
[codecarbon INFO @ 16:45:03] Energy consumed for RAM : 0.004693 kWh. RAM Power : 23.4539794921875 W
[codecarbon INFO @ 16:45:03] Energy consumed for all CPUs : 0.000000 kWh. All CPUs Power : 0.0 W
[codecarbon INFO @ 16:45:03] 0.004693 kWh of electricity used since the begining.

Is a 0W fallback expected?

[nikhil153]

So Docker version won't work unless run with the --privileged flag since by default it doesn't have sufficient permissions to read RAPL logs. I have been primarily using and testing with Singularity, which is more common on HPCs and that's where primarily we want to track carbon emissions.

[effigies]

I approve this in principle. I'm not sure what to do with the scripts/ and carbontracker/ directory. It looks like these were for proof-of-concept and/or documentation patches. What's the end goal for these?

[nikhil153]

Thanks @effigies!
The script directory has a couple my test CSVs - which can be ignored. The other two scripts fetch_templates.py and generate_reference_mask.py are not mine.
The carbontracker directory can also be ignored as it basically contains READMEs and scripts to patch my fork on the fMRIPrep Singularity container for trials and tests.
What's the best way to migrate my existing documentation for this ENH to the official one?

[effigies]

I would probably go ahead and make a new top-level document, like docs/carbon.rst, which can be inserted into the TOC here:

fmriprep/docs/index.rst

Lines 12 to 22 in 53765b5

	.. toctree::
	:maxdepth: 3
	installation
	usage
	workflows
	outputs
	spaces
	faq
	api
	changes

I would place it above faq. Are you comfortable writing RST? If you'd rather stick to markdown, we would need to add myst_parser to the extensions and doc requirements:

fmriprep/docs/conf.py

Lines 37 to 47 in 53765b5

	extensions = [
	"sphinx.ext.autodoc",
	"sphinx.ext.doctest",
	"sphinx.ext.intersphinx",
	"sphinx.ext.coverage",
	"sphinx.ext.mathjax",
	"sphinx.ext.linkcode",
	"sphinxarg.ext", # argparse extension
	"nipype.sphinxext.plot_workflow",
	"sphinxcontrib.napoleon",
	]

fmriprep/setup.cfg

Lines 54 to 59 in 53765b5

	doc =
	pydot >= 1.2.3
	sphinx >= 1.8
	sphinx-argparse
	sphinx_rtd_theme
	sphinxcontrib-napoleon

[effigies]

@nikhil153 I merged the condensed result: b6c8e1b

Documentation can be updated at your convenience in a new PR.

[nikhil153]

@effigies Thanks so much! Really appreciate your help in this project! Curious to see carbon estimate across hardware and geolocations.
RST is not a problem. I will update the documentation within few weeks!