codegreen 0.4.8__tar.gz → 0.5.0__tar.gz

{codegreen-0.4.8 → codegreen-0.5.0}/CMakeLists.txt

@@ -46,15 +46,8 @@ include_directories(${CMAKE_SOURCE_DIR}/codegreen/measurement/include)
 add_subdirectory(codegreen/measurement)
 
 
-# Copy config to build dir
-if(EXISTS "${CMAKE_SOURCE_DIR}/config/codegreen.json")
-    file(MAKE_DIRECTORY ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/config)
-    configure_file(
-        ${CMAKE_SOURCE_DIR}/config/codegreen.json
-        ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/config/codegreen.json
-        COPYONLY
-    )
-endif()
+# NEMB finds its config at <library dir>/../config.json; place the bundled one there so the build tree works
+configure_file(${CMAKE_SOURCE_DIR}/codegreen/config.json ${CMAKE_BINARY_DIR}/config.json COPYONLY)
 
 # Dev-install: copy NEMB library to project root for pip editable installs
 add_custom_target(dev-install ALL
@@ -73,17 +66,13 @@ install(TARGETS codegreen-nemb
     RUNTIME DESTINATION lib
 )
 
+install(FILES ${CMAKE_SOURCE_DIR}/codegreen/config.json DESTINATION share/codegreen)  # <prefix>/lib/../share/codegreen
+
 install(FILES
     ${CMAKE_SOURCE_DIR}/codegreen/instrumentation/language_runtimes/python/codegreen_runtime.py
     DESTINATION bin/runtime
 )
 
-if(EXISTS "${CMAKE_SOURCE_DIR}/config/codegreen.json")
-    install(FILES ${CMAKE_SOURCE_DIR}/config/codegreen.json
-        DESTINATION bin/config
-    )
-endif()
-
 set(CPACK_PACKAGE_NAME "CodeGreen")
 set(CPACK_PACKAGE_VERSION "${PROJECT_VERSION}")
 set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "Energy-aware software development tool")

codegreen-0.5.0/MANIFEST.in

@@ -0,0 +1,16 @@
+include README.md LICENSE requirements.txt pyproject.toml CMakeLists.txt setup.py
+
+recursive-include codegreen/measurement CMakeLists.txt *.cpp *.c *.h *.hpp
+recursive-include codegreen/instrumentation/language_runtimes *.py *.h *.hpp *.java
+recursive-include codegreen/instrumentation/configs *.json
+include codegreen/config.json
+
+global-exclude *.pyc
+global-exclude __pycache__
+global-exclude *.so
+global-exclude *.dylib
+global-exclude *.dll
+global-exclude *.jar
+global-exclude *.class
+global-exclude .DS_Store
+global-exclude *.o

{codegreen-0.4.8/codegreen.egg-info → codegreen-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codegreen
-Version: 0.4.8
+Version: 0.5.0
 Summary: Know the true energy cost of your code
 Author-email: Saurabhsingh Rajput <saurabh@dal.ca>
 Maintainer-email: Saurabhsingh Rajput <saurabh@dal.ca>
@@ -413,6 +413,7 @@ Requires-Dist: packaging>=21.0
 Requires-Dist: markdown-it-py<4.0.0,>=3.0.0
 Requires-Dist: tree-sitter<0.26,>=0.21
 Requires-Dist: tree-sitter-language-pack<1.0,>=0.7
+Requires-Dist: tree-sitter-java<0.24,>=0.23
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
@@ -429,6 +430,17 @@ Provides-Extra: viz
 Requires-Dist: matplotlib>=3.5.0; extra == "viz"
 Requires-Dist: pandas>=1.4.0; extra == "viz"
 Requires-Dist: plotly>=5.10.0; extra == "viz"
+Provides-Extra: otlp
+Requires-Dist: opentelemetry-api>=1.20.0; extra == "otlp"
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "otlp"
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20.0; extra == "otlp"
+Provides-Extra: prometheus
+Requires-Dist: prometheus-client>=0.20.0; extra == "prometheus"
+Provides-Extra: all
+Requires-Dist: opentelemetry-api>=1.20.0; extra == "all"
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "all"
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20.0; extra == "all"
+Requires-Dist: prometheus-client>=0.20.0; extra == "all"
 Dynamic: license-file
 
 <p align="center">
@@ -436,7 +448,12 @@ Dynamic: license-file
   <img src="docs/website/docs/assets/codegreen_logo_white.svg#gh-dark-mode-only" width="200" alt="CodeGreen Logo">
 </p>
 
-[![DOI](https://zenodo.org/badge/942273936.svg)](https://doi.org/10.5281/zenodo.18371771)
+[![PyPI](https://img.shields.io/pypi/v/codegreen)](https://pypi.org/project/codegreen/)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/codegreen?period=total&units=NONE&left_color=GREY&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/codegreen)
+[![GitHub stars](https://img.shields.io/github/stars/SMART-Dal/codegreen)](https://github.com/SMART-Dal/codegreen/stargazers)
+[![License](https://img.shields.io/badge/license-MPL%202.0-blue)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows-lightgrey)](https://pypi.org/project/codegreen/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18371771.svg)](https://doi.org/10.5281/zenodo.18371771)
 
 # CodeGreen - Garage for Energy Measurement and Optimization
 
@@ -452,6 +469,8 @@ pip install codegreen
 
 Pre-built wheels available for Linux x86_64 and macOS ARM64 (Apple Silicon). Includes the native NEMB energy measurement backend.
 
+Optional telemetry exporters for `codegreen monitor`: `pip install "codegreen[otlp]"` (OpenTelemetry/OTLP) or `pip install "codegreen[prometheus]"`.
+
 ### From source (recommended for development)
 
 ```bash
@@ -509,6 +528,23 @@ codegreen measure python script.py -g fine --json
 codegreen measure python script.py -g fine --export-plot energy.html
 ```
 
+### Project profiling, monitoring and timelines
+
+```bash
+# Per-function hotspots for a whole project (build once, run, attribute)
+codegreen project python ./src -r "python main.py" -s "**/*.py"
+
+# GPU work attributed to the launching function (torch/CUDA)
+codegreen project python ./src -r "python train.py" --sync-device cuda
+
+# Continuous host or per-PID sampling, optional OTLP / Prometheus export
+codegreen monitor -d 30 -o energy.jsonl
+codegreen monitor --pid 1234 --exporter prometheus --prometheus-port 9464
+
+# Power, stacks, GC and GPU kernels on one axis for ui.perfetto.dev
+codegreen timeline --nemb nemb.json --jfr run.json --out trace.json
+```
+
 ### Manual measurement from Python (Session API)
 
 For span-based measurement of arbitrary code regions, import `codegreen.Session` directly — no CLI, no AST instrumentation:
@@ -546,7 +582,7 @@ codegreen analyze python script.py --save-instrumented
 ### Benchmark validation (against perf RAPL ground truth)
 
 ```bash
-codegreen benchmark -p nbody spectralnorm -l python -r 5 --profilers codegreen perf
+codegreen benchmark -p nbody -p spectralnorm -l python -r 5 --profiler codegreen --profiler perf
 ```
 
 ## Output formats
@@ -557,7 +593,7 @@ JSON (default for `--json`), CSV, Markdown table, and text summary. The JSON out
 
 Adding a new language requires only a JSON config file in `codegreen/instrumentation/configs/` plus the tree-sitter grammar. No Python code changes needed.
 
-Currently supported: Python, C, C++, Java. JavaScript config exists but is not yet exposed via CLI.
+Currently supported: Python, C, C++, Java, JavaScript. Functions that cannot be framed safely (async, generators, coroutines, C++ `constexpr`) are reported as `skipped_functions` rather than instrumented.
 
 ## Benchmarking
 
@@ -574,11 +610,11 @@ bash scripts/generate_comparison_artifacts.sh docs/benchmarks/
 
 ## Energy Flow Graph (EFG)
 
-CodeGreen includes an Energy Flow Graph module (`codegreen/analysis/cfg/`) that builds energy-annotated control flow graphs from source code:
+CodeGreen includes an Energy Flow Graph module (`codegreen/analysis/efg/`) that builds energy-annotated control flow graphs from source code:
 
 ```python
 from codegreen.analysis.cfg.builder import build_per_method_cfgs
-from codegreen.analysis.cfg.energy_flow import build_efg, efg_to_dot, efg_to_text
+from codegreen.analysis.efg import build_efg, efg_to_dot, efg_to_text
 
 cfgs = build_per_method_cfgs(java_source_code)
 efg = build_efg(cfg_nodes, cfg_edges, "ClassName.method", "File.java", codegreen_data)
@@ -587,6 +623,8 @@ print(efg_to_text(efg))  # compact format for LLM prompts
 
 Features: Ball & Larus branch heuristics, SCC-based hot path computation, three-level accuracy annotations (MEASURED/ESTIMATED/INFERRED), configurable via `EFGConfig`.
 
+See `codegreen/analysis/efg/README.md` for the module layout, a runnable example (`python -m codegreen.analysis.efg.example.demo`), and the current list of known issues. `codegreen.analysis.cfg.energy_flow` still resolves as a back-compat shim.
+
 ## Architecture
 
 - **C++ NEMB backend**: platform-aware energy measurement (RAPL on Linux, IOReport on macOS, EMI on Windows), sub-microsecond timestamping, background polling with lock-free ring buffers
@@ -599,7 +637,7 @@ Features: Ball & Larus branch heuristics, SCC-based hot path computation, three-
 ```bash
 # Fail pipeline if energy exceeds budget
 codegreen run --budget 10.0 --json -- python tests/benchmark.py
-# Exit code 1 if mean energy > 10 Joules
+# Exit code 1 if mean energy > 10 Joules, 3 if the measurement is invalid (see validity.reasons)
 ```
 
 ## Upgrading

{codegreen-0.4.8 → codegreen-0.5.0}/README.md

@@ -3,7 +3,12 @@
   <img src="docs/website/docs/assets/codegreen_logo_white.svg#gh-dark-mode-only" width="200" alt="CodeGreen Logo">
 </p>
 
-[![DOI](https://zenodo.org/badge/942273936.svg)](https://doi.org/10.5281/zenodo.18371771)
+[![PyPI](https://img.shields.io/pypi/v/codegreen)](https://pypi.org/project/codegreen/)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/codegreen?period=total&units=NONE&left_color=GREY&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/codegreen)
+[![GitHub stars](https://img.shields.io/github/stars/SMART-Dal/codegreen)](https://github.com/SMART-Dal/codegreen/stargazers)
+[![License](https://img.shields.io/badge/license-MPL%202.0-blue)](LICENSE)
+[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20windows-lightgrey)](https://pypi.org/project/codegreen/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18371771.svg)](https://doi.org/10.5281/zenodo.18371771)
 
 # CodeGreen - Garage for Energy Measurement and Optimization
 
@@ -19,6 +24,8 @@ pip install codegreen
 
 Pre-built wheels available for Linux x86_64 and macOS ARM64 (Apple Silicon). Includes the native NEMB energy measurement backend.
 
+Optional telemetry exporters for `codegreen monitor`: `pip install "codegreen[otlp]"` (OpenTelemetry/OTLP) or `pip install "codegreen[prometheus]"`.
+
 ### From source (recommended for development)
 
 ```bash
@@ -76,6 +83,23 @@ codegreen measure python script.py -g fine --json
 codegreen measure python script.py -g fine --export-plot energy.html
 ```
 
+### Project profiling, monitoring and timelines
+
+```bash
+# Per-function hotspots for a whole project (build once, run, attribute)
+codegreen project python ./src -r "python main.py" -s "**/*.py"
+
+# GPU work attributed to the launching function (torch/CUDA)
+codegreen project python ./src -r "python train.py" --sync-device cuda
+
+# Continuous host or per-PID sampling, optional OTLP / Prometheus export
+codegreen monitor -d 30 -o energy.jsonl
+codegreen monitor --pid 1234 --exporter prometheus --prometheus-port 9464
+
+# Power, stacks, GC and GPU kernels on one axis for ui.perfetto.dev
+codegreen timeline --nemb nemb.json --jfr run.json --out trace.json
+```
+
 ### Manual measurement from Python (Session API)
 
 For span-based measurement of arbitrary code regions, import `codegreen.Session` directly — no CLI, no AST instrumentation:
@@ -113,7 +137,7 @@ codegreen analyze python script.py --save-instrumented
 ### Benchmark validation (against perf RAPL ground truth)
 
 ```bash
-codegreen benchmark -p nbody spectralnorm -l python -r 5 --profilers codegreen perf
+codegreen benchmark -p nbody -p spectralnorm -l python -r 5 --profiler codegreen --profiler perf
 ```
 
 ## Output formats
@@ -124,7 +148,7 @@ JSON (default for `--json`), CSV, Markdown table, and text summary. The JSON out
 
 Adding a new language requires only a JSON config file in `codegreen/instrumentation/configs/` plus the tree-sitter grammar. No Python code changes needed.
 
-Currently supported: Python, C, C++, Java. JavaScript config exists but is not yet exposed via CLI.
+Currently supported: Python, C, C++, Java, JavaScript. Functions that cannot be framed safely (async, generators, coroutines, C++ `constexpr`) are reported as `skipped_functions` rather than instrumented.
 
 ## Benchmarking
 
@@ -141,11 +165,11 @@ bash scripts/generate_comparison_artifacts.sh docs/benchmarks/
 
 ## Energy Flow Graph (EFG)
 
-CodeGreen includes an Energy Flow Graph module (`codegreen/analysis/cfg/`) that builds energy-annotated control flow graphs from source code:
+CodeGreen includes an Energy Flow Graph module (`codegreen/analysis/efg/`) that builds energy-annotated control flow graphs from source code:
 
 ```python
 from codegreen.analysis.cfg.builder import build_per_method_cfgs
-from codegreen.analysis.cfg.energy_flow import build_efg, efg_to_dot, efg_to_text
+from codegreen.analysis.efg import build_efg, efg_to_dot, efg_to_text
 
 cfgs = build_per_method_cfgs(java_source_code)
 efg = build_efg(cfg_nodes, cfg_edges, "ClassName.method", "File.java", codegreen_data)
@@ -154,6 +178,8 @@ print(efg_to_text(efg))  # compact format for LLM prompts
 
 Features: Ball & Larus branch heuristics, SCC-based hot path computation, three-level accuracy annotations (MEASURED/ESTIMATED/INFERRED), configurable via `EFGConfig`.
 
+See `codegreen/analysis/efg/README.md` for the module layout, a runnable example (`python -m codegreen.analysis.efg.example.demo`), and the current list of known issues. `codegreen.analysis.cfg.energy_flow` still resolves as a back-compat shim.
+
 ## Architecture
 
 - **C++ NEMB backend**: platform-aware energy measurement (RAPL on Linux, IOReport on macOS, EMI on Windows), sub-microsecond timestamping, background polling with lock-free ring buffers
@@ -166,7 +192,7 @@ Features: Ball & Larus branch heuristics, SCC-based hot path computation, three-
 ```bash
 # Fail pipeline if energy exceeds budget
 codegreen run --budget 10.0 --json -- python tests/benchmark.py
-# Exit code 1 if mean energy > 10 Joules
+# Exit code 1 if mean energy > 10 Joules, 3 if the measurement is invalid (see validity.reasons)
 ```
 
 ## Upgrading

{codegreen-0.4.8 → codegreen-0.5.0}/benchmark/__main__.py

@@ -1,9 +1,9 @@
 """Entry point for `python3 -m benchmark`."""
 import argparse
-import sys
 from pathlib import Path
 from benchmark.config import BenchmarkConfig
 from benchmark.harness import BenchmarkHarness
+from benchmark.suites.benchmarksgame import BenchmarksgameSuite
 
 def main():
     parser = argparse.ArgumentParser(description="CodeGreen Energy Benchmark Suite")
@@ -18,27 +18,23 @@ def main():
     args = parser.parse_args()
 
     config = BenchmarkConfig.from_yaml(args.config) if args.config else BenchmarkConfig.default()
-    harness = BenchmarkHarness(config)
+    suite = BenchmarksgameSuite(Path(config.benchmarks_dir) if config.benchmarks_dir else None,
+                                languages=args.languages, problems=args.problems, sizes=args.sizes)
+    harness = BenchmarkHarness(suite, repetitions=args.repetitions, warmup_runs=config.warmup_runs,
+                               timeout_seconds=config.timeout_seconds, min_runtime_seconds=config.min_runtime_seconds)
 
     try:
-        collector = harness.run_suite(
-            problems=args.problems,
-            languages=args.languages,
-            sizes=args.sizes,
-            profilers=args.profilers,
-            repetitions=args.repetitions,
-        )
+        collector = harness.run_suite(profilers=args.profilers, repetitions=args.repetitions)
         summaries = collector.summarize_all()
         print(f"\n{'='*60}")
         print(f"Results: {len(collector.results)} runs")
         print(f"{'='*60}")
         for key, data in sorted(summaries.items()):
-            e = data.get("energy")
-            t = data.get("time")
-            valid = data.get("valid_runs", 0)
-            total = data.get("total_runs", 0)
+            e, t = data["energy"], data["time"]
             energy_str = f"{e.mean:.4f} +/- {e.std:.4f} J" if e else "N/A"
-            print(f"  {key}: energy={energy_str}  time={t.mean:.3f}s  valid={valid}/{total}")
+            time_str = f"{t.mean:.3f}s" if t else "N/A"
+            print(f"  {key}: energy={energy_str}  time={time_str}  valid={data['valid_runs']}/{data['total_runs']}"
+                  f"  invalid={data['invalid_reasons']}")
 
         if args.output:
             collector.to_json(args.output)

{codegreen-0.4.8 → codegreen-0.5.0}/benchmark/config.py

@@ -15,7 +15,7 @@ class SystemState:
     cpu_model: str = ""
     cpu_governor: str = ""
     kernel_version: str = ""
-    rapl_domains: List[str] = field(default_factory=list)
+    power_events: List[str] = field(default_factory=list)
 
     @classmethod
     def capture(cls) -> "SystemState":
@@ -34,17 +34,8 @@ class SystemState:
                 state.cpu_governor = f.read().strip()
         except (FileNotFoundError, OSError):
             pass
-        import os
-        for i in range(10):
-            path = f"/sys/class/powercap/intel-rapl:0:{i}/name"
-            if os.path.exists(path):
-                try:
-                    with open(path) as f:
-                        state.rapl_domains.append(f.read().strip())
-                except OSError:
-                    pass
-            else:
-                break
+        from benchmark.profilers import perf_power_events
+        state.power_events = perf_power_events()
         return state
 
 @dataclass
@@ -66,7 +57,7 @@ class RunResult:
     language: str
     size: str
     profiler: str
-    energy_joules: float
+    energy_joules: Optional[float]
     time_seconds: float
     output_valid: bool
     repetition: int = 0
@@ -74,6 +65,31 @@ class RunResult:
     suite: str = "benchmarksgame"
     timestamp: datetime = field(default_factory=datetime.now)
     checkpoints: List[Dict[str, Any]] = field(default_factory=list)
+    validity: Optional[Dict[str, Any]] = None
+
+    @property
+    def measurement_valid(self) -> bool:
+        """No fatal validity reason; profilers without a validity contract (perf, native) report None."""
+        return self.validity is None or self.validity["status"] == "valid"
+
+# perf power events summed as the CPU-scope truth, mirroring the RAPL adapters' top-level domain rule: the first set
+# whose first event the power PMU offers wins (psys supersedes package + dram), using the offered events of that set.
+PERF_CPU_EVENT_SETS = (("energy-psys",), ("energy-pkg", "energy-ram"))
+
+@dataclass
+class ValidityTolerances:
+    """Expectations of benchmark.validation.experiments.ValidityExperiment. Windows are in sampler intervals
+    (sampler.interval_ms of the run itself); a window below min_window_samples - 1 intervals must be flagged
+    TOTAL_BELOW_RESOLUTION, one at or above min_window_samples + 1 must not, the two intervals between are either (one
+    late reading costs the window a reading). A sampler allowed on fewer than min_affinity_cpus CPUs must raise the
+    AFFINITY_SINGLE_CPU warning and may be SAMPLER_STARVED, as may any run whose reading gaps exceed codegreen's gap policy.
+    cv_max_pct maps a minimum window (s) to the largest CV (%) of valid energies across repetitions."""
+    min_window_samples: int = 2
+    min_affinity_cpus: int = 2
+    exclusive_rel_tol: float = 0.01
+    run_vs_perf_rel_tol: float = 0.03
+    run_vs_perf_min_duration_s: float = 1.0
+    cv_max_pct: Dict[float, float] = field(default_factory=lambda: {1.0: 5.0, 0.1: 10.0})
 
 @dataclass
 class BenchmarkConfig:

{codegreen-0.4.8 → codegreen-0.5.0}/benchmark/harness.py

@@ -3,7 +3,6 @@ import math
 import subprocess
 import sys
 import time
-from pathlib import Path
 from typing import Callable, List, Optional
 
 from benchmark.config import RunResult
@@ -49,11 +48,13 @@ class BenchmarkHarness:
         """Run a single task with a single profiler."""
         reps = repetitions or self.repetitions
         profiler = get_profiler(profiler_name)
+        if not profiler.is_available():
+            self.progress_callback(f"  Skipping {task.name} [{profiler_name}]: {profiler.unavailable_reason()}")
+            return []
+        # Build the task (compile, construct run command); the build may name the source anew (Java public class)
+        task = self.suite.build(task)
         if hasattr(profiler, 'set_source') and task.source_file:
             profiler.set_source(task.source_file, task.language)
-
-        # Build the task (compile, construct run command)
-        task = self.suite.build(task)
         if not task.run_command:
             self.progress_callback(f"  No run command for {task.name}, skipping")
             return []
@@ -96,6 +97,7 @@ class BenchmarkHarness:
                     variant=task.variant,
                     suite=self.suite.name,
                     checkpoints=profile_result.checkpoints,
+                    validity=profile_result.validity,
                 )
                 results.append(result)
                 self.collector.add(result)
@@ -105,6 +107,22 @@ class BenchmarkHarness:
                 self.progress_callback(f"  Run {i+1} failed: {e}")
         return results
 
+    def tasks(self, problem: str, languages: List[str], sizes: Optional[List[str]] = None) -> List[Task]:
+        """Tasks of one problem at the given languages and sizes (suite defaults when None); the default suite is
+        benchmarksgame."""
+        if self.suite is None:
+            from benchmark.suites.benchmarksgame import BenchmarksgameSuite
+            self.suite = BenchmarksgameSuite()
+        found = self.suite.discover({"problems": [problem], "languages": languages, "sizes": sizes})
+        if not found:
+            raise ValueError(f"{self.suite.name} has no task for {problem} in {languages} at sizes {sizes}")
+        return found
+
+    def run_problem(self, problem: str, languages: List[str], sizes: List[str], profilers: List[str],
+                    repetitions: Optional[int] = None) -> List[RunResult]:
+        """Run one problem for every language, size and profiler; returns the results of all runs."""
+        return [r for t in self.tasks(problem, languages, sizes) for p in profilers for r in self.run_task(t, p, repetitions)]
+
     def run_suite(self, profilers: Optional[List[str]] = None,
                   repetitions: Optional[int] = None,
                   filters: Optional[dict] = None) -> ResultCollector: