{"record":{"id":"c79decfa91695d4f","repo":"Lightning-AI/pytorch-lightning","slug":"expected-samples-samples-to-be-greater-or-equa","errorCode":null,"errorMessage":"Expected samples ({samples}) to be greater or equal than batches ({batches})","messagePattern":"Expected samples \\((.+?)\\) to be greater or equal than batches \\((.+?)\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/lightning/fabric/utilities/throughput.py","lineNumber":156,"sourceCode":"        flops: Optional[int] = None,\n    ) -> None:\n        \"\"\"Update throughput metrics.\n\n        Args:\n            time: Total elapsed time in seconds. It should monotonically increase by the iteration time with each\n                call.\n            batches: Total batches seen per device. It should monotonically increase with each call.\n            samples: Total samples seen per device. It should monotonically increase by the batch size with each call.\n            lengths: Total length of the samples seen. It should monotonically increase by the lengths of a batch with\n                each call.\n            flops: Flops elapased per device since last ``update()`` call. You can easily compute this by using\n                :func:`measure_flops` and multiplying it by the number of batches that have been processed.\n                The value might be different in each device if the batch size is not the same.\n\n        \"\"\"\n        self._time.append(time)\n        if samples < batches:\n            raise ValueError(f\"Expected samples ({samples}) to be greater or equal than batches ({batches})\")\n        self._batches.append(batches)\n        self._samples.append(samples)\n        if lengths is not None:\n            if lengths < samples:\n                raise ValueError(f\"Expected lengths ({lengths}) to be greater or equal than samples ({samples})\")\n            self._lengths.append(lengths)\n            if len(self._samples) != len(self._lengths):\n                raise RuntimeError(\n                    f\"If lengths are passed ({len(self._lengths)}), there needs to be the same number of samples\"\n                    f\" ({len(self._samples)})\"\n                )\n        if flops is not None:\n            # sum of flops across ranks\n            self._flops.append(flops * self.world_size)\n\n    def compute(self) -> _THROUGHPUT_METRICS:\n        \"\"\"Compute throughput metrics.\"\"\"\n        metrics = {","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/Lightning-AI/pytorch-lightning/blob/9fed5c27d2a62ff0efd6c3573599921d6ff67c14/src/lightning/fabric/utilities/throughput.py#L138-L174","documentation":"`ThroughputCollector.update(...)`/Throughput metric's `update` accumulates per-step time, batch count and sample count; a basic invariant is that each batch contains at least one sample, so `samples >= batches` must hold. Passing fewer samples than batches (e.g. samples=0 with batches>0, or mixing up argument order) raises this ValueError.","triggerScenarios":"Calling `update(time=t, batches=n, samples=m)` with m < n, commonly by swapping the `batches` and `samples` arguments, passing `samples=0`, or computing samples as batch_size instead of batch_size*num_batches.","commonSituations":"Argument-order mixups (samples and batches are adjacent ints), unit tests feeding zeros, dynamic batch sizes where the last partial batch's sample count is computed incorrectly, position vs keyword argument mismatch after an API update.","solutions":["Check argument order and pass samples = total items across the update window (>= number of batches)","Use keyword arguments: `update(time=..., batches=..., samples=...)`","Compute samples as sum of per-batch sizes, not a single batch size; guard with `if samples < batches: raise/skip`"],"exampleFix":"# before\ncollector.update(time=dt, batches=steps, samples=batch_size)  # batch_size < steps -> error\n\n# after\ncollector.update(time=dt, batches=steps, samples=batch_size * steps)","handlingStrategy":"validation","validationCode":"assert samples >= batches, f\"samples ({samples}) < batches ({batches})\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always call update with keyword arguments (time=, batches=, samples=)","Compute samples as the sum of per-batch sizes, not a single batch size"],"tags":["lightning","throughput","validation"],"backgroundTag":"invalid-argument-value","analyzedSha":"9fed5c27d2a62ff0efd6c3573599921d6ff67c14","analyzedAt":"2026-08-28T11:52:41.083Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}