add time-weighted power statistics analysis stage

[WarningRan]

Add Power Statistics Analysis Pipeline Stage

Summary

This PR introduces a new pipeline stage to analyze power consumption statistics. It provides time-weighted insights by correlating power counter data with kernel execution timelines, allowing for a clear distinction between "active computation" and "idle" power profiles.

Key Features

• Scenario-Based Analysis: Automatically separates statistics for periods with and without kernel execution (identified by Cmpt Exec).
• Time-Weighted Calculations: Prevents statistical bias from non-uniform sampling frequencies by weighting power values by their duration.
• Dual-Perspective Metrics:
  • Non-Zero (NZ) Metrics: Focuses on "operational" power by excluding zero values (e.g., mean_non_zero, median_non_zero).
  • Total Average: Includes all samples (including zeros) to represent the true energy footprint (avg_total).
• Command-Line Integration: Controlled via the new --power-stats flag.

Output Example

INFO Power with kernels: min_non_zero=6.52W, max=99.69W, mean_non_zero=36.09W, median_non_zero=35.77W, avg_total=35.96W (time-weighted, dur_total=115598.64ms, dur_non_zero=115171.07ms)
INFO Power without kernels: min_non_zero=6.52W, max=99.69W, mean_non_zero=11.09W, median_non_zero=11.08W, avg_total=11.09W (time-weighted, dur_total=908597.91ms, dur_non_zero=908573.36ms)

Implementation Details

Core Algorithm: Period Splitting

The implementation employs a "Timeline Slicing" approach:

1. Power Period Construction: Converts instantaneous counter samples into continuous duration blocks.
2. Kernel Timeline Merging: Merges overlapping kernel events to create a canonical "Busy" timeline.
3. Fragmenting: Slices each power block by the kernel timeline to categorize energy usage accurately.

Metrics Definition

• mean_non_zero: Weighted Mean = sum(Power_nz * Duration_nz) / sum(Duration_nz). It reflects hardware intensity during active/powered states.
• avg_total: The true time-weighted average including zeros. Essential for total energy (Energy = Average_Power * Total_Time) calculations.

Changes

• New Analysis Module: Created power_stats.py containing PowerStatisticsContext and the core analysis logic.
• CLI & Pipeline Integration: Added --power-stats argument to acelyzer.py and registered the new stage in the event pipeline.
• Pipeline Exposure: Updated pipeline/__init__.py to export the new context and dispatch functions.
• Profile Updates:
• Enabled the analysis by default in everything.json.
• Added the entry to torch_minimal.json (disabled by default) for consistency.

Usage

To enable power statistics in your trace analysis:

acelyzer -i trace.json --power-stats

[lasch]

Thank you @WarningRan
A self-contained stage to extract power stats. 👍

A few of the items in the drain() for-loops (e.g. Step 1) might be possible to move into the same function that collects the power_counters (might require changing the position of the overall pipeline step to a place after events are sorted by time stamp. That could remove the need to do the extra sorting and get rid of that first for loop.)

But that's functional sugar and optimization like that can be done later.

May I ask you to address the flake8 warnings. They're currently passing the tests but a pending PR #82 will enforce the code formatting and this could then force other people to fix code formatting for changes they didn't make.