Hebe

Hebe is an energy-aware optimization and measurement system for Triton GPU kernels. It combines reproducible GPU energy experiments, compiler artifact tracking, Triton/MLIR transformations, and eventually equality saturation.

All compilation, GPU execution, and experiment results live on prometheus. The workstation contains only synchronized source, documentation, and paper references; Triton and LLVM source/build trees remain remote.

PyTorch and Triton are provisioned as part of the remote compiler toolchain, not resolved by Hebe's Python package. This is intentional: PyTorch's published wheel pins a released Triton version, while Hebe uses its source-built Triton checkout. hebe doctor records and validates the active toolchain.

Current vertical slice

The initial command measures the same compiled vector-add kernel under labels A and B. This A/A experiment is a provisional measurement-noise study before any compiler transformation is evaluated. Current consumer-GPU counter research and the full prometheus meter probe reject the cumulative NVML counter for this RTX 5070 Ti. Driver-buffered power integration is now the provisional software source, cross-checked against explicit instant power; it is not yet externally validated.

scripts/on-prometheus .venv/bin/hebe doctor
scripts/on-prometheus .venv/bin/hebe probe-meter
scripts/on-prometheus .venv/bin/hebe probe-response
scripts/on-prometheus .venv/bin/hebe run-positive-control
scripts/hebe-prometheus run-control-ladder
scripts/on-prometheus .venv/bin/hebe run-aa --pairs 20 --batch-seconds 5
scripts/on-prometheus .venv/bin/hebe real-kernel-recon --all-cases
scripts/hebe-prometheus layernorm-retention-qualify --all-cases
scripts/hebe-prometheus layernorm-reintegration-probe
scripts/hebe-prometheus layernorm-reintegration-qualify
scripts/hebe-prometheus run-layernorm-retention \
  --qualification ~/school/hebe-data/qualifications/layernorm-retention/<qualification>.json
scripts/hebe-prometheus run-layernorm-retention-study \
  --qualification ~/school/hebe-data/qualifications/layernorm-retention/<qualification>.json
scripts/hebe-prometheus run-layernorm-reintegration-study \
  --qualification ~/school/hebe-data/qualifications/layernorm-reintegration/<qualification>.json
scripts/hebe-prometheus resume-layernorm-reintegration-study <campaign-id>

real-kernel-recon is compile-first: it correctness-qualifies pinned official Triton softmax, LayerNorm, matmul, and attention kernels and stores their exact compiler artifacts and static mechanism summaries. It does not measure energy; its purpose is to select real-derived causal A/B microkernels before committing to long paired campaigns.

layernorm-reintegration-probe verifies the exact dump/override capabilities of the installed pinned Triton without downloading or building a toolchain. layernorm-reintegration-qualify compiles the unchanged official LayerNorm source normally, exactly matches its three single-tile X load loops at TTGIR, hoists one equivalent load into the entry block, and feeds that TTGIR through the remaining default pipeline with the same ABI and fixed schedule. It requires bitwise equality for Y/Mean/Rstd, repeated-launch stability, intact canaries and inputs, non-aliasing pointers, exact compiler artifacts, distinct TTGIR/LLVM/PTX/SASS/cubin, and zero candidate spills before passing. It does not observe an energy label.

layernorm-retention-qualify compiles the real-derived LayerNorm G/G, R/G, G/R, and R/R materialization policies across the frozen five-width ladder, adds the S/S shared-memory point at 32K, checks all outputs and memory contracts, captures exact artifacts and CUDA-driver occupancy, and freezes the label-free choice of measurement cases. It performs no energy measurement.

run-layernorm-retention consumes one explicit passing, energy-label-free qualification and executes its frozen G/G versus R/R primary contrast. It revalidates all outputs and memory contracts, requires the measured cubins to match the qualification byte for byte, uses randomized paired CUDA-graph windows, records buffered NVML energy plus CUDA-event latency, and exports a typed synthesis dataset. The default confirmation-v1 tier refuses fewer than 12 pairs, five-second windows, 30 seconds of warmup, or the declared thermal stability window; use --protocol-tier smoke-v1 for infrastructure checks.

run-layernorm-retention-study is the preferred causal-result entry point. It freezes A/A, the qualified LayerNorm primary, and the 100% extra-traffic control as one ordered campaign; holds one GPU lease across all three jobs; checks that their boot session, stable platform, and acquisition protocol match; and seals one aggregate analysis and dataset. A smoke study may pass execution quality, but only confirmation-v1 can set study_qualified=true.

run-layernorm-reintegration-study applies the same controlled protocol to the complete pinned official LayerNorm source: default Triton is A, while B feeds the qualified single-tile load-retention TTGIR into the unchanged downstream compiler. Both cubins must match the label-free qualification byte for byte. The command seals A/A, the primary, and the positive control under one lease; resume-layernorm-reintegration-study safely continues only pending jobs from an integrity-checked campaign after an interruption.

The first full confirmation-v1 study is qualified. At the frozen 2048x8192 fp16 point, retaining X in registers (R/R) instead of reloading it (G/G) reduced energy by 12.3314% (95% interval [-12.3791%, -12.2856%]) and CUDA-event latency by 4.0410% (95% interval [-4.0950%, -3.9826%]). Same-session A/A was equivalent, the 100% extra-traffic control measured +93.2120%, every job passed on its first attempt, and the exact qualified cubins matched. The sealed study is analysis_sha256_8d89921dd344632c79db586c183fa6570167fb9137b55fa0c298a3cbcd8a4a99.

The first full-source reintegration confirmation is also qualified. Hoisting the official kernel's three semantic X loads to one reduced energy by 16.3022% (95% interval [-16.4652%, -16.1160%]) and latency by 9.0447% (95% interval [-9.3413%, -8.7053%]). The candidate reduces static SASS global loads 20 -> 12 without spills, despite increasing registers/thread 62 -> 116 and reducing active CTAs/SM 4 -> 2. Same-session A/A was equivalent, the deliberate extra-traffic control measured +93.0290%, every job passed on its first attempt, and all exact cubin and telemetry gates passed. The sealed study is analysis_sha256_20d2b18efb077c7d04ea4df26c7a75d5f69b4dc3a57bff428ca0650484dc5149.

run-control-ladder expands the requested extra-memory fractions and replicates into a frozen campaign, executes one exclusively leased GPU job at a time, compacts typed telemetry to Parquet, ingests the catalog, and creates immutable point/campaign analyses plus a synthesis-ready dataset snapshot. Its defaults are the research protocol (12 pairs, five-second windows, and a 30-second minimum thermal warmup); shorter settings should be labeled as infrastructure smoke tests rather than evidence.

The infrastructure commands have a shorter Prometheus wrapper and default to the authoritative ~/school/hebe-data root:

scripts/hebe-prometheus data-init
scripts/hebe-prometheus campaign-plan campaign.json
scripts/hebe-prometheus campaign-submit ~/school/hebe-data/campaigns/<campaign-id>
scripts/hebe-prometheus queue-status
scripts/hebe-prometheus catalog-rebuild
scripts/hebe-prometheus run-verify ~/school/hebe-data/runs/YYYY/MM/DD/<run-id>
scripts/hebe-prometheus dataset-verify ~/school/hebe-data/datasets/<dataset-id>

Set HEBE_DATA_ROOT or pass the global --data-root option before the subcommand to use a different root.

Hebe refuses to measure when another compute or graphics process owns the GPU. Generated artifacts and raw results are stored under results/ on prometheus; they are intentionally excluded from workstation synchronization.

See HEBE_BENCHMARKING.md for the experimental contract and host setup, and HEBE_MEASUREMENT_AUDIT.md for the evidence and next qualification gates. The paper-by-paper measurement review and resulting protocol are in NVIDIA_GPU_ENERGY_MEASUREMENT_RESEARCH.md. The active research questions, multi-level compiler architecture, milestone gates, and implementation queue are maintained in HEBE_RESEARCH_ROADMAP.md. The current execution sequence, component contracts, and gates are in the TTGIR-first implementation plan. The immutable data model, campaign hierarchy, artifact identity rules, and planned queue/warehouse boundaries are specified in HEBE_INFRASTRUCTURE.md.