GreenTrace 0.1.0__tar.gz

greentrace-0.1.0/GreenTrace/emissions.py

@@ -0,0 +1,61 @@
+# GreenTrace/emissions.py
+
+
+class CarbonIntensityProvider:
+    """
+    Provides carbon intensity data (gCO₂eq/kWh).
+    """
+
+    # Source: IEA – International Energy Agency. Data for 2025.
+    # Data represents grams of CO2 equivalent per kilowatt-hour (gCO₂eq/kWh).
+    _INTENSITY_DATA = {
+        # Europe
+        "DE": 380,  # Germany (declining, but coal still retains a share)
+        "GB": 145,  # Great Britain (active decommissioning of coal)
+        "FR": 55,  # France (traditionally low due to nuclear power)
+        "IT": 290,  # Italy
+        "ES": 140,  # Spain (high share of solar generation)
+        "PL": 650,  # Poland (gradual move away from coal, significant reduction)
+        "NL": 310,  # Netherlands
+        "SE": 12,  # Sweden (almost complete decarbonization)
+        "NO": 10,  # Norway
+        "FI": 50,  # Finland
+        "DK": 85,  # Denmark
+        "RU": 335,  # Russia (stable, slight increase in the share of gas)
+        "CH": 25,  # Switzerland
+        "AT": 80,  # Austria
+        "BE": 135,  # Belgium
+        "IE": 310,  # Ireland
+        "PT": 150,  # Portugal
+        "GR": 265,  # Greece (reached a historic low in 2025)
+        # America
+        "US": 355,  # USA (moderate decline, gas growth limits the fall)
+        "CA": 105,  # Canada
+        "BR": 85,  # Brazil (high share of hydropower)
+        "MX": 410,  # Mexico
+        "AR": 260,  # Argentina
+        "CL": 145,  # Chile
+        "CO": 90,  # Colombia
+        # Asia and Oceania
+        "CN": 525,  # China (noticeable reduction due to record commissioning of renewables)
+        "IN": 680,  # India (intensity is falling, despite the growth in absolute emissions)
+        "JP": 440,  # Japan
+        "AU": 480,  # Australia (rapid adoption of solar panels)
+        "KR": 395,  # South Korea
+        "ID": 740,  # Indonesia
+        "VN": 450,  # Vietnam
+        "TH": 420,  # Thailand
+        "MY": 560,  # Malaysia
+        "PK": 480,  # Pakistan
+        "NZ": 85,  # New Zealand
+        # Other regions
+        "ZA": 810,  # South Africa (remains one of the highest in the world)
+        "TR": 430,  # Turkey
+        "DEFAULT": 425,  # Global average (IEA forecast for 2025: ~415-430)
+    }
+
+    def get_intensity(self, region_code: str) -> int:
+        """Returns the intensity for a region or the default value."""
+        return self._INTENSITY_DATA.get(
+            region_code.upper(), self._INTENSITY_DATA["DEFAULT"]
+        )

greentrace-0.1.0/GreenTrace/hardware/base.py

@@ -0,0 +1,56 @@
+# GreenTrace/hardware/base.py
+
+from abc import ABC, abstractmethod
+from typing import List, Dict, Tuple, Optional
+from datetime import datetime
+
+
+class HardwareMonitor(ABC):
+    """Abstract base class for monitoring hardware power consumption."""
+
+    def __init__(self, max_measurements: Optional[int] = None):
+        self._measurements: List[Tuple[datetime, float]] = []
+        self.max_measurements = max_measurements
+
+    @abstractmethod
+    def start(self, silent: bool = False) -> None:
+        """Start monitoring."""
+        pass
+
+    @abstractmethod
+    def stop(self, silent: bool = False) -> None:
+        """Stop monitoring."""
+        pass
+
+    @abstractmethod
+    def get_power_usage(self) -> float:
+        """Get the current power consumption in Watts."""
+        pass
+
+    def get_total_energy_kwh(self, interval_seconds: int) -> float:
+        """
+        Calculates the total energy consumed in kWh.
+
+        Formula: (average_power_watts * total_seconds) / (1000 * 3600)
+        """
+        if not self._measurements:
+            return 0.0
+
+        avg_power_watts = sum(power for _, power in self._measurements) / len(
+            self._measurements
+        )
+        total_seconds = len(self._measurements) * interval_seconds
+
+        kwh = (avg_power_watts * total_seconds) / (1000 * 3600)
+        return kwh
+
+    def add_measurement(self, power_watts: float):
+        """Adds a power measurement with a timestamp."""
+        self._measurements.append((datetime.now(), power_watts))
+
+        if self.max_measurements and len(self._measurements) > self.max_measurements:
+            self._measurements.pop(0)
+
+    def get_metadata(self) -> Dict[str, str]:
+        """Returns metadata about the hardware."""
+        return {}

greentrace-0.1.0/GreenTrace/hardware/cpu.py

@@ -0,0 +1,150 @@
+# GreenTrace/hardware/cpu.py
+
+import os
+import platform
+import time
+import psutil
+from typing import Optional, Dict
+
+import cpuinfo
+
+from .base import HardwareMonitor
+
+# Data source for TDP/Max Power:
+# Intel/AMD: Data from manufacturers and benchmarks.
+CPU_POWER_DATA: Dict[str, float] = {
+    # Apple Silicon (Max Power, W)
+    "Apple M1": 20.0,
+    "Apple M1 Pro": 40.0,
+    "Apple M1 Max": 90.0,
+    "Apple M1 Ultra": 150.0,
+    "Apple M2": 25.0,
+    "Apple M2 Pro": 50.0,
+    "Apple M2 Max": 100.0,
+    "Apple M2 Ultra": 160.0,
+    "Apple M3": 28.0,
+    "Apple M3 Pro": 60.0,
+    "Apple M3 Max": 120.0,
+    "Apple M4": 24.0,
+    "Apple M4 Pro": 38.0,
+    "Apple M4 Max": 70.0,
+    # Intel Core (TDP, W)
+    "Intel Core i9-13900K": 125.0,
+    "Intel Core i7-13700K": 125.0,
+    "Intel Core i5-13600K": 125.0,
+    "Intel Core i9-12900K": 125.0,
+    "Intel Core i7-12700K": 125.0,
+    "Intel Core i5-12600K": 125.0,
+    "Intel Core i9-11900K": 125.0,
+    "Intel Core i7-11700K": 125.0,
+    "Intel Core i5-11600K": 125.0,
+    # AMD Ryzen (TDP, W)
+    "AMD Ryzen 9 7950X": 170.0,
+    "AMD Ryzen 7 7700X": 105.0,
+    "AMD Ryzen 5 7600X": 105.0,
+    "AMD Ryzen 9 5950X": 105.0,
+    "AMD Ryzen 9 5900X": 105.0,
+    "AMD Ryzen 7 5800X": 105.0,
+    "AMD Ryzen 5 5600X": 65.0,
+}
+
+RAPL_DIR = "/sys/class/powercap/intel-rapl/"
+
+
+class CPUMonitor(HardwareMonitor):
+    """Monitors CPU power consumption."""
+
+    def __init__(self, max_measurements: Optional[int] = None):
+        super().__init__(max_measurements=max_measurements)
+        self.tdp = 125.0  # Default value
+        self.is_rapl_available = False
+        self.rapl_energy_files = []
+        self._last_rapl_energy = 0.0
+        self._last_rapl_time = 0.0
+
+    def start(self, silent: bool = False) -> None:
+        self._measurements = []
+        self._detect_cpu_power_source(silent)
+
+        if self.is_rapl_available:
+            self._last_rapl_energy = self._get_rapl_energy()
+            self._last_rapl_time = time.time()
+            if not silent:
+                print("CPU Monitor: Started using Intel RAPL.")
+        else:
+            if not silent:
+                print(f"CPU Monitor: Started using TDP model ({self.tdp}W).")
+
+    def _detect_cpu_power_source(self, silent: bool):
+        """Determines the data source: RAPL or TDP."""
+        # 1. Check for Intel RAPL (Linux only)
+        if platform.system() == "Linux" and os.path.exists(RAPL_DIR):
+            for root, _, files in os.walk(RAPL_DIR):
+                if "energy_uj" in files and "intel-rapl" in root:
+                    self.rapl_energy_files.append(os.path.join(root, "energy_uj"))
+            if self.rapl_energy_files:
+                self.is_rapl_available = True
+                return
+
+        cpu_info = cpuinfo.get_cpu_info()
+        brand = cpu_info.get("brand_raw", "")
+
+        for name, power in CPU_POWER_DATA.items():
+            if name.lower() in brand.lower():
+                self.tdp = power
+                if not silent:
+                    print(f"CPU Monitor: Detected '{brand}', using {power}W.")
+                return
+
+        if not silent:
+            print(
+                f"CPU Monitor Warning: CPU '{brand}' not in database. "
+                f"Falling back to default TDP ({self.tdp}W)."
+            )
+
+    def _get_rapl_energy(self) -> float:
+        """Reads the total energy from all found RAPL files."""
+        total_energy_uj = 0
+        for file_path in self.rapl_energy_files:
+            try:
+                with open(file_path, "r") as f:
+                    total_energy_uj += int(f.read())
+            except (IOError, ValueError):
+                continue
+        return total_energy_uj
+
+    def _get_power_from_rapl(self) -> float:
+        """Calculates the average power over a time interval using RAPL."""
+        current_energy = self._get_rapl_energy()
+        current_time = time.time()
+
+        time_delta = current_time - self._last_rapl_time
+        energy_delta = current_energy - self._last_rapl_energy
+
+        # Update values for the next call
+        self._last_rapl_energy = current_energy
+        self._last_rapl_time = current_time
+
+        if time_delta == 0:
+            return 0.0
+
+        # Convert from microjoules to joules and divide by seconds to get Watts
+        power_watts = (energy_delta / 1_000_000) / time_delta
+        return power_watts if power_watts >= 0 else 0.0
+
+    def _get_power_from_tdp(self) -> float:
+        """Estimates power consumption based on TDP and CPU utilization."""
+        cpu_utilization = psutil.cpu_percent() / 100.0
+        power_watts = self.tdp * cpu_utilization
+        return power_watts
+
+    def stop(self, silent: bool = False) -> None:
+        if not silent:
+            print("CPU Monitor: Stopped")
+
+    def get_power_usage(self) -> float:
+        """Returns the current CPU power consumption in Watts."""
+        if self.is_rapl_available:
+            return self._get_power_from_rapl()
+        else:
+            return self._get_power_from_tdp()

greentrace-0.1.0/GreenTrace/reporting.py

@@ -0,0 +1,206 @@
+# GreenTrace/reporting.py
+import json
+import csv
+import os
+from datetime import datetime
+from typing import Dict, Any
+
+
+class Reporter:
+    """
+    A class for generating reports in various formats (console, JSON, CSV).
+    """
+
+    def __init__(
+        self,
+        data: Dict[str, Any],
+        output_file: str = None,
+        output_format: str = "console",
+        csv_summary_only: bool = False,
+        silent: bool = False,
+    ):
+        self.data = data
+        self.output_file = output_file
+        self.output_format = output_format
+        self.csv_summary_only = csv_summary_only
+        self.silent = silent
+
+    def report(self):
+        """The main method that calls the required output format."""
+        if self.output_file:
+            self._report_to_file()
+        else:
+            self.to_console()
+
+    def to_console(self):
+        """Prints the report to the console."""
+        if self.silent:
+            return
+        summary = self.data["summary"]
+        print("\n" + "=" * 30 + " GreenTrace Report " + "=" * 30)
+        print(f"Start Time: {summary.get('start_time', 'N/A')}")
+        print(f"End Time: {summary.get('end_time', 'N/A')}")
+        print(f"Duration: {summary.get('duration_seconds', 0):.2f} seconds")
+        print(f"Total Energy Consumed: {summary['total_energy_kwh']:.6f} kWh")
+        print(
+            f"Carbon Intensity ({summary['region']}): {summary['carbon_intensity_gco2_per_kwh']} gCO₂eq/kWh"
+        )
+        print(f"Total CO₂ Emissions: {summary['emissions_gco2eq']:.4f} gCO₂eq")
+        print(f"Number of measurements: {len(self.data['measurements'])}")
+        print("=" * 80 + "\n")
+
+    def _report_to_file(self):
+        """Calls the method to save the report to a file depending on the format."""
+        if self.output_format == "json":
+            self._to_json()
+        elif self.output_format == "csv":
+            self._to_csv()
+        elif self.output_format == "html":
+            self._to_html()
+        elif not self.silent:
+            print(
+                f"Warning: Unsupported file format '{self.output_format}'. Defaulting to console output."
+            )
+            self.to_console()
+
+    def _to_json(self):
+        with open(self.output_file, "w", encoding="utf-8") as f:
+            json.dump(self.data, f, ensure_ascii=False, indent=4)
+        if not self.silent:
+            print(f"Report saved to {self.output_file}")
+
+    def _to_csv(self):
+        if self.csv_summary_only:
+            rows = [self.data.get("summary", {})]
+            if not rows:
+                if not self.silent:
+                    print("No summary data to save to CSV.")
+                return
+        else:
+            measurements = self.data.get("measurements", [])
+            if not measurements:
+                if not self.silent:
+                    print("No measurements to save to CSV.")
+                return
+            rows = measurements
+
+        with open(self.output_file, "w", newline="", encoding="utf-8") as f:
+            writer = csv.DictWriter(f, fieldnames=rows[0].keys())
+            writer.writeheader()
+            writer.writerows(rows)
+        if not self.silent:
+            print(f"Report saved to {self.output_file}")
+
+    def _to_html(self):
+        summary = self.data["summary"]
+        # Average car emissions: ~120 gCO2/km.
+        # Source: European Environment Agency
+        car_emissions_per_km = 120
+        equivalent_km = summary["emissions_gco2eq"] / car_emissions_per_km
+
+        # Average smartphone battery capacity ~15 Wh = 0.015 kWh
+        smartphone_charge_kwh = 0.015
+        equivalent_charges = (
+            summary["total_energy_kwh"] / smartphone_charge_kwh
+            if smartphone_charge_kwh > 0
+            else 0
+        )
+
+        start_time = (
+            datetime.fromisoformat(summary["start_time"])
+            if summary.get("start_time")
+            else None
+        )
+        report_id = (
+            f"CP-PY-{(start_time.strftime('%Y%m%d-%H%M%S'))}" if start_time else "N/A"
+        )
+        issue_date = datetime.now().strftime("%d.%m.%Y")
+        duration_str = f"{summary.get('duration_seconds', 0):.2f} sec"
+        start_time_str = (
+            start_time.strftime("%d.%m.%Y %H:%M:%S") if start_time else "N/A"
+        )
+
+        html_content = f"""
+        <!DOCTYPE html>
+        <html lang="en">
+        <head>
+            <meta charset="UTF-8">
+            <title>Carbon Footprint Certificate</title>
+            <style>
+                body {{ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif; margin: 0; padding: 40px; background-color: #e9ecef; color: #343a40; }}
+                .certificate {{ max-width: 800px; margin: auto; background: white; padding: 40px; border: 10px solid #343a40; box-shadow: 0 0 20px rgba(0,0,0,0.15); position: relative; }}
+                .header {{ text-align: center; border-bottom: 2px solid #dee2e6; padding-bottom: 20px; margin-bottom: 20px; }}
+                .header h1 {{ font-size: 28px; color: #343a40; margin: 0; }}
+                .header p {{ font-size: 14px; color: #6c757d; }}
+                .main-results {{ text-align: center; margin: 40px 0; }}
+                .main-results h2 {{ font-size: 16px; color: #6c757d; text-transform: uppercase; margin-bottom: 10px; }}
+                .main-results .value {{ font-size: 48px; font-weight: bold; color: #2a9d8f; }}
+                .details-grid {{ display: grid; grid-template-columns: 1fr 1fr; gap: 30px; margin-top: 30px; }}
+                .card {{ background-color: #f8f9fa; padding: 20px; border-radius: 8px; border: 1px solid #dee2e6; }}
+                .card h3 {{ margin-top: 0; font-size: 16px; color: #495057; border-bottom: 1px solid #dee2e6; padding-bottom: 10px; margin-bottom: 15px;}}
+                .card p {{ font-size: 22px; font-weight: bold; margin: 0; color: #343a40; }}
+                .card small {{ color: #6c757d; font-size: 12px; }}
+                .methodology {{ margin-top: 40px; padding-top: 20px; border-top: 1px solid #dee2e6; font-size: 12px; color: #6c757d; text-align: justify; }}
+                .footer {{ margin-top: 30px; text-align: center; font-size: 12px; color: #adb5bd; }}
+                .seal {{ position: absolute; bottom: 30px; right: 30px; width: 90px; height: 90px; background-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><circle cx="50" cy="50" r="48" fill="%23343a40"/><path d="M50,15 L61.8,38.2 L87.5,42.5 L68.8,60.8 L73.6,86 L50,73.8 L26.4,86 L31.2,60.8 L12.5,42.5 L38.2,38.2 Z" fill="%23e9ecef"/><text x="50" y="55" font-family="Arial" font-size="10" fill="%23343a40" text-anchor="middle" font-weight="bold">GreenTrace</text></svg>'); }}
+            </style>
+        </head>
+        <body>
+            <div class="certificate">
+                <div class="header">
+                    <h1>Carbon Footprint Certificate</h1>
+                    <p>Report ID: {report_id}  |  Issue Date: {issue_date}</p>
+                </div>
+
+                <div class="main-results">
+                    <h2>Total CO₂ Emissions</h2>
+                    <p class="value">{summary['emissions_gco2eq']:.4f} gCO₂eq</p>
+                </div>
+
+                <div class="details-grid">
+                    <div class="card">
+                        <h3>Total Energy Consumption</h3>
+                        <p>{summary['total_energy_kwh']:.6f} kWh</p>
+                    </div>
+                    <div class="card">
+                        <h3>Analysis Duration</h3>
+                        <p>{duration_str}</p>
+                        <small>Start: {start_time_str}</small>
+                    </div>
+                </div>
+
+                <div class="details-grid">
+                    <div class="card">
+                        <h3>Carbon Intensity ({summary['region']})</h3>
+                        <p>{summary['carbon_intensity_gco2_per_kwh']} g/kWh</p>
+                        <small>Amount of CO₂ emitted per 1 kWh of energy generated in this region.</small>
+                    </div>
+                     <div class="card">
+                        <h3>Equivalents</h3>
+                        <p>~{equivalent_km:.2f} km</p>
+                        <small>of a passenger car journey</small>
+                        <p style="margin-top: 10px;">~{equivalent_charges:.0f}</p>
+                        <small>full smartphone charges</small>
+                    </div>
+                </div>
+
+                <div class="methodology">
+                    <h3>Methodology</h3>
+                    <p>
+                        The emissions estimate was produced by the GreenTrace library. The calculation is based on measuring CPU power consumption. For Linux systems with Intel processors, Intel RAPL technology can be used for more accurate measurements. In other cases, a model based on Thermal Design Power (TDP) and current processor load is used. The resulting energy consumption is multiplied by the carbon intensity factor for the '{summary['region']}' region. The data is an estimate and is intended for comparative analysis.
+                    </p>
+                </div>
+
+                <div class="footer">
+                    Generated with GreenTrace
+                </div>
+
+                <div class="seal"></div>
+            </div>
+        </body>
+        </html>
+        """
+        with open(self.output_file, "w", encoding="utf-8") as f:
+            f.write(html_content)
+        if not self.silent:
+            print(f"Report saved to {self.output_file}")