docs: name peak memory as the MLX allocator peak

[kevin9327]

Summary

The Benchmark table and Requirements section said "peak active memory". That number comes from mlx.core.get_peak_memory() (Metal allocator high-water mark), not process RSS. Readers took ~2.9 GB as the machine requirement; the paper's process footprints are roughly 2× the allocator peak.

• Rename the table column to Peak MLX allocator memory
• Clarify Requirements and the benchmark footnote
• Match examples/bench.py labels (mlx_allocator_peak=…)

Test plan

• test_readme_names_peak_memory_as_mlx_allocator (new hygiene guard) passes
• Table header no longer says "Peak active memory"

Fixes #106

[shuk777]

Thanks for tightening this and sorry for our late review. The column rename is the right fix: examples/bench.py records mlx.core.get_peak_memory() after decode, and "peak active memory" is what led readers in #106 to take 2.9 GB as the machine requirement. The measured 2.9 GiB / 1.0 GiB figures should stay as they are.

Three changes before this can land:

1. python/examples/bench.py module docstring. The previous line already ends with "and MLX", and the new line starts with "MLX allocator…", so it reads "tok/s and MLX MLX allocator peak memory". Drop the extra "MLX".

2. Requirements wording. README "peak active memory" is the MLX allocator peak, not process memory; hot-expert backing is anonymous memory #106 is closed on the conclusion that we report the allocator high-water mark on purpose: RSS above that is reclaimable and does not set the machine requirement (the same build runs on a 16 GB M2). The new sentence that process footprints are roughly 2× the allocator peak sits next to the README's 2.9 GB row, which was measured on a 24 GB M4 Pro. The ~2× figures in the issue are the paper's 16 GB M2 K=2/4/8 runs (allocator 2.33 / 2.60 / 3.22 GiB, process 4.91 / 5.61 / 6.39 GiB), not this table. Please remove that sentence, or move it so it is clearly about those M2 runs and still says the extra RSS is reclaimable.

3. python/README.md still has the same "Peak active memory" column. The new hygiene test only reads the repo-root README.md and does not assert that the old header is gone, so that copy can stay stale. Please update it the same way, and assert the old header is absent.

The peak_active= → mlx_allocator_peak= print label is fine. The returned peak_gib field is unchanged, and nothing in the repo parses the old print string.

[shuk777]

Requesting changes on two edits. The column rename, the footnote, the bench.py print labels, and the new hygiene test are fine.

The module docstring now reads "MLX MLX", and the Requirements sentence about a 2× process footprint conflicts with the conclusion already recorded on #106.

[shuk777]

The line above already ends with "and MLX", so this now reads "report tok/s and MLX MLX allocator peak memory". Drop the leading "MLX" on this line, for example: allocator peak memory (mlx.core.get_peak_memory()).

[shuk777]

The rename on this bullet ("MLX allocator peak" and "not process RSS") is right. This sentence is not.

#106 is closed on a different conclusion: we report the allocator high-water mark on purpose, because RSS above it is reclaimable and does not set the machine requirement. The same build runs on a 16 GB M2.

"Roughly 2×" here sits next to the 2.9 GB figure, which was measured on a 24 GB M4 Pro. The ~2× pair in the issue is the paper's 16 GB M2 K=2/4/8 runs (allocator 2.33 / 2.60 / 3.22 GiB, process 4.91 / 5.61 / 6.39 GiB), not this row. Please remove the sentence, or scope it to those M2 runs and say the extra RSS is reclaimable.

[kevin9327]

Thanks for the detailed review. Pushed 2924af9:

1. bench.py docstring: dropped the duplicated "MLX".
2. Requirements: removed the ~2× process-footprint sentence. It now says the extra RSS beyond the allocator peak is reclaimable and does not set the machine requirement (the same build runs on a 16 GB M2).
3. python/README.md: renamed the "Peak active memory" column to "Peak MLX allocator memory", fixed the Memory row, and added the same footnote. The hygiene test is now parametrized over both READMEs and asserts "peak active" is gone (it fails on the old python/README.md).

pytest tests/test_repo_hygiene.py: 6 passed.

[shuk777]

The two requested edits are in 2924af9.

The bench.py docstring now reads "MLX allocator peak memory" without the duplicated "MLX". The Requirements bullet drops the ~2× process-footprint sentence and says the extra RSS is reclaimable and does not set the machine requirement.