Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 87 additions & 21 deletions src/main/java/org/apache/datasketches/tdigest/TDigestDouble.java
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,14 @@
* by weight ascending. This makes each merge independent of how the centroids are arranged
* before sorting, so that the same sequence of updates and merges always produces the same
* sketch. It does not make the sketch independent of the order of the input values.</p>
*
* <p><b>Memory allocation.</b> A new t-Digest does not allocate storage for centroids or buffered values
* up front. The storage is allocated on first use and grows as values arrive, up to its full size.
* A t-Digest that stays small never allocates the full storage. An {@link OutOfMemoryError} while
* growing the storage therefore happens in {@link #update(double)} or {@link #merge(TDigestDouble)},
* not in the constructor; if it happens, the t-Digest is unchanged. Call {@link #ensureCapacity()} right
* after construction to allocate the full storage up front instead. Results and the serialized form
* are the same either way.</p>
*/
public final class TDigestDouble {

Expand All @@ -59,13 +67,17 @@ public final class TDigestDouble {
private double maxValue_;
private final int centroidsCapacity_;
private int numCentroids_;
private final double[] centroidMeans_;
private final long[] centroidWeights_;
// the storage arrays grow as they fill, up to their full size; see ensureCapacity()
private double[] centroidMeans_;
private long[] centroidWeights_;
private long centroidsWeight_;
private int numBuffered_;
private final double[] bufferValues_;
private double[] bufferValues_;

private static final int BUFFER_MULTIPLIER = 4;
private static final int MIN_BUFFER_GROWTH = 8;
private static final double[] NO_VALUES = new double[0];
private static final long[] NO_WEIGHTS = new long[0];

private static final byte PREAMBLE_LONGS_EMPTY_OR_SINGLE = 1;
private static final byte PREAMBLE_LONGS_MULTIPLE = 2;
Expand All @@ -77,14 +89,16 @@ public final class TDigestDouble {
private enum Flags { IS_EMPTY, IS_SINGLE_VALUE, REVERSE_MERGE }

/**
* Constructor with the default K
* Constructor with the default K.
* Storage is allocated on first use; see {@link #ensureCapacity()}.
*/
public TDigestDouble() {
this(DEFAULT_K);
}

/**
* Constructor
* Constructor.
* Storage is allocated on first use; see {@link #ensureCapacity()}.
* @param k affects the size of TDigest and its estimation error
*/
public TDigestDouble(final short k) {
Expand All @@ -108,7 +122,8 @@ public short getK() {
public void update(final double value) {
if (!Double.isFinite(value)) { return; }
Math.addExact(getTotalWeight(), 1);
if (numBuffered_ >= (centroidsCapacity_ * BUFFER_MULTIPLIER)) { compress(); }
if (numBuffered_ >= getFullBufferSize()) { compress(); }
else if (numBuffered_ == bufferValues_.length) { growBuffer(); } //allocates before anything changes
bufferValues_[numBuffered_] = value;
numBuffered_++;
minValue_ = Math.min(minValue_, value);
Expand All @@ -123,12 +138,14 @@ public void update(final double value) {
public void merge(final TDigestDouble other) {
if (other.isEmpty()) { return; }
Math.addExact(getTotalWeight(), other.getTotalWeight());
// Extreme centroid means are not the true min/max when those centroids have weight > 1.
minValue_ = Math.min(minValue_, other.minValue_);
maxValue_ = Math.max(maxValue_, other.maxValue_);
// allocate everything before changing anything, so that an OutOfMemoryError leaves this t-Digest unchanged
final int num = numCentroids_ + numBuffered_ + other.numCentroids_ + other.numBuffered_;
ensureCentroidCapacity(num);
final double[] values = new double[num];
final long[] weights = new long[num];
// Extreme centroid means are not the true min/max when those centroids have weight > 1.
minValue_ = Math.min(minValue_, other.minValue_);
maxValue_ = Math.max(maxValue_, other.maxValue_);
System.arraycopy(bufferValues_, 0, values, 0, numBuffered_);
Arrays.fill(weights, 0, numBuffered_, 1);
System.arraycopy(other.bufferValues_, 0, values, numBuffered_, other.numBuffered_);
Expand All @@ -144,6 +161,7 @@ public void merge(final TDigestDouble other) {
private void compress() {
if (numBuffered_ == 0) { return; }
final int num = numBuffered_ + numCentroids_;
ensureCentroidCapacity(num);
final double[] values = new double[num];
final long[] weights = new long[num];
System.arraycopy(bufferValues_, 0, values, 0, numBuffered_);
Expand Down Expand Up @@ -613,8 +631,10 @@ public String toString(final boolean printCentroids) {
.append(" Compression: ").append(k_).append(LS)
.append(" Centroids: ").append(numCentroids_).append(LS)
.append(" Buffered: ").append(numBuffered_).append(LS)
.append(" Centroids Capacity: ").append(centroidMeans_.length).append(LS)
.append(" Buffer Capacity: ").append(bufferValues_.length).append(LS)
.append(" Centroids Capacity: ").append(centroidsCapacity_)
.append(" (allocated ").append(centroidMeans_.length).append(")").append(LS)
.append(" Buffer Capacity: ").append(getFullBufferSize())
.append(" (allocated ").append(bufferValues_.length).append(")").append(LS)
.append("Centroids Weight: ").append(centroidsWeight_).append(LS)
.append(" Total Weight: ").append(getTotalWeight()).append(LS)
.append(" Reverse Merge: ").append(reverseMerge_).append(LS);
Expand Down Expand Up @@ -649,25 +669,71 @@ private TDigestDouble(final boolean reverseMerge, final short k, final double mi
final int fudge = k < 30 ? 30 : 10;
centroidsCapacity_ = (k * 2) + fudge;
// Compression thresholds are local sizing choices, not serialization limits.
final int centroidSlots = Math.max(centroidsCapacity_, means == null ? 0 : means.length);
final int bufferSlots = Math.max(centroidsCapacity_ * BUFFER_MULTIPLIER, buffer == null ? 0 : buffer.length);
centroidMeans_ = new double[centroidSlots];
centroidWeights_ = new long[centroidSlots];
bufferValues_ = new double[bufferSlots];
numCentroids_ = 0;
numBuffered_ = 0;
// Storage is sized to the given data and grows as needed; a new t-Digest allocates none.
centroidsWeight_ = weight;
if ((means != null) && (weights != null)) {
System.arraycopy(means, 0, centroidMeans_, 0, means.length);
System.arraycopy(weights, 0, centroidWeights_, 0, weights.length);
centroidMeans_ = Arrays.copyOf(means, means.length);
centroidWeights_ = Arrays.copyOf(weights, weights.length);
numCentroids_ = means.length;
} else {
centroidMeans_ = NO_VALUES;
centroidWeights_ = NO_WEIGHTS;
numCentroids_ = 0;
}
if (buffer != null) {
System.arraycopy(buffer, 0, bufferValues_, 0, buffer.length);
bufferValues_ = Arrays.copyOf(buffer, buffer.length);
numBuffered_ = buffer.length;
} else {
bufferValues_ = NO_VALUES;
numBuffered_ = 0;
}
}

/**
* Allocates the full storage for centroids and buffered values now, rather than as values arrive.
* Call this right after construction to move an {@link OutOfMemoryError} from {@link #update(double)}
* or {@link #merge(TDigestDouble)} to this call, or so that updates do not pay for growing the storage.
* It has no effect on storage that is already at its full size, and it does not change the contents.
*/
public void ensureCapacity() {
final int fullBuffer = getFullBufferSize();
final double[] buffer = (bufferValues_.length < fullBuffer) ? Arrays.copyOf(bufferValues_, fullBuffer) : null;
ensureCentroidCapacity(centroidsCapacity_);
if (buffer != null) { bufferValues_ = buffer; }
}

/** Returns the full size of the buffer, at which buffered values are compressed into centroids. */
private int getFullBufferSize() {
return centroidsCapacity_ * BUFFER_MULTIPLIER;
}

/** Grows the buffer geometrically, up to its full size. */
private void growBuffer() {
final int newLength = Math.min(Math.max(2 * bufferValues_.length, MIN_BUFFER_GROWTH), getFullBufferSize());
bufferValues_ = Arrays.copyOf(bufferValues_, newLength);
}

/**
* Grows the centroid storage, if needed, so that it holds the given number of centroids, up to its full size.
* Both arrays are allocated before either is replaced.
*/
private void ensureCentroidCapacity(final int num) {
final int target = Math.min(num, centroidsCapacity_);
final int length = centroidMeans_.length;
if (length >= target) { return; }
final int newLength = Math.max(target, Math.min(2 * length, centroidsCapacity_));
final double[] means = Arrays.copyOf(centroidMeans_, newLength);
final long[] weights = Arrays.copyOf(centroidWeights_, newLength);
centroidMeans_ = means;
centroidWeights_ = weights;
}

/** Returns the number of centroids the allocated storage holds. For tests. */
int getAllocatedCentroids() { return centroidMeans_.length; }

/** Returns the number of values the allocated buffer holds. For tests. */
int getAllocatedBuffer() { return bufferValues_.length; }

private static void checkK(final short k) {
if (k < 10) { throw new SketchesArgumentException("k must be at least 10"); }
}
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,153 @@
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/


package org.apache.datasketches.tdigest;

import static org.testng.Assert.assertEquals;
import static org.testng.Assert.assertTrue;

import java.lang.foreign.MemorySegment;

import org.testng.annotations.Test;

/**
* Checks that a t-Digest allocates its storage on first use and grows it as values arrive,
* or allocates it up front with ensureCapacity(), with the same results either way.
*/
public class TDigestLazyAllocationTest {
private static final short K = 100;
private static final int FULL_CENTROIDS = (2 * K) + 10;
private static final int FULL_BUFFER = 4 * FULL_CENTROIDS;

private static double value(final int i) { return (i * 7919) % 100_003; } //not sorted, deterministic

private static void assertAllocated(final TDigestDouble td, final int centroids, final int buffer) {
assertEquals(td.getAllocatedCentroids(), centroids, "centroids");
assertEquals(td.getAllocatedBuffer(), buffer, "buffer");
}

@Test
public void emptyDigestHoldsNoStorage() {
final TDigestDouble td = new TDigestDouble(K);
assertAllocated(td, 0, 0);
td.update(Double.NaN); //ignored, so not a first use
td.update(Double.POSITIVE_INFINITY);
td.merge(new TDigestDouble(K)); //merging an empty t-Digest is not a first use
assertTrue(td.isEmpty());
td.toString(true);
final TDigestDouble reserved = new TDigestDouble(K);
reserved.ensureCapacity();
assertEquals(td.toByteArray(), reserved.toByteArray());
assertAllocated(td, 0, 0);
final TDigestDouble copy = TDigestDouble.heapify(MemorySegment.ofArray(td.toByteArray()));
assertAllocated(copy, 0, 0);
}

@Test
public void bufferGrowsGeometrically() {
final TDigestDouble td = new TDigestDouble(K);
td.update(1);
assertAllocated(td, 0, 8);
for (int i = 2; i <= 9; i++) { td.update(i); }
assertAllocated(td, 0, 16);
for (int i = 10; i <= FULL_BUFFER; i++) { td.update(i); }
assertEquals(td.getAllocatedBuffer(), FULL_BUFFER); //capped at the full size
assertEquals(td.getAllocatedCentroids(), 0); //nothing compressed yet
td.update(0); //the buffer is full, so this compresses
assertEquals(td.getAllocatedBuffer(), FULL_BUFFER);
assertTrue(td.getAllocatedCentroids() > 0);
assertTrue(td.getAllocatedCentroids() <= FULL_CENTROIDS);
}

@Test
public void smallDigestNeverAllocatesFullStorage() {
final TDigestDouble td = new TDigestDouble(K);
for (int i = 0; i < 100; i++) { td.update(value(i)); }
assertEquals(td.getAllocatedBuffer(), 128);
td.getRank(50_000); //compresses
assertTrue(td.getAllocatedCentroids() <= 100, "centroids " + td.getAllocatedCentroids());
assertTrue(td.getAllocatedCentroids() < FULL_CENTROIDS);
}

@Test
public void ensureCapacityAllocatesFullStorage() {
final TDigestDouble td = new TDigestDouble(K);
td.ensureCapacity();
assertAllocated(td, FULL_CENTROIDS, FULL_BUFFER);
td.ensureCapacity(); //no effect once allocated
assertAllocated(td, FULL_CENTROIDS, FULL_BUFFER);
final TDigestDouble lazy = new TDigestDouble(K);
for (int i = 0; i < 100_000; i++) { td.update(value(i)); lazy.update(value(i)); }
assertAllocated(td, FULL_CENTROIDS, FULL_BUFFER); //the storage never grew
assertEquals(td.toByteArray(), lazy.toByteArray());
assertEquals(td.getQuantile(0.5), lazy.getQuantile(0.5));
}

@Test
public void ensureCapacityAfterUpdatesKeepsContents() {
final TDigestDouble td = new TDigestDouble(K);
final TDigestDouble ref = new TDigestDouble(K);
for (int i = 0; i < 1000; i++) { td.update(value(i)); ref.update(value(i)); }
final String before = td.toString(true).replaceAll("\\(allocated \\d+\\)", "");
td.ensureCapacity();
assertEquals(td.toString(true).replaceAll("\\(allocated \\d+\\)", ""), before); //buffered values included
assertAllocated(td, FULL_CENTROIDS, FULL_BUFFER);
for (int i = 1000; i < 50_000; i++) { td.update(value(i)); ref.update(value(i)); }
assertEquals(td.toByteArray(), ref.toByteArray());
}

@Test
public void mergeIntoNewDigest() {
final TDigestDouble other = new TDigestDouble(K);
for (int i = 0; i < 10_000; i++) { other.update(value(i)); }
final TDigestDouble lazy = new TDigestDouble(K);
final TDigestDouble reserved = new TDigestDouble(K);
reserved.ensureCapacity();
lazy.merge(other);
reserved.merge(other);
assertTrue(lazy.getAllocatedCentroids() > 0);
assertEquals(lazy.getAllocatedBuffer(), 0); //a merge does not need the buffer
assertEquals(lazy.toByteArray(), reserved.toByteArray());
assertEquals(lazy.getMinValue(), other.getMinValue());
assertEquals(lazy.getMaxValue(), other.getMaxValue());

final TDigestDouble single = new TDigestDouble(K);
single.update(42);
final TDigestDouble fromSingle = new TDigestDouble(K);
fromSingle.merge(single);
assertEquals(fromSingle.toByteArray(), single.toByteArray());
}

@Test
public void heapifiedDigestIsSizedToItsImage() {
final TDigestDouble src = new TDigestDouble(K);
for (int i = 0; i < 10_000; i++) { src.update(value(i)); }
final byte[] image = src.toByteArray();
final TDigestDouble td = TDigestDouble.heapify(MemorySegment.ofArray(image));
final TDigestDouble reserved = TDigestDouble.heapify(MemorySegment.ofArray(image));
reserved.ensureCapacity();
assertEquals(td.getAllocatedBuffer(), 0);
assertTrue(td.getAllocatedCentroids() < FULL_CENTROIDS);
for (int i = 0; i < 20_000; i++) { td.update(value(i) + 0.5); reserved.update(value(i) + 0.5); }
td.merge(src);
reserved.merge(src);
assertEquals(td.toByteArray(), reserved.toByteArray());
}
}
Loading