Skip to content

Commit b8b2288

Browse files
author
benoit-cty
committed
Documentation
Docs
1 parent ef9ac99 commit b8b2288

5 files changed

Lines changed: 78 additions & 74 deletions

File tree

examples/slurm_rocm/README.md renamed to docs/advanced/adastra.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# CodeCarbon on CINES Adastra HPC with AMD ROCM
1+
# ROCm and PyTorch on SLURM SuperComputer
22

3-
This project was provided with computing and storage resources by GENCI at CINES thanks to the grant AD010615147R1 on the supercomputer Adastra's MI250x/MI300 partition.
3+
This project was provided with computing and storage resources by GENCI at CINES thanks to the grant AD010615147R1 on the [supercomputer Adastra](https://dci.dci-gitlab.cines.fr/webextranet/architecture/index.html)'s MI250x/MI300 partition.
44

55
Thanks to this grant we were able to develop and test the AMD ROCM support in CodeCarbon, and provide this quick start guide to help other users of Adastra HPC to easily monitor the carbon emissions of their machine learning workloads running on AMD GPUs.
66

‎docs/advanced/ansible.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Deploy CodeCarbon CLI as a Service using Ansible
2+
3+
This section describes how to deploy CodeCarbon as a system service
4+
using Ansible automation.
5+
6+
It automate the manual installation done in the previous chapter.
7+
8+
## What the Playbook Does
9+
10+
The Ansible playbook automates the following tasks:
11+
12+
- Creates a dedicated system user and group for CodeCarbon
13+
- Sets up a Python virtual environment
14+
- Installs CodeCarbon package
15+
- Configures RAPL permissions for power measurements
16+
- Creates and configures the systemd service
17+
- Sets up the CodeCarbon configuration file
18+
- Starts and enables the service
19+
20+
## Prerequisites
21+
22+
- Ansible installed on your machine
23+
- Debian-based target system(s)
24+
- SSH access to target system(s)
25+
- CodeCarbon API credentials from the dashboard
26+
27+
## Directory Structure
28+
29+
``` text
30+
codecarbon/deploy/ansible/codecarbon_cli_as_a_service/
31+
├── hosts
32+
├── tasks
33+
│ ├── install_codecarbon.yml
34+
│ ├── main.yml
35+
│ ├── rapl.yml
36+
│ └── systemd_service.yml
37+
├── templates
38+
│ ├── codecarbon.config.j2
39+
│ └── systemd_service.j2
40+
└── vars
41+
└── main.yml
42+
```
43+
44+
## Quick Start
45+
46+
1. Set the the target to install in `hosts`:
47+
48+
``` text
49+
yourservername.yourdomain.com hostname=yourservername ansible_user=root ansible_ssh_private_key_file=~/.ssh/id_ed25519
50+
```
51+
52+
2. Update the variables in `vars/main.yml` with your configuration:
53+
54+
``` yaml
55+
organization_id: your_org_id
56+
project_id: your_project_id
57+
experiment_id: your_experiment_id
58+
api_key: your_api_key
59+
```
60+
61+
3. Run the playbook:
62+
63+
``` bash
64+
ansible-playbook -i hosts tasks/main.yml
65+
```

docs/getting-started/advanced_installation.md renamed to docs/advanced/linux_service.md

Lines changed: 2 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,4 @@
1-
# Advanced Installation
2-
3-
## Install CodeCarbon as a Linux service
1+
# Install CodeCarbon as a Linux service
42

53
To install CodeCarbon as a Linux service, follow the instructions below.
64
It works on Ubuntu or other Debian-based systems using systemd.
@@ -112,70 +110,4 @@ journalctl -u codecarbon
112110
You are done, CodeCarbon is now running as a service on your machine.
113111

114112
Wait 5 minutes for the first measure to be send to the dashboard at
115-
<https://dashboard.codecarbon.io/>.
116-
117-
## Deploy CodeCarbon CLI as a Service using Ansible
118-
119-
This section describes how to deploy CodeCarbon as a system service
120-
using Ansible automation.
121-
122-
It automate the manual installation done in the previous chapter.
123-
124-
### What the Playbook Does
125-
126-
The Ansible playbook automates the following tasks:
127-
128-
- Creates a dedicated system user and group for CodeCarbon
129-
- Sets up a Python virtual environment
130-
- Installs CodeCarbon package
131-
- Configures RAPL permissions for power measurements
132-
- Creates and configures the systemd service
133-
- Sets up the CodeCarbon configuration file
134-
- Starts and enables the service
135-
136-
### Prerequisites
137-
138-
- Ansible installed on your machine
139-
- Debian-based target system(s)
140-
- SSH access to target system(s)
141-
- CodeCarbon API credentials from the dashboard
142-
143-
### Directory Structure
144-
145-
``` text
146-
codecarbon/deploy/ansible/codecarbon_cli_as_a_service/
147-
├── hosts
148-
├── tasks
149-
│ ├── install_codecarbon.yml
150-
│ ├── main.yml
151-
│ ├── rapl.yml
152-
│ └── systemd_service.yml
153-
├── templates
154-
│ ├── codecarbon.config.j2
155-
│ └── systemd_service.j2
156-
└── vars
157-
└── main.yml
158-
```
159-
160-
### Quick Start
161-
162-
1. Set the the target to install in `hosts`:
163-
164-
``` text
165-
yourservername.yourdomain.com hostname=yourservername ansible_user=root ansible_ssh_private_key_file=~/.ssh/id_ed25519
166-
```
167-
168-
2. Update the variables in `vars/main.yml` with your configuration:
169-
170-
``` yaml
171-
organization_id: your_org_id
172-
project_id: your_project_id
173-
experiment_id: your_experiment_id
174-
api_key: your_api_key
175-
```
176-
177-
3. Run the playbook:
178-
179-
``` bash
180-
ansible-playbook -i hosts tasks/main.yml
181-
```
113+
<https://dashboard.codecarbon.io/>.

‎docs/introduction/power_estimation.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ While energy is the metric primarily responsible for CO₂ emissions estimations
77
## 1. Energy as the Source of Truth
88

99
The most accurate tracking methods rely on built-in hardware energy counters rather than instantaneous power draw. For example:
10+
1011
- **NVIDIA GPUs** using `nvmlDeviceGetTotalEnergyConsumption` return accumulated energy in millijoules.
1112
- **AMD GPUs** using `amdsmi_get_energy_count` yield a counter that is multiplied by its resolution and converted into millijoules.
1213
- **CPUs** using the RAPL interface read from files like `energy_uj` to get accumulated microjoules.
@@ -40,6 +41,7 @@ The tracker has designated logic blocks for different components (e.g., CPU, RAM
4041
Inside the main `EmissionsTracker`, the energy values are securely accumulated over the session's lifespan.
4142

4243
For recording the power, a running sum is maintained:
44+
4345
- As CodeCarbon sequentially takes measurements, it tracks the output of `power.W`.
4446
- It dynamically increments running variables like `_gpu_power_sum`, `_cpu_power_sum`, `_ram_power_sum`.
4547
- It increments a global counter `_power_measurement_count`.
@@ -53,6 +55,7 @@ This smoothing process prevents singular short measurement anomalies from skewin
5355
## Summary Pipeline
5456

5557
In short:
58+
5659
1. **Hardware Counters (Accumulated Energy)**
5760
2. Subtract `last_energy` = **Energy Delta**
5861
3. Divide Energy Delta by `last_duration` = **Interval Average Power**

‎mkdocs.yml‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,7 @@ nav:
113113
- Motivation: introduction/motivation.md
114114
- Methodology: introduction/methodology.md
115115
- RAPL Metrics: introduction/rapl.md
116+
- Power Estimation: introduction/power_estimation.md
116117
- Model Comparisons: introduction/model_examples.md
117118
- Frequently Asked Questions: introduction/faq.md
118119
- Getting Started:
@@ -121,9 +122,12 @@ nav:
121122
- CodeCarbon API: getting-started/api.md
122123
- Parameters: getting-started/parameters.md
123124
- Examples: getting-started/examples.md
124-
- Comet Integration: getting-started/comet.md
125-
- Advanced Installation: getting-started/advanced_installation.md
126125
- Test on Scaleway: getting-started/test_on_scaleway.md
126+
- Advanced Usage:
127+
- Install CodeCarbon as a Linux service: advanced/linux_service.md
128+
- Deploy with Ansible: advanced/ansible.md
129+
- Comet Integration: getting-started/comet.md
130+
- ROCm and PyTorch on SLURM SuperComputer: advanced/adastra.md
127131
- Logging:
128132
- Output: logging/output.md
129133
- Collecting emissions to a logger: logging/to_logger.md

0 commit comments

Comments
 (0)