codecarbon 2.6.0__tar.gz → 2.7.1__tar.gz

{codecarbon-2.6.0 → codecarbon-2.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: codecarbon
-Version: 2.6.0
+Version: 2.7.1
 Project-URL: Homepage, https://codecarbon.io/
 Project-URL: Repository, https://github.com/mlco2/codecarbon
 Project-URL: Dashboard, http://dashboard.codecarbon.io/

codecarbon-2.7.1/codecarbon/_version.py

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

{codecarbon-2.6.0 → codecarbon-2.7.1}/codecarbon/core/api_client.py

@@ -8,7 +8,6 @@ TODO : use async call to API
 # from httpx import AsyncClient
 import dataclasses
 import json
-import time
 from datetime import timedelta, tzinfo
 
 import arrow
@@ -37,7 +36,6 @@ class ApiClient:  # (AsyncClient)
     """
 
     run_id = None
-    _previous_call = time.time()
 
     def __init__(
         self,
@@ -167,7 +165,6 @@ class ApiClient:  # (AsyncClient)
 
     def add_emission(self, carbon_emission: dict):
         assert self.experiment_id is not None
-        self._previous_call = time.time()
         if self.run_id is None:
             # TODO : raise an Exception ?
             logger.debug(

codecarbon-2.7.1/codecarbon/core/co2_signal.py

@@ -0,0 +1,62 @@
+from typing import Any, Dict
+
+import requests
+
+from codecarbon.core.units import EmissionsPerKWh, Energy
+from codecarbon.external.geography import GeoMetadata
+
+URL: str = "https://api.co2signal.com/v1/latest"
+CO2_SIGNAL_API_TIMEOUT: int = 30
+
+
+def get_emissions(
+    energy: Energy, geo: GeoMetadata, co2_signal_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 CO2
+    Signal API 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.
+        co2_signal_api_token (str, optional):
+            The API token for authenticating with the CO2 Signal 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:
+        CO2SignalAPIError:
+            If the CO2 Signal API request fails or returns an error.
+    """
+    params: Dict[str, Any]
+    if geo.latitude:
+        params = {"lat": geo.latitude, "lon": geo.longitude}
+    else:
+        params = {"countryCode": geo.country_2letter_iso_code}
+    resp = requests.get(
+        URL,
+        params=params,
+        headers={"auth-token": co2_signal_api_token},
+        timeout=CO2_SIGNAL_API_TIMEOUT,
+    )
+    if resp.status_code != 200:
+        message = resp.json().get("error") or resp.json().get("message")
+        raise CO2SignalAPIError(message)
+    carbon_intensity_g_per_kWh = resp.json()["data"]["carbonIntensity"]
+    emissions_per_kWh: EmissionsPerKWh = EmissionsPerKWh.from_g_per_kWh(
+        carbon_intensity_g_per_kWh
+    )
+    return emissions_per_kWh.kgs_per_kWh * energy.kWh
+
+
+class CO2SignalAPIError(Exception):
+    pass

{codecarbon-2.6.0 → codecarbon-2.7.1}/codecarbon/core/cpu.py

@@ -21,30 +21,60 @@ from codecarbon.input import DataSource
 
 
 def is_powergadget_available() -> bool:
+    """
+    Checks if Intel Power Gadget is available on the system.
+
+    Returns:
+        bool: `True` if Intel Power Gadget is available, `False` otherwise.
+    """
     try:
         IntelPowerGadget()
         return True
     except Exception as e:
         logger.debug(
-            "Not using PowerGadget, an exception occurred while instantiating"
-            + f" IntelPowerGadget : {e}",
+            "Not using PowerGadget, an exception occurred while instantiating "
+            + "IntelPowerGadget : %s",
+            e,
         )
         return False
 
 
 def is_rapl_available() -> bool:
+    """
+    Checks if Intel RAPL is available on the system.
+
+    Returns:
+        bool: `True` if Intel RAPL is available, `False` otherwise.
+    """
     try:
         IntelRAPL()
         return True
     except Exception as e:
         logger.debug(
             "Not using the RAPL interface, an exception occurred while instantiating "
-            + f"IntelRAPL : {e}",
+            + "IntelRAPL : %s",
+            e,
         )
         return False
 
 
 class IntelPowerGadget:
+    """
+    A class to interface with Intel Power Gadget for monitoring CPU power consumption on Windows and (non-Apple Silicon) macOS.
+
+    This class provides methods to set up and execute Intel Power Gadget's command-line interface (CLI) to
+    log power consumption data over a specified duration and resolution. It also includes functionality to
+    read and process the logged data to extract CPU power details.
+
+    Methods:
+        start():
+            Placeholder method for starting the Intel Power Gadget monitoring.
+
+        get_cpu_details() -> Dict:
+            Fetches the CPU power details by reading the values from the logged CSV file.
+
+    """
+
     _osx_exec = "PowerLog"
     _osx_exec_backup = "/Applications/Intel Power Gadget/PowerLog"
     _windows_exec = "PowerLog3.0.exe"
@@ -60,6 +90,7 @@ class IntelPowerGadget:
         self._system = sys.platform.lower()
         self._duration = duration
         self._resolution = resolution
+        self._windows_exec_backup = None
         self._setup_cli()
 
     def _setup_cli(self) -> None:
@@ -142,16 +173,17 @@ class IntelPowerGadget:
         if returncode != 0:
             logger.warning(
                 "Returncode while logging power values using "
-                + f"Intel Power Gadget: {returncode}"
+                + "Intel Power Gadget: %s",
+                returncode,
             )
 
-    def get_cpu_details(self, **kwargs) -> Dict:
+    def get_cpu_details(self) -> Dict:
         """
         Fetches the CPU Power Details by fetching values from a logged csv file
         in _log_values function
         """
         self._log_values()
-        cpu_details = dict()
+        cpu_details = {}
         try:
             cpu_data = pd.read_csv(self._log_file_path).dropna()
             for col_name in cpu_data.columns:
@@ -164,23 +196,53 @@ class IntelPowerGadget:
         except Exception as e:
             logger.info(
                 f"Unable to read Intel Power Gadget logged file at {self._log_file_path}\n \
-                Exception occurred {e}",
+                Exception occurred %s",
+                e,
                 exc_info=True,
             )
         return cpu_details
 
-    def start(self):
+    def start(self) -> None:
+        """
+        Placeholder method for starting the Intel Power Gadget monitoring.
+        """
         # TODO: Read energy
-        pass
 
 
 class IntelRAPL:
+    """
+    A class to interface Intel's Running Average Power Limit (RAPL) for monitoring CPU power consumption.
+
+    This class provides methods to set up and read energy consumption data from Intel RAPL files,
+    which are available on Linux systems.
+    It enables the measurement of CPU energy usage over time and provides methods to fetch
+    both dynamic and static CPU energy details.
+
+    Attributes:
+        _lin_rapl_dir (str): The directory path where Intel RAPL files are located.
+        _system (str): The platform of the running system, typically used to ensure compatibility.
+        _rapl_files (List[RAPLFile]): A list of RAPLFile objects representing the files to read energy data from.
+        _cpu_details (Dict): A dictionary storing the latest CPU energy details.
+        _last_mesure (int): Placeholder for storing the last measurement time.
+
+    Methods:
+        start():
+            Starts monitoring CPU energy consumption.
+
+        get_cpu_details(duration: Time) -> Dict:
+            Fetches the CPU energy deltas over a specified duration by reading values from RAPL files.
+
+        get_static_cpu_details() -> Dict:
+            Returns the CPU details without recalculating them.
+
+    """
+
     def __init__(self, rapl_dir="/sys/class/powercap/intel-rapl"):
         self._lin_rapl_dir = rapl_dir
         self._system = sys.platform.lower()
-        self._rapl_files = list()
+        self._rapl_files = []
         self._setup_rapl()
-        self._cpu_details: Dict = dict()
+        self._cpu_details: Dict = {}
 
         self._last_mesure = 0
 
@@ -199,7 +261,7 @@ class IntelRAPL:
         else:
             raise SystemError("Platform not supported by Intel RAPL Interface")
 
-    def _fetch_rapl_files(self):
+    def _fetch_rapl_files(self) -> None:
         """
         Fetches RAPL files from the RAPL directory
         """
@@ -229,19 +291,20 @@ class IntelRAPL:
                     self._rapl_files.append(
                         RAPLFile(name=name, path=rapl_file, max_path=rapl_file_max)
                     )
-                    logger.debug(f"We will read Intel RAPL files at {rapl_file}")
+                    logger.debug("We will read Intel RAPL files at %s", rapl_file)
                 except PermissionError as e:
                     raise PermissionError(
                         "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"
-                        + f" for workarounds : {e}"
-                    )
+                        + " for workarounds : %s",
+                        e,
+                    ) from e
 
-    def get_cpu_details(self, duration: Time, **kwargs) -> Dict:
+    def get_cpu_details(self, duration: Time) -> Dict:
         """
         Fetches the CPU Energy Deltas by fetching values from RAPL files
         """
-        cpu_details = dict()
+        cpu_details = {}
         try:
             list(map(lambda rapl_file: rapl_file.delta(duration), self._rapl_files))
 
@@ -255,28 +318,50 @@ class IntelRAPL:
                     )
         except Exception as e:
             logger.info(
-                f"Unable to read Intel RAPL files at {self._rapl_files}\n \
-                Exception occurred {e}",
+                "Unable to read Intel RAPL files at %s\n \
+                Exception occurred %s",
+                self._rapl_files,
+                e,
                 exc_info=True,
             )
-        self.cpu_details = cpu_details
-        logger.debug(f"get_cpu_details {self.cpu_details}")
+        self._cpu_details = cpu_details
+        logger.debug("get_cpu_details %s", self._cpu_details)
         return cpu_details
 
     def get_static_cpu_details(self) -> Dict:
         """
         Return CPU details without computing them.
         """
-        logger.debug(f"get_static_cpu_details {self.cpu_details}")
+        logger.debug("get_static_cpu_details %s", self._cpu_details)
 
-        return self.cpu_details
+        return self._cpu_details
 
-    def start(self):
+    def start(self) -> None:
+        """
+        Starts monitoring CPU energy consumption.
+        """
         for rapl_file in self._rapl_files:
             rapl_file.start()
 
 
 class TDP:
+    """
+    Represents Thermal Design Power (TDP) for detecting and estimating
+    the power consumption of the CPU on a machine.
+
+    The class provides methods to identify the CPU model, match it with known TDP
+    values from a dataset, and return the corresponding power consumption in watts.
+
+    Attributes:
+        model (str): The detected CPU model name.
+        tdp (int): The TDP value of the detected CPU in watts.
+
+    Methods:
+        start():
+            Placeholder method to initiate TDP analysis.
+
+    """
+
     def __init__(self):
         self.model, self.tdp = self._main()
 
@@ -323,8 +408,8 @@ class TDP:
             THRESHOLD_TOKEN_SET defines the similarity ratio value to consider
             token_set matches (for more detail see fuzz.token_set_ratio).
         """
-        THRESHOLD_DIRECT = 100
-        THRESHOLD_TOKEN_SET = 100
+        THRESHOLD_DIRECT: int = 100
+        THRESHOLD_TOKEN_SET: int = 100
 
         direct_match = process.extractOne(
             model_raw,
@@ -372,12 +457,15 @@ class TDP:
 
             if power:
                 logger.debug(
-                    f"CPU : We detect a {cpu_model_detected} with a TDP of {power} W"
+                    "CPU : We detect a %s with a TDP of %s W",
+                    cpu_model_detected,
+                    power,
                 )
                 return cpu_model_detected, power
             logger.warning(
-                f"We saw that you have a {cpu_model_detected} but we don't know it."
-                + " Please contact us."
+                "We saw that you have a %s but we don't know it."
+                + " Please contact us.",
+                cpu_model_detected,
             )
             return cpu_model_detected, None
         logger.warning(

{codecarbon-2.6.0 → codecarbon-2.7.1}/codecarbon/core/gpu.py

@@ -1,4 +1,5 @@
 from dataclasses import dataclass, field
+from typing import Any, Dict, List, Union
 
 import pynvml
 
@@ -8,6 +9,22 @@ from codecarbon.external.logger import logger
 
 @dataclass
 class GPUDevice:
+    """
+    Represents a GPU device with associated energy and power metrics.
+
+    Attributes:
+        handle (any): An identifier for the GPU device.
+        gpu_index (int): The index of the GPU device in the system.
+        energy_delta (Energy): The amount of energy consumed by the GPU device
+            since the last measurement, expressed in kilowatt-hours (kWh).
+            Defaults to an initial value of 0 kWh.
+        power (Power): The current power consumption of the GPU device,
+            measured in watts (W). Defaults to an initial value of 0 W.
+        last_energy (Energy): The last recorded energy reading for the GPU
+            device, expressed in kilowatt-hours (kWh). This is used to
+            calculate `energy_delta`. Defaults to an initial value of 0 kWh.
+    """
+
     handle: any
     gpu_index: int
     # Energy consumed in kWh
@@ -17,14 +34,14 @@ class GPUDevice:
     # Last energy reading in kWh
     last_energy: Energy = field(default_factory=lambda: Energy(0))
 
-    def start(self):
+    def start(self) -> None:
         self.last_energy = self._get_energy_kwh()
 
-    def __post_init__(self):
+    def __post_init__(self) -> None:
         self.last_energy = self._get_energy_kwh()
         self._init_static_details()
 
-    def _get_energy_kwh(self):
+    def _get_energy_kwh(self) -> Energy:
         total_energy_consumption = self._get_total_energy_consumption()
         if total_energy_consumption is None:
             return self.last_energy
@@ -47,7 +64,7 @@ class GPUDevice:
             "power_usage": self.power,
         }
 
-    def get_static_details(self):
+    def get_static_details(self) -> Dict[str, Any]:
         return {
             "name": self._gpu_name,
             "uuid": self._uuid,
@@ -56,7 +73,7 @@ class GPUDevice:
             "gpu_index": self.gpu_index,
         }
 
-    def _init_static_details(self):
+    def _init_static_details(self) -> None:
         self._gpu_name = self._get_gpu_name()
         self._uuid = self._get_uuid()
         self._power_limit = self._get_power_limit()
@@ -64,7 +81,7 @@ class GPUDevice:
         memory = self._get_memory_info()
         self._total_memory = memory.total
 
-    def get_gpu_details(self):
+    def get_gpu_details(self) -> Dict[str, Any]:
         # Memory
         memory = self._get_memory_info()
 
@@ -85,13 +102,13 @@ class GPUDevice:
         }
         return device_details
 
-    def _to_utf8(self, str_or_bytes):
+    def _to_utf8(self, str_or_bytes) -> Any:
         if hasattr(str_or_bytes, "decode"):
             return str_or_bytes.decode("utf-8", errors="replace")
 
         return str_or_bytes
 
-    def _get_total_energy_consumption(self):
+    def _get_total_energy_consumption(self) -> int:
         """Returns total energy consumption for this GPU in millijoules (mJ) since the driver was last reloaded
         https://docs.nvidia.com/deploy/nvml-api/group__nvmlDeviceQueries.html#group__nvmlDeviceQueries_1g732ab899b5bd18ac4bfb93c02de4900a
         """
@@ -103,14 +120,14 @@ class GPUDevice:
             )
             return None
 
-    def _get_gpu_name(self):
+    def _get_gpu_name(self) -> Any:
         """Returns the name of the GPU device
         https://docs.nvidia.com/deploy/nvml-api/group__nvmlDeviceQueries.html#group__nvmlDeviceQueries_1ga5361803e044c6fdf3b08523fb6d1481
         """
         name = pynvml.nvmlDeviceGetName(self.handle)
         return self._to_utf8(name)
 
-    def _get_uuid(self):
+    def _get_uuid(self) -> Any:
         """Returns the globally unique GPU device UUID
         https://docs.nvidia.com/deploy/nvml-api/group__nvmlDeviceQueries.html#group__nvmlDeviceQueries_1g72710fb20f30f0c2725ce31579832654
         """
@@ -123,19 +140,19 @@ class GPUDevice:
         """
         return pynvml.nvmlDeviceGetMemoryInfo(self.handle)
 
-    def _get_temperature(self):
+    def _get_temperature(self) -> int:
         """Returns degrees in the Celsius scale
         https://docs.nvidia.com/deploy/nvml-api/group__nvmlDeviceQueries.html#group__nvmlDeviceQueries_1g92d1c5182a14dd4be7090e3c1480b121
         """
         return pynvml.nvmlDeviceGetTemperature(self.handle, pynvml.NVML_TEMPERATURE_GPU)
 
-    def _get_power_usage(self):
+    def _get_power_usage(self) -> int:
         """Returns power usage in milliwatts
         https://docs.nvidia.com/deploy/nvml-api/group__nvmlDeviceQueries.html#group__nvmlDeviceQueries_1g7ef7dff0ff14238d08a19ad7fb23fc87
         """
         return pynvml.nvmlDeviceGetPowerUsage(self.handle)
 
-    def _get_power_limit(self):
+    def _get_power_limit(self) -> Union[int, None]:
         """Returns max power usage in milliwatts
         https://docs.nvidia.com/deploy/nvml-api/group__nvmlDeviceQueries.html#group__nvmlDeviceQueries_1g263b5bf552d5ec7fcd29a088264d10ad
         """
@@ -150,13 +167,13 @@ class GPUDevice:
         """
         return pynvml.nvmlDeviceGetUtilizationRates(self.handle).gpu
 
-    def _get_compute_mode(self):
+    def _get_compute_mode(self) -> int:
         """Returns the compute mode of the GPU
         https://docs.nvidia.com/deploy/nvml-api/group__nvmlDeviceEnumvs.html#group__nvmlDeviceEnumvs_1gbed1b88f2e3ba39070d31d1db4340233
         """
         return pynvml.nvmlDeviceGetComputeMode(self.handle)
 
-    def _get_compute_processes(self):
+    def _get_compute_processes(self) -> List:
         """Returns the list of processes ids having a compute context on the
         device with the memory used
         https://docs.nvidia.com/deploy/nvml-api/group__nvmlDeviceQueries.html#group__nvmlDeviceQueries_1g46ceaea624d5c96e098e03c453419d68
@@ -168,7 +185,7 @@ class GPUDevice:
         except pynvml.NVMLError:
             return []
 
-    def _get_graphics_processes(self):
+    def _get_graphics_processes(self) -> List:
         """Returns the list of processes ids having a graphics context on the
         device with the memory used
         https://docs.nvidia.com/deploy/nvml-api/group__nvmlDeviceQueries.html#group__nvmlDeviceQueries_1g7eacf7fa7ba4f4485d166736bf31195e
@@ -182,7 +199,7 @@ class GPUDevice:
 
 
 class AllGPUDevices:
-    def __init__(self):
+    def __init__(self) -> None:
         if is_gpu_details_available():
             logger.debug("GPU available. Starting setup")
             self.device_count = pynvml.nvmlDeviceGetCount()
@@ -195,7 +212,7 @@ class AllGPUDevices:
             gpu_device = GPUDevice(handle=handle, gpu_index=i)
             self.devices.append(gpu_device)
 
-    def get_gpu_static_info(self):
+    def get_gpu_static_info(self) -> List:
         """Get all GPUs static information.
         >>> get_gpu_static_info()
         [
@@ -219,7 +236,7 @@ class AllGPUDevices:
             logger.warning("Failed to retrieve gpu static info", exc_info=True)
             return []
 
-    def get_gpu_details(self):
+    def get_gpu_details(self) -> List:
         """Get all GPUs instantaneous metrics
         >>> get_gpu_details()
         [
@@ -251,7 +268,7 @@ class AllGPUDevices:
             logger.warning("Failed to retrieve gpu information", exc_info=True)
             return []
 
-    def get_delta(self, last_duration: Time):
+    def get_delta(self, last_duration: Time) -> List:
         """Get difference since last time this function was called
         >>> get_delta()
         [
@@ -275,7 +292,7 @@ class AllGPUDevices:
             return []
 
 
-def is_gpu_details_available():
+def is_gpu_details_available() -> bool:
     """Returns True if the GPU details are available."""
     try:
         pynvml.nvmlInit()

{codecarbon-2.6.0 → codecarbon-2.7.1}/codecarbon/core/measure.py

@@ -1,4 +1,4 @@
-from time import time
+from time import perf_counter
 
 from codecarbon.external.hardware import CPU, GPU, RAM, AppleSiliconChip
 from codecarbon.external.logger import logger
@@ -25,7 +25,7 @@ class MeasurePowerEnergy:
         :param hardware: list of hardware components to measure
         :param pue: Power Usage Effectiveness of the datacenter
         """
-        self._last_measured_time = time()
+        self._last_measured_time = perf_counter()
         self._hardware = hardware
         self._pue = pue
         # TODO: Read initial energy values from hardware
@@ -40,9 +40,9 @@ class MeasurePowerEnergy:
 
     def do_measure(self) -> None:
         for hardware in self._hardware:
-            h_time = time.time()
+            h_time = perf_counter()
             # Compute last_duration again for more accuracy
-            last_duration = time.time() - self._last_measured_time
+            last_duration = perf_counter() - self._last_measured_time
             power, energy = hardware.measure_power_and_energy(
                 last_duration=last_duration
             )
@@ -87,7 +87,7 @@ class MeasurePowerEnergy:
                     )
             else:
                 logger.error(f"Unknown hardware type: {hardware} ({type(hardware)})")
-            h_time = time.time() - h_time
+            h_time = perf_counter() - h_time
             logger.debug(
                 f"{hardware.__class__.__name__} : {hardware.total_power().W:,.2f} "
                 + f"W during {last_duration:,.2f} s [measurement time: {h_time:,.4f}]"