feat: add roofline analysis (RooflineAnalyzer, measure_peaks)

Adds measurement primitives for compute-vs-memory-bound layer analysis:

- measure_peaks(): empirical probe of peak FLOPs/s (matmul) and streaming
  bandwidth (cache-defeating memcpy). Pins TF32 off by default for honest
  fp32 peaks; caches per (device, dtype, sizes).
- HardwarePeaks: dataclass with peak_flops, peak_bandwidth, ridge_point,
  and the flags under which they were measured.
- RooflineAnalyzer: per-layer profiler with .profile() / .summary() /
  .plot(). Single-pass hooks measure FLOPs (analytical for Conv and
  Linear), bytes (weights + input + output, Williams 2009), and time.
  Classifies each layer as memory-bound or compute-bound; layers outside
  Conv/Linear land in an "undefined" bucket with a warning.
- Plotly log-log roofline with transparent background and the project
  teal palette.

Per the measurement-only contract, fasterbench exposes numbers and the
plot; compression decisions belong in fasterrecipes.

Includes:
- API notebook nbs/analysis/roofline.ipynb with inline unit tests
  (hand-computed Conv2d flops/bytes, cache test, Linear stack) and
  #|slow integration tests (ResNet-18 CPU with synthetic peaks,
  CUDA smoke test guarded by is_available()).
- Tutorial nbs/tutorials/roofline.ipynb showing hardware peaks,
  ResNet-18 profiling, and AI shift across input resolutions.
- Sidebar + index.ipynb re-exports.

Author: nathanhubens

fasterbench/__init__.py

@@ -19,6 +19,9 @@
 from .compute import ComputeMetrics, compute_compute
 from .memory import MemoryMetrics, compute_memory, compute_memory_multi
 from .energy import EnergyMetrics, compute_energy, compute_energy_multi
+from fasterbench.roofline import (
+    HardwarePeaks, RooflinePoint, measure_peaks, clear_peaks_cache, RooflineAnalyzer,
+)
 from .plot import create_radar_plot, SPECS
 from .utils import parse_metric_value
 
@@ -38,6 +41,8 @@
     'MemoryMetrics', 'compute_memory', 'compute_memory_multi',
     # Energy
     'EnergyMetrics', 'compute_energy', 'compute_energy_multi',
+    # Roofline
+    'HardwarePeaks', 'RooflinePoint', 'measure_peaks', 'clear_peaks_cache', 'RooflineAnalyzer',
     # Plot
     'create_radar_plot', 'SPECS',
     # Report

fasterbench/_modidx.py

@@ -130,6 +130,36 @@
                                     'fasterbench.report._generate_css': ('analysis/report.html#_generate_css', 'fasterbench/report.py'),
                                     'fasterbench.report._improvement_indicator': ( 'analysis/report.html#_improvement_indicator',
                                                                                    'fasterbench/report.py')},
+            'fasterbench.roofline': { 'fasterbench.roofline.HardwarePeaks': ( 'analysis/roofline.html#hardwarepeaks',
+                                                                              'fasterbench/roofline.py'),
+                                      'fasterbench.roofline.HardwarePeaks.as_dict': ( 'analysis/roofline.html#hardwarepeaks.as_dict',
+                                                                                      'fasterbench/roofline.py'),
+                                      'fasterbench.roofline.RooflineAnalyzer': ( 'analysis/roofline.html#rooflineanalyzer',
+                                                                                 'fasterbench/roofline.py'),
+                                      'fasterbench.roofline.RooflineAnalyzer.__init__': ( 'analysis/roofline.html#rooflineanalyzer.__init__',
+                                                                                          'fasterbench/roofline.py'),
+                                      'fasterbench.roofline.RooflineAnalyzer.plot': ( 'analysis/roofline.html#rooflineanalyzer.plot',
+                                                                                      'fasterbench/roofline.py'),
+                                      'fasterbench.roofline.RooflineAnalyzer.profile': ( 'analysis/roofline.html#rooflineanalyzer.profile',
+                                                                                         'fasterbench/roofline.py'),
+                                      'fasterbench.roofline.RooflineAnalyzer.results': ( 'analysis/roofline.html#rooflineanalyzer.results',
+                                                                                         'fasterbench/roofline.py'),
+                                      'fasterbench.roofline.RooflineAnalyzer.summary': ( 'analysis/roofline.html#rooflineanalyzer.summary',
+                                                                                         'fasterbench/roofline.py'),
+                                      'fasterbench.roofline.RooflinePoint': ( 'analysis/roofline.html#rooflinepoint',
+                                                                              'fasterbench/roofline.py'),
+                                      'fasterbench.roofline.RooflinePoint.as_dict': ( 'analysis/roofline.html#rooflinepoint.as_dict',
+                                                                                      'fasterbench/roofline.py'),
+                                      'fasterbench.roofline._layer_flops': ( 'analysis/roofline.html#_layer_flops',
+                                                                             'fasterbench/roofline.py'),
+                                      'fasterbench.roofline._pinned_benchmark_flags': ( 'analysis/roofline.html#_pinned_benchmark_flags',
+                                                                                        'fasterbench/roofline.py'),
+                                      'fasterbench.roofline._setup_roofline_hooks': ( 'analysis/roofline.html#_setup_roofline_hooks',
+                                                                                      'fasterbench/roofline.py'),
+                                      'fasterbench.roofline.clear_peaks_cache': ( 'analysis/roofline.html#clear_peaks_cache',
+                                                                                  'fasterbench/roofline.py'),
+                                      'fasterbench.roofline.measure_peaks': ( 'analysis/roofline.html#measure_peaks',
+                                                                              'fasterbench/roofline.py')},
             'fasterbench.size': { 'fasterbench.size.SizeMetrics': ('metrics/size.html#sizemetrics', 'fasterbench/size.py'),
                                   'fasterbench.size.SizeMetrics.as_dict': ('metrics/size.html#sizemetrics.as_dict', 'fasterbench/size.py'),
                                   'fasterbench.size.compute_size': ('metrics/size.html#compute_size', 'fasterbench/size.py'),