pichak 0.1.0__tar.gz

pichak-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/

pichak-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksandr Pichak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pichak-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.5
+Name: pichak
+Version: 0.1.0
+Summary: Derive fine-tuning hyperparameters from measurements of your actual machine, and print the measurement behind every number.
+Project-URL: Homepage, https://github.com/olesxg/pichak
+Project-URL: Findings, https://github.com/olesxg/flap-findings
+Author-email: Oleksandr Pichak <stasselust@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: batch-size,benchmark,fine-tuning,gpu,hyperparameters,learning-rate,llm,lora,vram
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: hf
+Requires-Dist: safetensors>=0.4; extra == 'hf'
+Requires-Dist: torch>=2.0; extra == 'hf'
+Requires-Dist: transformers>=4.40; extra == 'hf'
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == 'torch'
+Description-Content-Type: text/markdown
+
+# pichak
+
+**Fine-tuning hyperparameters derived from your machine, with the measurement
+printed next to every number.**
+
+```bash
+pip install pichak
+```
+
+```python
+from pichak import derive
+
+plan = derive(
+    data="train.jsonl",
+    tokenizer=tok,
+    step_fn=lambda b: one_real_forward_and_backward(b),
+    named_weights=model.named_parameters(),
+)
+print(plan.report())
+```
+
+```
+  seq_len            512
+                     token p95 416 over 512 real rows, rounded up to 512; p99 is
+                     657 and max 943, so 5% of rows lose their tail at this length
+
+  micro_batch        3
+                     a doubling ramp with a real forward+backward at each rung:
+                     1=ok, 2=ok, 4=ok, 8=SPILL. 8 SPILLED to system memory — it did
+                     not raise, it got 1.6x slower per sample, which is the Windows
+                     failure mode, so 4 is the largest that fit, peaking at 5.05GB
+                     of 5.05GB; kept 3 to leave 12% for optimizer state
+
+  learning_rate      0.000282
+                     1/32 of the scale at which one Adam step would rewrite rather
+                     than perturb. ||W||_F/sqrt(numel) over 26 matrices; the
+                     smallest binds and it is b.1.f.2.weight at 0.00902
+
+  NOT MEASURED (1): target_tokens=65536
+```
+
+---
+
+## Why not just use a good default
+
+Because you cannot tell a good default from a bad one when it fails.
+
+`micro_batch=4` tells you nothing about whether 4 came from a measurement on your
+card, a heuristic in a blog post, or a number someone picked in 2023 for a
+different model. So when it OOMs at step 40 you bisect instead of reading.
+
+Every number `pichak` returns carries the sentence that produced it. Anything it
+could **not** measure is collected under `plan.constants()` and printed together,
+so a constant can never quietly pass for a derivation.
+
+```python
+plan.micro_batch          # 3
+plan.why("micro_batch")   # the ramp, rung by rung, and which one failed
+plan.constants()          # {'target_tokens': 65536}
+```
+
+## It catches the failure that does not raise
+
+On Windows, a batch that exceeds VRAM does not throw. The driver pages the excess
+to system memory and the step simply crawls. Measured on a GTX 1060 6GB with a
+6-layer model at sequence 512:
+
+| | micro_batch | peak | seconds/step |
+|---|---|---|---|
+| watching only for OOM | 14 | **18.24GB** on a 6GB card | 47.5 |
+| watching per-sample time too | 3 | 5.05GB | **2.0** |
+
+Both "work". The first is 23x slower and nothing in the logs says why. On a healthy
+ramp, seconds-per-sample is flat or improves as the batch grows — bigger batches
+amortise fixed costs. A sudden jump means the batch did not really fit.
+
+## What it derives, and from what
+
+| | measurement |
+|---|---|
+| `seq_len` | tokenised p95 over 512 real rows of your corpus |
+| `loss_policy` | whether the rows have a separable completion to mask against |
+| `micro_batch` | a doubling ramp with a real forward+backward at each rung |
+| `seconds_per_step` | the wall time of that rung |
+| `grad_accum` | micro-batch x seq_len against your token target |
+| `lora_rank` | largest rung whose optimizer state fits — fp32 master, two Adam moments, and one step's gradients, which is the copy count people forget |
+| `learning_rate` | the model's own Frobenius norms: the step size at which one Adam update would rewrite a weight rather than perturb it |
+
+Everything is optional. Pass only a corpus and a tokenizer and you get a sequence
+length; pass a `step_fn` and you get the batch. It will not invent a number it
+could not measure — a plan with three derived values and an honest gap is more
+useful than one with ten you cannot tell apart.
+
+## The learning rate, since it is the surprising one
+
+An Adam update moves a parameter by roughly `lr`, whatever the gradient's scale. So
+there is a learning rate at which one step rewrites a weight matrix instead of
+nudging it: where `lr * sqrt(numel(W))` reaches `||W||_F`. Every sane learning rate
+is a fraction of that, and the fraction is what schedules argue about.
+
+Measured, at the ranks behind this library:
+
+```
+rewrite/2    2.26e-3   destroyed the model twice (CE 1.74 -> 10.4, 1.11 -> 19.3)
+rewrite/32   1.41e-4   the first scale that actually learned
+rewrite/45             where a hand-tuned LoRA run at 2e-4 landed
+```
+
+`pichak` opens at `rewrite/32` — the top of the range that works. Opening hot costs
+the model; opening cold costs time. With a penalty that asymmetric you start at the
+bottom of what is known.
+
+This is not tuned for your dataset. It is the scale at which updates are the right
+*size* for these weights. It replaces "I copied 2e-4 from a post about a different
+model", which is the actual alternative.
+
+## Measurement tools, usable on their own
+
+```bash
+pichak gpu                    # virtualisation, launch latency, transfer bandwidth
+pichak disk "models/*.safetensors"   # queue-depth sweep, page cache bypassed
+pichak corpus train.jsonl mistralai/Mistral-Small-24B-Instruct-2501
+```
+
+```python
+from pichak.measure import disk_queue_depth, transfer_bandwidth, virtualisation
+```
+
+These exist because the numbers people quote are rarely the numbers their machine
+gives:
+
+- A buffered disk benchmark reported **4079 MB/s on a drive rated 2100** — that was
+  the page cache. Unbuffered, the same drive peaks at **queue depth 3** and gets
+  *slower* past it.
+- A rented A6000 measured **D2H 457 MB/s against H2D 1502**, and pinned memory —
+  the standard fix — bought nothing. Nothing about PCIe explains that; it was a
+  fabric, and it decided where hidden states could live.
+- One rented machine had **84.8us kernel launches** against a normal 2-5. A
+  workload issuing 400,000 launches per step would have spent nine hours on
+  overhead and looked slower than a 2016 card.
+
+## Install
+
+```bash
+pip install pichak            # the plan, the disk sweep — no dependencies
+pip install pichak[torch]     # the ramp, the learning rate, the GPU measurements
+pip install pichak[hf]        # + transformers, for the corpus CLI
+```
+
+Python 3.9+. The core has **no dependencies at all**; torch is only needed for the
+parts that touch a GPU.
+
+## Where the numbers come from
+
+Every measurement quoted here was made while fine-tuning a 24B model on a 6GB
+GTX 1060 and on a rented A6000 held down to the same 6GB. The raw logs — including
+the six runs that failed before one worked — are at
+[flap-findings](https://github.com/olesxg/flap-findings), along with the five
+hypotheses that sounded right and were wrong.
+
+## Licence
+
+MIT. By [Oleksandr Pichak](https://github.com/olesxg).

pichak-0.1.0/README.md

@@ -0,0 +1,163 @@
+# pichak
+
+**Fine-tuning hyperparameters derived from your machine, with the measurement
+printed next to every number.**
+
+```bash
+pip install pichak
+```
+
+```python
+from pichak import derive
+
+plan = derive(
+    data="train.jsonl",
+    tokenizer=tok,
+    step_fn=lambda b: one_real_forward_and_backward(b),
+    named_weights=model.named_parameters(),
+)
+print(plan.report())
+```
+
+```
+  seq_len            512
+                     token p95 416 over 512 real rows, rounded up to 512; p99 is
+                     657 and max 943, so 5% of rows lose their tail at this length
+
+  micro_batch        3
+                     a doubling ramp with a real forward+backward at each rung:
+                     1=ok, 2=ok, 4=ok, 8=SPILL. 8 SPILLED to system memory — it did
+                     not raise, it got 1.6x slower per sample, which is the Windows
+                     failure mode, so 4 is the largest that fit, peaking at 5.05GB
+                     of 5.05GB; kept 3 to leave 12% for optimizer state
+
+  learning_rate      0.000282
+                     1/32 of the scale at which one Adam step would rewrite rather
+                     than perturb. ||W||_F/sqrt(numel) over 26 matrices; the
+                     smallest binds and it is b.1.f.2.weight at 0.00902
+
+  NOT MEASURED (1): target_tokens=65536
+```
+
+---
+
+## Why not just use a good default
+
+Because you cannot tell a good default from a bad one when it fails.
+
+`micro_batch=4` tells you nothing about whether 4 came from a measurement on your
+card, a heuristic in a blog post, or a number someone picked in 2023 for a
+different model. So when it OOMs at step 40 you bisect instead of reading.
+
+Every number `pichak` returns carries the sentence that produced it. Anything it
+could **not** measure is collected under `plan.constants()` and printed together,
+so a constant can never quietly pass for a derivation.
+
+```python
+plan.micro_batch          # 3
+plan.why("micro_batch")   # the ramp, rung by rung, and which one failed
+plan.constants()          # {'target_tokens': 65536}
+```
+
+## It catches the failure that does not raise
+
+On Windows, a batch that exceeds VRAM does not throw. The driver pages the excess
+to system memory and the step simply crawls. Measured on a GTX 1060 6GB with a
+6-layer model at sequence 512:
+
+| | micro_batch | peak | seconds/step |
+|---|---|---|---|
+| watching only for OOM | 14 | **18.24GB** on a 6GB card | 47.5 |
+| watching per-sample time too | 3 | 5.05GB | **2.0** |
+
+Both "work". The first is 23x slower and nothing in the logs says why. On a healthy
+ramp, seconds-per-sample is flat or improves as the batch grows — bigger batches
+amortise fixed costs. A sudden jump means the batch did not really fit.
+
+## What it derives, and from what
+
+| | measurement |
+|---|---|
+| `seq_len` | tokenised p95 over 512 real rows of your corpus |
+| `loss_policy` | whether the rows have a separable completion to mask against |
+| `micro_batch` | a doubling ramp with a real forward+backward at each rung |
+| `seconds_per_step` | the wall time of that rung |
+| `grad_accum` | micro-batch x seq_len against your token target |
+| `lora_rank` | largest rung whose optimizer state fits — fp32 master, two Adam moments, and one step's gradients, which is the copy count people forget |
+| `learning_rate` | the model's own Frobenius norms: the step size at which one Adam update would rewrite a weight rather than perturb it |
+
+Everything is optional. Pass only a corpus and a tokenizer and you get a sequence
+length; pass a `step_fn` and you get the batch. It will not invent a number it
+could not measure — a plan with three derived values and an honest gap is more
+useful than one with ten you cannot tell apart.
+
+## The learning rate, since it is the surprising one
+
+An Adam update moves a parameter by roughly `lr`, whatever the gradient's scale. So
+there is a learning rate at which one step rewrites a weight matrix instead of
+nudging it: where `lr * sqrt(numel(W))` reaches `||W||_F`. Every sane learning rate
+is a fraction of that, and the fraction is what schedules argue about.
+
+Measured, at the ranks behind this library:
+
+```
+rewrite/2    2.26e-3   destroyed the model twice (CE 1.74 -> 10.4, 1.11 -> 19.3)
+rewrite/32   1.41e-4   the first scale that actually learned
+rewrite/45             where a hand-tuned LoRA run at 2e-4 landed
+```
+
+`pichak` opens at `rewrite/32` — the top of the range that works. Opening hot costs
+the model; opening cold costs time. With a penalty that asymmetric you start at the
+bottom of what is known.
+
+This is not tuned for your dataset. It is the scale at which updates are the right
+*size* for these weights. It replaces "I copied 2e-4 from a post about a different
+model", which is the actual alternative.
+
+## Measurement tools, usable on their own
+
+```bash
+pichak gpu                    # virtualisation, launch latency, transfer bandwidth
+pichak disk "models/*.safetensors"   # queue-depth sweep, page cache bypassed
+pichak corpus train.jsonl mistralai/Mistral-Small-24B-Instruct-2501
+```
+
+```python
+from pichak.measure import disk_queue_depth, transfer_bandwidth, virtualisation
+```
+
+These exist because the numbers people quote are rarely the numbers their machine
+gives:
+
+- A buffered disk benchmark reported **4079 MB/s on a drive rated 2100** — that was
+  the page cache. Unbuffered, the same drive peaks at **queue depth 3** and gets
+  *slower* past it.
+- A rented A6000 measured **D2H 457 MB/s against H2D 1502**, and pinned memory —
+  the standard fix — bought nothing. Nothing about PCIe explains that; it was a
+  fabric, and it decided where hidden states could live.
+- One rented machine had **84.8us kernel launches** against a normal 2-5. A
+  workload issuing 400,000 launches per step would have spent nine hours on
+  overhead and looked slower than a 2016 card.
+
+## Install
+
+```bash
+pip install pichak            # the plan, the disk sweep — no dependencies
+pip install pichak[torch]     # the ramp, the learning rate, the GPU measurements
+pip install pichak[hf]        # + transformers, for the corpus CLI
+```
+
+Python 3.9+. The core has **no dependencies at all**; torch is only needed for the
+parts that touch a GPU.
+
+## Where the numbers come from
+
+Every measurement quoted here was made while fine-tuning a 24B model on a 6GB
+GTX 1060 and on a rented A6000 held down to the same 6GB. The raw logs — including
+the six runs that failed before one worked — are at
+[flap-findings](https://github.com/olesxg/flap-findings), along with the five
+hypotheses that sounded right and were wrong.
+
+## Licence
+
+MIT. By [Oleksandr Pichak](https://github.com/olesxg).

pichak-0.1.0/pichak/__init__.py

@@ -0,0 +1,29 @@
+"""pichak — derive fine-tuning hyperparameters from your machine, not from a blog.
+
+    from pichak import derive
+    plan = derive(data="train.jsonl", tokenizer=tok,
+                  step_fn=lambda b: one_real_step(b),
+                  named_weights=model.named_parameters())
+    print(plan.report())
+
+Every number comes back with the measurement that produced it, and anything NOT
+measured is listed together under `plan.constants()` so a constant can never pass
+for a derivation.
+
+By Oleksandr Pichak. The measurements this is built on, including the wrong turns,
+are at https://github.com/olesxg/flap-findings
+"""
+
+from .plan import CONSTANT, Plan, Value
+from .tune import (adapter_bytes_per_rank, auto_rank, derive, derive_lr,
+                   grad_accum_for, profile_corpus, ramp_micro_batch,
+                   rewrite_scale)
+
+__version__ = "0.1.0"
+__author__ = "Oleksandr Pichak"
+__all__ = [
+    "derive", "Plan", "Value", "CONSTANT",
+    "profile_corpus", "ramp_micro_batch", "auto_rank", "adapter_bytes_per_rank",
+    "grad_accum_for", "derive_lr", "rewrite_scale",
+    "__version__", "__author__",
+]

pichak-0.1.0/pichak/__main__.py

@@ -0,0 +1,64 @@
+"""`pichak` on the command line — measure this machine, print what it gives.
+
+    pichak gpu                 virtualisation, launch latency, transfer bandwidth
+    pichak disk <glob>         queue-depth sweep with the page cache bypassed
+    pichak corpus <jsonl> <tokenizer>   sequence length from real rows
+"""
+import sys
+
+
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    cmd = argv[0] if argv else "help"
+
+    if cmd == "gpu":
+        from .measure import kernel_launch_us, transfer_bandwidth, virtualisation
+        v = virtualisation()
+        print(f"gpu          : {v['gpu']}")
+        print(f"virt mode    : {v['virtualisation_mode']}")
+        print(f"host         : {v['host']}   ({v['note']})")
+        if v["virtualised"]:
+            print("\nVIRTUALISED — every timing below is the hypervisor's, not "
+                  "the card's.")
+        try:
+            import torch
+        except ImportError:
+            print("\ntorch is not installed; install pichak[torch] for the rest.")
+            return 2
+        if not torch.cuda.is_available():
+            print("\nno CUDA visible.")
+            return 2
+        us = kernel_launch_us(torch)
+        print(f"\nkernel launch: {us:.1f} us "
+              f"(2-5 normal passthrough; 85 seen on a network-attached vGPU)")
+        print("  judge this as a SHARE of your step, never in raw microseconds")
+        print()
+        print(transfer_bandwidth(torch).describe())
+        return 0
+
+    if cmd == "disk":
+        if len(argv) < 2:
+            print("usage: pichak disk <glob of several large files>")
+            return 2
+        from .measure import disk_queue_depth
+        disk_queue_depth(argv[1:])
+        return 0
+
+    if cmd == "corpus":
+        if len(argv) < 3:
+            print("usage: pichak corpus <train.jsonl> <tokenizer-name-or-path>")
+            return 2
+        from transformers import AutoTokenizer
+        from .tune import profile_corpus
+        tok = AutoTokenizer.from_pretrained(argv[2])
+        prof = profile_corpus(argv[1], tok)
+        print(prof.describe())
+        print(f"\nseq_len {prof.seq_len}\n  {prof.seq_source}")
+        return 0
+
+    print(__doc__)
+    return 0 if cmd in ("help", "-h", "--help") else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pichak-0.1.0/pichak/measure/__init__.py

@@ -0,0 +1,15 @@
+"""Measurements that answer one question each, with no training loop attached.
+
+    from pichak.measure import disk_queue_depth, transfer_bandwidth
+
+These exist because the numbers people quote for storage and PCIe are almost never
+the numbers their machine gives. A buffered disk benchmark on a host with free RAM
+reports the page cache; a rented GPU can have a 3.4x asymmetry between its transfer
+directions that no datasheet mentions.
+"""
+
+from .disk import disk_queue_depth
+from .gpu import kernel_launch_us, transfer_bandwidth, virtualisation
+
+__all__ = ["disk_queue_depth", "kernel_launch_us", "transfer_bandwidth",
+           "virtualisation"]

pichak-0.1.0/pichak/measure/disk.py

@@ -0,0 +1,144 @@
+"""How many concurrent readers does this drive actually want?
+
+WHY YOU CANNOT USE A BUFFERED BENCHMARK. The first version of this measurement,
+run with ordinary `open()`, reported:
+
+    QD1  1158 MB/s     QD4   781 MB/s   <- slower than one reader
+    QD8  4079 MB/s     <- above the drive's rated 2100
+
+Those are the OS page cache answering, not the disk. If a storage benchmark tells
+you more than the hardware can do, it has stopped measuring the hardware. On
+Windows this bypasses it with `FILE_FLAG_NO_BUFFERING`, which is why the reads have
+to be sector-aligned and why this goes through ctypes.
+
+WHAT IT FOUND. On a DRAM-less Kingston NV1:
+
+    QD1 1017 MB/s   QD2 1655   QD3 1703 (optimum)   QD4 1535   QD8 1035
+
+More threads is not more throughput. A DRAM-less controller degrades past its sweet
+spot rather than saturating, so past QD3 it simply loses — and eight readers, the
+number a reasonable person would pick, is no better than one.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import glob
+import os
+import sys
+import time
+from concurrent.futures import ThreadPoolExecutor
+from typing import Dict, List, Optional, Sequence
+
+MB = 1024 ** 2
+SECTOR = 4096
+
+
+def _unbuffered_reader():
+    """(reader, available) — an unbuffered read on Windows, else plain reads."""
+    if not sys.platform.startswith("win"):
+        def posix(path: str, off: int, nbytes: int, block: int) -> int:
+            # O_DIRECT needs alignment and is not portable across filesystems;
+            # POSIX_FADV_DONTNEED after the read is the honest compromise.
+            fd = os.open(path, os.O_RDONLY)
+            got = 0
+            try:
+                os.lseek(fd, off, os.SEEK_SET)
+                while got < nbytes:
+                    b = os.read(fd, min(block, nbytes - got))
+                    if not b:
+                        break
+                    got += len(b)
+                if hasattr(os, "posix_fadvise"):
+                    os.posix_fadvise(fd, off, nbytes, os.POSIX_FADV_DONTNEED)
+            finally:
+                os.close(fd)
+            return got
+        return posix, False
+
+    k32 = ctypes.WinDLL("kernel32", use_last_error=True)
+    from ctypes import wintypes
+    GENERIC_READ, FILE_SHARE_READ, OPEN_EXISTING = 0x80000000, 1, 3
+    NO_BUFFERING, SEQUENTIAL = 0x20000000, 0x08000000
+    MEM_COMMIT_RESERVE, PAGE_RW, MEM_RELEASE = 0x3000, 4, 0x8000
+    k32.CreateFileW.restype = wintypes.HANDLE
+    k32.CreateFileW.argtypes = [wintypes.LPCWSTR, wintypes.DWORD, wintypes.DWORD,
+                                ctypes.c_void_p, wintypes.DWORD, wintypes.DWORD,
+                                wintypes.HANDLE]
+    k32.VirtualAlloc.restype = ctypes.c_void_p
+    k32.VirtualAlloc.argtypes = [ctypes.c_void_p, ctypes.c_size_t,
+                                 wintypes.DWORD, wintypes.DWORD]
+    k32.ReadFile.argtypes = [wintypes.HANDLE, ctypes.c_void_p, wintypes.DWORD,
+                             ctypes.POINTER(wintypes.DWORD), ctypes.c_void_p]
+    k32.SetFilePointerEx.argtypes = [wintypes.HANDLE, ctypes.c_longlong,
+                                     ctypes.c_void_p, wintypes.DWORD]
+
+    def win(path: str, off: int, nbytes: int, block: int) -> int:
+        h = k32.CreateFileW(path, GENERIC_READ, FILE_SHARE_READ, None,
+                            OPEN_EXISTING, NO_BUFFERING | SEQUENTIAL, None)
+        if h == wintypes.HANDLE(-1).value:
+            raise OSError(ctypes.get_last_error())
+        buf = k32.VirtualAlloc(None, block, MEM_COMMIT_RESERVE, PAGE_RW)
+        got, done = 0, wintypes.DWORD(0)
+        try:
+            k32.SetFilePointerEx(h, ctypes.c_longlong(off), None, 0)
+            while got < nbytes:
+                if not k32.ReadFile(h, ctypes.c_void_p(buf), block,
+                                    ctypes.byref(done), None):
+                    raise OSError(ctypes.get_last_error())
+                if done.value == 0:
+                    break
+                got += done.value
+        finally:
+            k32.VirtualFree(ctypes.c_void_p(buf), 0, MEM_RELEASE)
+            k32.CloseHandle(h)
+        return got
+    return win, True
+
+
+def disk_queue_depth(paths: Sequence[str], *, depths: Sequence[int] = (1, 2, 3, 4, 6, 8),
+                     chunk_mb: int = 256, block_mb: int = 8,
+                     log=print) -> Dict[int, float]:
+    """MB/s at each queue depth. Returns {depth: rate}, and prints as it goes.
+
+    ``paths`` should be several large files — model shards are ideal. Workers read
+    DIFFERENT files at DIFFERENT offsets so that a second reader cannot be served
+    from the first one's readahead.
+    """
+    files = [p for pat in paths for p in sorted(glob.glob(pat))] if any(
+        "*" in p or "?" in p for p in paths) else list(paths)
+    files = [f for f in files if os.path.isfile(f)]
+    if not files:
+        raise FileNotFoundError(f"no readable files in {list(paths)!r}")
+
+    read, unbuffered = _unbuffered_reader()
+    if not unbuffered:
+        log("  note: unbuffered reads are Windows-only here; on this platform the "
+            "page cache is advised away after each read, which is weaker. Treat "
+            "any result above the drive's rating as cache.")
+
+    chunk, block = chunk_mb * MB, block_mb * MB
+    out: Dict[int, float] = {}
+    log(f"  {len(files)} file(s), {chunk_mb}MB per worker, {block_mb}MB blocks")
+    for d in depths:
+        jobs = []
+        for i in range(d):
+            p = files[i % len(files)]
+            size = (os.path.getsize(p) // SECTOR) * SECTOR
+            slot = i // len(files)
+            off = ((slot * 1300 * MB + 300 * MB) % max(SECTOR, size - chunk))
+            jobs.append((p, (off // SECTOR) * SECTOR, chunk, block))
+        t0 = time.perf_counter()
+        with ThreadPoolExecutor(max_workers=d) as ex:
+            total = sum(ex.map(lambda a: read(*a), jobs))
+        rate = total / (time.perf_counter() - t0) / MB
+        out[d] = rate
+        log(f"  QD{d:<3d} {total / MB:6.0f} MB in {(total / MB) / rate:5.2f}s "
+            f"= {rate:6.0f} MB/s")
+    best = max(out, key=out.get)
+    log(f"  optimum QD{best} at {out[best]:.0f} MB/s "
+        f"({out[best] / out[min(out)]:.2f}x QD{min(out)})")
+    if best < max(out):
+        log("  more readers than that LOSE — a DRAM-less controller degrades past "
+            "its sweet spot rather than saturating.")
+    return out