Stop the rescorer falling to its memmap while RAM is free

[RobbinBouwmeester]

Reported as "rescoring is still very very slow". On the six-file Astral experiment the pooled rescore took 166 minutes for 3,133,636 PSMs × 387 features.

Cause

That matrix decodes to 4.52 GiB, and MUMDIA_NN_STREAM_GB was a fixed 4. So the worker chose its disk-backed memmap — over the line by 13%, on a machine with 96 GiB of RAM and 42 free. The recorded in-memory reference for a comparable pool is about 20 minutes, so the fixed threshold cost roughly 9×.

CLAUDE.md already documented this trap almost exactly: "a 4.31 GB matrix against the 4.00 GB default took the slow path". It had simply never been fixed.

Change

Unset, the threshold is now twice free physical memory, floored at the historical 4 GB so a machine too small to benefit is unaffected.

Greater than 1× on purpose: the memmap is a last resort, not a safety margin.

• between 1× and 2× free memory the operating system pages, which for this largely sequential access is far cheaper than the memmap's indexed minibatch reads;
• past that the paging thrashes and the memmap becomes the better of two bad options.

The consequence is deliberate and documented: in that band the rescore relies on the page file, so a machine without one (or with a small fixed one) should set MUMDIA_NN_STREAM_GB explicitly. That override works exactly as before.

machine	before	after
96 GiB, 41 free (the reporter's)	4.00 GB	82.1 GB
48 GiB, 40 free	4.00 GB	80.0 GB
8 GiB, 1 free	4.00 GB	4.00 GB (floor)

Free memory is read without a new dependency — psutil is not in the rescore environment and is not worth the resolver risk for one number — via GlobalMemoryStatusEx on Windows and MemAvailable on Linux, returning None anywhere else so the caller keeps the fixed default rather than guessing.

A correction to my own diagnosis

I told the reporter the worker was silent about this. It was not — it has always printed the backend and the sizes. That line was lost among the DeepLC blank lines that #84 has since removed. It now additionally reports where the threshold came from, and warns plainly when the slow path was taken for want of memory.

Validation

pytest tests/python — 85 passed, 8 skipped (two new tests: the multiplier is >1 so the memmap is never preferred over paging, the floor holds, the threshold explains itself, and reading free memory is optional and never fatal). Also passes on a bare interpreter with no ML dependencies. Config reference regenerated for the changed env-var documentation.

🤖 Generated with Claude Code