diff --git a/CHANGELOG.md b/CHANGELOG.md index 722d20c45..e203ca42a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Breaking:** CSV import stores an empty cell in a number or boolean column as null instead of `0` or `false`, so inferred number and boolean columns are now nullable (read through `MaskedArray`), and an empty cell or a missing column fails the import where the schema declares the column non-nullable. ([#592](https://github.com/dfa1/vortex-java/issues/592)) ### Fixed +- ALP writes patch values that are all equal as a `vortex.constant`, as Rust does. ([#619](https://github.com/dfa1/vortex-java/pull/619)) +- Bit-packing writes its patches as Rust does: indices and per-1024-value chunk offsets narrowed to the smallest unsigned type that holds them, and equal values as a `vortex.constant`. ([#619](https://github.com/dfa1/vortex-java/pull/619)) - The cascade tries encodings in Rust's registration order, so a tie between two equally small encodings goes the way Rust breaks it. ([#604](https://github.com/dfa1/vortex-java/issues/604)) - ALP-RD packs its left and right parts at the dictionary's widths, as Rust does, instead of narrower widths that made it win where Rust picks a dictionary. ([#604](https://github.com/dfa1/vortex-java/issues/604)) - ALP on an `F32` column compresses its encoded integers through the cascade, as Rust does for both float widths, instead of storing them raw. ([#604](https://github.com/dfa1/vortex-java/issues/604)) diff --git a/docs/compatibility.md b/docs/compatibility.md index 968fe5d38..1ae07505f 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -140,7 +140,7 @@ decimals ([#430](https://github.com/dfa1/vortex-java/pull/430)) and nulls in nul | `vortex.decimal_byte_parts` | `DecimalBytePartsEncodingDecoder`| `DecimalBytePartsEncodingEncoder`| ✅ | ✅ | Write: precision ≤ 18 only (one i64 mantissa, no low parts); competes in the cascade | | `vortex.datetimeparts` | `DateTimePartsEncodingDecoder` | `DateTimePartsEncodingEncoder` | ✅ | ✅ | | | `vortex.pco` | `PcoEncodingDecoder` | `PcoEncodingEncoder` | ✅ | ✅ | Decode: all modes. Encode: Classic + Consecutive (orders 1–7) delta + IntMult, in Rust's chunk/page layout and byte-identical to pco 1.0.1 for those; FloatMult/FloatQuant and Lookback deferred | -| `fastlanes.bitpacked` | `BitpackedEncodingDecoder` | `BitpackedEncodingEncoder` | ✅ | ✅ | Unsigned integer PTypes | +| `fastlanes.bitpacked` | `BitpackedEncodingDecoder` | `BitpackedEncodingEncoder` | ✅ | ✅ | Unsigned integer PTypes. Patches are written as Rust's `compress_patches` leaves them: narrowed indices, values as a `vortex.constant` when all equal, and per-1024-value chunk offsets | | `fastlanes.delta` | `DeltaEncodingDecoder` | `DeltaEncodingEncoder` | ✅ | ✅ | Integer PTypes. In no edition: cascading writes offer it (bases/deltas cascaded, as Rust's `DeltaScheme`) only with `WriteOptions.withoutEditions()` | | `fastlanes.for` | `FrameOfReferenceEncodingDecoder`| `FrameOfReferenceEncodingEncoder`| ✅ | ✅ | Integer PTypes | | `fastlanes.rle` | `RleEncodingDecoder` | `RleEncodingEncoder` | ✅ | ✅ | Chunk-based RLE. Integers and floats (Rust's int and float RLE schemes); float runs compare raw bits, so -0.0 and NaN payloads round-trip. Cascades values/indices/offsets | diff --git a/integration/src/test/java/io/github/dfa1/vortex/integration/NullableFloatInteropIntegrationTest.java b/integration/src/test/java/io/github/dfa1/vortex/integration/NullableFloatInteropIntegrationTest.java index 9ce81f96a..6c075d17a 100644 --- a/integration/src/test/java/io/github/dfa1/vortex/integration/NullableFloatInteropIntegrationTest.java +++ b/integration/src/test/java/io/github/dfa1/vortex/integration/NullableFloatInteropIntegrationTest.java @@ -91,7 +91,16 @@ static Stream shapes() { i -> (i / 20) % 7 == 0), // taxi Airport_fee: one dominant value, two rare ones, nulls: a dict layout shape("f64 airport fee", PType.F64, i -> i % 17 == 0 ? 1.75 : i % 101 == 0 ? -1.75 : 0.0, - i -> i % 10 == 3)); + i -> i % 10 == 3), + // a few values ALP cannot round-trip, all equal: its patch values are a constant + shape("f64 equal exceptions", PType.F64, i -> i % 97 == 0 ? Math.PI : twoDecimals.applyAsDouble(i), + every7), + // the same in F32, over halves: ALP with constant patch values (two decimals + // would go to ALP-RD in F32), with and without nulls + shape("f32 equal exceptions", PType.F32, i -> i % 97 == 0 ? Math.PI : Math.floorMod(RANDOM[i], 1000) * 0.5, + every7), + shape("f32 equal exceptions, no nulls", PType.F32, + i -> i % 97 == 0 ? Math.PI : Math.floorMod(RANDOM[i], 1000) * 0.5, _ -> false)); } @ParameterizedTest(name = "{0}") diff --git a/integration/src/test/java/io/github/dfa1/vortex/integration/NullableIntegerInteropIntegrationTest.java b/integration/src/test/java/io/github/dfa1/vortex/integration/NullableIntegerInteropIntegrationTest.java index 4043eed34..57d95ee65 100644 --- a/integration/src/test/java/io/github/dfa1/vortex/integration/NullableIntegerInteropIntegrationTest.java +++ b/integration/src/test/java/io/github/dfa1/vortex/integration/NullableIntegerInteropIntegrationTest.java @@ -54,8 +54,7 @@ /// /// Each column goes through vortex-jni and vortex-java, and the two files must hold the same /// encoding tree, data and zone stats table alike. Each shape steers the cascade to a different -/// winner. Not covered: a column whose bit-packing needs patches, as Rust also stores the patches' -/// chunk offsets and Java does not yet. +/// winner. class NullableIntegerInteropIntegrationTest { private static final Session SESSION = Session.create(); @@ -97,7 +96,13 @@ static Stream shapes() { shape("95% null", PType.I32, i -> Math.floorMod(RANDOM[i], 1000), i -> Math.floorMod(RANDOM[i] >>> 20, 100) < 95), shape("clustered nulls", PType.I32, i -> Math.floorMod(RANDOM[i], 1000), i -> (i / 500) % 3 == 0), // one null in one zone: that zone's null count makes the stats table's dict - shape("one null", PType.I32, i -> Math.floorMod(RANDOM[i], 1000), i -> i == 5)); + shape("one null", PType.I32, i -> Math.floorMod(RANDOM[i], 1000), i -> i == 5), + // a few wide values: bit-packing with patches, which carry one offset per 1024 rows + shape("wide outliers", PType.I32, i -> i % 97 == 0 ? 1_000_000 + Math.floorMod(RANDOM[i], 1_000_000) + : Math.floorMod(RANDOM[i], 1000), every7), + // all outliers equal: the patch values are a constant + shape("equal outliers", PType.I32, i -> i % 97 == 0 ? 1_000_000_000 : Math.floorMod(RANDOM[i], 1000), + every7)); } @ParameterizedTest(name = "{0}") diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/AlpEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/AlpEncodingEncoder.java index 3b4a66482..42179ab50 100644 --- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/AlpEncodingEncoder.java +++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/AlpEncodingEncoder.java @@ -5,12 +5,12 @@ import io.github.dfa1.vortex.core.model.EncodingId; import io.github.dfa1.vortex.core.io.VortexFormat; import io.github.dfa1.vortex.core.proto.ProtoALPMetadata; -import io.github.dfa1.vortex.core.proto.ProtoPatchesMetadata; import io.github.dfa1.vortex.core.proto.ProtoScalarValue; import java.lang.foreign.MemorySegment; import java.util.Set; import java.util.ArrayList; +import java.util.Arrays; import java.util.List; /// Write-only encoder for `vortex.alp`. @@ -41,6 +41,8 @@ public final class AlpEncodingEncoder implements EncodingEncoder { /// `patch_bytes`). private static final int PATCH_BYTES_F64 = Double.BYTES + Short.BYTES; private static final int PATCH_BYTES_F32 = Float.BYTES + Short.BYTES; + /// Initial capacity of the exception arrays, grown by doubling: most columns have few. + private static final int INITIAL_PATCHES = 16; /// Creates the encoder. public AlpEncodingEncoder() { @@ -117,16 +119,36 @@ public CascadeStep encodeCascade(DType dtype, Object data, EncodeContext ctx) { /// Rust drops the exceptions at null rows: "we remove null exceptions in order to keep the /// Patches small" (`alp_encode_components_typed`). Their encoded slots keep the fill value. - private static void dropNullExceptions(List indices, List values, boolean[] validity) { + /// Compacts `indices` and `values` in place and returns how many are kept, at the front. + private static int dropNullExceptions(long[] indices, double[] values, boolean[] validity) { if (validity == null) { - return; + return indices.length; } - for (int i = indices.size() - 1; i >= 0; i--) { - if (!validity[indices.get(i)]) { - indices.remove(i); - values.remove(i); + int kept = 0; + for (int i = 0; i < indices.length; i++) { + if (validity[(int) indices[i]]) { + indices[kept] = indices[i]; + values[kept] = values[i]; + kept++; } } + return kept; + } + + /// The F32 counterpart of [#dropNullExceptions(long[], double[], boolean[])]. + private static int dropNullExceptions(long[] indices, float[] values, boolean[] validity) { + if (validity == null) { + return indices.length; + } + int kept = 0; + for (int i = 0; i < indices.length; i++) { + if (validity[(int) indices[i]]) { + indices[kept] = indices[i]; + values[kept] = values[i]; + kept++; + } + } + return kept; } /// The encoded ints, keeping the column's validity when it has one. @@ -234,8 +256,9 @@ private static AlpF64Data computeF64(double[] values) { int expF = exps[1]; long[] encodedArr = new long[n]; - var patchIndices = new ArrayList(); - var patchValues = new ArrayList(); + long[] patchIndices = new long[INITIAL_PATCHES]; + double[] patchValues = new double[INITIAL_PATCHES]; + int patches = 0; double min = Double.MAX_VALUE; double max = -Double.MAX_VALUE; @@ -248,8 +271,13 @@ private static AlpF64Data computeF64(double[] values) { // Bit-exact, as Rust's is_eq: -0.0 encodes to 0 and decodes to +0.0, so it is an // exception like any other value that does not round-trip. if (Double.doubleToRawLongBits(decodeF64(encoded, expE, expF)) != Double.doubleToRawLongBits(v)) { - patchIndices.add(i); - patchValues.add(v); + if (patches == patchIndices.length) { + patchIndices = Arrays.copyOf(patchIndices, patches * 2); + patchValues = Arrays.copyOf(patchValues, patches * 2); + } + patchIndices[patches] = i; + patchValues[patches] = v; + patches++; } else if (!haveFill) { fill = encoded; haveFill = true; @@ -265,14 +293,15 @@ private static AlpF64Data computeF64(double[] values) { // encoded child keeps its range (a 0 there widened prices' frame of reference); with no // such value the raw encodings stay, as in Rust. if (haveFill) { - for (int idx : patchIndices) { - encodedArr[idx] = fill; + for (int p = 0; p < patches; p++) { + encodedArr[(int) patchIndices[p]] = fill; } } ProtoScalarValue statsMin = n > 0 ? scalarF64(min) : null; ProtoScalarValue statsMax = n > 0 ? scalarF64(max) : null; - return new AlpF64Data(expE, expF, encodedArr, patchIndices, patchValues, statsMin, statsMax); + return new AlpF64Data(expE, expF, encodedArr, Arrays.copyOf(patchIndices, patches), + Arrays.copyOf(patchValues, patches), statsMin, statsMax); } private static EncodeResult encodeF64(double[] values, EncodeContext ctx) { @@ -286,39 +315,27 @@ private static EncodeResult encodeF64(double[] values, EncodeContext ctx) { EncodeNode encodedNode = EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, 0); - if (d.patchIndices().isEmpty()) { + if (d.patchIndices().length == 0) { byte[] metaBytes = new ProtoALPMetadata(d.expE(), d.expF(), null).encode(); EncodeNode root = new EncodeNode(EncodingId.VORTEX_ALP, MemorySegment.ofArray(metaBytes), new EncodeNode[]{encodedNode}, new int[0]); return new EncodeResult(root, List.of(EncodedBuffer.of(encodedBuf, PType.I64)), d.statsMin(), d.statsMax()); } - int numPatches = d.patchIndices().size(); PatchBuffers patchBuffers = PatchBuffers.of(d.patchIndices(), n, ctx); - MemorySegment valBuf = ctx.arena().allocate((long) numPatches * 8, 8); - for (int i = 0; i < numPatches; i++) { - valBuf.setAtIndex(VortexFormat.LE_DOUBLE, i, d.patchValues().get(i)); - } - - ProtoPatchesMetadata patches = patchBuffers.meta(numPatches); - byte[] metaBytes = new ProtoALPMetadata(d.expE(), d.expF(), patches).encode(); - - EncodeNode idxNode = EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, 1); - EncodeNode valNode = EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, 2); - EncodeNode offsetsNode = EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, 3); - EncodeNode root = new EncodeNode(EncodingId.VORTEX_ALP, - MemorySegment.ofArray(metaBytes), - new EncodeNode[]{encodedNode, idxNode, valNode, offsetsNode}, - new int[0]); - return new EncodeResult(root, List.of(EncodedBuffer.of(encodedBuf, PType.I64), - EncodedBuffer.of(patchBuffers.indices(), patchBuffers.indexType()), EncodedBuffer.of(valBuf, PType.F64), - EncodedBuffer.of(patchBuffers.offsets(), patchBuffers.offsetType())), d.statsMin(), d.statsMax()); + List buffers = new ArrayList<>(List.of(EncodedBuffer.of(encodedBuf, PType.I64))); + EncodeNode[] patchNodes = patchBuffers.append(d.patchValues(), PType.F64, buffers, ctx); + byte[] metaBytes = new ProtoALPMetadata(d.expE(), d.expF(), patchBuffers.meta(d.patchIndices().length)) + .encode(); + EncodeNode root = new EncodeNode(EncodingId.VORTEX_ALP, MemorySegment.ofArray(metaBytes), + new EncodeNode[]{encodedNode, patchNodes[0], patchNodes[1], patchNodes[2]}, new int[0]); + return new EncodeResult(root, buffers, d.statsMin(), d.statsMax()); } private static CascadeStep encodeCascadeF64(double[] values, boolean[] validity, EncodeContext ctx) { AlpF64Data d = computeF64(values); - dropNullExceptions(d.patchIndices(), d.patchValues(), validity); - if (d.patchIndices().isEmpty()) { + int kept = dropNullExceptions(d.patchIndices(), d.patchValues(), validity); + if (kept == 0) { byte[] metaBytes = new ProtoALPMetadata(d.expE(), d.expF(), null).encode(); EncodeNode partialRoot = new EncodeNode(EncodingId.VORTEX_ALP, MemorySegment.ofArray(metaBytes), new EncodeNode[1], new int[0]); @@ -326,25 +343,14 @@ private static CascadeStep encodeCascadeF64(double[] values, boolean[] validity, return new CascadeStep(partialRoot, List.of(), List.of(slot), d.statsMin(), d.statsMax(), true); } - int numPatches = d.patchIndices().size(); - PatchBuffers patchBuffers = PatchBuffers.of(d.patchIndices(), values.length, ctx); - MemorySegment valBuf = ctx.arena().allocate((long) numPatches * 8, 8); - for (int i = 0; i < numPatches; i++) { - valBuf.setAtIndex(VortexFormat.LE_DOUBLE, i, d.patchValues().get(i)); - } - - ProtoPatchesMetadata patches = patchBuffers.meta(numPatches); - byte[] metaBytes = new ProtoALPMetadata(d.expE(), d.expF(), patches).encode(); - - EncodeNode idxNode = EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, 0); - EncodeNode valNode = EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, 1); - EncodeNode offsetsNode = EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, 2); - EncodeNode partialRoot = new EncodeNode(EncodingId.VORTEX_ALP, - MemorySegment.ofArray(metaBytes), new EncodeNode[]{null, idxNode, valNode, offsetsNode}, new int[0]); + PatchBuffers patchBuffers = PatchBuffers.of(Arrays.copyOf(d.patchIndices(), kept), values.length, ctx); + List buffers = new ArrayList<>(); + EncodeNode[] patchNodes = patchBuffers.append(Arrays.copyOf(d.patchValues(), kept), PType.F64, buffers, ctx); + byte[] metaBytes = new ProtoALPMetadata(d.expE(), d.expF(), patchBuffers.meta(kept)).encode(); + EncodeNode partialRoot = new EncodeNode(EncodingId.VORTEX_ALP, MemorySegment.ofArray(metaBytes), + new EncodeNode[]{null, patchNodes[0], patchNodes[1], patchNodes[2]}, new int[0]); ChildSlot slot = encodedSlot(DType.I64, d.encodedArr(), validity); - return new CascadeStep(partialRoot, List.of(EncodedBuffer.of(patchBuffers.indices(), patchBuffers.indexType()), - EncodedBuffer.of(valBuf, PType.F64), EncodedBuffer.of(patchBuffers.offsets(), patchBuffers.offsetType())), - List.of(slot), d.statsMin(), d.statsMax(), true); + return new CascadeStep(partialRoot, buffers, List.of(slot), d.statsMin(), d.statsMax(), true); } private static int encodeF32(float v, int e, int f) { @@ -424,8 +430,9 @@ private static AlpF32Data computeF32(float[] values) { int expE = exps[0]; int expF = exps[1]; int[] encodedArr = new int[n]; - var patchIndices = new ArrayList(); - var patchValues = new ArrayList(); + long[] patchIndices = new long[INITIAL_PATCHES]; + float[] patchValues = new float[INITIAL_PATCHES]; + int patches = 0; float min = Float.MAX_VALUE; float max = -Float.MAX_VALUE; @@ -437,8 +444,13 @@ private static AlpF32Data computeF32(float[] values) { encodedArr[i] = encoded; // Bit-exact: see the F64 path above for why (-0.0 vs +0.0). if (Float.floatToRawIntBits(decodeF32(encoded, expE, expF)) != Float.floatToRawIntBits(v)) { - patchIndices.add(i); - patchValues.add(v); + if (patches == patchIndices.length) { + patchIndices = Arrays.copyOf(patchIndices, patches * 2); + patchValues = Arrays.copyOf(patchValues, patches * 2); + } + patchIndices[patches] = i; + patchValues[patches] = v; + patches++; } else if (!haveFill) { fill = encoded; haveFill = true; @@ -451,22 +463,23 @@ private static AlpF32Data computeF32(float[] values) { } } if (haveFill) { - for (int idx : patchIndices) { - encodedArr[idx] = fill; + for (int p = 0; p < patches; p++) { + encodedArr[(int) patchIndices[p]] = fill; } } ProtoScalarValue statsMin = n > 0 ? scalarF32(min) : null; ProtoScalarValue statsMax = n > 0 ? scalarF32(max) : null; - return new AlpF32Data(expE, expF, encodedArr, patchIndices, patchValues, statsMin, statsMax); + return new AlpF32Data(expE, expF, encodedArr, Arrays.copyOf(patchIndices, patches), + Arrays.copyOf(patchValues, patches), statsMin, statsMax); } /// The F32 counterpart of [#encodeCascadeF64(double[], boolean[], EncodeContext)]: Rust's ALP scheme /// compresses the encoded `i32`s through the cascade for either width. private static CascadeStep encodeCascadeF32(float[] values, boolean[] validity, EncodeContext ctx) { AlpF32Data d = computeF32(values); - dropNullExceptions(d.patchIndices(), d.patchValues(), validity); - if (d.patchIndices().isEmpty()) { + int kept = dropNullExceptions(d.patchIndices(), d.patchValues(), validity); + if (kept == 0) { byte[] metaBytes = new ProtoALPMetadata(d.expE(), d.expF(), null).encode(); EncodeNode partialRoot = new EncodeNode(EncodingId.VORTEX_ALP, MemorySegment.ofArray(metaBytes), new EncodeNode[1], new int[0]); @@ -474,25 +487,14 @@ private static CascadeStep encodeCascadeF32(float[] values, boolean[] validity, return new CascadeStep(partialRoot, List.of(), List.of(slot), d.statsMin(), d.statsMax(), true); } - int numPatches = d.patchIndices().size(); - PatchBuffers patchBuffers = PatchBuffers.of(d.patchIndices(), values.length, ctx); - MemorySegment valBuf = ctx.arena().allocate((long) numPatches * 4, 4); - for (int i = 0; i < numPatches; i++) { - valBuf.setAtIndex(VortexFormat.LE_FLOAT, i, d.patchValues().get(i)); - } - - ProtoPatchesMetadata patches = patchBuffers.meta(numPatches); - byte[] metaBytes = new ProtoALPMetadata(d.expE(), d.expF(), patches).encode(); - - EncodeNode idxNode = EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, 0); - EncodeNode valNode = EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, 1); - EncodeNode offsetsNode = EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, 2); - EncodeNode partialRoot = new EncodeNode(EncodingId.VORTEX_ALP, - MemorySegment.ofArray(metaBytes), new EncodeNode[]{null, idxNode, valNode, offsetsNode}, new int[0]); + PatchBuffers patchBuffers = PatchBuffers.of(Arrays.copyOf(d.patchIndices(), kept), values.length, ctx); + List buffers = new ArrayList<>(); + EncodeNode[] patchNodes = patchBuffers.append(Arrays.copyOf(d.patchValues(), kept), PType.F32, buffers, ctx); + byte[] metaBytes = new ProtoALPMetadata(d.expE(), d.expF(), patchBuffers.meta(kept)).encode(); + EncodeNode partialRoot = new EncodeNode(EncodingId.VORTEX_ALP, MemorySegment.ofArray(metaBytes), + new EncodeNode[]{null, patchNodes[0], patchNodes[1], patchNodes[2]}, new int[0]); ChildSlot slot = encodedSlot(DType.I32, d.encodedArr(), validity); - return new CascadeStep(partialRoot, List.of(EncodedBuffer.of(patchBuffers.indices(), patchBuffers.indexType()), - EncodedBuffer.of(valBuf, PType.F32), EncodedBuffer.of(patchBuffers.offsets(), patchBuffers.offsetType())), - List.of(slot), d.statsMin(), d.statsMax(), true); + return new CascadeStep(partialRoot, buffers, List.of(slot), d.statsMin(), d.statsMax(), true); } private static EncodeResult encodeF32(float[] values, EncodeContext ctx) { @@ -501,8 +503,8 @@ private static EncodeResult encodeF32(float[] values, EncodeContext ctx) { int expE = d.expE(); int expF = d.expF(); int[] encodedArr = d.encodedArr(); - List patchIndices = d.patchIndices(); - List patchValues = d.patchValues(); + long[] patchIndices = d.patchIndices(); + float[] patchValues = d.patchValues(); ProtoScalarValue statsMin = d.statsMin(); ProtoScalarValue statsMax = d.statsMax(); @@ -513,33 +515,20 @@ private static EncodeResult encodeF32(float[] values, EncodeContext ctx) { EncodeNode encodedNode = EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, 0); - if (patchIndices.isEmpty()) { + if (patchIndices.length == 0) { byte[] metaBytes = new ProtoALPMetadata(expE, expF, null).encode(); EncodeNode root = new EncodeNode(EncodingId.VORTEX_ALP, MemorySegment.ofArray(metaBytes), new EncodeNode[]{encodedNode}, new int[0]); return new EncodeResult(root, List.of(EncodedBuffer.of(encodedBuf, PType.I32)), statsMin, statsMax); } - int numPatches = patchIndices.size(); PatchBuffers patchBuffers = PatchBuffers.of(patchIndices, n, ctx); - MemorySegment valBuf = ctx.arena().allocate((long) numPatches * 4, 4); - for (int i = 0; i < numPatches; i++) { - valBuf.setAtIndex(VortexFormat.LE_FLOAT, i, patchValues.get(i)); - } - - ProtoPatchesMetadata patches = patchBuffers.meta(numPatches); - byte[] metaBytes = new ProtoALPMetadata(expE, expF, patches).encode(); - - EncodeNode idxNode = EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, 1); - EncodeNode valNode = EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, 2); - EncodeNode offsetsNode = EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, 3); - EncodeNode root = new EncodeNode(EncodingId.VORTEX_ALP, - MemorySegment.ofArray(metaBytes), - new EncodeNode[]{encodedNode, idxNode, valNode, offsetsNode}, - new int[0]); - return new EncodeResult(root, List.of(EncodedBuffer.of(encodedBuf, PType.I32), - EncodedBuffer.of(patchBuffers.indices(), patchBuffers.indexType()), EncodedBuffer.of(valBuf, PType.F32), - EncodedBuffer.of(patchBuffers.offsets(), patchBuffers.offsetType())), statsMin, statsMax); + List buffers = new ArrayList<>(List.of(EncodedBuffer.of(encodedBuf, PType.I32))); + EncodeNode[] patchNodes = patchBuffers.append(patchValues, PType.F32, buffers, ctx); + byte[] metaBytes = new ProtoALPMetadata(expE, expF, patchBuffers.meta(patchIndices.length)).encode(); + EncodeNode root = new EncodeNode(EncodingId.VORTEX_ALP, MemorySegment.ofArray(metaBytes), + new EncodeNode[]{encodedNode, patchNodes[0], patchNodes[1], patchNodes[2]}, new int[0]); + return new EncodeResult(root, buffers, statsMin, statsMax); } private static ProtoScalarValue scalarF64(double v) { @@ -552,13 +541,13 @@ private static ProtoScalarValue scalarF32(float v) { @SuppressWarnings("java:S6218") // internal data carrier; record components are arrays of immutable primitives or refs that flow through pipelines without ever being compared. private record AlpF32Data(int expE, int expF, int[] encodedArr, - List patchIndices, List patchValues, + long[] patchIndices, float[] patchValues, ProtoScalarValue statsMin, ProtoScalarValue statsMax) { } @SuppressWarnings("java:S6218") // internal data carrier; record components are arrays of immutable primitives or refs that flow through pipelines without ever being compared. private record AlpF64Data(int expE, int expF, long[] encodedArr, - List patchIndices, List patchValues, + long[] patchIndices, double[] patchValues, ProtoScalarValue statsMin, ProtoScalarValue statsMax) { } } diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/AlpRdEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/AlpRdEncodingEncoder.java index fc381eebc..a05d89307 100644 --- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/AlpRdEncodingEncoder.java +++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/AlpRdEncodingEncoder.java @@ -1,14 +1,12 @@ package io.github.dfa1.vortex.writer.encode; import io.github.dfa1.vortex.core.compute.LongIntMap; -import io.github.dfa1.vortex.core.io.VortexFormat; import io.github.dfa1.vortex.core.model.DType; import io.github.dfa1.vortex.core.model.PType; import io.github.dfa1.vortex.core.model.EncodingId; import io.github.dfa1.vortex.core.proto.ProtoALPRDMetadata; import io.github.dfa1.vortex.core.proto.ProtoPatchesMetadata; import io.github.dfa1.vortex.core.proto.ProtoScalarValue; -import io.github.dfa1.vortex.core.simd.SimdOperationsSupport; import java.lang.foreign.MemorySegment; import java.util.ArrayList; @@ -362,18 +360,7 @@ private static EncodeResult buildEncodeResult( allBuffers.add(EncodedBuffer.of(PatchBuffers.unsigned(excPosArr, idxType, ctx), idxType)); EncodeNode idxNode = EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, idxOffset); - EncodeNode valNode; - int valOffset = allBuffers.size(); - if (SimdOperationsSupport.preferred().allEqual(excValsArr, PType.I16)) { - EncodeResult constant = new ConstantEncodingEncoder().encode(DType.U16, excValsArr, ctx); - allBuffers.addAll(constant.encodedBuffers()); - valNode = EncodeNode.remapBufferIndices(constant.rootNode(), valOffset); - } else { - MemorySegment valBuf = ctx.arena().allocate((long) excValsArr.length * Short.BYTES, Short.BYTES); - MemorySegment.copy(excValsArr, 0, valBuf, VortexFormat.LE_SHORT, 0, excValsArr.length); - allBuffers.add(EncodedBuffer.of(valBuf, PType.U16)); - valNode = EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, valOffset); - } + EncodeNode valNode = PatchBuffers.valuesNode(excValsArr, PType.U16, allBuffers, ctx); patchesMeta = new ProtoPatchesMetadata( exceptions.size, diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/BitpackedEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/BitpackedEncodingEncoder.java index 3d1040cc0..03b0ca5cf 100644 --- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/BitpackedEncodingEncoder.java +++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/BitpackedEncodingEncoder.java @@ -7,16 +7,15 @@ import io.github.dfa1.vortex.core.compute.FastLanes; import io.github.dfa1.vortex.core.compute.PrimitiveArrays; import io.github.dfa1.vortex.core.io.VortexFormat; -import io.github.dfa1.vortex.core.io.PTypeIO; import io.github.dfa1.vortex.core.simd.SimdOperations; import io.github.dfa1.vortex.core.simd.SimdOperationsSupport; import io.github.dfa1.vortex.core.proto.ProtoBitPackedMetadata; -import io.github.dfa1.vortex.core.proto.ProtoPatchesMetadata; import io.github.dfa1.vortex.core.proto.ProtoScalarValue; import java.lang.foreign.Arena; import java.lang.foreign.MemorySegment; import java.lang.foreign.ValueLayout; +import java.util.ArrayList; import java.util.Arrays; import java.util.List; @@ -207,7 +206,7 @@ private static EncodeResult encodeLongs(PType ptype, long[] longs, EncodeContext return new EncodeResult(root, List.of(EncodedBuffer.of(packed, ptype)), statsMin, statsMax); } - int[] patchIdx = new int[numPatches]; + long[] patchIdx = new long[numPatches]; long[] patchVal = new long[numPatches]; long packCap = 1L << bitWidth; for (int i = 0, p = 0; p < numPatches; i++) { @@ -217,22 +216,17 @@ private static EncodeResult encodeLongs(PType ptype, long[] longs, EncodeContext p++; } } - PType idxPtype = PType.narrowestUnsigned(n); - MemorySegment idxBuf = buildPatchIdxBuf(patchIdx, idxPtype, ctx.arena()); - MemorySegment valBuf = buildPatchValBuf(patchVal, ptype, ctx.arena()); - ProtoPatchesMetadata patches = new ProtoPatchesMetadata( - numPatches, 0L, - io.github.dfa1.vortex.core.proto.ProtoPType.fromValue(idxPtype.ordinal()), - null, null, null); - byte[] metaBytes = new ProtoBitPackedMetadata(bitWidth, 0, patches).encode(); - - EncodeNode idxNode = EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, 1); - EncodeNode valNode = EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, 2); + // Rust's gather_patches records each 1024-value chunk's first patch, and compress_patches + // narrows the indices and those chunk offsets and keeps equal values as a constant + // (vortex-btrblocks schemes/patches.rs): children [indices, values, chunk_offsets] + PatchBuffers patchBuffers = PatchBuffers.of(patchIdx, n, ctx); + List buffers = new ArrayList<>(List.of(EncodedBuffer.of(packed, ptype))); + EncodeNode[] patchNodes = patchBuffers.append(patchVal, ptype, buffers, ctx); + byte[] metaBytes = new ProtoBitPackedMetadata(bitWidth, 0, patchBuffers.meta(numPatches)).encode(); EncodeNode root = new EncodeNode(EncodingId.FASTLANES_BITPACKED, MemorySegment.ofArray(metaBytes), - new EncodeNode[]{idxNode, valNode}, new int[]{0}); - return new EncodeResult(root, List.of(EncodedBuffer.of(packed, ptype), EncodedBuffer.of(idxBuf, idxPtype), - EncodedBuffer.of(valBuf, ptype)), statsMin, statsMax); + patchNodes, new int[]{0}); + return new EncodeResult(root, buffers, statsMin, statsMax); } /// Picks the bit-width that minimizes `packed_bytes + exceptions_bytes`. @@ -257,26 +251,6 @@ private static int bestBitWidth(int[] bitWidthFreq, int bytesPerException, int n return bestWidth; } - private static MemorySegment buildPatchIdxBuf(int[] idx, PType idxPtype, Arena arena) { - int numPatches = idx.length; - int elemBytes = idxPtype.byteSize(); - MemorySegment seg = arena.allocate(Math.max(1L, (long) numPatches * elemBytes), elemBytes); - for (int i = 0; i < numPatches; i++) { - PTypeIO.set(seg, (long) i * elemBytes, idxPtype, idx[i]); - } - return seg; - } - - private static MemorySegment buildPatchValBuf(long[] val, PType ptype, Arena arena) { - int numPatches = val.length; - int elemBytes = ptype.byteSize(); - MemorySegment seg = arena.allocate(Math.max(1L, (long) numPatches * elemBytes), elemBytes); - for (int i = 0; i < numPatches; i++) { - PTypeIO.set(seg, (long) i * elemBytes, ptype, val[i]); - } - return seg; - } - private static MemorySegment packFastLanes(long[] values, int n, int bitWidth, int typeBits, Arena arena) { if (bitWidth == 0 || n == 0) { return MemorySegment.ofArray(new byte[0]); diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ConstantEncodingEncoder.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ConstantEncodingEncoder.java index 4a0e25303..9e9692d25 100644 --- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ConstantEncodingEncoder.java +++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/ConstantEncodingEncoder.java @@ -11,6 +11,7 @@ import java.lang.reflect.Array; import java.nio.charset.StandardCharsets; import java.util.Arrays; +import java.util.Optional; import java.util.OptionalLong; /// Write-only encoder for `vortex.constant`. @@ -70,16 +71,45 @@ public EncodeResult encode(DType dtype, Object data, EncodeContext ctx) { if (!(dtype instanceof DType.Primitive p)) { throw new VortexException(EncodingId.VORTEX_CONSTANT, "encode only supports Primitive or Bool dtype, got " + dtype); } - PType ptype = p.ptype(); - long firstRaw = constantBits(data, ptype) + return encodeIfConstant(p.ptype(), data) .orElseThrow(() -> new VortexException(EncodingId.VORTEX_CONSTANT, "not a constant array")); - ProtoScalarValue scalar = buildScalar(ptype, firstRaw); - byte[] scalarBytes = scalar.encode(); - ProtoScalarValue statsScalar = scalar; - // A constant array's min and max are both the one repeated value, by construction -- no - // scan needed. Empty arrays report no stats, matching every other encoder's convention. - ProtoScalarValue stats = Array.getLength(data) > 0 ? statsScalar : null; - return EncodeResult.simple(EncodingId.VORTEX_CONSTANT, EncodedBuffer.bytes(MemorySegment.ofArray(scalarBytes)), stats, stats); + } + + /// Encodes `data` as a `vortex.constant` when every value is equal (floats by raw bits), in + /// one scan: checking first and then encoding would scan it twice. + /// + /// @param ptype the values' type + /// @param data a primitive array of `ptype` + /// @return the constant array, or empty when the values differ + static Optional encodeIfConstant(PType ptype, Object data) { + OptionalLong bits = constantBits(data, ptype); + if (bits.isEmpty()) { + return Optional.empty(); + } + return Optional.of(constant(ptype, bits.getAsLong(), Array.getLength(data) > 0)); + } + + /// The [#encodeIfConstant(PType, Object)] of integers already widened to `long`, as + /// `PrimitiveArrays.toLongs` widens them: zero-extended when unsigned, sign-extended when signed. + /// + /// @param ptype the integer type the values were widened from + /// @param widened the widened values + /// @return the constant array, or empty when the values differ + static Optional encodeIfConstantWidened(PType ptype, long[] widened) { + if (widened.length > 0 && !SimdOperationsSupport.preferred().allEqual(widened, PType.I64)) { + return Optional.empty(); + } + long bits = widened.length > 0 ? widened[0] : 0L; + return Optional.of(constant(ptype, bits, widened.length > 0)); + } + + // A constant array's min and max are both the one repeated value, by construction -- no + // scan needed. Empty arrays report no stats, matching every other encoder's convention. + private static EncodeResult constant(PType ptype, long rawBits, boolean hasStats) { + ProtoScalarValue scalar = buildScalar(ptype, rawBits); + ProtoScalarValue stats = hasStats ? scalar : null; + return EncodeResult.simple(EncodingId.VORTEX_CONSTANT, EncodedBuffer.bytes(MemorySegment.ofArray(scalar.encode())), + stats, stats); } @Override diff --git a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/PatchBuffers.java b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/PatchBuffers.java index 138ef5558..47727fcff 100644 --- a/writer/src/main/java/io/github/dfa1/vortex/writer/encode/PatchBuffers.java +++ b/writer/src/main/java/io/github/dfa1/vortex/writer/encode/PatchBuffers.java @@ -1,6 +1,9 @@ package io.github.dfa1.vortex.writer.encode; +import io.github.dfa1.vortex.core.compute.PrimitiveArrays; +import io.github.dfa1.vortex.core.io.PTypeIO; import io.github.dfa1.vortex.core.io.VortexFormat; +import io.github.dfa1.vortex.core.model.EncodingId; import io.github.dfa1.vortex.core.model.PType; import io.github.dfa1.vortex.core.proto.ProtoPType; import io.github.dfa1.vortex.core.proto.ProtoPatchesMetadata; @@ -8,6 +11,7 @@ import java.lang.foreign.MemorySegment; import java.lang.foreign.ValueLayout; import java.util.List; +import java.util.Optional; /// The index and chunk-offset buffers of an encoding's patches, laid out as Rust's /// `compress_patches` (`vortex-btrblocks`) leaves them: positions and offsets narrowed to the @@ -24,16 +28,17 @@ record PatchBuffers(PType indexType, MemorySegment indices, PType offsetType, Me /// Values per chunk of patch offsets (Rust's `ENCODE_CHUNK_SIZE`, one FastLanes block). static final int CHUNK_SIZE = 1024; - /// Lays out the patches of an array of `length` values, `positions` being ascending. + /// Lays out the patches of an array of `length` values, `positionArray` being ascending. /// - /// @param positions the positions of the patched values, ascending - /// @param length the number of values in the array being patched - /// @param ctx the context supplying the arena + /// @param positionArray the positions of the patched values, ascending, at least one + /// @param length the number of values in the array being patched + /// @param ctx the context supplying the arena /// @return the buffers, with chunk offsets - static PatchBuffers of(List positions, int length, EncodeContext ctx) { - long[] positionArray = new long[positions.size()]; - for (int i = 0; i < positionArray.length; i++) { - positionArray[i] = positions.get(i); + /// @throws IllegalArgumentException if there are no positions: an array without patches has no + /// patch children at all + static PatchBuffers of(long[] positionArray, int length, EncodeContext ctx) { + if (positionArray.length == 0) { + throw new IllegalArgumentException("no patches to lay out"); } int chunkCount = (length + CHUNK_SIZE - 1) / CHUNK_SIZE; long[] offsetArray = new long[chunkCount]; @@ -50,6 +55,62 @@ static PatchBuffers of(List positions, int length, EncodeContext ctx) { offsetType, unsigned(offsetArray, offsetType, ctx), chunkCount); } + /// Appends the patches to `buffers` as the three children Rust writes them as: indices, + /// values (see [#valuesNode(Object, PType, List, EncodeContext)]) and chunk offsets. + /// + /// @param values the patch values, as [#valuesNode(Object, PType, List, EncodeContext)] takes them + /// @param ptype the values' type + /// @param buffers the node's buffers so far, appended to + /// @param ctx the context supplying the arena + /// @return the indices, values and chunk-offsets children, pointing at the buffers appended + EncodeNode[] append(Object values, PType ptype, List buffers, EncodeContext ctx) { + EncodeNode indicesNode = EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, buffers.size()); + buffers.add(EncodedBuffer.of(indices, indexType)); + EncodeNode valuesNode = valuesNode(values, ptype, buffers, ctx); + EncodeNode offsetsNode = EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, buffers.size()); + buffers.add(EncodedBuffer.of(offsets, offsetType)); + return new EncodeNode[]{indicesNode, valuesNode, offsetsNode}; + } + + /// Appends the patch values to `buffers` as Rust's `compress_patches` leaves them: a + /// `vortex.constant` when every value is equal, a `vortex.primitive` otherwise. + /// + /// @param values the patch values: a primitive array of `ptype`, or for an integer `ptype` its + /// values widened to a `long[]` as `PrimitiveArrays.toLongs` widens them + /// @param ptype the values' type + /// @param buffers the node's buffers so far, appended to + /// @param ctx the context supplying the arena + /// @return the values child, pointing at the buffers it appended + static EncodeNode valuesNode(Object values, PType ptype, List buffers, EncodeContext ctx) { + int first = buffers.size(); + boolean widened = values instanceof long[] && ptype.isInteger(); + Optional constant = widened + ? ConstantEncodingEncoder.encodeIfConstantWidened(ptype, (long[]) values) + : ConstantEncodingEncoder.encodeIfConstant(ptype, values); + if (constant.isPresent()) { + buffers.addAll(constant.get().encodedBuffers()); + return EncodeNode.remapBufferIndices(constant.get().rootNode(), first); + } + MemorySegment segment; + if (widened) { + segment = narrowed((long[]) values, ptype, ctx); + } else { + segment = PrimitiveArrays.toSegment(values, ptype, ctx.arena()); + } + buffers.add(EncodedBuffer.of(segment, ptype)); + return EncodeNode.leaf(EncodingId.VORTEX_PRIMITIVE, first); + } + + // Writes widened integers back at their own width, in one copy. + private static MemorySegment narrowed(long[] values, PType ptype, EncodeContext ctx) { + int width = ptype.byteSize(); + MemorySegment segment = ctx.arena().allocate((long) values.length * width, width); + for (int i = 0; i < values.length; i++) { + PTypeIO.set(segment, (long) i * width, ptype, values[i]); + } + return segment; + } + /// The patches metadata for `count` patches. /// /// @param count the number of patches diff --git a/writer/src/test/java/io/github/dfa1/vortex/writer/encode/AlpEncodingEncoderTest.java b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/AlpEncodingEncoderTest.java index dbfc2c83f..a8651dea0 100644 --- a/writer/src/test/java/io/github/dfa1/vortex/writer/encode/AlpEncodingEncoderTest.java +++ b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/AlpEncodingEncoderTest.java @@ -16,6 +16,7 @@ import io.github.dfa1.vortex.core.proto.ProtoPType; import io.github.dfa1.vortex.core.proto.ProtoPatchesMetadata; import io.github.dfa1.vortex.reader.decode.AlpEncodingDecoder; +import io.github.dfa1.vortex.reader.decode.ConstantEncodingDecoder; import io.github.dfa1.vortex.reader.decode.PrimitiveEncodingDecoder; import org.junit.jupiter.api.Nested; import org.junit.jupiter.api.Test; @@ -36,7 +37,8 @@ class AlpEncodingEncoderTest { private static final AlpEncodingEncoder ENCODER = new AlpEncodingEncoder(); private static final AlpEncodingDecoder DECODER = new AlpEncodingDecoder(); - private static final ReadRegistry REGISTRY = TestRegistry.ofDecoders(DECODER, new PrimitiveEncodingDecoder()); + private static final ReadRegistry REGISTRY = TestRegistry.ofDecoders(DECODER, new PrimitiveEncodingDecoder(), + new ConstantEncodingDecoder()); @Nested class Decode { @@ -247,6 +249,26 @@ void encode_f64_patchesAreNarrowedWithChunkOffsets() throws java.io.IOException assertThat(offsets.toArray(java.lang.foreign.ValueLayout.JAVA_BYTE)).containsExactly(0, 1, 3); } + @Test + void encode_f64_equalExceptions_patchValuesAreConstant() { + // Given: Rust's compress_patches keeps patch values that are all equal as a constant + double[] values = new double[2_048]; + java.util.Arrays.fill(values, 1.0); + values[10] = Math.PI; + values[1_500] = Math.PI; + + // When + EncodeResult result = ENCODER.encode(DTypes.F64, values, EncodeTestHelper.testCtx()); + + // Then: encoded, indices, values, chunk offsets + assertThat(result.rootNode().children()[2].encodingId()).isEqualTo(EncodingId.VORTEX_CONSTANT); + DecodeContext ctx = DecodeTestHelper.toDecodeContext(result, values.length, DTypes.F64, REGISTRY); + DoubleArray decoded = (DoubleArray) DECODER.decode(ctx); + assertThat(decoded.getDouble(10)).isEqualTo(Math.PI); + assertThat(decoded.getDouble(1_500)).isEqualTo(Math.PI); + assertThat(decoded.getDouble(11)).isEqualTo(1.0); + } + @Test void encode_f64_roundTrip_noPatches() { // Given diff --git a/writer/src/test/java/io/github/dfa1/vortex/writer/encode/BitpackedEncodingPatchesTest.java b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/BitpackedEncodingPatchesTest.java index 41ef912f9..15beadc45 100644 --- a/writer/src/test/java/io/github/dfa1/vortex/writer/encode/BitpackedEncodingPatchesTest.java +++ b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/BitpackedEncodingPatchesTest.java @@ -5,21 +5,33 @@ import io.github.dfa1.vortex.core.testing.DTypes; import io.github.dfa1.vortex.reader.decode.DecodeContext; +import io.github.dfa1.vortex.core.compute.PrimitiveArrays; +import io.github.dfa1.vortex.core.model.DType; import io.github.dfa1.vortex.core.model.EncodingId; +import io.github.dfa1.vortex.core.model.PType; import io.github.dfa1.vortex.core.io.VortexFormat; import io.github.dfa1.vortex.reader.ReadRegistry; import io.github.dfa1.vortex.reader.decode.TestRegistry; import io.github.dfa1.vortex.core.proto.ProtoBitPackedMetadata; +import io.github.dfa1.vortex.core.proto.ProtoPType; import io.github.dfa1.vortex.core.proto.ProtoPatchesMetadata; import io.github.dfa1.vortex.reader.decode.BitpackedEncodingDecoder; +import io.github.dfa1.vortex.reader.decode.ConstantEncodingDecoder; import io.github.dfa1.vortex.reader.decode.PrimitiveEncodingDecoder; import org.junit.jupiter.api.Nested; import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.Arguments; +import org.junit.jupiter.params.provider.MethodSource; +import java.io.IOException; import java.lang.foreign.Arena; import java.lang.foreign.MemorySegment; import java.nio.ByteBuffer; import java.nio.ByteOrder; +import java.util.Arrays; +import java.util.List; +import java.util.stream.Stream; import static org.assertj.core.api.Assertions.assertThat; @@ -27,7 +39,8 @@ class BitpackedEncodingPatchesTest { private static final BitpackedEncodingEncoder ENCODER = new BitpackedEncodingEncoder(); private static final BitpackedEncodingDecoder DECODER = new BitpackedEncodingDecoder(); - private static final ReadRegistry REGISTRY = TestRegistry.ofDecoders(DECODER, new PrimitiveEncodingDecoder()); + private static final ReadRegistry REGISTRY = TestRegistry.ofDecoders(DECODER, new PrimitiveEncodingDecoder(), + new ConstantEncodingDecoder()); @Nested class Decode { @@ -84,43 +97,174 @@ void decode_appliesPatches_overridingBitPackedValues() { @Nested class Encode { + /// Rust's `gather_patches` + `compress_patches`: children [indices, values, chunk_offsets], + /// the indices and chunk offsets narrowed to the smallest unsigned type holding the largest. @Test - void encode_thenDecode_roundTripsWithPatches() { + void distinctOutliers_patchesCarryNarrowedIndicesAndChunkOffsets() throws IOException { + // Given — 3000 small values over 3 chunks of 1024, two wide ones: positions up to 2500 + // need u16, while the chunk offsets [0, 1, 1] fit in u8 + int[] values = new int[3000]; + values[42] = 70_000; + values[2500] = 80_000; + + // When + EncodeResult result = ENCODER.encode(DTypes.I32, values, EncodeTestHelper.testCtx()); + + // Then + ProtoPatchesMetadata patches = metadata(result).patches(); + assertThat(patches.indices_ptype()).isEqualTo(ProtoPType.U16); + assertThat(patches.chunk_offsets_len()).isEqualTo(3L); + assertThat(patches.chunk_offsets_ptype()).isEqualTo(ProtoPType.U8); + assertThat(childIds(result)).containsExactly(EncodingId.VORTEX_PRIMITIVE, EncodingId.VORTEX_PRIMITIVE, + EncodingId.VORTEX_PRIMITIVE); + assertThat(decodeInts(result, values.length)).isEqualTo(values); + } + + /// `compress_patches` keeps patch values that are all equal as a constant. + @Test + void equalOutliers_patchValuesAreConstant() { // Given - // U8 codes mostly zero with one outlier — encoder picks bit_width=0 + 1 patch. - byte[] codes = new byte[1000]; - codes[42] = 7; + int[] values = new int[2000]; + values[7] = 1_000_000; + values[1500] = 1_000_000; // When - EncodeResult result = ENCODER.encode(DTypes.U8, codes, EncodeTestHelper.testCtx()); + EncodeResult result = ENCODER.encode(DTypes.I32, values, EncodeTestHelper.testCtx()); // Then - assertThat(result.buffers()).hasSize(3); // packed (0 B) + idx + val - assertThat(result.rootNode().children()).hasSize(2); + assertThat(childIds(result)).containsExactly(EncodingId.VORTEX_PRIMITIVE, EncodingId.VORTEX_CONSTANT, + EncodingId.VORTEX_PRIMITIVE); + assertThat(decodeInts(result, values.length)).isEqualTo(values); + } - MemorySegment[] segments = { - result.buffers().get(0), - result.buffers().get(1), - result.buffers().get(2) - }; - ArrayNode idxNode = new ArrayNode(EncodingId.VORTEX_PRIMITIVE, null, - new ArrayNode[0], new int[]{1}); - ArrayNode valNode = new ArrayNode(EncodingId.VORTEX_PRIMITIVE, null, - new ArrayNode[0], new int[]{2}); - ArrayNode bpNode = new ArrayNode(EncodingId.FASTLANES_BITPACKED, - result.rootNode().metadata(), - new ArrayNode[]{idxNode, valNode}, - new int[]{0}); + /// Outliers over every width of patch value, signed and unsigned: one patch and equal + /// ones (a constant), and distinct ones. U8 200 and the U64 above 2^63 catch a value + /// sign-extended where it must be zero-extended, in the primitive and the constant alike. + static Stream outliers() { + return Stream.of( + Arguments.of(PType.U8, new long[]{200}), + Arguments.of(PType.U8, new long[]{200, 200}), + Arguments.of(PType.I8, new long[]{100, 120}), + Arguments.of(PType.U16, new long[]{40_000, 50_000}), + Arguments.of(PType.I16, new long[]{30_000, 30_000}), + Arguments.of(PType.I32, new long[]{70_000}), + Arguments.of(PType.U32, new long[]{3_000_000_000L, 4_000_000_000L}), + Arguments.of(PType.I64, new long[]{1L << 40, 1L << 40}), + Arguments.of(PType.U64, new long[]{0x8000_0000_0000_0001L, Long.MAX_VALUE}), + Arguments.of(PType.U64, new long[]{-1L, -1L})); + } - DecodeContext ctx = new DecodeContext( - bpNode, DTypes.U8, codes.length, segments, REGISTRY, Arena.global()); - Array decoded = DECODER.decode(ctx); + @ParameterizedTest(name = "{0} {1}") + @MethodSource("outliers") + void outliers_roundTripThroughTheirPatches(PType ptype, long[] outliers) { + // Given — small values over three 1024-value chunks, the outliers spread across them + int n = 3000; + long[] longs = new long[n]; + for (int i = 0; i < n; i++) { + longs[i] = i % 4; + } + for (int o = 0; o < outliers.length; o++) { + longs[100 + o * 1200] = outliers[o]; + } + DType dtype = new DType.Primitive(ptype, false); + Object values = PrimitiveArrays.fromLongsArray(longs, ptype, EncodingId.FASTLANES_BITPACKED); + + // When + EncodeResult result = ENCODER.encode(dtype, values, EncodeTestHelper.testCtx()); + + // Then + // a single patch is constant too, as Rust's is_constant holds for one value + EncodingId valuesId = EncodingId.VORTEX_PRIMITIVE; + if (Arrays.stream(outliers).distinct().count() == 1) { + valuesId = EncodingId.VORTEX_CONSTANT; + } + assertThat(childIds(result)).containsExactly(EncodingId.VORTEX_PRIMITIVE, valuesId, + EncodingId.VORTEX_PRIMITIVE); + assertThat(decodeLongs(result, dtype, n)).isEqualTo(longs); + } + } + + /// Rust's `gather_patches` patches valid rows only: a null row's value never becomes a patch, + /// however wide the placeholder it holds. + @Nested + class NullRows { + + @Test + void wideValueAtANullRow_isNotPatched() throws IOException { + // Given + int[] values = new int[2000]; + boolean[] validity = new boolean[values.length]; + Arrays.fill(validity, true); + values[5] = 1_000_000; + validity[5] = false; + + // When + EncodeResult result = ENCODER.encode(DTypes.I32_N, new NullableData(values, validity), + EncodeTestHelper.testCtx()); + + // Then only the validity child, no patches + assertThat(metadata(result).patches()).isNull(); + assertThat(childIds(result)).containsExactly(EncodingId.VORTEX_BOOL); + } - assertThat(decoded.length()).isEqualTo(codes.length); - for (int i = 0; i < codes.length; i++) { - byte got = decoded.materialize(Arena.ofAuto()).get(java.lang.foreign.ValueLayout.JAVA_BYTE, i); - assertThat(got).as("idx " + i).isEqualTo(codes[i]); + /// FoR shifts every slot by the minimum: a null slot's zero placeholder in a column of + /// negatives would become a wide residual, unless the null slot is set to the reference. + @Test + void forOverNegatives_nullPlaceholderIsNotPatched() throws IOException { + // Given + int[] values = new int[2000]; + boolean[] validity = new boolean[values.length]; + for (int i = 0; i < values.length; i++) { + values[i] = -1000 + i % 4; + validity[i] = i % 7 != 3; + } + for (int i = 0; i < values.length; i++) { + if (!validity[i]) { + values[i] = 0; + } } + + // When + CascadeStep step = new FrameOfReferenceEncodingEncoder().encodeCascade(DTypes.I32_N, + new NullableData(values, validity), EncodeTestHelper.testCtx()); + + // Then + EncodeNode packed = step.partialRoot().children()[0]; + assertThat(packed.encodingId()).isEqualTo(EncodingId.FASTLANES_BITPACKED); + MemorySegment meta = packed.metadata(); + assertThat(ProtoBitPackedMetadata.decode(meta, 0, meta.byteSize()).patches()).isNull(); } } + + private static ProtoBitPackedMetadata metadata(EncodeResult result) throws IOException { + MemorySegment meta = result.rootNode().metadata(); + return ProtoBitPackedMetadata.decode(meta, 0, meta.byteSize()); + } + + private static List childIds(EncodeResult result) { + return Arrays.stream(result.rootNode().children()).map(EncodeNode::encodingId).toList(); + } + + private static int[] decodeInts(EncodeResult result, int n) { + MemorySegment[] segments = result.buffers().toArray(new MemorySegment[0]); + DecodeContext ctx = new DecodeContext(toArrayNode(result.rootNode()), DTypes.I32, n, segments, REGISTRY, + Arena.ofAuto()); + return DECODER.decode(ctx).materialize(Arena.ofAuto()).toArray(VortexFormat.LE_INT); + } + + private static long[] decodeLongs(EncodeResult result, DType dtype, int n) { + MemorySegment[] segments = result.buffers().toArray(new MemorySegment[0]); + DecodeContext ctx = new DecodeContext(toArrayNode(result.rootNode()), dtype, n, segments, REGISTRY, + Arena.ofAuto()); + MemorySegment decoded = DECODER.decode(ctx).materialize(Arena.ofAuto()); + PType ptype = ((DType.Primitive) dtype).ptype(); + return PrimitiveArrays.toLongs(decoded, 0, n, ptype, EncodingId.FASTLANES_BITPACKED); + } + + private static ArrayNode toArrayNode(EncodeNode node) { + ArrayNode[] children = Arrays.stream(node.children()) + .map(BitpackedEncodingPatchesTest::toArrayNode) + .toArray(ArrayNode[]::new); + return new ArrayNode(node.encodingId(), node.metadata(), children, node.bufferIndices()); + } } diff --git a/writer/src/test/java/io/github/dfa1/vortex/writer/encode/ConstantEncodingEncoderTest.java b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/ConstantEncodingEncoderTest.java index 3b2b9b1e7..0401357c9 100644 --- a/writer/src/test/java/io/github/dfa1/vortex/writer/encode/ConstantEncodingEncoderTest.java +++ b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/ConstantEncodingEncoderTest.java @@ -492,6 +492,75 @@ void decode_nullScalar_returnsEveryRowInvalid(DType dtype) { } } + /// The single-scan helpers patch encodings use for their values child. + @Nested + class IfConstant { + + @Test + void encodeIfConstant_differingValues_isEmpty() { + // When + var result = ConstantEncodingEncoder.encodeIfConstant(PType.I32, new int[]{7, 7, 8}); + + // Then + assertThat(result).isEmpty(); + } + + /// Floats compare raw bits, as Rust's `is_constant` does: -0.0 is not 0.0. + @Test + void encodeIfConstant_signedZeros_isEmpty() { + // When + var result = ConstantEncodingEncoder.encodeIfConstant(PType.F64, new double[]{0.0, -0.0}); + + // Then + assertThat(result).isEmpty(); + } + + @Test + void encodeIfConstant_equalValues_isTheConstant() throws java.io.IOException { + // When + var result = ConstantEncodingEncoder.encodeIfConstant(PType.F32, new float[]{1.5f, 1.5f}); + + // Then + assertThat(result).isPresent(); + assertThat(scalarOf(result.get()).f32_value()).isEqualTo(1.5f); + } + + @Test + void encodeIfConstantWidened_differingValues_isEmpty() { + // When + var result = ConstantEncodingEncoder.encodeIfConstantWidened(PType.U16, new long[]{1, 2}); + + // Then + assertThat(result).isEmpty(); + } + + @ParameterizedTest(name = "{0}") + @MethodSource("io.github.dfa1.vortex.writer.encode.ConstantEncodingEncoderTest#widenedConstants") + void encodeIfConstantWidened_equalValues_keepTheirSign(PType ptype, long widened, + ProtoScalarValue expected) throws java.io.IOException { + // When + var result = ConstantEncodingEncoder.encodeIfConstantWidened(ptype, new long[]{widened, widened}); + + // Then + assertThat(result).isPresent(); + assertThat(scalarOf(result.get())).isEqualTo(expected); + } + + private static ProtoScalarValue scalarOf(EncodeResult result) throws java.io.IOException { + MemorySegment seg = result.encodedBuffers().getFirst().data(); + return ProtoScalarValue.decode(seg, 0, seg.byteSize()); + } + } + + /// Values as `PrimitiveArrays.toLongs` widens them: unsigned zero-extended, signed sign-extended. + static Stream widenedConstants() { + return Stream.of( + Arguments.of(PType.U8, 230L, ProtoScalarValue.ofUint64Value(230L)), + Arguments.of(PType.I8, -26L, ProtoScalarValue.ofInt64Value(-26L)), + Arguments.of(PType.U32, 0xFFFF_FFF0L, ProtoScalarValue.ofUint64Value(0xFFFF_FFF0L)), + Arguments.of(PType.U64, -1L, ProtoScalarValue.ofUint64Value(-1L))); + } + static Stream highUnsignedConstants() { return Stream.of( Arguments.of(PType.U8, new byte[]{(byte) 230, (byte) 230}, 230L), diff --git a/writer/src/test/java/io/github/dfa1/vortex/writer/encode/PatchBuffersTest.java b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/PatchBuffersTest.java new file mode 100644 index 000000000..3780a6e52 --- /dev/null +++ b/writer/src/test/java/io/github/dfa1/vortex/writer/encode/PatchBuffersTest.java @@ -0,0 +1,68 @@ +package io.github.dfa1.vortex.writer.encode; + +import io.github.dfa1.vortex.core.io.VortexFormat; +import io.github.dfa1.vortex.core.model.PType; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.CsvSource; + +import java.lang.foreign.ValueLayout; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatThrownBy; + +class PatchBuffersTest { + + /// Each chunk's offset counts the patches before it: a patch on the last row of a chunk + /// belongs to that chunk, one on its first row to the next (Rust's `gather_patches`). + @Test + void of_patchesOnChunkBoundaries_countTowardsTheirOwnChunk() { + // Given + long[] positions = {1023, 1024, 2047, 2048}; + + // When + PatchBuffers sut = PatchBuffers.of(positions, 3000, EncodeTestHelper.testCtx()); + + // Then + assertThat(sut.chunkCount()).isEqualTo(3); + assertThat(sut.offsetType()).isEqualTo(PType.U8); + assertThat(sut.offsets().toArray(ValueLayout.JAVA_BYTE)).containsExactly(0, 1, 3); + assertThat(sut.indexType()).isEqualTo(PType.U16); + assertThat(sut.indices().toArray(VortexFormat.LE_SHORT)).containsExactly((short) 1023, (short) 1024, + (short) 2047, (short) 2048); + } + + @Test + void of_lengthNotAMultipleOfTheChunk_hasAPartialLastChunk() { + // Given + long[] positions = {0}; + + // When + PatchBuffers sut = PatchBuffers.of(positions, 1025, EncodeTestHelper.testCtx()); + + // Then + assertThat(sut.chunkCount()).isEqualTo(2); + assertThat(sut.offsets().toArray(ValueLayout.JAVA_BYTE)).containsExactly(0, 1); + } + + @Test + void of_noPositions_fails() { + // Given + long[] positions = {}; + + // When / Then + assertThatThrownBy(() -> PatchBuffers.of(positions, 10, EncodeTestHelper.testCtx())) + .isInstanceOf(IllegalArgumentException.class); + } + + @ParameterizedTest(name = "{0} -> {1}") + @CsvSource({"0, U8", "255, U8", "256, U16", "65535, U16", "65536, U32", "4294967295, U32", "4294967296, U64", + "-1, U64"}) + void narrowestUnsigned_picksTheSmallestTypeHoldingTheValue(long max, PType expected) { + // When + PType result = PatchBuffers.narrowestUnsigned(max); + + // Then + assertThat(result).isEqualTo(expected); + } +}