codecarbon 3.3.1__tar.gz → 3.3.2__tar.gz

{codecarbon-3.3.1 → codecarbon-3.3.2}/PKG-INFO

@@ -1,6 +1,7 @@
 Metadata-Version: 2.4
 Name: codecarbon
-Version: 3.3.1
+Version: 3.3.2
+Summary: Track and reduce the CO2 emissions of your computing
 Author: Mila, DataForGood, BCG GAMMA, Comet.ml, Haverford College
 License-Expression: MIT
 Project-URL: Homepage, https://codecarbon.io/
@@ -9,12 +10,25 @@ Project-URL: Dashboard, http://dashboard.codecarbon.io/
 Project-URL: Documentation, https://docs.codecarbon.io/
 Project-URL: Issues, https://github.com/mlco2/codecarbon/issues
 Project-URL: Changelog, https://github.com/mlco2/codecarbon/releases
+Keywords: carbon,co2,emissions,carbon-footprint,sustainability,green-ai,green-computing,energy,energy-consumption,power-consumption,rapl,gpu,machine-learning,mlops,monitoring
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: System Administrators
 Classifier: Natural Language :: English
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Benchmark
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE

codecarbon-3.3.2/codecarbon/_version.py

@@ -0,0 +1 @@
+__version__ = "3.3.2"

{codecarbon-3.3.1 → codecarbon-3.3.2}/codecarbon/cli/main.py

@@ -393,6 +393,10 @@ def _external_config() -> dict:
 )
 def monitor(
     ctx: typer.Context,
+    project_name: Annotated[
+        str,
+        typer.Option(help="Project name for the current experiment."),
+    ] = None,
     measure_power_secs: Annotated[
         int,
         typer.Option(help="Interval between two measures."),
@@ -427,6 +431,7 @@ def monitor(
     # Only the options actually given are forwarded: the others are left to the
     # tracker, which resolves them from the configuration file and environment.
     cli_defaults = (
+        ("project_name", project_name),
         ("measure_power_secs", measure_power_secs),
         ("api_call_interval", api_call_interval),
         ("log_level", log_level),

{codecarbon-3.3.1 → codecarbon-3.3.2}/codecarbon/cli/monitor.py

@@ -120,13 +120,12 @@ def run_and_monitor(
         else:
             print("   Emissions: N/A")
 
-        # Show where the data was saved
-        if hasattr(tracker, "_conf") and "output_file" in tracker._conf:
-            output_path = tracker._conf["output_file"]
-            # Make it absolute if it's relative
-            if not os.path.isabs(output_path):
-                output_path = os.path.abspath(output_path)
-            print(f"   Saved to: {output_path}")
+        # Show where the data was saved, asking the output handlers themselves
+        # so the path stays right whatever `output_dir` / `output_file` are.
+        for handler in getattr(tracker, "_output_handlers", []):
+            save_file_path = getattr(handler, "save_file_path", None)
+            if save_file_path:
+                print(f"   Saved to: {os.path.abspath(save_file_path)}")
 
         print("   ⚠️  Note: Tracked the command process and its children")
         print("=" * 60)

{codecarbon-3.3.1 → codecarbon-3.3.2}/codecarbon/core/cpu.py

@@ -33,6 +33,13 @@ if TYPE_CHECKING:
 # default W value per core for a CPU if no model is found in the ref csv
 DEFAULT_POWER_PER_CORE = 4
 
+_TROUBLESHOOTING_URL = "https://docs.codecarbon.io/latest/how-to/troubleshooting/"
+RAPL_PERMISSION_HELP = (
+    "You can grant read permission with: sudo chmod -R a+r /sys/class/powercap/* "
+    "(this does not persist across reboots, see "
+    f"{_TROUBLESHOOTING_URL}#rapl-permission-denied for a permanent setup)"
+)
+
 
 @lru_cache(maxsize=1)
 def is_powergadget_available() -> bool:
@@ -180,18 +187,16 @@ def _create_warn_function():
         nonlocal already_warned
         if not already_warned:
             logger.warning(
-                "\tRAPL - Permission denied reading RAPL file %s. "
-                "You can grant read permission with: "
-                "sudo chmod -R a+r /sys/class/powercap/*",
+                "\tRAPL - Permission denied reading RAPL file %s. %s",
                 energy_path,
+                RAPL_PERMISSION_HELP,
             )
             already_warned = True
         else:
             logger.debug(
-                "\tRAPL - Permission denied reading RAPL file %s. "
-                "You can grant read permission with: "
-                "sudo chmod -R a+r /sys/class/powercap/*",
+                "\tRAPL - Permission denied reading RAPL file %s. %s",
                 energy_path,
+                RAPL_PERMISSION_HELP,
             )
 
     return warn_permission_denied
@@ -253,6 +258,24 @@ def is_psutil_available():
         return False
 
 
+def is_raspberry() -> bool:
+    """
+    Check if the Raspberry Pi PMIC power readings are available.
+
+    `vcgencmd` ships with every Raspberry Pi OS, but only the Pi 5 answers
+    `pmic_read_adc`: older boards fall back to the TDP of their CPU.
+    """
+    if not os.path.exists("/usr/bin/vcgencmd"):
+        return False
+    try:
+        res = subprocess.run(
+            ["vcgencmd", "pmic_read_adc"], capture_output=True, timeout=5
+        )
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return res.returncode == 0 and b"volt(" in res.stdout
+
+
 class IntelPowerGadget:
     """
     A class to interface with Intel Power Gadget for monitoring CPU power consumption on Windows and (non-Apple Silicon) macOS.
@@ -489,7 +512,7 @@ class IntelRAPL:
         """Scan subdirectories of a RAPL entry for domain directories."""
         subdirs = []
         try:
-            for sub in os.listdir(entry_path):
+            for sub in sorted(os.listdir(entry_path)):
                 sub_path = os.path.join(entry_path, sub)
                 if ":" in sub and os.path.isdir(sub_path):
                     if os.path.exists(os.path.join(sub_path, "energy_uj")):
@@ -508,7 +531,7 @@ class IntelRAPL:
         """Scan a base directory for intel-rapl entries."""
         domain_dirs = []
         try:
-            for entry in os.listdir(base):
+            for entry in sorted(os.listdir(base)):
                 if not entry.startswith("intel-rapl"):
                     continue
                 entry_path = os.path.join(base, entry)
@@ -537,7 +560,7 @@ class IntelRAPL:
         if domain_dirs:
             return domain_dirs
         try:
-            for item in os.listdir(self._lin_rapl_dir):
+            for item in sorted(os.listdir(self._lin_rapl_dir)):
                 if ":" in item:
                     path = os.path.join(self._lin_rapl_dir, item)
                     if os.path.isdir(path) and os.path.exists(
@@ -592,8 +615,7 @@ class IntelRAPL:
             return True, is_required_main
         except PermissionError:
             msg = f"\tRAPL - Permission denied reading RAPL file {rapl_file}."
-            suggestion = "You can grant read permission with: sudo chmod -R a+r /sys/class/powercap/*"
-            logger.warning("%s %s; skipping.", msg, suggestion)
+            logger.warning("%s %s; skipping.", msg, RAPL_PERMISSION_HELP)
             return False, False
         except Exception as e:
             logger.debug(
@@ -893,6 +915,7 @@ class IntelRAPL:
             (rapl_file.path, float(rapl_file.last_energy))
             for rapl_file in self._rapl_files
             if "dram" not in rapl_file.name.lower()
+            and rapl_file.last_energy is not None
         ]
         self._mirrored_candidates = find_mirrored_counters(
             counters, SEQUENTIAL_READ_TOLERANCE_KWH
@@ -928,7 +951,10 @@ class IntelRAPL:
                 continue
             delta = float(rapl_file.energy_delta)
             reference_delta = float(reference.energy_delta)
-            if delta <= 0 and reference_delta <= 0:
+            if rapl_file.sample_skipped or reference.sample_skipped:
+                # A skipped sample reports no energy: the interval is not conclusive
+                pending[path] = reference_path
+            elif delta <= 0 and reference_delta <= 0:
                 # Nothing was accumulated: the interval is not conclusive
                 pending[path] = reference_path
             elif counters_match(delta, reference_delta, SEQUENTIAL_READ_TOLERANCE_KWH):
@@ -1088,9 +1114,10 @@ class TDP:
                 )
                 return cpu_model_detected, power
             logger.warning(
-                "We saw that you have a %s but we don't know it."
-                + " Please contact us.",
+                "We saw that you have a %s but we don't know it. "
+                "Please help us add it, see %s#unknown-cpu-model",
                 cpu_model_detected,
+                _TROUBLESHOOTING_URL,
             )
             if is_psutil_available():
                 # Count thread of the CPU

codecarbon-3.3.2/codecarbon/core/electricitymaps_api.py

@@ -0,0 +1,152 @@
+import threading
+import time
+from typing import Any, Dict, Tuple
+
+import requests
+
+from codecarbon.core.units import EmissionsPerKWh, Energy
+from codecarbon.external.geography import GeoMetadata
+from codecarbon.external.logger import logger
+
+_Key = Tuple[Tuple[Tuple[str, Any], ...], str]
+
+URL: str = "https://api.electricitymaps.com/v3/carbon-intensity/latest"
+# Kept short: the lookup runs on the measurement thread, which stop() joins.
+ELECTRICITYMAPS_API_TIMEOUT: int = 10
+
+# Grid carbon intensity is published hourly at best, while emissions are computed
+# on every measurement tick, so the value is cached instead of refetched.
+ELECTRICITYMAPS_CACHE_TTL: int = 60
+# After a failure (bad token, network down), wait before retrying instead of
+# issuing one doomed request per measurement tick. The wait doubles on each
+# consecutive failure, up to the maximum, and resets on success.
+ELECTRICITYMAPS_COOLDOWN: int = 30
+ELECTRICITYMAPS_MAX_COOLDOWN: int = 3600
+
+# {(sorted query params, token): (monotonic fetch time, intensity in gCO2e/kWh)}
+_cache: Dict[_Key, Tuple[float, float]] = {}
+# {cache key: (monotonic time until which requests are skipped, cooldown length)}
+# Keyed like the cache: one tracker's bad token must not block another's good one.
+_cooldown: Dict[_Key, Tuple[float, float]] = {}
+# The state above is read-modify-written from the measurement thread.
+_lock = threading.Lock()
+
+
+def reset_cache() -> None:
+    """Drop the cached carbon intensities and any pending failure cooldown."""
+    with _lock:
+        _cache.clear()
+        _cooldown.clear()
+
+
+def _start_cooldown(key: _Key) -> None:
+    with _lock:
+        previous = _cooldown.get(key, (0.0, 0.0))[1]
+        delay = min(
+            max(previous * 2, ELECTRICITYMAPS_COOLDOWN), ELECTRICITYMAPS_MAX_COOLDOWN
+        )
+        _cooldown[key] = (time.monotonic() + delay, delay)
+
+
+def get_carbon_intensity(
+    geo: GeoMetadata, electricitymaps_api_token: str = ""
+) -> float:
+    """
+    Retrieve the carbon intensity of the grid, in gCO2e/kWh, from the Electricity
+    Maps API (formerly CO2 Signal) for the given geographic location.
+
+    Raises:
+        ElectricityMapsAPIError: the request failed, returned an error, or was
+            skipped because a previous one failed (``...CooldownError``).
+    """
+    if geo.latitude is not None:
+        params: Dict[str, Any] = {"lat": geo.latitude, "lon": geo.longitude}
+    else:
+        params = {"countryCode": geo.country_2letter_iso_code}
+    key = (tuple(sorted(params.items())), electricitymaps_api_token)
+    with _lock:
+        cached = _cache.get(key)
+        cooldown_until = _cooldown.get(key, (0.0, 0.0))[0]
+    if cached and time.monotonic() - cached[0] <= ELECTRICITYMAPS_CACHE_TTL:
+        logger.debug(
+            f"electricitymaps_api: using cached carbon intensity {cached[1]} gCO2e/kWh"
+        )
+        return cached[1]
+
+    remaining = cooldown_until - time.monotonic()
+    if remaining > 0:
+        raise ElectricityMapsAPICooldownError(
+            "Electricity Maps API is in cooldown after a previous failure, "
+            f"retrying in {remaining:.0f} seconds"
+        )
+
+    try:
+        resp = requests.get(
+            URL,
+            params=params,
+            headers={"auth-token": electricitymaps_api_token},
+            timeout=ELECTRICITYMAPS_API_TIMEOUT,
+        )
+        if resp.status_code != 200:
+            try:
+                body = resp.json()
+            except ValueError:
+                body = {}
+            raise ElectricityMapsAPIError(
+                body.get("error") or body.get("message") or resp.text
+            )
+        # API v3 response structure: carbonIntensity is at the root level
+        carbon_intensity_g_per_kWh = resp.json().get("carbonIntensity")
+        if carbon_intensity_g_per_kWh is None:
+            raise ElectricityMapsAPIError("No carbonIntensity data in response")
+    except Exception:
+        _start_cooldown(key)
+        raise
+
+    with _lock:
+        _cache[key] = (time.monotonic(), carbon_intensity_g_per_kWh)
+        _cooldown.pop(key, None)
+    return carbon_intensity_g_per_kWh
+
+
+def get_emissions(
+    energy: Energy, geo: GeoMetadata, electricitymaps_api_token: str = ""
+) -> float:
+    """
+    Calculate the CO2 emissions based on energy consumption and geographic location.
+
+    This function retrieves the carbon intensity (in grams of CO2 per kWh) from the
+    Electricity Maps API (formerly CO2 Signal) based on the geographic location provided.
+    It then calculates the total CO2 emissions for a given amount of energy consumption.
+
+    Args:
+        energy (Energy):
+            An object representing the energy consumption in kilowatt-hours (kWh).
+        geo (GeoMetadata):
+            Geographic metadata, including either latitude/longitude
+            or a country code.
+        electricitymaps_api_token (str, optional):
+            The API token for authenticating with the Electricity Maps API (default is an empty string).
+
+    Returns:
+        float:
+            The total CO2 emissions in kilograms based on the provided energy consumption and
+            carbon intensity of the specified geographic location.
+
+    Raises:
+        ElectricityMapsAPIError:
+            If the Electricity Maps API request fails or returns an error.
+    """
+    carbon_intensity_g_per_kWh = get_carbon_intensity(geo, electricitymaps_api_token)
+    emissions_per_kWh: EmissionsPerKWh = EmissionsPerKWh.from_g_per_kWh(
+        carbon_intensity_g_per_kWh
+    )
+    return emissions_per_kWh.kgs_per_kWh * energy.kWh
+
+
+class ElectricityMapsAPIError(Exception):
+    pass
+
+
+class ElectricityMapsAPICooldownError(ElectricityMapsAPIError):
+    """Raised when a request is skipped because a previous one failed."""

{codecarbon-3.3.1 → codecarbon-3.3.2}/codecarbon/core/emissions.py

@@ -6,6 +6,7 @@ https://github.com/mlco2/impact
 https://github.com/responsibleproblemsolving/energy-usage
 """
 
+import re
 from typing import TYPE_CHECKING, Dict, Optional
 
 from codecarbon.core import electricitymaps_api
@@ -23,6 +24,10 @@ _NORDIC_REGIONS_BY_COUNTRY = {
     "FIN": {"FI"},
 }
 
+_CHINA_REGION_SUFFIX = re.compile(
+    r"\s+(autonomous region|municipality|province|sheng|shi|zizhiqu)$"
+)
+
 
 class Emissions:
     def __init__(
@@ -169,6 +174,13 @@ class Emissions:
                     + f"Retrieved emissions for {geo.country_name} using Electricity Maps API :{emissions * 1000} g CO2eq"
                 )
                 return emissions
+            except electricitymaps_api.ElectricityMapsAPICooldownError as e:
+                # The failure that started the cooldown was already logged.
+                logger.debug(
+                    "electricitymaps_api.get_emissions: "
+                    + str(e)
+                    + " >>> Using CodeCarbon's data."
+                )
             except Exception as e:
                 logger.error(
                     "electricitymaps_api.get_emissions: "
@@ -180,7 +192,8 @@ class Emissions:
             geo.country_iso_code.upper() if geo.country_iso_code is not None else None
         )
         compute_with_regional_data: bool = (geo.region is not None) and (
-            country_iso_code in ["USA", "CAN"] or self._is_supported_nordic_region(geo)
+            country_iso_code in ["USA", "CAN", "CHN"]
+            or self._is_supported_nordic_region(geo)
         )
 
         if compute_with_regional_data:
@@ -231,6 +244,30 @@ class Emissions:
         )
         return geo.region.upper() in country_regions
 
+    def _try_get_china_province_emissions(
+        self, energy: Energy, geo: GeoMetadata
+    ) -> Optional[float]:
+        """
+        Computes emissions with the official 2023 MEE/NBS provincial factor.
+        Returns None if the province is unknown or not published (Tibet,
+        Hong Kong, Macao and Taiwan), so the caller uses the national value.
+        """
+        if geo.region is None:
+            return None
+
+        name = _CHINA_REGION_SUFFIX.sub("", " ".join(geo.region.lower().split()))
+        china_data = self._data_source.get_china_provincial_emissions_data()
+        for province, province_data in china_data["data"].items():
+            if name in province_data["names"]:
+                emission_factor_g = province_data["emission_factor"]
+                emissions = emission_factor_g / 1000 * energy.kWh
+                logger.debug(
+                    f"China province {province}: Retrieved emissions using static factor "
+                    + f"{emission_factor_g} gCO2/kWh: {emissions * 1000} g CO2"
+                )
+                return emissions
+        return None
+
     def get_region_emissions(self, energy: Energy, geo: GeoMetadata) -> float:
         """
         Computes emissions for a region on private infra.
@@ -240,10 +277,11 @@ class Emissions:
 
         get_private_infra_emissions
         ├─ Electricity Maps API (si token)
-        ├─ get_region_emissions (USA/CAN/SWE/NOR/FIN)
+        ├─ get_region_emissions (USA/CAN/CHN/SWE/NOR/FIN)
         │   └─ _try_get_nordic_region_emissions (pour SWE/NOR/FIN)
         │   └─ country_emissions_data (pour USA)
         │   └─ country_energy_mix_data (pour CAN)
+        │   └─ _try_get_china_province_emissions (pour CHN)
         └─ get_country_emissions (fallback)
 
         :param energy: Mean power consumption of the process (kWh)
@@ -260,6 +298,13 @@ class Emissions:
         ):
             return self.get_country_emissions(energy, geo)
 
+        # Handle China provinces (official MEE/NBS factors)
+        if geo.country_iso_code is not None and geo.country_iso_code.upper() == "CHN":
+            china_emissions = self._try_get_china_province_emissions(energy, geo)
+            if china_emissions is not None:
+                return china_emissions
+            return self.get_country_emissions(energy, geo)
+
         # Handle USA and Canada regional data
         try:
             country_emissions_data = self._data_source.get_country_emissions_data(
@@ -335,7 +380,7 @@ class Emissions:
             in Kgs.CO2 / kWh
         """
         # If we have the chance to have the carbon intensity for this country
-        if energy_mix.get("carbon_intensity"):
+        if energy_mix.get("carbon_intensity") is not None:
             return EmissionsPerKWh.from_g_per_kWh(energy_mix.get("carbon_intensity"))
 
         # Else we compute it from the energy mix.
@@ -353,7 +398,7 @@ class Emissions:
                 carbon_intensity_for_type = carbon_intensity_per_source.get(
                     energy_type[: -len("_TWh")]
                 )
-                if carbon_intensity_for_type:  # to ignore "total_TWh"
+                if carbon_intensity_for_type is not None:  # to ignore "total_TWh"
                     carbon_intensity += (
                         energy_per_year / energy_sum
                     ) * carbon_intensity_for_type

{codecarbon-3.3.1 → codecarbon-3.3.2}/codecarbon/core/gpu.py

@@ -1,4 +1,4 @@
-from typing import List
+from typing import Iterable, List, Optional
 
 from codecarbon.core import gpu_amd, gpu_nvidia
 from codecarbon.core.gpu_device import GPUDevice
@@ -154,6 +154,18 @@ class AllGPUDevices:
             logger.warning("Failed to retrieve gpu utilization", exc_info=True)
             return []
 
+    def sample_power(self, gpu_ids: Optional[Iterable[int]] = None) -> None:
+        """Record a power reading for devices without a usable energy
+        counter, called from the tracker's 1s monitoring loop.
+        :param gpu_ids: indexes of the tracked GPUs, all of them if None."""
+        for device in self.devices:
+            if gpu_ids is not None and device.gpu_index not in gpu_ids:
+                continue
+            try:
+                device.sample_power()
+            except Exception:
+                logger.debug("Failed to sample gpu power", exc_info=True)
+
     def get_delta(self, last_duration: Time) -> List:
         """Get difference since last time this function was called
         >>> get_delta()

{codecarbon-3.3.1 → codecarbon-3.3.2}/codecarbon/core/gpu_amd.py

@@ -62,6 +62,11 @@ class AMDGPUDevice(GPUDevice):
             self._gpu_name
         )
 
+    def _reports_zero_power_by_design(self) -> bool:
+        # The second GCD of a dual-GCD device reports 0, its power is
+        # included in the first GCD's reading.
+        return self._known_zero_energy_counter and self.gpu_index % 2 == 1
+
     def emit_selection_warning(self) -> None:
         if not self._known_zero_energy_counter:
             return
@@ -124,7 +129,8 @@ class AMDGPUDevice(GPUDevice):
             elif "power" in energy_count:
                 energy_key = "power"
             if energy_key is None:
-                logger.warning(
+                self._counter_error = "amdsmi_get_energy_count has no energy counter"
+                logger.debug(
                     f"Neither 'energy_accumulator' nor 'power' found in energy_count: {energy_count}"
                 )
                 return None
@@ -139,14 +145,16 @@ class AMDGPUDevice(GPUDevice):
                 if counter_value == 0:
                     if getattr(self, "_known_zero_energy_counter", False):
                         return 0
+                    self._counter_error = "energy counter reads 0"
                     return None
 
             # energy_in_µJ = counter_value * resolution_in_µJ
             # Divide by 1000 to convert µJ to mJ
             energy_mj = counter_value * counter_resolution_uj / 1000
             return energy_mj
-        except Exception:
-            logger.warning(
+        except Exception as e:
+            self._counter_error = repr(e)
+            logger.debug(
                 "Failed to retrieve AMD GPU total energy consumption", exc_info=True
             )
             return None