bench: fix apples-to-apples Parquet comparison + update numbers

Add Parquet batch API variants (ColumnReader.nextBatch + getDoubles/getInts)
alongside the existing row-cursor variants (renamed RowByRow). Batch is the
fair comparison with Vortex's fold — row-by-row was inflating Vortex's apparent
speedup by 2.5-3× due to row-cursor API overhead.

Results (Apple M5, OpenJDK 25, fork 2, wi=5, i=5):
  parquetRead (batch)               166.5 ops/s  baseline
  parquetReadRowByRow               67.6  ops/s  (2.5× API penalty)
  vortexRead                        235.1 ops/s  1.41× vs batch
  parquetReadMultiColumn (batch)    133.0 ops/s  baseline
  parquetReadMultiColumnRowByRow    44.0  ops/s  (3× API penalty)
  vortexReadMultiColumn             122.6 ops/s  0.92× vs batch

Update explanation.md benchmark table and analysis accordingly.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: dfa1

docs/explanation.md

@@ -134,49 +134,55 @@ File sizes: Parquet 47.6 MB, Vortex Java 50 MB.
 
 **Environment:** Apple M5, OpenJDK 25, 5 warmup × 3 s, 5 measurement × 5 s, fork 2.
 
-| Benchmark | ops/s | ms/scan | vs Parquet |
-|---|---|---|---|
-| `parquetRead` — Hardwood, 1 col (`trip_distance`) | 73.9 ± 1.5 | 13.5 ms | baseline |
-| `vortexRead` — 1 col (`trip_distance`) | 240.3 ± 3.8 | 4.2 ms | **3.3×** |
-| `parquetReadMultiColumn` — 2 cols (`fare_amount`, `PULocationID`) | 45.2 ± 1.2 | 22.1 ms | baseline |
-| `vortexReadMultiColumn` — 2 cols (`fare_amount`, `PULocationID`) | 129.1 ± 2.3 | 7.7 ms | **2.9×** |
-
-#### Why Vortex is faster
-
-**1. Batch columnar API vs row-by-row cursor.**
-Hardwood's `RowReader` requires `rows.next()` + `rows.getDouble("trip_distance")` per row
-— 2 virtual calls × 3 M rows = 6 M calls, plus a string-keyed column lookup on every
-access. `DoubleArray.fold()` is a tight loop over a flat `MemorySegment`; the JIT sees a
-scalar reduction over contiguous memory with no dispatch overhead.
-
-**2. mmap zero-copy.**
+Two Parquet variants are measured to isolate format cost from API overhead:
+- **batch**: `ColumnReader.nextBatch()` + loop over `getDoubles()`/`getInts()` arrays — apples-to-apples with Vortex's batch fold
+- **row-by-row**: `RowReader.next()` + `getDouble("col")` per row — measures the full row-cursor overhead on top of format decode
+
+| Benchmark | ops/s | vs Parquet batch |
+|---|---|---|
+| `parquetRead` — batch, 1 col (`trip_distance`) | 166.5 ± 4.0 | baseline |
+| `parquetReadRowByRow` — row cursor, 1 col | 67.6 ± 4.4 | 0.41× (2.5× API penalty) |
+| `vortexRead` — 1 col (`trip_distance`) | 235.1 ± 6.9 | **1.41×** |
+| `parquetReadMultiColumn` — batch, 2 cols (`fare_amount`, `PULocationID`) | 133.0 ± 18.3 | baseline |
+| `parquetReadMultiColumnRowByRow` — row cursor, 2 cols | 44.0 ± 2.2 | 0.33× (3× API penalty) |
+| `vortexReadMultiColumn` — 2 cols | 122.6 ± 3.3 | 0.92× |
+
+Single-column: Vortex 1.4× faster than Parquet batch — format advantage is real (mmap
+zero-copy + ALP vs Parquet RLE/ZSTD page decode).
+
+Multi-column: Vortex (122.6) slightly behind Parquet batch (133.0). Known gap: Rust uses a
+global dict per column (one tiny dict for all 3 M rows); Java applies dict per 131 K-row
+chunk, increasing per-chunk overhead for low-cardinality columns like `PULocationID` (260
+unique values).
+
+#### Why Vortex is faster on single-column reads
+
+**1. mmap zero-copy.**
 Vortex reads directly from the mmap'd `MemorySegment` — the file bytes _are_ the decode
 input, no intermediate copies. Hardwood reads into internal page buffers and materialises
-values into a row cursor (one extra copy per page). Parquet also pays per-page framing
-overhead: RLE-encoded definition/repetition levels, page header parsing, optional dictionary
-decode. Vortex's layout is a flat array of encoded values with no per-row framing.
+values before batch hand-off. Parquet also pays per-page framing overhead: RLE-encoded
+definition/repetition levels, page header parsing, optional dictionary decode. Vortex's
+layout is a flat array of encoded values with no per-row framing.
 
-**3. Typed scatter instead of per-element copy.**
+**2. Typed scatter instead of per-element copy.**
 `DictEncoding` expansion uses `getAtIndex`/`setAtIndex` with loop-unswitched elemSize —
-a single typed load + store per row. Prior to this fix, each element was expanded via
-`MemorySegment.copy(8 bytes)`, which carries per-call bounds-check overhead and dominated
-60% of JFR execution samples on multi-column scans.
+a single typed load + store per row. The prior `MemorySegment.copy(8 bytes)` per element
+dominated 60% of JFR execution samples on multi-column scans before it was fixed.
 
 ```
 Hardwood parquetRead (per 3 M rows)       Vortex vortexRead (per 3 M rows)
 ────────────────────────────────────      ──────────────────────────────────
 47.6 MB on disk                           50 MB on disk
 + page header parse × N pages             + ALP decode (branch-free ×/+)
 + definition-level RLE decode × 3 M rows  + fold() tight loop, no dispatch
-+ getDouble("col") × 3 M virtual calls
 ```
 
 #### Why ZstdEncoding is excluded from the numeric cascade
 
 Adding `ZstdEncoding` to `CASCADE_CODECS` improves file size (50 MB → 43 MB) because
 Zstd out-compresses ALP on some F64 columns. But ZSTD decompression is an order of
 magnitude slower than ALP reconstruction or bitpack unpack: single-column read throughput
-collapses from 240 to 40 ops/s (6×), falling below Parquet's 73.9 ops/s baseline.
+collapses from 235 to 40 ops/s (6×), falling below Parquet batch (166.5 ops/s).
 
 The smaller file is not worth the read regression. `ZstdEncoding` is retained in the
 codec registry for `Utf8`/`Binary` columns where no faster structural alternative exists,

performance/src/main/java/io/github/dfa1/vortex/performance/ParquetVsVortexReadBenchmark.java

@@ -1,6 +1,8 @@
 package io.github.dfa1.vortex.performance;
 
 import dev.hardwood.InputFile;
+import dev.hardwood.reader.ColumnReader;
+import dev.hardwood.reader.ColumnReaders;
 import dev.hardwood.reader.ParquetFileReader;
 import dev.hardwood.reader.RowReader;
 import dev.hardwood.schema.ColumnProjection;
@@ -35,15 +37,20 @@
 
 /// Benchmark: Hardwood Parquet read vs Java Vortex read on the same real-world dataset.
 ///
-/// Dataset: NYC Yellow Taxi 2024-01 (~3M rows), three columns:
-///   trip_distance (DOUBLE), fare_amount (DOUBLE), PULocationID (INT32)
+/// Dataset: NYC Yellow Taxi 2024-01 (~3M rows).
+/// Columns: trip_distance (DOUBLE), fare_amount (DOUBLE), PULocationID (INT32).
 ///
-/// Setup downloads the Parquet file once per trial (cached in /tmp), converts it to
-/// Vortex with column projection, then both benchmarks scan and sum trip_distance.
+/// Two Parquet variants:
+///   - {@code parquetRead} / {@code parquetReadMultiColumn}: batch column API
+///     ({@link ColumnReader#nextBatch()} + {@link ColumnReader#getDoubles()}) —
+///     apples-to-apples comparison with Vortex's batch fold.
+///   - {@code parquetReadRowByRow} / {@code parquetReadMultiColumnRowByRow}:
+///     Hardwood row cursor ({@link RowReader}) — measures row-oriented API overhead
+///     on top of format decode cost.
 ///
-/// Override the Parquet source with: -Dbench.parquet=/path/to/file.parquet
+/// Override the Parquet source with: {@code -Dbench.parquet=/path/to/file.parquet}
 ///
-/// Run: java -jar performance/target/benchmarks.jar ParquetVsVortexReadBenchmark
+/// Run: {@code java -jar performance/target/benchmarks.jar ParquetVsVortexReadBenchmark}
 @State(Scope.Benchmark)
 @BenchmarkMode(Mode.Throughput)
 @OutputTimeUnit(TimeUnit.SECONDS)
@@ -106,9 +113,50 @@ public void tearDown() throws IOException {
         }
     }
 
-    /// Hardwood: scan all rows, sum trip_distance (single column).
+    // ── Batch API (apples-to-apples with Vortex) ─────────────────────────────
+
+    /// Hardwood batch: decode trip_distance column in chunks, sum all values.
     @Benchmark
     public double parquetRead() throws IOException {
+        double sum = 0.0;
+        try (ParquetFileReader reader = ParquetFileReader.open(InputFile.of(parquetFile));
+             ColumnReader cr = reader.columnReader("trip_distance")) {
+            while (cr.nextBatch()) {
+                double[] vals = cr.getDoubles();
+                int n = cr.getRecordCount();
+                for (int i = 0; i < n; i++) {
+                    sum += vals[i];
+                }
+            }
+        }
+        return sum;
+    }
+
+    /// Hardwood batch: decode fare_amount + PULocationID in chunks, sum both.
+    @Benchmark
+    public double parquetReadMultiColumn() throws IOException {
+        double fareSum = 0.0;
+        long idSum = 0L;
+        try (ParquetFileReader reader = ParquetFileReader.open(InputFile.of(parquetFile));
+             ColumnReaders crs = reader.columnReaders(ColumnProjection.columns("fare_amount", "PULocationID"))) {
+            while (crs.nextBatch()) {
+                int n = crs.getRecordCount();
+                double[] fares = crs.getColumnReader("fare_amount").getDoubles();
+                int[] locs = crs.getColumnReader("PULocationID").getInts();
+                for (int i = 0; i < n; i++) {
+                    fareSum += fares[i];
+                    idSum += locs[i];
+                }
+            }
+        }
+        return fareSum + idSum;
+    }
+
+    // ── Row cursor API (measures row-oriented overhead on top of decode) ──────
+
+    /// Hardwood row cursor: sum trip_distance, one virtual call per row.
+    @Benchmark
+    public double parquetReadRowByRow() throws IOException {
         double sum = 0.0;
         ColumnProjection projection = ColumnProjection.columns("trip_distance");
         try (ParquetFileReader reader = ParquetFileReader.open(InputFile.of(parquetFile));
@@ -121,9 +169,9 @@ public double parquetRead() throws IOException {
         return sum;
     }
 
-    /// Hardwood: scan all rows, sum fare_amount + PULocationID (two columns).
+    /// Hardwood row cursor: sum fare_amount + PULocationID, two virtual calls per row.
     @Benchmark
-    public double parquetReadMultiColumn() throws IOException {
+    public double parquetReadMultiColumnRowByRow() throws IOException {
         double fareSum = 0.0;
         long idSum = 0L;
         ColumnProjection projection = ColumnProjection.columns("fare_amount", "PULocationID");
@@ -138,7 +186,9 @@ public double parquetReadMultiColumn() throws IOException {
         return fareSum + idSum;
     }
 
-    /// Vortex: scan all rows, sum trip_distance via fold.
+    // ── Vortex ────────────────────────────────────────────────────────────────
+
+    /// Vortex: decode trip_distance in chunks, sum via batch fold.
     @Benchmark
     public double vortexRead() throws IOException {
         double sum = 0.0;
@@ -153,7 +203,7 @@ public double vortexRead() throws IOException {
         return sum;
     }
 
-    /// Vortex: scan fare_amount + PULocationID, sum both (exercises multi-column projection).
+    /// Vortex: decode fare_amount + PULocationID in chunks, sum both via batch fold.
     @Benchmark
     public double vortexReadMultiColumn() throws IOException {
         double fareSum = 0.0;
@@ -171,6 +221,8 @@ public double vortexReadMultiColumn() throws IOException {
         return fareSum + idSum;
     }
 
+    // ── Setup helper ──────────────────────────────────────────────────────────
+
     private static Path downloadIfAbsent(Path dest, String url) throws Exception {
         if (Files.exists(dest)) {
             System.out.printf("[ParquetVsVortexReadBenchmark] cache hit: %s%n", dest);