refactor: use architecture-neutral memory bandwidth terms instead of HBM

[mehdi-saeedi]

Summary

TraceLens calls the memory-bandwidth ceiling "HBM" in code, Agent prompts and docs. That's accurate for MI300X, but not for GPUs that use GDDR6 (for example R9700) or that share LPDDR5X with the CPU, such as the Radeon 8060S (gfx1151) arch file already in utils/arch/. This PR follows the name the arch JSON already uses (mem_bw_gbps, next to l1_bw_gbps). It's a rename only: no computed values change.

"Device memory" was the other candidate, but it's wrong on APUs, where the GPU has no memory of its own. It also clashes with how TraceLens already uses "device" for H2D, D2H and D2D copies.

Part	Memory	HBM	Device memory	Memory (mem)
MI300X	HBM3, discrete	✓	✓	✓
R9700	GDDR6, discrete	✗	✓	✓
Radeon 8060S (Strix Halo)	LPDDR5X, shared with CPU	✗	✗	✓
MI300A	HBM3, shared with CPU	✓	✗	✓

What changes

Today	Proposed
peak_hbm_bw_tbs (Agent metadata, category_specific, kernel-fusion metrics)	peak_mem_bw_tbs
resolved_peak_hbm_bw (per-op efficiency)	resolved_peak_mem_bw
peak_hbm_bw argument of calculate_efficiency and calculate_efficiency_with_validation	peak_mem_bw
bench_hbm_bandwidth, bench_hbm_bandwidth_sweep, run_shape_sweep(include_hbm=) (microbench)	bench_mem_bandwidth, bench_mem_bandwidth_sweep, include_mem=
Sweep JSON hbm_rows, hbm_best, "sweep_type": "gemm_and_hbm"	mem_rows, mem_best, "gemm_and_mem"
"peak HBM BW" (Agent prompts, report template, eval rubrics, docs)	"peak memory BW"
"HBM traffic" (perf-model docstrings)	"DRAM traffic"

The new metadata key is written everywhere in one change. A new helper, get_peak_mem_bw_tbs(), still reads peak_hbm_bw_tbs from older output directories. This matters because build_operation_metrics otherwise falls back to 1 TB/s when the key is missing.

The eval rubrics are updated together with the report template, so LLM-graded evals look for "memory BW" in the Hardware Reference section.

What still says HBM after this PR

Item	Why it stays
peak_hbm_bw_tbs when reading older output directories	Accepted on read, never written
--hbm_bw flag passed to the GEMM simulator (perf_model.py)	The flag belongs to the external simulator
MI300X worked example (perf-model-without-trace.md and its notebook)	Its numbers are MI300X's HBM3 bandwidth
Sample MI300X Agent report in the Agent README	Quoted output from a real MI300X run

Compatibility

• Code outside TraceLens that calls the renamed microbench functions or the renamed keyword arguments, or that reads the renamed output keys, needs to update. I can add thin aliases for the old function names if you'd prefer.
• If a metadata file stores null for the bandwidth, kernel fusion's load_arch_config now falls back to the arch JSON instead of returning None. The metadata code never writes null.
• Report columns and units, the arch JSON schema, and the arch values are unchanged. No reference outputs were regenerated (--update-references was not used).

Test plan

• pytest tests/test_analysis_agent_utils.py tests/test_analysis_agent_category_utils.py tests/test_analysis_agent_evals.py tests/test_perfmodel_benchmarking.py tests/test_perfmodel_extensions.py tests/test_reporting_utils.py tests/test_util.py: 1180 passed, 25 skipped (torch-only microbench tests)
• New tests for the legacy-key fallback: the new key takes precedence, the legacy key is read, the default applies when both are missing, and both build_operation_metrics and load_arch_config read legacy metadata
• Full pytest tests/: 3178 passed. The failures were the same 30 tests, which also fail on main in my environment because the [jax] extra and setuptools aren't installed there
• black==26.3.1 --check, ruff check --select F401,F841,RET502,RET503, lint-imports, git diff --check on changed files
• Run microbench.py on a GPU (the renamed functions aren't exercised by CPU-only CI)

[mehdi-saeedi]

@mohbasit could you review this when you get a chance? It's a terminology-only rename (HBM to memory bandwidth) with a read fallback for older metadata. Details are in the description. Thanks!

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[ajassani]

Thanks Mehdi, +1 on dropping "HBM". I checked the scope against main:

What this does and doesn't touch

• The core perf report (Reporting/, TreePerf/) never uses "HBM". The roofline bound, Roofline Time (µs) and Pct Roofline all read mem_bw_gbps straight from the arch JSON (TreePerfAnalyzer.compute_perf_metrics in tree_perf.py). Report columns and the compute/memory-bound logic are unchanged by this PR.
• There's only one source for the bandwidth number. microbench.py writes mem_bw_gbps (max of copy-read and fill-write). The Agent derives peak_*_bw_tbs = mem_bw_gbps / 1000 in orchestrator_prepare.py. "HBM" was only a label on that derived copy, plus microbench function names and the --shape-sweep diagnostic JSON.
• The Agent's bound_type comes from the report's Roofline Bound column and efficiency_percent from Pct Roofline_mean. The renamed peak only feeds the displayed reference (resolved_peak_mem_bw), the >100% sanity warnings and kernel-fusion impact estimates, and its values don't change.

[gabeweisz]

Based on Adeem's opinion that this will not break things for other users, I am on board with this change

[tsrikris]

@mehdi-saeedi could we pls update this branch to track the changes in #1077? (staging_agent). These changes have gone through a round of evals so I'd get those into main today and then merge in yours.

[mehdi-saeedi]

@tsrikris done. The branch is now rebased on staging_agent (#1077 head 0ac91cdf) with no conflicts. Until #1077 merges, this PR's diff vs main includes #1077's commits; after that it's back to just the rename.

The rebase also covers the HBM mentions #1077 added:

• tests/test_analysis_agent_utils.py: two test inputs now use peak_mem_bw_tbs.
• tests/test_analysis_agent_post_processing.py: the sample report now says "Peak Memory BW" and "DRAM round-trip", matching the updated template and analyzer prompts.

There's no HBM in #1077's Agent code or prompts. All Agent test files plus util, reporting and perf-model tests: 1641 passed. black, ruff, lint-imports and git diff --check are clean.

[tsrikris]

@mehdi-saeedi can you point this PR to main? It's pointing to another branch by the looks of it

[mehdi-saeedi]

@tsrikris thanks, fixed. The PR already targeted main, but after #1077 was squash-merged the branch still carried the original staging_agent commits. It's now a single commit on top of current main (e2458a34): 1 commit, 36 files, mergeable.

#1058 and #1051 landed since then and add no new HBM mentions. Agent, util, reporting and perf-model tests: 1641 passed.

[tsrikris]

@mehdi-saeedi LGTM from Agent PoV. One comment to confirm that the analysis.json generated and used in Hyperloom is not affected.

[ajassani]

Looks good to me
One nit:
"HBM traffic" (perf-model docstrings) "DRAM traffic"
should we just call it Memory traffic instead of DRAM traffic?

[mehdi-saeedi]

@tsrikris confirmed: the analysis.json that Hyperloom reads is unaffected.

• analysis.json is rendered from analysis.md. This PR doesn't touch the renderer or its schema (post_processing/), so every field keeps its name. efficiency_peak_unit is parsed from strings like "X% of Y TB/s", and the units don't change.
• The only analysis.md change is the free-text label in the Hardware Reference section ("Peak memory BW"). Hyperloom doesn't parse that section.
• Hyperloom writes its arch JSON with mem_bw_gbps, which is unchanged. It doesn't read peak_hbm_bw_tbs or the shape-sweep JSON, and doesn't call the renamed microbench functions.

@ajassani agreed, done in ba2f7a1. The perf-model docstrings now say "memory traffic" (and "memory bytes", "memory accounting", "memory read/write"). The two places that contrast on-chip storage (the MoE analyzer prompt and the matching sample report in tests/test_analysis_agent_post_processing.py) now say "round-trip through global memory". The three "DRAM traffic" docstrings in perf_model.py predate this PR, so I left them. black is clean; Agent post-processing, Agent utils, category utils and perf-model extension tests: 818 passed.

[devalshahamd]

LGTM!