Feature/add water usage (#941)

* Add support for setting WUE (water usage effectiveness) via a flag and calculating water usage.

This adds a --wue flag for a L/kWh WUE value.
I also fix some tests that for some reason started failing on Mac. Unclear why they are failing
now.

* Create documentation and an example script for WUE.

Also remove an unecessary asserts in unit.py that was breaking the pue.py example script. It's uncessary because we only need to assert one number in a product is a float to get a float result.

* Check scheduler exists before checking if it has stopped - a cause of test flakiness

Author: cianc

codecarbon/core/units.py

@@ -90,7 +90,6 @@ def __add__(self, other: "Energy") -> "Energy":
         return Energy(self.kWh + other.kWh)
 
     def __mul__(self, factor: float) -> "Energy":
-        assert isinstance(factor, float)
         assert isinstance(self.kWh, float)
         result = Energy(self.kWh * factor)
         return result
@@ -162,3 +161,19 @@ def __truediv__(self, divisor: float) -> "Power":
 
     def __floordiv__(self, divisor: float) -> "Power":
         return Power(self.kW // divisor)
+
+
+@dataclass
+class Water:
+    """
+    Measured in litres
+    """
+
+    litres: float
+
+    @classmethod
+    def from_litres(cls, litres: float) -> "Water":
+        return cls(litres=litres)
+
+    def __add__(self, other: "Water") -> "Water":
+        return Water(self.litres + other.litres)

codecarbon/emissions_tracker.py

@@ -17,7 +17,7 @@
 from codecarbon.core.config import get_hierarchical_config
 from codecarbon.core.emissions import Emissions
 from codecarbon.core.resource_tracker import ResourceTracker
-from codecarbon.core.units import Energy, Power, Time
+from codecarbon.core.units import Energy, Power, Time, Water
 from codecarbon.core.util import count_cpus, count_physical_cpus, suppress
 from codecarbon.external.geography import CloudMetadata, GeoMetadata
 from codecarbon.external.hardware import CPU, GPU, AppleSiliconChip
@@ -179,6 +179,7 @@ def __init__(
         force_cpu_power: Optional[int] = _sentinel,
         force_ram_power: Optional[int] = _sentinel,
         pue: Optional[int] = _sentinel,
+        wue: Optional[bool] = _sentinel,
         force_mode_cpu_load: Optional[bool] = _sentinel,
         allow_multiple_runs: Optional[bool] = _sentinel,
     ):
@@ -238,6 +239,7 @@ def __init__(
         :param pue: PUE (Power Usage Effectiveness) of the datacenter.
         :param force_mode_cpu_load: Force the addition of a CPU in MODE_CPU_LOAD
         :param allow_multiple_runs: Allow multiple instances of codecarbon running in parallel. Defaults to False.
+        :param wue: WUE (Water Usage Effectiveness) of the datacenter, L/kWh.
         """
 
         # logger.info("base tracker init")
@@ -287,6 +289,7 @@ def __init__(
         self._set_from_conf(force_cpu_power, "force_cpu_power", None, float)
         self._set_from_conf(force_ram_power, "force_ram_power", None, float)
         self._set_from_conf(pue, "pue", 1.0, float)
+        self._set_from_conf(wue, "wue", 0, float)
         self._set_from_conf(force_mode_cpu_load, "force_mode_cpu_load", False, bool)
         self._set_from_conf(
             experiment_id, "experiment_id", "5b0fa12a-3dd7-45bb-9766-cc326314d9f1"
@@ -299,6 +302,7 @@ def __init__(
         self._start_time: Optional[float] = None
         self._last_measured_time: float = time.perf_counter()
         self._total_energy: Energy = Energy.from_energy(kWh=0)
+        self._total_water: Water = Water.from_litres(litres=0)
         self._total_cpu_energy: Energy = Energy.from_energy(kWh=0)
         self._total_gpu_energy: Energy = Energy.from_energy(kWh=0)
         self._total_ram_energy: Energy = Energy.from_energy(kWh=0)
@@ -703,6 +707,7 @@ def _prepare_emissions_data(self) -> EmissionsData:
             gpu_energy=self._total_gpu_energy.kWh,
             ram_energy=self._total_ram_energy.kWh,
             energy_consumed=self._total_energy.kWh,
+            water_consumed=self._total_water.litres,
             country_name=country_name,
             country_iso_code=country_iso_code,
             region=region,
@@ -721,6 +726,7 @@ def _prepare_emissions_data(self) -> EmissionsData:
             ram_total_size=self._conf.get("ram_total_size"),
             tracking_mode=self._conf.get("tracking_mode"),
             pue=self._pue,
+            wue=self._wue,
         )
         logger.debug(total_emissions)
         return total_emissions
@@ -778,7 +784,9 @@ def _do_measurements(self) -> None:
             ) = hardware.measure_power_and_energy(last_duration=last_duration)
             # Apply the PUE of the datacenter to the consumed energy
             energy *= self._pue
+            water = Water.from_litres(litres=self._wue * energy.kWh)
             self._total_energy += energy
+            self._total_water += water
             if isinstance(hardware, CPU):
                 self._total_cpu_energy += energy
                 self._cpu_power = power
@@ -825,7 +833,7 @@ def _do_measurements(self) -> None:
                 f"Done measure for {hardware.__class__.__name__} - measurement time: {h_time:,.4f} s - last call {last_duration:,.2f} s"
             )
         logger.info(
-            f"{self._total_energy.kWh:.6f} kWh of electricity used since the beginning."
+            f"{self._total_energy.kWh:.6f} kWh of electricity and {self._total_water.litres:.6f} L of water were used since the beginning."
         )
 
     def _measure_power_and_energy(self) -> None:
@@ -843,7 +851,11 @@ def _measure_power_and_energy(self) -> None:
             raise e
 
         warning_duration = self._measure_power_secs * 3
-        if last_duration > warning_duration and not self._scheduler._stopped:
+        if (
+            last_duration > warning_duration
+            and self._scheduler
+            and not self._scheduler._stopped
+        ):
             warn_msg = (
                 "Background scheduler didn't run for a long period"
                 + " (%ds), results might be inaccurate"
@@ -1066,6 +1078,7 @@ def track_emissions(
     force_cpu_power: Optional[int] = _sentinel,
     force_ram_power: Optional[int] = _sentinel,
     pue: Optional[int] = _sentinel,
+    wue: Optional[float] = _sentinel,
     allow_multiple_runs: Optional[bool] = _sentinel,
 ):
     """
@@ -1141,6 +1154,7 @@ def track_emissions(
     :param force_cpu_power: cpu power to be used instead of automatic detection.
     :param force_ram_power: ram power to be used instead of automatic detection.
     :param pue: PUE (Power Usage Effectiveness) of the datacenter.
+    :param wue: WUE (Water Usage Effectiveness) of the datacenter, L/kWh.
     :param allow_multiple_runs: Prevent multiple instances of codecarbon running. Defaults to False.
 
     :return: The decorated function
@@ -1181,6 +1195,7 @@ def wrapped_fn(*args, **kwargs):
                     force_cpu_power=force_cpu_power,
                     force_ram_power=force_ram_power,
                     pue=pue,
+                    wue=wue,
                     allow_multiple_runs=allow_multiple_runs,
                 )
             else:
@@ -1212,6 +1227,7 @@ def wrapped_fn(*args, **kwargs):
                     force_cpu_power=force_cpu_power,
                     force_ram_power=force_ram_power,
                     pue=pue,
+                    wue=wue,
                     allow_multiple_runs=allow_multiple_runs,
                 )
             tracker.start()

codecarbon/external/task.py

@@ -34,6 +34,7 @@ def out(self):
             gpu_energy=self.emissions_data.gpu_energy,
             ram_energy=self.emissions_data.ram_energy,
             energy_consumed=self.emissions_data.energy_consumed,
+            water_consumed=self.emissions_data.water_consumed,
             country_name=self.emissions_data.country_name,
             country_iso_code=self.emissions_data.country_iso_code,
             region=self.emissions_data.region,

codecarbon/output_methods/emissions_data.py

@@ -23,6 +23,7 @@ class EmissionsData:
     gpu_energy: float
     ram_energy: float
     energy_consumed: float
+    water_consumed: float
     country_name: str
     country_iso_code: str
     region: str
@@ -41,6 +42,7 @@ class EmissionsData:
     tracking_mode: str
     on_cloud: str = "N"
     pue: float = 1
+    wue: float = 0
 
     @property
     def values(self) -> OrderedDict:
@@ -55,6 +57,7 @@ def compute_delta_emission(self, previous_emission):
         self.gpu_energy -= previous_emission.gpu_energy
         self.ram_energy -= previous_emission.ram_energy
         self.energy_consumed -= previous_emission.energy_consumed
+        self.water_consumed -= previous_emission.water_consumed
         if delta_duration > 0:
             # emissions_rate in g/s : delta_emissions in kg.CO2 / delta_duration in s
             self.emissions_rate = delta_emissions / delta_duration
@@ -81,6 +84,7 @@ class TaskEmissionsData:
     gpu_energy: float
     ram_energy: float
     energy_consumed: float
+    water_consumed: float
     country_name: str
     country_iso_code: str
     region: str

docs/_sources/parameters.rst.txt

@@ -36,6 +36,11 @@ Input Parameters
    * - pue
      - | PUE (Power Usage Effectiveness) of the data center
        | where the experiment is being run.
+   * - wue
+     - | WUE (Water Usage Effectiveness) of the data center
+       | where the experiment is being run.
+       | Units of *L/kWh* - how many litres of water are consumed per kilowatt-hour
+       | of electricity consumed.
    * - force_cpu_power
      - | Force the CPU max power consumption in watts,
        | use this if you know the TDP of your machine.

docs/edit/parameters.rst

@@ -36,6 +36,11 @@ Input Parameters
    * - pue
      - | PUE (Power Usage Effectiveness) of the data center
        | where the experiment is being run.
+   * - wue
+     - | WUE (Water Usage Effectiveness) of the data center
+       | where the experiment is being run.
+       | Units of *L/kWh* - how many litres of water are consumed per kilowatt-hour
+       | of electricity consumed.
    * - force_cpu_power
      - | Force the CPU max power consumption in watts,
        | use this if you know the TDP of your machine.

docs/objects.inv

@@ -158,15 +158,24 @@ <h2>Input Parameters<a class="headerlink" href="#input-parameters" title="Link t
 </div>
 </td>
 </tr>
-<tr class="row-even"><td><p>force_cpu_power</p></td>
+<tr class="row-even"><td><p>wue</p></td>
+<td><div class="line-block">
+<div class="line">WUE (Water Usage Effectiveness) of the data center</div>
+<div class="line">where the experiment is being run.</div>
+<div class="line">Units of <em>L/kWh</em> - how many litres of water are consumed per kilowatt-hour</div>
+<div class="line">of electricity consumed.</div>
+</div>
+</td>
+</tr>
+<tr class="row-odd"><td><p>force_cpu_power</p></td>
 <td><div class="line-block">
 <div class="line">Force the CPU max power consumption in watts,</div>
 <div class="line">use this if you know the TDP of your machine.</div>
 <div class="line"><em>(POWER_CONSTANT x CONSUMPTION_PERCENTAGE)</em></div>
 </div>
 </td>
 </tr>
-<tr class="row-odd"><td><p>force_ram_power</p></td>
+<tr class="row-even"><td><p>force_ram_power</p></td>
 <td><div class="line-block">
 <div class="line">Force the RAM power consumption in watts,</div>
 <div class="line">use this if you know the power consumption of your RAM.</div>
@@ -176,7 +185,7 @@ <h2>Input Parameters<a class="headerlink" href="#input-parameters" title="Link t
 </div>
 </td>
 </tr>
-<tr class="row-even"><td><p>allow_multiple_runs</p></td>
+<tr class="row-odd"><td><p>allow_multiple_runs</p></td>
 <td><div class="line-block">
 <div class="line">Boolean variable indicating if multiple instance of CodeCarbon</div>
 <div class="line">on the same machine is allowed,</div>

docs/parameters.html

@@ -0,0 +1,19 @@
+import time
+
+from codecarbon import track_emissions
+
+
+@track_emissions(
+    measure_power_secs=3,
+    wue=1.1,
+)
+def train_model():
+    """
+    This function will do nothing.
+    """
+    print("30 seconds before ending script...")
+    time.sleep(30)
+
+
+if __name__ == "__main__":
+    model = train_model()