Allow simulating idle components

Author: PedramBakh

carbontracker/cli.py

@@ -25,27 +25,28 @@ def main():
     The **carbontracker** CLI allows the user to track the energy consumption and carbon intensity of any program.
     [Make sure that you have relevant permissions before running this.](/#permissions)
 
-    Args:
-        --log_dir (path, optional): Log directory. Defaults to `./logs`.
-        --api_keys (str, optional): API keys in a dictionary-like format, e.g. `\'{"electricitymaps": "YOUR_KEY"}\'`
-        --parse (path, optional): Directory containing the log files to parse.
-        --report (path, optional): Generate a PDF report from a log file.
-        --output (path, optional): Output path for the generated report. Defaults to 'carbon_report.pdf'
-        --sim-cpu (str, optional): Simulated CPU name (overrides detection)
-        --sim-cpu-tdp (float, optional): Simulated CPU TDP in Watts
-        --sim-cpu-util (float, optional): Simulated CPU utilization (0.0 to 1.0)
-        --sim-gpu (str, optional): Simulated GPU name (overrides detection)
-        --sim-gpu-watts (float, optional): Simulated GPU power consumption in Watts
-        --sim-gpu-util (float, optional): Simulated GPU utilization (0.0 to 1.0)
+    The following command-line arguments are supported:
+
+    * `--log_dir` (str, optional): Log directory. Defaults to `./logs`.
+    * `--api_keys` (str, optional): API keys in a dictionary-like format, e.g. `{ \\"electricitymaps\\": \\"YOUR_KEY\\" }`
+    * `--parse` (str, optional): Directory containing the log files to parse.
+    * `--report` (str, optional): Generate a PDF report from a log file.
+    * `--output` (str, optional): Output path for the generated report. Defaults to 'carbon_report.pdf'
+    * `--sim-cpu` (str, optional): Simulated CPU name (overrides detection)
+    * `--sim-cpu-tdp` (float, optional): Simulated CPU TDP in Watts
+    * `--sim-cpu-util` (float, optional): Simulated CPU utilization (0.0 to 1.0)
+    * `--sim-gpu` (str, optional): Simulated GPU name (overrides detection)
+    * `--sim-gpu-watts` (float, optional): Simulated GPU power consumption in Watts
+    * `--sim-gpu-util` (float, optional): Simulated GPU utilization (0.0 to 1.0)
 
     Example:
-        Tracking the carbon intensity of `script.py`.
+        Tracking the carbon intensity of `script.py`:
 
             $ carbontracker python script.py
 
-        With example options
+        With example options:
 
-            $ carbontracker --log_dir='./logs' --api_keys='{"electricitymaps": "API_KEY_EXAMPLE"}' python script.py
+            $ carbontracker --log_dir='./logs' --api_keys='{ \\"electricitymaps\\": \\"API_KEY_EXAMPLE\\" }' python script.py
 
         Using simulated hardware:
 

carbontracker/components/component.py

@@ -50,13 +50,13 @@ def handlers_by_name(
 ):
     for comp in COMPONENTS:
         if comp["name"] == name:
-            if name == "cpu" and sim_cpu and sim_cpu_tdp:
+            if name == "cpu" and sim_cpu is not None and sim_cpu_tdp is not None:
                 return [lambda pids, devices_by_pid: SimulatedCPUHandler(
                     sim_cpu, 
                     float(sim_cpu_tdp),
                     float(sim_cpu_util) if sim_cpu_util is not None else 0.5
                 )]
-            elif name == "gpu" and sim_gpu and sim_gpu_watts:
+            elif name == "gpu" and sim_gpu is not None and sim_gpu_watts is not None:
                 return [lambda pids, devices_by_pid: SimulatedGPUHandler(
                     sim_gpu, 
                     float(sim_gpu_watts),

carbontracker/components/cpu/sim_cpu.py

@@ -6,8 +6,8 @@ def __init__(self, name: str, tdp: float, utilization: float = 0.5):
         super().__init__(pids=[], devices_by_pid=False)
         if not isinstance(name, str) or not name.strip():
             raise ValueError("CPU name must be a non-empty string.")
-        if tdp is None or not isinstance(tdp, (int, float)) or tdp <= 0:
-            raise ValueError("CPU TDP must be a positive number.")
+        if tdp is None or not isinstance(tdp, (int, float)) or tdp < 0:
+            raise ValueError("CPU TDP must be a non-negative number.")
         if not isinstance(utilization, (int, float)) or not (0.0 <= utilization <= 1.0):
             raise ValueError("CPU utilization must be between 0.0 and 1.0.")
         self.cpu_brand = name

carbontracker/components/gpu/sim_gpu.py

@@ -6,8 +6,8 @@ def __init__(self, name: str, watts: float, utilization: float = 0.5):
         super().__init__(pids=[], devices_by_pid=False)
         if not isinstance(name, str) or not name.strip():
             raise ValueError("GPU name must be a non-empty string.")
-        if watts is None or not isinstance(watts, (int, float)) or watts <= 0:
-            raise ValueError("GPU watts must be a positive number.")
+        if watts is None or not isinstance(watts, (int, float)) or watts < 0:
+            raise ValueError("GPU watts must be a non-negative number.")
         if not isinstance(utilization, (int, float)) or not (0.0 <= utilization <= 1.0):
             raise ValueError("GPU utilization must be between 0.0 and 1.0.")
         self.gpu_brand = name
@@ -26,5 +26,20 @@ def power_usage(self) -> List[float]:
     def init(self):
         print(f"Using simulated GPU: {self.gpu_brand} with power consumption: {self.watts:.2f}W (at {self.utilization*100:.0f}% utilization)")
 
+    def shutdown(self):
+        pass
+
+    def devices(self) -> List[str]:
+        return [self.gpu_brand]
+
+    def available(self) -> bool:
+        return True
+
+    def power_usage(self) -> List[float]:
+        return [self.watts]
+
+    def init(self):
+        print(f"Using simulated GPU: {self.gpu_brand} with power consumption: {self.watts:.2f}W (at {self.utilization*100:.0f}% utilization)")
+
     def shutdown(self):
         pass 

docs/index.md

@@ -11,7 +11,7 @@ See [CLI](documentation/CLI.md) for CLI options.
 **carbontracker** supports the following components:
 
 - Intel CPUs that support [Intel RAPL](http://web.eece.maine.edu/~vweaver/projects/rapl/rapl_support.html) on Linux. [Note on how to enable permissions](/#permissions)
-- NVIDIA GPUs that support [NVIDIA Management Library (NVML)](Intel CPUs that support Intel RAPL) on Linux
+- NVIDIA GPUs that support [NVIDIA Management Library (NVML)] on Linux
 - Apple Silicon on MacOS
 
 ## Permissions