slide2vec 5.9.0__tar.gz → 5.9.2__tar.gz

{slide2vec-5.9.0 → slide2vec-5.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 5.9.0
+Version: 5.9.2
 Summary: Embedding of whole slide images with Foundation Models
 Author-email: Clément Grisi <clement.grisi@radboudumc.nl>
 License-Expression: Apache-2.0
@@ -276,4 +276,5 @@ docker run --rm -it \
 - [API guide](https://clemsgrs.github.io/slide2vec/api.html)
 - [CLI guide](https://clemsgrs.github.io/slide2vec/cli.html)
 - [Model zoo](https://clemsgrs.github.io/slide2vec/models.html)
+- [Performance benchmarks and QA](docs/performance.md)
 - [`tutorials/api_walkthrough.ipynb`](tutorials/api_walkthrough.ipynb) for a notebook walkthrough of the API

{slide2vec-5.9.0 → slide2vec-5.9.2}/README.md

@@ -160,4 +160,5 @@ docker run --rm -it \
 - [API guide](https://clemsgrs.github.io/slide2vec/api.html)
 - [CLI guide](https://clemsgrs.github.io/slide2vec/cli.html)
 - [Model zoo](https://clemsgrs.github.io/slide2vec/models.html)
+- [Performance benchmarks and QA](docs/performance.md)
 - [`tutorials/api_walkthrough.ipynb`](tutorials/api_walkthrough.ipynb) for a notebook walkthrough of the API

{slide2vec-5.9.0 → slide2vec-5.9.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "slide2vec"
-version = "5.9.0"
+version = "5.9.2"
 description = "Embedding of whole slide images with Foundation Models"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -180,7 +180,7 @@ no_implicit_reexport = true
 max-line-length = 160
 
 [tool.bumpver]
-current_version = "5.9.0"
+current_version = "5.9.2"
 version_pattern = "MAJOR.MINOR.PATCH"
 commit = false
 tag = false

{slide2vec-5.9.0 → slide2vec-5.9.2}/slide2vec/__init__.py

@@ -27,7 +27,7 @@ from slide2vec.encoders import (
 )
 
 
-__version__ = "5.9.0"
+__version__ = "5.9.2"
 
 __all__ = [
     "Model",

{slide2vec-5.9.0 → slide2vec-5.9.2}/slide2vec/data/tile_reader.py

@@ -510,14 +510,14 @@ def _unfold_region_tensor_uint8(region_tensor: torch.Tensor, tile_size: int) ->
         return torch.empty((0, 0, 3, tile_size, tile_size), dtype=torch.uint8)
     if int(region_tensor.shape[-1]) % tile_size != 0 or int(region_tensor.shape[-2]) % tile_size != 0:
         raise ValueError("Region tensor dimensions must be divisible by the tile size")
-    unfolded = torch.nn.functional.unfold(
-        region_tensor.to(torch.float32),
-        kernel_size=tile_size,
-        stride=tile_size,
+    batch, channels, height, width = region_tensor.shape
+    # Disjoint tiles need only a layout change. Keep pixels as bytes instead of
+    # materializing float regions and im2col buffers, then converting them back.
+    return (
+        region_tensor.reshape(batch, channels, height // tile_size, tile_size, width // tile_size, tile_size)
+        .permute(0, 2, 4, 1, 3, 5)
+        .reshape(batch, -1, channels, tile_size, tile_size)
     )
-    unfolded = unfolded.transpose(1, 2)
-    reshaped = unfolded.reshape(region_tensor.shape[0], -1, region_tensor.shape[1], tile_size, tile_size)
-    return reshaped.round().clamp(0, 255).to(torch.uint8)
 
 
 def _area_resize_tile_batch(

{slide2vec-5.9.0 → slide2vec-5.9.2}/slide2vec/encoders/models/prism.py

@@ -46,5 +46,7 @@ class PrismSlideEncoder(SlideEncoder):
     ) -> torch.Tensor:
         if tile_features.ndim == 2:
             tile_features = tile_features.unsqueeze(0)
+        # Stored feature precision can differ from PRISM's weights; CPU has no autocast.
+        tile_features = tile_features.to(dtype=self._model.dtype)
         reprs = self._model.slide_representations(tile_features)
         return reprs["image_embedding"].squeeze(0)

{slide2vec-5.9.0 → slide2vec-5.9.2}/slide2vec/runtime/batching.py

@@ -110,7 +110,8 @@ class BatchPrefetcher:
         self.loaded = loaded
         self.batch_preprocessor = batch_preprocessor
         self.copy_stream = self._make_copy_stream()
-        self._pinned_host_buffer = None
+        self.defer_preload = self.copy_stream is not None and batch_preprocessor is not None
+        self._exhausted = False
         self._next_batch: PreparedBatch | None = None
         self._preload()
 
@@ -132,18 +133,10 @@ class BatchPrefetcher:
             return image
         if image.device.type != "cpu" or image.is_pinned():
             return image
-        if (
-            self._pinned_host_buffer is None
-            or tuple(self._pinned_host_buffer.shape) != tuple(image.shape)
-            or self._pinned_host_buffer.dtype != image.dtype
-        ):
-            self._pinned_host_buffer = torch.empty(
-                image.shape,
-                dtype=image.dtype,
-                pin_memory=True,
-            )
-        self._pinned_host_buffer.copy_(image)
-        return self._pinned_host_buffer
+        # A shared staging buffer could be overwritten by the next preload while
+        # its asynchronous H2D copy is still pending. PyTorch tracks the lifetime
+        # of each pinned allocation until the transfer completes.
+        return image.pin_memory()
 
     def _prepare_batch(self, image):
         preprocess_start = time.perf_counter()
@@ -160,10 +153,13 @@ class BatchPrefetcher:
         return prepared, preprocess_ms
 
     def _preload(self) -> None:
+        if self._exhausted or self._next_batch is not None:
+            return
         wait_start = time.perf_counter()
         try:
             batch = next(self.iterator)
         except StopIteration:
+            self._exhausted = True
             self._next_batch = None
             return
         loader_wait_ms = (time.perf_counter() - wait_start) * 1000.0
@@ -206,6 +202,7 @@ class BatchPrefetcher:
         return self
 
     def __next__(self) -> PreparedBatch:
+        self._preload()
         if self._next_batch is None:
             raise StopIteration
         current = self._next_batch
@@ -213,8 +210,12 @@ class BatchPrefetcher:
             ready_start = time.perf_counter()
             current_stream = torch.cuda.current_stream(device=self.loaded.device)
             current_stream.wait_stream(self.copy_stream)
+            if torch.is_tensor(current.image) and current.image.is_cuda:
+                current.image.record_stream(current_stream)
             current.ready_wait_ms = (time.perf_counter() - ready_start) * 1000.0
-        self._preload()
+        self._next_batch = None
+        if not self.defer_preload:
+            self._preload()
         return current
 
 
@@ -254,8 +255,16 @@ def iter_forward_batches(
             image = prepared_batch.image
             _record_encoder_input_size(loaded, image)
             forward_start = time.perf_counter()
-            embedding = loaded.model.encode_tiles(image).detach().cpu()
+            embedding = loaded.model.encode_tiles(image).detach()
             forward_ms = (time.perf_counter() - forward_start) * 1000.0
+            if prefetcher.defer_preload:
+                # Launch CUDA work before blocking on the next reader batch. CPU
+                # and itemwise transforms retain their original execution order.
+                prefetcher._preload()
+            result_start = time.perf_counter()
+            embedding = embedding.cpu()
+            # Residual host time excludes the overlapping preload, not GPU time.
+            forward_ms += (time.perf_counter() - result_start) * 1000.0
             current_indices = torch.as_tensor(prepared_batch.indices, dtype=torch.long).detach().cpu()
             processed += int(embedding.shape[0])
             batch_index += 1

{slide2vec-5.9.0 → slide2vec-5.9.2}/slide2vec/runtime/persistence.py

@@ -230,44 +230,42 @@ def update_process_list_after_embedding(
         feature_success_ids = {slide.sample_id for slide in successful_slides}
     feature_success_keys = set(feature_path_by_key)
     annotation_aware = any(annotation is not None for _, annotation in feature_success_keys)
+    successful_ids = {slide.sample_id for slide in successful_slides}
     row_annotations = _row_annotation_series(df)
-    for slide in successful_slides:
-        mask = df["sample_id"].astype(str) == slide.sample_id
-        if annotation_aware:
-            # Resolve each (sample_id, annotation) row independently so per-class paths and
-            # statuses don't bleed across the slide's other annotation rows. An incremental
-            # update may contain only one finished annotation, so unmatched siblings stay
-            # untouched until their own artifact is available.
-            for annotation in _row_annotations(row_annotations, mask):
-                # ``== None`` is element-wise False in pandas, so match the flat None key
-                # via isna() and real classes via equality.
-                if annotation is None:
-                    row_mask = mask & row_annotations.isna()
-                else:
-                    row_mask = mask & (row_annotations == annotation)
-                key = (slide.sample_id, annotation)
-                mapped_feature_path = feature_path_by_key.get(key)
-                if mapped_feature_path is not None:
-                    df.loc[row_mask, "feature_status"] = "success"
-                    df.loc[row_mask, "feature_path"] = mapped_feature_path
-                    df.loc[row_mask, "encoder_name"] = encoder_name
-                    df.loc[row_mask, "output_variant"] = output_variant
-                    df.loc[row_mask, "feature_kind"] = feature_kind
-                if include_slide_embeddings and key in slide_success_keys:
-                    df.loc[row_mask, "aggregation_status"] = "success"
-        else:
-            feature_status = "success" if slide.sample_id in feature_success_ids else "error"
-            df.loc[mask, "feature_status"] = feature_status
-            mapped_feature_path = feature_path_by_key.get((slide.sample_id, None))
-            if mapped_feature_path is not None:
-                df.loc[mask, "feature_path"] = mapped_feature_path
-                df.loc[mask, "encoder_name"] = encoder_name
-                df.loc[mask, "output_variant"] = output_variant
-                df.loc[mask, "feature_kind"] = feature_kind
-            if include_slide_embeddings:
-                df.loc[mask, "aggregation_status"] = (
-                    "success" if slide.sample_id in slide_success_ids else "error"
-                )
+    status_rows, statuses = [], []
+    feature_rows, feature_paths = [], []
+    aggregation_rows, aggregation_statuses = [], []
+    # Visit each CSV row once, including duplicate rows. The old per-slide masks
+    # repeatedly converted/scanned the whole table during every checkpoint flush.
+    for index, sample_id, annotation in zip(df.index, df["sample_id"].astype(str), row_annotations):
+        if sample_id not in successful_ids:
+            continue
+        key = (sample_id, _normalized_annotation(annotation) if annotation_aware else None)
+        mapped_feature_path = feature_path_by_key.get(key)
+        if not annotation_aware or mapped_feature_path is not None:
+            status_rows.append(index)
+            statuses.append("success" if sample_id in feature_success_ids else "error")
+        if mapped_feature_path is not None:
+            feature_rows.append(index)
+            feature_paths.append(mapped_feature_path)
+        # An incremental annotation update leaves unfinished sibling classes alone.
+        if include_slide_embeddings and (not annotation_aware or key in slide_success_keys):
+            aggregation_rows.append(index)
+            aggregation_statuses.append("success" if sample_id in slide_success_ids else "error")
+
+    if status_rows:
+        df.loc[status_rows, "feature_status"] = statuses
+    if feature_rows:
+        # Empty CSV columns are inferred as floats. Explicit object columns also
+        # allow provenance to be filled on pandas versions that reject upcasting.
+        for column in ("feature_path", "encoder_name", "output_variant", "feature_kind"):
+            df[column] = df[column].astype(object)
+        df.loc[feature_rows, "feature_path"] = feature_paths
+        df.loc[feature_rows, "encoder_name"] = encoder_name
+        df.loc[feature_rows, "output_variant"] = output_variant
+        df.loc[feature_rows, "feature_kind"] = feature_kind
+    if aggregation_rows:
+        df.loc[aggregation_rows, "aggregation_status"] = aggregation_statuses
     atomic_write_dataframe_csv(df, process_list_path)
 
 
@@ -291,13 +289,3 @@ def _row_annotation_series(df: pd.DataFrame) -> pd.Series:
     if "annotation" not in df.columns:
         return pd.Series([np.nan] * len(df), index=df.index, dtype=object)
     return df["annotation"].map(lambda value: _normalized_annotation(value) or np.nan)
-
-
-def _row_annotations(row_annotations: pd.Series, mask: pd.Series) -> list[str | None]:
-    """Distinct normalized annotations present in the masked rows (``None`` for flat rows)."""
-    seen: list[str | None] = []
-    for value in row_annotations[mask].tolist():
-        normalized = None if value is None or (isinstance(value, float) and pd.isna(value)) else value
-        if normalized not in seen:
-            seen.append(normalized)
-    return seen

{slide2vec-5.9.0 → slide2vec-5.9.2}/slide2vec.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 5.9.0
+Version: 5.9.2
 Summary: Embedding of whole slide images with Foundation Models
 Author-email: Clément Grisi <clement.grisi@radboudumc.nl>
 License-Expression: Apache-2.0
@@ -276,4 +276,5 @@ docker run --rm -it \
 - [API guide](https://clemsgrs.github.io/slide2vec/api.html)
 - [CLI guide](https://clemsgrs.github.io/slide2vec/cli.html)
 - [Model zoo](https://clemsgrs.github.io/slide2vec/models.html)
+- [Performance benchmarks and QA](docs/performance.md)
 - [`tutorials/api_walkthrough.ipynb`](tutorials/api_walkthrough.ipynb) for a notebook walkthrough of the API

{slide2vec-5.9.0 → slide2vec-5.9.2}/slide2vec.egg-info/SOURCES.txt

@@ -111,6 +111,7 @@ slide2vec/utils/tiling_io.py
 slide2vec/utils/utils.py
 tests/test_architecture_runtime_split.py
 tests/test_attention_extraction.py
+tests/test_benchmark_tooling.py
 tests/test_dense_encode_kit.py
 tests/test_dense_encoder_input.py
 tests/test_dense_extraction.py
@@ -134,6 +135,7 @@ tests/test_gpfm_genbio_heavy.py
 tests/test_hs2p_package_cutover.py
 tests/test_image_shard.py
 tests/test_image_stage.py
+tests/test_inference_benchmark.py
 tests/test_isight.py
 tests/test_load_model_hf_auth.py
 tests/test_mascaret.py
@@ -144,7 +146,9 @@ tests/test_patient_manifest.py
 tests/test_phaet.py
 tests/test_pooled_encoder_input.py
 tests/test_pooled_geometry.py
+tests/test_prism.py
 tests/test_prism2.py
+tests/test_process_list_performance.py
 tests/test_progress.py
 tests/test_regression_core.py
 tests/test_regression_inference.py

slide2vec-5.9.2/tests/test_benchmark_tooling.py

@@ -0,0 +1,193 @@
+"""Benchmark configuration stays compatible with the public pipeline API."""
+
+import importlib
+import os
+from pathlib import Path
+
+import pytest
+
+
+@pytest.mark.parametrize("module_name,builder,reuses_coordinates", [
+    ("benchmark_end_to_end_paths", "_build_pipeline_from_config_dict", False),
+    ("benchmark_tile_read_strategies", "_build_pipeline_from_config_dict", True),
+    ("benchmark_embedding_throughput", "_build_model_pipeline_from_config", True),
+])
+def test_benchmark_config_preserves_requested_pipeline_settings(module_name, builder, reuses_coordinates):
+    module = importlib.import_module(f"scripts.{module_name}")
+    pipeline = getattr(module, builder)({
+        "output_dir": "/tmp/benchmark-config-only",
+        "device": "cpu",
+        "model": {"name": "phikonv2", "batch_size": 8},
+        "speed": {"num_dataloader_workers": 2, "precision": "fp32"},
+        "tiling": {
+            "backend": "openslide",
+            "params": {"requested_spacing_um": 0.5, "requested_tile_size_px": 224},
+            "masks": {"min_coverage": {"tissue": 0.3}},
+            "preview": {"save": False},
+        },
+    })
+    assert pipeline.execution.batch_size == 8
+    assert pipeline.execution.num_workers_per_gpu == 2
+    assert pipeline.execution.num_gpus == 1
+    assert pipeline.execution.precision == "fp32"
+    assert pipeline.preprocessing.backend == "openslide"
+    assert pipeline.preprocessing.requested_tile_size_px == 224
+    assert pipeline.preprocessing.requested_spacing_um == 0.5
+    assert pipeline.preprocessing.masks["min_coverage"]["tissue"] == 0.3
+    assert pipeline.preprocessing.preview["save_mask_preview"] is False
+    assert pipeline.preprocessing.read_coordinates_from == (
+        Path("/tmp/benchmark-config-only/coordinates") if reuses_coordinates else None
+    )
+
+
+@pytest.mark.parametrize("module_name,builder", [
+    ("benchmark_end_to_end_paths", "_build_pipeline_from_config_dict"),
+    ("benchmark_tile_read_strategies", "_build_pipeline_from_config_dict"),
+    ("benchmark_embedding_throughput", "_build_model_pipeline_from_config"),
+])
+@pytest.mark.parametrize("process_rows", [
+    "broken,error,,10\n",
+    "broken,success,error,10\n",
+    "empty,success,,0\n",
+])
+def test_benchmark_harness_rejects_failed_or_empty_work(tmp_path, monkeypatch, module_name, builder, process_rows):
+    import json
+    from types import SimpleNamespace
+
+    module = importlib.import_module(f"scripts.{module_name}")
+    (tmp_path / "process_list.csv").write_text(
+        "sample_id,tiling_status,feature_status,num_tiles\n" + process_rows
+    )
+    config_path = tmp_path / "config.yaml"
+    config_path.write_text(f"output_dir: {tmp_path}\ncsv: unused.csv\n")
+    pipeline = SimpleNamespace(run=lambda **kwargs: SimpleNamespace(tile_artifacts=[object()], slide_artifacts=[]))
+    monkeypatch.setattr(module, builder, lambda config: pipeline)
+    args = SimpleNamespace(
+        harness_config=config_path, config_file=config_path,
+        metrics_json=tmp_path / "metrics.json", progress_jsonl=tmp_path / "progress.jsonl",
+    )
+
+    assert module._run_internal_harness(args) == 1
+    metrics = json.loads(args.metrics_json.read_text())
+    assert metrics["success"] is False
+    assert metrics["tiles_per_second"] == 0.0
+
+
+def test_benchmark_accepts_completed_hierarchical_artifacts():
+    from types import SimpleNamespace
+    from scripts.benchmark_common import validate_completed_work
+
+    validate_completed_work(
+        {"failed_slides": 0, "total_tiles": 4},
+        SimpleNamespace(tile_artifacts=[], slide_artifacts=[], hierarchical_artifacts=[object()]),
+    )
+
+
+@pytest.mark.skipif(
+    os.environ.get("SLIDE2VEC_PERF_SMOKE") != "1",
+    reason="Set SLIDE2VEC_PERF_SMOKE=1 for the real WSI reader and CPU encoder smoke test",
+)
+def test_benchmark_real_fixture_cpu_pipeline(tmp_path, monkeypatch):
+    """Run real reading, batching, persistence and metrics without pretrained weights."""
+    import json
+    from types import SimpleNamespace
+
+    import torch
+    from torchvision import transforms
+    import yaml
+
+    from slide2vec.api import Model
+    from slide2vec.runtime.types import LoadedModel
+    from scripts.benchmark_end_to_end_paths import _run_internal_harness
+
+    class MeanEncoder:
+        encoder = SimpleNamespace(pretrained_cfg={})
+
+        def encode_tiles(self, image):
+            return image.mean(dim=(-2, -1))
+
+    loaded = LoadedModel(
+        name="phikonv2", level="tile", model=MeanEncoder(),
+        transforms=transforms.Compose([transforms.ToTensor()]),
+        feature_dim=3, device=torch.device("cpu"),
+    )
+    monkeypatch.setattr(Model, "_load_backend", lambda self: loaded)
+    monkeypatch.setattr(Model, "_load_backend_without_transform", lambda self: loaded)
+    fixtures = Path(__file__).parent / "fixtures" / "input"
+    manifest = tmp_path / "slides.csv"
+    manifest.write_text(
+        f'sample_id,image_path,mask_path\ntest-wsi,{fixtures / "test-wsi.tif"},{fixtures / "test-mask.tif"}\n'
+    )
+    config = {
+        "csv": str(manifest), "output_dir": str(tmp_path), "device": "cpu",
+        "model": {"name": "phikonv2", "batch_size": 32},
+        "speed": {"num_dataloader_workers": 0, "num_preprocessing_workers": 1, "num_gpus": 1, "precision": "fp32"},
+        "tiling": {
+            "backend": "openslide", "mask_backend": "asap", "on_the_fly": True, "use_supertiles": False,
+            "params": {"requested_spacing_um": 0.5, "requested_tile_size_px": 224, "tolerance": 0.07},
+            "preview": {"save": False},
+        },
+    }
+    config_path = tmp_path / "config.yaml"
+    config_path.write_text(yaml.safe_dump(config))
+    args = SimpleNamespace(
+        harness_config=config_path, metrics_json=tmp_path / "metrics.json", progress_jsonl=tmp_path / "progress.jsonl",
+    )
+    original_threads = torch.get_num_threads()
+    try:
+        torch.set_num_threads(1)
+        assert _run_internal_harness(args) == 0
+    finally:
+        torch.set_num_threads(original_threads)
+    metrics = json.loads(args.metrics_json.read_text())
+    assert metrics["success"] is True
+    assert metrics["failed_slides"] == 0
+    assert metrics["total_tiles"] == 474
+    assert metrics["tile_artifacts"] == 1
+    assert metrics["timed_batches"] == 15
+    features = torch.load(tmp_path / "tile_embeddings" / "test-wsi.pt", weights_only=True)
+    assert features.shape == (474, 3)
+    assert bool(torch.isfinite(features).all())
+
+
+@pytest.mark.parametrize("module_name,builder,expected_workers", [
+    ("benchmark_end_to_end_paths", "_build_pipeline_from_config_dict", 2),
+    ("benchmark_tile_read_strategies", "_build_pipeline_from_config_dict", 2),
+    ("benchmark_embedding_throughput", "_build_model_pipeline_from_config", 7),
+])
+def test_benchmark_worker_override_beats_legacy_config(module_name, builder, expected_workers):
+    module = importlib.import_module(f"scripts.{module_name}")
+    pipeline = getattr(module, builder)({
+        "output_dir": "/tmp/benchmark-config-only", "device": "cpu",
+        "model": {"name": "phikonv2"},
+        "speed": {"num_dataloader_workers": 2, "num_workers_embedding": 7},
+    })
+    assert pipeline.execution.num_workers_per_gpu == expected_workers
+
+
+def test_runtime_benchmark_checks_expected_pixels_and_rejects_changed_baseline(tmp_path, monkeypatch):
+    import hashlib
+    import json
+    import sys
+    from scripts import benchmark_runtime
+
+    output = tmp_path / 'result.json'
+    arguments = ['benchmark_runtime.py', '--case', 'hierarchical', '--regions', '1',
+                 '--region-size', '4', '--tile-size', '2', '--repeat', '1', '--output', str(output)]
+    monkeypatch.setattr(sys, 'argv', arguments)
+    benchmark_runtime.main()
+    report = json.loads(output.read_text())
+    # Four RGB tiles, channel-first inside each tile, row-major across the region.
+    expected_pixels = bytes([
+        0, 3, 12, 15, 1, 4, 13, 16, 2, 5, 14, 17,
+        6, 9, 18, 21, 7, 10, 19, 22, 8, 11, 20, 23,
+        24, 27, 36, 39, 25, 28, 37, 40, 26, 29, 38, 41,
+        30, 33, 42, 45, 31, 34, 43, 46, 32, 35, 44, 47,
+    ])
+    assert report['output_sha256'] == hashlib.sha256(expected_pixels).hexdigest()
+    baseline = tmp_path / 'before.json'
+    report['output_sha256'] = 'changed-output'
+    baseline.write_text(json.dumps(report))
+    monkeypatch.setattr(sys, 'argv', [*arguments, '--compare', str(baseline)])
+    with pytest.raises(ValueError, match='Baseline output differs'):
+        benchmark_runtime.main()

slide2vec-5.9.2/tests/test_inference_benchmark.py

@@ -0,0 +1,140 @@
+"""Behavioral checks for the fixed-coordinate inference measurement workflow."""
+from types import SimpleNamespace
+
+import pytest
+
+
+@pytest.mark.parametrize("field,value,message", [
+    ("batch_size", 0, "batch_size must be positive"),
+    ("modes", ["unknown"], "Unknown inference mode"),
+    ("cache_policy", "server-cold", "Unknown cache policy"),
+])
+def test_inference_benchmark_rejects_invalid_workloads(field, value, message):
+    from scripts.benchmark_inference import run_inference_benchmark
+
+    args = SimpleNamespace(batch_size=2, tile_size=224, repeat=1, warmup=0,
+                           workers=0, threads=1, modes=["cached"], cache_policy="warm")
+    setattr(args, field, value)
+    with pytest.raises(ValueError, match=message):
+        run_inference_benchmark(args)
+
+
+def test_inference_modes_preserve_coordinates_batches_and_embeddings(tmp_path, monkeypatch):
+    import itertools
+    import json
+    import numpy as np
+    import torch
+    from torchvision.transforms import Compose, ToTensor
+    import slide2vec.inference
+    import slide2vec.data.tile_reader
+    from slide2vec.runtime.types import LoadedModel
+    from scripts.benchmark_inference import run_inference_benchmark
+    import scripts.benchmark_inference as benchmark
+
+    snapshots = itertools.cycle([
+        {"parent_minor_faults": 10, "parent_major_faults": 1,
+         "cgroup_memory_psi_us": {"some": 100, "full": 50}, "host_memory_psi_us": None},
+        {"parent_minor_faults": 17, "parent_major_faults": 3,
+         "cgroup_memory_psi_us": {"some": 120, "full": 55}, "host_memory_psi_us": None},
+    ])
+    monkeypatch.setattr(benchmark, "_resource_snapshot", lambda: next(snapshots))
+
+    class Encoder:
+        def encode_tiles(self, images):
+            return images.mean(dim=(2, 3))
+
+    class Reader:
+        def read_region(self, location, level, size):
+            return np.full((size[1], size[0], 3), location[0], dtype=np.uint8)
+
+        def close(self):
+            pass
+
+    monkeypatch.setattr(slide2vec.inference, "load_model", lambda **kwargs: LoadedModel(
+        name="phikonv2", level="tile", model=Encoder(), transforms=Compose([ToTensor()]),
+        feature_dim=3, device=torch.device("cpu"),
+    ))
+    monkeypatch.setattr(slide2vec.data.tile_reader, "_open_wsi_backend", lambda *a: Reader())
+    slide = tmp_path / "slide.tif"
+    slide.write_bytes(b"mock slide")
+    coordinates = tmp_path / "coordinates.npz"
+    np.savez(coordinates, x=np.array([255, 0, 255]), y=np.array([0, 0, 224]))
+    output = tmp_path / "result.json"
+    args = SimpleNamespace(
+        model="phikonv2", slide=slide, coordinates=coordinates, tile_size=224,
+        batch_size=2, workers=0, backend="openslide", modes=["model-only", "cached", "wsi"],
+        repeat=1, warmup=0, threads=1, output=output, profile=False,
+        use_supertiles=False, cache_policy="fresh-reader", device="cpu", precision="fp32",
+    )
+    result = run_inference_benchmark(args)
+    assert set(result["modes"]) == {"model-only", "cached", "wsi"}
+    expected = torch.tensor([[1., 1., 1.], [0., 0., 0.], [1., 1., 1.]])
+    for mode, measured in result["modes"].items():
+        assert len(measured["samples_seconds"]) == 1
+        assert measured["max_abs_error"] == 0
+        assert measured["sample_resources"] == [{
+            "parent_minor_faults": 7, "parent_major_faults": 2,
+            "cgroup_memory_psi_us": {"some": 20, "full": 5}, "host_memory_psi_us": None,
+        }]
+        torch.testing.assert_close(torch.load(measured["embeddings_path"], weights_only=True), expected)
+    assert json.loads(output.read_text())["parameters"]["num_tiles"] == 3
+    args.compare = output
+    args.output = tmp_path / "after.json"
+    comparison = run_inference_benchmark(args)
+    for measured in comparison["modes"].values():
+        assert measured["baseline_max_abs_error"] == 0
+        assert "speedup" in measured
+    baseline_payload = (tmp_path / "result-cached.pt").read_bytes()
+    args.output = tmp_path / "result.txt"
+    with pytest.raises(ValueError, match="preserve the baseline embeddings"):
+        run_inference_benchmark(args)
+    assert (tmp_path / "result-cached.pt").read_bytes() == baseline_payload
+
+
+@pytest.mark.parametrize("available", [True, False])
+def test_resource_snapshot_reads_pressure_totals_or_reports_unavailable(monkeypatch, available):
+    import resource
+    from pathlib import Path
+    from scripts.benchmark_inference import _resource_snapshot
+
+    def usage(_):
+        if not available:
+            raise OSError("unavailable")
+        return SimpleNamespace(ru_minflt=13, ru_majflt=2)
+
+    def read(path):
+        if not available:
+            raise OSError("unavailable")
+        if str(path) == "/sys/fs/cgroup/memory.pressure":
+            return "some avg10=0.00 avg60=0.00 avg300=0.00 total=123\nfull avg10=0.00 avg60=0.00 avg300=0.00 total=45\n"
+        assert str(path) == "/proc/pressure/memory"
+        return "some avg10=0.00 total=789\nfull avg10=0.00 total=67\n"
+
+    monkeypatch.setattr(resource, "getrusage", usage)
+    monkeypatch.setattr(Path, "read_text", read)
+    assert _resource_snapshot() == {
+        "parent_minor_faults": 13 if available else None,
+        "parent_major_faults": 2 if available else None,
+        "cgroup_memory_psi_us": {"some": 123, "full": 45} if available else None,
+        "host_memory_psi_us": {"some": 789, "full": 67} if available else None,
+    }
+
+
+def test_inference_comparison_rejects_different_coordinates_before_model_load(tmp_path):
+    import json
+    import numpy as np
+    from scripts.benchmark_inference import run_inference_benchmark
+
+    coordinates = tmp_path / "coordinates.npz"
+    np.savez(coordinates, x=np.array([0]), y=np.array([0]))
+    slide = tmp_path / "slide.tif"
+    slide.write_bytes(b"mock slide")
+    baseline = tmp_path / "baseline.json"
+    baseline.write_text(json.dumps({"parameters": {"coordinates_sha256": "different"}}))
+    with pytest.raises(ValueError, match="different parameters"):
+        run_inference_benchmark(SimpleNamespace(
+            model="never-load-this-model", slide=slide, coordinates=coordinates, tile_size=224,
+            batch_size=2, workers=0, backend="openslide", modes=["wsi"],
+            repeat=1, warmup=0, threads=1, output=tmp_path / "after.json", profile=False,
+            use_supertiles=False, cache_policy="warm", device="cpu", precision="fp32", compare=baseline,
+        ))