From fd34104b62dda6d4dd61cb4a71b0b4af14a793f4 Mon Sep 17 00:00:00 2001 From: Simon Lee Date: Mon, 16 Nov 2026 01:15:19 -0800 Subject: [PATCH] [tpums] feat: Add host-link roofline efficiency for host_to_device / device_to_host - Add a PCIe host link bandwidth field to the hardware spec. - Report the host link peak for the measured scope and roofline efficiency for host_to_device and device_to_host. PiperOrigin-RevId: 1022603369 --- README.md | 4 +- docs/BENCHMARKS.md | 22 ++++- .../benchmarks/host_device.py | 32 +++++++ src/accelerator_microbenchmarks/core/base.py | 14 +++ .../core/constants.py | 9 +- .../core/roofline.py | 19 ++++ .../core/system.py | 1 + .../specs/schema.py | 18 ++++ .../specs/tpu7x.py | 3 + src/accelerator_microbenchmarks/specs/v6e.py | 3 + tests/test_host_device.py | 93 +++++++++++++++++++ tests/test_roofline.py | 54 +++++++++++ tests/test_system.py | 6 ++ 13 files changed, 274 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index fc1927ba..9fb4c328 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ | :--- | :--- | :--- | :--- | | **Compute** | **Matrix Multiplication (GEMM)** | Dense matrix multiplication ($$C = \alpha (A \times B) + \beta C$$) across configurable data types | • Compute Throughput (**TFLOPS**)
• Compute Roofline Efficiency (**%**)
• Compute Latency (**ms**) | | **Memory (HBM)** | **HBM Memory Bandwidth** | High Bandwidth Memory STREAM operations (Copy, Scale, Add, Triad, Read-Only, Write-Only) | • Memory Bandwidth (**GB/s**)
• Memory Roofline Efficiency (**%**)
• Memory Access Latency (**ms**) | -| **Host I/O (PCIe)** | **Host-to-Device (H2D)**
**Device-to-Host (D2H)** | Host CPU memory to/from accelerator HBM data transfers | • PCIe Transfer Bandwidth (**GB/s**)
• Transfer Latency (**ms**) | +| **Host I/O (PCIe)** | **Host-to-Device (H2D)**
**Device-to-Host (D2H)** | Host CPU memory to/from accelerator HBM data transfers | • PCIe Transfer Bandwidth (**GB/s**)
• Host Link Roofline Efficiency (**%**)
• Transfer Latency (**ms**) | | **Interconnect (ICI)** | **Device-to-Device (D2D)** | Data transfers between each device pair, over ICI (different chips) or die-to-die (same chip) | • D2D Link Bandwidth (**GB/s**)
• Pairwise N × N Device Bandwidth Matrix
• Transfer Latency (**ms**) | | **Collectives** | **All-Gather**
**All-Reduce**
**All-to-All** | Distributed collective communication across multi-chip topologies | • Collective Bus Bandwidth (**GB/s**)
• Collective Step Latency (**ms**) | @@ -487,7 +487,7 @@ TPUMS records primary performance metrics across both timing domains: | **Latency (`ms`)** | `wall_clock_p50_ms`
*(+ `p90`, `avg`, `std`)* | `xprof_p50_ms`
*(+ `p90`, `avg`, `std`)* | Execution duration across timed iterations (`p50` median, `p90`, mean, and standard deviation). | | **Compute Throughput (`TFLOPS`)** | `wall_clock_tflops_per_chip`
`wall_clock_tflops_per_device` | `xprof_tflops_per_chip`
`xprof_tflops_per_device` | Achieved compute throughput per physical TPU chip or per logical device ($$10^{12}$$ FLOPS). | | **Bandwidth (`GB/s`)** | `wall_clock_bandwidth_per_chip_gb_s`
`wall_clock_bandwidth_per_device_gb_s`
`wall_clock_bandwidth_per_host_gb_s` | `xprof_bandwidth_per_chip_gb_s`
`xprof_bandwidth_per_device_gb_s`
`xprof_bandwidth_per_host_gb_s` | Achieved HBM, PCIe, ICI link, or collective bus bandwidth per chip, per device, or per host ($$10^9$$ bytes/sec). | -| **Roofline Efficiency (`%`)** | `wall_clock_compute_roofline_efficiency_pct`
`wall_clock_memory_roofline_efficiency_pct`
`wall_clock_ici_roofline_efficiency_pct`
`wall_clock_roofline_efficiency_pct` | `xprof_compute_roofline_efficiency_pct`
`xprof_memory_roofline_efficiency_pct`
`xprof_ici_roofline_efficiency_pct`
`xprof_roofline_efficiency_pct` | Achieved compute, memory, ICI (`all_to_all` only), or device-to-device link (`device_to_device` only) performance as a percentage of the hardware's theoretical peak. | +| **Roofline Efficiency (`%`)** | `wall_clock_compute_roofline_efficiency_pct`
`wall_clock_memory_roofline_efficiency_pct`
`wall_clock_ici_roofline_efficiency_pct`
`wall_clock_roofline_efficiency_pct` | `xprof_compute_roofline_efficiency_pct`
`xprof_memory_roofline_efficiency_pct`
`xprof_ici_roofline_efficiency_pct`
`xprof_roofline_efficiency_pct` | Achieved compute, memory, ICI (`all_to_all` only), device-to-device link (`device_to_device`: ICI or die-to-die), or host link (`host_to_device` / `device_to_host`: PCIe) performance as a percentage of the hardware's theoretical peak. | See **[Throughput & Bandwidth Metric Conventions in `docs/BENCHMARKS.md`](docs/BENCHMARKS.md#per-device-vs-per-chip-scaling)** for how `_per_chip` vs. `_per_device` scales across dual-device (`tpu7x`) and single-device (`v6e`) TPU chips and which metrics each benchmark reports. diff --git a/docs/BENCHMARKS.md b/docs/BENCHMARKS.md index 6299b30b..8cc69f04 100644 --- a/docs/BENCHMARKS.md +++ b/docs/BENCHMARKS.md @@ -101,7 +101,7 @@ The table below summarizes which `` and `` each ben | :--- | :--- | :--- | :--- | | **`gemm`** | **Compute Throughput (`TFLOPS`)** & Roofline (`%`) | **Both Per-Chip & Per-Device**
(`*_tflops_per_chip`, `*_tflops_per_device`) | **Measures** per-device and aggregate per-chip matrix compute throughput (`TFLOPS`), and **compares** against peak chip compute rooflines (`%`). | | **`hbm`** | **Memory Bandwidth (`GB/s`)** & Roofline (`%`) | **All Three Scopes (`Per-Device`, `Per-Chip`, `Per-Host`; active measured, smaller derived, larger `None`)**
(`*_bandwidth_per_{device,chip,host}_gb_s`) | **Measures** HBM memory bandwidth (`GB/s`) across the selected hardware `scope` (`device` default, `chip`, or `host`), **derives** smaller scopes as the average share of the concurrent aggregate measurement, leaves larger scopes as `None` (no upward extrapolation), and **compares** against peak per-device HBM bandwidth rooflines (`%`). | -| **`host_to_device` / `device_to_host`** | **Host I/O Bandwidth (`GB/s`)** | **All Three Scopes (`Per-Device`, `Per-Chip`, `Per-Host`; active measured, smaller derived, larger `None`)**
(`*_bandwidth_per_{device,chip,host}_gb_s`) | **Measures** PCIe transfer bandwidth (`GB/s`) between the host CPU and the selected hardware `scope`: all local devices concurrently (`scope: "host"`, default), one physical chip (`scope: "chip"`), or one local device (`scope: "device"`), **deriving** smaller scopes as the average share while leaving larger scopes as `None` (since shared PCIe links do not scale linearly across cores). | +| **`host_to_device` / `device_to_host`** | **Host I/O Bandwidth (`GB/s`)** & Roofline (`%`) | **All Three Scopes (`Per-Device`, `Per-Chip`, `Per-Host`; active measured, smaller derived, larger `None`)**
(`*_bandwidth_per_{device,chip,host}_gb_s`) | **Measures** PCIe transfer bandwidth (`GB/s`) between the host CPU and the selected hardware `scope`: all local devices concurrently (`scope: "host"`, default), one physical chip (`scope: "chip"`), or one local device (`scope: "device"`), **deriving** smaller scopes as the average share while leaving larger scopes as `None` (since shared PCIe links do not scale linearly across cores), and **compares** the measured scope against the host link (PCIe) peak of the chips involved (`%`). | | **`device_to_device`** | **Device-to-Device Link Bandwidth (`GB/s`)** & Roofline (`%`) | **Per-Device**
(`*_bandwidth_per_device_gb_s`) | **Measures** transfer bandwidth (`GB/s`) between each device pair and **compares** it against the peak of the link used, ICI or die-to-die (`%`). | | **`all_reduce` / `all_gather` / `all_to_all`** | **Collective Bus Bandwidth (`GB/s`)** | **Per-Chip**
(`*_bandwidth_per_chip_gb_s`) | **Measures** aggregate external ICI collective bus bandwidth (`GB/s`) per physical TPU chip across the active device mesh. | @@ -415,6 +415,26 @@ inputs `A[M, K]` and `B[K, N]` dynamically quantized row-wise/column-wise to (`-` in console tables, empty in `summary.csv`, `null` in `detailed.json`) because shared PCIe links (such as a dual-die TPU chip sharing one PCIe endpoint) cannot be extrapolated upward from a smaller scope. +- **Host Link Roofline** (summary.csv / detailed.json only; not in the + console table): + - `roofline_bound_by` — Link that carries the transfer: always `pcie` (the + chip's host link). Shared with `device_to_device` (`ici` / `die_to_die`), + so every `peak_link_bandwidth_per_*_gb_s` row names its link. + - `peak_link_bandwidth_per_{device|chip|host}_gb_s` — Theoretical host link + peak for the measured `scope` only (`GB/s`): the chip's raw per-direction + PCIe bandwidth (`HardwareSpec.pcie`, e.g. Gen5 x8 = 32 GB/s on `v6e`, + Gen5 x16 = 64 GB/s on `tpu7x`) times the number of chips the measured + devices span (`ceil(num_devices / devices_per_chip)`). The link belongs to + the chip and is shared by its devices, so a single device transferring + alone (`scope="device"`) is bounded by the full chip link. Omitted when the + hardware spec has no PCIe bandwidth. + - `{wall_clock|xprof}_roofline_efficiency_pct` — Measured bandwidth of the + active `scope` as a percentage of that peak (`%`). Emitted for both + `transfer_backend` values: `tpu_sync` typically reaches ~88–92% (the + practical PCIe ceiling after 128b/130b encoding and TLP/DLLP protocol + overhead), while lower `jax` values reflect host staging overhead rather + than the link. Host-side limits (root complex, NUMA, host DRAM) are not + modeled. - **Latency (`ms`)**: - `{wall_clock|xprof}_{p50|p90|avg|std}_ms` — Iteration execution latency across median (`p50`), 90th percentile (`p90`), mean (`avg`), and standard deviation (`std`) in milliseconds (`ms`). - **Benchmark Attributes**: diff --git a/src/accelerator_microbenchmarks/benchmarks/host_device.py b/src/accelerator_microbenchmarks/benchmarks/host_device.py index fe2e8d71..007543a7 100644 --- a/src/accelerator_microbenchmarks/benchmarks/host_device.py +++ b/src/accelerator_microbenchmarks/benchmarks/host_device.py @@ -1,6 +1,8 @@ """Host-to-Device and Device-to-Host transfer performance benchmarks.""" import dataclasses +import logging +import math from typing import Any, Callable, Optional, Sequence from accelerator_microbenchmarks.core import base @@ -81,6 +83,9 @@ class _HostDeviceBenchmark(base.BaseBenchmark[HostDeviceParams]): derive_chip_bandwidth: bool = False # Data moves between host buffers and each local device only; no ICI. requires_ici: bool = False + roofline_mode: constants.RooflineMode = ( + constants.RooflineMode.HOST_DEVICE_LINK + ) REPORT_SCHEMA: Sequence[tuple[str, Callable[[Any], str]]] = ( ("dtype", report.format_str), ("transfer_backend", report.format_str), @@ -225,6 +230,33 @@ def get_total_bytes(self) -> float: def get_workload_metadata(self) -> dict[str, Any]: return {"num_devices": self.num_transfer_devices} + def get_peak_host_link_bandwidth(self) -> float | None: + """Returns the host link peak (GB/s) for the devices at `config.scope`. + + The host PCIe link belongs to the chip and is shared by all of its + devices, so the peak is the per-chip link bandwidth times the number of + chips the measured devices span (`ceil(num_devices / devices_per_chip)`, + the same `devices_per_chip` the scope bandwidths are derived with). A + single device transferring alone (`scope="device"`) is therefore bounded + by its full chip link. The peak applies to both transfer backends; + host-side limits (root complex, NUMA, host DRAM) are not modeled. + + Returns: + The peak bandwidth in decimal GB/s, or None (with a warning) when the + hardware spec has no PCIe host link. + """ + pcie = self.hardware_spec.pcie if self.hardware_spec is not None else None + if pcie is None: + logging.warning( + "No PCIe host link bandwidth in the hardware spec; skipping" + " host-link roofline analysis." + ) + return None + num_chips = math.ceil( + len(self.get_devices_to_measure()) / self.hardware_spec.devices_per_chip + ) + return pcie.bandwidth_per_direction_gb_s * num_chips + def calculate_throughput_metrics( self, latency_ms: float, prefix: constants.TimingDomain ) -> dict[str, Any]: diff --git a/src/accelerator_microbenchmarks/core/base.py b/src/accelerator_microbenchmarks/core/base.py index fcec2904..53732891 100644 --- a/src/accelerator_microbenchmarks/core/base.py +++ b/src/accelerator_microbenchmarks/core/base.py @@ -571,6 +571,20 @@ def get_peak_link_bandwidth( " RooflineMode.NETWORK_LINK." ) + def get_peak_host_link_bandwidth(self) -> float | None: + """Return the host link peak (GB/s) at the active measurement scope. + + Required when roofline_mode == RooflineMode.HOST_DEVICE_LINK. The value is + compared against `*_bandwidth_per__gb_s` for `config.scope`. + Returns None when the peak cannot be modeled for the current + configuration. + """ + raise NotImplementedError( + f"{self.__class__.__name__} must implement" + " get_peak_host_link_bandwidth() when roofline_mode ==" + " RooflineMode.HOST_DEVICE_LINK." + ) + @abc.abstractmethod def get_total_bytes(self) -> float: """Calculate total bytes moved to/from HBM.""" diff --git a/src/accelerator_microbenchmarks/core/constants.py b/src/accelerator_microbenchmarks/core/constants.py index 807502e1..d88c5a13 100644 --- a/src/accelerator_microbenchmarks/core/constants.py +++ b/src/accelerator_microbenchmarks/core/constants.py @@ -48,6 +48,11 @@ class RooflineMode(str, enum.Enum): the dies of one chip), as supplied by the benchmark. Emits `peak_link_bandwidth_per_device_gb_s`, `roofline_bound_by` (a `TransferLink` value), and `_roofline_efficiency_pct`. + HOST_DEVICE_LINK: Host<->device transfer roofline: the measured bandwidth + at the active measurement scope is compared against the host link peak + of the chips involved, as supplied by the benchmark. Emits + `peak_link_bandwidth_per__gb_s`, `roofline_bound_by` + (`TransferLink.PCIE`), and `_roofline_efficiency_pct`. """ NONE = "none" @@ -55,16 +60,18 @@ class RooflineMode(str, enum.Enum): MEMORY_HBM = "memory_hbm" NETWORK_ICI = "network_ici" NETWORK_LINK = "network_link" + HOST_DEVICE_LINK = "host_device_link" class TransferLink(enum.StrEnum): - """Physical link bounding a device-to-device transfer. + """Physical link bounding a device-to-device or host<->device transfer. The values are the strings emitted in the `roofline_bound_by` metric. """ ICI = "ici" DIE_TO_DIE = "die_to_die" + PCIE = "pcie" class TimingDomain(enum.StrEnum): diff --git a/src/accelerator_microbenchmarks/core/roofline.py b/src/accelerator_microbenchmarks/core/roofline.py index 80b619df..368267af 100644 --- a/src/accelerator_microbenchmarks/core/roofline.py +++ b/src/accelerator_microbenchmarks/core/roofline.py @@ -28,6 +28,8 @@ def apply_roofline_analysis( collectives report exclusively `*_bandwidth_per_chip_gb_s`. `_roofline_efficiency_pct` (NETWORK_LINK) is defined per device, since device-to-device transfers report `*_bandwidth_per_device_gb_s`. + `_roofline_efficiency_pct` (HOST_DEVICE_LINK) is computed at the + measured `config.scope` only, never from derived smaller-scope shares. Args: benchmark_instance: The benchmark instance being analyzed. @@ -136,4 +138,21 @@ def apply_roofline_analysis( ) * 100.0 return metrics + if mode == constants.RooflineMode.HOST_DEVICE_LINK: + peak_bw = benchmark_instance.get_peak_host_link_bandwidth() + if peak_bw is None or peak_bw <= 0: + return metrics + scope = constants.Scope(benchmark_instance.config.scope).value + metrics[f"peak_link_bandwidth_per_{scope}_gb_s"] = peak_bw + # Shares `peak_link_bandwidth_per_device_gb_s` with NETWORK_LINK, so name + # the bounding link to keep the column self-describing. + metrics["roofline_bound_by"] = str(constants.TransferLink.PCIE) + for prefix in constants.TimingDomain: + actual_bw = metrics.get(f"{prefix}_bandwidth_per_{scope}_gb_s") + if actual_bw is not None and actual_bw >= 0: + metrics[f"{prefix}_roofline_efficiency_pct"] = ( + actual_bw / peak_bw + ) * 100.0 + return metrics + return metrics diff --git a/src/accelerator_microbenchmarks/core/system.py b/src/accelerator_microbenchmarks/core/system.py index 95abfb23..93aafc43 100644 --- a/src/accelerator_microbenchmarks/core/system.py +++ b/src/accelerator_microbenchmarks/core/system.py @@ -17,6 +17,7 @@ TflopsSpec = schema.TflopsSpec IciSpec = schema.IciSpec DieToDieSpec = schema.DieToDieSpec +PcieSpec = schema.PcieSpec WraparoundRule = schema.WraparoundRule HbmSpec = schema.HbmSpec diff --git a/src/accelerator_microbenchmarks/specs/schema.py b/src/accelerator_microbenchmarks/specs/schema.py index acd1e8df..f26eb413 100644 --- a/src/accelerator_microbenchmarks/specs/schema.py +++ b/src/accelerator_microbenchmarks/specs/schema.py @@ -119,6 +119,21 @@ class DieToDieSpec: bandwidth_per_direction_gb_s: float +@dataclasses.dataclass(frozen=True) +class PcieSpec: + """PCIe host link of one chip (theoretical peak). + + Attributes: + bandwidth_per_direction_gb_s: Raw bandwidth of the chip's host PCIe link in + one direction, in decimal GB/s (transfer rate x lanes / 8, before + 128b/130b line encoding). The link is full-duplex, so each direction + carries this bandwidth independently. All devices of a multi-device chip + share the link. + """ + + bandwidth_per_direction_gb_s: float + + @dataclasses.dataclass(frozen=True) class HbmSpec: """High Bandwidth Memory specifications (per-chip). @@ -144,6 +159,9 @@ class HardwareSpec: # `None` when the chip has no die-to-die link (one device per chip) or its # bandwidth has not been verified yet. die_to_die: DieToDieSpec | None = None + # `None` when the host link is not PCIe or its bandwidth has not been + # verified yet. + pcie: PcieSpec | None = None hbm: HbmSpec | None = None @property diff --git a/src/accelerator_microbenchmarks/specs/tpu7x.py b/src/accelerator_microbenchmarks/specs/tpu7x.py index 4634fbb2..a7a15997 100644 --- a/src/accelerator_microbenchmarks/specs/tpu7x.py +++ b/src/accelerator_microbenchmarks/specs/tpu7x.py @@ -25,5 +25,8 @@ # (https://docs.cloud.google.com/tpu/docs/tpu7x#dual-chiplet_architecture). # The D2D link is full duplex. die_to_die=schema.DieToDieSpec(bandwidth_per_direction_gb_s=800.0), + # Host interface: PCIe Gen5 x16 per chip, shared by both chiplets; raw + # 32 GT/s x 16 lanes / 8. + pcie=schema.PcieSpec(bandwidth_per_direction_gb_s=64.0), hbm=schema.HbmSpec(peak_bw_gb_s=7380.0), ) diff --git a/src/accelerator_microbenchmarks/specs/v6e.py b/src/accelerator_microbenchmarks/specs/v6e.py index b933fa5b..0018d525 100644 --- a/src/accelerator_microbenchmarks/specs/v6e.py +++ b/src/accelerator_microbenchmarks/specs/v6e.py @@ -22,5 +22,8 @@ link_bw_per_direction_gb_s=100.0, wraparound_rule=schema.WraparoundRule.PER_DIM_GE_16, ), + # Host interface: PCIe Gen5 x8 per chip + # (https://docs.cloud.google.com/tpu/docs/v6e), raw 32 GT/s x 8 lanes / 8. + pcie=schema.PcieSpec(bandwidth_per_direction_gb_s=32.0), hbm=schema.HbmSpec(peak_bw_gb_s=1638.4), ) diff --git a/tests/test_host_device.py b/tests/test_host_device.py index 559598c7..e9e544fa 100644 --- a/tests/test_host_device.py +++ b/tests/test_host_device.py @@ -2,6 +2,7 @@ import contextlib import csv +import dataclasses import itertools import json import os @@ -502,6 +503,95 @@ def test_get_run_identifier(self, backend, scope, local_index, expected): ) self.assertEqual(bm.get_run_identifier(), expected) + # --- Host-link roofline ------------------------------------------------- + + @parameterized.named_parameters(*_BENCHMARK_CLASSES) + def test_roofline_mode_is_host_device_link(self, bm_cls): + self.assertEqual( + bm_cls.roofline_mode, constants.RooflineMode.HOST_DEVICE_LINK + ) + + @parameterized.named_parameters( + # The 4 CPU devices form 2 chips under the tpu7x spec (2 devices per + # chip) and 4 chips under the v6e spec. + ("tpu7x_device_0", system.TPU7X_HARDWARE_SPEC, "device", 0, 64.0), + ("tpu7x_device_1", system.TPU7X_HARDWARE_SPEC, "device", 1, 64.0), + ("tpu7x_chip_1", system.TPU7X_HARDWARE_SPEC, "chip", 1, 64.0), + ("tpu7x_host", system.TPU7X_HARDWARE_SPEC, "host", 0, 128.0), + ("v6e_device_3", system.V6E_HARDWARE_SPEC, "device", 3, 32.0), + ("v6e_chip_2", system.V6E_HARDWARE_SPEC, "chip", 2, 32.0), + ("v6e_host", system.V6E_HARDWARE_SPEC, "host", 0, 128.0), + ) + def test_get_peak_host_link_bandwidth( + self, hw_spec, scope, local_index, expected + ): + """The peak is the per-chip PCIe peak times the chips measured.""" + for bm_cls, backend in itertools.product( + (_H2D, _D2H), ("tpu_sync", "jax") + ): + with self.subTest(bm_cls=bm_cls.__name__, backend=backend): + bm = self._make_benchmark( + bm_cls, + hardware_spec=hw_spec, + transfer_backend=backend, + scope=scope, + local_index=local_index, + ) + self.assertEqual(bm.get_peak_host_link_bandwidth(), expected) + + def test_get_peak_host_link_bandwidth_without_pcie_returns_none(self): + spec = dataclasses.replace(system.TPU7X_HARDWARE_SPEC, pcie=None) + bm = self._make_benchmark(_H2D, hardware_spec=spec) + with self.assertLogs(level="WARNING") as logs: + self.assertIsNone(bm.get_peak_host_link_bandwidth()) + self.assertIn("No PCIe host link", logs.output[0]) + + @parameterized.named_parameters( + # tpu7x spec on 4 CPU devices (2 chips). Per device, 4 MiB moves in + # 10 ms (wall clock, 0.4194304 GB/s) and 1 ms (xprof, 4.194304 GB/s). + ("h2d_jax_host", _H2D, "jax", "host", 128.0, 1.31072, 13.1072), + ("d2h_jax_device", _D2H, "jax", "device", 64.0, 0.65536, 6.5536), + ( + "h2d_tpu_sync_device", + _H2D, + "tpu_sync", + "device", + 64.0, + 0.65536, + 6.5536, + ), + ("d2h_tpu_sync_chip", _D2H, "tpu_sync", "chip", 64.0, 1.31072, 13.1072), + ("d2h_tpu_sync_host", _D2H, "tpu_sync", "host", 128.0, 1.31072, 13.1072), + ) + def test_apply_roofline_analysis( + self, + bm_cls, + backend, + scope, + expected_peak, + expected_wall_clock_pct, + expected_xprof_pct, + ): + """Only the measured scope gets a peak; efficiency uses that scope.""" + bm = self._setup_benchmark(bm_cls, transfer_backend=backend, scope=scope) + metrics = bm.calculate_metrics([10.0, 10.0, 10.0]) + metrics.update( + bm.calculate_throughput_metrics(1.0, constants.TimingDomain.XPROF) + ) + metrics = bm.apply_roofline_analysis(metrics) + self.assertEqual( + metrics[f"peak_link_bandwidth_per_{scope}_gb_s"], expected_peak + ) + self.assertAlmostEqual( + metrics["wall_clock_roofline_efficiency_pct"], expected_wall_clock_pct + ) + self.assertAlmostEqual( + metrics["xprof_roofline_efficiency_pct"], expected_xprof_pct + ) + for other_scope in {"device", "chip", "host"} - {scope}: + self.assertNotIn(f"peak_link_bandwidth_per_{other_scope}_gb_s", metrics) + self.assertEqual(metrics["roofline_bound_by"], "pcie") + # --- Report schema ------------------------------------------------------ @parameterized.named_parameters(*_LAYOUT_CASES) @@ -978,6 +1068,9 @@ def test_run_e2e(self, bm_cls, backend, scope): "memory_roofline_efficiency_pct", ): self.assertNotIn(key, metrics) + self.assertIn(f"peak_link_bandwidth_per_{scope}_gb_s", metrics) + self.assertIn("wall_clock_roofline_efficiency_pct", metrics) + self.assertEqual(metrics["roofline_bound_by"], "pcie") self.assertEqual(result.metadata.params["transfer_backend"], backend) self.assertEqual(result.metadata.params["scope"], scope) if backend == "tpu_sync": diff --git a/tests/test_roofline.py b/tests/test_roofline.py index 5548ddd5..79cb3b90 100644 --- a/tests/test_roofline.py +++ b/tests/test_roofline.py @@ -497,6 +497,60 @@ def test_apply_roofline_analysis_network_link_no_peak(self): res = roofline.apply_roofline_analysis(self.mock_benchmark, metrics) self.assertEqual(res, {"wall_clock_bandwidth_per_device_gb_s": 80.0}) + def _set_host_link(self, scope: str, peak: float | None) -> None: + self.mock_benchmark.roofline_mode = constants.RooflineMode.HOST_DEVICE_LINK + self.mock_benchmark.config = mock.Mock(scope=scope) + self.mock_benchmark.get_peak_host_link_bandwidth.return_value = peak + + def test_apply_roofline_analysis_host_link_uses_measured_scope(self): + """Verify HOST_DEVICE_LINK names the peak and efficiency by scope.""" + for scope in ("device", "chip", "host"): + with self.subTest(scope=scope): + self._set_host_link(scope, 200.0) + metrics = { + f"wall_clock_bandwidth_per_{scope}_gb_s": 150.0, + f"xprof_bandwidth_per_{scope}_gb_s": 180.0, + } + # Derived smaller-scope shares must not drive the efficiency. + if scope != "device": + metrics["wall_clock_bandwidth_per_device_gb_s"] = 1.0 + metrics["xprof_bandwidth_per_device_gb_s"] = 1.0 + res = roofline.apply_roofline_analysis(self.mock_benchmark, metrics) + self.assertEqual(res[f"peak_link_bandwidth_per_{scope}_gb_s"], 200.0) + self.assertAlmostEqual(res["wall_clock_roofline_efficiency_pct"], 75.0) + self.assertAlmostEqual(res["xprof_roofline_efficiency_pct"], 90.0) + other_scopes = {"device", "chip", "host"} - {scope} + for other in other_scopes: + self.assertNotIn(f"peak_link_bandwidth_per_{other}_gb_s", res) + self.assertEqual(res["roofline_bound_by"], "pcie") + + def test_apply_roofline_analysis_host_link_skips_missing_domain(self): + """Verify efficiency is only emitted for domains with a bandwidth.""" + self._set_host_link("host", 128.0) + metrics = { + "wall_clock_bandwidth_per_host_gb_s": 64.0, + "xprof_bandwidth_per_host_gb_s": None, + } + res = roofline.apply_roofline_analysis(self.mock_benchmark, metrics) + self.assertAlmostEqual(res["wall_clock_roofline_efficiency_pct"], 50.0) + self.assertNotIn("xprof_roofline_efficiency_pct", res) + + def test_apply_roofline_analysis_host_link_not_clamped(self): + """Verify efficiency above 100% is reported as-is.""" + self._set_host_link("chip", 64.0) + metrics = {"wall_clock_bandwidth_per_chip_gb_s": 80.0} + res = roofline.apply_roofline_analysis(self.mock_benchmark, metrics) + self.assertAlmostEqual(res["wall_clock_roofline_efficiency_pct"], 125.0) + + def test_apply_roofline_analysis_host_link_no_peak(self): + """Verify no host-link roofline keys are added without a positive peak.""" + for peak in (None, 0.0): + with self.subTest(peak=peak): + self._set_host_link("host", peak) + metrics = {"wall_clock_bandwidth_per_host_gb_s": 64.0} + res = roofline.apply_roofline_analysis(self.mock_benchmark, metrics) + self.assertEqual(res, {"wall_clock_bandwidth_per_host_gb_s": 64.0}) + if __name__ == "__main__": absltest.main() diff --git a/tests/test_system.py b/tests/test_system.py index b8f28e62..0b220ae6 100644 --- a/tests/test_system.py +++ b/tests/test_system.py @@ -197,6 +197,9 @@ def test_hardware_spec_tpu7x_presets(self): # Test die-to-die stats self.assertEqual(hw_spec.die_to_die.bandwidth_per_direction_gb_s, 800.0) + # PCIe Gen5 x16 host link per chip (raw). + self.assertEqual(hw_spec.pcie.bandwidth_per_direction_gb_s, 64.0) + # Test HBM stats self.assertEqual(hw_spec.hbm.peak_bw_gb_s, 7380.0) self.assertEqual(hw_spec.peak_hbm_bandwidth_per_device, 3690.0) @@ -231,6 +234,9 @@ def test_hardware_spec_v6e_presets(self): # One device per chip: no die-to-die link. self.assertIsNone(hw_spec.die_to_die) + # PCIe Gen5 x8 host link per chip (raw). + self.assertEqual(hw_spec.pcie.bandwidth_per_direction_gb_s, 32.0) + # Test HBM stats self.assertEqual(hw_spec.hbm.peak_bw_gb_s, 1638.4) self.assertEqual(hw_spec.peak_hbm_bandwidth_per_device, 1638.4)