From 9a13ce00c4faedc02b2a04670ea9ef4729b70b2c Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sat, 29 Aug 2026 08:50:58 +0300 Subject: [PATCH 01/92] chore(deps): bump github/codeql-action from 4.37.7 to 4.37.8 in /.github/workflows (#7584) chore(deps): bump github/codeql-action in /.github/workflows Bumps [github/codeql-action](https://github.com/github/codeql-action) from 4.37.7 to 4.37.8. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](https://github.com/github/codeql-action/compare/v4.37.7...v4.37.8) --- updated-dependencies: - dependency-name: github/codeql-action dependency-version: 4.37.8 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/codeql.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index db2c7f5a1b46..7e99604ca98d 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -30,7 +30,7 @@ jobs: distribution: 'temurin' - name: Initialize CodeQL - uses: github/codeql-action/init@v4.37.7 + uses: github/codeql-action/init@v4.37.8 with: languages: 'java-kotlin' @@ -38,7 +38,7 @@ jobs: run: mvn --batch-mode --update-snapshots verify - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4.37.7 + uses: github/codeql-action/analyze@v4.37.8 with: category: "/language:java-kotlin" @@ -55,12 +55,12 @@ jobs: uses: actions/checkout@v7 - name: Initialize CodeQL - uses: github/codeql-action/init@v4.37.7 + uses: github/codeql-action/init@v4.37.8 with: languages: 'actions' - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4.37.7 + uses: github/codeql-action/analyze@v4.37.8 with: category: "/language:actions" ... From ffb3bed004a5bc6ee1dc317394b2978278eacd2c Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 1 Sep 2026 08:39:44 +0300 Subject: [PATCH 02/92] chore(deps): bump actions/setup-java from 5.7.0 to 6.0.0 in /.github/workflows (#7587) chore(deps): bump actions/setup-java in /.github/workflows Bumps [actions/setup-java](https://github.com/actions/setup-java) from 5.7.0 to 6.0.0. - [Release notes](https://github.com/actions/setup-java/releases) - [Commits](https://github.com/actions/setup-java/compare/v5.7.0...v6.0.0) --- updated-dependencies: - dependency-name: actions/setup-java dependency-version: 6.0.0 dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/build.yml | 2 +- .github/workflows/codeql.yml | 2 +- .github/workflows/infer.yml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index a1395d87ec8d..6be71195eb1e 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -10,7 +10,7 @@ jobs: steps: - uses: actions/checkout@v7 - name: Set up JDK - uses: actions/setup-java@v5.7.0 + uses: actions/setup-java@v6.0.0 with: java-version: 21 distribution: 'temurin' diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 7e99604ca98d..bb559edb0a0e 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -24,7 +24,7 @@ jobs: uses: actions/checkout@v7 - name: Set up JDK - uses: actions/setup-java@v5.7.0 + uses: actions/setup-java@v6.0.0 with: java-version: 21 distribution: 'temurin' diff --git a/.github/workflows/infer.yml b/.github/workflows/infer.yml index 3bfc509ebf47..2099dd969567 100644 --- a/.github/workflows/infer.yml +++ b/.github/workflows/infer.yml @@ -18,7 +18,7 @@ jobs: - uses: actions/checkout@v7 - name: Set up JDK - uses: actions/setup-java@v5.7.0 + uses: actions/setup-java@v6.0.0 with: java-version: 21 distribution: 'temurin' From 6ec633979dc4717e28f74caf27717cc10fe6b728 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 3 Sep 2026 09:01:10 +0300 Subject: [PATCH 03/92] chore(deps): bump github/codeql-action from 4.37.8 to 4.37.9 in /.github/workflows (#7589) chore(deps): bump github/codeql-action in /.github/workflows Bumps [github/codeql-action](https://github.com/github/codeql-action) from 4.37.8 to 4.37.9. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](https://github.com/github/codeql-action/compare/v4.37.8...v4.37.9) --- updated-dependencies: - dependency-name: github/codeql-action dependency-version: 4.37.9 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/codeql.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index bb559edb0a0e..33235609a787 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -30,7 +30,7 @@ jobs: distribution: 'temurin' - name: Initialize CodeQL - uses: github/codeql-action/init@v4.37.8 + uses: github/codeql-action/init@v4.37.9 with: languages: 'java-kotlin' @@ -38,7 +38,7 @@ jobs: run: mvn --batch-mode --update-snapshots verify - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4.37.8 + uses: github/codeql-action/analyze@v4.37.9 with: category: "/language:java-kotlin" @@ -55,12 +55,12 @@ jobs: uses: actions/checkout@v7 - name: Initialize CodeQL - uses: github/codeql-action/init@v4.37.8 + uses: github/codeql-action/init@v4.37.9 with: languages: 'actions' - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4.37.8 + uses: github/codeql-action/analyze@v4.37.9 with: category: "/language:actions" ... From 0a6c7560e555daa7b77b894a690fbc0335e1e0c3 Mon Sep 17 00:00:00 2001 From: poorva0405 Date: Fri, 4 Sep 2026 23:13:47 +0530 Subject: [PATCH 04/92] Add K-Nearest Neighbors classifier (#7563) * Add K-Nearest Neighbors classifier * Fix checkstyle issues * Improve test coverage * Apply clang-format formatting * Refine KNN validation and data handling * Fix KNN test formatting * Fix KNN test formatting --------- Co-authored-by: A <19151554+alxkm@users.noreply.github.com> --- .../machinelearning/KNearestNeighbors.java | 203 ++++++++++++++ .../KNearestNeighborsTest.java | 247 ++++++++++++++++++ 2 files changed, 450 insertions(+) create mode 100644 src/main/java/com/thealgorithms/machinelearning/KNearestNeighbors.java create mode 100644 src/test/java/com/thealgorithms/machinelearning/KNearestNeighborsTest.java diff --git a/src/main/java/com/thealgorithms/machinelearning/KNearestNeighbors.java b/src/main/java/com/thealgorithms/machinelearning/KNearestNeighbors.java new file mode 100644 index 000000000000..02c3943365bf --- /dev/null +++ b/src/main/java/com/thealgorithms/machinelearning/KNearestNeighbors.java @@ -0,0 +1,203 @@ +package com.thealgorithms.machinelearning; + +import java.util.ArrayList; +import java.util.Comparator; +import java.util.HashMap; +import java.util.List; +import java.util.Map; + +/** + * K-Nearest Neighbors (KNN) classifier. + * + *

+ * K-Nearest Neighbors is a supervised machine learning algorithm that + * classifies a sample based on the majority class among its {@code k} + * nearest training samples using the Euclidean distance metric. + * + *

+ * The classifier stores the training dataset during the fitting phase and + * predicts class labels for new samples without building an explicit model. + * + * @see + * K-Nearest Neighbors + */ +public final class KNearestNeighbors { + private final int k; + private double[][] trainingFeatures; + private int[] trainingLabels; + private int numFeatures; + + /** + * Constructs a K-Nearest Neighbors classifier with the specified number + * of neighbors. + * + * @param k the number of nearest neighbors to consider during prediction + */ + public KNearestNeighbors(int k) { + + if (k <= 0) { + throw new IllegalArgumentException("k must be greater than 0."); + } + + this.k = k; + } + + /** + * Represents a neighboring training sample and its distance from the test + * sample. + */ + private record Neighbor(double distance, int label) { + } + + /** + * Fits the classifier using the provided training dataset. + * + *

+ * The training feature vectors and their corresponding class labels are + * stored for use during prediction. + * + * @param features the training feature vectors + * @param labels the corresponding class labels + */ + public void fit(double[][] features, int[] labels) { + + if (features == null || labels == null) { + throw new IllegalArgumentException("Features and labels cannot be null."); + } + + if (features.length == 0 || labels.length == 0) { + throw new IllegalArgumentException("Features and labels cannot be empty."); + } + + if (features.length != labels.length) { + throw new IllegalArgumentException("Features and labels must have the same length."); + } + + if (k > features.length) { + throw new IllegalArgumentException("k cannot be greater than the number of training samples."); + } + + if (features[0] == null) { + throw new IllegalArgumentException("Feature vectors cannot be null."); + } + + numFeatures = features[0].length; + + if (numFeatures == 0) { + throw new IllegalArgumentException("Feature vectors cannot be empty."); + } + + for (double[] sample : features) { + if (sample == null) { + throw new IllegalArgumentException("Feature vectors cannot be null."); + } + + if (sample.length != numFeatures) { + throw new IllegalArgumentException("All feature vectors must have the same dimension."); + } + } + + this.trainingFeatures = new double[features.length][]; + + for (int i = 0; i < features.length; i++) { + this.trainingFeatures[i] = features[i].clone(); + } + this.trainingLabels = labels.clone(); + } + + /** + * Computes the Euclidean distance between two feature vectors. + * + * @param first the first feature vector + * @param second the second feature vector + * @return the Euclidean distance between the two vectors + */ + private static double euclideanDistance(double[] first, double[] second) { + double sum = 0.0; + + for (int i = 0; i < first.length; i++) { + double difference = first[i] - second[i]; + sum += difference * difference; + } + + return Math.sqrt(sum); + } + + /** + * Predicts the class label for a single sample. + * + *

+ * The prediction is made by finding the {@code k} nearest neighbors + * among the training samples and selecting the class with the highest + * number of votes. In the event of a tie, the smaller class label is + * returned. + * + * @param testPoint the sample to classify + * @return the predicted class label + */ + public int predict(double[] testPoint) { + if (trainingFeatures == null || trainingLabels == null) { + throw new IllegalStateException("Classifier has not been fitted."); + } + + if (testPoint == null) { + throw new IllegalArgumentException("Sample cannot be null."); + } + + if (testPoint.length != numFeatures) { + throw new IllegalArgumentException("Sample length must match training feature count."); + } + + List neighbors = new ArrayList<>(trainingFeatures.length); + + for (int i = 0; i < trainingFeatures.length; i++) { + double distance = euclideanDistance(trainingFeatures[i], testPoint); + neighbors.add(new Neighbor(distance, trainingLabels[i])); + } + + neighbors.sort(Comparator.comparingDouble(Neighbor::distance)); + + Map votes = new HashMap<>(); + + for (int i = 0; i < k; i++) { + int label = neighbors.get(i).label(); + votes.merge(label, 1, Integer::sum); + } + + int predictedLabel = -1; + int maxVotes = -1; + + for (Map.Entry entry : votes.entrySet()) { + int label = entry.getKey(); + int count = entry.getValue(); + + if (count > maxVotes || (count == maxVotes && label < predictedLabel)) { + maxVotes = count; + predictedLabel = label; + } + } + + return predictedLabel; + } + + /** + * Predicts class labels for multiple samples. + * + * @param samples the samples to classify + * @return an array containing the predicted class label for each sample + */ + public int[] predict(double[][] samples) { + + if (samples == null) { + throw new IllegalArgumentException("Samples cannot be null."); + } + + int[] predictions = new int[samples.length]; + + for (int i = 0; i < samples.length; i++) { + predictions[i] = predict(samples[i]); + } + + return predictions; + } +} diff --git a/src/test/java/com/thealgorithms/machinelearning/KNearestNeighborsTest.java b/src/test/java/com/thealgorithms/machinelearning/KNearestNeighborsTest.java new file mode 100644 index 000000000000..85f732a08ecb --- /dev/null +++ b/src/test/java/com/thealgorithms/machinelearning/KNearestNeighborsTest.java @@ -0,0 +1,247 @@ +package com.thealgorithms.machinelearning; + +import static org.junit.jupiter.api.Assertions.assertArrayEquals; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; + +import org.junit.jupiter.api.Test; + +class KNearestNeighborsTest { + + @Test + void predictsCorrectClassOnSeparableDataset() { + double[][] features = { + {0, 0}, + {1, 1}, + {8, 8}, + {9, 9}, + }; + + int[] labels = {0, 0, 1, 1}; + + KNearestNeighbors knn = new KNearestNeighbors(3); + knn.fit(features, labels); + + assertEquals(0, knn.predict(new double[] {1.5, 1.5})); + assertEquals(1, knn.predict(new double[] {8.5, 8.5})); + } + + @Test + void predictsBatchClassesOnSeparableDataset() { + double[][] features = { + {0, 0}, + {1, 1}, + {8, 8}, + {9, 9}, + }; + + int[] labels = {0, 0, 1, 1}; + + KNearestNeighbors knn = new KNearestNeighbors(3); + knn.fit(features, labels); + + double[][] samples = {{1.5, 1.5}, {8.5, 8.5}}; + int[] predictions = knn.predict(samples); + + assertArrayEquals(new int[] {0, 1}, predictions); + } + + @Test + void throwsExceptionWhenKIsNotPositive() { + assertThrows(IllegalArgumentException.class, () -> new KNearestNeighbors(-4)); + assertThrows(IllegalArgumentException.class, () -> new KNearestNeighbors(0)); + } + + @Test + void throwsExceptionWhenKIsGreaterThanNumberOfTrainingSamples() { + double[][] features = { + {0, 0}, + {1, 1}, + {8, 8}, + {9, 9}, + }; + + int[] labels = {0, 0, 1, 1}; + KNearestNeighbors knn = new KNearestNeighbors(7); + + assertThrows(IllegalArgumentException.class, () -> knn.fit(features, labels)); + } + + @Test + void nullFeaturesArrayThrowsIllegalArgumentException() { + KNearestNeighbors knn = new KNearestNeighbors(1); + + assertThrows(IllegalArgumentException.class, () -> knn.fit(null, new int[] {0, 1})); + } + + @Test + void emptyFeaturesArrayThrowsIllegalArgumentException() { + KNearestNeighbors knn = new KNearestNeighbors(1); + + assertThrows(IllegalArgumentException.class, () -> knn.fit(new double[][] {}, new int[] {})); + } + + @Test + void nullLabelsArrayThrowsIllegalArgumentException() { + KNearestNeighbors knn = new KNearestNeighbors(1); + + assertThrows(IllegalArgumentException.class, () -> knn.fit(new double[][] {{1, 1}, {2, 2}}, null)); + } + + @Test + void emptyLabelsArrayThrowsIllegalArgumentException() { + KNearestNeighbors knn = new KNearestNeighbors(1); + + assertThrows(IllegalArgumentException.class, () -> knn.fit(new double[][] {{1, 1}, {2, 2}}, new int[] {})); + } + + @Test + void mismatchedFeatureAndLabelLengthsThrowsIllegalArgumentException() { + KNearestNeighbors knn = new KNearestNeighbors(3); + + assertThrows(IllegalArgumentException.class, () -> knn.fit(new double[][] {{0, 0}, {1, 1}, {8, 8}, {9, 9}}, new int[] {0, 0, 1})); + } + + @Test + void firstFeatureVectorNullThrowsIllegalArgumentException() { + KNearestNeighbors knn = new KNearestNeighbors(1); + + assertThrows(IllegalArgumentException.class, () -> knn.fit(new double[][] {null, {1, 1}}, new int[] {0, 1})); + } + + @Test + void emptyFeatureVectorThrowsIllegalArgumentException() { + KNearestNeighbors knn = new KNearestNeighbors(1); + + assertThrows(IllegalArgumentException.class, () -> knn.fit(new double[][] {{}}, new int[] {0})); + } + + @Test + void nullFeatureSampleThrowsIllegalArgumentException() { + KNearestNeighbors knn = new KNearestNeighbors(2); + + assertThrows(IllegalArgumentException.class, () -> knn.fit(new double[][] {{0, 0}, null, {8, 8}}, new int[] {0, 0, 1})); + } + + @Test + void mismatchedDimensionThrowsIllegalArgumentException() { + KNearestNeighbors knn = new KNearestNeighbors(2); + + assertThrows(IllegalArgumentException.class, () -> knn.fit(new double[][] {{0, 0}, {1, 1, 2}, {8, 8}}, new int[] {0, 0, 1})); + } + + @Test + void predictBeforeFitThrowsIllegalStateException() { + KNearestNeighbors knn = new KNearestNeighbors(3); + + assertThrows(IllegalStateException.class, () -> knn.predict(new double[] {1, 1})); + } + + @Test + void nullTestPointThrowsIllegalArgumentException() { + double[][] features = { + {0, 0}, + {1, 1}, + {8, 8}, + {9, 9}, + }; + + int[] labels = {0, 0, 1, 1}; + + KNearestNeighbors knn = new KNearestNeighbors(3); + knn.fit(features, labels); + + assertThrows(IllegalArgumentException.class, () -> knn.predict((double[]) null)); + assertThrows(IllegalArgumentException.class, () -> knn.predict((double[][]) null)); + } + + @Test + void mismatchedTestPointLengthThrowsIllegalArgumentException() { + double[][] features = { + {0, 0}, + {1, 1}, + {8, 8}, + {9, 9}, + }; + + int[] labels = {0, 0, 1, 1}; + + KNearestNeighbors knn = new KNearestNeighbors(3); + knn.fit(features, labels); + + assertThrows(IllegalArgumentException.class, () -> knn.predict(new double[] {1.5, 1.5, 1.5})); + } + + @Test + void tieBreakReturnsSmallerLabel() { + double[][] features = {{0, 0}, {0, 2}, {2, 0}, {2, 2}}; + + int[] labels = {0, 1, 0, 1}; + + KNearestNeighbors knn = new KNearestNeighbors(4); + knn.fit(features, labels); + + assertEquals(0, knn.predict(new double[] {1, 1})); + } + + @Test + void tieBreakKeepsCurrentWinnerWhenLabelIsGreater() { + double[][] features = {{0, 0}, {0, 2}, {2, 0}, {2, 2}}; + + int[] labels = {1, 0, 1, 0}; + + KNearestNeighbors knn = new KNearestNeighbors(4); + knn.fit(features, labels); + + assertEquals(0, knn.predict(new double[] {1, 1})); + } + + @Test + void nullBatchSampleThrowsIllegalArgumentException() { + double[][] features = { + {0, 0}, + {1, 1}, + {8, 8}, + {9, 9}, + }; + + int[] labels = {0, 0, 1, 1}; + + KNearestNeighbors knn = new KNearestNeighbors(3); + knn.fit(features, labels); + + assertThrows(IllegalArgumentException.class, () -> knn.predict(new double[][] {{1.5, 1.5}, null})); + } + + @Test + void invalidBatchSampleThrowsIllegalArgumentException() { + double[][] features = { + {0, 0}, + {1, 1}, + {8, 8}, + {9, 9}, + }; + + int[] labels = {0, 0, 1, 1}; + + KNearestNeighbors knn = new KNearestNeighbors(3); + knn.fit(features, labels); + + assertThrows(IllegalArgumentException.class, () -> knn.predict(new double[][] {{1.5, 1.5}, {8.5, 8.5, 8.5}})); + } + + @Test + void fitMakesDefensiveCopyOfTrainingData() { + double[][] features = {{0, 0}, {10, 10}}; + + int[] labels = {0, 1}; + + KNearestNeighbors knn = new KNearestNeighbors(1); + knn.fit(features, labels); + + features[0][0] = 100; + labels[0] = 1; + + assertEquals(0, knn.predict(new double[] {0, 0})); + } +} From 14c8db82a2b4d999ccd66868e95aab32ab9dcfa9 Mon Sep 17 00:00:00 2001 From: Oleksandr Klymenko Date: Sun, 6 Sep 2026 15:45:09 +0300 Subject: [PATCH 05/92] feat: add SlidingWindowAggregator, a ring buffer with windowed aggregation (#7591) A fixed-capacity circular buffer that additionally keeps an aggregate of every element it currently holds, so a sliding window sum, minimum or maximum is available in constant time. Rather than the usual "add the new value, subtract the evicted one" trick, which only works for invertible operators, it uses the two-stack sliding window aggregation algorithm: the window is split into a front section holding suffix aggregates and a back section summarised by a single running aggregate. Every element takes part in at most one rotation between the two, which makes insertion and removal O(1) amortised with no allocation after construction. Any associative operator works, commutative or not, and no identity element is needed. Comes with factories for sum, minimum and maximum, indexed access, a fail-fast iterator, and tests that check the aggregate against a brute force reference under randomly interleaved insertions and removals. Signed-off-by: alxkm <19151554+alxkm@users.noreply.github.com> Co-authored-by: alxkm <19151554+alxkm@users.noreply.github.com> --- .../buffers/SlidingWindowAggregator.java | 447 +++++++++++++++++ .../buffers/SlidingWindowAggregatorTest.java | 449 ++++++++++++++++++ 2 files changed, 896 insertions(+) create mode 100644 src/main/java/com/thealgorithms/datastructures/buffers/SlidingWindowAggregator.java create mode 100644 src/test/java/com/thealgorithms/datastructures/buffers/SlidingWindowAggregatorTest.java diff --git a/src/main/java/com/thealgorithms/datastructures/buffers/SlidingWindowAggregator.java b/src/main/java/com/thealgorithms/datastructures/buffers/SlidingWindowAggregator.java new file mode 100644 index 000000000000..ae20c88cd334 --- /dev/null +++ b/src/main/java/com/thealgorithms/datastructures/buffers/SlidingWindowAggregator.java @@ -0,0 +1,447 @@ +package com.thealgorithms.datastructures.buffers; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.Comparator; +import java.util.ConcurrentModificationException; +import java.util.Iterator; +import java.util.List; +import java.util.NoSuchElementException; +import java.util.Objects; +import java.util.function.BinaryOperator; +import java.util.function.Function; + +/** + * A fixed-capacity ring (circular) buffer that additionally keeps an aggregate of every element it + * currently holds, i.e. a sliding window with aggregation. + * + *

The window slides automatically: once the buffer is full, adding a new element evicts the + * oldest one, and the aggregate is kept in sync without rescanning the window. + * + *

How the aggregate is maintained

+ * + *

The naive way to keep a windowed sum is "add the new value, subtract the evicted one". That + * trick only works for invertible operators: there is no way to subtract a value from a + * minimum. This class instead uses the classic two-stack sliding window aggregation + * algorithm, which needs nothing but associativity: + * + *

    + *
  • The window is split into a front section {@code [head, flip)} and a back + * section {@code [flip, tail)}.
  • + *
  • For every slot of the front section the buffer stores the aggregate of that element and all + * younger elements of the front section (a suffix aggregate), so the aggregate of the + * whole front section is readable from the single slot pointed at by {@code head}.
  • + *
  • The back section is summarised by one running aggregate, updated on every insertion.
  • + *
  • {@link #aggregate()} combines the two, in that order, so the operator does not need to be + * commutative.
  • + *
  • When the front section runs out, the back section is turned into a new front section by one + * backwards pass. Every element takes part in at most one such pass, which makes the cost + * O(1) amortised per element.
  • + *
+ * + *

A pleasant side effect is numerical stability: because aggregates are recomputed from scratch + * on every flip, floating-point error cannot accumulate indefinitely the way it does with the + * add-then-subtract approach. + * + *

Complexity

+ * + * + * + * + * + * + * + * + * + *
Time and space complexity
OperationComplexity
{@link #add(Object)}O(1) amortised, O(n) worst case
{@link #removeOldest()}O(1) amortised, O(n) worst case
{@link #aggregate()}O(1)
{@link #get(int)}, {@link #peekOldest()}, {@link #peekNewest()}O(1)
memoryO(capacity), no allocation after construction
+ * + *

Usage

+ * + *
{@code
+ * // Maximum of the last three readings.
+ * SlidingWindowAggregator window = SlidingWindowAggregator.maximum(3, Comparator.naturalOrder());
+ * for (int value : new int[] {1, 3, 2, 5, 0}) {
+ *     window.add(value);
+ *     System.out.println(window.aggregate());
+ * }
+ * // prints 1, 3, 3, 5, 5
+ *
+ * // Moving average of the last 100 samples: the window knows both the sum and its own size.
+ * SlidingWindowAggregator sum = SlidingWindowAggregator.sumOfDoubles(100);
+ * sum.add(sample);
+ * double movingAverage = sum.aggregate() / sum.size();
+ * }
+ * + *

Contract

+ * + *
    + *
  • {@code null} elements are rejected, and neither the mapper nor the combiner may return + * {@code null}.
  • + *
  • The combiner must be associative; it does not have to be commutative and no + * identity element is required. Elements are always combined oldest-first.
  • + *
  • The mapper is applied exactly once per element, at insertion time.
  • + *
  • This class is not thread-safe.
  • + *
+ * + * @param type of the elements stored in the window + * @param type of the aggregate; use {@code A == E} for operators such as min, max or sum + * @see CircularBuffer + * @see Circular buffer + * @see K. Tangwongsan, M. Hirzel, S. Schneider, K.-L. Wu, General incremental sliding-window aggregation (VLDB 2015) + */ +public final class SlidingWindowAggregator implements Iterable { + + private final Object[] elements; + + /** + * Parallel ring holding one aggregate per occupied slot. The meaning depends on the section the + * slot belongs to: inside the front section it is the aggregate of the element and every younger + * element of that section, inside the back section it is simply the mapped element itself. + */ + private final Object[] aggregates; + + private final Function mapper; + private final BinaryOperator combiner; + private final int capacity; + + /** Absolute index of the oldest element; {@code head <= flip <= tail} always holds. */ + private long head; + + /** Absolute index of the boundary between the front and the back section. */ + private long flip; + + /** Absolute index one past the newest element. */ + private long tail; + + /** Aggregate of the back section, or {@code null} when that section is empty. */ + private A backAggregate; + + private int modCount; + + /** + * Creates an empty window. + * + * @param capacity maximum number of elements held at once; adding beyond it evicts the oldest + * @param mapper turns an element into the value the aggregate is computed over + * @param combiner associative operator used to merge two aggregates + * @throws IllegalArgumentException if {@code capacity} is not positive + * @throws NullPointerException if {@code mapper} or {@code combiner} is {@code null} + */ + public SlidingWindowAggregator(int capacity, Function mapper, BinaryOperator combiner) { + if (capacity <= 0) { + throw new IllegalArgumentException("Window capacity must be positive, but was " + capacity); + } + this.capacity = capacity; + this.elements = new Object[capacity]; + this.aggregates = new Object[capacity]; + this.mapper = Objects.requireNonNull(mapper, "mapper must not be null"); + this.combiner = Objects.requireNonNull(combiner, "combiner must not be null"); + } + + /** + * Creates a window whose aggregate has the same type as its elements. + * + * @param capacity maximum number of elements held at once + * @param combiner associative operator used to merge two elements + * @param type of the elements and of the aggregate + * @return a new window + */ + public static SlidingWindowAggregator of(int capacity, BinaryOperator combiner) { + return new SlidingWindowAggregator<>(capacity, Function.identity(), combiner); + } + + /** + * Creates a window that keeps the sum of the last {@code capacity} values. + * + * @param capacity maximum number of elements held at once + * @return a new window aggregating with {@link Long#sum(long, long)} + */ + public static SlidingWindowAggregator sumOfLongs(int capacity) { + return of(capacity, Long::sum); + } + + /** + * Creates a window that keeps the sum of the last {@code capacity} values. Combined with + * {@link #size()} this is the cheapest way to obtain a moving average. + * + * @param capacity maximum number of elements held at once + * @return a new window aggregating with {@link Double#sum(double, double)} + */ + public static SlidingWindowAggregator sumOfDoubles(int capacity) { + return of(capacity, Double::sum); + } + + /** + * Creates a window that keeps the smallest of the last {@code capacity} values. + * + * @param capacity maximum number of elements held at once + * @param comparator ordering used to pick the minimum + * @param type of the elements + * @return a new window aggregating with {@link BinaryOperator#minBy(Comparator)} + */ + public static SlidingWindowAggregator minimum(int capacity, Comparator comparator) { + return of(capacity, BinaryOperator.minBy(comparator)); + } + + /** + * Creates a window that keeps the largest of the last {@code capacity} values. + * + * @param capacity maximum number of elements held at once + * @param comparator ordering used to pick the maximum + * @param type of the elements + * @return a new window aggregating with {@link BinaryOperator#maxBy(Comparator)} + */ + public static SlidingWindowAggregator maximum(int capacity, Comparator comparator) { + return of(capacity, BinaryOperator.maxBy(comparator)); + } + + /** + * Appends an element, evicting the oldest one if the window is already full. + * + * @param element the element to append + * @return the evicted element, or {@code null} if the window was not full + * @throws NullPointerException if {@code element} is {@code null} or the mapper returns {@code null} + */ + public E add(E element) { + Objects.requireNonNull(element, "This window does not accept null elements"); + E evicted = isFull() ? removeOldest() : null; + + int slot = slotOf(tail); + elements[slot] = element; + A mapped = requireNonNullResult(mapper.apply(element), "mapper"); + aggregates[slot] = mapped; + backAggregate = tail == flip ? mapped : requireNonNullResult(combiner.apply(backAggregate, mapped), "combiner"); + tail++; + modCount++; + return evicted; + } + + /** + * Appends every given element in order. The insertion is not atomic: if an element turns out to be + * {@code null}, the ones before it are already in the window. + * + * @param items the elements to append + * @throws NullPointerException if {@code items} or any of its elements is {@code null} + */ + public void addAll(Iterable items) { + Objects.requireNonNull(items, "items must not be null"); + for (E item : items) { + add(item); + } + } + + /** + * Removes the oldest element, shrinking the window. + * + * @return the removed element + * @throws NoSuchElementException if the window is empty + */ + public E removeOldest() { + if (isEmpty()) { + throw new NoSuchElementException("The window is empty"); + } + if (head == flip) { + rotateBackSectionToFront(); + } + + int slot = slotOf(head); + E oldest = elementAt(slot); + elements[slot] = null; + aggregates[slot] = null; + head++; + modCount++; + return oldest; + } + + /** + * Returns the aggregate of every element currently in the window, combined from the oldest to + * the newest. + * + * @return the aggregate of the window + * @throws NoSuchElementException if the window is empty + */ + public A aggregate() { + if (isEmpty()) { + throw new NoSuchElementException("The aggregate of an empty window is undefined"); + } + if (head == flip) { + return backAggregate; + } + A frontAggregate = aggregateAt(slotOf(head)); + return tail == flip ? frontAggregate : requireNonNullResult(combiner.apply(frontAggregate, backAggregate), "combiner"); + } + + /** + * Returns the element at the given position, counting from the oldest one. + * + * @param index zero-based position, {@code 0} being the oldest element in the window + * @return the element at that position + * @throws IndexOutOfBoundsException if {@code index} is negative or not smaller than {@link #size()} + */ + public E get(int index) { + if (index < 0 || index >= size()) { + throw new IndexOutOfBoundsException("Index " + index + " is out of bounds for a window of size " + size()); + } + return elementAt(slotOf(head + index)); + } + + /** + * Returns the oldest element without removing it. + * + * @return the element that would be evicted next + * @throws NoSuchElementException if the window is empty + */ + public E peekOldest() { + if (isEmpty()) { + throw new NoSuchElementException("The window is empty"); + } + return elementAt(slotOf(head)); + } + + /** + * Returns the most recently added element without removing it. + * + * @return the newest element + * @throws NoSuchElementException if the window is empty + */ + public E peekNewest() { + if (isEmpty()) { + throw new NoSuchElementException("The window is empty"); + } + return elementAt(slotOf(tail - 1)); + } + + /** + * Returns the number of elements currently in the window. + * + * @return the current size, never greater than {@link #capacity()} + */ + public int size() { + return (int) (tail - head); + } + + /** + * Returns the maximum number of elements the window can hold. + * + * @return the capacity given at construction time + */ + public int capacity() { + return capacity; + } + + /** + * Tells whether the window holds no elements. + * + * @return {@code true} if the window is empty + */ + public boolean isEmpty() { + return head == tail; + } + + /** + * Tells whether the next insertion will evict the oldest element. + * + * @return {@code true} if the window is saturated + */ + public boolean isFull() { + return size() == capacity; + } + + /** + * Discards every element, leaving the window as if freshly constructed. + */ + public void clear() { + Arrays.fill(elements, null); + Arrays.fill(aggregates, null); + head = 0; + flip = 0; + tail = 0; + backAggregate = null; + modCount++; + } + + /** + * Returns a snapshot of the window, ordered from the oldest element to the newest one. The list + * is detached from the window: later insertions do not affect it. + * + * @return a new list holding the current contents of the window + */ + public List toList() { + List snapshot = new ArrayList<>(size()); + for (long i = head; i < tail; i++) { + snapshot.add(elementAt(slotOf(i))); + } + return snapshot; + } + + /** + * Returns a fail-fast iterator walking the window from the oldest element to the newest one. + * + * @return an iterator over the current contents of the window + */ + @Override + public Iterator iterator() { + return new WindowIterator(); + } + + @Override + public String toString() { + return toList().toString(); + } + + /** + * Turns the back section into the front section by walking it backwards and storing, for every + * slot, the aggregate of that element and all younger ones. Called only when the front section is + * exhausted, so each element takes part in at most one such pass. + */ + private void rotateBackSectionToFront() { + A suffix = null; + for (long i = tail - 1; i >= head; i--) { + int slot = slotOf(i); + A own = aggregateAt(slot); + suffix = suffix == null ? own : requireNonNullResult(combiner.apply(own, suffix), "combiner"); + aggregates[slot] = suffix; + } + flip = tail; + backAggregate = null; + } + + private int slotOf(long absoluteIndex) { + return (int) (absoluteIndex % capacity); + } + + @SuppressWarnings("unchecked") + private E elementAt(int slot) { + return (E) elements[slot]; + } + + @SuppressWarnings("unchecked") + private A aggregateAt(int slot) { + return (A) aggregates[slot]; + } + + private static T requireNonNullResult(T value, String producer) { + return Objects.requireNonNull(value, "The " + producer + " of a SlidingWindowAggregator must not return null"); + } + + private final class WindowIterator implements Iterator { + private long cursor = head; + private final int expectedModCount = modCount; + + @Override + public boolean hasNext() { + return cursor < tail; + } + + @Override + public E next() { + if (expectedModCount != modCount) { + throw new ConcurrentModificationException(); + } + if (!hasNext()) { + throw new NoSuchElementException("The iterator has been exhausted"); + } + return elementAt(slotOf(cursor++)); + } + } +} diff --git a/src/test/java/com/thealgorithms/datastructures/buffers/SlidingWindowAggregatorTest.java b/src/test/java/com/thealgorithms/datastructures/buffers/SlidingWindowAggregatorTest.java new file mode 100644 index 000000000000..2595678961ed --- /dev/null +++ b/src/test/java/com/thealgorithms/datastructures/buffers/SlidingWindowAggregatorTest.java @@ -0,0 +1,449 @@ +package com.thealgorithms.datastructures.buffers; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.ArrayDeque; +import java.util.ArrayList; +import java.util.Comparator; +import java.util.ConcurrentModificationException; +import java.util.Deque; +import java.util.Iterator; +import java.util.List; +import java.util.NoSuchElementException; +import java.util.Random; +import java.util.concurrent.atomic.AtomicInteger; +import java.util.function.BinaryOperator; +import java.util.function.Function; +import org.junit.jupiter.api.Assertions; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Nested; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +class SlidingWindowAggregatorTest { + + private static final Comparator NATURAL = Comparator.naturalOrder(); + + private static SlidingWindowAggregator sumWindow(int capacity) { + return SlidingWindowAggregator.of(capacity, Integer::sum); + } + + @Nested + @DisplayName("construction") + class Construction { + + @ParameterizedTest + @ValueSource(ints = {0, -1, Integer.MIN_VALUE}) + void rejectsNonPositiveCapacity(int capacity) { + assertThrows(IllegalArgumentException.class, () -> sumWindow(capacity)); + } + + @Test + void rejectsNullMapper() { + assertThrows(NullPointerException.class, () -> new SlidingWindowAggregator(4, null, Integer::sum)); + } + + @Test + void rejectsNullCombiner() { + assertThrows(NullPointerException.class, () -> new SlidingWindowAggregator(4, Function.identity(), null)); + } + + @Test + void startsEmpty() { + SlidingWindowAggregator window = sumWindow(3); + assertTrue(window.isEmpty()); + assertFalse(window.isFull()); + assertEquals(0, window.size()); + assertEquals(3, window.capacity()); + assertTrue(window.toList().isEmpty()); + assertEquals("[]", window.toString()); + } + } + + @Nested + @DisplayName("empty window") + class EmptyWindow { + + private final SlidingWindowAggregator window = sumWindow(3); + + @Test + void aggregateThrows() { + assertThrows(NoSuchElementException.class, window::aggregate); + } + + @Test + void peeksThrow() { + assertThrows(NoSuchElementException.class, window::peekOldest); + assertThrows(NoSuchElementException.class, window::peekNewest); + } + + @Test + void removeThrows() { + assertThrows(NoSuchElementException.class, window::removeOldest); + } + + @Test + void getThrows() { + assertThrows(IndexOutOfBoundsException.class, () -> window.get(0)); + } + + @Test + void iteratorIsExhausted() { + Iterator iterator = window.iterator(); + assertFalse(iterator.hasNext()); + assertThrows(NoSuchElementException.class, iterator::next); + } + } + + @Nested + @DisplayName("aggregation") + class Aggregation { + + @Test + void aggregatesWhileFilling() { + SlidingWindowAggregator window = sumWindow(4); + window.add(1); + assertEquals(1, window.aggregate()); + window.add(2); + assertEquals(3, window.aggregate()); + window.add(3); + assertEquals(6, window.aggregate()); + window.add(4); + assertEquals(10, window.aggregate()); + assertTrue(window.isFull()); + } + + @Test + void slidesOnceFull() { + SlidingWindowAggregator window = sumWindow(3); + window.addAll(List.of(1, 2, 3)); + assertEquals(6, window.aggregate()); + + assertEquals(1, window.add(4)); + assertEquals(9, window.aggregate()); + assertEquals(List.of(2, 3, 4), window.toList()); + + assertEquals(2, window.add(5)); + assertEquals(12, window.aggregate()); + } + + @Test + void addReturnsNullWhileTheWindowIsNotFull() { + SlidingWindowAggregator window = sumWindow(2); + Assertions.assertNull(window.add(1)); + Assertions.assertNull(window.add(2)); + assertEquals(1, window.add(3)); + } + + @Test + @DisplayName("keeps the maximum of the last three readings") + void tracksMaximum() { + SlidingWindowAggregator window = SlidingWindowAggregator.maximum(3, NATURAL); + List observed = new ArrayList<>(); + for (int value : new int[] {1, 3, 2, 5, 0, 0, 0}) { + window.add(value); + observed.add(window.aggregate()); + } + assertEquals(List.of(1, 3, 3, 5, 5, 5, 0), observed); + } + + @Test + void tracksMinimum() { + SlidingWindowAggregator window = SlidingWindowAggregator.minimum(3, NATURAL); + window.addAll(List.of(5, 4, 6, 7, 8)); + assertEquals(6, window.aggregate()); + } + + @Test + @DisplayName("combines oldest first, so non-commutative operators work") + void preservesOrderForNonCommutativeOperators() { + SlidingWindowAggregator window = SlidingWindowAggregator.of(3, (a, b) -> a + b); + window.addAll(List.of("a", "b", "c", "d", "e")); + assertEquals("cde", window.aggregate()); + window.removeOldest(); + assertEquals("de", window.aggregate()); + } + + @Test + void supportsAggregatesOfADifferentType() { + SlidingWindowAggregator lengths = new SlidingWindowAggregator<>(3, String::length, Integer::sum); + lengths.addAll(List.of("a", "bb", "ccc", "dddd")); + assertEquals(2 + 3 + 4, lengths.aggregate()); + } + + @Test + void movingAverageIsSumOverSize() { + SlidingWindowAggregator window = SlidingWindowAggregator.sumOfDoubles(3); + window.addAll(List.of(1.0, 2.0, 3.0, 6.0)); + assertEquals(11.0 / 3.0, window.aggregate() / window.size(), 1e-12); + } + + @Test + void sumOfLongsFactoryWorks() { + SlidingWindowAggregator window = SlidingWindowAggregator.sumOfLongs(2); + window.addAll(List.of(1L, 2L, 3L)); + assertEquals(5L, window.aggregate()); + } + + @Test + @DisplayName("the mapper runs exactly once per element") + void mapperIsCalledOncePerElement() { + AtomicInteger calls = new AtomicInteger(); + SlidingWindowAggregator window = new SlidingWindowAggregator<>(3, value -> { + calls.incrementAndGet(); + return value; + }, Integer::sum); + for (int i = 0; i < 100; i++) { + window.add(i); + window.aggregate(); + } + assertEquals(100, calls.get()); + } + } + + @Nested + @DisplayName("null handling") + class NullHandling { + + @Test + void rejectsNullElements() { + SlidingWindowAggregator window = sumWindow(2); + assertThrows(NullPointerException.class, () -> window.add(null)); + } + + @Test + @DisplayName("a null hidden inside a collection is rejected, and the elements before it stay") + void rejectsNullElementsInsideACollection() { + SlidingWindowAggregator window = sumWindow(2); + List items = new ArrayList<>(); + items.add(1); + items.add(null); + + assertThrows(NullPointerException.class, () -> window.addAll(items)); + assertEquals(1, window.size()); + assertEquals(1, window.aggregate()); + } + + @Test + void rejectsMappersReturningNull() { + SlidingWindowAggregator window = new SlidingWindowAggregator<>(2, value -> null, Integer::sum); + assertThrows(NullPointerException.class, () -> window.add(1)); + } + + @Test + void rejectsCombinersReturningNull() { + SlidingWindowAggregator window = SlidingWindowAggregator.of(2, (a, b) -> null); + window.add(1); + assertThrows(NullPointerException.class, () -> window.add(2)); + } + } + + @Nested + @DisplayName("access and iteration") + class Access { + + @Test + void indexedAccessStartsAtTheOldestElement() { + SlidingWindowAggregator window = sumWindow(3); + window.addAll(List.of(10, 20, 30, 40)); + assertEquals(20, window.get(0)); + assertEquals(30, window.get(1)); + assertEquals(40, window.get(2)); + assertEquals(20, window.peekOldest()); + assertEquals(40, window.peekNewest()); + } + + @ParameterizedTest + @ValueSource(ints = {-1, 3, 100}) + void rejectsOutOfBoundsIndices(int index) { + SlidingWindowAggregator window = sumWindow(5); + window.addAll(List.of(1, 2, 3)); + assertThrows(IndexOutOfBoundsException.class, () -> window.get(index)); + } + + @Test + void iteratesFromOldestToNewest() { + SlidingWindowAggregator window = sumWindow(3); + window.addAll(List.of(1, 2, 3, 4, 5)); + List seen = new ArrayList<>(); + for (int value : window) { + seen.add(value); + } + assertEquals(List.of(3, 4, 5), seen); + assertEquals("[3, 4, 5]", window.toString()); + } + + @Test + void iteratorIsFailFast() { + SlidingWindowAggregator window = sumWindow(4); + window.addAll(List.of(1, 2, 3)); + Iterator iterator = window.iterator(); + assertEquals(1, iterator.next()); + window.add(4); + assertThrows(ConcurrentModificationException.class, iterator::next); + } + + @Test + void toListIsASnapshot() { + SlidingWindowAggregator window = sumWindow(3); + window.addAll(List.of(1, 2, 3)); + List snapshot = window.toList(); + window.add(4); + assertEquals(List.of(1, 2, 3), snapshot); + } + } + + @Nested + @DisplayName("removal and reuse") + class Removal { + + @Test + void removeOldestShrinksTheWindow() { + SlidingWindowAggregator window = sumWindow(4); + window.addAll(List.of(1, 2, 3, 4)); + assertEquals(1, window.removeOldest()); + assertEquals(9, window.aggregate()); + assertEquals(3, window.size()); + assertFalse(window.isFull()); + + assertEquals(2, window.removeOldest()); + assertEquals(3, window.removeOldest()); + assertEquals(4, window.aggregate()); + assertEquals(4, window.removeOldest()); + assertTrue(window.isEmpty()); + assertThrows(NoSuchElementException.class, window::aggregate); + } + + @Test + void clearRestoresTheInitialState() { + SlidingWindowAggregator window = sumWindow(3); + window.addAll(List.of(1, 2, 3, 4, 5)); + window.clear(); + assertTrue(window.isEmpty()); + assertEquals(0, window.size()); + assertThrows(NoSuchElementException.class, window::aggregate); + + window.addAll(List.of(7, 8)); + assertEquals(15, window.aggregate()); + assertEquals(List.of(7, 8), window.toList()); + } + + @Test + @DisplayName("a capacity of one keeps only the latest element") + void capacityOfOne() { + SlidingWindowAggregator window = sumWindow(1); + window.add(1); + assertEquals(1, window.aggregate()); + assertEquals(1, window.add(2)); + assertEquals(2, window.aggregate()); + assertEquals(2, window.add(3)); + assertEquals(3, window.aggregate()); + assertEquals(1, window.size()); + } + + @Test + @DisplayName("survives far more insertions than its capacity") + void survivesManyRotations() { + SlidingWindowAggregator window = sumWindow(3); + for (int i = 1; i <= 100_000; i++) { + window.add(i); + } + assertEquals(99_998 + 99_999 + 100_000, window.aggregate()); + assertEquals(3, window.size()); + } + } + + @Nested + @DisplayName("agreement with a brute force reference") + class BruteForceAgreement { + + @ParameterizedTest + @ValueSource(ints = {1, 2, 3, 5, 8, 13}) + void matchesBruteForceSum(int capacity) { + assertMatchesBruteForce(capacity, Integer::sum); + } + + @ParameterizedTest + @ValueSource(ints = {1, 2, 3, 5, 8, 13}) + void matchesBruteForceMaximum(int capacity) { + assertMatchesBruteForce(capacity, BinaryOperator.maxBy(NATURAL)); + } + + @ParameterizedTest + @ValueSource(ints = {1, 2, 3, 5, 8, 13}) + void matchesBruteForceMinimum(int capacity) { + assertMatchesBruteForce(capacity, BinaryOperator.minBy(NATURAL)); + } + + private void assertMatchesBruteForce(int capacity, BinaryOperator combiner) { + SlidingWindowAggregator window = SlidingWindowAggregator.of(capacity, combiner); + Deque reference = new ArrayDeque<>(); + Random random = new Random(20240517L + capacity); + + for (int step = 0; step < 2_000; step++) { + int value = random.nextInt(2_000) - 1_000; + window.add(value); + reference.addLast(value); + if (reference.size() > capacity) { + reference.removeFirst(); + } + assertEquals(fold(reference, combiner), window.aggregate(), "after step " + step); + } + } + + @Test + @DisplayName("interleaved insertions and removals stay in sync with the reference") + void matchesBruteForceUnderInterleavedOperations() { + int capacity = 7; + SlidingWindowAggregator window = SlidingWindowAggregator.of(capacity, Integer::sum); + Deque reference = new ArrayDeque<>(); + Random random = new Random(987654321L); + + for (int step = 0; step < 20_000; step++) { + if (reference.isEmpty() || random.nextInt(3) > 0) { + int value = random.nextInt(100); + window.add(value); + reference.addLast(value); + if (reference.size() > capacity) { + reference.removeFirst(); + } + } else { + assertEquals(reference.removeFirst(), window.removeOldest()); + } + + assertEquals(reference.size(), window.size()); + assertEquals(new ArrayList<>(reference), window.toList()); + if (reference.isEmpty()) { + assertThrows(NoSuchElementException.class, window::aggregate); + } else { + assertEquals(fold(reference, Integer::sum), window.aggregate(), "after step " + step); + } + } + } + + private Integer fold(Iterable values, BinaryOperator combiner) { + Integer accumulator = null; + for (Integer value : values) { + accumulator = accumulator == null ? value : combiner.apply(accumulator, value); + } + return accumulator; + } + } + + @Test + @DisplayName("the documented example from the class javadoc") + void documentedExample() { + SlidingWindowAggregator window = SlidingWindowAggregator.maximum(3, Comparator.naturalOrder()); + List printed = new ArrayList<>(); + for (int value : new int[] {1, 3, 2, 5, 0}) { + window.add(value); + printed.add(window.aggregate()); + } + assertEquals(List.of(1, 3, 3, 5, 5), printed); + Assertions.assertDoesNotThrow(window::clear); + } +} From 8f08a920fbffe80e3e8fb08bba946427db9296ed Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 8 Sep 2026 08:38:05 +0300 Subject: [PATCH 06/92] chore(deps): bump com.puppycrawl.tools:checkstyle from 14.0.0 to 14.1.0 (#7594) Bumps [com.puppycrawl.tools:checkstyle](https://github.com/checkstyle/checkstyle) from 14.0.0 to 14.1.0. - [Release notes](https://github.com/checkstyle/checkstyle/releases) - [Commits](https://github.com/checkstyle/checkstyle/compare/checkstyle-14.0.0...checkstyle-14.1.0) --- updated-dependencies: - dependency-name: com.puppycrawl.tools:checkstyle dependency-version: 14.1.0 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index a168f326fbd6..54353863a047 100644 --- a/pom.xml +++ b/pom.xml @@ -112,7 +112,7 @@ com.puppycrawl.tools checkstyle - 14.0.0 + 14.1.0 From 06f0480ab137f416a07c7f17b1f73f81716847c9 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 8 Sep 2026 08:51:44 +0300 Subject: [PATCH 07/92] chore(deps-dev): bump org.apache.maven.plugins:maven-compiler-plugin from 3.15.0 to 3.16.0 (#7595) chore(deps-dev): bump org.apache.maven.plugins:maven-compiler-plugin Bumps [org.apache.maven.plugins:maven-compiler-plugin](https://github.com/apache/maven-compiler-plugin) from 3.15.0 to 3.16.0. - [Release notes](https://github.com/apache/maven-compiler-plugin/releases) - [Commits](https://github.com/apache/maven-compiler-plugin/compare/maven-compiler-plugin-3.15.0...maven-compiler-plugin-3.16.0) --- updated-dependencies: - dependency-name: org.apache.maven.plugins:maven-compiler-plugin dependency-version: 3.16.0 dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Oleksandr Klymenko <19151554+alxkm@users.noreply.github.com> --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 54353863a047..bc5a9ee2f13f 100644 --- a/pom.xml +++ b/pom.xml @@ -69,7 +69,7 @@ org.apache.maven.plugins maven-compiler-plugin - 3.15.0 + 3.16.0 21 From 1c0c7c04d044111c9f8527d39d60d2997714f854 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 8 Sep 2026 08:56:15 +0300 Subject: [PATCH 08/92] chore(deps-dev): bump org.apache.maven.plugins:maven-surefire-plugin from 3.5.6 to 3.6.0 (#7596) chore(deps-dev): bump org.apache.maven.plugins:maven-surefire-plugin Bumps [org.apache.maven.plugins:maven-surefire-plugin](https://github.com/apache/maven-surefire) from 3.5.6 to 3.6.0. - [Release notes](https://github.com/apache/maven-surefire/releases) - [Commits](https://github.com/apache/maven-surefire/compare/surefire-3.5.6...surefire-3.6.0) --- updated-dependencies: - dependency-name: org.apache.maven.plugins:maven-surefire-plugin dependency-version: 3.6.0 dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Oleksandr Klymenko <19151554+alxkm@users.noreply.github.com> --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index bc5a9ee2f13f..e7b0649204a8 100644 --- a/pom.xml +++ b/pom.xml @@ -61,7 +61,7 @@ maven-surefire-plugin - 3.5.6 + 3.6.0 From ad10edac3b3a1992f8d1687dac59310848370b1a Mon Sep 17 00:00:00 2001 From: Oleksandr Klymenko Date: Tue, 8 Sep 2026 11:16:18 +0300 Subject: [PATCH 09/92] feat: add KalmanFilter, a scalar Kalman filter with sensor fusion (#7592) feat: add KalmanFilter, a scalar Kalman filter with sensor fusion Signed-off-by: alxkm <19151554+alxkm@users.noreply.github.com> Co-authored-by: alxkm <19151554+alxkm@users.noreply.github.com> --- .../thealgorithms/streaming/KalmanFilter.java | 287 ++++++++++++++++++ .../streaming/KalmanFilterTest.java | 229 ++++++++++++++ 2 files changed, 516 insertions(+) create mode 100644 src/main/java/com/thealgorithms/streaming/KalmanFilter.java create mode 100644 src/test/java/com/thealgorithms/streaming/KalmanFilterTest.java diff --git a/src/main/java/com/thealgorithms/streaming/KalmanFilter.java b/src/main/java/com/thealgorithms/streaming/KalmanFilter.java new file mode 100644 index 000000000000..5e6d5143b12d --- /dev/null +++ b/src/main/java/com/thealgorithms/streaming/KalmanFilter.java @@ -0,0 +1,287 @@ +package com.thealgorithms.streaming; + +/** + * A scalar (one dimensional) Kalman filter: the optimal way to track a quantity that drifts + * slowly while every measurement of it is noisy. + * + *

The filter carries two numbers: the current estimate {@code x} and how much it distrusts that + * estimate, the error variance {@code p}. Each step has two halves. + * + *

+ * predict:  x <- x + u            p <- p + q
+ * update:   k <- p / (p + r)      x <- x + k * (z - x)      p <- (1 - k) * p
+ * 
+ * + *

where {@code q} is the process noise (how much the tracked quantity is expected to wander + * between two steps), {@code r} the measurement noise, {@code z} the measurement and {@code k} the + * Kalman gain. The gain is the whole story: it is the share of the measurement that gets believed. + * When the filter is unsure ({@code p} large) or the sensor is good ({@code r} small), {@code k} + * approaches 1 and the filter follows the sensor; in the opposite case it clings to its own + * prediction. Nothing tunes this by hand, the variances do it. + * + *

Sensor fusion

+ * + *

Fusing several sensors is not a separate algorithm: it is what happens when the same estimate + * is corrected once per sensor, each with its own noise level. A cheap sensor with a large {@code r} + * nudges the estimate a little, a precise one pulls it a lot, and the result is exactly the + * inverse-variance weighted combination that {@link #fuse(double[], double[])} computes in closed + * form: + * + *

{@code
+ * KalmanFilter filter = new KalmanFilter(startingHeight, 1.0, 0.01, 1.0);
+ * for (int t = 0; t < steps; t++) {
+ *     filter.predict();
+ *     filter.update(barometer[t], barometerVariance);
+ *     filter.update(gps[t], gpsVariance);          // second sensor, same estimate
+ *     double height = filter.estimate();
+ * }
+ * }
+ * + *

Both steps run in O(1) time and memory. This class is not thread-safe. + * + * @see Kalman filter + */ +public final class KalmanFilter { + + private final double processNoise; + private final double measurementNoise; + + private double estimate; + private double errorCovariance; + private double lastGain; + + private final double initialEstimate; + private final double initialErrorCovariance; + + /** + * Creates a filter. + * + * @param initialEstimate the starting guess for the tracked quantity + * @param initialErrorCovariance how uncertain that guess is; a large value makes the filter trust + * the first measurements almost completely + * @param processNoise variance added on every {@link #predict()}, i.e. how fast the quantity is + * expected to change on its own + * @param measurementNoise default variance of a measurement, used by {@link #update(double)} + * @throws IllegalArgumentException if any argument is not finite, or if a variance is negative, + * or if {@code measurementNoise} is zero + */ + public KalmanFilter(double initialEstimate, double initialErrorCovariance, double processNoise, double measurementNoise) { + requireFinite(initialEstimate, "initialEstimate"); + requireNonNegativeVariance(initialErrorCovariance, "initialErrorCovariance"); + requireNonNegativeVariance(processNoise, "processNoise"); + requirePositiveVariance(measurementNoise, "measurementNoise"); + + this.initialEstimate = initialEstimate; + this.initialErrorCovariance = initialErrorCovariance; + this.processNoise = processNoise; + this.measurementNoise = measurementNoise; + reset(); + } + + /** + * Advances the model by one step without any control input, growing the uncertainty by the + * process noise. + * + * @return the predicted estimate, unchanged in value for this constant model + */ + public double predict() { + return predict(0.0); + } + + /** + * Advances the model by one step, shifting the estimate by a known control input. + * + * @param controlInput the change the estimate is expected to undergo, e.g. velocity times the + * time step when tracking a position + * @return the predicted estimate + * @throws IllegalArgumentException if {@code controlInput} is not finite + */ + public double predict(double controlInput) { + requireFinite(controlInput, "controlInput"); + estimate += controlInput; + errorCovariance += processNoise; + return estimate; + } + + /** + * Corrects the estimate with a measurement taken by the default sensor. + * + * @param measurement the observed value + * @return the corrected estimate + * @throws IllegalArgumentException if {@code measurement} is not finite + */ + public double update(double measurement) { + return update(measurement, measurementNoise); + } + + /** + * Corrects the estimate with a measurement whose noise differs from the default one. Calling this + * several times per step, once per sensor, is the whole of sensor fusion. + * + * @param measurement the observed value + * @param noise variance of this particular measurement, strictly positive + * @return the corrected estimate + * @throws IllegalArgumentException if {@code measurement} is not finite or {@code noise} is not strictly positive + */ + public double update(double measurement, double noise) { + requireFinite(measurement, "measurement"); + requirePositiveVariance(noise, "noise"); + + double innovationVariance = errorCovariance + noise; + lastGain = errorCovariance / innovationVariance; + estimate += lastGain * (measurement - estimate); + // Algebraically this is (1 - gain) * p, but computing 1 - gain cancels away most of the + // significant digits whenever the gain is close to one, as it is on the first measurements. + errorCovariance = errorCovariance * noise / innovationVariance; + return estimate; + } + + /** + * Runs one full cycle: predict, then correct with the given measurement. + * + * @param measurement the observed value + * @return the filtered estimate + * @throws IllegalArgumentException if {@code measurement} is not finite + */ + public double filter(double measurement) { + predict(); + return update(measurement); + } + + /** + * Filters a whole signal offline, one cycle per sample. + * + * @param measurements the noisy signal + * @return a new array holding the filtered signal, of the same length + * @throws IllegalArgumentException if any measurement is not finite + * @throws NullPointerException if {@code measurements} is {@code null} + */ + public double[] filter(double[] measurements) { + double[] filtered = new double[measurements.length]; + for (int i = 0; i < measurements.length; i++) { + filtered[i] = filter(measurements[i]); + } + return filtered; + } + + /** + * Combines simultaneous readings of the same quantity taken by independent sensors, weighting + * each by the inverse of its variance. This is the closed form of what repeated + * {@link #update(double, double)} calls achieve within one step. + * + * @param measurements one reading per sensor + * @param variances the noise variance of each sensor, strictly positive, same length as {@code measurements} + * @return the fused reading together with its variance, which is never larger than the variance of + * the best single sensor + * @throws IllegalArgumentException if the arrays are empty, differ in length, hold a non-finite + * measurement or a non-positive variance + * @throws NullPointerException if either array is {@code null} + */ + public static Estimate fuse(double[] measurements, double[] variances) { + if (measurements.length != variances.length) { + throw new IllegalArgumentException("There must be exactly one variance per measurement, but got " + measurements.length + " and " + variances.length); + } + if (measurements.length == 0) { + throw new IllegalArgumentException("At least one measurement is required"); + } + + double weightSum = 0.0; + double weightedSum = 0.0; + for (int i = 0; i < measurements.length; i++) { + requireFinite(measurements[i], "measurement"); + requirePositiveVariance(variances[i], "variance"); + double weight = 1.0 / variances[i]; + weightSum += weight; + weightedSum += weight * measurements[i]; + } + return new Estimate(weightedSum / weightSum, 1.0 / weightSum); + } + + /** + * Returns the current estimate of the tracked quantity. + * + * @return the state estimate + */ + public double estimate() { + return estimate; + } + + /** + * Returns the variance of the current estimate; it shrinks with every update and grows with every + * prediction. + * + * @return the error covariance + */ + public double errorCovariance() { + return errorCovariance; + } + + /** + * Returns the Kalman gain used by the most recent update, a number in {@code [0, 1)} telling how + * much of that measurement was believed. + * + * @return the last gain, {@code 0} if no update has happened yet + */ + public double lastGain() { + return lastGain; + } + + /** + * Returns the process noise variance. + * + * @return the value given at construction time + */ + public double processNoise() { + return processNoise; + } + + /** + * Returns the default measurement noise variance. + * + * @return the value given at construction time + */ + public double measurementNoise() { + return measurementNoise; + } + + /** + * Restores the state the filter had right after construction. + */ + public void reset() { + estimate = initialEstimate; + errorCovariance = initialErrorCovariance; + lastGain = 0.0; + } + + @Override + public String toString() { + return "KalmanFilter{estimate=" + estimate + ", errorCovariance=" + errorCovariance + ", lastGain=" + lastGain + '}'; + } + + private static void requireFinite(double value, String name) { + if (!Double.isFinite(value)) { + throw new IllegalArgumentException("The " + name + " must be finite, but was " + value); + } + } + + private static void requireNonNegativeVariance(double value, String name) { + if (!(value >= 0.0) || !Double.isFinite(value)) { + throw new IllegalArgumentException("The " + name + " must be finite and non-negative, but was " + value); + } + } + + private static void requirePositiveVariance(double value, String name) { + if (!(value > 0.0) || !Double.isFinite(value)) { + throw new IllegalArgumentException("The " + name + " must be finite and strictly positive, but was " + value); + } + } + + /** + * A value paired with the variance that describes how much it can be trusted. + * + * @param value the estimated quantity + * @param variance the variance of that estimate + */ + public record Estimate(double value, double variance) { + } +} diff --git a/src/test/java/com/thealgorithms/streaming/KalmanFilterTest.java b/src/test/java/com/thealgorithms/streaming/KalmanFilterTest.java new file mode 100644 index 000000000000..14037eb79476 --- /dev/null +++ b/src/test/java/com/thealgorithms/streaming/KalmanFilterTest.java @@ -0,0 +1,229 @@ +package com.thealgorithms.streaming; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.Random; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +class KalmanFilterTest { + + private static double rootMeanSquareError(double[] values, double truth) { + double sum = 0.0; + for (double value : values) { + sum += (value - truth) * (value - truth); + } + return Math.sqrt(sum / values.length); + } + + @ParameterizedTest + @ValueSource(doubles = {Double.NaN, Double.POSITIVE_INFINITY}) + void rejectsNonFiniteInitialEstimate(double initialEstimate) { + assertThrows(IllegalArgumentException.class, () -> new KalmanFilter(initialEstimate, 1.0, 0.1, 1.0)); + } + + @Test + void rejectsInvalidVariances() { + assertThrows(IllegalArgumentException.class, () -> new KalmanFilter(0.0, -1.0, 0.1, 1.0)); + assertThrows(IllegalArgumentException.class, () -> new KalmanFilter(0.0, 1.0, -0.1, 1.0)); + assertThrows(IllegalArgumentException.class, () -> new KalmanFilter(0.0, 1.0, 0.1, 0.0)); + assertThrows(IllegalArgumentException.class, () -> new KalmanFilter(0.0, 1.0, 0.1, Double.NaN)); + } + + @Test + void rejectsNonFiniteInputs() { + KalmanFilter filter = new KalmanFilter(0.0, 1.0, 0.1, 1.0); + assertThrows(IllegalArgumentException.class, () -> filter.predict(Double.NaN)); + assertThrows(IllegalArgumentException.class, () -> filter.update(Double.POSITIVE_INFINITY)); + assertThrows(IllegalArgumentException.class, () -> filter.update(1.0, 0.0)); + } + + @Test + @DisplayName("prediction adds uncertainty, correction removes it") + void covarianceGrowsOnPredictAndShrinksOnUpdate() { + KalmanFilter filter = new KalmanFilter(0.0, 1.0, 0.25, 1.0); + assertEquals(0.0, filter.lastGain()); + + filter.predict(); + assertEquals(1.25, filter.errorCovariance(), 1e-12); + + filter.update(2.0); + assertTrue(filter.errorCovariance() < 1.25); + assertTrue(filter.lastGain() > 0.0 && filter.lastGain() < 1.0); + } + + @Test + @DisplayName("the gain is the share of the measurement that gets believed") + void gainFollowsTheClosedForm() { + KalmanFilter filter = new KalmanFilter(0.0, 1.0, 0.0, 1.0); + filter.update(10.0); + assertEquals(0.5, filter.lastGain(), 1e-12); + assertEquals(5.0, filter.estimate(), 1e-12); + assertEquals(0.5, filter.errorCovariance(), 1e-12); + } + + @Test + void aControlInputShiftsTheEstimate() { + KalmanFilter filter = new KalmanFilter(100.0, 1.0, 0.1, 1.0); + assertEquals(103.0, filter.predict(3.0), 1e-12); + assertEquals(103.0, filter.estimate(), 1e-12); + } + + @Test + @DisplayName("with no process noise and no prior information the filter is the running mean") + void degeneratesIntoTheRunningMean() { + KalmanFilter filter = new KalmanFilter(0.0, 1e12, 0.0, 1.0); + Random random = new Random(2024L); + + double sum = 0.0; + for (int i = 1; i <= 200; i++) { + double measurement = random.nextGaussian(); + sum += measurement; + filter.update(measurement); + assertEquals(sum / i, filter.estimate(), 1e-6, "after " + i + " measurements"); + } + } + + @Test + @DisplayName("filtering a noisy constant beats using the raw measurements") + void reducesNoiseOnAConstantSignal() { + double truth = 12.5; + double noise = 2.0; + Random random = new Random(555L); + + double[] measurements = new double[400]; + for (int i = 0; i < measurements.length; i++) { + measurements[i] = truth + noise * random.nextGaussian(); + } + + KalmanFilter filter = new KalmanFilter(0.0, 100.0, 1e-4, noise * noise); + double[] filtered = filter.filter(measurements); + + assertEquals(measurements.length, filtered.length); + assertEquals(truth, filter.estimate(), 0.3); + assertTrue(rootMeanSquareError(filtered, truth) < rootMeanSquareError(measurements, truth) / 2.0); + } + + @Test + @DisplayName("a moving quantity is tracked, and more process noise means faster tracking") + void tracksAMovingSignal() { + Random random = new Random(31L); + double[] measurements = new double[200]; + for (int i = 0; i < measurements.length; i++) { + measurements[i] = i * 0.5 + random.nextGaussian(); + } + + KalmanFilter agile = new KalmanFilter(0.0, 1.0, 1.0, 1.0); + KalmanFilter sluggish = new KalmanFilter(0.0, 1.0, 1e-6, 1.0); + agile.filter(measurements); + sluggish.filter(measurements); + + double truth = 199 * 0.5; + assertTrue(Math.abs(agile.estimate() - truth) < Math.abs(sluggish.estimate() - truth), "agile=" + agile.estimate() + " sluggish=" + sluggish.estimate()); + assertEquals(truth, agile.estimate(), 3.0); + } + + @Test + @DisplayName("updating once per sensor reproduces the closed form inverse-variance fusion") + void sequentialUpdatesFuseSensors() { + double preciseReading = 10.0; + double preciseVariance = 0.25; + double coarseReading = 14.0; + double coarseVariance = 4.0; + + KalmanFilter filter = new KalmanFilter(0.0, 1e15, 0.0, 1.0); + filter.update(preciseReading, preciseVariance); + filter.update(coarseReading, coarseVariance); + + KalmanFilter.Estimate fused = KalmanFilter.fuse(new double[] {preciseReading, coarseReading}, new double[] {preciseVariance, coarseVariance}); + assertEquals(fused.value(), filter.estimate(), 1e-6); + assertEquals(fused.variance(), filter.errorCovariance(), 1e-6); + } + + @Test + void fusionWeightsSensorsByTheirPrecision() { + KalmanFilter.Estimate equal = KalmanFilter.fuse(new double[] {1.0, 3.0}, new double[] {1.0, 1.0}); + assertEquals(2.0, equal.value(), 1e-12); + assertEquals(0.5, equal.variance(), 1e-12); + + KalmanFilter.Estimate skewed = KalmanFilter.fuse(new double[] {1.0, 3.0}, new double[] {0.01, 1.0}); + assertTrue(skewed.value() < 1.1, "the precise sensor should dominate, but got " + skewed.value()); + assertTrue(skewed.variance() < 0.01, "fusing can only reduce the variance, but got " + skewed.variance()); + } + + @Test + void fusionOfASingleSensorReturnsIt() { + KalmanFilter.Estimate single = KalmanFilter.fuse(new double[] {7.0}, new double[] {2.0}); + assertEquals(7.0, single.value(), 1e-12); + assertEquals(2.0, single.variance(), 1e-12); + } + + @Test + void fusionRejectsMalformedInput() { + assertThrows(IllegalArgumentException.class, () -> KalmanFilter.fuse(new double[0], new double[0])); + assertThrows(IllegalArgumentException.class, () -> KalmanFilter.fuse(new double[] {1.0}, new double[] {1.0, 2.0})); + assertThrows(IllegalArgumentException.class, () -> KalmanFilter.fuse(new double[] {1.0}, new double[] {0.0})); + assertThrows(IllegalArgumentException.class, () -> KalmanFilter.fuse(new double[] {Double.NaN}, new double[] {1.0})); + } + + @Test + @DisplayName("fusing two sensors is better than trusting either of them alone") + void fusionBeatsEitherSensorAlone() { + double truth = 3.0; + Random random = new Random(97L); + double barometerNoise = 1.0; + double gpsNoise = 3.0; + + KalmanFilter filter = new KalmanFilter(0.0, 100.0, 1e-6, barometerNoise * barometerNoise); + double[] fused = new double[300]; + KalmanFilter barometerFilter = new KalmanFilter(0.0, 100.0, 1e-6, barometerNoise * barometerNoise); + + for (int i = 0; i < fused.length; i++) { + double barometer = truth + barometerNoise * random.nextGaussian(); + double gps = truth + gpsNoise * random.nextGaussian(); + + filter.predict(); + filter.update(barometer, barometerNoise * barometerNoise); + filter.update(gps, gpsNoise * gpsNoise); + fused[i] = filter.estimate(); + + barometerFilter.predict(); + barometerFilter.update(barometer); + } + + assertTrue(filter.errorCovariance() < barometerFilter.errorCovariance(), "fusing must not increase the uncertainty"); + assertEquals(truth, fused[fused.length - 1], 0.5); + } + + @Test + void resetRestoresTheInitialState() { + KalmanFilter filter = new KalmanFilter(5.0, 2.0, 0.1, 1.0); + assertEquals(0.1, filter.processNoise()); + assertEquals(1.0, filter.measurementNoise()); + + filter.filter(100.0); + filter.reset(); + + assertEquals(5.0, filter.estimate()); + assertEquals(2.0, filter.errorCovariance()); + assertEquals(0.0, filter.lastGain()); + } + + @Test + void toStringMentionsTheState() { + KalmanFilter filter = new KalmanFilter(1.0, 1.0, 0.1, 1.0); + assertTrue(filter.toString().contains("estimate=1.0"), filter.toString()); + } + + @Test + void rejectsNonFiniteVariances() { + assertThrows(IllegalArgumentException.class, () -> new KalmanFilter(0.0, Double.NaN, 0.1, 1.0)); + assertThrows(IllegalArgumentException.class, () -> new KalmanFilter(0.0, Double.POSITIVE_INFINITY, 0.1, 1.0)); + assertThrows(IllegalArgumentException.class, () -> new KalmanFilter(0.0, 1.0, Double.NaN, 1.0)); + assertThrows(IllegalArgumentException.class, () -> new KalmanFilter(0.0, 1.0, 0.1, Double.POSITIVE_INFINITY)); + } +} From 8abfcf796ba72b84111565f2bc8bc0fd3c9a2fb9 Mon Sep 17 00:00:00 2001 From: Oleksandr Klymenko Date: Tue, 8 Sep 2026 11:19:47 +0300 Subject: [PATCH 10/92] feat: add CusumDetector, cumulative sum change detection for streams (#7593) Signed-off-by: alxkm <19151554+alxkm@users.noreply.github.com> Co-authored-by: alxkm <19151554+alxkm@users.noreply.github.com> --- .../streaming/CusumDetector.java | 279 ++++++++++++++++++ .../streaming/CusumDetectorTest.java | 191 ++++++++++++ 2 files changed, 470 insertions(+) create mode 100644 src/main/java/com/thealgorithms/streaming/CusumDetector.java create mode 100644 src/test/java/com/thealgorithms/streaming/CusumDetectorTest.java diff --git a/src/main/java/com/thealgorithms/streaming/CusumDetector.java b/src/main/java/com/thealgorithms/streaming/CusumDetector.java new file mode 100644 index 000000000000..07a801b8015e --- /dev/null +++ b/src/main/java/com/thealgorithms/streaming/CusumDetector.java @@ -0,0 +1,279 @@ +package com.thealgorithms.streaming; + +/** + * CUSUM (cumulative sum) change detection: it notices that the level of a stream has shifted, + * long before the shift is visible in a moving average. + * + *

A threshold on the raw samples can only catch a change that is large compared with the noise. + * CUSUM instead accumulates evidence. Every sample is normalised into + * {@code z = (x - target) / sigma} and pushed into two one-sided sums: + * + *

+ * upper <- max(0, upper + z - allowance)
+ * lower <- max(0, lower - z - allowance)
+ * 
+ * + *

The allowance {@code k} is a toll paid on every step. While the stream sits at its + * target the toll exceeds the average evidence, both sums are pinned at zero and the detector stays + * quiet no matter how long it runs. As soon as the mean shifts by more than {@code k} standard + * deviations, the corresponding sum starts drifting upwards, and it keeps drifting: a small but + * persistent bias accumulates until it crosses the decision threshold {@code h}. That is the whole + * point of the method - a shift of half a standard deviation is invisible in any single sample, yet + * unmistakable after twenty of them. + * + *

The classic tuning is {@code k = delta / 2} for the shift size {@code delta} one wants to catch + * quickly, together with {@code h} between 4 and 5, which keeps false alarms rare while detecting a + * one sigma shift within roughly ten samples. Both sums are cleared whenever an alarm fires, so the + * detector immediately starts looking for the next change instead of latching. + * + *

Usage

+ * + *
{@code
+ * // Watch for a shift of one standard deviation around a target of 20.0.
+ * CusumDetector detector = new CusumDetector(20.0, 0.5, 0.5, 5.0);
+ * for (double sample : stream) {
+ *     ShiftSignal signal = detector.accept(sample);
+ *     if (signal.isAlarm()) {
+ *         alert(signal, detector.count());
+ *     }
+ * }
+ * }
+ * + *

Each sample costs O(1) time and the detector keeps O(1) state. This class is not thread-safe. + * + * @see CUSUM + */ +public final class CusumDetector { + + /** Allowance used when none is given; it targets shifts of one standard deviation. */ + public static final double DEFAULT_ALLOWANCE = 0.5; + + /** Decision threshold used when none is given. */ + public static final double DEFAULT_THRESHOLD = 5.0; + + private final double target; + private final double standardDeviation; + private final double allowance; + private final double threshold; + + private double upperSum; + private double lowerSum; + private long count; + private long alarmCount; + private ShiftSignal lastSignal = ShiftSignal.NONE; + + /** + * Creates a detector tuned for shifts of about one standard deviation. + * + * @param target the level the stream is expected to sit at + * @param standardDeviation the noise level of the stream, strictly positive + * @throws IllegalArgumentException if {@code target} is not finite or {@code standardDeviation} is not strictly positive + */ + public CusumDetector(double target, double standardDeviation) { + this(target, standardDeviation, DEFAULT_ALLOWANCE, DEFAULT_THRESHOLD); + } + + /** + * Creates a detector. + * + * @param target the level the stream is expected to sit at + * @param standardDeviation the noise level of the stream, strictly positive + * @param allowance the toll subtracted on every step, in standard deviations; half of the shift + * size one wants to detect quickly + * @param threshold how much accumulated evidence raises an alarm, in standard deviations + * @throws IllegalArgumentException if any argument is not finite, if {@code standardDeviation} or + * {@code threshold} is not strictly positive, or if {@code allowance} is negative + */ + public CusumDetector(double target, double standardDeviation, double allowance, double threshold) { + requireFinite(target, "target"); + if (!(standardDeviation > 0.0) || !Double.isFinite(standardDeviation)) { + throw new IllegalArgumentException("The standard deviation must be finite and strictly positive, but was " + standardDeviation); + } + if (!(allowance >= 0.0) || !Double.isFinite(allowance)) { + throw new IllegalArgumentException("The allowance must be finite and non-negative, but was " + allowance); + } + if (!(threshold > 0.0) || !Double.isFinite(threshold)) { + throw new IllegalArgumentException("The threshold must be finite and strictly positive, but was " + threshold); + } + this.target = target; + this.standardDeviation = standardDeviation; + this.allowance = allowance; + this.threshold = threshold; + } + + /** + * Feeds one sample into the detector. + * + * @param value the incoming sample + * @return {@link ShiftSignal#NONE} while the stream stays in control, otherwise the direction of + * the detected shift; the accumulated sums are cleared on an alarm + * @throws IllegalArgumentException if {@code value} is NaN or infinite + */ + public ShiftSignal accept(double value) { + requireFinite(value, "sample"); + count++; + + double normalized = (value - target) / standardDeviation; + upperSum = Math.max(0.0, upperSum + normalized - allowance); + lowerSum = Math.max(0.0, lowerSum - normalized - allowance); + + if (upperSum > threshold) { + lastSignal = ShiftSignal.UPWARD; + } else if (lowerSum > threshold) { + lastSignal = ShiftSignal.DOWNWARD; + } else { + lastSignal = ShiftSignal.NONE; + } + + if (lastSignal.isAlarm()) { + alarmCount++; + upperSum = 0.0; + lowerSum = 0.0; + } + return lastSignal; + } + + /** + * Runs the detector over a whole signal. + * + * @param signal the samples to inspect + * @return a new array of the same length holding the verdict for every sample + * @throws IllegalArgumentException if any sample is NaN or infinite + * @throws NullPointerException if {@code signal} is {@code null} + */ + public ShiftSignal[] scan(double[] signal) { + ShiftSignal[] signals = new ShiftSignal[signal.length]; + for (int i = 0; i < signal.length; i++) { + signals[i] = accept(signal[i]); + } + return signals; + } + + /** + * Returns the evidence accumulated in favour of an upward shift. + * + * @return the one-sided upper sum, never negative + */ + public double upperSum() { + return upperSum; + } + + /** + * Returns the evidence accumulated in favour of a downward shift. + * + * @return the one-sided lower sum, never negative + */ + public double lowerSum() { + return lowerSum; + } + + /** + * Returns the verdict on the most recent sample. + * + * @return the last signal, {@link ShiftSignal#NONE} before the first sample + */ + public ShiftSignal lastSignal() { + return lastSignal; + } + + /** + * Returns how many samples have been inspected since the last reset. + * + * @return the sample count + */ + public long count() { + return count; + } + + /** + * Returns how many alarms have been raised since the last reset. + * + * @return the alarm count + */ + public long alarmCount() { + return alarmCount; + } + + /** + * Returns the expected level of the stream. + * + * @return the target given at construction time + */ + public double target() { + return target; + } + + /** + * Returns the assumed noise level. + * + * @return the standard deviation given at construction time + */ + public double standardDeviation() { + return standardDeviation; + } + + /** + * Returns the per-step allowance. + * + * @return the allowance given at construction time + */ + public double allowance() { + return allowance; + } + + /** + * Returns the decision threshold. + * + * @return the threshold given at construction time + */ + public double threshold() { + return threshold; + } + + /** + * Clears the accumulated evidence and the counters. + */ + public void reset() { + upperSum = 0.0; + lowerSum = 0.0; + count = 0; + alarmCount = 0; + lastSignal = ShiftSignal.NONE; + } + + @Override + public String toString() { + return "CusumDetector{target=" + target + ", upperSum=" + upperSum + ", lowerSum=" + lowerSum + ", alarms=" + alarmCount + '}'; + } + + private static void requireFinite(double value, String name) { + if (!Double.isFinite(value)) { + throw new IllegalArgumentException("The " + name + " must be finite, but was " + value); + } + } + + /** + * What the detector reports after looking at one sample: either the stream still behaves as + * expected, or its level has shifted, in one direction or the other. + */ + public enum ShiftSignal { + + /** No evidence of a change; the stream is in control. */ + NONE, + + /** The level of the stream has moved above the target. */ + UPWARD, + + /** The level of the stream has moved below the target. */ + DOWNWARD; + + /** + * Tells whether this signal reports a change. + * + * @return {@code true} for {@link #UPWARD} and {@link #DOWNWARD} + */ + public boolean isAlarm() { + return this != NONE; + } + } +} diff --git a/src/test/java/com/thealgorithms/streaming/CusumDetectorTest.java b/src/test/java/com/thealgorithms/streaming/CusumDetectorTest.java new file mode 100644 index 000000000000..9c0e4a49f56a --- /dev/null +++ b/src/test/java/com/thealgorithms/streaming/CusumDetectorTest.java @@ -0,0 +1,191 @@ +package com.thealgorithms.streaming; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import com.thealgorithms.streaming.CusumDetector.ShiftSignal; +import java.util.Random; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +class CusumDetectorTest { + + /** + * Index of the first alarm in a sequence of verdicts, or {@code -1} if there is none. + */ + private static int firstAlarm(ShiftSignal[] signals) { + for (int i = 0; i < signals.length; i++) { + if (signals[i].isAlarm()) { + return i; + } + } + return -1; + } + + @Test + void rejectsInvalidConfiguration() { + assertThrows(IllegalArgumentException.class, () -> new CusumDetector(Double.NaN, 1.0)); + assertThrows(IllegalArgumentException.class, () -> new CusumDetector(0.0, 0.0)); + assertThrows(IllegalArgumentException.class, () -> new CusumDetector(0.0, -1.0)); + assertThrows(IllegalArgumentException.class, () -> new CusumDetector(0.0, 1.0, -0.5, 5.0)); + assertThrows(IllegalArgumentException.class, () -> new CusumDetector(0.0, 1.0, 0.5, 0.0)); + assertThrows(IllegalArgumentException.class, () -> new CusumDetector(0.0, 1.0, 0.5, Double.NaN)); + } + + @ParameterizedTest + @ValueSource(doubles = {Double.NaN, Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY}) + void rejectsNonFiniteSamples(double value) { + CusumDetector detector = new CusumDetector(0.0, 1.0); + assertThrows(IllegalArgumentException.class, () -> detector.accept(value)); + } + + @Test + void exposesItsConfiguration() { + CusumDetector detector = new CusumDetector(20.0, 0.5, 0.4, 4.0); + assertEquals(20.0, detector.target()); + assertEquals(0.5, detector.standardDeviation()); + assertEquals(0.4, detector.allowance()); + assertEquals(4.0, detector.threshold()); + assertEquals(ShiftSignal.NONE, detector.lastSignal()); + assertEquals(0L, detector.count()); + assertEquals(0L, detector.alarmCount()); + } + + @Test + @DisplayName("a stream sitting exactly on target never raises an alarm") + void staysQuietOnTarget() { + CusumDetector detector = new CusumDetector(10.0, 1.0); + for (int i = 0; i < 100_000; i++) { + assertEquals(ShiftSignal.NONE, detector.accept(10.0)); + } + assertEquals(0.0, detector.upperSum()); + assertEquals(0.0, detector.lowerSum()); + assertEquals(0L, detector.alarmCount()); + assertEquals(100_000L, detector.count()); + } + + @Test + @DisplayName("the toll keeps in-control noise from accumulating") + void staysMostlyQuietOnInControlNoise() { + Random random = new Random(20240517L); + CusumDetector detector = new CusumDetector(0.0, 1.0, 0.5, 8.0); + for (int i = 0; i < 2_000; i++) { + detector.accept(random.nextGaussian()); + } + assertTrue(detector.alarmCount() <= 2, "raised " + detector.alarmCount() + " false alarms in 2000 samples"); + } + + @Test + @DisplayName("a persistent upward shift is detected within a handful of samples") + void detectsAnUpwardShift() { + double[] signal = new double[60]; + Random random = new Random(11L); + for (int i = 0; i < signal.length; i++) { + signal[i] = (i < 30 ? 0.0 : 2.0) + 0.1 * random.nextGaussian(); + } + + CusumDetector detector = new CusumDetector(0.0, 1.0, 0.5, 5.0); + ShiftSignal[] verdicts = detector.scan(signal); + int alarm = firstAlarm(verdicts); + assertTrue(alarm >= 30, "alarmed before the shift, at index " + alarm); + assertTrue(alarm <= 35, "took too long to alarm, index " + alarm); + assertEquals(ShiftSignal.UPWARD, verdicts[alarm]); + } + + @Test + void detectsADownwardShift() { + double[] signal = new double[60]; + Random random = new Random(12L); + for (int i = 0; i < signal.length; i++) { + signal[i] = (i < 30 ? 100.0 : 96.0) + 0.5 * random.nextGaussian(); + } + + CusumDetector detector = new CusumDetector(100.0, 1.0, 0.5, 5.0); + ShiftSignal[] verdicts = detector.scan(signal); + int alarm = firstAlarm(verdicts); + assertTrue(alarm >= 30 && alarm <= 35, "alarm at index " + alarm); + assertEquals(ShiftSignal.DOWNWARD, verdicts[alarm]); + } + + @Test + @DisplayName("catches a drift far too small to see in any single sample") + void detectsASmallPersistentDrift() { + double[] signal = new double[400]; + Random random = new Random(13L); + for (int i = 0; i < signal.length; i++) { + // The stream is noise free until the drift starts, so an early alarm can only be a + // reaction to the drift itself. + signal[i] = i < 200 ? 0.0 : 0.5 + random.nextGaussian(); + } + + CusumDetector detector = new CusumDetector(0.0, 1.0, 0.25, 5.0); + int alarm = firstAlarm(detector.scan(signal)); + assertTrue(alarm >= 200, "alarmed before the drift, at index " + alarm); + assertTrue(alarm < 260, "a half sigma drift should be caught quickly, but took until " + alarm); + } + + @Test + void sumsNeverGoNegativeAndClearOnAlarm() { + CusumDetector detector = new CusumDetector(0.0, 1.0, 0.5, 3.0); + for (int i = 0; i < 50; i++) { + detector.accept(-5.0); + assertTrue(detector.upperSum() >= 0.0); + assertTrue(detector.lowerSum() >= 0.0); + } + assertTrue(detector.alarmCount() > 1, "a sustained shift should keep alarming"); + } + + @Test + void scanReportsOneVerdictPerSample() { + CusumDetector detector = new CusumDetector(0.0, 1.0); + ShiftSignal[] signals = detector.scan(new double[] {0.0, 0.0, 0.0}); + assertEquals(3, signals.length); + for (ShiftSignal signal : signals) { + assertEquals(ShiftSignal.NONE, signal); + assertFalse(signal.isAlarm()); + } + } + + @Test + void resetClearsTheEvidence() { + CusumDetector detector = new CusumDetector(0.0, 1.0, 0.5, 5.0); + for (int i = 0; i < 10; i++) { + detector.accept(1.5); + } + assertTrue(detector.upperSum() > 0.0 || detector.alarmCount() > 0); + + detector.reset(); + assertEquals(0.0, detector.upperSum()); + assertEquals(0.0, detector.lowerSum()); + assertEquals(0L, detector.count()); + assertEquals(0L, detector.alarmCount()); + assertEquals(ShiftSignal.NONE, detector.lastSignal()); + } + + @Test + void toStringMentionsTheState() { + CusumDetector detector = new CusumDetector(7.0, 1.0); + assertTrue(detector.toString().contains("target=7.0"), detector.toString()); + } + + @Test + void shiftSignalDescribesItself() { + assertFalse(ShiftSignal.NONE.isAlarm()); + assertTrue(ShiftSignal.UPWARD.isAlarm()); + assertTrue(ShiftSignal.DOWNWARD.isAlarm()); + assertEquals(3, ShiftSignal.values().length); + assertEquals(ShiftSignal.UPWARD, ShiftSignal.valueOf("UPWARD")); + } + + @Test + void rejectsNonFiniteConfiguration() { + assertThrows(IllegalArgumentException.class, () -> new CusumDetector(0.0, Double.NaN)); + assertThrows(IllegalArgumentException.class, () -> new CusumDetector(0.0, 1.0, Double.NaN, 5.0)); + assertThrows(IllegalArgumentException.class, () -> new CusumDetector(0.0, 1.0, Double.POSITIVE_INFINITY, 5.0)); + assertThrows(IllegalArgumentException.class, () -> new CusumDetector(0.0, 1.0, 0.5, Double.POSITIVE_INFINITY)); + } +} From d93d0ea444b170ee390baa7d8c945011d79b2707 Mon Sep 17 00:00:00 2001 From: Oleksandr Klymenko Date: Wed, 9 Sep 2026 10:40:33 +0300 Subject: [PATCH 11/92] feat: add HampelFilter, robust outlier replacement for streams (#7598) Signed-off-by: alxkm <19151554+alxkm@users.noreply.github.com> Co-authored-by: alxkm <19151554+alxkm@users.noreply.github.com> --- .../thealgorithms/streaming/HampelFilter.java | 263 ++++++++++++++++++ .../thealgorithms/streaming/MedianFilter.java | 229 +++++++++++++++ .../streaming/HampelFilterTest.java | 207 ++++++++++++++ .../streaming/MedianFilterTest.java | 172 ++++++++++++ 4 files changed, 871 insertions(+) create mode 100644 src/main/java/com/thealgorithms/streaming/HampelFilter.java create mode 100644 src/main/java/com/thealgorithms/streaming/MedianFilter.java create mode 100644 src/test/java/com/thealgorithms/streaming/HampelFilterTest.java create mode 100644 src/test/java/com/thealgorithms/streaming/MedianFilterTest.java diff --git a/src/main/java/com/thealgorithms/streaming/HampelFilter.java b/src/main/java/com/thealgorithms/streaming/HampelFilter.java new file mode 100644 index 000000000000..f6969d4cbca6 --- /dev/null +++ b/src/main/java/com/thealgorithms/streaming/HampelFilter.java @@ -0,0 +1,263 @@ +package com.thealgorithms.streaming; + +/** + * The Hampel filter, also known as the Hampel identifier: a decision rule that replaces the + * samples of a signal that look like outliers and leaves every other sample untouched. + * + *

A {@link MedianFilter} rewrites every sample, which throws away detail even where the signal + * was perfectly clean. The Hampel filter is the conservative version. For each incoming sample it + * looks at the window that ends at that sample and computes two robust statistics: + * + *

    + *
  • the median of the window, a robust estimate of where the signal is;
  • + *
  • the median absolute deviation {@code MAD = median(|x_i - median|)}, a robust estimate + * of how much the signal normally moves.
  • + *
+ * + *

The MAD is rescaled by {@code 1.4826}, the factor that makes it match the standard deviation + * for normally distributed data, and the sample is declared an outlier when + * + *

+ * |x - median| > threshold * 1.4826 * MAD
+ * 
+ * + *

Outliers are reported and replaced by the window median; everything else passes through + * unchanged. Both statistics are robust, so the spike being tested cannot inflate the very + * yardstick it is measured against - which is exactly what happens if one uses a mean and a standard + * deviation instead. + * + *

A threshold of 3 is the usual starting point, but how eager the filter turns out to be depends + * just as much on the window, because the MAD of a handful of samples is itself a noisy estimate of + * the spread. Measured on clean Gaussian noise with a threshold of 3, the filter flags about 7% of + * the samples with a window of 5, 3% with a window of 11 and 0.5% with a window of 101, slowly + * approaching the 0.3% one would get from a perfect estimate of sigma. Widen the window, or raise + * the threshold, when too many good samples are being rewritten. + * + *

Usage

+ * + *
{@code
+ * HampelFilter filter = new HampelFilter(7, 3.0);
+ * for (double sample : sensorReadings) {
+ *     double clean = filter.accept(sample);
+ *     if (filter.lastWasOutlier()) {
+ *         log.warn("spike of {} replaced by {}", sample, clean);
+ *     }
+ * }
+ * }
+ * + *

The window is causal and includes the sample being judged, so the filter introduces no delay, + * and the raw sample - not its replacement - is what enters the window, which keeps the statistics + * honest. Before the window has filled up the statistics are computed over the samples seen so far. + * If more than half of the window holds one and the same value the MAD is zero, and any sample that + * differs from the median at all is then flagged; that is the textbook behaviour of the identifier. + * + *

Each sample costs O(w) time for a window of {@code w} samples and nothing is allocated after + * construction. This class is not thread-safe. + * + * @see MedianFilter + * @see Median absolute deviation + */ +public final class HampelFilter { + + /** Makes the MAD of normally distributed data an unbiased estimator of its standard deviation. */ + public static final double GAUSSIAN_MAD_SCALE = 1.4826; + + /** Threshold, in robust standard deviations, used when none is given. */ + public static final double DEFAULT_THRESHOLD = 3.0; + + private final MedianFilter window; + private final double threshold; + private final double[] sortedWindow; + private final double[] deviations; + + private boolean lastWasOutlier; + private long outlierCount; + + /** + * Creates a filter with the customary threshold of three robust standard deviations. + * + * @param windowSize how many recent samples the statistics are computed over; odd sizes are the usual choice + * @throws IllegalArgumentException if {@code windowSize} is not positive + */ + public HampelFilter(int windowSize) { + this(windowSize, DEFAULT_THRESHOLD); + } + + /** + * Creates a filter. + * + * @param windowSize how many recent samples the statistics are computed over + * @param threshold how many robust standard deviations a sample may deviate before it counts as an + * outlier; must be non-negative + * @throws IllegalArgumentException if {@code windowSize} is not positive or {@code threshold} is negative or not finite + */ + public HampelFilter(int windowSize, double threshold) { + if (!(threshold >= 0.0) || !Double.isFinite(threshold)) { + throw new IllegalArgumentException("The threshold must be finite and non-negative, but was " + threshold); + } + this.window = new MedianFilter(windowSize); + this.threshold = threshold; + this.sortedWindow = new double[windowSize]; + this.deviations = new double[windowSize]; + } + + /** + * Feeds one sample into the filter. + * + * @param value the incoming sample + * @return the sample itself, or the window median if the sample was judged to be an outlier + * @throws IllegalArgumentException if {@code value} is NaN or infinite + */ + public double accept(double value) { + double median = window.accept(value); + double scaledDeviation = threshold * GAUSSIAN_MAD_SCALE * medianAbsoluteDeviation(); + lastWasOutlier = Math.abs(value - median) > scaledDeviation; + if (lastWasOutlier) { + outlierCount++; + return median; + } + return value; + } + + /** + * Filters a whole signal, one sample at a time, starting from the current state. + * + * @param signal the samples to filter + * @return a new array of the same length in which flagged samples are replaced by the local median + * @throws IllegalArgumentException if any sample is NaN or infinite + * @throws NullPointerException if {@code signal} is {@code null} + */ + public double[] filter(double[] signal) { + double[] filtered = new double[signal.length]; + for (int i = 0; i < signal.length; i++) { + filtered[i] = accept(signal[i]); + } + return filtered; + } + + /** + * Runs the filter over a signal and reports which samples were flagged, without altering them. + * + * @param signal the samples to inspect + * @return a new array of the same length, {@code true} where the sample was judged an outlier + * @throws IllegalArgumentException if any sample is NaN or infinite + * @throws NullPointerException if {@code signal} is {@code null} + */ + public boolean[] detectOutliers(double[] signal) { + boolean[] flags = new boolean[signal.length]; + for (int i = 0; i < signal.length; i++) { + accept(signal[i]); + flags[i] = lastWasOutlier; + } + return flags; + } + + /** + * Returns the median absolute deviation of the current window, the robust counterpart of the + * standard deviation. + * + * @return the MAD, {@code 0} when the window holds a single sample + * @throws IllegalStateException if no sample has been accepted yet + */ + public double medianAbsoluteDeviation() { + int size = window.copySortedWindow(sortedWindow); + if (size == 0) { + throw new IllegalStateException("The window is empty"); + } + double median = window.median(); + + // The window is sorted, so the absolute deviations form two already sorted runs that meet at + // the median: descending to its left, ascending to its right. Merging them is linear. + int split = size; + for (int i = 0; i < size; i++) { + if (sortedWindow[i] > median) { + split = i; + break; + } + } + int left = split - 1; + int right = split; + for (int i = 0; i < size; i++) { + boolean takeLeft = right >= size || (left >= 0 && median - sortedWindow[left] <= sortedWindow[right] - median); + if (takeLeft) { + deviations[i] = median - sortedWindow[left]; + left--; + } else { + deviations[i] = sortedWindow[right] - median; + right++; + } + } + + int middle = size / 2; + return size % 2 != 0 ? deviations[middle] : 0.5 * (deviations[middle - 1] + deviations[middle]); + } + + /** + * Returns the median of the current window. + * + * @return the window median + * @throws IllegalStateException if no sample has been accepted yet + */ + public double median() { + return window.median(); + } + + /** + * Tells whether the most recently accepted sample was flagged. + * + * @return {@code true} if the last sample was replaced by the median + */ + public boolean lastWasOutlier() { + return lastWasOutlier; + } + + /** + * Returns how many samples have been flagged since the last reset. + * + * @return the number of detected outliers + */ + public long outlierCount() { + return outlierCount; + } + + /** + * Returns the configured window length. + * + * @return the window size given at construction time + */ + public int windowSize() { + return window.windowSize(); + } + + /** + * Returns the configured threshold. + * + * @return the threshold in robust standard deviations + */ + public double threshold() { + return threshold; + } + + /** + * Returns how many samples the window currently holds. + * + * @return the current fill level, at most {@link #windowSize()} + */ + public int size() { + return window.size(); + } + + /** + * Empties the window and forgets the outlier count. + */ + public void reset() { + window.reset(); + lastWasOutlier = false; + outlierCount = 0; + } + + @Override + public String toString() { + return "HampelFilter{windowSize=" + windowSize() + ", threshold=" + threshold + ", outliers=" + outlierCount + '}'; + } +} diff --git a/src/main/java/com/thealgorithms/streaming/MedianFilter.java b/src/main/java/com/thealgorithms/streaming/MedianFilter.java new file mode 100644 index 000000000000..fa876a4feece --- /dev/null +++ b/src/main/java/com/thealgorithms/streaming/MedianFilter.java @@ -0,0 +1,229 @@ +package com.thealgorithms.streaming; + +import java.util.Arrays; + +/** + * A streaming median filter: it reports the median of the last {@code windowSize} samples of + * a signal. + * + *

The median filter is the standard first line of defence against impulsive noise. A single + * corrupted sample - a dropped bit, a spike on an analogue line, a sensor glitch - drags a moving + * average with it, but it cannot drag a median: as long as fewer than half of the samples in the + * window are corrupted, the output stays on the true signal. Unlike a linear low-pass filter, a + * median filter also preserves sharp edges instead of smearing them. + * + *

Two arrays of {@code windowSize} doubles are kept: the samples in arrival order, so the oldest + * one can be evicted, and the same samples in ascending order, so the median is the middle element. + * Insertion and removal in the sorted copy are binary search plus a memory move, which makes an + * update O(w) in the worst case but with a very small constant, and nothing is allocated after + * construction. + * + *

Usage

+ * + *
{@code
+ * MedianFilter filter = new MedianFilter(5);
+ * for (double sample : signal) {
+ *     double clean = filter.accept(sample);
+ * }
+ * }
+ * + *

The filter is causal: the value it reports for a sample is the median of that sample and the + * {@code windowSize - 1} preceding ones, so the output lags the input by roughly half a window. + * Before the window is full the median is taken over however many samples have arrived. With an even + * window size the median is the average of the two middle samples. + * + *

This class is not thread-safe. + * + * @see HampelFilter for a variant that only replaces samples identified as outliers + * @see Median filter + */ +public final class MedianFilter { + + private final double[] arrivalOrder; + private final double[] ascending; + private final int windowSize; + + private int size; + private int oldest; + + /** + * Creates an empty filter. + * + * @param windowSize how many recent samples the median is taken over; odd sizes are the usual choice + * @throws IllegalArgumentException if {@code windowSize} is not positive + */ + public MedianFilter(int windowSize) { + if (windowSize <= 0) { + throw new IllegalArgumentException("The window size must be positive, but was " + windowSize); + } + this.windowSize = windowSize; + this.arrivalOrder = new double[windowSize]; + this.ascending = new double[windowSize]; + } + + /** + * Feeds one sample into the filter. + * + * @param value the incoming sample + * @return the median of the window that now ends at this sample + * @throws IllegalArgumentException if {@code value} is NaN or infinite + */ + public double accept(double value) { + if (!Double.isFinite(value)) { + throw new IllegalArgumentException("Samples must be finite, but was " + value); + } + if (size == windowSize) { + removeFromSorted(arrivalOrder[oldest]); + size--; + } + insertIntoSorted(value); + arrivalOrder[oldest] = value; + oldest = (oldest + 1) % windowSize; + size++; + return median(); + } + + /** + * Filters a whole signal, one sample at a time, starting from the current state. + * + * @param signal the samples to filter + * @return a new array of the same length holding the running medians + * @throws IllegalArgumentException if any sample is NaN or infinite + * @throws NullPointerException if {@code signal} is {@code null} + */ + public double[] filter(double[] signal) { + double[] filtered = new double[signal.length]; + for (int i = 0; i < signal.length; i++) { + filtered[i] = accept(signal[i]); + } + return filtered; + } + + /** + * Returns the median of the samples currently in the window. + * + * @return the median, averaging the two middle samples when the window holds an even number of them + * @throws IllegalStateException if no sample has been accepted yet + */ + public double median() { + if (size == 0) { + throw new IllegalStateException("The window is empty"); + } + int middle = size / 2; + if (size % 2 != 0) { + return ascending[middle]; + } + return 0.5 * (ascending[middle - 1] + ascending[middle]); + } + + /** + * Returns the smallest sample currently in the window. + * + * @return the minimum of the window + * @throws IllegalStateException if no sample has been accepted yet + */ + public double min() { + requireNonEmpty(); + return ascending[0]; + } + + /** + * Returns the largest sample currently in the window. + * + * @return the maximum of the window + * @throws IllegalStateException if no sample has been accepted yet + */ + public double max() { + requireNonEmpty(); + return ascending[size - 1]; + } + + /** + * Returns the configured window length. + * + * @return the window size given at construction time + */ + public int windowSize() { + return windowSize; + } + + /** + * Returns how many samples the window currently holds. + * + * @return the current fill level, at most {@link #windowSize()} + */ + public int size() { + return size; + } + + /** + * Tells whether the window has warmed up. + * + * @return {@code true} once the window holds {@link #windowSize()} samples + */ + public boolean isFull() { + return size == windowSize; + } + + /** + * Tells whether the window holds no samples. + * + * @return {@code true} if nothing has been accepted since the last reset + */ + public boolean isEmpty() { + return size == 0; + } + + /** + * Returns the window contents in ascending order. + * + * @return a new array holding the sorted window + */ + public double[] sortedWindow() { + return Arrays.copyOf(ascending, size); + } + + /** + * Empties the window. + */ + public void reset() { + size = 0; + oldest = 0; + } + + @Override + public String toString() { + return "MedianFilter{windowSize=" + windowSize + ", size=" + size + ", median=" + (size == 0 ? Double.NaN : median()) + '}'; + } + + /** + * Copies the sorted window into a caller supplied buffer, which lets tight loops avoid allocating. + * + * @param destination buffer of at least {@link #windowSize()} elements + * @return the number of values written + */ + int copySortedWindow(double[] destination) { + System.arraycopy(ascending, 0, destination, 0, size); + return size; + } + + private void insertIntoSorted(double value) { + int position = Arrays.binarySearch(ascending, 0, size, value); + if (position < 0) { + position = -(position + 1); + } + System.arraycopy(ascending, position, ascending, position + 1, size - position); + ascending[position] = value; + } + + private void removeFromSorted(double value) { + int position = Arrays.binarySearch(ascending, 0, size, value); + System.arraycopy(ascending, position + 1, ascending, position, size - position - 1); + } + + private void requireNonEmpty() { + if (size == 0) { + throw new IllegalStateException("The window is empty"); + } + } +} diff --git a/src/test/java/com/thealgorithms/streaming/HampelFilterTest.java b/src/test/java/com/thealgorithms/streaming/HampelFilterTest.java new file mode 100644 index 000000000000..fe33656eb5da --- /dev/null +++ b/src/test/java/com/thealgorithms/streaming/HampelFilterTest.java @@ -0,0 +1,207 @@ +package com.thealgorithms.streaming; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.Arrays; +import java.util.Random; +import org.junit.jupiter.api.Assertions; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +class HampelFilterTest { + + private static double median(double[] values) { + double[] sorted = values.clone(); + Arrays.sort(sorted); + int middle = sorted.length / 2; + return sorted.length % 2 != 0 ? sorted[middle] : 0.5 * (sorted[middle - 1] + sorted[middle]); + } + + /** + * Median absolute deviation of the window ending at {@code index}, computed the obvious way. + */ + private static double bruteForceMad(double[] signal, int index, int windowSize) { + int from = Math.max(0, index - windowSize + 1); + double[] window = Arrays.copyOfRange(signal, from, index + 1); + double windowMedian = median(window); + double[] deviations = new double[window.length]; + for (int i = 0; i < window.length; i++) { + deviations[i] = Math.abs(window[i] - windowMedian); + } + return median(deviations); + } + + @ParameterizedTest + @ValueSource(ints = {0, -1}) + void rejectsNonPositiveWindowSizes(int windowSize) { + assertThrows(IllegalArgumentException.class, () -> new HampelFilter(windowSize)); + } + + @ParameterizedTest + @ValueSource(doubles = {-1.0, Double.NaN, Double.POSITIVE_INFINITY}) + void rejectsInvalidThresholds(double threshold) { + assertThrows(IllegalArgumentException.class, () -> new HampelFilter(5, threshold)); + } + + @Test + void queriesBeforeTheFirstSampleFail() { + HampelFilter filter = new HampelFilter(5); + assertEquals(5, filter.windowSize()); + assertEquals(HampelFilter.DEFAULT_THRESHOLD, filter.threshold()); + assertEquals(0, filter.size()); + assertEquals(0L, filter.outlierCount()); + assertFalse(filter.lastWasOutlier()); + assertThrows(IllegalStateException.class, filter::median); + assertThrows(IllegalStateException.class, filter::medianAbsoluteDeviation); + } + + @ParameterizedTest + @ValueSource(doubles = {Double.NaN, Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY}) + void rejectsNonFiniteSamples(double value) { + HampelFilter filter = new HampelFilter(5); + assertThrows(IllegalArgumentException.class, () -> filter.accept(value)); + } + + @ParameterizedTest + @ValueSource(ints = {1, 2, 3, 5, 8, 15}) + @DisplayName("the median absolute deviation agrees with a brute force computation") + void madMatchesBruteForce(int windowSize) { + Random random = new Random(20240517L + windowSize); + double[] signal = new double[2_000]; + for (int i = 0; i < signal.length; i++) { + signal[i] = random.nextInt(100) - 50; + } + + HampelFilter filter = new HampelFilter(windowSize, 3.0); + for (int i = 0; i < signal.length; i++) { + filter.accept(signal[i]); + assertEquals(bruteForceMad(signal, i, windowSize), filter.medianAbsoluteDeviation(), 1e-12, "at index " + i); + } + } + + @Test + @DisplayName("a single spike is flagged and replaced by the local median") + void replacesASpike() { + HampelFilter filter = new HampelFilter(5, 3.0); + double[] signal = {5.0, 5.1, 4.9, 5.0, 5.05, 50.0, 5.0, 5.1}; + double[] filtered = filter.filter(signal); + + assertEquals(1L, filter.outlierCount()); + assertTrue(filtered[5] < 6.0, "the spike should have been replaced, but stayed at " + filtered[5]); + for (int i = 0; i < signal.length; i++) { + if (i != 5) { + assertEquals(signal[i], filtered[i], 0.0, "clean sample at index " + i + " must pass through"); + } + } + } + + @Test + void detectOutliersReportsWithoutChangingTheSignal() { + HampelFilter filter = new HampelFilter(5, 3.0); + double[] signal = {5.0, 5.1, 4.9, 5.0, 5.05, 50.0, 5.0, 5.1}; + boolean[] flags = filter.detectOutliers(signal); + + boolean[] expected = new boolean[signal.length]; + expected[5] = true; + Assertions.assertArrayEquals(expected, flags); + assertEquals(1L, filter.outlierCount()); + } + + @Test + @DisplayName("a clean ramp contains no outliers, since the MAD grows with the slope") + void leavesASmoothRampAlone() { + HampelFilter filter = new HampelFilter(5, 3.0); + double[] ramp = new double[200]; + for (int i = 0; i < ramp.length; i++) { + ramp[i] = i; + } + Assertions.assertArrayEquals(ramp, filter.filter(ramp), 0.0); + assertEquals(0L, filter.outlierCount()); + } + + @Test + void leavesAConstantSignalAlone() { + HampelFilter filter = new HampelFilter(7); + for (int i = 0; i < 100; i++) { + assertEquals(3.0, filter.accept(3.0)); + } + assertEquals(0L, filter.outlierCount()); + assertEquals(0.0, filter.medianAbsoluteDeviation()); + } + + @Test + @DisplayName("only a few samples of clean Gaussian noise are flagged") + void staysQuietOnCleanNoise() { + Random random = new Random(4242L); + HampelFilter filter = new HampelFilter(11, 3.0); + for (int i = 0; i < 5_000; i++) { + filter.accept(random.nextGaussian()); + } + assertTrue(filter.outlierCount() < 500, "flagged " + filter.outlierCount() + " of 5000 clean samples"); + } + + @Test + @DisplayName("spikes buried in noise are caught") + void catchesSpikesInNoisyData() { + Random random = new Random(7L); + double[] signal = new double[1_000]; + for (int i = 0; i < signal.length; i++) { + signal[i] = 20.0 + random.nextGaussian(); + } + int[] spikes = {100, 300, 700}; + for (int spike : spikes) { + signal[spike] = 200.0; + } + + HampelFilter filter = new HampelFilter(9, 3.0); + double[] filtered = filter.filter(signal); + for (int spike : spikes) { + assertTrue(filtered[spike] < 30.0, "spike at " + spike + " survived as " + filtered[spike]); + } + } + + @Test + @DisplayName("a zero MAD makes the identifier maximally strict") + void flagsAnyDeviationWhenTheMadIsZero() { + HampelFilter filter = new HampelFilter(5, 3.0); + for (int i = 0; i < 5; i++) { + filter.accept(5.0); + } + assertEquals(0.0, filter.medianAbsoluteDeviation()); + assertEquals(5.0, filter.accept(5.5)); + assertTrue(filter.lastWasOutlier()); + } + + @Test + void aThresholdOfZeroFlagsEverythingOffTheMedian() { + HampelFilter filter = new HampelFilter(3, 0.0); + filter.accept(1.0); + filter.accept(2.0); + assertTrue(filter.lastWasOutlier()); + assertEquals(1.5, filter.median(), 1e-12); + } + + @Test + void resetForgetsTheWindowAndTheCounters() { + HampelFilter filter = new HampelFilter(5, 3.0); + filter.filter(new double[] {5.0, 5.1, 4.9, 5.0, 5.05, 50.0}); + assertEquals(1L, filter.outlierCount()); + + filter.reset(); + assertEquals(0, filter.size()); + assertEquals(0L, filter.outlierCount()); + assertFalse(filter.lastWasOutlier()); + assertThrows(IllegalStateException.class, filter::median); + } + + @Test + void toStringMentionsTheState() { + HampelFilter filter = new HampelFilter(5, 2.5); + assertTrue(filter.toString().contains("threshold=2.5"), filter.toString()); + } +} diff --git a/src/test/java/com/thealgorithms/streaming/MedianFilterTest.java b/src/test/java/com/thealgorithms/streaming/MedianFilterTest.java new file mode 100644 index 000000000000..a176000022cc --- /dev/null +++ b/src/test/java/com/thealgorithms/streaming/MedianFilterTest.java @@ -0,0 +1,172 @@ +package com.thealgorithms.streaming; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.Arrays; +import java.util.Random; +import org.junit.jupiter.api.Assertions; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +class MedianFilterTest { + + /** + * Median of the last {@code windowSize} samples of {@code signal} ending at {@code index}, + * computed the obvious way. + */ + private static double bruteForceMedian(double[] signal, int index, int windowSize) { + int from = Math.max(0, index - windowSize + 1); + double[] window = Arrays.copyOfRange(signal, from, index + 1); + Arrays.sort(window); + int middle = window.length / 2; + return window.length % 2 != 0 ? window[middle] : 0.5 * (window[middle - 1] + window[middle]); + } + + @ParameterizedTest + @ValueSource(ints = {0, -1, Integer.MIN_VALUE}) + void rejectsNonPositiveWindowSizes(int windowSize) { + assertThrows(IllegalArgumentException.class, () -> new MedianFilter(windowSize)); + } + + @Test + void queriesBeforeTheFirstSampleFail() { + MedianFilter filter = new MedianFilter(3); + assertTrue(filter.isEmpty()); + assertFalse(filter.isFull()); + assertEquals(0, filter.size()); + assertEquals(3, filter.windowSize()); + assertEquals(0, filter.sortedWindow().length); + assertThrows(IllegalStateException.class, filter::median); + assertThrows(IllegalStateException.class, filter::min); + assertThrows(IllegalStateException.class, filter::max); + } + + @ParameterizedTest + @ValueSource(doubles = {Double.NaN, Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY}) + void rejectsNonFiniteSamples(double value) { + MedianFilter filter = new MedianFilter(3); + assertThrows(IllegalArgumentException.class, () -> filter.accept(value)); + } + + @Test + @DisplayName("before the window fills up the median is taken over what has arrived") + void warmsUpGracefully() { + MedianFilter filter = new MedianFilter(5); + assertEquals(4.0, filter.accept(4.0)); + assertEquals(3.0, filter.accept(2.0), 1e-12); + assertEquals(4.0, filter.accept(9.0), 1e-12); + assertEquals(3, filter.size()); + assertFalse(filter.isFull()); + } + + @Test + void aWindowOfOneIsTheIdentity() { + MedianFilter filter = new MedianFilter(1); + assertEquals(5.0, filter.accept(5.0)); + assertEquals(-3.0, filter.accept(-3.0)); + assertTrue(filter.isFull()); + assertEquals(-3.0, filter.min()); + assertEquals(-3.0, filter.max()); + } + + @Test + @DisplayName("an even window averages the two middle samples") + void handlesEvenWindows() { + MedianFilter filter = new MedianFilter(4); + filter.accept(1.0); + filter.accept(2.0); + filter.accept(3.0); + assertEquals(2.5, filter.accept(4.0), 1e-12); + assertEquals(3.5, filter.accept(5.0), 1e-12); + } + + @Test + @DisplayName("a lone spike is removed, an edge is preserved") + void removesSpikesButKeepsEdges() { + MedianFilter filter = new MedianFilter(3); + double[] signal = {1.0, 1.0, 100.0, 1.0, 1.0, 9.0, 9.0, 9.0}; + double[] filtered = filter.filter(signal); + Assertions.assertArrayEquals(new double[] {1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 9.0, 9.0}, filtered, 1e-12); + } + + @Test + void reportsTheExtremesOfTheWindow() { + MedianFilter filter = new MedianFilter(3); + filter.filter(new double[] {5.0, 1.0, 9.0}); + assertEquals(1.0, filter.min()); + assertEquals(9.0, filter.max()); + Assertions.assertArrayEquals(new double[] {1.0, 5.0, 9.0}, filter.sortedWindow(), 0.0); + + filter.accept(7.0); + assertEquals(1.0, filter.min()); + assertEquals(9.0, filter.max()); + Assertions.assertArrayEquals(new double[] {1.0, 7.0, 9.0}, filter.sortedWindow(), 0.0); + } + + @ParameterizedTest + @ValueSource(ints = {1, 2, 3, 4, 7, 16, 31}) + @DisplayName("agrees with a brute force median for every window size") + void matchesBruteForce(int windowSize) { + Random random = new Random(20240517L + windowSize); + double[] signal = new double[3_000]; + for (int i = 0; i < signal.length; i++) { + signal[i] = random.nextInt(50); + } + + MedianFilter filter = new MedianFilter(windowSize); + for (int i = 0; i < signal.length; i++) { + assertEquals(bruteForceMedian(signal, i, windowSize), filter.accept(signal[i]), 1e-12, "at index " + i); + assertEquals(Math.min(i + 1, windowSize), filter.size()); + } + } + + @Test + @DisplayName("handles duplicates, which is where a sorted mirror of the window can go wrong") + void handlesHeavyDuplication() { + Random random = new Random(11L); + double[] signal = new double[2_000]; + for (int i = 0; i < signal.length; i++) { + signal[i] = random.nextInt(3); + } + + MedianFilter filter = new MedianFilter(5); + for (int i = 0; i < signal.length; i++) { + assertEquals(bruteForceMedian(signal, i, 5), filter.accept(signal[i]), 1e-12, "at index " + i); + } + } + + @Test + void resetEmptiesTheWindow() { + MedianFilter filter = new MedianFilter(3); + filter.filter(new double[] {1.0, 2.0, 3.0}); + filter.reset(); + + assertTrue(filter.isEmpty()); + assertThrows(IllegalStateException.class, filter::median); + assertEquals(8.0, filter.accept(8.0)); + } + + @Test + void toStringMentionsTheState() { + MedianFilter filter = new MedianFilter(3); + assertTrue(filter.toString().contains("size=0"), filter.toString()); + filter.accept(2.0); + assertTrue(filter.toString().contains("median=2.0"), filter.toString()); + } + + @Test + void reportsWhetherItHoldsSamples() { + MedianFilter filter = new MedianFilter(2); + assertTrue(filter.isEmpty()); + filter.accept(1.0); + assertFalse(filter.isEmpty()); + assertFalse(filter.isFull()); + filter.accept(2.0); + assertTrue(filter.isFull()); + } +} From 1f08afb1697f41afb1d692eaff43b1fbe725d670 Mon Sep 17 00:00:00 2001 From: Oleksandr Klymenko Date: Wed, 9 Sep 2026 21:37:52 +0300 Subject: [PATCH 12/92] feat: add EwmaChangeDetector, an EWMA control chart for streams (#7600) Adds an exponentially weighted moving average control chart that flags level shifts in a stream in O(1) time and memory per sample, with an exact variance-based control band so that the warm-up does not trip false alarms. It builds on a new reusable ExponentialMovingAverage (alpha, span or half-life parameterisation, and the exponentially weighted variance of the same stream) and shares the ShiftSignal verdict enum with CusumDetector, out of which it is extracted to the package level so that both detectors report the same type. Signed-off-by: alxkm <19151554+alxkm@users.noreply.github.com> Co-authored-by: alxkm <19151554+alxkm@users.noreply.github.com> --- .../streaming/CusumDetector.java | 25 -- .../streaming/EwmaChangeDetector.java | 251 ++++++++++++++++++ .../streaming/ExponentialMovingAverage.java | 233 ++++++++++++++++ .../thealgorithms/streaming/ShiftSignal.java | 29 ++ .../streaming/CusumDetectorTest.java | 1 - .../streaming/EwmaChangeDetectorTest.java | 209 +++++++++++++++ .../ExponentialMovingAverageTest.java | 180 +++++++++++++ 7 files changed, 902 insertions(+), 26 deletions(-) create mode 100644 src/main/java/com/thealgorithms/streaming/EwmaChangeDetector.java create mode 100644 src/main/java/com/thealgorithms/streaming/ExponentialMovingAverage.java create mode 100644 src/main/java/com/thealgorithms/streaming/ShiftSignal.java create mode 100644 src/test/java/com/thealgorithms/streaming/EwmaChangeDetectorTest.java create mode 100644 src/test/java/com/thealgorithms/streaming/ExponentialMovingAverageTest.java diff --git a/src/main/java/com/thealgorithms/streaming/CusumDetector.java b/src/main/java/com/thealgorithms/streaming/CusumDetector.java index 07a801b8015e..618edb25a9af 100644 --- a/src/main/java/com/thealgorithms/streaming/CusumDetector.java +++ b/src/main/java/com/thealgorithms/streaming/CusumDetector.java @@ -251,29 +251,4 @@ private static void requireFinite(double value, String name) { throw new IllegalArgumentException("The " + name + " must be finite, but was " + value); } } - - /** - * What the detector reports after looking at one sample: either the stream still behaves as - * expected, or its level has shifted, in one direction or the other. - */ - public enum ShiftSignal { - - /** No evidence of a change; the stream is in control. */ - NONE, - - /** The level of the stream has moved above the target. */ - UPWARD, - - /** The level of the stream has moved below the target. */ - DOWNWARD; - - /** - * Tells whether this signal reports a change. - * - * @return {@code true} for {@link #UPWARD} and {@link #DOWNWARD} - */ - public boolean isAlarm() { - return this != NONE; - } - } } diff --git a/src/main/java/com/thealgorithms/streaming/EwmaChangeDetector.java b/src/main/java/com/thealgorithms/streaming/EwmaChangeDetector.java new file mode 100644 index 000000000000..88d60da02988 --- /dev/null +++ b/src/main/java/com/thealgorithms/streaming/EwmaChangeDetector.java @@ -0,0 +1,251 @@ +package com.thealgorithms.streaming; + +/** + * An EWMA control chart: change detection built on the exponentially weighted moving average. + * + *

The detector smooths the stream with + * {@link ExponentialMovingAverage} seeded at the target level and compares the smoothed value with a + * band around that target: + * + *

+ * z     <- z + alpha * (x - target)
+ * limit  = width * sigma * sqrt( alpha / (2 - alpha) * (1 - (1 - alpha)^(2n)) )
+ * 
+ * + *

The band is the exact standard deviation of {@code z} under the null hypothesis, multiplied by + * the desired width in sigmas. It starts narrow and widens towards its asymptote + * {@code width * sigma * sqrt(alpha / (2 - alpha))}, which keeps the false alarm rate steady during + * the warm-up instead of letting the first few samples trip the alarm. An alarm fires as soon as the + * smoothed value leaves the band; the average is then reset to the target so that the detector + * starts fresh on the next change rather than latching. + * + *

Where {@link CusumDetector} accumulates evidence without limit and so excels at small, + * persistent shifts, an EWMA chart looks at a decaying window of the recent past: {@code alpha} + * around {@code 0.1 - 0.3} is a good compromise, larger values reacting faster to big jumps and + * smaller ones being more sensitive to slow drifts. A width of 3 sigmas is the customary setting. + * + *

Usage

+ * + *
{@code
+ * EwmaChangeDetector detector = new EwmaChangeDetector(20.0, 0.5, 0.2, 3.0);
+ * for (double sample : stream) {
+ *     if (detector.accept(sample).isAlarm()) {
+ *         alert(detector.statistic(), detector.controlLimit());
+ *     }
+ * }
+ * }
+ * + *

Each sample costs O(1) time and the detector keeps O(1) state. This class is not thread-safe. + * + * @see CusumDetector + * @see ExponentialMovingAverage + * @see EWMA chart + */ +public final class EwmaChangeDetector { + + /** Smoothing factor used when none is given. */ + public static final double DEFAULT_ALPHA = 0.2; + + /** Half-width of the control band, in sigmas, used when none is given. */ + public static final double DEFAULT_WIDTH = 3.0; + + private final double target; + private final double standardDeviation; + private final double alpha; + private final double width; + + private final ExponentialMovingAverage average; + private long count; + private long stepsSinceAlarm; + private long alarmCount; + private ShiftSignal lastSignal = ShiftSignal.NONE; + + /** + * Creates a detector with the customary smoothing factor of {@code 0.2} and a band of three + * sigmas. + * + * @param target the level the stream is expected to sit at + * @param standardDeviation the noise level of the stream, strictly positive + * @throws IllegalArgumentException if {@code target} is not finite or {@code standardDeviation} is not strictly positive + */ + public EwmaChangeDetector(double target, double standardDeviation) { + this(target, standardDeviation, DEFAULT_ALPHA, DEFAULT_WIDTH); + } + + /** + * Creates a detector. + * + * @param target the level the stream is expected to sit at + * @param standardDeviation the noise level of the stream, strictly positive + * @param alpha smoothing factor in {@code (0, 1]}; larger values react faster but tolerate less noise + * @param width half-width of the control band in sigmas, strictly positive + * @throws IllegalArgumentException if any argument is not finite, if {@code standardDeviation} or + * {@code width} is not strictly positive, or if {@code alpha} is outside {@code (0, 1]} + */ + public EwmaChangeDetector(double target, double standardDeviation, double alpha, double width) { + if (!Double.isFinite(target)) { + throw new IllegalArgumentException("The target must be finite, but was " + target); + } + if (!(standardDeviation > 0.0) || !Double.isFinite(standardDeviation)) { + throw new IllegalArgumentException("The standard deviation must be finite and strictly positive, but was " + standardDeviation); + } + if (!(width > 0.0) || !Double.isFinite(width)) { + throw new IllegalArgumentException("The width must be finite and strictly positive, but was " + width); + } + this.target = target; + this.standardDeviation = standardDeviation; + this.width = width; + this.average = ExponentialMovingAverage.ofAlpha(alpha, target); + this.alpha = this.average.alpha(); + } + + /** + * Feeds one sample into the detector. + * + * @param value the incoming sample + * @return {@link ShiftSignal#NONE} while the smoothed value stays inside the control band, + * otherwise the direction in which it left the band; the average is reset to the target on an alarm + * @throws IllegalArgumentException if {@code value} is NaN or infinite + */ + public ShiftSignal accept(double value) { + if (!Double.isFinite(value)) { + throw new IllegalArgumentException("Samples must be finite, but was " + value); + } + count++; + stepsSinceAlarm++; + double smoothed = average.add(value); + double deviation = smoothed - target; + double limit = controlLimit(); + + if (deviation > limit) { + lastSignal = ShiftSignal.UPWARD; + } else if (deviation < -limit) { + lastSignal = ShiftSignal.DOWNWARD; + } else { + lastSignal = ShiftSignal.NONE; + } + + if (lastSignal.isAlarm()) { + alarmCount++; + stepsSinceAlarm = 0; + average.reset(); + } + return lastSignal; + } + + /** + * Runs the detector over a whole signal. + * + * @param signal the samples to inspect + * @return a new array of the same length holding the verdict for every sample + * @throws IllegalArgumentException if any sample is NaN or infinite + * @throws NullPointerException if {@code signal} is {@code null} + */ + public ShiftSignal[] scan(double[] signal) { + ShiftSignal[] signals = new ShiftSignal[signal.length]; + for (int i = 0; i < signal.length; i++) { + signals[i] = accept(signal[i]); + } + return signals; + } + + /** + * Returns the smoothed value the alarm decision is based on. + * + * @return the exponentially weighted average of the stream + */ + public double statistic() { + return average.value(); + } + + /** + * Returns the current half-width of the control band, which widens during the warm-up and then + * settles. + * + * @return the distance from the target at which an alarm fires + */ + public double controlLimit() { + double asymptotic = alpha / (2.0 - alpha); + double warmUp = -Math.expm1(2.0 * stepsSinceAlarm * Math.log1p(-alpha)); + return width * standardDeviation * Math.sqrt(asymptotic * warmUp); + } + + /** + * Returns the verdict on the most recent sample. + * + * @return the last signal, {@link ShiftSignal#NONE} before the first sample + */ + public ShiftSignal lastSignal() { + return lastSignal; + } + + /** + * Returns how many samples have been inspected since the last reset. + * + * @return the sample count + */ + public long count() { + return count; + } + + /** + * Returns how many alarms have been raised since the last reset. + * + * @return the alarm count + */ + public long alarmCount() { + return alarmCount; + } + + /** + * Returns the expected level of the stream. + * + * @return the target given at construction time + */ + public double target() { + return target; + } + + /** + * Returns the assumed noise level. + * + * @return the standard deviation given at construction time + */ + public double standardDeviation() { + return standardDeviation; + } + + /** + * Returns the smoothing factor in use. + * + * @return alpha + */ + public double alpha() { + return alpha; + } + + /** + * Returns the configured band half-width. + * + * @return the width in sigmas given at construction time + */ + public double width() { + return width; + } + + /** + * Returns the average to the target and clears the counters. + */ + public void reset() { + average.reset(); + count = 0; + stepsSinceAlarm = 0; + alarmCount = 0; + lastSignal = ShiftSignal.NONE; + } + + @Override + public String toString() { + return "EwmaChangeDetector{target=" + target + ", statistic=" + statistic() + ", limit=" + controlLimit() + ", alarms=" + alarmCount + '}'; + } +} diff --git a/src/main/java/com/thealgorithms/streaming/ExponentialMovingAverage.java b/src/main/java/com/thealgorithms/streaming/ExponentialMovingAverage.java new file mode 100644 index 000000000000..ce97c6339c8c --- /dev/null +++ b/src/main/java/com/thealgorithms/streaming/ExponentialMovingAverage.java @@ -0,0 +1,233 @@ +package com.thealgorithms.streaming; + +/** + * Exponentially weighted moving average (EWMA) and, alongside it, the exponentially weighted + * variance of the same stream. + * + *

A plain moving average has to remember the whole window. An exponentially weighted one does + * not: every sample simply decays, so a single number carries the entire history. + * + *

+ * mean     <- mean + alpha * (x - mean)
+ * variance <- (1 - alpha) * (variance + alpha * (x - mean_before)^2)
+ * 
+ * + *

The smoothing factor {@code alpha} in {@code (0, 1]} sets how fast the past is forgotten: + * {@code alpha == 1} keeps only the latest sample, while a small {@code alpha} produces a smooth but + * sluggish estimate. It is usually easier to specify the responsiveness in terms of a window, which + * the factory methods do for you: + * + * + * + * + * + * + * + *
Ways to choose alpha
FactoryalphaMeaning
{@link #ofAlpha(double)}as givendirect control
{@link #ofSpan(double)}{@code 2 / (span + 1)}comparable to a simple moving average of {@code span} samples
{@link #ofHalfLife(double)}{@code 1 - exp(-ln2 / halfLife)}a sample loses half of its weight after {@code halfLife} steps
+ * + *

The average is seeded with the first sample, which avoids the warm-up bias that a zero seed + * would introduce. Pass an explicit seed to {@link #ofAlpha(double, double)} when the resting level + * of the signal is known in advance, as a control chart does. + * + *

Both the update and every query run in O(1) time and O(1) memory. This class is not + * thread-safe. + * + * @see EwmaChangeDetector + * @see Exponential moving average + */ +public final class ExponentialMovingAverage { + + private final double alpha; + private final double seed; + private final boolean seeded; + + private double mean; + private double variance; + private long count; + private boolean initialized; + + private ExponentialMovingAverage(double alpha, double seed, boolean seeded) { + if (!(alpha > 0.0) || alpha > 1.0) { + throw new IllegalArgumentException("The smoothing factor alpha must lie in (0, 1], but was " + alpha); + } + if (seeded && !Double.isFinite(seed)) { + throw new IllegalArgumentException("The seed must be finite, but was " + seed); + } + this.alpha = alpha; + this.seed = seed; + this.seeded = seeded; + reset(); + } + + /** + * Creates an average that is seeded with its first sample. + * + * @param alpha smoothing factor in {@code (0, 1]} + * @return a new average + * @throws IllegalArgumentException if {@code alpha} is outside {@code (0, 1]} + */ + public static ExponentialMovingAverage ofAlpha(double alpha) { + return new ExponentialMovingAverage(alpha, 0.0, false); + } + + /** + * Creates an average that starts from a known level instead of waiting for the first sample. + * + * @param alpha smoothing factor in {@code (0, 1]} + * @param seed the initial value of the average + * @return a new average + * @throws IllegalArgumentException if {@code alpha} is outside {@code (0, 1]} or {@code seed} is not finite + */ + public static ExponentialMovingAverage ofAlpha(double alpha, double seed) { + return new ExponentialMovingAverage(alpha, seed, true); + } + + /** + * Creates an average whose responsiveness matches a simple moving average of {@code span} + * samples, that is {@code alpha = 2 / (span + 1)}. + * + * @param span the equivalent window length, greater than or equal to one + * @return a new average + * @throws IllegalArgumentException if {@code span} is smaller than one or not finite + */ + public static ExponentialMovingAverage ofSpan(double span) { + if (!(span >= 1.0) || !Double.isFinite(span)) { + throw new IllegalArgumentException("The span must be finite and at least 1, but was " + span); + } + return ofAlpha(2.0 / (span + 1.0)); + } + + /** + * Creates an average in which a sample loses half of its weight after {@code halfLife} updates, + * that is {@code alpha = 1 - exp(-ln2 / halfLife)}. + * + * @param halfLife number of updates after which a weight is halved, strictly positive + * @return a new average + * @throws IllegalArgumentException if {@code halfLife} is not strictly positive or not finite + */ + public static ExponentialMovingAverage ofHalfLife(double halfLife) { + if (!(halfLife > 0.0) || !Double.isFinite(halfLife)) { + throw new IllegalArgumentException("The half-life must be finite and positive, but was " + halfLife); + } + return ofAlpha(-Math.expm1(-Math.log(2.0) / halfLife)); + } + + /** + * Incorporates one sample. + * + * @param value the sample to add + * @return the updated average + * @throws IllegalArgumentException if {@code value} is NaN or infinite + */ + public double add(double value) { + if (!Double.isFinite(value)) { + throw new IllegalArgumentException("Samples must be finite, but was " + value); + } + count++; + if (!initialized) { + initialized = true; + mean = value; + variance = 0.0; + return mean; + } + double deviation = value - mean; + mean += alpha * deviation; + variance = (1.0 - alpha) * (variance + alpha * deviation * deviation); + return mean; + } + + /** + * Incorporates every given sample, in order. + * + * @param values the samples to add + * @return the average after the last sample + * @throws IllegalArgumentException if any value is NaN or infinite + * @throws IllegalStateException if {@code values} is empty and the average is not initialized yet + * @throws NullPointerException if {@code values} is {@code null} + */ + public double addAll(double... values) { + for (double value : values) { + add(value); + } + return value(); + } + + /** + * Returns the current average. + * + * @return the exponentially weighted mean + * @throws IllegalStateException if the average has neither a seed nor a sample yet + */ + public double value() { + if (!initialized) { + throw new IllegalStateException("The average has not seen any sample yet"); + } + return mean; + } + + /** + * Returns the exponentially weighted variance of the stream, the natural companion of + * {@link #value()} when the spread matters as much as the level. + * + * @return the weighted variance, {@code 0} until the second sample arrives + * @throws IllegalStateException if the average has neither a seed nor a sample yet + */ + public double variance() { + if (!initialized) { + throw new IllegalStateException("The average has not seen any sample yet"); + } + return variance; + } + + /** + * Returns the square root of {@link #variance()}. + * + * @return the weighted standard deviation + * @throws IllegalStateException if the average has neither a seed nor a sample yet + */ + public double standardDeviation() { + return Math.sqrt(variance()); + } + + /** + * Returns the smoothing factor in use. + * + * @return alpha + */ + public double alpha() { + return alpha; + } + + /** + * Returns the number of samples added since the last reset. + * + * @return the sample count, which excludes the seed + */ + public long count() { + return count; + } + + /** + * Tells whether {@link #value()} may be queried. + * + * @return {@code true} once a seed or at least one sample is available + */ + public boolean isInitialized() { + return initialized; + } + + /** + * Restores the state the average had right after construction. + */ + public void reset() { + count = 0; + variance = 0.0; + mean = seeded ? seed : 0.0; + initialized = seeded; + } + + @Override + public String toString() { + return "ExponentialMovingAverage{alpha=" + alpha + ", value=" + (initialized ? mean : Double.NaN) + ", count=" + count + '}'; + } +} diff --git a/src/main/java/com/thealgorithms/streaming/ShiftSignal.java b/src/main/java/com/thealgorithms/streaming/ShiftSignal.java new file mode 100644 index 000000000000..467dcf060e0e --- /dev/null +++ b/src/main/java/com/thealgorithms/streaming/ShiftSignal.java @@ -0,0 +1,29 @@ +package com.thealgorithms.streaming; + +/** + * What a change detector reports after looking at one sample: either the stream still behaves as + * expected, or its level has shifted, in one direction or the other. + * + * @see CusumDetector + * @see EwmaChangeDetector + */ +public enum ShiftSignal { + + /** No evidence of a change; the stream is in control. */ + NONE, + + /** The level of the stream has moved above the target. */ + UPWARD, + + /** The level of the stream has moved below the target. */ + DOWNWARD; + + /** + * Tells whether this signal reports a change. + * + * @return {@code true} for {@link #UPWARD} and {@link #DOWNWARD} + */ + public boolean isAlarm() { + return this != NONE; + } +} diff --git a/src/test/java/com/thealgorithms/streaming/CusumDetectorTest.java b/src/test/java/com/thealgorithms/streaming/CusumDetectorTest.java index 9c0e4a49f56a..996d71d219bc 100644 --- a/src/test/java/com/thealgorithms/streaming/CusumDetectorTest.java +++ b/src/test/java/com/thealgorithms/streaming/CusumDetectorTest.java @@ -5,7 +5,6 @@ import static org.junit.jupiter.api.Assertions.assertThrows; import static org.junit.jupiter.api.Assertions.assertTrue; -import com.thealgorithms.streaming.CusumDetector.ShiftSignal; import java.util.Random; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; diff --git a/src/test/java/com/thealgorithms/streaming/EwmaChangeDetectorTest.java b/src/test/java/com/thealgorithms/streaming/EwmaChangeDetectorTest.java new file mode 100644 index 000000000000..37b1688b424f --- /dev/null +++ b/src/test/java/com/thealgorithms/streaming/EwmaChangeDetectorTest.java @@ -0,0 +1,209 @@ +package com.thealgorithms.streaming; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.Random; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +class EwmaChangeDetectorTest { + + /** + * Index of the first alarm in a sequence of verdicts, or {@code -1} if there is none. + */ + private static int firstAlarm(ShiftSignal[] signals) { + for (int i = 0; i < signals.length; i++) { + if (signals[i].isAlarm()) { + return i; + } + } + return -1; + } + + private static double[] stepSignal(int length, int stepAt, double before, double after) { + double[] signal = new double[length]; + for (int i = 0; i < length; i++) { + signal[i] = i < stepAt ? before : after; + } + return signal; + } + + @Test + void rejectsInvalidConfiguration() { + assertThrows(IllegalArgumentException.class, () -> new EwmaChangeDetector(Double.NaN, 1.0)); + assertThrows(IllegalArgumentException.class, () -> new EwmaChangeDetector(0.0, 0.0)); + assertThrows(IllegalArgumentException.class, () -> new EwmaChangeDetector(0.0, -2.0)); + assertThrows(IllegalArgumentException.class, () -> new EwmaChangeDetector(0.0, 1.0, 0.2, 0.0)); + assertThrows(IllegalArgumentException.class, () -> new EwmaChangeDetector(0.0, 1.0, 0.0, 3.0)); + assertThrows(IllegalArgumentException.class, () -> new EwmaChangeDetector(0.0, 1.0, 1.5, 3.0)); + } + + @ParameterizedTest + @ValueSource(doubles = {Double.NaN, Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY}) + void rejectsNonFiniteSamples(double value) { + EwmaChangeDetector detector = new EwmaChangeDetector(0.0, 1.0); + assertThrows(IllegalArgumentException.class, () -> detector.accept(value)); + } + + @Test + void exposesItsConfiguration() { + EwmaChangeDetector detector = new EwmaChangeDetector(20.0, 0.5, 0.3, 2.5); + assertEquals(20.0, detector.target()); + assertEquals(0.5, detector.standardDeviation()); + assertEquals(0.3, detector.alpha()); + assertEquals(2.5, detector.width()); + assertEquals(20.0, detector.statistic()); + assertEquals(ShiftSignal.NONE, detector.lastSignal()); + assertEquals(0L, detector.count()); + assertEquals(0L, detector.alarmCount()); + } + + @Test + @DisplayName("the defaults are the customary alpha of 0.2 and a band of three sigmas") + void usesCustomaryDefaults() { + EwmaChangeDetector detector = new EwmaChangeDetector(0.0, 1.0); + assertEquals(EwmaChangeDetector.DEFAULT_ALPHA, detector.alpha()); + assertEquals(EwmaChangeDetector.DEFAULT_WIDTH, detector.width()); + } + + @Test + @DisplayName("a stream sitting exactly on target never raises an alarm") + void staysQuietOnTarget() { + EwmaChangeDetector detector = new EwmaChangeDetector(5.0, 1.0); + for (int i = 0; i < 10_000; i++) { + assertEquals(ShiftSignal.NONE, detector.accept(5.0)); + } + assertEquals(5.0, detector.statistic(), 1e-12); + assertEquals(0L, detector.alarmCount()); + assertEquals(10_000L, detector.count()); + } + + @Test + @DisplayName("the control band widens during the warm-up and then settles") + void controlLimitApproachesItsAsymptote() { + double alpha = 0.2; + double width = 3.0; + double sigma = 2.0; + EwmaChangeDetector detector = new EwmaChangeDetector(0.0, sigma, alpha, width); + + double asymptote = width * sigma * Math.sqrt(alpha / (2.0 - alpha)); + assertEquals(0.0, detector.controlLimit(), 1e-12); + + double previous = 0.0; + for (int i = 0; i < 40; i++) { + detector.accept(0.0); + double limit = detector.controlLimit(); + assertTrue(limit > previous, "the limit stopped growing at step " + i); + assertTrue(limit < asymptote, "the exact limit stays below its asymptote, but was " + limit); + previous = limit; + } + + for (int i = 0; i < 200; i++) { + detector.accept(0.0); + } + assertEquals(asymptote, detector.controlLimit(), 1e-9); + } + + @Test + void detectsAnUpwardShift() { + EwmaChangeDetector detector = new EwmaChangeDetector(0.0, 1.0, 0.2, 3.0); + ShiftSignal[] verdicts = detector.scan(stepSignal(60, 30, 0.0, 2.0)); + + int alarm = firstAlarm(verdicts); + assertTrue(alarm >= 30, "alarmed before the shift, at index " + alarm); + assertTrue(alarm <= 36, "took too long to alarm, index " + alarm); + assertEquals(ShiftSignal.UPWARD, verdicts[alarm]); + } + + @Test + void detectsADownwardShift() { + EwmaChangeDetector detector = new EwmaChangeDetector(100.0, 2.0, 0.2, 3.0); + ShiftSignal[] verdicts = detector.scan(stepSignal(60, 30, 100.0, 94.0)); + + int alarm = firstAlarm(verdicts); + assertTrue(alarm >= 30 && alarm <= 36, "alarm at index " + alarm); + assertEquals(ShiftSignal.DOWNWARD, verdicts[alarm]); + } + + @Test + @DisplayName("an alarm returns the statistic to the target so the detector does not latch") + void resetsTheStatisticOnAnAlarm() { + EwmaChangeDetector detector = new EwmaChangeDetector(0.0, 1.0, 0.2, 3.0); + ShiftSignal[] verdicts = detector.scan(stepSignal(40, 0, 2.0, 2.0)); + + assertTrue(firstAlarm(verdicts) >= 0); + assertTrue(detector.alarmCount() > 1, "a sustained shift should keep alarming"); + for (int i = 0; i < verdicts.length; i++) { + if (verdicts[i].isAlarm() && i + 1 < verdicts.length) { + assertEquals(ShiftSignal.NONE, verdicts[i + 1], "the sample right after an alarm restarts from the target"); + } + } + } + + @Test + @DisplayName("in-control noise rarely trips the band") + void staysMostlyQuietOnInControlNoise() { + Random random = new Random(20240517L); + EwmaChangeDetector detector = new EwmaChangeDetector(0.0, 1.0, 0.2, 4.0); + for (int i = 0; i < 2_000; i++) { + detector.accept(random.nextGaussian()); + } + assertTrue(detector.alarmCount() <= 3, "raised " + detector.alarmCount() + " false alarms in 2000 samples"); + } + + @Test + @DisplayName("a shift buried in noise is still found") + void detectsAShiftInNoisyData() { + Random random = new Random(4242L); + double[] signal = new double[400]; + for (int i = 0; i < signal.length; i++) { + signal[i] = (i < 200 ? 0.0 : 1.5) + random.nextGaussian(); + } + + EwmaChangeDetector detector = new EwmaChangeDetector(0.0, 1.0, 0.2, 4.0); + ShiftSignal[] verdicts = detector.scan(signal); + int alarm = firstAlarm(verdicts); + assertTrue(alarm >= 200, "alarmed before the shift, at index " + alarm); + assertTrue(alarm < 220, "the shift should be found quickly, but took until " + alarm); + assertEquals(ShiftSignal.UPWARD, verdicts[alarm]); + } + + @Test + void scanReportsOneVerdictPerSample() { + EwmaChangeDetector detector = new EwmaChangeDetector(0.0, 1.0); + ShiftSignal[] verdicts = detector.scan(new double[] {0.0, 0.0, 0.0}); + assertEquals(3, verdicts.length); + assertEquals(3L, detector.count()); + } + + @Test + void resetRestoresTheInitialState() { + EwmaChangeDetector detector = new EwmaChangeDetector(4.0, 1.0, 0.5, 3.0); + detector.scan(stepSignal(20, 0, 20.0, 20.0)); + detector.reset(); + + assertEquals(4.0, detector.statistic()); + assertEquals(0.0, detector.controlLimit(), 1e-12); + assertEquals(0L, detector.count()); + assertEquals(0L, detector.alarmCount()); + assertEquals(ShiftSignal.NONE, detector.lastSignal()); + } + + @Test + void toStringMentionsTheState() { + EwmaChangeDetector detector = new EwmaChangeDetector(7.0, 1.0); + assertTrue(detector.toString().contains("target=7.0"), detector.toString()); + } + + @Test + void rejectsNonFiniteConfiguration() { + assertThrows(IllegalArgumentException.class, () -> new EwmaChangeDetector(0.0, Double.NaN)); + assertThrows(IllegalArgumentException.class, () -> new EwmaChangeDetector(0.0, Double.POSITIVE_INFINITY)); + assertThrows(IllegalArgumentException.class, () -> new EwmaChangeDetector(0.0, 1.0, 0.2, Double.NaN)); + assertThrows(IllegalArgumentException.class, () -> new EwmaChangeDetector(0.0, 1.0, 0.2, Double.POSITIVE_INFINITY)); + } +} diff --git a/src/test/java/com/thealgorithms/streaming/ExponentialMovingAverageTest.java b/src/test/java/com/thealgorithms/streaming/ExponentialMovingAverageTest.java new file mode 100644 index 000000000000..83931dbec1b1 --- /dev/null +++ b/src/test/java/com/thealgorithms/streaming/ExponentialMovingAverageTest.java @@ -0,0 +1,180 @@ +package com.thealgorithms.streaming; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.Random; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +class ExponentialMovingAverageTest { + + @ParameterizedTest + @ValueSource(doubles = {0.0, -0.5, 1.5, Double.NaN, Double.POSITIVE_INFINITY}) + void rejectsInvalidAlpha(double alpha) { + assertThrows(IllegalArgumentException.class, () -> ExponentialMovingAverage.ofAlpha(alpha)); + } + + @ParameterizedTest + @ValueSource(doubles = {0.0, 0.5, -3.0, Double.NaN, Double.POSITIVE_INFINITY}) + void rejectsInvalidSpan(double span) { + assertThrows(IllegalArgumentException.class, () -> ExponentialMovingAverage.ofSpan(span)); + } + + @ParameterizedTest + @ValueSource(doubles = {0.0, -1.0, Double.NaN, Double.POSITIVE_INFINITY}) + void rejectsInvalidHalfLife(double halfLife) { + assertThrows(IllegalArgumentException.class, () -> ExponentialMovingAverage.ofHalfLife(halfLife)); + } + + @Test + void rejectsNonFiniteSeed() { + assertThrows(IllegalArgumentException.class, () -> ExponentialMovingAverage.ofAlpha(0.5, Double.NaN)); + } + + @Test + void spanAndHalfLifeTranslateIntoAlpha() { + assertEquals(0.2, ExponentialMovingAverage.ofSpan(9.0).alpha(), 1e-12); + assertEquals(1.0, ExponentialMovingAverage.ofSpan(1.0).alpha(), 1e-12); + assertEquals(0.5, ExponentialMovingAverage.ofHalfLife(1.0).alpha(), 1e-12); + assertEquals(1.0 - Math.pow(0.5, 0.1), ExponentialMovingAverage.ofHalfLife(10.0).alpha(), 1e-12); + } + + @Test + void queriesBeforeTheFirstSampleFail() { + ExponentialMovingAverage average = ExponentialMovingAverage.ofAlpha(0.5); + assertFalse(average.isInitialized()); + assertThrows(IllegalStateException.class, average::value); + assertThrows(IllegalStateException.class, average::variance); + assertThrows(IllegalStateException.class, average::standardDeviation); + } + + @Test + @DisplayName("the first sample seeds the average instead of being pulled towards zero") + void seedsWithTheFirstSample() { + ExponentialMovingAverage average = ExponentialMovingAverage.ofAlpha(0.1); + assertEquals(100.0, average.add(100.0)); + assertTrue(average.isInitialized()); + assertEquals(1L, average.count()); + } + + @Test + void followsTheRecurrence() { + ExponentialMovingAverage average = ExponentialMovingAverage.ofAlpha(0.5); + assertEquals(1.0, average.add(1.0), 1e-12); + assertEquals(1.5, average.add(2.0), 1e-12); + assertEquals(2.25, average.add(3.0), 1e-12); + assertEquals(3L, average.count()); + } + + @Test + void anExplicitSeedIsUsedRightAway() { + ExponentialMovingAverage average = ExponentialMovingAverage.ofAlpha(0.5, 0.0); + assertTrue(average.isInitialized()); + assertEquals(0.0, average.value()); + assertEquals(0.5, average.add(1.0), 1e-12); + assertEquals(1L, average.count(), "the seed is not counted as a sample"); + } + + @Test + void alphaOfOneKeepsOnlyTheLatestSample() { + ExponentialMovingAverage average = ExponentialMovingAverage.ofAlpha(1.0); + average.addAll(1.0, 2.0, 3.0); + assertEquals(3.0, average.value(), 1e-12); + assertEquals(0.0, average.variance(), 1e-12); + } + + @Test + void trackedVarianceFollowsTheRecurrence() { + ExponentialMovingAverage average = ExponentialMovingAverage.ofAlpha(0.5); + average.add(0.0); + assertEquals(0.0, average.variance(), 1e-12); + average.add(2.0); + assertEquals(1.0, average.variance(), 1e-12); + average.add(0.0); + assertEquals(0.75, average.variance(), 1e-12); + assertEquals(Math.sqrt(0.75), average.standardDeviation(), 1e-12); + } + + @Test + void aConstantSignalHasNoSpread() { + ExponentialMovingAverage average = ExponentialMovingAverage.ofSpan(10.0); + for (int i = 0; i < 100; i++) { + average.add(7.0); + } + assertEquals(7.0, average.value(), 1e-12); + assertEquals(0.0, average.variance(), 1e-12); + } + + @Test + @DisplayName("a step in the signal is tracked, the faster the larger alpha is") + void tracksAStep() { + ExponentialMovingAverage fast = ExponentialMovingAverage.ofAlpha(0.5); + ExponentialMovingAverage slow = ExponentialMovingAverage.ofAlpha(0.05); + fast.add(0.0); + slow.add(0.0); + for (int i = 0; i < 10; i++) { + fast.add(10.0); + slow.add(10.0); + } + assertTrue(fast.value() > slow.value(), "fast=" + fast.value() + " slow=" + slow.value()); + assertEquals(10.0, fast.value(), 0.05); + assertTrue(slow.value() < 5.0); + + for (int i = 0; i < 500; i++) { + slow.add(10.0); + } + assertEquals(10.0, slow.value(), 1e-6); + } + + @Test + @DisplayName("on stationary noise the estimates sit close to the true mean and variance") + void approximatesTheStationaryMoments() { + Random random = new Random(987L); + ExponentialMovingAverage average = ExponentialMovingAverage.ofAlpha(0.01); + for (int i = 0; i < 200_000; i++) { + average.add(5.0 + 2.0 * random.nextGaussian()); + } + assertEquals(5.0, average.value(), 0.5); + assertEquals(4.0, average.variance(), 2.0); + } + + @Test + void resetReturnsToTheInitialState() { + ExponentialMovingAverage plain = ExponentialMovingAverage.ofAlpha(0.5); + plain.addAll(1.0, 2.0, 3.0); + plain.reset(); + assertFalse(plain.isInitialized()); + assertEquals(0L, plain.count()); + + ExponentialMovingAverage seeded = ExponentialMovingAverage.ofAlpha(0.5, 42.0); + seeded.addAll(1.0, 2.0); + seeded.reset(); + assertTrue(seeded.isInitialized()); + assertEquals(42.0, seeded.value()); + } + + @ParameterizedTest + @ValueSource(doubles = {Double.NaN, Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY}) + void rejectsNonFiniteSamples(double value) { + ExponentialMovingAverage average = ExponentialMovingAverage.ofAlpha(0.3); + assertThrows(IllegalArgumentException.class, () -> average.add(value)); + } + + @Test + void toStringMentionsTheState() { + ExponentialMovingAverage average = ExponentialMovingAverage.ofAlpha(0.25); + average.add(4.0); + assertTrue(average.toString().contains("alpha=0.25"), average.toString()); + } + + @Test + void toStringWorksBeforeTheFirstSample() { + ExponentialMovingAverage average = ExponentialMovingAverage.ofAlpha(0.25); + assertTrue(average.toString().contains("value=NaN"), average.toString()); + } +} From a097a286fc0c7b268ec9788996db5dfd8782ab45 Mon Sep 17 00:00:00 2001 From: Oleksandr Klymenko Date: Fri, 11 Sep 2026 21:03:41 +0300 Subject: [PATCH 13/92] feat: add WelfordAlgorithm, online mean and variance in one pass (#7602) Welford's recurrence keeps a running mean and the sum of squared deviations from it, so it never forms the large nearly equal intermediate values that make the textbook variance formula lose its significant digits, and it needs O(1) time per sample and O(1) memory regardless of the stream length. Beyond the plain accumulation it supports removal, which runs the recurrence backwards and turns the accumulator into the statistics of a sliding window, and a static merge implementing Chan's parallel update so partial results from different shards combine exactly. Signed-off-by: alxkm <19151554+alxkm@users.noreply.github.com> Co-authored-by: alxkm <19151554+alxkm@users.noreply.github.com> --- .../streaming/WelfordAlgorithm.java | 245 ++++++++++++++++++ .../streaming/WelfordAlgorithmTest.java | 243 +++++++++++++++++ 2 files changed, 488 insertions(+) create mode 100644 src/main/java/com/thealgorithms/streaming/WelfordAlgorithm.java create mode 100644 src/test/java/com/thealgorithms/streaming/WelfordAlgorithmTest.java diff --git a/src/main/java/com/thealgorithms/streaming/WelfordAlgorithm.java b/src/main/java/com/thealgorithms/streaming/WelfordAlgorithm.java new file mode 100644 index 000000000000..62752df3d7da --- /dev/null +++ b/src/main/java/com/thealgorithms/streaming/WelfordAlgorithm.java @@ -0,0 +1,245 @@ +package com.thealgorithms.streaming; + +/** + * Online (single pass) mean and variance using Welford's algorithm. + * + *

The textbook formula {@code Var = (sum(x^2) - n * mean^2) / (n - 1)} is fast but numerically + * treacherous: {@code sum(x^2)} and {@code n * mean^2} may be huge and nearly equal, so their + * difference loses most of its significant digits and can even come out negative. Welford's + * recurrence never forms those large intermediate values. It keeps only the running mean and the sum + * of squared deviations from that running mean, {@code M2}: + * + *

+ * n     <- n + 1
+ * delta <- x - mean
+ * mean  <- mean + delta / n
+ * M2    <- M2 + delta * (x - mean)   // note: the second factor uses the *updated* mean
+ * 
+ * + *

Both {@link #add(double)} and {@link #remove(double)} run in O(1) time and the accumulator + * occupies O(1) memory no matter how many samples pass through it. + * + *

Sliding windows and map-reduce

+ * + *
    + *
  • {@link #remove(double)} runs the recurrence backwards, which turns the accumulator into the + * statistics of a sliding window: feed the incoming sample to {@code add} and the sample that + * just left the window to {@code remove}. Removal is the one operation that can degrade + * accuracy over a very long run, since the value being removed no longer matches the mean it + * was added to; recreate the accumulator periodically if that matters.
  • + *
  • {@link #merge(WelfordAlgorithm, WelfordAlgorithm)} implements Chan's parallel update, so + * partial results computed on different shards can be combined exactly.
  • + *
+ * + *

Usage

+ * + *
{@code
+ * WelfordAlgorithm stats = new WelfordAlgorithm();
+ * stats.add(2.0);
+ * stats.add(4.0);
+ * stats.add(4.0);
+ * stats.mean();                        // 3.3333...
+ * stats.populationStandardDeviation();  // 0.9428...
+ * }
+ * + *

This class is not thread-safe. + * + * @see ExponentialMovingAverage + * @see Algorithms for calculating variance + */ +public final class WelfordAlgorithm { + + private long count; + private double mean; + private double sumOfSquaredDeviations; + + /** + * Creates an empty accumulator. + */ + public WelfordAlgorithm() { + clear(); + } + + /** + * Incorporates one sample. + * + * @param value the sample to add + * @throws IllegalArgumentException if {@code value} is NaN or infinite + */ + public void add(double value) { + requireFinite(value); + count++; + double delta = value - mean; + mean += delta / count; + sumOfSquaredDeviations += delta * (value - mean); + } + + /** + * Incorporates every given sample, in order. + * + * @param values the samples to add + * @throws IllegalArgumentException if any value is NaN or infinite + * @throws NullPointerException if {@code values} is {@code null} + */ + public void addAll(double... values) { + for (double value : values) { + add(value); + } + } + + /** + * Removes a previously added sample, reversing {@link #add(double)}. This is what makes the + * accumulator usable for a sliding window. + * + * @param value the sample to remove; it must genuinely have been added before + * @throws IllegalStateException if the accumulator is empty + * @throws IllegalArgumentException if {@code value} is NaN or infinite + */ + public void remove(double value) { + requireFinite(value); + if (count == 0) { + throw new IllegalStateException("Cannot remove a sample from an empty accumulator"); + } + if (count == 1) { + clear(); + return; + } + double previousMean = mean; + mean = (count * mean - value) / (count - 1); + sumOfSquaredDeviations -= (value - previousMean) * (value - mean); + count--; + if (sumOfSquaredDeviations < 0.0) { + sumOfSquaredDeviations = 0.0; + } + } + + /** + * Combines two independently accumulated summaries using Chan's parallel variance update. + * + * @param left summary of the first batch of samples + * @param right summary of the second batch of samples + * @return a new summary describing the concatenation of both batches + * @throws NullPointerException if either argument is {@code null} + */ + public static WelfordAlgorithm merge(WelfordAlgorithm left, WelfordAlgorithm right) { + WelfordAlgorithm merged = new WelfordAlgorithm(); + merged.count = left.count + right.count; + if (merged.count == 0) { + return merged; + } + double delta = right.mean - left.mean; + merged.mean = left.mean + delta * right.count / merged.count; + merged.sumOfSquaredDeviations = left.sumOfSquaredDeviations + right.sumOfSquaredDeviations + delta * delta * left.count * right.count / merged.count; + return merged; + } + + /** + * Returns the number of samples seen so far. + * + * @return the sample count + */ + public long count() { + return count; + } + + /** + * Tells whether any sample has been added. + * + * @return {@code true} if no sample is currently accounted for + */ + public boolean isEmpty() { + return count == 0; + } + + /** + * Returns the arithmetic mean of the samples. + * + * @return the mean, or {@link Double#NaN} if no sample has been added + */ + public double mean() { + return count == 0 ? Double.NaN : mean; + } + + /** + * Returns the sum of the samples, reconstructed from the mean. + * + * @return {@code count * mean}, or {@code 0} if no sample has been added + */ + public double sum() { + return count == 0 ? 0.0 : mean * count; + } + + /** + * Returns the sum of squared deviations from the mean, {@code M2}. + * + * @return the sum of squared deviations, {@code 0} for an empty accumulator + */ + public double sumOfSquaredDeviations() { + return sumOfSquaredDeviations; + } + + /** + * Returns the unbiased sample variance, normalised by {@code count - 1}. + * + * @return the sample variance, or {@link Double#NaN} if fewer than two samples were added + */ + public double sampleVariance() { + return count < 2 ? Double.NaN : sumOfSquaredDeviations / (count - 1); + } + + /** + * Returns the population variance, normalised by {@code count}. + * + * @return the population variance, or {@link Double#NaN} if no sample has been added + */ + public double populationVariance() { + return count == 0 ? Double.NaN : sumOfSquaredDeviations / count; + } + + /** + * Returns the square root of {@link #sampleVariance()}. + * + * @return the sample standard deviation, or {@link Double#NaN} if fewer than two samples were added + */ + public double sampleStandardDeviation() { + return Math.sqrt(sampleVariance()); + } + + /** + * Returns the square root of {@link #populationVariance()}. + * + * @return the population standard deviation, or {@link Double#NaN} if no sample has been added + */ + public double populationStandardDeviation() { + return Math.sqrt(populationVariance()); + } + + /** + * Returns the standard error of the mean, {@code sampleStandardDeviation / sqrt(count)}. + * + * @return the standard error, or {@link Double#NaN} if fewer than two samples were added + */ + public double standardError() { + return sampleStandardDeviation() / Math.sqrt(count); + } + + /** + * Forgets every sample. + */ + public void clear() { + count = 0; + mean = 0.0; + sumOfSquaredDeviations = 0.0; + } + + @Override + public String toString() { + return "WelfordAlgorithm{count=" + count + ", mean=" + mean() + ", sampleStandardDeviation=" + sampleStandardDeviation() + '}'; + } + + private static void requireFinite(double value) { + if (!Double.isFinite(value)) { + throw new IllegalArgumentException("Samples must be finite, but was " + value); + } + } +} diff --git a/src/test/java/com/thealgorithms/streaming/WelfordAlgorithmTest.java b/src/test/java/com/thealgorithms/streaming/WelfordAlgorithmTest.java new file mode 100644 index 000000000000..5031e9de6e62 --- /dev/null +++ b/src/test/java/com/thealgorithms/streaming/WelfordAlgorithmTest.java @@ -0,0 +1,243 @@ +package com.thealgorithms.streaming; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.Random; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +class WelfordAlgorithmTest { + + private static final double[] TEXTBOOK_SAMPLE = {2.0, 4.0, 4.0, 4.0, 5.0, 5.0, 7.0, 9.0}; + + private static double twoPassPopulationVariance(double... values) { + double mean = 0.0; + for (double value : values) { + mean += value; + } + mean /= values.length; + + double sumOfSquares = 0.0; + for (double value : values) { + sumOfSquares += (value - mean) * (value - mean); + } + return sumOfSquares / values.length; + } + + @Test + void emptyAccumulatorReportsNothing() { + WelfordAlgorithm stats = new WelfordAlgorithm(); + assertTrue(stats.isEmpty()); + assertEquals(0L, stats.count()); + assertEquals(0.0, stats.sum()); + assertEquals(0.0, stats.sumOfSquaredDeviations()); + assertTrue(Double.isNaN(stats.mean())); + assertTrue(Double.isNaN(stats.populationVariance())); + assertTrue(Double.isNaN(stats.sampleVariance())); + assertTrue(Double.isNaN(stats.sampleStandardDeviation())); + assertTrue(Double.isNaN(stats.standardError())); + } + + @Test + void singleSampleHasNoSpread() { + WelfordAlgorithm stats = new WelfordAlgorithm(); + stats.add(42.0); + assertFalse(stats.isEmpty()); + assertEquals(1L, stats.count()); + assertEquals(42.0, stats.mean()); + assertEquals(42.0, stats.sum()); + assertEquals(0.0, stats.populationVariance()); + assertTrue(Double.isNaN(stats.sampleVariance())); + } + + @Test + @DisplayName("reproduces the textbook values of a known sample") + void matchesKnownValues() { + WelfordAlgorithm stats = new WelfordAlgorithm(); + stats.addAll(TEXTBOOK_SAMPLE); + + assertEquals(8L, stats.count()); + assertEquals(5.0, stats.mean(), 1e-12); + assertEquals(40.0, stats.sum(), 1e-12); + assertEquals(32.0, stats.sumOfSquaredDeviations(), 1e-12); + assertEquals(4.0, stats.populationVariance(), 1e-12); + assertEquals(2.0, stats.populationStandardDeviation(), 1e-12); + assertEquals(32.0 / 7.0, stats.sampleVariance(), 1e-12); + assertEquals(Math.sqrt(32.0 / 7.0), stats.sampleStandardDeviation(), 1e-12); + assertEquals(Math.sqrt(32.0 / 7.0 / 8.0), stats.standardError(), 1e-12); + } + + @Test + @DisplayName("stays accurate where the naive sum of squares collapses") + void survivesLargeOffsets() { + double offset = 1e9; + double[] values = {offset + 4.0, offset + 7.0, offset + 13.0, offset + 16.0}; + + WelfordAlgorithm stats = new WelfordAlgorithm(); + stats.addAll(values); + + // The naive formula computes sum(x^2) - n * mean^2 on numbers of order 1e18 and loses every + // significant digit of the answer; Welford's recurrence never forms them. + double naive = 0.0; + for (double value : values) { + naive += value * value; + } + naive = (naive - values.length * stats.mean() * stats.mean()) / (values.length - 1); + + assertEquals(30.0, stats.sampleVariance(), 1e-6); + assertTrue(Math.abs(naive - 30.0) > 1.0, "the naive formula is expected to be far off, but returned " + naive); + } + + @ParameterizedTest + @ValueSource(ints = {2, 3, 10, 1_000}) + void agreesWithATwoPassComputation(int sampleCount) { + Random random = new Random(4242L + sampleCount); + double[] values = new double[sampleCount]; + for (int i = 0; i < sampleCount; i++) { + values[i] = random.nextGaussian() * 17.0 + 3.0; + } + + WelfordAlgorithm stats = new WelfordAlgorithm(); + stats.addAll(values); + + double expectedVariance = twoPassPopulationVariance(values); + assertEquals(expectedVariance, stats.populationVariance(), 1e-9 * Math.max(1.0, expectedVariance)); + } + + @Test + void removeUndoesAdd() { + WelfordAlgorithm stats = new WelfordAlgorithm(); + stats.addAll(TEXTBOOK_SAMPLE); + stats.add(1000.0); + stats.remove(1000.0); + + assertEquals(8L, stats.count()); + assertEquals(5.0, stats.mean(), 1e-9); + assertEquals(4.0, stats.populationVariance(), 1e-9); + } + + @Test + void removingTheLastSampleEmptiesTheAccumulator() { + WelfordAlgorithm stats = new WelfordAlgorithm(); + stats.add(3.0); + stats.remove(3.0); + assertTrue(stats.isEmpty()); + assertEquals(0.0, stats.sumOfSquaredDeviations()); + } + + @Test + void removeOnAnEmptyAccumulatorFails() { + WelfordAlgorithm stats = new WelfordAlgorithm(); + assertThrows(IllegalStateException.class, () -> stats.remove(1.0)); + } + + @Test + @DisplayName("add plus remove turns the accumulator into a sliding window") + void supportsSlidingWindows() { + int windowSize = 20; + Random random = new Random(1234L); + double[] signal = new double[500]; + for (int i = 0; i < signal.length; i++) { + signal[i] = random.nextGaussian() * 5.0 + 100.0; + } + + WelfordAlgorithm window = new WelfordAlgorithm(); + for (int i = 0; i < signal.length; i++) { + window.add(signal[i]); + if (window.count() > windowSize) { + window.remove(signal[i - windowSize]); + } + if (i >= windowSize) { + double[] expectedWindow = new double[windowSize]; + System.arraycopy(signal, i - windowSize + 1, expectedWindow, 0, windowSize); + + WelfordAlgorithm reference = new WelfordAlgorithm(); + reference.addAll(expectedWindow); + assertEquals(windowSize, window.count()); + assertEquals(reference.mean(), window.mean(), 1e-9); + assertEquals(reference.populationVariance(), window.populationVariance(), 1e-8); + } + } + } + + @Test + void mergeCombinesPartialSummaries() { + Random random = new Random(20240517L); + double[] values = new double[1_000]; + for (int i = 0; i < values.length; i++) { + values[i] = random.nextGaussian(); + } + + WelfordAlgorithm whole = new WelfordAlgorithm(); + WelfordAlgorithm left = new WelfordAlgorithm(); + WelfordAlgorithm right = new WelfordAlgorithm(); + for (int i = 0; i < values.length; i++) { + whole.add(values[i]); + if (i < 337) { + left.add(values[i]); + } else { + right.add(values[i]); + } + } + + WelfordAlgorithm merged = WelfordAlgorithm.merge(left, right); + assertEquals(whole.count(), merged.count()); + assertEquals(whole.mean(), merged.mean(), 1e-12); + assertEquals(whole.sampleVariance(), merged.sampleVariance(), 1e-12); + } + + @Test + void mergeHandlesEmptyOperands() { + WelfordAlgorithm empty = new WelfordAlgorithm(); + WelfordAlgorithm filled = new WelfordAlgorithm(); + filled.addAll(TEXTBOOK_SAMPLE); + + assertTrue(WelfordAlgorithm.merge(empty, empty).isEmpty()); + assertEquals(filled.mean(), WelfordAlgorithm.merge(empty, filled).mean(), 1e-12); + assertEquals(filled.mean(), WelfordAlgorithm.merge(filled, empty).mean(), 1e-12); + assertEquals(filled.sampleVariance(), WelfordAlgorithm.merge(filled, empty).sampleVariance(), 1e-12); + } + + @Test + void clearForgetsEverything() { + WelfordAlgorithm stats = new WelfordAlgorithm(); + stats.addAll(TEXTBOOK_SAMPLE); + stats.clear(); + assertTrue(stats.isEmpty()); + assertTrue(Double.isNaN(stats.mean())); + } + + @ParameterizedTest + @ValueSource(doubles = {Double.NaN, Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY}) + void rejectsNonFiniteSamples(double value) { + WelfordAlgorithm stats = new WelfordAlgorithm(); + assertThrows(IllegalArgumentException.class, () -> stats.add(value)); + stats.add(1.0); + assertThrows(IllegalArgumentException.class, () -> stats.remove(value)); + } + + @Test + void toStringMentionsTheSummary() { + WelfordAlgorithm stats = new WelfordAlgorithm(); + stats.addAll(TEXTBOOK_SAMPLE); + assertTrue(stats.toString().contains("count=8"), stats.toString()); + } + + @Test + @DisplayName("removing a sample far from the mean cannot push the variance below zero") + void removalNeverYieldsANegativeVariance() { + WelfordAlgorithm stats = new WelfordAlgorithm(); + stats.add(1e16); + stats.add(1.0); + stats.remove(1e16); + + assertEquals(1L, stats.count()); + assertTrue(stats.sumOfSquaredDeviations() >= 0.0, "got " + stats.sumOfSquaredDeviations()); + assertTrue(stats.populationVariance() >= 0.0); + } +} From c99b056d71f8793a6f3da31c77773034646bd4a8 Mon Sep 17 00:00:00 2001 From: Oleksandr Klymenko Date: Sat, 12 Sep 2026 16:07:47 +0300 Subject: [PATCH 14/92] feat: add P2QuantileEstimator, one quantile of a stream in constant memory (#7603) The P-square algorithm of Jain and Chlamtac keeps five markers instead of the samples, so a quantile of an unbounded stream costs O(1) time per sample and O(1) memory. Each marker is nudged towards its desired position with a piecewise parabolic prediction, falling back to a linear one whenever the parabola would break the ordering of the heights. The first five samples are kept verbatim, so the estimate is exact until the sixth arrives, and the minimum and maximum stay exact for the whole stream. Signed-off-by: alxkm <19151554+alxkm@users.noreply.github.com> Co-authored-by: alxkm <19151554+alxkm@users.noreply.github.com> --- .../streaming/P2QuantileEstimator.java | 310 ++++++++++++++++++ .../streaming/P2QuantileEstimatorTest.java | 206 ++++++++++++ 2 files changed, 516 insertions(+) create mode 100644 src/main/java/com/thealgorithms/streaming/P2QuantileEstimator.java create mode 100644 src/test/java/com/thealgorithms/streaming/P2QuantileEstimatorTest.java diff --git a/src/main/java/com/thealgorithms/streaming/P2QuantileEstimator.java b/src/main/java/com/thealgorithms/streaming/P2QuantileEstimator.java new file mode 100644 index 000000000000..9fa4bcf701b9 --- /dev/null +++ b/src/main/java/com/thealgorithms/streaming/P2QuantileEstimator.java @@ -0,0 +1,310 @@ +package com.thealgorithms.streaming; + +import java.util.Arrays; + +/** + * The P-square (P²) algorithm of Jain and Chlamtac: it estimates one quantile of a stream + * using five numbers and no memory of the samples themselves. + * + *

Computing an exact quantile requires storing everything seen so far, which is impossible for an + * unbounded stream. P² instead keeps five markers that track the minimum, the quantile + * {@code p/2}, the quantile {@code p} itself, the quantile {@code (1 + p)/2} and the maximum. Each + * marker has a height (its current value) and a position (how many samples are known to be below + * it). Every new sample shifts the positions of the markers it falls below, and each marker is then + * nudged back towards the position it is supposed to occupy. The nudge follows a piecewise + * parabolic prediction fitted through the three neighbouring markers, falling back to a linear one + * whenever the parabola would break the ordering of the heights. + * + *

Accuracy is typically a fraction of a percent in rank for stationary streams and improves as + * more samples arrive. The markers adapt continuously, so a drifting distribution is tracked rather + * than averaged away, but no accuracy bound is guaranteed for adversarial inputs. + * + * + * + * + * + * + * + *
Cost
OperationComplexity
{@link #add(double)}O(1)
{@link #quantile()}O(1)
memoryO(1) - five markers, independent of the stream length
+ * + *

Usage

+ * + *
{@code
+ * P2QuantileEstimator p99 = new P2QuantileEstimator(0.99);
+ * for (double latency : latencies) {
+ *     p99.add(latency);
+ * }
+ * double tail = p99.quantile();
+ * }
+ * + *

The first five samples are stored verbatim, so the estimate is exact until the sixth one + * arrives. This class is not thread-safe. + * + * @see R. Jain, I. Chlamtac, The P-square algorithm (1985) + */ +public final class P2QuantileEstimator { + + private static final int MARKERS = 5; + + private final double probability; + + /** Marker heights, kept in non-decreasing order; also the raw buffer for the first five samples. */ + private final double[] heights = new double[MARKERS]; + + /** One-based rank of each marker, i.e. how many samples are known to sit at or below it. */ + private final int[] positions = new int[MARKERS]; + + /** Position each marker should ideally occupy. */ + private final double[] desiredPositions = new double[MARKERS]; + + /** How much {@link #desiredPositions} grows per sample. */ + private final double[] positionIncrements = new double[MARKERS]; + + private long count; + + /** + * Creates an estimator for a single quantile. + * + * @param probability the quantile to track, strictly between 0 and 1, e.g. {@code 0.5} for the median + * @throws IllegalArgumentException if {@code probability} is outside {@code (0, 1)} + */ + public P2QuantileEstimator(double probability) { + if (!(probability > 0.0) || !(probability < 1.0)) { + throw new IllegalArgumentException("The quantile probability must lie strictly between 0 and 1, but was " + probability); + } + this.probability = probability; + } + + /** + * Incorporates one sample. + * + * @param value the sample to add + * @throws IllegalArgumentException if {@code value} is NaN or infinite + */ + public void add(double value) { + if (!Double.isFinite(value)) { + throw new IllegalArgumentException("Samples must be finite, but was " + value); + } + if (count < MARKERS) { + collectInitialSample(value); + return; + } + + int cell = locate(value); + for (int i = cell + 1; i < MARKERS; i++) { + positions[i]++; + } + for (int i = 0; i < MARKERS; i++) { + desiredPositions[i] += positionIncrements[i]; + } + for (int i = 1; i < MARKERS - 1; i++) { + adjustMarker(i); + } + count++; + } + + /** + * Incorporates every given sample, in order. + * + * @param values the samples to add + * @throws IllegalArgumentException if any value is NaN or infinite + * @throws NullPointerException if {@code values} is {@code null} + */ + public void addAll(double... values) { + for (double value : values) { + add(value); + } + } + + /** + * Returns the current estimate of the tracked quantile. + * + * @return the estimated quantile, exact while fewer than five samples have been seen + * @throws IllegalStateException if no sample has been added yet + */ + public double quantile() { + requireNonEmpty(); + if (count < MARKERS) { + return exactQuantileOfInitialSamples(); + } + return heights[2]; + } + + /** + * Returns the smallest sample seen so far, which P² tracks exactly. + * + * @return the running minimum + * @throws IllegalStateException if no sample has been added yet + */ + public double min() { + requireNonEmpty(); + return count < MARKERS ? Arrays.stream(heights, 0, (int) count).min().orElse(Double.NaN) : heights[0]; + } + + /** + * Returns the largest sample seen so far, which P² tracks exactly. + * + * @return the running maximum + * @throws IllegalStateException if no sample has been added yet + */ + public double max() { + requireNonEmpty(); + return count < MARKERS ? Arrays.stream(heights, 0, (int) count).max().orElse(Double.NaN) : heights[MARKERS - 1]; + } + + /** + * Returns the quantile this estimator was configured for. + * + * @return the probability given at construction time + */ + public double probability() { + return probability; + } + + /** + * Returns the number of samples seen so far. + * + * @return the sample count + */ + public long count() { + return count; + } + + /** + * Tells whether any sample has been added. + * + * @return {@code true} if the estimator holds no samples + */ + public boolean isEmpty() { + return count == 0; + } + + /** + * Forgets every sample. + */ + public void reset() { + count = 0; + Arrays.fill(heights, 0.0); + Arrays.fill(positions, 0); + Arrays.fill(desiredPositions, 0.0); + Arrays.fill(positionIncrements, 0.0); + } + + @Override + public String toString() { + return "P2QuantileEstimator{p=" + probability + ", count=" + count + ", quantile=" + (count == 0 ? Double.NaN : quantile()) + '}'; + } + + /** + * Stores one of the first five samples and, on the fifth, lays out the markers. + */ + private void collectInitialSample(double value) { + heights[(int) count] = value; + count++; + if (count < MARKERS) { + return; + } + Arrays.sort(heights); + // Marker positions are one-based, exactly as in the paper. Only differences of positions are + // ever used, so the origin is arithmetically irrelevant - but the desired positions are grown + // by repeated addition, and starting them one lower would round differently and flip the + // strict comparisons below on the samples where a desired position lands on a whole number. + for (int i = 0; i < MARKERS; i++) { + positions[i] = i + 1; + } + desiredPositions[0] = 1.0; + desiredPositions[1] = 1.0 + 2.0 * probability; + desiredPositions[2] = 1.0 + 4.0 * probability; + desiredPositions[3] = 3.0 + 2.0 * probability; + desiredPositions[4] = 5.0; + positionIncrements[0] = 0.0; + positionIncrements[1] = probability / 2.0; + positionIncrements[2] = probability; + positionIncrements[3] = (1.0 + probability) / 2.0; + positionIncrements[4] = 1.0; + } + + /** + * Finds the cell the sample falls into, stretching the outer markers when it falls outside the + * range seen so far. + * + * @param value the incoming sample + * @return the index of the marker immediately below the sample + */ + private int locate(double value) { + if (value < heights[0]) { + heights[0] = value; + return 0; + } + for (int i = 1; i < MARKERS - 1; i++) { + if (value < heights[i]) { + return i - 1; + } + } + if (value > heights[MARKERS - 1]) { + heights[MARKERS - 1] = value; + } + return MARKERS - 2; + } + + /** + * Moves one inner marker by a single position if it has drifted too far from where it should be. + */ + private void adjustMarker(int i) { + double drift = desiredPositions[i] - positions[i]; + boolean shiftRight = drift >= 1.0 && positions[i + 1] - positions[i] > 1; + boolean shiftLeft = drift <= -1.0 && positions[i - 1] - positions[i] < -1; + if (!shiftRight && !shiftLeft) { + return; + } + + int direction = shiftRight ? 1 : -1; + double candidate = parabolicPrediction(i, direction); + heights[i] = heights[i - 1] < candidate && candidate < heights[i + 1] ? candidate : linearPrediction(i, direction); + positions[i] += direction; + } + + /** + * Piecewise parabolic prediction: fits a parabola through markers {@code i - 1}, {@code i} and + * {@code i + 1} and evaluates it one position away from the current one. + */ + private double parabolicPrediction(int i, int direction) { + double left = positions[i] - positions[i - 1]; + double right = positions[i + 1] - positions[i]; + // Grouped exactly as in the paper. The result then decides, by a strict comparison against the + // neighbouring heights, whether the parabola is used at all, so regrouping the arithmetic would + // flip that decision on knife-edge inputs and make this estimator drift away from the reference. + return heights[i] + direction / (left + right) * ((left + direction) * (heights[i + 1] - heights[i]) / right + (right - direction) * (heights[i] - heights[i - 1]) / left); + } + + /** + * Linear fallback used whenever the parabolic prediction would violate the ordering of the + * marker heights. + */ + private double linearPrediction(int i, int direction) { + int neighbour = i + direction; + return heights[i] + direction * (heights[neighbour] - heights[i]) / (positions[neighbour] - positions[i]); + } + + /** + * Exact quantile of the fewer than five samples buffered so far, by linear interpolation between + * the two order statistics surrounding the requested rank. + */ + private double exactQuantileOfInitialSamples() { + double[] sorted = Arrays.copyOf(heights, (int) count); + Arrays.sort(sorted); + if (sorted.length == 1) { + return sorted[0]; + } + double rank = probability * (sorted.length - 1); + int lower = (int) Math.floor(rank); + int upper = Math.min(lower + 1, sorted.length - 1); + return sorted[lower] + (rank - lower) * (sorted[upper] - sorted[lower]); + } + + private void requireNonEmpty() { + if (count == 0) { + throw new IllegalStateException("The estimator has not seen any sample yet"); + } + } +} diff --git a/src/test/java/com/thealgorithms/streaming/P2QuantileEstimatorTest.java b/src/test/java/com/thealgorithms/streaming/P2QuantileEstimatorTest.java new file mode 100644 index 000000000000..777e00d62d66 --- /dev/null +++ b/src/test/java/com/thealgorithms/streaming/P2QuantileEstimatorTest.java @@ -0,0 +1,206 @@ +package com.thealgorithms.streaming; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.Arrays; +import java.util.Random; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +class P2QuantileEstimatorTest { + + /** + * Exact quantile of a sample, by linear interpolation between the surrounding order statistics. + */ + private static double exactQuantile(double[] sortedValues, double probability) { + double rank = probability * (sortedValues.length - 1); + int lower = (int) Math.floor(rank); + int upper = Math.min(lower + 1, sortedValues.length - 1); + return sortedValues[lower] + (rank - lower) * (sortedValues[upper] - sortedValues[lower]); + } + + private static double[] shuffledUniformSample(int count, long seed) { + Random random = new Random(seed); + double[] values = new double[count]; + for (int i = 0; i < count; i++) { + values[i] = random.nextDouble(); + } + return values; + } + + @ParameterizedTest + @ValueSource(doubles = {0.0, 1.0, -0.1, 1.5, Double.NaN}) + void rejectsInvalidProbabilities(double probability) { + assertThrows(IllegalArgumentException.class, () -> new P2QuantileEstimator(probability)); + } + + @Test + void queriesBeforeTheFirstSampleFail() { + P2QuantileEstimator estimator = new P2QuantileEstimator(0.5); + assertTrue(estimator.isEmpty()); + assertEquals(0L, estimator.count()); + assertEquals(0.5, estimator.probability()); + assertThrows(IllegalStateException.class, estimator::quantile); + assertThrows(IllegalStateException.class, estimator::min); + assertThrows(IllegalStateException.class, estimator::max); + } + + @ParameterizedTest + @ValueSource(doubles = {Double.NaN, Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY}) + void rejectsNonFiniteSamples(double value) { + P2QuantileEstimator estimator = new P2QuantileEstimator(0.5); + assertThrows(IllegalArgumentException.class, () -> estimator.add(value)); + } + + @Test + @DisplayName("the first five samples are answered exactly") + void isExactDuringWarmUp() { + P2QuantileEstimator median = new P2QuantileEstimator(0.5); + median.add(3.0); + assertEquals(3.0, median.quantile()); + median.add(1.0); + assertEquals(2.0, median.quantile(), 1e-12); + median.add(2.0); + assertEquals(2.0, median.quantile(), 1e-12); + median.add(10.0); + assertEquals(2.5, median.quantile(), 1e-12); + assertEquals(1.0, median.min()); + assertEquals(10.0, median.max()); + assertEquals(4L, median.count()); + } + + @Test + void tracksTheExtremesExactly() { + P2QuantileEstimator estimator = new P2QuantileEstimator(0.5); + double[] values = shuffledUniformSample(5_000, 7L); + estimator.addAll(values); + + double[] sorted = values.clone(); + Arrays.sort(sorted); + assertEquals(sorted[0], estimator.min(), 0.0); + assertEquals(sorted[sorted.length - 1], estimator.max(), 0.0); + assertEquals(5_000L, estimator.count()); + } + + @Test + void aConstantStreamHasAConstantQuantile() { + P2QuantileEstimator estimator = new P2QuantileEstimator(0.9); + for (int i = 0; i < 1_000; i++) { + estimator.add(7.0); + } + assertEquals(7.0, estimator.quantile(), 1e-12); + } + + @ParameterizedTest + @ValueSource(doubles = {0.05, 0.25, 0.5, 0.75, 0.9, 0.99}) + @DisplayName("estimates a uniform stream within a percent of the exact quantile") + void approximatesUniformQuantiles(double probability) { + double[] values = shuffledUniformSample(100_000, 20240517L); + P2QuantileEstimator estimator = new P2QuantileEstimator(probability); + estimator.addAll(values); + + double[] sorted = values.clone(); + Arrays.sort(sorted); + assertEquals(exactQuantile(sorted, probability), estimator.quantile(), 0.01); + } + + @Test + @DisplayName("estimates the tail of a skewed stream") + void approximatesTheTailOfAnExponentialStream() { + Random random = new Random(31337L); + double[] values = new double[100_000]; + for (int i = 0; i < values.length; i++) { + values[i] = -Math.log(1.0 - random.nextDouble()) * 10.0; + } + + P2QuantileEstimator estimator = new P2QuantileEstimator(0.95); + estimator.addAll(values); + + double[] sorted = values.clone(); + Arrays.sort(sorted); + double expected = exactQuantile(sorted, 0.95); + assertEquals(expected, estimator.quantile(), 0.05 * expected); + } + + @Test + @DisplayName("stays sane even when the stream arrives already sorted, the worst case for P-square") + void handlesMonotonicInput() { + P2QuantileEstimator estimator = new P2QuantileEstimator(0.5); + for (int i = 1; i <= 10_000; i++) { + estimator.add(i); + } + assertEquals(5_000.0, estimator.quantile(), 500.0); + assertEquals(1.0, estimator.min()); + assertEquals(10_000.0, estimator.max()); + } + + @Test + void estimatesOfDifferentQuantilesStayOrdered() { + double[] values = shuffledUniformSample(50_000, 99L); + P2QuantileEstimator low = new P2QuantileEstimator(0.25); + P2QuantileEstimator middle = new P2QuantileEstimator(0.5); + P2QuantileEstimator high = new P2QuantileEstimator(0.75); + low.addAll(values); + middle.addAll(values); + high.addAll(values); + + assertTrue(low.quantile() < middle.quantile()); + assertTrue(middle.quantile() < high.quantile()); + } + + @Test + void resetForgetsEverything() { + P2QuantileEstimator estimator = new P2QuantileEstimator(0.5); + estimator.addAll(shuffledUniformSample(1_000, 5L)); + estimator.reset(); + + assertTrue(estimator.isEmpty()); + assertThrows(IllegalStateException.class, estimator::quantile); + + estimator.addAll(1.0, 2.0, 3.0); + assertEquals(2.0, estimator.quantile(), 1e-12); + } + + @Test + void toStringMentionsTheEstimate() { + P2QuantileEstimator estimator = new P2QuantileEstimator(0.5); + assertTrue(estimator.toString().contains("count=0"), estimator.toString()); + estimator.addAll(1.0, 2.0, 3.0, 4.0, 5.0, 6.0); + assertFalse(estimator.isEmpty()); + assertTrue(estimator.toString().contains("quantile="), estimator.toString()); + } + + @Test + @DisplayName("violent jumps force the parabolic prediction to fall back to a linear one") + void survivesWildlyJumpingInput() { + P2QuantileEstimator estimator = new P2QuantileEstimator(0.5); + double value = 1.0; + for (int i = 0; i < 5_000; i++) { + value = i % 2 == 0 ? value * 3.0 + 1.0 : 1.0 / (i + 1); + estimator.add(value); + assertTrue(estimator.quantile() >= estimator.min(), "the estimate fell below the minimum"); + assertTrue(estimator.quantile() <= estimator.max(), "the estimate rose above the maximum"); + } + } + + @ParameterizedTest + @ValueSource(doubles = {0.01, 0.5, 0.99}) + @DisplayName("lands exactly on the textbook quantile of a ramp, which pins the marker convention") + void isExactOnARamp(double probability) { + // The markers are numbered from one, as in the paper. That origin is arithmetically irrelevant + // - only differences of positions are ever used - but the desired positions are grown by + // repeated addition, so a different origin rounds differently and flips the strict comparisons + // that pick between the parabolic and the linear prediction. On a ramp, whose quantiles are + // whole numbers, that shows up as an answer off by one. + P2QuantileEstimator estimator = new P2QuantileEstimator(probability); + for (int i = 0; i <= 1_700; i++) { + estimator.add(i); + } + assertEquals(probability * 1_700, estimator.quantile(), 1e-9); + } +} From b6fb8ad0fac794f16e8de4f8bb4a37360034606a Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 15 Sep 2026 08:39:38 +0300 Subject: [PATCH 15/92] chore(deps-dev): bump com.github.spotbugs:spotbugs-maven-plugin from 4.10.4.0 to 4.10.4.1 (#7605) chore(deps-dev): bump com.github.spotbugs:spotbugs-maven-plugin Bumps [com.github.spotbugs:spotbugs-maven-plugin](https://github.com/spotbugs/spotbugs-maven-plugin) from 4.10.4.0 to 4.10.4.1. - [Release notes](https://github.com/spotbugs/spotbugs-maven-plugin/releases) - [Commits](https://github.com/spotbugs/spotbugs-maven-plugin/compare/spotbugs-maven-plugin-4.10.4.0...spotbugs-maven-plugin-4.10.4.1) --- updated-dependencies: - dependency-name: com.github.spotbugs:spotbugs-maven-plugin dependency-version: 4.10.4.1 dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index e7b0649204a8..1c5ccdf0500b 100644 --- a/pom.xml +++ b/pom.xml @@ -119,7 +119,7 @@ com.github.spotbugs spotbugs-maven-plugin - 4.10.4.0 + 4.10.4.1 spotbugs-exclude.xml true From d652955c2198b099e0e0f81de20052e779b293af Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 17 Sep 2026 08:46:01 +0300 Subject: [PATCH 16/92] chore(deps): bump actions/setup-java from 6.0.0 to 6.0.1 in /.github/workflows (#7607) chore(deps): bump actions/setup-java in /.github/workflows Bumps [actions/setup-java](https://github.com/actions/setup-java) from 6.0.0 to 6.0.1. - [Release notes](https://github.com/actions/setup-java/releases) - [Commits](https://github.com/actions/setup-java/compare/v6.0.0...v6.0.1) --- updated-dependencies: - dependency-name: actions/setup-java dependency-version: 6.0.1 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/build.yml | 2 +- .github/workflows/codeql.yml | 2 +- .github/workflows/infer.yml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 6be71195eb1e..9c582fbe0a3d 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -10,7 +10,7 @@ jobs: steps: - uses: actions/checkout@v7 - name: Set up JDK - uses: actions/setup-java@v6.0.0 + uses: actions/setup-java@v6.0.1 with: java-version: 21 distribution: 'temurin' diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 33235609a787..1b81ab064ae3 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -24,7 +24,7 @@ jobs: uses: actions/checkout@v7 - name: Set up JDK - uses: actions/setup-java@v6.0.0 + uses: actions/setup-java@v6.0.1 with: java-version: 21 distribution: 'temurin' diff --git a/.github/workflows/infer.yml b/.github/workflows/infer.yml index 2099dd969567..7b0973996a41 100644 --- a/.github/workflows/infer.yml +++ b/.github/workflows/infer.yml @@ -18,7 +18,7 @@ jobs: - uses: actions/checkout@v7 - name: Set up JDK - uses: actions/setup-java@v6.0.0 + uses: actions/setup-java@v6.0.1 with: java-version: 21 distribution: 'temurin' From b3a96d22717fecb8a0f018f55640585a3b561305 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 17 Sep 2026 09:23:10 +0300 Subject: [PATCH 17/92] chore(deps): bump github/codeql-action from 4.37.9 to 4.38.0 in /.github/workflows (#7608) chore(deps): bump github/codeql-action in /.github/workflows Bumps [github/codeql-action](https://github.com/github/codeql-action) from 4.37.9 to 4.38.0. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](https://github.com/github/codeql-action/compare/v4.37.9...v4.38.0) --- updated-dependencies: - dependency-name: github/codeql-action dependency-version: 4.38.0 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: a <19151554+alxkm@users.noreply.github.com> --- .github/workflows/codeql.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 1b81ab064ae3..1eb8e9f2865e 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -30,7 +30,7 @@ jobs: distribution: 'temurin' - name: Initialize CodeQL - uses: github/codeql-action/init@v4.37.9 + uses: github/codeql-action/init@v4.38.0 with: languages: 'java-kotlin' @@ -38,7 +38,7 @@ jobs: run: mvn --batch-mode --update-snapshots verify - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4.37.9 + uses: github/codeql-action/analyze@v4.38.0 with: category: "/language:java-kotlin" @@ -55,12 +55,12 @@ jobs: uses: actions/checkout@v7 - name: Initialize CodeQL - uses: github/codeql-action/init@v4.37.9 + uses: github/codeql-action/init@v4.38.0 with: languages: 'actions' - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4.37.9 + uses: github/codeql-action/analyze@v4.38.0 with: category: "/language:actions" ... From 734a7a41bc6a5a38583492d6060e5e3e7746c7bd Mon Sep 17 00:00:00 2001 From: Arsam Date: Thu, 17 Sep 2026 11:57:47 +0330 Subject: [PATCH 18/92] Fix integer overflow in AbsoluteValue.getAbsValue for Integer.MIN_VALUE (#7604) --- src/main/java/com/thealgorithms/maths/AbsoluteValue.java | 2 +- src/test/java/com/thealgorithms/maths/AbsoluteValueTest.java | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/main/java/com/thealgorithms/maths/AbsoluteValue.java b/src/main/java/com/thealgorithms/maths/AbsoluteValue.java index 114eb71b1015..acc7302eb451 100644 --- a/src/main/java/com/thealgorithms/maths/AbsoluteValue.java +++ b/src/main/java/com/thealgorithms/maths/AbsoluteValue.java @@ -10,7 +10,7 @@ private AbsoluteValue() { * @param number The number to be transformed * @return The absolute value of the {@code number} */ - public static int getAbsValue(int number) { + public static long getAbsValue(long number) { return Math.abs(number); } } diff --git a/src/test/java/com/thealgorithms/maths/AbsoluteValueTest.java b/src/test/java/com/thealgorithms/maths/AbsoluteValueTest.java index 907d5cb45ef9..308f38ad9bd5 100644 --- a/src/test/java/com/thealgorithms/maths/AbsoluteValueTest.java +++ b/src/test/java/com/thealgorithms/maths/AbsoluteValueTest.java @@ -34,6 +34,6 @@ void testNegativeNumbers() { @Test void testMinIntEdgeCase() { - assertEquals(Integer.MIN_VALUE, AbsoluteValue.getAbsValue(Integer.MIN_VALUE)); + assertEquals(2147483648L, AbsoluteValue.getAbsValue(Integer.MIN_VALUE)); } } From a0c3eb5e615ca8f85f7bd21acbeba225d8f1a0d9 Mon Sep 17 00:00:00 2001 From: Oleksandr Klymenko Date: Thu, 17 Sep 2026 11:33:46 +0300 Subject: [PATCH 19/92] feat: add Adwin, an adaptive window that cuts itself when the stream changes (#7606) ADWIN keeps a window of recent values and, after every sample, looks for a split into an old and a recent part whose means differ by more than a variance sensitive Hoeffding bound. When it finds one the old part is dropped, so the window grows while the stream is stationary and collapses as soon as it moves, and its length becomes an estimate of how long the current regime has lasted rather than a parameter to tune. The window is stored as an exponential histogram, buckets of 1, 2, 4 ... elements with at most five of each size, so a window of n elements needs O(log n) buckets and cuts are tried only at bucket boundaries. The bucket merge carries the sum and the variance exactly, which the tests check against a direct computation over 2000 samples. Signed-off-by: alxkm <19151554+alxkm@users.noreply.github.com> Co-authored-by: alxkm <19151554+alxkm@users.noreply.github.com> --- .../com/thealgorithms/streaming/Adwin.java | 354 ++++++++++++++++++ .../thealgorithms/streaming/AdwinTest.java | 212 +++++++++++ 2 files changed, 566 insertions(+) create mode 100644 src/main/java/com/thealgorithms/streaming/Adwin.java create mode 100644 src/test/java/com/thealgorithms/streaming/AdwinTest.java diff --git a/src/main/java/com/thealgorithms/streaming/Adwin.java b/src/main/java/com/thealgorithms/streaming/Adwin.java new file mode 100644 index 000000000000..dc95d98461b6 --- /dev/null +++ b/src/main/java/com/thealgorithms/streaming/Adwin.java @@ -0,0 +1,354 @@ +package com.thealgorithms.streaming; + +/** + * ADWIN, adaptive windowing, after Bifet and Gavalda: an average over a window whose length is + * not a parameter but a result. + * + *

Every windowed estimator forces the same bad choice. A long window is accurate while nothing + * changes and hopelessly slow once something does; a short one reacts immediately and is noisy the + * rest of the time. ADWIN refuses the choice: it keeps a window of recent values and, after every + * sample, looks for a way to split it into an old part and a recent part whose means are too far + * apart to be explained by chance. When it finds one, the old part is dropped. The window therefore + * grows on its own while the stream is stationary and collapses as soon as the stream moves, and the + * length it settles at is an estimate of how long the current regime has been running. + * + *

"Too far apart" is a variance sensitive Hoeffding bound. For a cut into sub-windows of + * {@code n0} and {@code n1} elements, with {@code v} the variance of the whole window: + * + *

+ * m       = 1 / (n0 - minLength + 1) + 1 / (n1 - minLength + 1)
+ * d       = ln( 2 * ln(width) / delta )
+ * epsilon = sqrt(2 * m * v * d) + 2/3 * d * m
+ * cut when |mean0 - mean1| > epsilon
+ * 
+ * + *

The {@code delta} parameter is a confidence level: the probability of cutting a window that + * never changed is bounded by it, which is the guarantee that makes the window length trustworthy. + * Smaller values make the detector more conservative and slower. + * + *

Keeping every sample would cost O(n) memory, so the window is stored as an exponential + * histogram: buckets of 1, 2, 4, 8 ... elements, at most {@code MAX_BUCKETS} of each size, each + * holding the sum and the variance of the elements it covers. That is O(log n) buckets for a window + * of n elements, and cuts are only tried at bucket boundaries, which is what keeps a sample O(log n) + * instead of O(n) while costing only a bounded loss of resolution. + * + *

Usage

+ * + *
{@code
+ * Adwin window = new Adwin(0.002);
+ * for (double sample : stream) {
+ *     if (window.accept(sample)) {
+ *         alert(window.estimate(), window.width());
+ *     }
+ * }
+ * }
+ * + *

This class is not thread-safe. + * + * @see CusumDetector + * @see Concept drift, the problem ADWIN was written for; the algorithm is due to A. Bifet and R. Gavalda, Learning from Time-Changing Data with Adaptive Windowing, SDM 2007 + */ +public final class Adwin { + + /** Confidence level used when none is given. */ + public static final double DEFAULT_DELTA = 0.002; + + /** How many buckets of the same size the histogram holds before merging the two oldest. */ + public static final int MAX_BUCKETS = 5; + + private static final int MIN_SUBWINDOW = 5; + private static final long MIN_WIDTH_FOR_DETECTION = 2L * MIN_SUBWINDOW; + + private final double delta; + + private Row newest; + private Row oldest; + + private long width; + private double total; + private double variance; + private int bucketCount; + private long count; + private long changeCount; + + /** + * Creates a window with the customary confidence level of {@code 0.002}. + */ + public Adwin() { + this(DEFAULT_DELTA); + } + + /** + * Creates a window. + * + * @param delta the confidence level, in {@code (0, 1)}; smaller values cut less eagerly + * @throws IllegalArgumentException if {@code delta} is outside {@code (0, 1)} + */ + public Adwin(double delta) { + if (!(delta > 0.0) || !(delta < 1.0)) { + throw new IllegalArgumentException("The delta must lie in (0, 1), but was " + delta); + } + this.delta = delta; + start(); + } + + /** + * Feeds one sample into the window. + * + * @param value the incoming sample + * @return {@code true} if the window was cut, that is if the stream changed + * @throws IllegalArgumentException if {@code value} is NaN or infinite + */ + public boolean accept(double value) { + if (!Double.isFinite(value)) { + throw new IllegalArgumentException("Samples must be finite, but was " + value); + } + count++; + insert(value); + return detectChange(); + } + + /** + * Runs the window over a whole signal. + * + * @param signal the samples to inspect + * @return a new array of the same length saying for every sample whether it cut the window + * @throws IllegalArgumentException if any sample is NaN or infinite + * @throws NullPointerException if {@code signal} is {@code null} + */ + public boolean[] scan(double[] signal) { + boolean[] cuts = new boolean[signal.length]; + for (int i = 0; i < signal.length; i++) { + cuts[i] = accept(signal[i]); + } + return cuts; + } + + /** + * Returns the current estimate of the level of the stream. + * + * @return the mean of the window, {@code 0} while the window is empty + */ + public double estimate() { + return width == 0 ? 0.0 : total / width; + } + + /** + * Returns the length of the window, which is how many recent samples the estimate rests on. + * + * @return the window width + */ + public long width() { + return width; + } + + /** + * Returns the variance of the samples inside the window. + * + * @return the window variance, {@code 0} while the window holds fewer than two samples + */ + public double variance() { + return width < 2 ? 0.0 : variance / width; + } + + /** + * Returns how many buckets the histogram holds, which grows like the logarithm of the width. + * + * @return the bucket count + */ + public int bucketCount() { + return bucketCount; + } + + /** + * Returns how many samples have been inspected since the last reset. + * + * @return the sample count + */ + public long count() { + return count; + } + + /** + * Returns how many times the window has been cut since the last reset. + * + * @return the number of detected changes + */ + public long changeCount() { + return changeCount; + } + + /** + * Returns the configured confidence level. + * + * @return the delta given at construction time + */ + public double delta() { + return delta; + } + + /** + * Empties the window. + */ + public void reset() { + start(); + count = 0; + changeCount = 0; + } + + @Override + public String toString() { + return "Adwin{width=" + width + ", estimate=" + estimate() + ", buckets=" + bucketCount + ", changes=" + changeCount + "}"; + } + + private void start() { + newest = new Row(0); + oldest = newest; + width = 0; + total = 0.0; + variance = 0.0; + bucketCount = 0; + } + + private void insert(double value) { + width++; + newest.add(value, 0.0); + bucketCount++; + if (width > 1) { + double deviation = value - total / (width - 1); + variance += (width - 1) * deviation * deviation / width; + } + total += value; + compress(); + } + + /** + * Merges the two oldest buckets of every row that has run out of room into one bucket of the next + * row, which is what keeps the number of buckets logarithmic in the width. + */ + private void compress() { + Row row = newest; + while (row != null && row.size > MAX_BUCKETS) { + if (row.older == null) { + row.older = new Row(row.level + 1); + row.older.newer = row; + oldest = row.older; + } + long size = 1L << row.level; + double firstMean = row.totals[0] / size; + double secondMean = row.totals[1] / size; + double merged = size * size * (firstMean - secondMean) * (firstMean - secondMean) / (size + size); + row.older.add(row.totals[0] + row.totals[1], row.variances[0] + row.variances[1] + merged); + row.removeOldest(2); + bucketCount--; + row = row.older; + } + } + + /** + * Tries every cut the histogram allows, from the oldest boundary inwards, and drops the oldest + * bucket whenever a cut is significant. Repeats until no cut is left. + * + * @return whether anything was dropped + */ + private boolean detectChange() { + boolean changed = false; + boolean searching = true; + + while (searching && width >= MIN_WIDTH_FOR_DETECTION) { + searching = false; + long oldWidth = 0; + double oldTotal = 0.0; + + outer: + for (Row row = oldest; row != null; row = row.newer) { + for (int bucket = 0; bucket < row.size; bucket++) { + if (row.newer == null && bucket == row.size - 1) { + break outer; + } + oldWidth += 1L << row.level; + oldTotal += row.totals[bucket]; + long recentWidth = width - oldWidth; + double recentTotal = total - oldTotal; + if (recentWidth < MIN_SUBWINDOW) { + break outer; + } + if (oldWidth >= MIN_SUBWINDOW && isSignificant(oldWidth, recentWidth, oldTotal / oldWidth - recentTotal / recentWidth)) { + changed = true; + searching = true; + changeCount++; + dropOldestBucket(); + break outer; + } + } + } + } + return changed; + } + + private boolean isSignificant(long oldWidth, long recentWidth, double difference) { + double harmonic = 1.0 / (oldWidth - MIN_SUBWINDOW + 1) + 1.0 / (recentWidth - MIN_SUBWINDOW + 1); + double confidence = Math.log(2.0 * Math.log(width) / delta); + double windowVariance = variance / width; + double epsilon = Math.sqrt(2.0 * harmonic * windowVariance * confidence) + 2.0 / 3.0 * confidence * harmonic; + return Math.abs(difference) > epsilon; + } + + private void dropOldestBucket() { + Row row = oldest; + long size = 1L << row.level; + double bucketTotal = row.totals[0]; + + width -= size; + total -= bucketTotal; + if (width > 0) { + double bucketMean = bucketTotal / size; + double difference = bucketMean - total / width; + variance -= row.variances[0] + size * width * difference * difference / (size + width); + } else { + variance = 0.0; + } + if (variance < 0.0) { + variance = 0.0; + } + + row.removeOldest(1); + bucketCount--; + if (row.size == 0 && row.newer != null) { + oldest = row.newer; + oldest.older = null; + } + } + + /** + * One row of the exponential histogram: up to {@code MAX_BUCKETS + 1} buckets that each cover + * {@code 2^level} samples, the oldest at index zero. + */ + private static final class Row { + + private final int level; + private final double[] totals = new double[MAX_BUCKETS + 1]; + private final double[] variances = new double[MAX_BUCKETS + 1]; + private int size; + private Row older; + private Row newer; + + Row(int level) { + this.level = level; + } + + void add(double total, double variance) { + totals[size] = total; + variances[size] = variance; + size++; + } + + void removeOldest(int buckets) { + for (int i = buckets; i < size; i++) { + totals[i - buckets] = totals[i]; + variances[i - buckets] = variances[i]; + } + size -= buckets; + } + } +} diff --git a/src/test/java/com/thealgorithms/streaming/AdwinTest.java b/src/test/java/com/thealgorithms/streaming/AdwinTest.java new file mode 100644 index 000000000000..0208f32cdaaf --- /dev/null +++ b/src/test/java/com/thealgorithms/streaming/AdwinTest.java @@ -0,0 +1,212 @@ +package com.thealgorithms.streaming; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.Random; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +class AdwinTest { + + private static double mean(double[] values) { + double sum = 0.0; + for (double value : values) { + sum += value; + } + return sum / values.length; + } + + private static double variance(double[] values) { + double mean = mean(values); + double sum = 0.0; + for (double value : values) { + sum += (value - mean) * (value - mean); + } + return sum / values.length; + } + + @ParameterizedTest + @ValueSource(doubles = {0.0, 1.0, -0.5, 2.0, Double.NaN}) + void rejectsInvalidDeltas(double delta) { + assertThrows(IllegalArgumentException.class, () -> new Adwin(delta)); + } + + @ParameterizedTest + @ValueSource(doubles = {Double.NaN, Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY}) + void rejectsNonFiniteSamples(double value) { + Adwin window = new Adwin(); + assertThrows(IllegalArgumentException.class, () -> window.accept(value)); + } + + @Test + void startsEmpty() { + Adwin window = new Adwin(); + + assertEquals(0, window.width()); + assertEquals(0.0, window.estimate()); + assertEquals(0.0, window.variance()); + assertEquals(0, window.bucketCount()); + assertEquals(0, window.changeCount()); + assertEquals(0.002, window.delta()); + } + + @Test + @DisplayName("a constant stream is never cut and the window holds all of it") + void keepsEverythingOnAConstantStream() { + Adwin window = new Adwin(); + + for (int i = 0; i < 1000; i++) { + assertFalse(window.accept(3.0)); + } + + assertEquals(1000, window.width()); + assertEquals(1000, window.count()); + assertEquals(3.0, window.estimate()); + assertEquals(0.0, window.variance()); + assertEquals(0, window.changeCount()); + } + + @Test + @DisplayName("the histogram reproduces the mean and the variance of the window exactly") + void agreesWithADirectComputation() { + Adwin window = new Adwin(); + Random random = new Random(11L); + double[] data = new double[2000]; + + for (int i = 0; i < data.length; i++) { + data[i] = random.nextGaussian(); + assertFalse(window.accept(data[i]), "stationary noise must not be cut, sample " + i); + } + + assertEquals(data.length, window.width()); + assertEquals(mean(data), window.estimate(), 1e-9); + assertEquals(variance(data), window.variance(), 1e-9); + } + + @Test + @DisplayName("a step in the level cuts the window quickly") + void findsAStep() { + Adwin window = new Adwin(); + Random random = new Random(5L); + + int firstCut = -1; + for (int i = 0; i < 1200; i++) { + double sample = 0.1 * random.nextGaussian() + (i < 1000 ? 0.0 : 1.0); + boolean cut = window.accept(sample); + if (cut && firstCut < 0) { + firstCut = i; + } + } + + assertTrue(firstCut >= 1000, "the window must not be cut before the step, cut at " + firstCut); + assertTrue(firstCut < 1050, "the step should be found quickly, cut at " + firstCut); + assertEquals(200, window.width(), "the window should hold exactly the samples after the step"); + assertEquals(1.0, window.estimate(), 0.05); + } + + @Test + @DisplayName("the window follows a level that changes several times") + void tracksSeveralRegimes() { + Adwin window = new Adwin(); + Random random = new Random(23L); + + double[] levels = {0.0, 5.0, -3.0, 10.0}; + for (double level : levels) { + for (int i = 0; i < 400; i++) { + window.accept(level + 0.2 * random.nextGaussian()); + } + assertEquals(level, window.estimate(), 0.1, "the estimate should have caught up with " + level); + } + + assertTrue(window.changeCount() > 0); + } + + @Test + @DisplayName("the window never holds more than the stream") + void theWidthNeverExceedsTheCount() { + Adwin window = new Adwin(); + Random random = new Random(31L); + + for (int i = 0; i < 500; i++) { + window.accept(random.nextGaussian() + i / 100.0); + assertTrue(window.width() <= window.count()); + assertTrue(window.width() >= 1); + } + } + + @Test + @DisplayName("the number of buckets grows like the logarithm of the width") + void keepsALogarithmicNumberOfBuckets() { + Adwin window = new Adwin(); + for (int i = 0; i < 5000; i++) { + window.accept(1.0); + } + + int levels = 64 - Long.numberOfLeadingZeros(window.width()); + int bound = (Adwin.MAX_BUCKETS + 1) * (levels + 1); + + assertEquals(5000, window.width()); + assertTrue(window.bucketCount() <= bound, "held " + window.bucketCount() + " buckets, bound was " + bound); + } + + @Test + @DisplayName("a smaller delta cuts less eagerly") + void deltaControlsHowEagerlyTheWindowIsCut() { + Adwin eager = new Adwin(0.5); + Adwin careful = new Adwin(1e-9); + Random random = new Random(41L); + + for (int i = 0; i < 600; i++) { + double sample = random.nextGaussian() + (i < 300 ? 0.0 : 0.3); + eager.accept(sample); + careful.accept(sample); + } + + assertTrue(eager.changeCount() >= careful.changeCount(), "eager cut " + eager.changeCount() + ", careful cut " + careful.changeCount()); + } + + @Test + void scanReportsOneVerdictPerSample() { + Adwin window = new Adwin(); + + boolean[] cuts = window.scan(new double[] {1.0, 1.0, 1.0, 1.0}); + + assertEquals(4, cuts.length); + assertEquals(4, window.count()); + } + + @Test + void resetEmptiesTheWindow() { + Adwin window = new Adwin(); + Random random = new Random(3L); + for (int i = 0; i < 300; i++) { + window.accept(random.nextGaussian()); + } + + window.reset(); + + assertEquals(0, window.width()); + assertEquals(0, window.count()); + assertEquals(0, window.changeCount()); + assertEquals(0, window.bucketCount()); + assertEquals(0.0, window.estimate()); + assertFalse(window.accept(1.0)); + assertEquals(1.0, window.estimate()); + } + + @Test + void toStringMentionsTheState() { + Adwin window = new Adwin(); + window.accept(2.0); + + String text = window.toString(); + + assertTrue(text.contains("Adwin")); + assertTrue(text.contains("width=1")); + } +} From 6bdb1acc2fe643834204abf835a53b915f05c91f Mon Sep 17 00:00:00 2001 From: Alikhan Turugeldiyev Date: Sat, 19 Sep 2026 16:58:37 +0500 Subject: [PATCH 20/92] =?UTF-8?q?Sigmoid=20Activation=20function=20impleme?= =?UTF-8?q?ntation=20with=20simplified=20batch=20calc=E2=80=A6=20(#7609)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Sigmoid Activation function implementation with simplified batch calculation * clang formatted * braces * private constructor added * final + clang-format * Update src/main/java/com/thealgorithms/maths/SigmoidActivation.java Co-authored-by: Oleksandr Klymenko * Update src/main/java/com/thealgorithms/maths/SigmoidActivation.java Co-authored-by: a <19151554+alxkm@users.noreply.github.com> --------- Co-authored-by: a <19151554+alxkm@users.noreply.github.com> --- .../maths/SigmoidActivation.java | 74 +++++++++++++++++++ .../maths/SigmoidActivationTest.java | 68 +++++++++++++++++ 2 files changed, 142 insertions(+) create mode 100644 src/main/java/com/thealgorithms/maths/SigmoidActivation.java create mode 100644 src/test/java/com/thealgorithms/maths/SigmoidActivationTest.java diff --git a/src/main/java/com/thealgorithms/maths/SigmoidActivation.java b/src/main/java/com/thealgorithms/maths/SigmoidActivation.java new file mode 100644 index 000000000000..aa12886e171b --- /dev/null +++ b/src/main/java/com/thealgorithms/maths/SigmoidActivation.java @@ -0,0 +1,74 @@ +package com.thealgorithms.maths; + +/** + * Implementation of the Sigmoid Activation function. + * Sigmoid function is used as an activation function in machine learning and neural networks + * for modeling binary classification problems, smoothing outputs, and introducing non-linearity + * into models. + * + * @author Alikhan Turugeldiyev + */ + +public final class SigmoidActivation { + + private SigmoidActivation() { + } + + /** + * @summary Maps any real-valued number into a value between 0 and 1 + * @param x In machine learning, x could be a weighted sum of inputs in a neural network neuron or a raw score in logistic regression. + * @return The output (range) of the sigmoid function is always strictly between 0 and 1. + */ + public static double activate(double x) { + // If the number x is NaN then, returning NaN to saving from unexpected output. + if (Double.isNaN(x)) { + return Double.NaN; + } + // Saving from unnecessary and heavy calculations. + // lim x->-inf sigmoid(x) will return number very close to 0 + if (x < -745) { + return 0.0; + } + // lim x->inf sigmoid(x) will return number very close to 1 + if (x > 745) { + return 1.0; + } + // sigmoid function's formula + return 1.0 / (1 + Math.exp((-1) * x)); + } + + public static double[][] activate(double[][] x) { + // apply calculation to every value in batch. + double[][] activatedNumbers = new double[x.length][]; + for (int i = 0; i < x.length; i++) { + activatedNumbers[i] = new double[x[i].length]; + for (int j = 0; j < x[i].length; j++) { + activatedNumbers[i][j] = activate(x[i][j]); + } + } + return activatedNumbers; + } + + /** + * @summary Calculates gradients for mapped values. By the chain rule, you can calculate error. + * @param y Activated by sigmoid function value. + * @return The output is a gradient of the activated value. + */ + public static double grad(double y) { + // sigmoid function derivative is reducing to this value. + // sigmoid'(x) = sigmoid(x) * (1-sigmoid(x)) + return y * (1 - y); + } + + public static double[][] grad(double[][] y) { + // apply calculation to every value in batch. + double[][] grads = new double[y.length][]; + for (int i = 0; i < y.length; i++) { + grads[i] = new double[y[i].length]; + for (int j = 0; j < y[i].length; j++) { + grads[i][j] = grad(y[i][j]); + } + } + return grads; + } +} diff --git a/src/test/java/com/thealgorithms/maths/SigmoidActivationTest.java b/src/test/java/com/thealgorithms/maths/SigmoidActivationTest.java new file mode 100644 index 000000000000..aadf2c7ddc12 --- /dev/null +++ b/src/test/java/com/thealgorithms/maths/SigmoidActivationTest.java @@ -0,0 +1,68 @@ +package com.thealgorithms.maths; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.Arrays; +import org.junit.jupiter.api.Test; + +public class SigmoidActivationTest { + + @Test + public void calculationTest() { + assertEquals(0.5, SigmoidActivation.activate(0), 0.01, "1 case correct"); + assertEquals(0.73, SigmoidActivation.activate(1), 0.01, "2 case correct"); + assertEquals(0.26, SigmoidActivation.activate(-1), 0.01, "3 case correct"); + assertEquals(0.88, SigmoidActivation.activate(2), 0.01, "4 case correct"); + assertEquals(0.11, SigmoidActivation.activate(-2), 0.01, "5 case correct"); + + double[][] xBatch = new double[4][3]; + double[][] expectedX = new double[4][3]; + + for (int i = 0; i < 4; i++) { + for (int j = 0; j < 3; j++) { + xBatch[i][j] = 0; + } + } + + for (int i = 0; i < 4; i++) { + for (int j = 0; j < 3; j++) { + expectedX[i][j] = 0.5; + } + } + + assertTrue(Arrays.deepEquals(expectedX, SigmoidActivation.activate(xBatch)), "batch case correct"); + + assertEquals(0.25, SigmoidActivation.grad(0.5), 0.01, "grad calculation correct"); + + double[][] yBatch = new double[4][3]; + for (int i = 0; i < 4; i++) { + for (int j = 0; j < 3; j++) { + yBatch[i][j] = 0.5; + } + } + + double[][] expectedY = new double[4][3]; + for (int i = 0; i < 4; i++) { + for (int j = 0; j < 3; j++) { + expectedY[i][j] = 0.25; + } + } + assertTrue(Arrays.deepEquals(expectedY, SigmoidActivation.grad(yBatch)), "grad batch case correct"); + } + + @Test + public void willReturnNaN() { + double x = Double.NaN; + + assertTrue(Double.isNaN(SigmoidActivation.activate(x)), "returned NaN"); + } + + @Test + public void extremumNumbersOnActivate() { + double x = 777; + + assertEquals(1.0, SigmoidActivation.activate(x), 0.01, "big number case correct"); + assertEquals(0.0, SigmoidActivation.activate((-1) * x), 0.01, "small number case correct"); + } +} From 87edc628aa92ce6dd7e9a14aece6f19355e7dd3a Mon Sep 17 00:00:00 2001 From: Oleksandr Klymenko Date: Tue, 22 Sep 2026 11:17:56 +0300 Subject: [PATCH 21/92] feat: add GeneralizedEsd, Rosner's test for up to r outliers (#7612) Grubbs' test asks whether the single most extreme point is an outlier and breaks as soon as there are two of them, because each one inflates the standard deviation the other is measured against. The generalized extreme Studentized deviate test removes the most extreme point, recomputes the statistics on what is left and repeats r times, and the answer is the largest step whose statistic exceeds its critical value rather than the first, which is what defeats that masking. The critical values need a Student t quantile, which the repository did not have, so the class computes it from the regularized incomplete beta function through a Lentz continued fraction and a Lanczos log gamma, inverted by bisection. No table is needed. The tests check the critical values and the number of outliers against Rosner's published 54 point example. Signed-off-by: alxkm <19151554+alxkm@users.noreply.github.com> Co-authored-by: alxkm <19151554+alxkm@users.noreply.github.com> --- .../streaming/GeneralizedEsd.java | 334 ++++++++++++++++++ .../streaming/GeneralizedEsdTest.java | 212 +++++++++++ 2 files changed, 546 insertions(+) create mode 100644 src/main/java/com/thealgorithms/streaming/GeneralizedEsd.java create mode 100644 src/test/java/com/thealgorithms/streaming/GeneralizedEsdTest.java diff --git a/src/main/java/com/thealgorithms/streaming/GeneralizedEsd.java b/src/main/java/com/thealgorithms/streaming/GeneralizedEsd.java new file mode 100644 index 000000000000..f4fee3a90a34 --- /dev/null +++ b/src/main/java/com/thealgorithms/streaming/GeneralizedEsd.java @@ -0,0 +1,334 @@ +package com.thealgorithms.streaming; + +import java.util.Arrays; + +/** + * The generalized extreme Studentized deviate test of Rosner: finds up to {@code r} outliers + * in a sample, without being told how many are there. + * + *

Grubbs' test asks whether the single most extreme point is an outlier, and it breaks as soon as + * there are two of them: each one inflates the standard deviation the other is measured against, so + * a pair of outliers can hide one another completely. This is the masking problem, and the + * generalized test is the standard answer to it. It removes the most extreme point, recomputes the + * statistics on what is left, and repeats {@code r} times: + * + *

+ * R_i      = max |x - mean| / sd            over the points that are still in
+ * lambda_i = (n - i) * t / sqrt( (n - i - 1 + t^2)(n - i + 1) )
+ * where t  = the 1 - alpha / (2(n - i + 1)) quantile of a t distribution with n - i - 1 degrees of freedom
+ * 
+ * + *

The number of outliers is the largest {@code i} whose statistic exceeds its critical + * value, not the first one. That is what defeats masking: in a sample with three outliers the first + * two tests can easily fall short while the third one succeeds, and the test then reports all three. + * + *

This is a batch test and it needs the whole sample, which is exactly the trade it makes against + * the streaming detectors in this package: it has a stated significance level and it decides how many + * points are outliers, where {@link HampelFilter} answers one sample at a time against a threshold the + * caller has to choose. Rosner's own recommendation is to use it on at least 25 points, and {@code r} + * is an upper bound that may be set generously, because overstating it costs accuracy only in extreme + * cases. + * + *

Usage

+ * + *
{@code
+ * GeneralizedEsd test = new GeneralizedEsd(0.05);
+ * int[] outliers = test.findOutliers(sample, 10);
+ * }
+ * + *

The test costs O(r * n) time and allocates O(n). The t quantile behind the critical value is + * computed from the regularized incomplete beta function, so no table is needed. + * + * @see HampelFilter + * @see Grubbs's test and its generalization + */ +public final class GeneralizedEsd { + + /** Significance level used when none is given. */ + public static final double DEFAULT_SIGNIFICANCE_LEVEL = 0.05; + + private static final int MINIMUM_SAMPLE_SIZE = 3; + private static final double[] LANCZOS = { + 0.99999999999980993, + 676.5203681218851, + -1259.1392167224028, + 771.32342877765313, + -176.61502916214059, + 12.507343278686905, + -0.13857109526572012, + 9.9843695780195716e-6, + 1.5056327351493116e-7, + }; + + private final double significanceLevel; + + /** + * Creates a test at the customary significance level of {@code 0.05}. + */ + public GeneralizedEsd() { + this(DEFAULT_SIGNIFICANCE_LEVEL); + } + + /** + * Creates a test. + * + * @param significanceLevel the probability of declaring an outlier in clean data, in {@code (0, 1)} + * @throws IllegalArgumentException if {@code significanceLevel} is not inside {@code (0, 1)} + */ + public GeneralizedEsd(double significanceLevel) { + if (!(significanceLevel > 0.0) || !(significanceLevel < 1.0)) { + throw new IllegalArgumentException("The significance level must lie in (0, 1), but was " + significanceLevel); + } + this.significanceLevel = significanceLevel; + } + + /** + * Finds the outliers of a sample. + * + * @param sample the data to inspect, left untouched + * @param maxOutliers upper bound on the number of outliers, at least one and at most + * {@code sample.length - 2} + * @return the indices of the outliers in ascending order, empty if the sample looks clean + * @throws IllegalArgumentException if the sample holds fewer than three points or a non-finite + * value, or if {@code maxOutliers} is out of range + * @throws NullPointerException if {@code sample} is {@code null} + */ + public int[] findOutliers(double[] sample, int maxOutliers) { + if (sample.length < MINIMUM_SAMPLE_SIZE) { + throw new IllegalArgumentException("The sample must hold at least " + MINIMUM_SAMPLE_SIZE + " points, but held " + sample.length); + } + if (maxOutliers < 1 || maxOutliers > sample.length - 2) { + throw new IllegalArgumentException("The number of outliers to look for must lie in [1, " + (sample.length - 2) + "], but was " + maxOutliers); + } + for (double value : sample) { + if (!Double.isFinite(value)) { + throw new IllegalArgumentException("Samples must be finite, but was " + value); + } + } + + int size = sample.length; + double[] values = Arrays.copyOf(sample, size); + int[] indices = new int[size]; + for (int i = 0; i < size; i++) { + indices[i] = i; + } + + int[] removed = new int[maxOutliers]; + int outliers = 0; + int remaining = size; + + for (int step = 1; step <= maxOutliers; step++) { + double mean = mean(values, remaining); + double deviation = standardDeviation(values, remaining, mean); + if (deviation == 0.0) { + break; + } + + int worst = indexOfLargestDeviation(values, remaining, mean); + double statistic = Math.abs(values[worst] - mean) / deviation; + removed[step - 1] = indices[worst]; + if (statistic > criticalValue(size, step)) { + outliers = step; + } + + remaining--; + values[worst] = values[remaining]; + indices[worst] = indices[remaining]; + } + + int[] result = Arrays.copyOf(removed, outliers); + Arrays.sort(result); + return result; + } + + /** + * Returns the critical value a statistic has to exceed at one step of the test. + * + * @param sampleSize the size of the whole sample + * @param step which removal this is, counting from one + * @return the critical value, that is {@code lambda_i} + * @throws IllegalArgumentException if {@code sampleSize} is smaller than three, or if {@code step} + * is outside {@code [1, sampleSize - 2]} + */ + public double criticalValue(int sampleSize, int step) { + if (sampleSize < MINIMUM_SAMPLE_SIZE) { + throw new IllegalArgumentException("The sample size must be at least " + MINIMUM_SAMPLE_SIZE + ", but was " + sampleSize); + } + if (step < 1 || step > sampleSize - 2) { + throw new IllegalArgumentException("The step must lie in [1, " + (sampleSize - 2) + "], but was " + step); + } + int size = sampleSize - step + 1; + int degreesOfFreedom = size - 2; + double probability = 1.0 - significanceLevel / (2.0 * size); + double t = studentTQuantile(probability, degreesOfFreedom); + return (size - 1) * t / Math.sqrt((degreesOfFreedom + t * t) * size); + } + + /** + * Returns the significance level of the test. + * + * @return the level given at construction time + */ + public double significanceLevel() { + return significanceLevel; + } + + @Override + public String toString() { + return "GeneralizedEsd{significanceLevel=" + significanceLevel + "}"; + } + + private static double mean(double[] values, int size) { + double sum = 0.0; + for (int i = 0; i < size; i++) { + sum += values[i]; + } + return sum / size; + } + + private static double standardDeviation(double[] values, int size, double mean) { + double sum = 0.0; + for (int i = 0; i < size; i++) { + double deviation = values[i] - mean; + sum += deviation * deviation; + } + return Math.sqrt(sum / (size - 1)); + } + + private static int indexOfLargestDeviation(double[] values, int size, double mean) { + int worst = 0; + double largest = -1.0; + for (int i = 0; i < size; i++) { + double deviation = Math.abs(values[i] - mean); + if (deviation > largest) { + largest = deviation; + worst = i; + } + } + return worst; + } + + /** + * Returns the {@code probability} quantile of a t distribution, found by bisecting its cumulative + * distribution function. + * + * @param probability the probability to invert, in {@code (0, 1)} + * @param degreesOfFreedom the degrees of freedom, at least one + * @return the quantile + */ + private static double studentTQuantile(double probability, int degreesOfFreedom) { + if (probability < 0.5) { + return -studentTQuantile(1.0 - probability, degreesOfFreedom); + } + double low = 0.0; + double high = 1.0; + while (studentTCumulative(high, degreesOfFreedom) < probability && high < 1e12) { + high *= 2.0; + } + for (int i = 0; i < 200; i++) { + double middle = 0.5 * (low + high); + if (studentTCumulative(middle, degreesOfFreedom) < probability) { + low = middle; + } else { + high = middle; + } + } + return 0.5 * (low + high); + } + + /** + * Returns the probability that a t distributed variable stays below {@code t}. + * + * @param t the point to evaluate at + * @param degreesOfFreedom the degrees of freedom, at least one + * @return the cumulative probability + */ + private static double studentTCumulative(double t, int degreesOfFreedom) { + double x = degreesOfFreedom / (degreesOfFreedom + t * t); + double tail = 0.5 * regularizedIncompleteBeta(0.5 * degreesOfFreedom, 0.5, x); + return t >= 0.0 ? 1.0 - tail : tail; + } + + /** + * Returns the regularized incomplete beta function, evaluated with the continued fraction of + * Lentz. + * + * @param a first shape parameter, strictly positive + * @param b second shape parameter, strictly positive + * @param x the point to evaluate at, in {@code [0, 1]} + * @return {@code I_x(a, b)} + */ + private static double regularizedIncompleteBeta(double a, double b, double x) { + if (x <= 0.0) { + return 0.0; + } + if (x >= 1.0) { + return 1.0; + } + double logBeta = logGamma(a) + logGamma(b) - logGamma(a + b); + if (x < (a + 1.0) / (a + b + 2.0)) { + return Math.exp(a * Math.log(x) + b * Math.log1p(-x) - logBeta) * betaContinuedFraction(a, b, x) / a; + } + return 1.0 - Math.exp(b * Math.log1p(-x) + a * Math.log(x) - logBeta) * betaContinuedFraction(b, a, 1.0 - x) / b; + } + + private static double betaContinuedFraction(double a, double b, double x) { + double tiny = 1e-300; + double c = 1.0; + double d = 1.0 - (a + b) * x / (a + 1.0); + if (Math.abs(d) < tiny) { + d = tiny; + } + d = 1.0 / d; + double fraction = d; + + for (int m = 1; m <= 300; m++) { + int even = 2 * m; + double numerator = m * (b - m) * x / ((a + even - 1.0) * (a + even)); + d = 1.0 + numerator * d; + if (Math.abs(d) < tiny) { + d = tiny; + } + c = 1.0 + numerator / c; + if (Math.abs(c) < tiny) { + c = tiny; + } + d = 1.0 / d; + fraction *= d * c; + + numerator = -(a + m) * (a + b + m) * x / ((a + even) * (a + even + 1.0)); + d = 1.0 + numerator * d; + if (Math.abs(d) < tiny) { + d = tiny; + } + c = 1.0 + numerator / c; + if (Math.abs(c) < tiny) { + c = tiny; + } + d = 1.0 / d; + double step = d * c; + fraction *= step; + + if (Math.abs(step - 1.0) < 1e-15) { + break; + } + } + return fraction; + } + + /** + * Returns the logarithm of the gamma function, using the Lanczos approximation. + * + * @param x the point to evaluate at, strictly positive + * @return {@code log(gamma(x))} + */ + private static double logGamma(double x) { + double shifted = x - 1.0; + double series = LANCZOS[0]; + for (int i = 1; i < LANCZOS.length; i++) { + series += LANCZOS[i] / (shifted + i); + } + double t = shifted + 7.5; + return 0.5 * Math.log(2.0 * Math.PI) + (shifted + 0.5) * Math.log(t) - t + Math.log(series); + } +} diff --git a/src/test/java/com/thealgorithms/streaming/GeneralizedEsdTest.java b/src/test/java/com/thealgorithms/streaming/GeneralizedEsdTest.java new file mode 100644 index 000000000000..cd5e1db492d9 --- /dev/null +++ b/src/test/java/com/thealgorithms/streaming/GeneralizedEsdTest.java @@ -0,0 +1,212 @@ +package com.thealgorithms.streaming; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.Arrays; +import java.util.Random; +import org.junit.jupiter.api.Assertions; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +class GeneralizedEsdTest { + + /** + * The sample Rosner published with the test, also used as the worked example in the NIST + * engineering statistics handbook. + */ + private static final double[] ROSNER_SAMPLE = {-0.25, 0.68, 0.94, 1.15, 1.20, 1.26, 1.26, 1.34, 1.38, 1.43, 1.49, 1.49, 1.55, 1.56, 1.58, 1.65, 1.69, 1.70, 1.76, 1.77, 1.81, 1.91, 1.94, 1.96, 1.99, 2.06, 2.09, 2.10, 2.14, 2.15, 2.23, 2.24, 2.26, 2.35, 2.37, 2.40, 2.47, 2.54, 2.62, 2.64, 2.90, + 2.92, 2.92, 2.93, 3.21, 3.26, 3.30, 3.59, 3.68, 4.30, 4.64, 5.34, 5.42, 6.01}; + + private static double[] gaussianSample(int size, long seed) { + Random random = new Random(seed); + double[] sample = new double[size]; + for (int i = 0; i < size; i++) { + sample[i] = 100.0 + 5.0 * random.nextGaussian(); + } + return sample; + } + + @ParameterizedTest + @ValueSource(doubles = {0.0, 1.0, -0.1, 1.5, Double.NaN}) + void rejectsInvalidSignificanceLevels(double level) { + assertThrows(IllegalArgumentException.class, () -> new GeneralizedEsd(level)); + } + + @Test + void rejectsSamplesThatAreTooSmall() { + GeneralizedEsd test = new GeneralizedEsd(); + + assertThrows(IllegalArgumentException.class, () -> test.findOutliers(new double[] {1.0, 2.0}, 1)); + } + + @Test + void rejectsAnOutlierBoundOutOfRange() { + GeneralizedEsd test = new GeneralizedEsd(); + double[] sample = gaussianSample(20, 1L); + + assertThrows(IllegalArgumentException.class, () -> test.findOutliers(sample, 0)); + assertThrows(IllegalArgumentException.class, () -> test.findOutliers(sample, 19)); + } + + @ParameterizedTest + @ValueSource(doubles = {Double.NaN, Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY}) + void rejectsNonFiniteSamples(double value) { + GeneralizedEsd test = new GeneralizedEsd(); + double[] sample = gaussianSample(20, 2L); + sample[7] = value; + + assertThrows(IllegalArgumentException.class, () -> test.findOutliers(sample, 3)); + } + + @Test + void exposesItsConfiguration() { + assertEquals(0.05, new GeneralizedEsd().significanceLevel()); + assertEquals(0.01, new GeneralizedEsd(0.01).significanceLevel()); + } + + @Test + @DisplayName("the critical values match the table published with the test") + void reproducesThePublishedCriticalValues() { + GeneralizedEsd test = new GeneralizedEsd(0.05); + + assertEquals(3.159, test.criticalValue(54, 1), 5e-4); + assertEquals(3.151, test.criticalValue(54, 2), 5e-4); + assertEquals(3.144, test.criticalValue(54, 3), 5e-4); + assertEquals(3.085, test.criticalValue(54, 10), 5e-4); + } + + @Test + @DisplayName("Rosner's own sample of 54 points holds exactly three outliers") + void reproducesTheWorkedExample() { + GeneralizedEsd test = new GeneralizedEsd(0.05); + + int[] outliers = test.findOutliers(ROSNER_SAMPLE, 10); + + assertArrayEqualsSorted(new int[] {51, 52, 53}, outliers); + assertEquals(5.34, ROSNER_SAMPLE[outliers[0]]); + assertEquals(5.42, ROSNER_SAMPLE[outliers[1]]); + assertEquals(6.01, ROSNER_SAMPLE[outliers[2]]); + } + + @Test + @DisplayName("the answer is the last test that succeeds, not the first") + void findsOutliersThatMaskEachOther() { + double[] sample = gaussianSample(40, 0L); + sample[10] = 160.0; + sample[20] = 161.0; + sample[30] = 162.0; + + int[] outliers = new GeneralizedEsd(0.05).findOutliers(sample, 5); + + assertArrayEqualsSorted(new int[] {10, 20, 30}, outliers); + } + + @Test + void findsASingleOutlier() { + double[] sample = gaussianSample(30, 4L); + sample[13] = 200.0; + + int[] outliers = new GeneralizedEsd().findOutliers(sample, 5); + + assertArrayEqualsSorted(new int[] {13}, outliers); + } + + @Test + @DisplayName("clean data holds no outliers") + void findsNothingInCleanData() { + for (long seed = 0; seed < 12; seed++) { + double[] sample = gaussianSample(60, seed); + + int[] outliers = new GeneralizedEsd(0.001).findOutliers(sample, 6); + + assertEquals(0, outliers.length, "seed " + seed + " reported " + Arrays.toString(outliers)); + } + } + + @Test + @DisplayName("the significance level is a rate, not a promise: clean data does report the odd outlier") + void falseAlarmsFollowTheSignificanceLevel() { + int reporting = 0; + for (long seed = 0; seed < 12; seed++) { + if (new GeneralizedEsd(0.05).findOutliers(gaussianSample(60, seed), 6).length > 0) { + reporting++; + } + } + + assertTrue(reporting > 0, "at five percent some clean sample is expected to report something"); + assertTrue(reporting <= 4, "but it must stay rare, " + reporting + " of 12 samples reported"); + } + + @Test + @DisplayName("a sample with no spread at all has no outliers") + void handlesAConstantSample() { + double[] sample = new double[20]; + Arrays.fill(sample, 3.0); + + assertEquals(0, new GeneralizedEsd().findOutliers(sample, 5).length); + } + + @Test + void leavesTheSampleUntouched() { + double[] sample = gaussianSample(30, 5L); + sample[3] = 500.0; + double[] copy = Arrays.copyOf(sample, sample.length); + + new GeneralizedEsd().findOutliers(sample, 4); + + Assertions.assertArrayEquals(copy, sample); + } + + @Test + @DisplayName("a stricter level reports at most as many outliers as a looser one") + void aStricterLevelIsMoreConservative() { + double[] sample = gaussianSample(50, 6L); + sample[5] = 125.0; + sample[6] = 126.0; + + int loose = new GeneralizedEsd(0.10).findOutliers(sample, 8).length; + int strict = new GeneralizedEsd(0.001).findOutliers(sample, 8).length; + + assertTrue(strict <= loose, "strict found " + strict + ", loose found " + loose); + } + + @Test + @DisplayName("the bound on the number of outliers is respected") + void neverReportsMoreThanTheBound() { + double[] sample = gaussianSample(40, 7L); + for (int i = 0; i < 6; i++) { + sample[i] = 300.0 + i; + } + + int[] outliers = new GeneralizedEsd().findOutliers(sample, 2); + + assertTrue(outliers.length <= 2); + } + + @Test + void findsOutliersOnBothSides() { + double[] sample = gaussianSample(40, 8L); + sample[4] = 300.0; + sample[24] = -150.0; + + int[] outliers = new GeneralizedEsd().findOutliers(sample, 4); + + assertArrayEqualsSorted(new int[] {4, 24}, outliers); + } + + @Test + void toStringMentionsTheLevel() { + String text = new GeneralizedEsd(0.05).toString(); + + assertTrue(text.contains("GeneralizedEsd")); + assertTrue(text.contains("0.05")); + } + + private static void assertArrayEqualsSorted(int[] expected, int[] actual) { + Assertions.assertArrayEquals(expected, actual, "expected " + Arrays.toString(expected) + " but got " + Arrays.toString(actual)); + } +} From b2b9d3a5626917283ef9ded669df7f14b30f7c21 Mon Sep 17 00:00:00 2001 From: irenemrtinez <71985908+irenemrtinez@users.noreply.github.com> Date: Tue, 22 Sep 2026 20:06:21 +0200 Subject: [PATCH 22/92] =?UTF-8?q?perf(strings):=20optimize=20LongestCommon?= =?UTF-8?q?Substring=20DP=20memory=20to=20O(N)=20and=20=E2=80=A6=20(#7613)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * perf(strings): optimize LongestCommonSubstring DP memory to O(N) and add tests * fix(strings): fix formatting, unicode characters and update performance test * style(strings): add trailing newline to fix Checkstyle and Clang-format * style(strings): inline lambda in testVeryLargeInputsPerformance for clang-format --------- Co-authored-by: irenemartnez <117649832+irenemartnez@users.noreply.github.com> --- .../strings/LongestCommonSubstring.java | 12 +-- .../strings/LongestCommonSubstringTest.java | 95 +++++++++++++++++++ 2 files changed, 101 insertions(+), 6 deletions(-) diff --git a/src/main/java/com/thealgorithms/strings/LongestCommonSubstring.java b/src/main/java/com/thealgorithms/strings/LongestCommonSubstring.java index b2190316aff2..27aef64ee883 100644 --- a/src/main/java/com/thealgorithms/strings/LongestCommonSubstring.java +++ b/src/main/java/com/thealgorithms/strings/LongestCommonSubstring.java @@ -29,20 +29,20 @@ public static String longestCommonSubstring(final String a, final String b) { return ""; } - int[][] dp = new int[a.length() + 1][b.length() + 1]; + int[] dp = new int[b.length() + 1]; int maxLength = 0; int endIndex = 0; for (int i = 1; i <= a.length(); i++) { - for (int j = 1; j <= b.length(); j++) { + for (int j = b.length(); j >= 1; j--) { if (a.charAt(i - 1) == b.charAt(j - 1)) { - dp[i][j] = dp[i - 1][j - 1] + 1; - if (dp[i][j] > maxLength) { - maxLength = dp[i][j]; + dp[j] = dp[j - 1] + 1; + if (dp[j] > maxLength) { + maxLength = dp[j]; endIndex = i; } } else { - dp[i][j] = 0; + dp[j] = 0; } } } diff --git a/src/test/java/com/thealgorithms/strings/LongestCommonSubstringTest.java b/src/test/java/com/thealgorithms/strings/LongestCommonSubstringTest.java index e54abcf2f1f3..ea62a6b64741 100644 --- a/src/test/java/com/thealgorithms/strings/LongestCommonSubstringTest.java +++ b/src/test/java/com/thealgorithms/strings/LongestCommonSubstringTest.java @@ -2,7 +2,9 @@ // author: Vraj Prajapati @Rosander0 import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTimeoutPreemptively; +import java.time.Duration; import org.junit.jupiter.api.Test; public class LongestCommonSubstringTest { @@ -33,4 +35,97 @@ public void testMultipleMatchesFirstLongest() { // Keeps the first matched longest substring when lengths are tied assertEquals("abc", LongestCommonSubstring.longestCommonSubstring("abcXdef", "abcYdef")); } + + // NEW + + @Test + public void testSpacesAndSpecialCharacters() { + assertEquals(" Hello World! ", LongestCommonSubstring.longestCommonSubstring("123 Hello World! 456", "ABC Hello World! XYZ")); + assertEquals("@#$%^", LongestCommonSubstring.longestCommonSubstring("test@#$%^123", "abc@#$%^xyz")); + } + + @Test + public void testCoincidenceAtBoundaries() { + // Match at the beginning + assertEquals("PREFIX_", LongestCommonSubstring.longestCommonSubstring("PREFIX_12345", "PREFIX_67890")); + // Match at the end + assertEquals("_SUFFIX", LongestCommonSubstring.longestCommonSubstring("12345_SUFFIX", "67890_SUFFIX")); + } + + @Test + public void testRepeatedPatterns() { + assertEquals("anabanana", LongestCommonSubstring.longestCommonSubstring("bananabanana", "anabanana")); + } + + @Test + public void testLargeInputsPerformanceAndTimeout() { + // Generate two 3,000-character strings containing a common substring in the middle + int size = 3000; + StringBuilder sb1 = new StringBuilder(size); + StringBuilder sb2 = new StringBuilder(size); + + for (int i = 0; i < 1000; i++) { + sb1.append('A'); + sb2.append('B'); + } + + String commonPart = "COMMON_LONG_SUBSTRING_TEST_1234567890"; + sb1.append(commonPart); + sb2.append(commonPart); + + for (int i = 0; i < 1500; i++) { + sb1.append('X'); + sb2.append('Y'); + } + + // Verify that the algorithm completes within 2 seconds + assertTimeoutPreemptively(Duration.ofSeconds(2), () -> { + String result = LongestCommonSubstring.longestCommonSubstring(sb1.toString(), sb2.toString()); + assertEquals(commonPart, result); + }); + } + + @Test + public void testVeryLargeInputsPerformance() { + // Generate two very large strings (4,000 characters each) + int size = 4000; + StringBuilder sb1 = new StringBuilder(size); + StringBuilder sb2 = new StringBuilder(size); + + for (int i = 0; i < size; i++) { + sb1.append('A'); + sb2.append('B'); + } + + assertTimeoutPreemptively(Duration.ofSeconds(2), () -> { assertEquals("", LongestCommonSubstring.longestCommonSubstring(sb1.toString(), sb2.toString())); }); + } + + @Test + public void testCaseSensitivityAndUnicode() { + // Case sensitivity test + assertEquals("ABC", LongestCommonSubstring.longestCommonSubstring("ABCdef", "123ABCxyz")); + assertEquals("", LongestCommonSubstring.longestCommonSubstring("abc", "ABC")); + + // Full substring containment + assertEquals("inside", LongestCommonSubstring.longestCommonSubstring("inside", "text_inside_here")); + + // Unicode characters + assertEquals("_áéíóú_", LongestCommonSubstring.longestCommonSubstring("hola_áéíóú_mundo", "test_áéíóú_abc")); + } + + @Test + public void testWhitespaceAndControlCharacters() { + // Test with newlines and tabs + assertEquals("\t\n", LongestCommonSubstring.longestCommonSubstring("start\t\nend", "begin\t\nfinish")); + + // Test with multiple consecutive spaces + assertEquals(" ", LongestCommonSubstring.longestCommonSubstring("a b", "x y")); + } + + @Test + public void testOverlappingSubstrings() { + // Test overlapping matches like "AAAA" in "AAAAA" vs "AAAA" + assertEquals("AAAA", LongestCommonSubstring.longestCommonSubstring("AAAAA", "AAAA")); + assertEquals("ABAB", LongestCommonSubstring.longestCommonSubstring("ABABAB", "CABAB")); + } } From deb3d77af9c66fd62b12ed2dc3898c3e37d41255 Mon Sep 17 00:00:00 2001 From: Oleksandr Klymenko Date: Wed, 23 Sep 2026 00:30:25 +0300 Subject: [PATCH 23/92] feat: add ComplementaryFilter, fusing a drifting rate with a noisy absolute reading (#7614) The classic pair is an accelerometer and a gyroscope measuring the same tilt: one never drifts but picks up every vibration, the other is smooth but has to be integrated, so any bias in it walks away without limit. Their errors live in different parts of the spectrum, and the filter is a high pass on the integrated rate plus a low pass on the absolute reading whose transfer functions sum to unity, so the true signal passes through untouched and no lag is introduced. The single parameter is exposed as a time constant as well, tau = a * dt / (1 - a), which fixes the price of the trade exactly: a rate with a constant bias b leaves a steady state error of tau * b and no more. The tests check that identity, the geometric convergence onto the reference, the noise reduction of sqrt((1 - a) / (1 + a)), and that a ramp is followed without the lag a plain low pass on the reference would add. Signed-off-by: alxkm <19151554+alxkm@users.noreply.github.com> Co-authored-by: alxkm <19151554+alxkm@users.noreply.github.com> --- .../streaming/ComplementaryFilter.java | 239 ++++++++++++++++ .../streaming/ComplementaryFilterTest.java | 258 ++++++++++++++++++ 2 files changed, 497 insertions(+) create mode 100644 src/main/java/com/thealgorithms/streaming/ComplementaryFilter.java create mode 100644 src/test/java/com/thealgorithms/streaming/ComplementaryFilterTest.java diff --git a/src/main/java/com/thealgorithms/streaming/ComplementaryFilter.java b/src/main/java/com/thealgorithms/streaming/ComplementaryFilter.java new file mode 100644 index 000000000000..c4dac5799d79 --- /dev/null +++ b/src/main/java/com/thealgorithms/streaming/ComplementaryFilter.java @@ -0,0 +1,239 @@ +package com.thealgorithms.streaming; + +/** + * The complementary filter: one estimate out of two sensors that are each wrong in a + * different way. + * + *

The classic pair is an accelerometer and a gyroscope measuring the same tilt. The accelerometer + * knows where down is and never drifts, but every vibration of the frame shows up in it. The + * gyroscope is smooth and immune to vibration, but it measures a rate, so using it means integrating, + * and the smallest bias in that rate integrates into an angle that walks away without limit. Neither + * is usable alone; their errors live in different parts of the spectrum, which is exactly the + * situation this filter is for. + * + *

+ * value <- a * (value + rate * dt) + (1 - a) * reference
+ * 
+ * + *

Read as a pair of filters that add up to one, it is a high pass on the integrated rate and a low + * pass on the absolute reading: the drift of the first is cut off below the corner frequency and the + * noise of the second above it. The two transfer functions sum to unity at every frequency, so the + * true signal passes through untouched whatever {@code a} is. That is where the name comes from, and + * it is also why the filter cannot introduce a lag of its own the way a plain low pass on the + * accelerometer would. + * + *

The single parameter is best thought of as a time constant rather than as a number near one: + * + *

+ * tau = a * dt / (1 - a)
+ * 
+ * + *

Below {@code tau} the answer comes from the gyroscope, above it from the accelerometer. That + * also fixes the price of the trade exactly: a gyroscope with a constant bias {@code b} leaves a + * steady state error of {@code tau * b} and no more, where plain integration would have grown without + * limit. Use {@link #ofTimeConstant(double, double)} to set it that way round. + * + *

Against {@link KalmanFilter}: the Kalman filter is the right answer when the noise of both + * sensors is known and worth modelling, and it will beat this one when it is. The complementary + * filter needs no covariance, no model of the process, two multiplications per sample and one number + * of state, and it degrades gracefully when the noise is not what anybody assumed. That is why it is + * what actually runs on small flight controllers. + * + *

Usage

+ * + *
{@code
+ * ComplementaryFilter tilt = ComplementaryFilter.ofTimeConstant(0.5, 0.01);
+ * for (Reading reading : imu) {
+ *     double angle = tilt.accept(reading.gyroscopeRate(), reading.accelerometerAngle(), reading.dt());
+ * }
+ * }
+ * + *

Each sample costs O(1) time and the filter keeps one number of state. This class is not + * thread-safe. + * + * @see KalmanFilter + * @see Complementary filter + */ +public final class ComplementaryFilter { + + /** Weight given to the integrated rate when none is chosen, the usual setting for an IMU. */ + public static final double DEFAULT_COEFFICIENT = 0.98; + + private final double coefficient; + + private double value; + private long count; + + /** + * Creates a filter that leans on the rate with the customary weight of {@code 0.98}. + */ + public ComplementaryFilter() { + this(DEFAULT_COEFFICIENT); + } + + /** + * Creates a filter. + * + * @param coefficient how much of the estimate comes from the integrated rate, in {@code (0, 1)}; + * closer to one trusts the rate for longer, closer to zero follows the reference more quickly + * @throws IllegalArgumentException if {@code coefficient} is outside {@code (0, 1)} + */ + public ComplementaryFilter(double coefficient) { + if (!(coefficient > 0.0) || !(coefficient < 1.0)) { + throw new IllegalArgumentException("The coefficient must lie in (0, 1), but was " + coefficient); + } + this.coefficient = coefficient; + } + + /** + * Creates a filter from the time constant that separates the two sensors, which is usually the + * quantity that is actually known: {@code a = tau / (tau + dt)}. + * + * @param timeConstant how long the rate is trusted before the reference takes over, strictly positive + * @param samplingInterval the interval between samples, strictly positive and in the same unit + * @return a new filter + * @throws IllegalArgumentException if either argument is not finite and strictly positive + */ + public static ComplementaryFilter ofTimeConstant(double timeConstant, double samplingInterval) { + requirePositive(timeConstant, "time constant"); + requirePositive(samplingInterval, "sampling interval"); + return new ComplementaryFilter(timeConstant / (timeConstant + samplingInterval)); + } + + /** + * Feeds one pair of readings taken one unit of time after the previous one. + * + * @param rate the reading of the drifting sensor, a derivative of the estimated quantity + * @param reference the reading of the noisy but drift free sensor, in the unit of the estimate + * @return the updated estimate + * @throws IllegalArgumentException if a reading is NaN or infinite + */ + public double accept(double rate, double reference) { + return accept(rate, reference, 1.0); + } + + /** + * Feeds one pair of readings. + * + * @param rate the reading of the drifting sensor, a derivative of the estimated quantity + * @param reference the reading of the noisy but drift free sensor, in the unit of the estimate + * @param elapsed time since the previous pair, strictly positive + * @return the updated estimate; the very first pair is answered with the reference alone, because + * there is nothing yet to integrate from + * @throws IllegalArgumentException if a reading is NaN or infinite, or if {@code elapsed} is not + * finite and strictly positive + */ + public double accept(double rate, double reference, double elapsed) { + requireFinite(rate, "rate"); + requireFinite(reference, "reference"); + requirePositive(elapsed, "elapsed time"); + + if (count == 0) { + value = reference; + } else { + value = coefficient * (value + rate * elapsed) + (1.0 - coefficient) * reference; + } + count++; + return value; + } + + /** + * Runs the filter over a whole pair of recordings sampled at unit intervals. + * + * @param rates the readings of the drifting sensor + * @param references the readings of the drift free sensor, as many as there are rates + * @return a new array of the same length holding the estimate after every sample + * @throws IllegalArgumentException if the two recordings differ in length or hold a reading that + * is NaN or infinite + * @throws NullPointerException if a recording is {@code null} + */ + public double[] scan(double[] rates, double[] references) { + if (rates.length != references.length) { + throw new IllegalArgumentException("Every rate needs a reference, but there were " + rates.length + " and " + references.length); + } + double[] estimates = new double[rates.length]; + for (int i = 0; i < rates.length; i++) { + estimates[i] = accept(rates[i], references[i]); + } + return estimates; + } + + /** + * Returns the current estimate. + * + * @return the estimate after the last pair of readings, {@code 0} before the first one + */ + public double value() { + return value; + } + + /** + * Returns the weight given to the integrated rate. + * + * @return the coefficient given at construction time + */ + public double coefficient() { + return coefficient; + } + + /** + * Returns the time constant the filter works out to at a given sampling interval, that is + * {@code a * dt / (1 - a)}: the horizon below which the rate decides the answer and above which + * the reference does. + * + * @param samplingInterval the interval between samples, strictly positive + * @return the time constant, in the unit of the interval + * @throws IllegalArgumentException if {@code samplingInterval} is not finite and strictly positive + */ + public double timeConstant(double samplingInterval) { + requirePositive(samplingInterval, "sampling interval"); + return coefficient * samplingInterval / (1.0 - coefficient); + } + + /** + * Returns how many pairs of readings have been filtered since the last reset. + * + * @return the sample count + */ + public long count() { + return count; + } + + /** + * Forgets everything seen so far, so that the next reference seeds the estimate again. + */ + public void reset() { + value = 0.0; + count = 0; + } + + /** + * Restarts the filter from a known estimate, which is what to do after the process has been moved + * by something the sensors could not see. + * + * @param estimate the value to carry on from + * @throws IllegalArgumentException if {@code estimate} is NaN or infinite + */ + public void reset(double estimate) { + requireFinite(estimate, "estimate"); + value = estimate; + count = 1; + } + + @Override + public String toString() { + return "ComplementaryFilter{coefficient=" + coefficient + ", value=" + value + ", samples=" + count + "}"; + } + + private static void requireFinite(double value, String name) { + if (!Double.isFinite(value)) { + throw new IllegalArgumentException("The " + name + " must be finite, but was " + value); + } + } + + private static void requirePositive(double value, String name) { + if (!(value > 0.0) || !Double.isFinite(value)) { + throw new IllegalArgumentException("The " + name + " must be finite and strictly positive, but was " + value); + } + } +} diff --git a/src/test/java/com/thealgorithms/streaming/ComplementaryFilterTest.java b/src/test/java/com/thealgorithms/streaming/ComplementaryFilterTest.java new file mode 100644 index 000000000000..0dc1db1a970d --- /dev/null +++ b/src/test/java/com/thealgorithms/streaming/ComplementaryFilterTest.java @@ -0,0 +1,258 @@ +package com.thealgorithms.streaming; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.Random; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +class ComplementaryFilterTest { + + private static final double COEFFICIENT = 0.98; + private static final double INTERVAL = 0.01; + + private static double standardDeviation(double[] values, double around) { + double sum = 0.0; + for (double value : values) { + sum += (value - around) * (value - around); + } + return Math.sqrt(sum / values.length); + } + + @ParameterizedTest + @ValueSource(doubles = {0.0, 1.0, -0.5, 1.5, Double.NaN, Double.POSITIVE_INFINITY}) + void rejectsACoefficientOutsideTheUnitInterval(double coefficient) { + assertThrows(IllegalArgumentException.class, () -> new ComplementaryFilter(coefficient)); + } + + @ParameterizedTest + @ValueSource(doubles = {0.0, -1.0, Double.NaN, Double.POSITIVE_INFINITY}) + void rejectsInvalidTimeConstants(double value) { + assertThrows(IllegalArgumentException.class, () -> ComplementaryFilter.ofTimeConstant(value, INTERVAL)); + assertThrows(IllegalArgumentException.class, () -> ComplementaryFilter.ofTimeConstant(0.5, value)); + assertThrows(IllegalArgumentException.class, () -> new ComplementaryFilter().timeConstant(value)); + } + + @ParameterizedTest + @ValueSource(doubles = {Double.NaN, Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY}) + void rejectsNonFiniteReadings(double value) { + ComplementaryFilter filter = new ComplementaryFilter(); + + assertThrows(IllegalArgumentException.class, () -> filter.accept(value, 0.0)); + assertThrows(IllegalArgumentException.class, () -> filter.accept(0.0, value)); + assertThrows(IllegalArgumentException.class, () -> filter.reset(value)); + } + + @ParameterizedTest + @ValueSource(doubles = {0.0, -1.0, Double.NaN, Double.POSITIVE_INFINITY}) + void rejectsAnInvalidElapsedTime(double elapsed) { + ComplementaryFilter filter = new ComplementaryFilter(); + + assertThrows(IllegalArgumentException.class, () -> filter.accept(0.0, 0.0, elapsed)); + } + + @Test + void rejectsMismatchedRecordings() { + ComplementaryFilter filter = new ComplementaryFilter(); + + assertThrows(IllegalArgumentException.class, () -> filter.scan(new double[] {1.0, 2.0}, new double[] {1.0})); + } + + @Test + void exposesItsConfiguration() { + ComplementaryFilter filter = new ComplementaryFilter(0.9); + + assertEquals(0.9, filter.coefficient()); + assertEquals(0.98, new ComplementaryFilter().coefficient()); + assertEquals(0, filter.count()); + assertEquals(0.0, filter.value()); + } + + @Test + @DisplayName("the first pair is answered with the reference, because there is nothing to integrate yet") + void seedsWithTheFirstReference() { + ComplementaryFilter filter = new ComplementaryFilter(); + + assertEquals(7.5, filter.accept(100.0, 7.5), 1e-12); + assertEquals(1, filter.count()); + } + + @Test + @DisplayName("the coefficient and the time constant are two ways of saying the same thing") + void theTimeConstantRoundTrips() { + ComplementaryFilter filter = ComplementaryFilter.ofTimeConstant(0.5, INTERVAL); + + assertEquals(0.5, filter.timeConstant(INTERVAL), 1e-12); + assertEquals(0.5 / (0.5 + INTERVAL), filter.coefficient(), 1e-12); + assertEquals(COEFFICIENT * INTERVAL / (1 - COEFFICIENT), new ComplementaryFilter(COEFFICIENT).timeConstant(INTERVAL), 1e-12); + } + + @Test + @DisplayName("with nothing to integrate the estimate decays onto the reference geometrically") + void convergesOnTheReference() { + ComplementaryFilter filter = new ComplementaryFilter(COEFFICIENT); + filter.reset(10.0); + + for (int step = 1; step <= 200; step++) { + double value = filter.accept(0.0, 0.0); + assertEquals(10.0 * Math.pow(COEFFICIENT, step), value, 1e-9, "step " + step); + } + } + + @Test + @DisplayName("a biased rate leaves a bounded error of tau times the bias, where integration alone would run away") + void boundsTheDriftOfTheRate() { + double bias = 0.1; + ComplementaryFilter filter = new ComplementaryFilter(COEFFICIENT); + filter.reset(0.0); + + double integrated = 0.0; + for (int step = 0; step < 5000; step++) { + filter.accept(bias, 0.0, INTERVAL); + integrated += bias * INTERVAL; + } + + double expected = filter.timeConstant(INTERVAL) * bias; + assertEquals(expected, filter.value(), 1e-9, "the steady state error must be exactly tau * bias"); + assertEquals(0.049, filter.value(), 1e-6); + assertEquals(5.0, integrated, 1e-9, "plain integration of the same bias walks away"); + } + + @Test + @DisplayName("noise on the reference is cut down, roughly by the factor the theory promises") + void rejectsNoiseOnTheReference() { + Random random = new Random(7L); + ComplementaryFilter filter = new ComplementaryFilter(COEFFICIENT); + double[] references = new double[20000]; + double[] estimates = new double[references.length]; + + for (int i = 0; i < references.length; i++) { + references[i] = random.nextGaussian(); + estimates[i] = filter.accept(0.0, references[i], INTERVAL); + } + + double referenceSpread = standardDeviation(references, 0.0); + double estimateSpread = standardDeviation(estimates, 0.0); + double promised = Math.sqrt((1 - COEFFICIENT) / (1 + COEFFICIENT)); + + assertEquals(promised, estimateSpread / referenceSpread, 0.02, "the spread should shrink by sqrt((1-a)/(1+a))"); + } + + @Test + @DisplayName("a moving signal is followed without lag, which a low pass on the reference alone cannot do") + void followsARampWithoutLag() { + Random random = new Random(11L); + double slope = 1.0; + ComplementaryFilter filter = new ComplementaryFilter(COEFFICIENT); + + double lowPass = 0.0; + double filterError = 0.0; + double lowPassError = 0.0; + int steps = 4000; + + for (int i = 0; i < steps; i++) { + double truth = slope * i * INTERVAL; + double reference = truth + 0.05 * random.nextGaussian(); + double estimate = filter.accept(slope, reference, INTERVAL); + lowPass = i == 0 ? reference : COEFFICIENT * lowPass + (1 - COEFFICIENT) * reference; + + if (i > steps / 2) { + filterError += Math.abs(estimate - truth); + lowPassError += Math.abs(lowPass - truth); + } + } + + int counted = steps - steps / 2 - 1; + double filterMean = filterError / counted; + double lowPassMean = lowPassError / counted; + + assertTrue(filterMean < 0.02, "the complementary filter should sit on the ramp, it was off by " + filterMean); + assertEquals(filter.timeConstant(INTERVAL) * slope, lowPassMean, 0.02, "the low pass should lag by tau * slope"); + assertTrue(lowPassMean > 10 * filterMean, "the lag should dwarf the error of the complementary filter"); + } + + @Test + @DisplayName("the coefficient decides how quickly the reference takes over") + void theCoefficientDecidesWhichSensorWins() { + ComplementaryFilter trustsTheRate = new ComplementaryFilter(0.999); + ComplementaryFilter trustsTheReference = new ComplementaryFilter(0.001); + trustsTheRate.reset(0.0); + trustsTheReference.reset(0.0); + + for (int i = 0; i < 100; i++) { + trustsTheRate.accept(0.0, 100.0, INTERVAL); + trustsTheReference.accept(0.0, 100.0, INTERVAL); + } + + assertEquals(100.0 * (1 - Math.pow(0.999, 100)), trustsTheRate.value(), 1e-9); + assertTrue(trustsTheRate.value() < 10.0, "a second is a tenth of its time constant, so it has barely moved"); + assertEquals(100.0, trustsTheReference.value(), 1e-9, "the other one is on the reference from the first sample"); + assertTrue(trustsTheRate.timeConstant(INTERVAL) > 1000 * trustsTheReference.timeConstant(INTERVAL)); + } + + @Test + @DisplayName("the elapsed time scales how much of the rate is taken in") + void theElapsedTimeScalesTheIntegration() { + ComplementaryFilter fast = new ComplementaryFilter(COEFFICIENT); + ComplementaryFilter slow = new ComplementaryFilter(COEFFICIENT); + fast.reset(0.0); + slow.reset(0.0); + + fast.accept(2.0, 0.0, 0.5); + slow.accept(2.0, 0.0, 1.0); + + assertEquals(COEFFICIENT * 1.0, fast.value(), 1e-12); + assertEquals(COEFFICIENT * 2.0, slow.value(), 1e-12); + } + + @Test + void scanReportsOneEstimatePerSample() { + ComplementaryFilter filter = new ComplementaryFilter(); + + double[] estimates = filter.scan(new double[] {0.0, 0.0, 0.0}, new double[] {1.0, 1.0, 1.0}); + + assertEquals(3, estimates.length); + assertEquals(3, filter.count()); + assertEquals(1.0, estimates[2], 1e-12); + } + + @Test + void resetForgetsEverything() { + ComplementaryFilter filter = new ComplementaryFilter(); + filter.scan(new double[] {1.0, 1.0}, new double[] {5.0, 5.0}); + + filter.reset(); + + assertEquals(0, filter.count()); + assertEquals(0.0, filter.value()); + assertEquals(9.0, filter.accept(100.0, 9.0), 1e-12, "the next reference seeds the estimate again"); + } + + @Test + @DisplayName("restarting from a known estimate keeps it instead of waiting for the next reference") + void resetCanCarryOnFromAValue() { + ComplementaryFilter filter = new ComplementaryFilter(COEFFICIENT); + + filter.reset(4.0); + + assertEquals(4.0, filter.value(), 1e-12); + assertEquals(1, filter.count()); + assertEquals(COEFFICIENT * 4.0, filter.accept(0.0, 0.0), 1e-12); + } + + @Test + void toStringMentionsTheState() { + ComplementaryFilter filter = new ComplementaryFilter(0.9); + filter.accept(0.0, 2.0); + + String text = filter.toString(); + + assertTrue(text.contains("ComplementaryFilter")); + assertTrue(text.contains("coefficient=0.9")); + assertTrue(text.contains("samples=1")); + } +} From dd8df803f948198b38bdef756fd8d92d6692d396 Mon Sep 17 00:00:00 2001 From: Oleksandr Klymenko Date: Thu, 24 Sep 2026 10:47:23 +0300 Subject: [PATCH 24/92] feat: add ExtendedKalmanFilter, the Kalman filter for a nonlinear model (#7615) The ordinary Kalman filter is optimal only for a linear model, and most things worth tracking are not linear: a bearing is an arctangent of the state, a range a square root of it. The extended filter pushes the state forward through the real functions and the covariance through their Jacobians, evaluated afresh at the current estimate, which keeps the whole machinery and replaces only the step that needed linearity. The covariance correction is written in Joseph form rather than as the shorter (I - K H) P. The two agree in exact arithmetic, but the short one subtracts nearly equal matrices and can leave a covariance that is no longer symmetric or has a negative variance on its diagonal; the Joseph form is a sum of two products of the form A P A' and stays symmetric by construction. The innovation covariance is inverted with the existing matrix.InverseOfMatrix instead of another copy of Gaussian elimination. The Javadoc states what the linearisation costs, namely that the filter is no longer optimal and can diverge on a sharp nonlinearity without the covariance warning about it. Tests: one update of a scalar filter is the textbook half way step, a linear model reproduces the scalar Kalman recursion to 1e-12 over 500 steps, the covariance stays symmetric over 500 steps of a three state model, and a target seen only as a range is tracked through the nonlinear measurement more accurately than inverting each reading on its own. Signed-off-by: alxkm <19151554+alxkm@users.noreply.github.com> Co-authored-by: alxkm <19151554+alxkm@users.noreply.github.com> --- .../streaming/ExtendedKalmanFilter.java | 422 ++++++++++++++++++ .../streaming/ExtendedKalmanFilterTest.java | 273 +++++++++++ 2 files changed, 695 insertions(+) create mode 100644 src/main/java/com/thealgorithms/streaming/ExtendedKalmanFilter.java create mode 100644 src/test/java/com/thealgorithms/streaming/ExtendedKalmanFilterTest.java diff --git a/src/main/java/com/thealgorithms/streaming/ExtendedKalmanFilter.java b/src/main/java/com/thealgorithms/streaming/ExtendedKalmanFilter.java new file mode 100644 index 000000000000..21ef27212a50 --- /dev/null +++ b/src/main/java/com/thealgorithms/streaming/ExtendedKalmanFilter.java @@ -0,0 +1,422 @@ +package com.thealgorithms.streaming; + +import com.thealgorithms.matrix.InverseOfMatrix; +import java.util.Arrays; +import java.util.function.Function; +import java.util.function.UnaryOperator; + +/** + * The extended Kalman filter: the Kalman filter for a process that does not move in straight + * lines. + * + *

The ordinary Kalman filter is optimal, but only for a linear model with Gaussian noise. Most + * things worth tracking are not linear: a bearing is an arctangent of the state, a range is a square + * root of it, an orbit is not a straight line. The extended filter keeps the whole machinery and + * replaces the one step that needs linearity. The state is still pushed forward through the real, + * nonlinear functions, but the covariance is pushed through their Jacobians, evaluated afresh + * at the current estimate: + * + *

+ * predict:  x <- f(x)                      P <- F P F' + Q,   F = df/dx at x
+ * update:   y  = z - h(x)                  S  = H P H' + R,   H = dh/dx at x
+ *           K  = P H' S^-1                 x <- x + K y
+ *                                          P <- (I - K H) P (I - K H)' + K R K'
+ * 
+ * + *

The covariance update is written in Joseph form rather than as the shorter + * {@code (I - K H) P}. The two are equal in exact arithmetic, but the short one subtracts two nearly + * equal matrices and, after a few thousand steps of rounding, can leave a covariance that is no + * longer symmetric or has a negative variance on its diagonal, at which point the filter quietly + * stops being a filter. The Joseph form is a sum of two products of the form {@code A P A'}, so it + * stays symmetric by construction and costs one extra multiplication. + * + *

What the linearisation costs is worth stating plainly: the filter is no longer optimal and no + * longer guaranteed to converge. A Jacobian is a good description of the model only near the point + * it was taken at, so a large error, a sharp nonlinearity or too long a step between updates can all + * make the estimate diverge, and the covariance will not warn about it, because the covariance was + * computed from the same linearisation. When that happens the answer is smaller steps, a better + * initial estimate, or the unscented variant, which samples the nonlinear function instead of + * differentiating it. + * + *

For a one dimensional linear process {@link KalmanFilter} is smaller, faster and exactly + * equivalent; this class earns its place once the state is a vector or the model bends. + * + *

Usage

+ * + *
{@code
+ * // a target moving at constant velocity, watched by a sensor that only measures range
+ * ExtendedKalmanFilter filter = new ExtendedKalmanFilter(new double[] {0.0, 1.0}, identity);
+ * filter.predict(new double[][] {{1.0, dt}, {0.0, 1.0}}, processNoise);
+ * filter.update(new double[] {range},
+ *               state -> new double[] {Math.hypot(state[0], offset)},
+ *               state -> new double[][] {{state[0] / Math.hypot(state[0], offset), 0.0}},
+ *               measurementNoise);
+ * }
+ * + *

A step costs O(n^3) in the size of the state, dominated by the matrix products, plus the + * inversion of the m by m innovation covariance, which is done by + * {@link InverseOfMatrix#invert(double[][])} rather than by another copy of Gaussian elimination. + * This class is not thread-safe. + * + * @see KalmanFilter + * @see Extended Kalman filter + */ +public final class ExtendedKalmanFilter { + + private final int stateSize; + + private double[] state; + private double[][] covariance; + private double[] innovation; + private double[][] gain; + private long predictions; + private long corrections; + + /** + * Creates a filter. + * + * @param initialState the first guess at the state, copied + * @param initialCovariance how uncertain that guess is, a square matrix of the same size, copied + * @throws IllegalArgumentException if the state is empty, if the covariance is not square and of + * the same size, or if either holds a value that is not finite + * @throws NullPointerException if an argument is {@code null} + */ + public ExtendedKalmanFilter(double[] initialState, double[][] initialCovariance) { + if (initialState.length == 0) { + throw new IllegalArgumentException("The state must not be empty"); + } + this.stateSize = initialState.length; + requireVector(initialState, stateSize, "initial state"); + requireMatrix(initialCovariance, stateSize, stateSize, "initial covariance"); + this.state = initialState.clone(); + this.covariance = copy(initialCovariance); + this.innovation = new double[0]; + this.gain = new double[0][0]; + } + + /** + * Pushes the estimate forward through a nonlinear model. + * + * @param transition the model itself, which maps a state to the state one step later + * @param jacobian the derivative of that model, evaluated by the filter at the current estimate + * @param processNoise how much the model is trusted, a square matrix of the size of the state + * @return a copy of the predicted state + * @throws IllegalArgumentException if the model returns the wrong shape or a value that is not + * finite, or if the process noise has the wrong shape + * @throws NullPointerException if an argument is {@code null} + */ + public double[] predict(UnaryOperator transition, Function jacobian, double[][] processNoise) { + requireMatrix(processNoise, stateSize, stateSize, "process noise"); + + double[][] derivative = jacobian.apply(state.clone()); + requireMatrix(derivative, stateSize, stateSize, "transition jacobian"); + double[] predicted = transition.apply(state.clone()); + requireVector(predicted, stateSize, "predicted state"); + + state = predicted; + covariance = add(multiply(multiply(derivative, covariance), transpose(derivative)), processNoise); + predictions++; + return state.clone(); + } + + /** + * Pushes the estimate forward through a linear model, which is the plain Kalman prediction. + * + * @param transition the transition matrix, a square matrix of the size of the state + * @param processNoise how much the model is trusted, a square matrix of the size of the state + * @return a copy of the predicted state + * @throws IllegalArgumentException if either matrix has the wrong shape or holds a value that is + * not finite + * @throws NullPointerException if an argument is {@code null} + */ + public double[] predict(double[][] transition, double[][] processNoise) { + requireMatrix(transition, stateSize, stateSize, "transition"); + return predict(current -> multiply(transition, current), current -> transition, processNoise); + } + + /** + * Folds one nonlinear measurement into the estimate. + * + * @param measurement what the sensor reported + * @param model the measurement model, which maps a state to what the sensor would report + * @param jacobian the derivative of that model, evaluated by the filter at the current estimate + * @param measurementNoise how much the sensor is trusted, a square matrix of the size of the + * measurement + * @return a copy of the corrected state + * @throws IllegalArgumentException if the measurement is empty, if the model returns the wrong + * shape or a value that is not finite, or if the noise has the wrong shape + * @throws ArithmeticException if the innovation covariance cannot be inverted, which means the + * measurement carries no information the filter can use + * @throws NullPointerException if an argument is {@code null} + */ + public double[] update(double[] measurement, Function model, Function jacobian, double[][] measurementNoise) { + if (measurement.length == 0) { + throw new IllegalArgumentException("The measurement must not be empty"); + } + int measurementSize = measurement.length; + requireVector(measurement, measurementSize, "measurement"); + requireMatrix(measurementNoise, measurementSize, measurementSize, "measurement noise"); + + double[] expected = model.apply(state.clone()); + requireVector(expected, measurementSize, "expected measurement"); + double[][] derivative = jacobian.apply(state.clone()); + requireMatrix(derivative, measurementSize, stateSize, "measurement jacobian"); + + double[] residual = new double[measurementSize]; + for (int i = 0; i < measurementSize; i++) { + residual[i] = measurement[i] - expected[i]; + } + + double[][] transposed = transpose(derivative); + double[][] crossCovariance = multiply(covariance, transposed); + double[][] innovationCovariance = add(multiply(derivative, crossCovariance), measurementNoise); + double[][] inverted = InverseOfMatrix.invert(copy(innovationCovariance)); + requireFiniteMatrix(inverted); + + gain = multiply(crossCovariance, inverted); + for (int i = 0; i < stateSize; i++) { + double correction = 0.0; + for (int j = 0; j < measurementSize; j++) { + correction += gain[i][j] * residual[j]; + } + state[i] += correction; + } + + // Joseph form: symmetric by construction, unlike the shorter (I - K H) P + double[][] spread = subtract(identity(stateSize), multiply(gain, derivative)); + covariance = add(multiply(multiply(spread, covariance), transpose(spread)), multiply(multiply(gain, measurementNoise), transpose(gain))); + + innovation = residual; + corrections++; + return state.clone(); + } + + /** + * Folds one linear measurement into the estimate, which is the plain Kalman correction. + * + * @param measurement what the sensor reported + * @param model the measurement matrix, with one row per measurement and one column per state + * @param measurementNoise how much the sensor is trusted, a square matrix of the size of the + * measurement + * @return a copy of the corrected state + * @throws IllegalArgumentException if a shape is wrong or a value is not finite + * @throws ArithmeticException if the innovation covariance cannot be inverted + * @throws NullPointerException if an argument is {@code null} + */ + public double[] update(double[] measurement, double[][] model, double[][] measurementNoise) { + requireMatrix(model, measurement.length, stateSize, "measurement model"); + return update(measurement, current -> multiply(model, current), current -> model, measurementNoise); + } + + /** + * Returns the current estimate. + * + * @return a copy of the state + */ + public double[] state() { + return state.clone(); + } + + /** + * Returns how uncertain the current estimate is. + * + * @return a copy of the covariance + */ + public double[][] covariance() { + return copy(covariance); + } + + /** + * Returns the variance of one component of the state, which is what a caller usually wants out of + * the covariance. + * + * @param component which component, from zero to the size of the state + * @return the variance of that component + * @throws IllegalArgumentException if {@code component} is outside the state + */ + public double variance(int component) { + if (component < 0 || component >= stateSize) { + throw new IllegalArgumentException("The component must lie in [0, " + (stateSize - 1) + "], but was " + component); + } + return covariance[component][component]; + } + + /** + * Returns the last innovation, that is how far the sensor was from what the filter expected. A + * run of innovations that are not centred on zero means the model no longer describes the + * process. + * + * @return a copy of the last residual, empty before the first update + */ + public double[] lastInnovation() { + return innovation.clone(); + } + + /** + * Returns the gain the last update applied. + * + * @return a copy of the last Kalman gain, empty before the first update + */ + public double[][] lastGain() { + return copy(gain); + } + + /** + * Returns the size of the state. + * + * @return how many components the state holds + */ + public int stateSize() { + return stateSize; + } + + /** + * Returns how many predictions have been made since the last reset. + * + * @return the prediction count + */ + public long predictionCount() { + return predictions; + } + + /** + * Returns how many measurements have been folded in since the last reset. + * + * @return the update count + */ + public long updateCount() { + return corrections; + } + + /** + * Restarts the filter from a known estimate. + * + * @param newState the state to carry on from, copied + * @param newCovariance how uncertain it is, copied + * @throws IllegalArgumentException if a shape is wrong or a value is not finite + * @throws NullPointerException if an argument is {@code null} + */ + public void reset(double[] newState, double[][] newCovariance) { + requireVector(newState, stateSize, "state"); + requireMatrix(newCovariance, stateSize, stateSize, "covariance"); + state = newState.clone(); + covariance = copy(newCovariance); + innovation = new double[0]; + gain = new double[0][0]; + predictions = 0; + corrections = 0; + } + + @Override + public String toString() { + return "ExtendedKalmanFilter{state=" + Arrays.toString(state) + ", predictions=" + predictions + ", updates=" + corrections + "}"; + } + + private static void requireVector(double[] vector, int size, String name) { + if (vector.length != size) { + throw new IllegalArgumentException("The " + name + " must hold " + size + " values, but held " + vector.length); + } + for (double value : vector) { + if (!Double.isFinite(value)) { + throw new IllegalArgumentException("The " + name + " must be finite, but held " + value); + } + } + } + + private static void requireMatrix(double[][] matrix, int rows, int columns, String name) { + if (matrix.length != rows) { + throw new IllegalArgumentException("The " + name + " must have " + rows + " rows, but had " + matrix.length); + } + for (double[] row : matrix) { + if (row.length != columns) { + throw new IllegalArgumentException("The " + name + " must have " + columns + " columns, but a row had " + row.length); + } + for (double value : row) { + if (!Double.isFinite(value)) { + throw new IllegalArgumentException("The " + name + " must be finite, but held " + value); + } + } + } + } + + private static void requireFiniteMatrix(double[][] matrix) { + for (double[] row : matrix) { + for (double value : row) { + if (!Double.isFinite(value)) { + throw new ArithmeticException("The innovation covariance is singular, so the gain is undefined"); + } + } + } + } + + private static double[][] copy(double[][] matrix) { + double[][] copied = new double[matrix.length][]; + for (int i = 0; i < matrix.length; i++) { + copied[i] = matrix[i].clone(); + } + return copied; + } + + private static double[][] identity(int size) { + double[][] result = new double[size][size]; + for (int i = 0; i < size; i++) { + result[i][i] = 1.0; + } + return result; + } + + private static double[][] transpose(double[][] matrix) { + double[][] result = new double[matrix[0].length][matrix.length]; + for (int i = 0; i < matrix.length; i++) { + for (int j = 0; j < matrix[i].length; j++) { + result[j][i] = matrix[i][j]; + } + } + return result; + } + + private static double[][] multiply(double[][] left, double[][] right) { + double[][] result = new double[left.length][right[0].length]; + for (int i = 0; i < left.length; i++) { + for (int k = 0; k < right.length; k++) { + double factor = left[i][k]; + for (int j = 0; j < right[0].length; j++) { + result[i][j] += factor * right[k][j]; + } + } + } + return result; + } + + private static double[] multiply(double[][] matrix, double[] vector) { + double[] result = new double[matrix.length]; + for (int i = 0; i < matrix.length; i++) { + double sum = 0.0; + for (int j = 0; j < vector.length; j++) { + sum += matrix[i][j] * vector[j]; + } + result[i] = sum; + } + return result; + } + + private static double[][] add(double[][] left, double[][] right) { + double[][] result = new double[left.length][left[0].length]; + for (int i = 0; i < left.length; i++) { + for (int j = 0; j < left[i].length; j++) { + result[i][j] = left[i][j] + right[i][j]; + } + } + return result; + } + + private static double[][] subtract(double[][] left, double[][] right) { + double[][] result = new double[left.length][left[0].length]; + for (int i = 0; i < left.length; i++) { + for (int j = 0; j < left[i].length; j++) { + result[i][j] = left[i][j] - right[i][j]; + } + } + return result; + } +} diff --git a/src/test/java/com/thealgorithms/streaming/ExtendedKalmanFilterTest.java b/src/test/java/com/thealgorithms/streaming/ExtendedKalmanFilterTest.java new file mode 100644 index 000000000000..d0286aac4a36 --- /dev/null +++ b/src/test/java/com/thealgorithms/streaming/ExtendedKalmanFilterTest.java @@ -0,0 +1,273 @@ +package com.thealgorithms.streaming; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.Random; +import org.junit.jupiter.api.Assertions; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; + +class ExtendedKalmanFilterTest { + + private static final double OFFSET = 5.0; + private static final double INTERVAL = 0.1; + + private static ExtendedKalmanFilter scalarFilter(double estimate, double variance) { + return new ExtendedKalmanFilter(new double[] {estimate}, new double[][] {{variance}}); + } + + /** The range a sensor at the origin sees of a target passing at a fixed lateral offset. */ + private static double range(double position) { + return Math.hypot(position, OFFSET); + } + + @Test + void rejectsAnEmptyOrMalformedStart() { + assertThrows(IllegalArgumentException.class, () -> new ExtendedKalmanFilter(new double[0], new double[0][0])); + assertThrows(IllegalArgumentException.class, () -> new ExtendedKalmanFilter(new double[] {1.0, 2.0}, new double[][] {{1.0}})); + assertThrows(IllegalArgumentException.class, () -> new ExtendedKalmanFilter(new double[] {1.0}, new double[][] {{1.0, 0.0}})); + assertThrows(IllegalArgumentException.class, () -> new ExtendedKalmanFilter(new double[] {Double.NaN}, new double[][] {{1.0}})); + assertThrows(IllegalArgumentException.class, () -> new ExtendedKalmanFilter(new double[] {1.0}, new double[][] {{Double.POSITIVE_INFINITY}})); + } + + @Test + void rejectsMisshapenModels() { + ExtendedKalmanFilter filter = scalarFilter(0.0, 1.0); + + assertThrows(IllegalArgumentException.class, () -> filter.predict(new double[][] {{1.0, 0.0}}, new double[][] {{1.0}})); + assertThrows(IllegalArgumentException.class, () -> filter.predict(new double[][] {{1.0}}, new double[][] {{1.0, 0.0}})); + assertThrows(IllegalArgumentException.class, () -> filter.update(new double[0], new double[0][0], new double[0][0])); + assertThrows(IllegalArgumentException.class, () -> filter.update(new double[] {1.0}, new double[][] {{1.0}}, new double[][] {{1.0, 0.0}})); + assertThrows(IllegalArgumentException.class, () -> filter.update(new double[] {1.0}, new double[][] {{1.0, 1.0}}, new double[][] {{1.0}})); + } + + @Test + @DisplayName("a model that returns the wrong shape or a non-finite value is caught") + void rejectsAModelThatMisbehaves() { + ExtendedKalmanFilter filter = scalarFilter(0.0, 1.0); + + assertThrows(IllegalArgumentException.class, () -> filter.predict(current -> new double[] {1.0, 2.0}, current -> new double[][] {{1.0}}, new double[][] {{1.0}})); + assertThrows(IllegalArgumentException.class, () -> filter.predict(current -> new double[] {Double.NaN}, current -> new double[][] {{1.0}}, new double[][] {{1.0}})); + assertThrows(IllegalArgumentException.class, () -> filter.update(new double[] {1.0}, current -> new double[] {1.0, 2.0}, current -> new double[][] {{1.0}}, new double[][] {{1.0}})); + } + + @Test + @DisplayName("a measurement that carries no information is reported rather than silently poisoning the state") + void rejectsASingularInnovationCovariance() { + ExtendedKalmanFilter filter = scalarFilter(0.0, 0.0); + + assertThrows(ArithmeticException.class, () -> filter.update(new double[] {1.0}, new double[][] {{1.0}}, new double[][] {{0.0}})); + } + + @Test + @DisplayName("one update of a one dimensional filter is the textbook half way step") + void reproducesTheTextbookScalarUpdate() { + ExtendedKalmanFilter filter = scalarFilter(0.0, 1.0); + + double[] corrected = filter.update(new double[] {1.0}, new double[][] {{1.0}}, new double[][] {{1.0}}); + + assertEquals(0.5, corrected[0], 1e-12, "with equal confidence the estimate lands in the middle"); + assertEquals(0.5, filter.variance(0), 1e-12); + assertEquals(0.5, filter.lastGain()[0][0], 1e-12); + assertEquals(1.0, filter.lastInnovation()[0], 1e-12); + } + + @Test + @DisplayName("on a linear model the filter is the scalar Kalman recursion, to the last digit") + void matchesTheScalarKalmanRecursion() { + double processNoise = 0.01; + double measurementNoise = 0.25; + ExtendedKalmanFilter filter = scalarFilter(0.0, 1.0); + double estimate = 0.0; + double variance = 1.0; + + Random random = new Random(5L); + for (int step = 0; step < 500; step++) { + filter.predict(new double[][] {{1.0}}, new double[][] {{processNoise}}); + variance += processNoise; + + double measurement = random.nextGaussian(); + filter.update(new double[] {measurement}, new double[][] {{1.0}}, new double[][] {{measurementNoise}}); + double gain = variance / (variance + measurementNoise); + estimate += gain * (measurement - estimate); + variance = (1 - gain) * variance * (1 - gain) + gain * measurementNoise * gain; + + assertEquals(estimate, filter.state()[0], 1e-12, "step " + step); + assertEquals(variance, filter.variance(0), 1e-12, "step " + step); + } + } + + @Test + @DisplayName("the Joseph form keeps the covariance symmetric over a long run") + void keepsTheCovarianceSymmetric() { + Random random = new Random(11L); + ExtendedKalmanFilter filter = new ExtendedKalmanFilter(new double[] {0.0, 0.0, 0.0}, new double[][] {{1.0, 0.0, 0.0}, {0.0, 1.0, 0.0}, {0.0, 0.0, 1.0}}); + double[][] transition = {{1.0, INTERVAL, 0.0}, {0.0, 1.0, INTERVAL}, {0.0, 0.0, 1.0}}; + double[][] processNoise = {{1e-4, 0.0, 0.0}, {0.0, 1e-4, 0.0}, {0.0, 0.0, 1e-4}}; + double[][] model = {{1.0, 0.0, 0.0}}; + double[][] measurementNoise = {{0.5}}; + + for (int step = 0; step < 500; step++) { + filter.predict(transition, processNoise); + filter.update(new double[] {random.nextGaussian()}, model, measurementNoise); + + double[][] covariance = filter.covariance(); + for (int i = 0; i < covariance.length; i++) { + assertTrue(covariance[i][i] >= 0.0, "a variance went negative at step " + step); + for (int j = 0; j < i; j++) { + assertEquals(covariance[i][j], covariance[j][i], 1e-12, "the covariance lost its symmetry at step " + step); + } + } + } + } + + @Test + @DisplayName("repeated measurements of something that does not move shrink the uncertainty towards zero") + void convergesOnAConstant() { + Random random = new Random(3L); + ExtendedKalmanFilter filter = scalarFilter(0.0, 100.0); + double truth = 7.0; + double previous = Double.MAX_VALUE; + + for (int step = 0; step < 2000; step++) { + filter.update(new double[] {truth + random.nextGaussian()}, new double[][] {{1.0}}, new double[][] {{1.0}}); + double variance = filter.variance(0); + assertTrue(variance < previous, "the uncertainty must never grow without process noise, step " + step); + previous = variance; + } + + assertEquals(truth, filter.state()[0], 0.1); + assertTrue(filter.variance(0) < 0.001, "after 2000 measurements the variance was still " + filter.variance(0)); + } + + @Test + @DisplayName("a target seen only as a range is tracked through the nonlinear measurement") + void tracksATargetThroughARangeOnlySensor() { + Random random = new Random(17L); + double[][] transition = {{1.0, INTERVAL}, {0.0, 1.0}}; + double[][] processNoise = {{1e-6, 0.0}, {0.0, 1e-4}}; + double[][] measurementNoise = {{0.04}}; + ExtendedKalmanFilter filter = new ExtendedKalmanFilter(new double[] {1.0, 0.5}, new double[][] {{4.0, 0.0}, {0.0, 4.0}}); + + double position = 2.0; + double velocity = 1.0; + double filterError = 0.0; + double rawError = 0.0; + int counted = 0; + + for (int step = 0; step < 400; step++) { + position += velocity * INTERVAL; + double measurement = range(position) + 0.2 * random.nextGaussian(); + + filter.predict(transition, processNoise); + filter.update(new double[] {measurement}, state -> new double[] {range(state[0])}, state -> new double[][] {{state[0] / range(state[0]), 0.0}}, measurementNoise); + + if (step > 200) { + filterError += Math.abs(filter.state()[0] - position); + rawError += Math.abs(Math.sqrt(Math.max(0.0, measurement * measurement - OFFSET * OFFSET)) - position); + counted++; + } + } + + double filtered = filterError / counted; + double raw = rawError / counted; + assertTrue(filtered < 0.2, "the filtered position was off by " + filtered); + assertTrue(filtered < raw / 2, "filtering should beat inverting each measurement on its own, " + filtered + " against " + raw); + assertEquals(velocity, filter.state()[1], 0.2, "the velocity is never measured, only inferred"); + } + + @Test + @DisplayName("the linear overloads are the nonlinear ones with a matrix for a model") + void theLinearOverloadsAgreeWithTheFunctionalOnes() { + double[][] transition = {{1.0, INTERVAL}, {0.0, 1.0}}; + double[][] processNoise = {{0.01, 0.0}, {0.0, 0.01}}; + double[][] model = {{1.0, 0.0}}; + double[][] measurementNoise = {{0.5}}; + double[] start = {1.0, 2.0}; + double[][] startCovariance = {{1.0, 0.0}, {0.0, 1.0}}; + + ExtendedKalmanFilter linear = new ExtendedKalmanFilter(start, startCovariance); + ExtendedKalmanFilter functional = new ExtendedKalmanFilter(start, startCovariance); + + for (int step = 0; step < 50; step++) { + linear.predict(transition, processNoise); + functional.predict(state -> new double[] {state[0] + INTERVAL * state[1], state[1]}, state -> transition, processNoise); + + double measurement = 0.1 * step; + linear.update(new double[] {measurement}, model, measurementNoise); + functional.update(new double[] {measurement}, state -> new double[] {state[0]}, state -> model, measurementNoise); + + Assertions.assertArrayEquals(linear.state(), functional.state(), 1e-12, "step " + step); + } + } + + @Test + @DisplayName("prediction without measurements only widens the uncertainty") + void predictionAloneAddsUncertainty() { + ExtendedKalmanFilter filter = scalarFilter(3.0, 1.0); + + for (int step = 1; step <= 10; step++) { + filter.predict(new double[][] {{1.0}}, new double[][] {{0.5}}); + + assertEquals(3.0, filter.state()[0], 1e-12, "a unit transition must not move the estimate"); + assertEquals(1.0 + 0.5 * step, filter.variance(0), 1e-12); + } + assertEquals(10, filter.predictionCount()); + assertEquals(0, filter.updateCount()); + } + + @Test + void theStateAndCovarianceAreCopiedOut() { + ExtendedKalmanFilter filter = scalarFilter(1.0, 2.0); + + filter.state()[0] = 99.0; + filter.covariance()[0][0] = 99.0; + filter.update(new double[] {1.0}, new double[][] {{1.0}}, new double[][] {{1.0}}); + filter.lastGain()[0][0] = 99.0; + filter.lastInnovation()[0] = 99.0; + + assertTrue(filter.state()[0] < 2.0); + assertTrue(filter.covariance()[0][0] < 2.0); + assertTrue(filter.lastGain()[0][0] < 1.0); + } + + @Test + void exposesItsShapeAndCounters() { + ExtendedKalmanFilter filter = new ExtendedKalmanFilter(new double[] {0.0, 0.0}, new double[][] {{1.0, 0.0}, {0.0, 1.0}}); + + assertEquals(2, filter.stateSize()); + assertEquals(0, filter.predictionCount()); + assertEquals(0, filter.updateCount()); + assertEquals(0, filter.lastInnovation().length); + assertThrows(IllegalArgumentException.class, () -> filter.variance(2)); + assertThrows(IllegalArgumentException.class, () -> filter.variance(-1)); + } + + @Test + void resetRestartsFromAKnownEstimate() { + ExtendedKalmanFilter filter = scalarFilter(0.0, 1.0); + filter.update(new double[] {5.0}, new double[][] {{1.0}}, new double[][] {{1.0}}); + + filter.reset(new double[] {-2.0}, new double[][] {{9.0}}); + + assertEquals(-2.0, filter.state()[0], 1e-12); + assertEquals(9.0, filter.variance(0), 1e-12); + assertEquals(0, filter.updateCount()); + assertEquals(0, filter.lastInnovation().length); + assertThrows(IllegalArgumentException.class, () -> filter.reset(new double[] {1.0, 2.0}, new double[][] {{1.0}})); + } + + @Test + void toStringMentionsTheState() { + ExtendedKalmanFilter filter = scalarFilter(1.5, 1.0); + filter.predict(new double[][] {{1.0}}, new double[][] {{0.1}}); + + String text = filter.toString(); + + assertTrue(text.contains("ExtendedKalmanFilter")); + assertTrue(text.contains("predictions=1")); + assertTrue(text.contains("1.5")); + } +} From 6ed9243cff1f86aeec1082b867eb289a531f4281 Mon Sep 17 00:00:00 2001 From: Jinwoo Park Date: Fri, 25 Sep 2026 01:42:36 -0700 Subject: [PATCH 25/92] docs: fix typos in comments (#7616) * docs: fix typos in comments Fix misspellings found with codespell: reccur/reccuring, positon, choosed, increate, contantating, and "Hava a Eulerian Path". Also rename the local variable formater to formatter in MathBuilder. * docs: fix grammar typos in comments Fix "tho" -> "to", doubled "of of", "than" -> "then", "it's" -> "its", "in-order to" -> "in order to", and "a" -> "an" before vowel sounds. --- .../datastructures/lists/DoublyLinkedList.java | 2 +- .../datastructures/lists/QuickSortLinkedList.java | 6 +++--- .../datastructures/queues/PriorityQueues.java | 2 +- .../thealgorithms/datastructures/trees/SegmentTree.java | 2 +- .../datastructures/trees/VerticalOrderTraversal.java | 2 +- src/main/java/com/thealgorithms/io/BufferedReader.java | 2 +- src/main/java/com/thealgorithms/maths/DigitalRoot.java | 2 +- src/main/java/com/thealgorithms/maths/EvilNumber.java | 2 +- src/main/java/com/thealgorithms/maths/MathBuilder.java | 8 ++++---- src/main/java/com/thealgorithms/maths/PollardRho.java | 2 +- .../java/com/thealgorithms/maths/VectorCrossProduct.java | 2 +- .../java/com/thealgorithms/others/ArrayRightRotation.java | 2 +- src/main/java/com/thealgorithms/others/Damm.java | 2 +- src/main/java/com/thealgorithms/others/PasswordGen.java | 2 +- src/main/java/com/thealgorithms/others/Verhoeff.java | 2 +- src/main/java/com/thealgorithms/sorts/LinkListSort.java | 8 ++++---- .../com/thealgorithms/strings/zigZagPattern/README.md | 8 ++++---- .../thealgorithms/graph/HierholzerEulerianPathTest.java | 2 +- 18 files changed, 29 insertions(+), 29 deletions(-) diff --git a/src/main/java/com/thealgorithms/datastructures/lists/DoublyLinkedList.java b/src/main/java/com/thealgorithms/datastructures/lists/DoublyLinkedList.java index 58898ddc0fcf..462521e464cc 100644 --- a/src/main/java/com/thealgorithms/datastructures/lists/DoublyLinkedList.java +++ b/src/main/java/com/thealgorithms/datastructures/lists/DoublyLinkedList.java @@ -7,7 +7,7 @@ *

* A linked list is similar to an array, it holds values. However, links in a * linked list do not have indexes. With a linked list you do not need to - * predetermine it's size as it grows and shrinks as it is edited. This is an + * predetermine its size as it grows and shrinks as it is edited. This is an * example of a double ended, doubly linked list. Each link references the next * link and the previous one. * diff --git a/src/main/java/com/thealgorithms/datastructures/lists/QuickSortLinkedList.java b/src/main/java/com/thealgorithms/datastructures/lists/QuickSortLinkedList.java index f018781ada70..a7c2da913cd5 100644 --- a/src/main/java/com/thealgorithms/datastructures/lists/QuickSortLinkedList.java +++ b/src/main/java/com/thealgorithms/datastructures/lists/QuickSortLinkedList.java @@ -20,7 +20,7 @@ * List lessThanPivot : 3 -> 1 -> 2 -> 4 * List greaterThanPivot : 5 -> 8 -> 10 -> 7 -> 9 -> 6 * - * -> reccur for lessThanPivot and greaterThanPivot + * -> recur for lessThanPivot and greaterThanPivot * * lessThanPivot : * current pivot : 3 @@ -32,7 +32,7 @@ * lessThanPivot : null * greaterThanPivot : 8 -> 10 -> 7 -> 9 -> 6 * - * By following the above pattern, reccuring tree will form like below : + * By following the above pattern, the recursion tree will form like below : * * List-> 5 -> 3 -> 8 -> 1 -> 10 -> 2 -> 7 -> 4 -> 9 -> 6 * @@ -66,7 +66,7 @@ * (N) (N) (N) (N) * * - * -> After this the tree will reccur back (or backtrack) + * -> After this the tree will recur back (or backtrack) * and the returning list from left and right subtree will attach * themselves around pivot. * i.e. , diff --git a/src/main/java/com/thealgorithms/datastructures/queues/PriorityQueues.java b/src/main/java/com/thealgorithms/datastructures/queues/PriorityQueues.java index b877a5843b98..5d4157deef70 100644 --- a/src/main/java/com/thealgorithms/datastructures/queues/PriorityQueues.java +++ b/src/main/java/com/thealgorithms/datastructures/queues/PriorityQueues.java @@ -85,7 +85,7 @@ private void swim(int pos) { private void sink(int pos) { // Check if node's position is that of parent node while (2 * pos <= nItems) { - int current = 2 * pos; // Jump to the positon of child node + int current = 2 * pos; // Jump to the position of child node // Compare both the children for the greater one if (current < nItems && queueArray[current] < queueArray[current + 1]) { current++; diff --git a/src/main/java/com/thealgorithms/datastructures/trees/SegmentTree.java b/src/main/java/com/thealgorithms/datastructures/trees/SegmentTree.java index af6acb0cbb2b..4fbb578dcf50 100644 --- a/src/main/java/com/thealgorithms/datastructures/trees/SegmentTree.java +++ b/src/main/java/com/thealgorithms/datastructures/trees/SegmentTree.java @@ -35,7 +35,7 @@ public final int constructTree(int[] arr, int start, int end, int index) { return this.segTree[index]; } - /* A function which will update the value at a index i. This will be called by the + /* A function which will update the value at an index i. This will be called by the update function internally*/ private void updateTree(int start, int end, int index, int diff, int segIndex) { if (index < start || index > end) { diff --git a/src/main/java/com/thealgorithms/datastructures/trees/VerticalOrderTraversal.java b/src/main/java/com/thealgorithms/datastructures/trees/VerticalOrderTraversal.java index c1d15390d4b9..5484b64641a9 100644 --- a/src/main/java/com/thealgorithms/datastructures/trees/VerticalOrderTraversal.java +++ b/src/main/java/com/thealgorithms/datastructures/trees/VerticalOrderTraversal.java @@ -73,7 +73,7 @@ public static ArrayList verticalTraversal(BinaryTree.Node root) { ArrayList a = new ArrayList<>(); map.put(index.peek(), a); } - /*For a index, corresponding Node data is added + /*For an index, corresponding Node data is added to the respective ArrayList present at that index. */ map.get(index.peek()).add(queue.peek().data); diff --git a/src/main/java/com/thealgorithms/io/BufferedReader.java b/src/main/java/com/thealgorithms/io/BufferedReader.java index 66673fe281ae..c0b7e8a449bd 100644 --- a/src/main/java/com/thealgorithms/io/BufferedReader.java +++ b/src/main/java/com/thealgorithms/io/BufferedReader.java @@ -108,7 +108,7 @@ public int peek(int n) throws IOException { /** * Removes the already read bytes from the buffer - * in-order to make space for new bytes to be filled up. + * in order to make space for new bytes to be filled up. *

* This may also do the job to read first time data (the whole buffer is empty) */ diff --git a/src/main/java/com/thealgorithms/maths/DigitalRoot.java b/src/main/java/com/thealgorithms/maths/DigitalRoot.java index e8f5305c7569..c7367e5965df 100644 --- a/src/main/java/com/thealgorithms/maths/DigitalRoot.java +++ b/src/main/java/com/thealgorithms/maths/DigitalRoot.java @@ -55,7 +55,7 @@ public static int digitalRoot(int n) { // This function is used for finding the sum of the digits of number public static int single(int n) { - if (n <= 9) { // if n becomes less than 10 than return n + if (n <= 9) { // if n becomes less than 10 then return n return n; } else { return (n % 10) + single(n / 10); // n % 10 for extracting digits one by one diff --git a/src/main/java/com/thealgorithms/maths/EvilNumber.java b/src/main/java/com/thealgorithms/maths/EvilNumber.java index 419133702fd4..a10794fb5a85 100644 --- a/src/main/java/com/thealgorithms/maths/EvilNumber.java +++ b/src/main/java/com/thealgorithms/maths/EvilNumber.java @@ -26,7 +26,7 @@ private static int countOneBits(int number) { * Check either {@code number} is an Evil number or Odious number * * @param number the number - * @return {@code true} if {@code number} is an Evil number, otherwise false (in case of of Odious number) + * @return {@code true} if {@code number} is an Evil number, otherwise false (in case of Odious number) */ public static boolean isEvilNumber(int number) { if (number < 0) { diff --git a/src/main/java/com/thealgorithms/maths/MathBuilder.java b/src/main/java/com/thealgorithms/maths/MathBuilder.java index 1cf3d8b7fc9a..08d2ae2c9456 100644 --- a/src/main/java/com/thealgorithms/maths/MathBuilder.java +++ b/src/main/java/com/thealgorithms/maths/MathBuilder.java @@ -481,8 +481,8 @@ public Builder closeParenthesisAndDivide() { } public Builder format(String format) { - DecimalFormat formater = new DecimalFormat(format); - String num = formater.format(number); + DecimalFormat formatter = new DecimalFormat(format); + String num = formatter.format(number); number = Double.parseDouble(num); return this; } @@ -490,8 +490,8 @@ public Builder format(String format) { public Builder format(int decimalPlace) { String pattern = "." + "#".repeat(decimalPlace); - DecimalFormat formater = new DecimalFormat(pattern); - String num = formater.format(number); + DecimalFormat formatter = new DecimalFormat(pattern); + String num = formatter.format(number); number = Double.parseDouble(num); return this; } diff --git a/src/main/java/com/thealgorithms/maths/PollardRho.java b/src/main/java/com/thealgorithms/maths/PollardRho.java index 7fa913b21b7e..c63f93d839bf 100644 --- a/src/main/java/com/thealgorithms/maths/PollardRho.java +++ b/src/main/java/com/thealgorithms/maths/PollardRho.java @@ -54,7 +54,7 @@ static int g(int base, int modulus) { /** * This method returns a non-trivial factor of given integer number * - * @param number Integer is a integer value whose non-trivial factor is to be found + * @param number Integer is an integer value whose non-trivial factor is to be found * @return Integer non-trivial factor of number * @throws RuntimeException object if GCD of given number cannot be found */ diff --git a/src/main/java/com/thealgorithms/maths/VectorCrossProduct.java b/src/main/java/com/thealgorithms/maths/VectorCrossProduct.java index e2769744bcda..41bbbb077c68 100644 --- a/src/main/java/com/thealgorithms/maths/VectorCrossProduct.java +++ b/src/main/java/com/thealgorithms/maths/VectorCrossProduct.java @@ -15,7 +15,7 @@ * matrix consisting of the first row with unit vectors of magnitude 1, the * second row with the direction ratios of the first vector and the third row * with the direction ratios of the second vector. The magnitude of a vector is - * it's value expressed as a number. Let the direction ratios of the first + * its value expressed as a number. Let the direction ratios of the first * vector, P be: a, b, c Let the direction ratios of the second vector, Q be: x, * y, z Therefore the calculation for the cross product can be arranged as: * diff --git a/src/main/java/com/thealgorithms/others/ArrayRightRotation.java b/src/main/java/com/thealgorithms/others/ArrayRightRotation.java index 125edadb6e73..ba80f29af710 100644 --- a/src/main/java/com/thealgorithms/others/ArrayRightRotation.java +++ b/src/main/java/com/thealgorithms/others/ArrayRightRotation.java @@ -34,7 +34,7 @@ public static int[] rotateRight(int[] arr, int k) { } /** - * Performs reversing of a array + * Performs reversing of an array * @param arr the array to be reversed * @param start starting position * @param end ending position diff --git a/src/main/java/com/thealgorithms/others/Damm.java b/src/main/java/com/thealgorithms/others/Damm.java index 55a4c5b81a89..c6365ada42f7 100644 --- a/src/main/java/com/thealgorithms/others/Damm.java +++ b/src/main/java/com/thealgorithms/others/Damm.java @@ -60,7 +60,7 @@ public static boolean dammCheck(String digits) { } /** - * Calculate check digit for initial digits and add it tho the last + * Calculate check digit for initial digits and add it to the last * position. * * @param initialDigits initial value diff --git a/src/main/java/com/thealgorithms/others/PasswordGen.java b/src/main/java/com/thealgorithms/others/PasswordGen.java index da9f21bc918f..4f139963eae5 100644 --- a/src/main/java/com/thealgorithms/others/PasswordGen.java +++ b/src/main/java/com/thealgorithms/others/PasswordGen.java @@ -41,7 +41,7 @@ public static String generatePassword(int minLength, int maxLength) { letters.add(c); } - // Inbuilt method to randomly shuffle a elements of a list + // Inbuilt method to randomly shuffle the elements of a list Collections.shuffle(letters); StringBuilder password = new StringBuilder(); diff --git a/src/main/java/com/thealgorithms/others/Verhoeff.java b/src/main/java/com/thealgorithms/others/Verhoeff.java index 9088612aaa43..bd25113f494f 100644 --- a/src/main/java/com/thealgorithms/others/Verhoeff.java +++ b/src/main/java/com/thealgorithms/others/Verhoeff.java @@ -108,7 +108,7 @@ public static boolean verhoeffCheck(String digits) { } /** - * Calculate check digit for initial digits and add it tho the last + * Calculate check digit for initial digits and add it to the last * position. * * @param initialDigits initial value diff --git a/src/main/java/com/thealgorithms/sorts/LinkListSort.java b/src/main/java/com/thealgorithms/sorts/LinkListSort.java index d8fd76a86236..4af789f1e460 100644 --- a/src/main/java/com/thealgorithms/sorts/LinkListSort.java +++ b/src/main/java/com/thealgorithms/sorts/LinkListSort.java @@ -13,7 +13,7 @@ public static boolean isSorted(int[] p, int option) { int[] b = p; // array similar to a int ch = option; - // Choice is choosed as any number from 1 to 3 (So the linked list will be + // Choice is chosen as any number from 1 to 3 (So the linked list will be // sorted by Merge sort technique/Insertion sort technique/Heap sort technique) switch (ch) { case 1: @@ -176,7 +176,7 @@ int count(Node head) { } return c; // This Method is used to count number of elements/nodes present in the linklist - // It will return a integer type value denoting the number of nodes present + // It will return an integer type value denoting the number of nodes present } void task(int[] n, int i, int j) { @@ -252,7 +252,7 @@ static int count(Node head) { } return c; // This Method is used to count number of elements/nodes present in the linklist - // It will return a integer type value denoting the number of nodes present + // It will return an integer type value denoting the number of nodes present } // The method task and task1 is used to sort the linklist using insertion sort } @@ -288,7 +288,7 @@ int count(Node head) { } return c; // This Method is used to count number of elements/nodes present in the linklist - // It will return a integer type value denoting the number of nodes present + // It will return an integer type value denoting the number of nodes present } void task(int[] n) { diff --git a/src/main/java/com/thealgorithms/strings/zigZagPattern/README.md b/src/main/java/com/thealgorithms/strings/zigZagPattern/README.md index 17e5ba6e26d8..a8689351f359 100644 --- a/src/main/java/com/thealgorithms/strings/zigZagPattern/README.md +++ b/src/main/java/com/thealgorithms/strings/zigZagPattern/README.md @@ -22,14 +22,14 @@ for example : # working if string size is smaller than numRows or numRows is smaller than 2 - than we can return string because it will make no changes to string. + then we can return string because it will make no changes to string. If not than we initiate three variable depth which is equalvalent to numRows , height which starts with 1 and start with starting index of string. - than we generate spaces to skip using formula 2 + (( n - 1 ) * 2 ) + then we generate spaces to skip using formula 2 + (( n - 1 ) * 2 ) for both height and depth - with each iteration we decrement depth and increate height and start - by one also we keep contantating character on to new string with first + with each iteration we decrement depth and increase height and start + by one also we keep concatenating character on to new string with first depth spaces and later height spaces that we generated using formula if not zero diff --git a/src/test/java/com/thealgorithms/graph/HierholzerEulerianPathTest.java b/src/test/java/com/thealgorithms/graph/HierholzerEulerianPathTest.java index 612d09561b7b..e6a35566c587 100644 --- a/src/test/java/com/thealgorithms/graph/HierholzerEulerianPathTest.java +++ b/src/test/java/com/thealgorithms/graph/HierholzerEulerianPathTest.java @@ -153,7 +153,7 @@ void testMultipleEdgesBetweenSameNodes() { HierholzerEulerianPath solver = new HierholzerEulerianPath(graph); List result = solver.findEulerianPath(); - // Hava a Eulerian Path but not a Eulerian Circuit + // Has an Eulerian Path but not an Eulerian Circuit assertEquals(result, Arrays.asList(0, 1, 2, 0, 1)); } From 4b58d367a88f5c1d922d6bdb6fd3141712b4b862 Mon Sep 17 00:00:00 2001 From: Nitin Jha <115951579+nitin1053@users.noreply.github.com> Date: Fri, 25 Sep 2026 16:44:54 +0530 Subject: [PATCH 26/92] feat(ciphers): add Lamport one-time signature (#7617) * feat(ciphers): add Lamport one-time signature * Fix for the check * fixing the bugs * comments resolved --- .../ciphers/LamportSignature.java | 145 ++++++++++++++++++ .../ciphers/LamportSignatureTest.java | 101 ++++++++++++ 2 files changed, 246 insertions(+) create mode 100644 src/main/java/com/thealgorithms/ciphers/LamportSignature.java create mode 100644 src/test/java/com/thealgorithms/ciphers/LamportSignatureTest.java diff --git a/src/main/java/com/thealgorithms/ciphers/LamportSignature.java b/src/main/java/com/thealgorithms/ciphers/LamportSignature.java new file mode 100644 index 000000000000..c4a6459fd4c3 --- /dev/null +++ b/src/main/java/com/thealgorithms/ciphers/LamportSignature.java @@ -0,0 +1,145 @@ +package com.thealgorithms.ciphers; + +import java.security.MessageDigest; +import java.security.NoSuchAlgorithmException; +import java.security.SecureRandom; +import java.util.Arrays; + +/** + * Lamport one-time signatures (OTS) are a hash-based post-quantum signature scheme. + * + *

The scheme is based on a private key consisting of 256 pairs of random 32-byte secrets, + * one pair per bit position of a SHA-256 digest. The public key contains the SHA-256 hashes of + * those secrets. + * + *

To sign a message, the algorithm hashes the message and reveals the secret corresponding to + * each bit value in the digest. Verification recomputes the digest and checks that each revealed + * secret hashes to the expected public-key value. + * + *

This implementation is educational and intentionally keeps dependencies minimal. Each key pair + * is strictly one-time: signing a second message with the same key is rejected. + * + *

Reference: Wikipedia: Lamport signature + */ +public final class LamportSignature { + + private static final int DIGEST_BITS = 256; + private static final int SECRET_BYTES = 32; + private static final int NUM_VALUES = 2; + + private LamportSignature() { + } + + /** + * A Lamport key pair containing both the private and public material. + */ + public static final class KeyPair { + private final byte[][][] privateKey; + private final byte[][][] publicKey; + private boolean used; + + private KeyPair(byte[][][] privateKey, byte[][][] publicKey) { + this.privateKey = privateKey; + this.publicKey = publicKey; + } + + /** + * Signs a message using this key pair. + * + * @param message the message to sign + * @return the signature bytes; exactly 256 secret values ordered by digest bit positions + * @throws IllegalArgumentException if the message is null + * @throws IllegalStateException if this key pair has already been used to sign a message + */ + public byte[] sign(byte[] message) { + if (message == null) { + throw new IllegalArgumentException("message must not be null"); + } + if (used) { + throw new IllegalStateException("This Lamport key pair can only sign one message"); + } + used = true; + + byte[] digest = sha256(message); + byte[] signature = new byte[DIGEST_BITS * SECRET_BYTES]; + for (int bit = 0; bit < DIGEST_BITS; bit++) { + int value = (digest[bit / 8] >> (7 - (bit % 8))) & 0x01; + byte[] secret = privateKey[bit][value]; + System.arraycopy(secret, 0, signature, bit * SECRET_BYTES, SECRET_BYTES); + } + return signature; + } + + /** + * Verifies a message signature against this public key. + * + * @param message the message to verify + * @param signature the signature to verify + * @return true if the signature is valid for the provided message and public key + * @throws IllegalArgumentException if message or signature is null or malformed + */ + public boolean verify(byte[] message, byte[] signature) { + if (message == null) { + throw new IllegalArgumentException("message must not be null"); + } + if (signature == null) { + throw new IllegalArgumentException("signature must not be null"); + } + if (signature.length != DIGEST_BITS * SECRET_BYTES) { + throw new IllegalArgumentException("signature length must be exactly 8192 bytes"); + } + + byte[] digest = sha256(message); + for (int bit = 0; bit < DIGEST_BITS; bit++) { + int value = (digest[bit / 8] >> (7 - (bit % 8))) & 0x01; + byte[] revealedSecret = Arrays.copyOfRange(signature, bit * SECRET_BYTES, (bit + 1) * SECRET_BYTES); + byte[] expectedHash = publicKey[bit][value]; + byte[] actualHash = sha256(revealedSecret); + if (!MessageDigest.isEqual(actualHash, expectedHash)) { + return false; + } + } + return true; + } + + public byte[][][] getPrivateKey() { + return privateKey; + } + + public byte[][][] getPublicKey() { + return publicKey; + } + } + + /** + * Generates a new Lamport key pair. + * + * @return a fresh Lamport key pair + */ + public static KeyPair generateKeyPair() { + SecureRandom secureRandom = new SecureRandom(); + byte[][][] privateKey = new byte[DIGEST_BITS][NUM_VALUES][SECRET_BYTES]; + byte[][][] publicKey = new byte[DIGEST_BITS][NUM_VALUES][SECRET_BYTES]; + + for (int bit = 0; bit < DIGEST_BITS; bit++) { + for (int value = 0; value < NUM_VALUES; value++) { + secureRandom.nextBytes(privateKey[bit][value]); + publicKey[bit][value] = sha256(privateKey[bit][value]); + } + } + return new KeyPair(privateKey, publicKey); + } + + static byte[] sha256(byte[] input) { + try { + MessageDigest digest = MessageDigest.getInstance("SHA-256"); + return digest.digest(input); + } catch (NoSuchAlgorithmException e) { + throw new AssertionError("SHA-256 is required by the Java SE specification", e); + } + } + + static byte[] sha256(byte[] message, int offset, int length) { + return sha256(Arrays.copyOfRange(message, offset, offset + length)); + } +} diff --git a/src/test/java/com/thealgorithms/ciphers/LamportSignatureTest.java b/src/test/java/com/thealgorithms/ciphers/LamportSignatureTest.java new file mode 100644 index 000000000000..99802f753a64 --- /dev/null +++ b/src/test/java/com/thealgorithms/ciphers/LamportSignatureTest.java @@ -0,0 +1,101 @@ +package com.thealgorithms.ciphers; + +import static org.junit.jupiter.api.Assertions.assertArrayEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.nio.charset.StandardCharsets; +import java.util.Arrays; +import org.junit.jupiter.api.Test; + +class LamportSignatureTest { + + @Test + void testValidSignatureVerifies() { + LamportSignature.KeyPair keyPair = LamportSignature.generateKeyPair(); + byte[] message = "hello lamport".getBytes(StandardCharsets.UTF_8); + + byte[] signature = keyPair.sign(message); + + assertTrue(keyPair.verify(message, signature)); + } + + @Test + void testTamperedMessageFailsVerification() { + LamportSignature.KeyPair keyPair = LamportSignature.generateKeyPair(); + byte[] message = "hello lamport".getBytes(StandardCharsets.UTF_8); + byte[] signature = keyPair.sign(message); + + assertFalse(keyPair.verify("hello lamport!".getBytes(StandardCharsets.UTF_8), signature)); + } + + @Test + void testTamperedSignatureFailsVerification() { + LamportSignature.KeyPair keyPair = LamportSignature.generateKeyPair(); + byte[] message = "hello lamport".getBytes(StandardCharsets.UTF_8); + byte[] signature = keyPair.sign(message); + + signature[0] = (byte) (signature[0] ^ 0xFF); + + assertFalse(keyPair.verify(message, signature)); + } + + @Test + void testDifferentKeyPairDoesNotVerify() { + LamportSignature.KeyPair keyPair1 = LamportSignature.generateKeyPair(); + LamportSignature.KeyPair keyPair2 = LamportSignature.generateKeyPair(); + byte[] message = "post-quantum".getBytes(StandardCharsets.UTF_8); + + byte[] signature = keyPair1.sign(message); + + assertFalse(keyPair2.verify(message, signature)); + } + + @Test + void testSecondSignatureThrowsException() { + LamportSignature.KeyPair keyPair = LamportSignature.generateKeyPair(); + byte[] first = "first message".getBytes(StandardCharsets.UTF_8); + byte[] second = "second message".getBytes(StandardCharsets.UTF_8); + + keyPair.sign(first); + + assertThrows(IllegalStateException.class, () -> keyPair.sign(second)); + } + + @Test + void testNullAndMalformedInput() { + LamportSignature.KeyPair keyPair = LamportSignature.generateKeyPair(); + byte[] validMessage = "message".getBytes(StandardCharsets.UTF_8); + byte[] validSignature = keyPair.sign(validMessage); + + assertThrows(IllegalArgumentException.class, () -> keyPair.sign(null)); + assertThrows(IllegalArgumentException.class, () -> keyPair.verify(null, validSignature)); + assertThrows(IllegalArgumentException.class, () -> keyPair.verify(validMessage, null)); + assertThrows(IllegalArgumentException.class, () -> keyPair.verify(validMessage, new byte[1])); + } + + @Test + void testPublicKeyMatchesPrivateKeyHash() { + LamportSignature.KeyPair keyPair = LamportSignature.generateKeyPair(); + byte[][][] publicKey = keyPair.getPublicKey(); + byte[][][] privateKey = keyPair.getPrivateKey(); + + for (int bit = 0; bit < 256; bit++) { + for (int value = 0; value < 2; value++) { + byte[] hash = LamportSignature.sha256(privateKey[bit][value]); + assertArrayEquals(hash, publicKey[bit][value]); + } + } + } + + @Test + void testSha256SliceHelperMatchesRangeHash() { + byte[] message = "hello lamport".getBytes(StandardCharsets.UTF_8); + + byte[] expected = LamportSignature.sha256(Arrays.copyOfRange(message, 2, 12)); + byte[] actual = LamportSignature.sha256(message, 2, 10); + + assertArrayEquals(expected, actual); + } +} From 3027ce1c968bafcf4d81c8f44d3390d5a4d9fc72 Mon Sep 17 00:00:00 2001 From: Shivam Singh Date: Fri, 25 Sep 2026 18:13:13 +0530 Subject: [PATCH 27/92] Add Perceptron binary classifier (#7601) * Add Perceptron binary classifier * Fixed related errors * Fix PMD static import violation and cover Perceptron gaps Reduce static imports to PMD's limit, assert the learned bias and weights, and cover the length-mismatch, null-vector, and divergence paths. --------- Co-authored-by: Alex <19151554+alxkm@users.noreply.github.com> --- .../machinelearning/Perceptron.java | 255 ++++++++++++++++++ .../machinelearning/PerceptronTest.java | 163 +++++++++++ 2 files changed, 418 insertions(+) create mode 100644 src/main/java/com/thealgorithms/machinelearning/Perceptron.java create mode 100644 src/test/java/com/thealgorithms/machinelearning/PerceptronTest.java diff --git a/src/main/java/com/thealgorithms/machinelearning/Perceptron.java b/src/main/java/com/thealgorithms/machinelearning/Perceptron.java new file mode 100644 index 000000000000..7b5e5c4b5429 --- /dev/null +++ b/src/main/java/com/thealgorithms/machinelearning/Perceptron.java @@ -0,0 +1,255 @@ +package com.thealgorithms.machinelearning; + +/** + * A binary Perceptron classifier. + * + *

The Perceptron is a single-layer neural network that learns a linear + * decision boundary. It updates its weights whenever a training sample is + * misclassified. Convergence is guaranteed for linearly separable data, but + * training stops after the configured epoch limit for non-separable data. + * Labels must be either {@code 0} or {@code 1}. + * + *

The prediction rule is {@code 1} when the weighted sum plus bias is + * greater than or equal to zero, and {@code 0} otherwise. For a + * misclassified sample, the update is {@code weight += learningRate * error * + * feature} and {@code bias += learningRate * error}, where {@code error} is + * the true label minus the prediction. Samples are visited one at a time, so + * each prediction uses the parameters produced by the preceding updates of + * the same epoch. + * + * @see Perceptron + */ +public final class Perceptron { + private final double learningRate; + private final int maxEpochs; + private double[] weights; + private double bias; + private int epochsRun; + private boolean converged; + + /** + * Constructs a Perceptron with the given training hyperparameters. + * + * @param learningRate positive step size used for each update + * @param maxEpochs positive maximum number of passes over the training data + * @throws IllegalArgumentException if a hyperparameter is invalid + */ + public Perceptron(double learningRate, int maxEpochs) { + if (!Double.isFinite(learningRate) || learningRate <= 0.0) { + throw new IllegalArgumentException("learningRate must be finite and greater than 0"); + } + if (maxEpochs <= 0) { + throw new IllegalArgumentException("maxEpochs must be greater than 0"); + } + this.learningRate = learningRate; + this.maxEpochs = maxEpochs; + } + + /** + * Fits the classifier using binary training labels. + * + *

Fitting resets the weights and bias to zero before training. The + * method records whether an entire epoch completed without an update. A + * large {@code learningRate} combined with large feature values can push + * the parameters past the range of {@code double}; the classifier then + * returns to its unfitted state instead of reporting predictions derived + * from non-finite parameters. + * + * @param features training feature vectors + * @param labels corresponding binary labels, each either {@code 0} or + * {@code 1} + * @throws IllegalArgumentException if the training data is invalid + * @throws ArithmeticException if training diverges and the learned + * parameters stop being finite + */ + public void fit(double[][] features, int[] labels) { + validateTrainingData(features, labels); + + weights = new double[features[0].length]; + bias = 0.0; + epochsRun = 0; + converged = false; + + for (int epoch = 0; epoch < maxEpochs; epoch++) { + boolean updated = false; + + for (int sampleIndex = 0; sampleIndex < features.length; sampleIndex++) { + int prediction = rawPredict(features[sampleIndex]); + int error = labels[sampleIndex] - prediction; + + if (error != 0) { + update(features[sampleIndex], error); + updated = true; + } + } + + epochsRun = epoch + 1; + if (!updated) { + converged = true; + break; + } + } + + ensureParametersAreFinite(); + } + + /** + * Predicts the binary label for one sample. + * + * @param sample feature vector to classify + * @return {@code 0} or {@code 1} + * @throws IllegalStateException if the classifier has not been fitted + * @throws IllegalArgumentException if the sample is invalid + */ + public int predict(double[] sample) { + ensureFitted(); + validateSample(sample); + return rawPredict(sample); + } + + /** + * Predicts binary labels for a batch of samples. + * + * @param samples feature vectors to classify + * @return one prediction for each sample + * @throws IllegalStateException if the classifier has not been fitted + * @throws IllegalArgumentException if the batch or one of its samples is + * invalid + */ + public int[] predict(double[][] samples) { + ensureFitted(); + if (samples == null) { + throw new IllegalArgumentException("samples cannot be null"); + } + + int[] predictions = new int[samples.length]; + for (int sampleIndex = 0; sampleIndex < samples.length; sampleIndex++) { + predictions[sampleIndex] = predict(samples[sampleIndex]); + } + return predictions; + } + + /** + * Returns a defensive copy of the learned feature weights. + * + * @return learned weights in feature order + * @throws IllegalStateException if the classifier has not been fitted + */ + public double[] getWeights() { + ensureFitted(); + return weights.clone(); + } + + /** + * Returns the learned bias term. + * + * @return learned bias + * @throws IllegalStateException if the classifier has not been fitted + */ + public double getBias() { + ensureFitted(); + return bias; + } + + /** + * Reports whether training completed with an update-free epoch. + * + * @return {@code true} if an epoch completed without an update + * @throws IllegalStateException if the classifier has not been fitted + */ + public boolean hasConverged() { + ensureFitted(); + return converged; + } + + /** + * Returns the number of epochs performed by the last fit. + * + * @return number of completed epochs + * @throws IllegalStateException if the classifier has not been fitted + */ + public int getEpochsRun() { + ensureFitted(); + return epochsRun; + } + + private int rawPredict(double[] sample) { + double weightedSum = bias; + for (int featureIndex = 0; featureIndex < weights.length; featureIndex++) { + weightedSum += weights[featureIndex] * sample[featureIndex]; + } + return weightedSum >= 0.0 ? 1 : 0; + } + + private void update(double[] sample, int error) { + for (int featureIndex = 0; featureIndex < weights.length; featureIndex++) { + weights[featureIndex] += learningRate * error * sample[featureIndex]; + } + bias += learningRate * error; + } + + private void ensureParametersAreFinite() { + if (!Double.isFinite(bias) || !isFinite(weights)) { + weights = null; + throw new ArithmeticException("training diverged; try a smaller learningRate or scaled features"); + } + } + + private void ensureFitted() { + if (weights == null) { + throw new IllegalStateException("classifier has not been fitted"); + } + } + + private void validateTrainingData(double[][] features, int[] labels) { + if (features == null || labels == null) { + throw new IllegalArgumentException("features and labels cannot be null"); + } + if (features.length == 0 || labels.length == 0) { + throw new IllegalArgumentException("features and labels cannot be empty"); + } + if (features.length != labels.length) { + throw new IllegalArgumentException("features and labels must have the same length"); + } + if (features[0] == null || features[0].length == 0) { + throw new IllegalArgumentException("feature vectors cannot be null or empty"); + } + + int featureCount = features[0].length; + for (int sampleIndex = 0; sampleIndex < features.length; sampleIndex++) { + double[] sample = features[sampleIndex]; + if (sample == null) { + throw new IllegalArgumentException("feature vectors cannot be null or empty"); + } + if (sample.length != featureCount) { + throw new IllegalArgumentException("all feature vectors must have the same dimension"); + } + validateFiniteValues(sample); + if (labels[sampleIndex] != 0 && labels[sampleIndex] != 1) { + throw new IllegalArgumentException("labels must be either 0 or 1"); + } + } + } + + private void validateSample(double[] sample) { + if (sample == null || sample.length != weights.length) { + throw new IllegalArgumentException("sample must match the training feature dimension"); + } + validateFiniteValues(sample); + } + + private static void validateFiniteValues(double[] values) { + if (!isFinite(values)) { + throw new IllegalArgumentException("feature values must be finite"); + } + } + + private static boolean isFinite(double[] values) { + for (double value : values) { + if (!Double.isFinite(value)) { + return false; + } + } + return true; + } +} diff --git a/src/test/java/com/thealgorithms/machinelearning/PerceptronTest.java b/src/test/java/com/thealgorithms/machinelearning/PerceptronTest.java new file mode 100644 index 000000000000..2dce0a0642ca --- /dev/null +++ b/src/test/java/com/thealgorithms/machinelearning/PerceptronTest.java @@ -0,0 +1,163 @@ +package com.thealgorithms.machinelearning; + +import static org.junit.jupiter.api.Assertions.assertArrayEquals; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import org.junit.jupiter.api.Assertions; +import org.junit.jupiter.api.Test; + +class PerceptronTest { + + @Test + void learnsAndFunction() { + double[][] features = {{0, 0}, {0, 1}, {1, 0}, {1, 1}}; + int[] labels = {0, 0, 0, 1}; + + Perceptron perceptron = new Perceptron(1.0, 20); + perceptron.fit(features, labels); + + assertArrayEquals(labels, perceptron.predict(features)); + assertTrue(perceptron.hasConverged()); + assertTrue(perceptron.getEpochsRun() <= 20); + } + + @Test + void learnsExpectedWeightsAndBias() { + Perceptron perceptron = new Perceptron(1.0, 20); + perceptron.fit(new double[][] {{0}, {1}}, new int[] {0, 1}); + + assertArrayEquals(new double[] {1.0}, perceptron.getWeights()); + assertEquals(-1.0, perceptron.getBias()); + assertTrue(perceptron.hasConverged()); + assertEquals(3, perceptron.getEpochsRun()); + } + + @Test + void predictsUnseenSamples() { + double[][] features = {{-2, -1}, {-1, -2}, {1, 2}, {2, 1}}; + int[] labels = {0, 0, 1, 1}; + + Perceptron perceptron = new Perceptron(0.5, 20); + perceptron.fit(features, labels); + + assertEquals(0, perceptron.predict(new double[] {-3, -1})); + assertEquals(1, perceptron.predict(new double[] {3, 1})); + } + + @Test + void batchPredictionMatchesIndividualPredictions() { + double[][] features = {{0, 0}, {0, 1}, {1, 0}, {1, 1}}; + int[] labels = {0, 0, 0, 1}; + double[][] samples = {{0, 0}, {1, 0}, {1, 1}}; + + Perceptron perceptron = new Perceptron(1.0, 20); + perceptron.fit(features, labels); + + assertArrayEquals(new int[] {0, 0, 1}, perceptron.predict(samples)); + int[] individualPredictions = {perceptron.predict(samples[0]), perceptron.predict(samples[1]), perceptron.predict(samples[2])}; + assertArrayEquals(individualPredictions, perceptron.predict(samples)); + } + + @Test + void emptyBatchProducesEmptyPrediction() { + Perceptron perceptron = new Perceptron(1.0, 10); + perceptron.fit(new double[][] {{0}}, new int[] {0}); + + assertArrayEquals(new int[] {}, perceptron.predict(new double[][] {})); + } + + @Test + void nonSeparableDataStopsAtEpochLimitWithoutConverging() { + double[][] features = {{0, 0}, {0, 1}, {1, 0}, {1, 1}}; + int[] labels = {0, 1, 1, 0}; + + Perceptron perceptron = new Perceptron(1.0, 8); + perceptron.fit(features, labels); + + Assertions.assertFalse(perceptron.hasConverged()); + assertEquals(8, perceptron.getEpochsRun()); + } + + @Test + void fittingResetsPreviousModel() { + Perceptron perceptron = new Perceptron(1.0, 20); + perceptron.fit(new double[][] {{0}, {1}}, new int[] {0, 1}); + perceptron.fit(new double[][] {{0}, {1}}, new int[] {1, 0}); + + assertArrayEquals(new int[] {1, 0}, perceptron.predict(new double[][] {{0}, {1}})); + } + + @Test + void weightsAreReturnedAsDefensiveCopy() { + Perceptron perceptron = new Perceptron(1.0, 10); + perceptron.fit(new double[][] {{0}, {1}}, new int[] {0, 1}); + + double[] weights = perceptron.getWeights(); + weights[0] = 1000; + + assertEquals(1, perceptron.predict(new double[] {1})); + } + + @Test + void predictionBeforeFitThrows() { + Perceptron perceptron = new Perceptron(1.0, 10); + + assertThrows(IllegalStateException.class, () -> perceptron.predict(new double[] {1})); + assertThrows(IllegalStateException.class, () -> perceptron.predict(new double[][] {})); + assertThrows(IllegalStateException.class, perceptron::getWeights); + assertThrows(IllegalStateException.class, perceptron::getBias); + assertThrows(IllegalStateException.class, perceptron::hasConverged); + assertThrows(IllegalStateException.class, perceptron::getEpochsRun); + } + + @Test + void invalidHyperparametersThrow() { + assertThrows(IllegalArgumentException.class, () -> new Perceptron(0.0, 10)); + assertThrows(IllegalArgumentException.class, () -> new Perceptron(-1.0, 10)); + assertThrows(IllegalArgumentException.class, () -> new Perceptron(Double.NaN, 10)); + assertThrows(IllegalArgumentException.class, () -> new Perceptron(Double.POSITIVE_INFINITY, 10)); + assertThrows(IllegalArgumentException.class, () -> new Perceptron(1.0, 0)); + assertThrows(IllegalArgumentException.class, () -> new Perceptron(1.0, -1)); + } + + @Test + void invalidTrainingDataThrows() { + Perceptron perceptron = new Perceptron(1.0, 10); + + assertThrows(IllegalArgumentException.class, () -> perceptron.fit(null, new int[] {0})); + assertThrows(IllegalArgumentException.class, () -> perceptron.fit(new double[][] {{0}}, null)); + assertThrows(IllegalArgumentException.class, () -> perceptron.fit(new double[][] {}, new int[] {})); + assertThrows(IllegalArgumentException.class, () -> perceptron.fit(new double[][] {{0}}, new int[] {})); + assertThrows(IllegalArgumentException.class, () -> perceptron.fit(new double[][] {{0}, {1}}, new int[] {0})); + assertThrows(IllegalArgumentException.class, () -> perceptron.fit(new double[][] {{0}, {1, 2}}, new int[] {0, 1})); + assertThrows(IllegalArgumentException.class, () -> perceptron.fit(new double[][] {null}, new int[] {0})); + assertThrows(IllegalArgumentException.class, () -> perceptron.fit(new double[][] {{0}, null}, new int[] {0, 1})); + assertThrows(IllegalArgumentException.class, () -> perceptron.fit(new double[][] {{}}, new int[] {0})); + assertThrows(IllegalArgumentException.class, () -> perceptron.fit(new double[][] {{0}}, new int[] {2})); + assertThrows(IllegalArgumentException.class, () -> perceptron.fit(new double[][] {{Double.NaN}}, new int[] {0})); + assertThrows(IllegalArgumentException.class, () -> perceptron.fit(new double[][] {{Double.POSITIVE_INFINITY}}, new int[] {0})); + } + + @Test + void invalidPredictionDataThrows() { + Perceptron perceptron = new Perceptron(1.0, 10); + perceptron.fit(new double[][] {{0, 0}}, new int[] {0}); + + assertThrows(IllegalArgumentException.class, () -> perceptron.predict((double[]) null)); + assertThrows(IllegalArgumentException.class, () -> perceptron.predict(new double[] {0})); + assertThrows(IllegalArgumentException.class, () -> perceptron.predict(new double[] {0, Double.NaN})); + assertThrows(IllegalArgumentException.class, () -> perceptron.predict((double[][]) null)); + assertThrows(IllegalArgumentException.class, () -> perceptron.predict(new double[][] {{0, 0}, null})); + } + + @Test + void divergingTrainingIsRejectedAndLeavesClassifierUnfitted() { + Perceptron perceptron = new Perceptron(1.0e300, 5); + + assertThrows(ArithmeticException.class, () -> perceptron.fit(new double[][] {{1.0e300}, {1.0e300}}, new int[] {0, 1})); + assertThrows(IllegalStateException.class, perceptron::getWeights); + assertThrows(IllegalStateException.class, perceptron::getBias); + } +} From 743ff5eb0944d8a3ed25d73fc992f5a69a36134d Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sat, 26 Sep 2026 08:54:00 +0300 Subject: [PATCH 28/92] chore(deps): bump github/codeql-action from 4.38.0 to 4.38.1 in /.github/workflows (#7618) chore(deps): bump github/codeql-action in /.github/workflows Bumps [github/codeql-action](https://github.com/github/codeql-action) from 4.38.0 to 4.38.1. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](https://github.com/github/codeql-action/compare/v4.38.0...v4.38.1) --- updated-dependencies: - dependency-name: github/codeql-action dependency-version: 4.38.1 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/codeql.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 1eb8e9f2865e..31fe8be603d2 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -30,7 +30,7 @@ jobs: distribution: 'temurin' - name: Initialize CodeQL - uses: github/codeql-action/init@v4.38.0 + uses: github/codeql-action/init@v4.38.1 with: languages: 'java-kotlin' @@ -38,7 +38,7 @@ jobs: run: mvn --batch-mode --update-snapshots verify - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4.38.0 + uses: github/codeql-action/analyze@v4.38.1 with: category: "/language:java-kotlin" @@ -55,12 +55,12 @@ jobs: uses: actions/checkout@v7 - name: Initialize CodeQL - uses: github/codeql-action/init@v4.38.0 + uses: github/codeql-action/init@v4.38.1 with: languages: 'actions' - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4.38.0 + uses: github/codeql-action/analyze@v4.38.1 with: category: "/language:actions" ... From d291e7d8b57ca038d0484f4c5471af926efc3722 Mon Sep 17 00:00:00 2001 From: Oleksandr Klymenko Date: Sun, 27 Sep 2026 12:21:18 +0300 Subject: [PATCH 29/92] feat: add DynamicTimeWarping, alignment distance with a Sakoe-Chiba band (#7619) The Euclidean distance compares sample i with sample i and nothing else, so two recordings of the same gesture, one performed slightly faster, come out as far apart as two unrelated ones. Dynamic time warping looks for the cheapest way to line the two series up instead: every point of each series is matched to at least one point of the other, the matching never goes backwards, and the cost is the sum over the matched pairs. That alignment is a shortest path through a grid, and the dynamic program has one line. Left alone the alignment may match one point against an arbitrarily long stretch of the other, so the Sakoe-Chiba band is offered as well: it forbids matches further apart in time than a given width, which rules out those degenerate alignments and narrows the grid that has to be filled. The band has to be at least the difference in length or no alignment exists, and that is rejected rather than returned as infinity. The distance runs in O(min(n, m)) memory over two rows; the warping path itself needs the whole grid and is returned as index pairs. The Javadoc notes that the result is not a metric, so it ranks candidates but cannot be indexed without further care. Signed-off-by: alxkm <19151554+alxkm@users.noreply.github.com> Co-authored-by: alxkm <19151554+alxkm@users.noreply.github.com> --- .../streaming/DynamicTimeWarping.java | 190 +++++++++++++++ .../streaming/DynamicTimeWarpingTest.java | 221 ++++++++++++++++++ 2 files changed, 411 insertions(+) create mode 100644 src/main/java/com/thealgorithms/streaming/DynamicTimeWarping.java create mode 100644 src/test/java/com/thealgorithms/streaming/DynamicTimeWarpingTest.java diff --git a/src/main/java/com/thealgorithms/streaming/DynamicTimeWarping.java b/src/main/java/com/thealgorithms/streaming/DynamicTimeWarping.java new file mode 100644 index 000000000000..52e188cee2c5 --- /dev/null +++ b/src/main/java/com/thealgorithms/streaming/DynamicTimeWarping.java @@ -0,0 +1,190 @@ +package com.thealgorithms.streaming; + +import java.util.Arrays; + +/** + * Dynamic time warping: how far apart two series are once one of them is allowed to be + * stretched and squeezed in time. + * + *

The Euclidean distance compares sample {@code i} with sample {@code i} and nothing else, so two + * recordings of the same gesture, one performed slightly faster, come out as far apart as two + * unrelated ones. Dynamic time warping instead looks for the cheapest way to line the two series up: + * every point of the first has to be matched to at least one point of the second and the other way + * round, the matching may never go backwards, and the cost is the sum over the matched pairs. That + * alignment is a shortest path through a grid, and the dynamic program is the obvious one: + * + *

+ * D[i][j] = |a[i] - b[j]| + min( D[i-1][j], D[i][j-1], D[i-1][j-1] )
+ * 
+ * + *

The three predecessors are exactly the three legal moves: consume a point of the first series, + * of the second, or of both. The answer is the bottom right corner. + * + *

Left alone, the alignment may match one point of a series against an arbitrarily long stretch of + * the other, which is rarely meaningful and costs {@code O(n * m)} regardless. The Sakoe-Chiba band + * forbids matches further apart in time than a given width, which both rules out those degenerate + * alignments and narrows the grid that has to be filled. The band has to be at least the difference + * in length, or no alignment exists at all. + * + *

Note that the result is not a metric: it does not satisfy the triangle inequality, so it can be + * used to rank candidates but not to index them without further care. + * + *

Usage

+ * + *
{@code
+ * double distance = DynamicTimeWarping.distance(query, candidate);
+ * double banded = DynamicTimeWarping.distance(query, candidate, 10);
+ * int[][] alignment = DynamicTimeWarping.path(query, candidate);
+ * }
+ * + *

The distance costs O(n * m) time and O(min(n, m)) memory; the path costs O(n * m) of both, + * because it has to remember the grid. + * + * @see Dynamic time warping + */ +public final class DynamicTimeWarping { + + private DynamicTimeWarping() { + } + + /** + * Returns the warping distance between two series. + * + * @param first the first series, left untouched + * @param second the second series, left untouched + * @return the cost of the cheapest alignment + * @throws IllegalArgumentException if a series is empty or holds a non-finite value + * @throws NullPointerException if a series is {@code null} + */ + public static double distance(double[] first, double[] second) { + return distance(first, second, Math.max(first.length, second.length)); + } + + /** + * Returns the warping distance between two series, with the alignment confined to a Sakoe-Chiba + * band. + * + * @param first the first series, left untouched + * @param second the second series, left untouched + * @param band how far apart in time two matched points may be, at least the difference in length + * @return the cost of the cheapest alignment inside the band + * @throws IllegalArgumentException if a series is empty or holds a non-finite value, or if the + * band is too narrow for any alignment to exist + * @throws NullPointerException if a series is {@code null} + */ + public static double distance(double[] first, double[] second, int band) { + requireSeries(first, "first"); + requireSeries(second, "second"); + requireBand(band, first.length, second.length); + + double[] previous = new double[second.length + 1]; + double[] current = new double[second.length + 1]; + Arrays.fill(previous, Double.POSITIVE_INFINITY); + previous[0] = 0.0; + + for (int i = 1; i <= first.length; i++) { + Arrays.fill(current, Double.POSITIVE_INFINITY); + int from = Math.max(1, i - band); + int to = Math.min(second.length, i + band); + for (int j = from; j <= to; j++) { + double cost = Math.abs(first[i - 1] - second[j - 1]); + double best = Math.min(previous[j], Math.min(current[j - 1], previous[j - 1])); + current[j] = cost + best; + } + double[] swap = previous; + previous = current; + current = swap; + } + return previous[second.length]; + } + + /** + * Returns the cheapest alignment itself. + * + * @param first the first series, left untouched + * @param second the second series, left untouched + * @return the matched pairs of indices, from {@code (0, 0)} to the two last indices + * @throws IllegalArgumentException if a series is empty or holds a non-finite value + * @throws NullPointerException if a series is {@code null} + */ + public static int[][] path(double[] first, double[] second) { + return path(first, second, Math.max(first.length, second.length)); + } + + /** + * Returns the cheapest alignment inside a Sakoe-Chiba band. + * + * @param first the first series, left untouched + * @param second the second series, left untouched + * @param band how far apart in time two matched points may be, at least the difference in length + * @return the matched pairs of indices, from {@code (0, 0)} to the two last indices + * @throws IllegalArgumentException if a series is empty or holds a non-finite value, or if the + * band is too narrow for any alignment to exist + * @throws NullPointerException if a series is {@code null} + */ + public static int[][] path(double[] first, double[] second, int band) { + requireSeries(first, "first"); + requireSeries(second, "second"); + requireBand(band, first.length, second.length); + + double[][] grid = new double[first.length + 1][second.length + 1]; + for (double[] row : grid) { + Arrays.fill(row, Double.POSITIVE_INFINITY); + } + grid[0][0] = 0.0; + + for (int i = 1; i <= first.length; i++) { + int from = Math.max(1, i - band); + int to = Math.min(second.length, i + band); + for (int j = from; j <= to; j++) { + double cost = Math.abs(first[i - 1] - second[j - 1]); + grid[i][j] = cost + Math.min(grid[i - 1][j], Math.min(grid[i][j - 1], grid[i - 1][j - 1])); + } + } + + int steps = 0; + int row = first.length; + int column = second.length; + int[][] reversed = new int[first.length + second.length][2]; + while (row > 0 && column > 0) { + reversed[steps][0] = row - 1; + reversed[steps][1] = column - 1; + steps++; + double diagonal = grid[row - 1][column - 1]; + double above = grid[row - 1][column]; + double left = grid[row][column - 1]; + if (diagonal <= above && diagonal <= left) { + row--; + column--; + } else if (above <= left) { + row--; + } else { + column--; + } + } + + int[][] alignment = new int[steps][2]; + for (int i = 0; i < steps; i++) { + alignment[i] = reversed[steps - 1 - i]; + } + return alignment; + } + + private static void requireSeries(double[] series, String name) { + if (series.length == 0) { + throw new IllegalArgumentException("The " + name + " series must not be empty"); + } + for (double value : series) { + if (!Double.isFinite(value)) { + throw new IllegalArgumentException("Samples must be finite, but the " + name + " series held " + value); + } + } + } + + private static void requireBand(int band, int firstLength, int secondLength) { + int minimum = Math.abs(firstLength - secondLength); + if (band < minimum) { + throw new IllegalArgumentException("The band must be at least the difference in length, " + minimum + ", but was " + band); + } + } +} diff --git a/src/test/java/com/thealgorithms/streaming/DynamicTimeWarpingTest.java b/src/test/java/com/thealgorithms/streaming/DynamicTimeWarpingTest.java new file mode 100644 index 000000000000..5be3b21eb101 --- /dev/null +++ b/src/test/java/com/thealgorithms/streaming/DynamicTimeWarpingTest.java @@ -0,0 +1,221 @@ +package com.thealgorithms.streaming; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.Random; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +class DynamicTimeWarpingTest { + + private static double manhattan(double[] first, double[] second) { + double sum = 0.0; + for (int i = 0; i < first.length; i++) { + sum += Math.abs(first[i] - second[i]); + } + return sum; + } + + private static double[] sine(int length, double period, double phase) { + double[] series = new double[length]; + for (int i = 0; i < length; i++) { + series[i] = Math.sin(2 * Math.PI * i / period + phase); + } + return series; + } + + @Test + void rejectsEmptySeries() { + assertThrows(IllegalArgumentException.class, () -> DynamicTimeWarping.distance(new double[0], new double[] {1.0})); + assertThrows(IllegalArgumentException.class, () -> DynamicTimeWarping.distance(new double[] {1.0}, new double[0])); + assertThrows(IllegalArgumentException.class, () -> DynamicTimeWarping.path(new double[0], new double[] {1.0})); + } + + @ParameterizedTest + @ValueSource(doubles = {Double.NaN, Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY}) + void rejectsNonFiniteSamples(double value) { + double[] good = {1.0, 2.0, 3.0}; + double[] bad = {1.0, value, 3.0}; + + assertThrows(IllegalArgumentException.class, () -> DynamicTimeWarping.distance(bad, good)); + assertThrows(IllegalArgumentException.class, () -> DynamicTimeWarping.distance(good, bad)); + } + + @Test + @DisplayName("a band narrower than the difference in length admits no alignment") + void rejectsABandThatIsTooNarrow() { + double[] shorter = {1.0, 2.0, 3.0}; + double[] longer = {1.0, 2.0, 3.0, 4.0, 5.0, 6.0}; + + assertThrows(IllegalArgumentException.class, () -> DynamicTimeWarping.distance(shorter, longer, 2)); + assertEquals(6.0, DynamicTimeWarping.distance(shorter, longer, 3), 1e-12, "the last point of the short series has to carry 3, 4, 5 and 6"); + } + + @Test + void aSeriesIsAtNoDistanceFromItself() { + double[] series = {1.0, 4.0, 2.0, 8.0, 3.0}; + + assertEquals(0.0, DynamicTimeWarping.distance(series, series)); + } + + @Test + @DisplayName("two flat series a fixed distance apart cost that distance once per sample") + void measuresAConstantOffset() { + double[] first = {1.0, 1.0, 1.0, 1.0}; + double[] second = {3.0, 3.0, 3.0, 3.0}; + + assertEquals(8.0, DynamicTimeWarping.distance(first, second), 1e-12, "the diagonal is the shortest path and every cell costs 2"); + } + + @Test + @DisplayName("a series shifted in value is cheaper than sample by sample, because warping reuses points") + void warpingBeatsTheStraightComparisonOnARamp() { + double[] first = {1.0, 2.0, 3.0, 4.0}; + double[] second = {3.0, 4.0, 5.0, 6.0}; + + assertEquals(6.0, DynamicTimeWarping.distance(first, second), 1e-12); + assertEquals(8.0, manhattan(first, second), 1e-12); + } + + @Test + void isSymmetric() { + Random random = new Random(3L); + for (int trial = 0; trial < 20; trial++) { + double[] first = new double[10 + random.nextInt(20)]; + double[] second = new double[10 + random.nextInt(20)]; + for (int i = 0; i < first.length; i++) { + first[i] = random.nextGaussian(); + } + for (int i = 0; i < second.length; i++) { + second[i] = random.nextGaussian(); + } + + assertEquals(DynamicTimeWarping.distance(first, second), DynamicTimeWarping.distance(second, first), 1e-9); + } + } + + @Test + @DisplayName("warping never costs more than matching sample by sample") + void neverExceedsTheStraightComparison() { + Random random = new Random(11L); + for (int trial = 0; trial < 50; trial++) { + double[] first = new double[30]; + double[] second = new double[30]; + for (int i = 0; i < first.length; i++) { + first[i] = random.nextGaussian(); + second[i] = random.nextGaussian(); + } + + assertTrue(DynamicTimeWarping.distance(first, second) <= manhattan(first, second) + 1e-9); + } + } + + @Test + @DisplayName("a band of zero forces the straight comparison") + void aBandOfZeroIsTheStraightComparison() { + double[] first = {1.0, 5.0, 2.0, 8.0}; + double[] second = {2.0, 4.0, 4.0, 7.0}; + + assertEquals(manhattan(first, second), DynamicTimeWarping.distance(first, second, 0), 1e-12); + } + + @Test + @DisplayName("a narrower band can only cost more") + void aNarrowerBandCostsAtLeastAsMuch() { + double[] first = sine(60, 12.0, 0.0); + double[] second = sine(60, 12.0, 0.9); + + double free = DynamicTimeWarping.distance(first, second); + double banded = DynamicTimeWarping.distance(first, second, 3); + double tight = DynamicTimeWarping.distance(first, second, 1); + + assertTrue(banded >= free - 1e-9, "banded " + banded + " should not be below free " + free); + assertTrue(tight >= banded - 1e-9, "tight " + tight + " should not be below banded " + banded); + } + + @Test + @DisplayName("a shift in time costs almost nothing, where a straight comparison is fooled") + void absorbsAShiftInTime() { + double[] first = sine(60, 12.0, 0.0); + double[] second = sine(60, 12.0, Math.PI / 3); + + double warping = DynamicTimeWarping.distance(first, second); + double straight = manhattan(first, second); + + assertTrue(warping < 0.25 * straight, "warping " + warping + " against straight " + straight); + } + + @Test + @DisplayName("a series stretched in time still matches the original") + void absorbsAStretch() { + double[] original = sine(40, 10.0, 0.0); + double[] stretched = new double[80]; + for (int i = 0; i < stretched.length; i++) { + stretched[i] = original[i / 2]; + } + + double warping = DynamicTimeWarping.distance(original, stretched); + + assertTrue(warping < 1.0, "a stretched copy should be close, but was " + warping); + } + + @Test + @DisplayName("the path runs from corner to corner without ever going backwards") + void thePathIsMonotoneAndComplete() { + double[] first = sine(30, 8.0, 0.0); + double[] second = sine(45, 12.0, 0.4); + + int[][] alignment = DynamicTimeWarping.path(first, second); + + assertEquals(0, alignment[0][0]); + assertEquals(0, alignment[0][1]); + assertEquals(first.length - 1, alignment[alignment.length - 1][0]); + assertEquals(second.length - 1, alignment[alignment.length - 1][1]); + for (int step = 1; step < alignment.length; step++) { + int rowStep = alignment[step][0] - alignment[step - 1][0]; + int columnStep = alignment[step][1] - alignment[step - 1][1]; + assertTrue(rowStep >= 0 && rowStep <= 1, "the path stepped " + rowStep + " rows"); + assertTrue(columnStep >= 0 && columnStep <= 1, "the path stepped " + columnStep + " columns"); + assertTrue(rowStep + columnStep > 0, "the path stood still"); + } + } + + @Test + @DisplayName("the cost of the path is the distance") + void thePathCostsWhatTheDistanceSays() { + double[] first = sine(25, 7.0, 0.0); + double[] second = sine(33, 9.0, 0.2); + + int[][] alignment = DynamicTimeWarping.path(first, second); + double cost = 0.0; + for (int[] pair : alignment) { + cost += Math.abs(first[pair[0]] - second[pair[1]]); + } + + assertEquals(DynamicTimeWarping.distance(first, second), cost, 1e-9); + } + + @Test + void handlesSeriesOfOneSample() { + assertEquals(3.0, DynamicTimeWarping.distance(new double[] {1.0}, new double[] {4.0}), 1e-12); + assertEquals(1, DynamicTimeWarping.path(new double[] {1.0}, new double[] {4.0}).length); + } + + @Test + void leavesTheSeriesUntouched() { + double[] first = {1.0, 2.0, 3.0}; + double[] second = {4.0, 5.0}; + double[] firstCopy = first.clone(); + double[] secondCopy = second.clone(); + + DynamicTimeWarping.distance(first, second); + DynamicTimeWarping.path(first, second); + + org.junit.jupiter.api.Assertions.assertArrayEquals(firstCopy, first); + org.junit.jupiter.api.Assertions.assertArrayEquals(secondCopy, second); + } +} From 550a7ed124324a9c9ad3ff664123dc41ffdbba7d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dilara=20=C3=87etin?= <155580901+dilaraacetin@users.noreply.github.com> Date: Sun, 27 Sep 2026 16:49:52 +0300 Subject: [PATCH 30/92] Feature/winternitz ots (#7621) * feat(ciphers): add Winternitz one-time signature (WOTS) * test(ciphers): add tests for Winternitz one-time signature --- .../ciphers/WinternitzSignature.java | 227 ++++++++++++++++++ .../ciphers/WinternitzSignatureTest.java | 178 ++++++++++++++ 2 files changed, 405 insertions(+) create mode 100644 src/main/java/com/thealgorithms/ciphers/WinternitzSignature.java create mode 100644 src/test/java/com/thealgorithms/ciphers/WinternitzSignatureTest.java diff --git a/src/main/java/com/thealgorithms/ciphers/WinternitzSignature.java b/src/main/java/com/thealgorithms/ciphers/WinternitzSignature.java new file mode 100644 index 000000000000..e4239b170adb --- /dev/null +++ b/src/main/java/com/thealgorithms/ciphers/WinternitzSignature.java @@ -0,0 +1,227 @@ +package com.thealgorithms.ciphers; + +import java.security.MessageDigest; +import java.security.NoSuchAlgorithmException; +import java.security.SecureRandom; + +/** + * Winternitz one-time signatures (WOTS) are a hash-based post-quantum signature scheme and a + * size-optimized version of the Lamport signature. + * + *

The message digest is split into base-{@code w} digits and each digit is signed with a hash + * chain: secret {@code sk[i]} is hashed {@code m[i]} times, while the public key is the chain end + * after {@code w - 1} hashes. A larger {@code w} gives smaller signatures but more hashing + * (133, 67 and 34 values for {@code w} = 4, 16 and 256). + * + *

Security relies only on the one-wayness of the hash function, which is why the scheme is + * considered quantum-resistant. A checksum over the digits is signed too, so an attacker cannot + * hash revealed values further to forge a signature. Each key pair can sign only one message, + * since a second signature reveals enough chain values to forge new ones. + * + *

WOTS is the building block of XMSS and SPHINCS+, which use the WOTS+ variant with per-step + * bitmasks. This implementation is educational and must not be used in production. + * + *

Reference: Wikipedia: Hash-based cryptography + * + * @author dilaraacetin + * @see LamportSignature + */ +public final class WinternitzSignature { + + // SHA-256 output length in bytes + private static final int HASH_BYTES = 32; + private static final int DEFAULT_W = 16; + + private final Parameters parameters; + private final byte[][] privateKey; + private final byte[][] publicKey; + private boolean used; + + /** + * Generates a new key pair with the default Winternitz parameter {@code w = 16}. + */ + public WinternitzSignature() { + this(DEFAULT_W); + } + + /** + * Generates a new key pair with the given Winternitz parameter. + * + * @param w the Winternitz parameter; must be 4, 16 or 256 + * @throws IllegalArgumentException if {@code w} is not a supported value + */ + public WinternitzSignature(int w) { + this.parameters = Parameters.forW(w); + SecureRandom secureRandom = new SecureRandom(); + privateKey = new byte[parameters.len()][HASH_BYTES]; + publicKey = new byte[parameters.len()][]; + for (int i = 0; i < parameters.len(); i++) { + secureRandom.nextBytes(privateKey[i]); + publicKey[i] = chain(privateKey[i], w - 1); + } + } + + /** + * Returns a copy of the public key. + * + * @return {@code len} hash chain end values, each 32 bytes long + */ + public byte[][] getPublicKey() { + return deepCopy(publicKey); + } + + /** + * Signs a message. A key pair can sign only one message. + * + * @param message the message to sign + * @return the signature: {@code len} values of 32 bytes each (67 values for {@code w = 16}) + * @throws IllegalArgumentException if the message is null + * @throws IllegalStateException if this key pair has already been used to sign a message + */ + public byte[][] sign(byte[] message) { + if (message == null) { + throw new IllegalArgumentException("message must not be null"); + } + if (used) { + throw new IllegalStateException("This Winternitz key pair can only sign one message"); + } + used = true; + + int[] digits = messageDigits(hash(message), parameters); + byte[][] signature = new byte[parameters.len()][]; + for (int i = 0; i < parameters.len(); i++) { + signature[i] = chain(privateKey[i], digits[i]); + } + return signature; + } + + /** + * Verifies a signature against a public key. Using a different {@code w} than the signer + * causes a size mismatch and an {@link IllegalArgumentException}. + * + * @param message the signed message + * @param signature the signature to check + * @param publicKey the public key of the signer + * @param w the Winternitz parameter used to create the key pair; must be 4, 16 or 256 + * @return true if the signature is valid for the message and public key, false otherwise + * @throws IllegalArgumentException if an argument is null, {@code w} is unsupported, or the + * signature or public key is malformed + */ + public static boolean verify(byte[] message, byte[][] signature, byte[][] publicKey, int w) { + Parameters params = Parameters.forW(w); + if (message == null) { + throw new IllegalArgumentException("message must not be null"); + } + validateShape(signature, params.len(), "signature"); + validateShape(publicKey, params.len(), "publicKey"); + + int[] digits = messageDigits(hash(message), params); + for (int i = 0; i < params.len(); i++) { + // complete the chain: m[i] + (w - 1 - m[i]) = w - 1 steps + byte[] chainEnd = chain(signature[i], w - 1 - digits[i]); + if (!MessageDigest.isEqual(chainEnd, publicKey[i])) { + return false; + } + } + return true; + } + + /** + * Parameters derived from {@code w}: {@code len1} message chains and {@code len2} checksum chains. + */ + record Parameters(int w, int log2w, int len1, int len2) { + + static Parameters forW(int w) { + if (w != 4 && w != 16 && w != 256) { + throw new IllegalArgumentException("w must be 4, 16 or 256, got " + w); + } + int log2w = Integer.numberOfTrailingZeros(w); + // len1 = ceil(8n / log2(w)) + int len1 = (8 * HASH_BYTES + log2w - 1) / log2w; + // len2 = floor(log2(len1 * (w - 1)) / log2(w)) + 1 + int maxChecksumBits = 32 - Integer.numberOfLeadingZeros(len1 * (w - 1)); + int len2 = (maxChecksumBits - 1) / log2w + 1; + return new Parameters(w, log2w, len1, len2); + } + + int len() { + return len1 + len2; + } + } + + /** + * Converts a digest into {@code len1} base-{@code w} message digits followed by {@code len2} + * checksum digits. Shared by sign and verify. + */ + private static int[] messageDigits(byte[] digest, Parameters params) { + int[] digits = new int[params.len()]; + int mask = params.w() - 1; + + // split the digest into log2(w)-bit digits + int bitsLeft = 0; + int currentByte = 0; + int byteIndex = 0; + for (int i = 0; i < params.len1(); i++) { + if (bitsLeft == 0) { + currentByte = digest[byteIndex++] & 0xFF; // unsigned byte + bitsLeft = 8; + } + bitsLeft -= params.log2w(); + digits[i] = (currentByte >> bitsLeft) & mask; + } + + // checksum C = sum(w - 1 - m[i]) + int checksum = 0; + for (int i = 0; i < params.len1(); i++) { + checksum += mask - digits[i]; + } + + // write C as len2 base-w digits, most significant first + for (int i = params.len() - 1; i >= params.len1(); i--) { + digits[i] = checksum & mask; + checksum >>>= params.log2w(); + } + return digits; + } + + /** + * Hashes {@code x} {@code iterations} times; returns a copy of {@code x} for zero iterations. + */ + private static byte[] chain(byte[] x, int iterations) { + byte[] result = x.clone(); + for (int i = 0; i < iterations; i++) { + result = hash(result); + } + return result; + } + + private static byte[] hash(byte[] data) { + try { + return MessageDigest.getInstance("SHA-256").digest(data); + } catch (NoSuchAlgorithmException e) { + throw new AssertionError("SHA-256 is required by the Java SE specification", e); + } + } + + private static void validateShape(byte[][] values, int expectedLength, String name) { + if (values == null) { + throw new IllegalArgumentException(name + " must not be null"); + } + if (values.length != expectedLength) { + throw new IllegalArgumentException(name + " must contain exactly " + expectedLength + " values, got " + values.length); + } + for (byte[] value : values) { + if (value == null || value.length != HASH_BYTES) { + throw new IllegalArgumentException(name + " values must be exactly " + HASH_BYTES + " bytes long"); + } + } + } + + private static byte[][] deepCopy(byte[][] values) { + byte[][] copy = new byte[values.length][]; + for (int i = 0; i < values.length; i++) { + copy[i] = values[i].clone(); + } + return copy; + } +} diff --git a/src/test/java/com/thealgorithms/ciphers/WinternitzSignatureTest.java b/src/test/java/com/thealgorithms/ciphers/WinternitzSignatureTest.java new file mode 100644 index 000000000000..908bf9b53855 --- /dev/null +++ b/src/test/java/com/thealgorithms/ciphers/WinternitzSignatureTest.java @@ -0,0 +1,178 @@ +package com.thealgorithms.ciphers; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.nio.charset.StandardCharsets; +import java.util.Arrays; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.CsvSource; +import org.junit.jupiter.params.provider.ValueSource; + +class WinternitzSignatureTest { + + private static final byte[] MESSAGE = "hello winternitz".getBytes(StandardCharsets.UTF_8); + + @Test + void testValidSignatureVerifies() { + WinternitzSignature keyPair = new WinternitzSignature(); + + byte[][] signature = keyPair.sign(MESSAGE); + + assertTrue(WinternitzSignature.verify(MESSAGE, signature, keyPair.getPublicKey(), 16)); + } + + @ParameterizedTest + @ValueSource(ints = {4, 16, 256}) + void testSignAndVerifyForEverySupportedW(int w) { + WinternitzSignature keyPair = new WinternitzSignature(w); + + byte[][] signature = keyPair.sign(MESSAGE); + + assertTrue(WinternitzSignature.verify(MESSAGE, signature, keyPair.getPublicKey(), w)); + } + + @ParameterizedTest + @CsvSource({"4, 128, 5", "16, 64, 3", "256, 32, 2"}) + void testParametersAreDerivedFromW(int w, int expectedLen1, int expectedLen2) { + WinternitzSignature.Parameters parameters = WinternitzSignature.Parameters.forW(w); + + assertEquals(expectedLen1, parameters.len1()); + assertEquals(expectedLen2, parameters.len2()); + assertEquals(expectedLen1 + expectedLen2, parameters.len()); + } + + @Test + void testDefaultSignatureHas67Values() { + WinternitzSignature keyPair = new WinternitzSignature(); + + byte[][] signature = keyPair.sign(MESSAGE); + + assertEquals(67, signature.length); + assertEquals(67, keyPair.getPublicKey().length); + for (byte[] value : signature) { + assertEquals(32, value.length); + } + } + + @Test + void testTamperedMessageFailsVerification() { + WinternitzSignature keyPair = new WinternitzSignature(); + byte[] message = MESSAGE.clone(); + byte[][] signature = keyPair.sign(message); + + message[0] ^= 0x01; + + assertFalse(WinternitzSignature.verify(message, signature, keyPair.getPublicKey(), 16)); + } + + @Test + void testTamperedSignatureFailsVerification() { + WinternitzSignature keyPair = new WinternitzSignature(); + byte[][] signature = keyPair.sign(MESSAGE); + + signature[10][0] ^= 0x01; + + assertFalse(WinternitzSignature.verify(MESSAGE, signature, keyPair.getPublicKey(), 16)); + } + + @Test + void testDifferentPublicKeyDoesNotVerify() { + WinternitzSignature keyPair1 = new WinternitzSignature(); + WinternitzSignature keyPair2 = new WinternitzSignature(); + + byte[][] signature = keyPair1.sign(MESSAGE); + + assertFalse(WinternitzSignature.verify(MESSAGE, signature, keyPair2.getPublicKey(), 16)); + } + + @Test + void testVerifyingWithDifferentWThrowsException() { + WinternitzSignature keyPair = new WinternitzSignature(16); + byte[][] signature = keyPair.sign(MESSAGE); + byte[][] publicKey = keyPair.getPublicKey(); + + assertThrows(IllegalArgumentException.class, () -> WinternitzSignature.verify(MESSAGE, signature, publicKey, 4)); + } + + @Test + void testSecondSignatureThrowsException() { + WinternitzSignature keyPair = new WinternitzSignature(); + byte[] second = "second message".getBytes(StandardCharsets.UTF_8); + + keyPair.sign(MESSAGE); + + assertThrows(IllegalStateException.class, () -> keyPair.sign(second)); + } + + @Test + void testNullAndMalformedInput() { + WinternitzSignature keyPair = new WinternitzSignature(); + byte[][] publicKey = keyPair.getPublicKey(); + byte[][] signature = keyPair.sign(MESSAGE); + byte[][] tooShort = Arrays.copyOf(signature, 66); + byte[][] wrongValueLength = signature.clone(); + wrongValueLength[0] = new byte[31]; + byte[][] nullValue = signature.clone(); + nullValue[0] = null; + + assertThrows(IllegalArgumentException.class, () -> new WinternitzSignature().sign(null)); + assertThrows(IllegalArgumentException.class, () -> WinternitzSignature.verify(null, signature, publicKey, 16)); + assertThrows(IllegalArgumentException.class, () -> WinternitzSignature.verify(MESSAGE, null, publicKey, 16)); + assertThrows(IllegalArgumentException.class, () -> WinternitzSignature.verify(MESSAGE, tooShort, publicKey, 16)); + assertThrows(IllegalArgumentException.class, () -> WinternitzSignature.verify(MESSAGE, wrongValueLength, publicKey, 16)); + assertThrows(IllegalArgumentException.class, () -> WinternitzSignature.verify(MESSAGE, nullValue, publicKey, 16)); + assertThrows(IllegalArgumentException.class, () -> WinternitzSignature.verify(MESSAGE, signature, null, 16)); + assertThrows(IllegalArgumentException.class, () -> WinternitzSignature.verify(MESSAGE, signature, tooShort, 16)); + } + + @ParameterizedTest + @ValueSource(ints = {0, 3, 15, -16, 2, 8, 512}) + void testUnsupportedWThrowsException(int w) { + assertThrows(IllegalArgumentException.class, () -> new WinternitzSignature(w)); + assertThrows(IllegalArgumentException.class, () -> WinternitzSignature.verify(MESSAGE, new byte[67][32], new byte[67][32], w)); + } + + @Test + void testModifyingReturnedPublicKeyDoesNotChangeInternalState() { + WinternitzSignature keyPair = new WinternitzSignature(); + byte[][] signature = keyPair.sign(MESSAGE); + + byte[][] exposed = keyPair.getPublicKey(); + exposed[0][0] ^= 0x01; + exposed[1] = new byte[32]; + + assertTrue(WinternitzSignature.verify(MESSAGE, signature, keyPair.getPublicKey(), 16)); + } + + @Test + void testEmptyAndLongMessages() { + byte[] empty = new byte[0]; + byte[] longMessage = new byte[8192]; + for (int i = 0; i < longMessage.length; i++) { + longMessage[i] = (byte) i; + } + WinternitzSignature keyPair1 = new WinternitzSignature(); + WinternitzSignature keyPair2 = new WinternitzSignature(); + + byte[][] emptySignature = keyPair1.sign(empty); + byte[][] longSignature = keyPair2.sign(longMessage); + + assertTrue(WinternitzSignature.verify(empty, emptySignature, keyPair1.getPublicKey(), 16)); + assertTrue(WinternitzSignature.verify(longMessage, longSignature, keyPair2.getPublicKey(), 16)); + } + + @Test + void testDifferentMessagesProduceDifferentSignatures() { + WinternitzSignature keyPair1 = new WinternitzSignature(); + WinternitzSignature keyPair2 = new WinternitzSignature(); + + byte[][] signature1 = keyPair1.sign("first message".getBytes(StandardCharsets.UTF_8)); + byte[][] signature2 = keyPair2.sign("second message".getBytes(StandardCharsets.UTF_8)); + + assertFalse(Arrays.deepEquals(signature1, signature2)); + } +} From 3f067087f217afc6c16f0d0ca90d194bd7a55726 Mon Sep 17 00:00:00 2001 From: Oleksandr Klymenko Date: Tue, 29 Sep 2026 14:28:13 +0300 Subject: [PATCH 31/92] feat: add UnscentedKalmanFilter, the Kalman filter that samples the model instead of differentiating it (#7622) The extended filter pushes the covariance through a Jacobian, a straight line drawn at one point, which needs the model to be differentiable, needs the derivative written out, and discards everything beyond first order. The unscented filter picks 2n + 1 sigma points whose mean and covariance are exactly those of the estimate, sends each through the real model and reads the new mean and covariance off where they land. The square root that spreads them is a Cholesky factor, so a step costs about what the extended filter does, with no Jacobian anywhere, and the result is right to second order. The defaults are alpha = 1, beta = 2, kappa = 0. The alpha = 1e-3 often quoted puts the sigma points almost on the mean and compensates with a central weight near minus a million, exact on paper and six digits lost in floating point. After an update the covariance P - K S K' is symmetrised explicitly, and a covariance that is no longer positive definite is refused with an ArithmeticException instead of being given a square root that does not exist. The innovation covariance is inverted with the existing matrix.InverseOfMatrix. Tests: the sigma points reproduce the mean and covariance of the estimate exactly, the mean and variance of x^2 come out exact where the extended filter misses both, a linear model agrees with the extended filter to 1e-9 over 500 steps, and a target seen only as a range is tracked without writing a derivative. Signed-off-by: alxkm <19151554+alxkm@users.noreply.github.com> Co-authored-by: alxkm <19151554+alxkm@users.noreply.github.com> --- .../streaming/UnscentedKalmanFilter.java | 561 ++++++++++++++++++ .../streaming/UnscentedKalmanFilterTest.java | 286 +++++++++ 2 files changed, 847 insertions(+) create mode 100644 src/main/java/com/thealgorithms/streaming/UnscentedKalmanFilter.java create mode 100644 src/test/java/com/thealgorithms/streaming/UnscentedKalmanFilterTest.java diff --git a/src/main/java/com/thealgorithms/streaming/UnscentedKalmanFilter.java b/src/main/java/com/thealgorithms/streaming/UnscentedKalmanFilter.java new file mode 100644 index 000000000000..69abdf0eb6c2 --- /dev/null +++ b/src/main/java/com/thealgorithms/streaming/UnscentedKalmanFilter.java @@ -0,0 +1,561 @@ +package com.thealgorithms.streaming; + +import com.thealgorithms.matrix.InverseOfMatrix; +import java.util.Arrays; +import java.util.function.Function; +import java.util.function.UnaryOperator; + +/** + * The unscented Kalman filter: a Kalman filter for a nonlinear model that samples the model + * instead of differentiating it. + * + *

The extended filter pushes the covariance through a Jacobian, which is a straight line drawn at + * one point. That needs the model to be differentiable, needs somebody to write the derivative, and + * throws away everything the model does beyond first order. The unscented filter takes the opposite + * route. It picks a small, deterministic set of sigma points whose mean and covariance are + * exactly those of the current estimate, sends every one of them through the real model, and reads + * the new mean and covariance off where they land: + * + *

+ * lambda = alpha^2 (n + kappa) - n
+ * X_0 = x,   X_i = x + [sqrt((n + lambda) P)]_i,   X_{i+n} = x - [sqrt((n + lambda) P)]_i
+ * Wm_0 = lambda / (n + lambda),   Wc_0 = Wm_0 + 1 - alpha^2 + beta,   W_i = 1 / (2 (n + lambda))
+ * 
+ * + *

The square root is the Cholesky factor, so a step costs {@code 2n + 1} evaluations of the model + * and one factorisation, about what the extended filter costs, with no Jacobian anywhere. The payoff + * is accuracy: the transformed mean and covariance are right to second order for any model, where + * the extended filter is right to first. For {@code x^2} with {@code x} normally distributed, the + * extended filter predicts a mean of {@code mu^2} and misses the {@code sigma^2} that the spread + * itself contributes; the unscented one gets the mean exactly, and with the defaults it gets the + * variance {@code 4 mu^2 sigma^2 + 2 sigma^4} exactly as well. For a linear model it reduces to the + * ordinary Kalman filter, step for step. + * + *

The three parameters are left at {@code alpha = 1}, {@code beta = 2}, {@code kappa = 0}. The + * value {@code alpha = 1e-3} often quoted from the literature puts the sigma points almost on top of + * the mean and compensates with a central weight of about minus a million, which is exact on paper + * and a loss of six digits in floating point. {@code beta = 2} is the optimal choice for a Gaussian + * prior and is what makes the variance of the quadratic above come out exact. + * + *

After an update the covariance {@code P - K S K'} is symmetrised explicitly. The subtraction is + * symmetric in exact arithmetic but not after rounding, and a covariance that has drifted out of + * symmetry eventually fails the Cholesky factorisation of the next step. When that factorisation does + * fail, because the covariance has stopped being positive definite, the step is refused with an + * {@link ArithmeticException} rather than carried on with a square root that does not exist. + * + *

Usage

+ * + *
{@code
+ * UnscentedKalmanFilter filter = new UnscentedKalmanFilter(new double[] {0.0, 1.0}, identity);
+ * filter.predict(state -> new double[] {state[0] + dt * state[1], state[1]}, processNoise);
+ * filter.update(new double[] {range}, state -> new double[] {Math.hypot(state[0], offset)}, measurementNoise);
+ * }
+ * + *

A step costs O(n^3) for the factorisation plus {@code 2n + 1} calls of the model. The inversion + * of the innovation covariance reuses {@link InverseOfMatrix#invert(double[][])}. This class is not + * thread-safe. + * + * @see ExtendedKalmanFilter + * @see KalmanFilter + * @see Unscented Kalman filter + */ +public final class UnscentedKalmanFilter { + + /** Spread of the sigma points used when none is given. */ + public static final double DEFAULT_ALPHA = 1.0; + + /** Prior knowledge of the distribution used when none is given, optimal for a Gaussian. */ + public static final double DEFAULT_BETA = 2.0; + + /** Secondary scaling used when none is given. */ + public static final double DEFAULT_KAPPA = 0.0; + + private final int stateSize; + private final double alpha; + private final double beta; + private final double kappa; + private final double lambda; + private final double[] meanWeights; + private final double[] covarianceWeights; + + private double[] state; + private double[][] covariance; + private double[] innovation; + private long predictions; + private long corrections; + + /** + * Creates a filter with the default sigma point parameters. + * + * @param initialState the first guess at the state, copied + * @param initialCovariance how uncertain that guess is, copied + * @throws IllegalArgumentException if the state is empty, if the covariance is not square and of + * the same size, or if either holds a value that is not finite + * @throws NullPointerException if an argument is {@code null} + */ + public UnscentedKalmanFilter(double[] initialState, double[][] initialCovariance) { + this(initialState, initialCovariance, DEFAULT_ALPHA, DEFAULT_BETA, DEFAULT_KAPPA); + } + + /** + * Creates a filter. + * + * @param initialState the first guess at the state, copied + * @param initialCovariance how uncertain that guess is, copied + * @param alpha how far the sigma points spread from the mean, strictly positive + * @param beta what is known about the shape of the distribution, not negative; two is optimal for + * a Gaussian + * @param kappa a secondary scaling, chosen so that {@code n + kappa} is strictly positive + * @throws IllegalArgumentException if a shape is wrong, a value is not finite, or the parameters do + * not leave {@code n + lambda} strictly positive + * @throws NullPointerException if an argument is {@code null} + */ + public UnscentedKalmanFilter(double[] initialState, double[][] initialCovariance, double alpha, double beta, double kappa) { + if (initialState.length == 0) { + throw new IllegalArgumentException("The state must not be empty"); + } + if (!(alpha > 0.0) || !Double.isFinite(alpha)) { + throw new IllegalArgumentException("The alpha must be finite and strictly positive, but was " + alpha); + } + if (!(beta >= 0.0) || !Double.isFinite(beta)) { + throw new IllegalArgumentException("The beta must be finite and not negative, but was " + beta); + } + if (!Double.isFinite(kappa)) { + throw new IllegalArgumentException("The kappa must be finite, but was " + kappa); + } + + this.stateSize = initialState.length; + requireVector(initialState, stateSize, "initial state"); + requireMatrix(initialCovariance, stateSize, stateSize, "initial covariance"); + + this.alpha = alpha; + this.beta = beta; + this.kappa = kappa; + this.lambda = alpha * alpha * (stateSize + kappa) - stateSize; + double scale = stateSize + lambda; + if (!(scale > 0.0)) { + throw new IllegalArgumentException("The parameters leave n + lambda at " + scale + ", but it must be strictly positive"); + } + + int points = 2 * stateSize + 1; + this.meanWeights = new double[points]; + this.covarianceWeights = new double[points]; + meanWeights[0] = lambda / scale; + covarianceWeights[0] = meanWeights[0] + 1.0 - alpha * alpha + beta; + for (int i = 1; i < points; i++) { + meanWeights[i] = 1.0 / (2.0 * scale); + covarianceWeights[i] = meanWeights[i]; + } + + this.state = initialState.clone(); + this.covariance = copy(initialCovariance); + this.innovation = new double[0]; + } + + /** + * Pushes the estimate forward through the model. + * + * @param transition the model, which maps a state to the state one step later + * @param processNoise how much the model is trusted, a square matrix of the size of the state + * @return a copy of the predicted state + * @throws IllegalArgumentException if the model returns the wrong shape or a value that is not + * finite, or if the process noise has the wrong shape + * @throws ArithmeticException if the covariance is no longer positive definite + * @throws NullPointerException if an argument is {@code null} + */ + public double[] predict(UnaryOperator transition, double[][] processNoise) { + requireMatrix(processNoise, stateSize, stateSize, "process noise"); + + double[][] points = sigmaPoints(); + double[][] propagated = new double[points.length][]; + for (int i = 0; i < points.length; i++) { + propagated[i] = transition.apply(points[i]); + requireVector(propagated[i], stateSize, "propagated sigma point"); + } + + double[] mean = weightedMean(propagated); + double[][] spread = add(weightedCovariance(propagated, mean, propagated, mean), processNoise); + + state = mean; + covariance = symmetrised(spread); + predictions++; + return state.clone(); + } + + /** + * Folds one measurement into the estimate. + * + * @param measurement what the sensor reported + * @param model the measurement model, which maps a state to what the sensor would report + * @param measurementNoise how much the sensor is trusted, a square matrix of the size of the + * measurement + * @return a copy of the corrected state + * @throws IllegalArgumentException if the measurement is empty, if the model returns the wrong + * shape or a value that is not finite, or if the noise has the wrong shape + * @throws ArithmeticException if the covariance is no longer positive definite, or if the + * innovation covariance cannot be inverted + * @throws NullPointerException if an argument is {@code null} + */ + public double[] update(double[] measurement, Function model, double[][] measurementNoise) { + if (measurement.length == 0) { + throw new IllegalArgumentException("The measurement must not be empty"); + } + int measurementSize = measurement.length; + requireVector(measurement, measurementSize, "measurement"); + requireMatrix(measurementNoise, measurementSize, measurementSize, "measurement noise"); + + double[][] points = sigmaPoints(); + double[][] observed = new double[points.length][]; + for (int i = 0; i < points.length; i++) { + observed[i] = model.apply(points[i].clone()); + requireVector(observed[i], measurementSize, "expected measurement"); + } + + double[] expected = weightedMean(observed); + double[][] innovationCovariance = add(weightedCovariance(observed, expected, observed, expected), measurementNoise); + double[][] crossCovariance = weightedCovariance(points, state, observed, expected); + + double[][] inverted = InverseOfMatrix.invert(copy(innovationCovariance)); + requireFiniteMatrix(inverted, "The innovation covariance is singular, so the gain is undefined"); + double[][] gain = multiply(crossCovariance, inverted); + + double[] residual = new double[measurementSize]; + for (int i = 0; i < measurementSize; i++) { + residual[i] = measurement[i] - expected[i]; + } + for (int i = 0; i < stateSize; i++) { + double correction = 0.0; + for (int j = 0; j < measurementSize; j++) { + correction += gain[i][j] * residual[j]; + } + state[i] += correction; + } + + double[][] reduction = multiply(multiply(gain, innovationCovariance), transpose(gain)); + covariance = symmetrised(subtract(covariance, reduction)); + innovation = residual; + corrections++; + return state.clone(); + } + + /** + * Returns the sigma points of the current estimate, whose weighted mean and covariance are the + * estimate and its covariance. + * + * @return {@code 2n + 1} points, the mean first, each a fresh array + * @throws ArithmeticException if the covariance is no longer positive definite + */ + public double[][] sigmaPoints() { + double[][] root = cholesky(scaled(covariance, stateSize + lambda)); + double[][] points = new double[2 * stateSize + 1][]; + points[0] = state.clone(); + for (int column = 0; column < stateSize; column++) { + double[] plus = state.clone(); + double[] minus = state.clone(); + for (int row = 0; row < stateSize; row++) { + plus[row] += root[row][column]; + minus[row] -= root[row][column]; + } + points[column + 1] = plus; + points[column + 1 + stateSize] = minus; + } + return points; + } + + /** + * Returns the weights the sigma points carry when the mean is formed. + * + * @return a copy of the mean weights, which sum to one + */ + public double[] meanWeights() { + return meanWeights.clone(); + } + + /** + * Returns the weights the sigma points carry when the covariance is formed. + * + * @return a copy of the covariance weights + */ + public double[] covarianceWeights() { + return covarianceWeights.clone(); + } + + /** + * Returns the current estimate. + * + * @return a copy of the state + */ + public double[] state() { + return state.clone(); + } + + /** + * Returns how uncertain the current estimate is. + * + * @return a copy of the covariance + */ + public double[][] covariance() { + return copy(covariance); + } + + /** + * Returns the variance of one component of the state. + * + * @param component which component, from zero to the size of the state + * @return the variance of that component + * @throws IllegalArgumentException if {@code component} is outside the state + */ + public double variance(int component) { + if (component < 0 || component >= stateSize) { + throw new IllegalArgumentException("The component must lie in [0, " + (stateSize - 1) + "], but was " + component); + } + return covariance[component][component]; + } + + /** + * Returns the last innovation, how far the sensor was from what the filter expected. + * + * @return a copy of the last residual, empty before the first update + */ + public double[] lastInnovation() { + return innovation.clone(); + } + + /** + * Returns the size of the state. + * + * @return how many components the state holds + */ + public int stateSize() { + return stateSize; + } + + /** + * Returns the spread parameter. + * + * @return alpha + */ + public double alpha() { + return alpha; + } + + /** + * Returns the distribution parameter. + * + * @return beta + */ + public double beta() { + return beta; + } + + /** + * Returns the secondary scaling parameter. + * + * @return kappa + */ + public double kappa() { + return kappa; + } + + /** + * Returns how many predictions have been made since the last reset. + * + * @return the prediction count + */ + public long predictionCount() { + return predictions; + } + + /** + * Returns how many measurements have been folded in since the last reset. + * + * @return the update count + */ + public long updateCount() { + return corrections; + } + + /** + * Restarts the filter from a known estimate. + * + * @param newState the state to carry on from, copied + * @param newCovariance how uncertain it is, copied + * @throws IllegalArgumentException if a shape is wrong or a value is not finite + * @throws NullPointerException if an argument is {@code null} + */ + public void reset(double[] newState, double[][] newCovariance) { + requireVector(newState, stateSize, "state"); + requireMatrix(newCovariance, stateSize, stateSize, "covariance"); + state = newState.clone(); + covariance = copy(newCovariance); + innovation = new double[0]; + predictions = 0; + corrections = 0; + } + + @Override + public String toString() { + return "UnscentedKalmanFilter{state=" + Arrays.toString(state) + ", alpha=" + alpha + ", beta=" + beta + ", kappa=" + kappa + ", predictions=" + predictions + ", updates=" + corrections + "}"; + } + + private double[] weightedMean(double[][] points) { + double[] mean = new double[points[0].length]; + for (int i = 0; i < points.length; i++) { + for (int j = 0; j < mean.length; j++) { + mean[j] += meanWeights[i] * points[i][j]; + } + } + return mean; + } + + private double[][] weightedCovariance(double[][] first, double[] firstMean, double[][] second, double[] secondMean) { + double[][] result = new double[firstMean.length][secondMean.length]; + for (int i = 0; i < first.length; i++) { + for (int row = 0; row < firstMean.length; row++) { + double left = covarianceWeights[i] * (first[i][row] - firstMean[row]); + for (int column = 0; column < secondMean.length; column++) { + result[row][column] += left * (second[i][column] - secondMean[column]); + } + } + } + return result; + } + + /** + * Returns the lower triangular Cholesky factor {@code L} of a symmetric positive definite matrix, + * with {@code L L' = matrix}. + * + * @param matrix the matrix to factorise + * @return its Cholesky factor + * @throws ArithmeticException if the matrix is not positive definite + */ + private static double[][] cholesky(double[][] matrix) { + int size = matrix.length; + double[][] factor = new double[size][size]; + for (int row = 0; row < size; row++) { + for (int column = 0; column <= row; column++) { + double sum = matrix[row][column]; + for (int k = 0; k < column; k++) { + sum -= factor[row][k] * factor[column][k]; + } + if (row == column) { + if (!(sum > 0.0)) { + throw new ArithmeticException("The covariance is not positive definite, so it has no square root to spread the sigma points with"); + } + factor[row][row] = Math.sqrt(sum); + } else { + factor[row][column] = sum / factor[column][column]; + } + } + } + return factor; + } + + private static void requireVector(double[] vector, int size, String name) { + if (vector.length != size) { + throw new IllegalArgumentException("The " + name + " must hold " + size + " values, but held " + vector.length); + } + for (double value : vector) { + if (!Double.isFinite(value)) { + throw new IllegalArgumentException("The " + name + " must be finite, but held " + value); + } + } + } + + private static void requireMatrix(double[][] matrix, int rows, int columns, String name) { + if (matrix.length != rows) { + throw new IllegalArgumentException("The " + name + " must have " + rows + " rows, but had " + matrix.length); + } + for (double[] row : matrix) { + if (row.length != columns) { + throw new IllegalArgumentException("The " + name + " must have " + columns + " columns, but a row had " + row.length); + } + for (double value : row) { + if (!Double.isFinite(value)) { + throw new IllegalArgumentException("The " + name + " must be finite, but held " + value); + } + } + } + } + + private static void requireFiniteMatrix(double[][] matrix, String message) { + for (double[] row : matrix) { + for (double value : row) { + if (!Double.isFinite(value)) { + throw new ArithmeticException(message); + } + } + } + } + + private static double[][] copy(double[][] matrix) { + double[][] copied = new double[matrix.length][]; + for (int i = 0; i < matrix.length; i++) { + copied[i] = matrix[i].clone(); + } + return copied; + } + + private static double[][] scaled(double[][] matrix, double factor) { + double[][] result = new double[matrix.length][matrix[0].length]; + for (int i = 0; i < matrix.length; i++) { + for (int j = 0; j < matrix[i].length; j++) { + result[i][j] = factor * matrix[i][j]; + } + } + return result; + } + + private static double[][] symmetrised(double[][] matrix) { + double[][] result = new double[matrix.length][matrix.length]; + for (int i = 0; i < matrix.length; i++) { + for (int j = 0; j < matrix.length; j++) { + result[i][j] = 0.5 * (matrix[i][j] + matrix[j][i]); + } + } + return result; + } + + private static double[][] transpose(double[][] matrix) { + double[][] result = new double[matrix[0].length][matrix.length]; + for (int i = 0; i < matrix.length; i++) { + for (int j = 0; j < matrix[i].length; j++) { + result[j][i] = matrix[i][j]; + } + } + return result; + } + + private static double[][] multiply(double[][] left, double[][] right) { + double[][] result = new double[left.length][right[0].length]; + for (int i = 0; i < left.length; i++) { + for (int k = 0; k < right.length; k++) { + double factor = left[i][k]; + for (int j = 0; j < right[0].length; j++) { + result[i][j] += factor * right[k][j]; + } + } + } + return result; + } + + private static double[][] add(double[][] left, double[][] right) { + double[][] result = new double[left.length][left[0].length]; + for (int i = 0; i < left.length; i++) { + for (int j = 0; j < left[i].length; j++) { + result[i][j] = left[i][j] + right[i][j]; + } + } + return result; + } + + private static double[][] subtract(double[][] left, double[][] right) { + double[][] result = new double[left.length][left[0].length]; + for (int i = 0; i < left.length; i++) { + for (int j = 0; j < left[i].length; j++) { + result[i][j] = left[i][j] - right[i][j]; + } + } + return result; + } +} diff --git a/src/test/java/com/thealgorithms/streaming/UnscentedKalmanFilterTest.java b/src/test/java/com/thealgorithms/streaming/UnscentedKalmanFilterTest.java new file mode 100644 index 000000000000..fa35d48af8fd --- /dev/null +++ b/src/test/java/com/thealgorithms/streaming/UnscentedKalmanFilterTest.java @@ -0,0 +1,286 @@ +package com.thealgorithms.streaming; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.Random; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +class UnscentedKalmanFilterTest { + + private static final double OFFSET = 5.0; + private static final double INTERVAL = 0.1; + private static final double[][] IDENTITY_2 = {{1.0, 0.0}, {0.0, 1.0}}; + + private static double range(double position) { + return Math.hypot(position, OFFSET); + } + + @Test + void rejectsAnEmptyOrMalformedStart() { + assertThrows(IllegalArgumentException.class, () -> new UnscentedKalmanFilter(new double[0], new double[0][0])); + assertThrows(IllegalArgumentException.class, () -> new UnscentedKalmanFilter(new double[] {1.0, 2.0}, new double[][] {{1.0}})); + assertThrows(IllegalArgumentException.class, () -> new UnscentedKalmanFilter(new double[] {Double.NaN}, new double[][] {{1.0}})); + assertThrows(IllegalArgumentException.class, () -> new UnscentedKalmanFilter(new double[] {1.0}, new double[][] {{Double.POSITIVE_INFINITY}})); + } + + @ParameterizedTest + @ValueSource(doubles = {0.0, -1.0, Double.NaN, Double.POSITIVE_INFINITY}) + void rejectsAnInvalidAlpha(double alpha) { + assertThrows(IllegalArgumentException.class, () -> new UnscentedKalmanFilter(new double[] {0.0}, new double[][] {{1.0}}, alpha, 2.0, 0.0)); + } + + @Test + void rejectsAnInvalidBetaOrKappa() { + assertThrows(IllegalArgumentException.class, () -> new UnscentedKalmanFilter(new double[] {0.0}, new double[][] {{1.0}}, 1.0, -0.5, 0.0)); + assertThrows(IllegalArgumentException.class, () -> new UnscentedKalmanFilter(new double[] {0.0}, new double[][] {{1.0}}, 1.0, 2.0, Double.NaN)); + } + + @Test + @DisplayName("parameters that collapse the sigma points onto the mean are refused") + void rejectsParametersThatLeaveNoSpread() { + assertThrows(IllegalArgumentException.class, () -> new UnscentedKalmanFilter(new double[] {0.0}, new double[][] {{1.0}}, 1.0, 2.0, -1.0)); + } + + @ParameterizedTest + @ValueSource(doubles = {0.001, 0.5, 1.0, 2.0}) + @DisplayName("the mean weights sum to one for any spread") + void theMeanWeightsSumToOne(double alpha) { + UnscentedKalmanFilter filter = new UnscentedKalmanFilter(new double[] {0.0, 0.0, 0.0}, new double[][] {{1, 0, 0}, {0, 1, 0}, {0, 0, 1}}, alpha, 2.0, 0.0); + + double sum = 0.0; + for (double weight : filter.meanWeights()) { + sum += weight; + } + + assertEquals(1.0, sum, 1e-9); + assertEquals(7, filter.meanWeights().length); + assertEquals(7, filter.covarianceWeights().length); + } + + @Test + @DisplayName("the sigma points carry exactly the mean and the covariance of the estimate") + void theSigmaPointsReproduceTheEstimate() { + double[] mean = {1.0, -2.0}; + double[][] covariance = {{2.0, 0.6}, {0.6, 1.0}}; + UnscentedKalmanFilter filter = new UnscentedKalmanFilter(mean, covariance); + + double[][] points = filter.sigmaPoints(); + double[] meanWeights = filter.meanWeights(); + double[] covarianceWeights = filter.covarianceWeights(); + + double[] recovered = new double[2]; + for (int i = 0; i < points.length; i++) { + for (int j = 0; j < 2; j++) { + recovered[j] += meanWeights[i] * points[i][j]; + } + } + double[][] spread = new double[2][2]; + for (int i = 0; i < points.length; i++) { + for (int r = 0; r < 2; r++) { + for (int c = 0; c < 2; c++) { + spread[r][c] += covarianceWeights[i] * (points[i][r] - mean[r]) * (points[i][c] - mean[c]); + } + } + } + + assertEquals(5, points.length); + for (int r = 0; r < 2; r++) { + assertEquals(mean[r], recovered[r], 1e-12); + for (int c = 0; c < 2; c++) { + assertEquals(covariance[r][c], spread[r][c], 1e-12); + } + } + } + + @Test + @DisplayName("the mean and the variance of x squared come out exact, where the extended filter misses both") + void isExactOnAQuadratic() { + double mu = 3.0; + double sigma = 0.5; + double trueMean = mu * mu + sigma * sigma; + double trueVariance = 4 * mu * mu * sigma * sigma + 2 * Math.pow(sigma, 4); + + UnscentedKalmanFilter unscented = new UnscentedKalmanFilter(new double[] {mu}, new double[][] {{sigma * sigma}}); + unscented.predict(state -> new double[] {state[0] * state[0]}, new double[][] {{0.0}}); + + ExtendedKalmanFilter extended = new ExtendedKalmanFilter(new double[] {mu}, new double[][] {{sigma * sigma}}); + extended.predict(state -> new double[] {state[0] * state[0]}, state -> new double[][] {{2 * state[0]}}, new double[][] {{0.0}}); + + assertEquals(trueMean, unscented.state()[0], 1e-12); + assertEquals(trueVariance, unscented.variance(0), 1e-12); + assertEquals(mu * mu, extended.state()[0], 1e-12, "the extended filter drops the sigma squared the spread contributes"); + assertEquals(4 * mu * mu * sigma * sigma, extended.variance(0), 1e-12, "and the 2 sigma^4 of the variance"); + } + + @Test + @DisplayName("on a linear model it is the Kalman filter, step for step") + void agreesWithTheKalmanFilterOnALinearModel() { + double[][] transition = {{1.0, INTERVAL}, {0.0, 1.0}}; + double[][] processNoise = {{1e-3, 0.0}, {0.0, 1e-3}}; + double[][] measurementNoise = {{0.25}}; + UnscentedKalmanFilter unscented = new UnscentedKalmanFilter(new double[] {0.0, 1.0}, IDENTITY_2); + ExtendedKalmanFilter extended = new ExtendedKalmanFilter(new double[] {0.0, 1.0}, IDENTITY_2); + Random random = new Random(3L); + + for (int step = 0; step < 500; step++) { + unscented.predict(state -> new double[] {state[0] + INTERVAL * state[1], state[1]}, processNoise); + extended.predict(transition, processNoise); + + double measurement = 0.1 * step + 0.5 * random.nextGaussian(); + unscented.update(new double[] {measurement}, state -> new double[] {state[0]}, measurementNoise); + extended.update(new double[] {measurement}, new double[][] {{1.0, 0.0}}, measurementNoise); + + for (int i = 0; i < 2; i++) { + assertEquals(extended.state()[i], unscented.state()[i], 1e-9, "state at step " + step); + for (int j = 0; j < 2; j++) { + assertEquals(extended.covariance()[i][j], unscented.covariance()[i][j], 1e-9, "covariance at step " + step); + } + } + } + } + + @Test + @DisplayName("a target seen only as a range is tracked without writing a single derivative") + void tracksATargetThroughARangeOnlySensor() { + Random random = new Random(17L); + double[][] processNoise = {{1e-6, 0.0}, {0.0, 1e-4}}; + double[][] measurementNoise = {{0.04}}; + UnscentedKalmanFilter filter = new UnscentedKalmanFilter(new double[] {1.0, 0.5}, new double[][] {{4.0, 0.0}, {0.0, 4.0}}); + + double position = 2.0; + double velocity = 1.0; + double error = 0.0; + int counted = 0; + + for (int step = 0; step < 400; step++) { + position += velocity * INTERVAL; + double measurement = range(position) + 0.2 * random.nextGaussian(); + + filter.predict(state -> new double[] {state[0] + INTERVAL * state[1], state[1]}, processNoise); + filter.update(new double[] {measurement}, state -> new double[] {range(state[0])}, measurementNoise); + + if (step > 200) { + error += Math.abs(filter.state()[0] - position); + counted++; + } + } + + assertTrue(error / counted < 0.2, "the filtered position was off by " + error / counted); + assertEquals(velocity, filter.state()[1], 0.2, "the velocity is never measured, only inferred"); + } + + @Test + @DisplayName("the covariance stays symmetric and its variances positive over a long nonlinear run") + void keepsTheCovarianceHealthy() { + Random random = new Random(29L); + UnscentedKalmanFilter filter = new UnscentedKalmanFilter(new double[] {2.0, 1.0}, IDENTITY_2); + double[][] processNoise = {{1e-4, 0.0}, {0.0, 1e-4}}; + double[][] measurementNoise = {{0.1}}; + + for (int step = 0; step < 500; step++) { + filter.predict(state -> new double[] {state[0] + INTERVAL * Math.sin(state[1]), state[1]}, processNoise); + filter.update(new double[] {range(2.0 + 0.01 * step) + 0.3 * random.nextGaussian()}, state -> new double[] {range(state[0])}, measurementNoise); + + double[][] covariance = filter.covariance(); + assertEquals(covariance[0][1], covariance[1][0], 1e-15, "the covariance lost its symmetry at step " + step); + assertTrue(covariance[0][0] > 0.0 && covariance[1][1] > 0.0, "a variance stopped being positive at step " + step); + } + } + + @Test + @DisplayName("prediction through the identity only adds the process noise") + void predictionAloneAddsTheProcessNoise() { + UnscentedKalmanFilter filter = new UnscentedKalmanFilter(new double[] {3.0}, new double[][] {{1.0}}); + + for (int step = 1; step <= 10; step++) { + filter.predict(state -> state.clone(), new double[][] {{0.5}}); + + assertEquals(3.0, filter.state()[0], 1e-12); + assertEquals(1.0 + 0.5 * step, filter.variance(0), 1e-12); + } + assertEquals(10, filter.predictionCount()); + assertEquals(0, filter.updateCount()); + } + + @Test + @DisplayName("a covariance that is not positive definite has no square root, and the step is refused") + void refusesACovarianceThatIsNotPositiveDefinite() { + UnscentedKalmanFilter filter = new UnscentedKalmanFilter(new double[] {0.0, 0.0}, new double[][] {{1.0, 2.0}, {2.0, 1.0}}); + + assertThrows(ArithmeticException.class, filter::sigmaPoints); + assertThrows(ArithmeticException.class, () -> filter.predict(state -> state, IDENTITY_2)); + } + + @Test + @DisplayName("a measurement that carries no information is reported rather than dividing by zero") + void refusesASingularInnovationCovariance() { + UnscentedKalmanFilter filter = new UnscentedKalmanFilter(new double[] {0.0}, new double[][] {{1.0}}); + + assertThrows(ArithmeticException.class, () -> filter.update(new double[] {1.0}, state -> new double[] {1.0}, new double[][] {{0.0}})); + } + + @Test + void rejectsAModelThatMisbehaves() { + UnscentedKalmanFilter filter = new UnscentedKalmanFilter(new double[] {0.0}, new double[][] {{1.0}}); + + assertThrows(IllegalArgumentException.class, () -> filter.predict(state -> new double[] {1.0, 2.0}, new double[][] {{1.0}})); + assertThrows(IllegalArgumentException.class, () -> filter.predict(state -> new double[] {Double.NaN}, new double[][] {{1.0}})); + assertThrows(IllegalArgumentException.class, () -> filter.predict(state -> state, new double[][] {{1.0, 0.0}})); + assertThrows(IllegalArgumentException.class, () -> filter.update(new double[0], state -> state, new double[0][0])); + assertThrows(IllegalArgumentException.class, () -> filter.update(new double[] {1.0}, state -> new double[] {1.0, 2.0}, new double[][] {{1.0}})); + } + + @Test + void theStateAndCovarianceAreCopiedOut() { + UnscentedKalmanFilter filter = new UnscentedKalmanFilter(new double[] {1.0}, new double[][] {{2.0}}); + + filter.state()[0] = 99.0; + filter.covariance()[0][0] = 99.0; + filter.meanWeights()[0] = 99.0; + + assertEquals(1.0, filter.state()[0], 1e-12); + assertEquals(2.0, filter.variance(0), 1e-12); + assertTrue(filter.meanWeights()[0] < 1.0); + } + + @Test + void exposesItsConfiguration() { + UnscentedKalmanFilter filter = new UnscentedKalmanFilter(new double[] {0.0, 0.0}, IDENTITY_2, 0.5, 2.0, 1.0); + + assertEquals(2, filter.stateSize()); + assertEquals(0.5, filter.alpha()); + assertEquals(2.0, filter.beta()); + assertEquals(1.0, filter.kappa()); + assertEquals(0, filter.lastInnovation().length); + assertThrows(IllegalArgumentException.class, () -> filter.variance(2)); + } + + @Test + void resetRestartsFromAKnownEstimate() { + UnscentedKalmanFilter filter = new UnscentedKalmanFilter(new double[] {0.0}, new double[][] {{1.0}}); + filter.update(new double[] {5.0}, state -> state.clone(), new double[][] {{1.0}}); + + filter.reset(new double[] {-2.0}, new double[][] {{9.0}}); + + assertEquals(-2.0, filter.state()[0], 1e-12); + assertEquals(9.0, filter.variance(0), 1e-12); + assertEquals(0, filter.updateCount()); + assertEquals(0, filter.lastInnovation().length); + } + + @Test + void toStringMentionsTheState() { + UnscentedKalmanFilter filter = new UnscentedKalmanFilter(new double[] {1.5}, new double[][] {{1.0}}); + + String text = filter.toString(); + + assertTrue(text.contains("UnscentedKalmanFilter")); + assertTrue(text.contains("1.5")); + assertTrue(text.contains("beta=2.0")); + } +} From 1c22ba66beac87f731fcb507bfa194db369ed854 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 1 Oct 2026 09:15:36 +0300 Subject: [PATCH 32/92] chore(deps-dev): bump org.mockito:mockito-core from 5.23.0 to 5.24.0 (#7624) Bumps [org.mockito:mockito-core](https://github.com/mockito/mockito) from 5.23.0 to 5.24.0. - [Release notes](https://github.com/mockito/mockito/releases) - [Commits](https://github.com/mockito/mockito/compare/v5.23.0...v5.24.0) --- updated-dependencies: - dependency-name: org.mockito:mockito-core dependency-version: 5.24.0 dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 1c5ccdf0500b..b90bf89fc14f 100644 --- a/pom.xml +++ b/pom.xml @@ -42,7 +42,7 @@ org.mockito mockito-core - 5.23.0 + 5.24.0 test From b33b75b846774274440d7c871e0802e26bed6dc0 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 2 Oct 2026 08:48:34 +0300 Subject: [PATCH 33/92] chore(deps): bump github/codeql-action from 4.38.1 to 4.38.2 in /.github/workflows (#7625) chore(deps): bump github/codeql-action in /.github/workflows Bumps [github/codeql-action](https://github.com/github/codeql-action) from 4.38.1 to 4.38.2. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](https://github.com/github/codeql-action/compare/v4.38.1...v4.38.2) --- updated-dependencies: - dependency-name: github/codeql-action dependency-version: 4.38.2 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/codeql.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 31fe8be603d2..82963c044afb 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -30,7 +30,7 @@ jobs: distribution: 'temurin' - name: Initialize CodeQL - uses: github/codeql-action/init@v4.38.1 + uses: github/codeql-action/init@v4.38.2 with: languages: 'java-kotlin' @@ -38,7 +38,7 @@ jobs: run: mvn --batch-mode --update-snapshots verify - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4.38.1 + uses: github/codeql-action/analyze@v4.38.2 with: category: "/language:java-kotlin" @@ -55,12 +55,12 @@ jobs: uses: actions/checkout@v7 - name: Initialize CodeQL - uses: github/codeql-action/init@v4.38.1 + uses: github/codeql-action/init@v4.38.2 with: languages: 'actions' - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4.38.1 + uses: github/codeql-action/analyze@v4.38.2 with: category: "/language:actions" ... From ed2928f659e2424321b51967bc641a24340b69f7 Mon Sep 17 00:00:00 2001 From: Saadanjum0 <160885369+Saadanjum0@users.noreply.github.com> Date: Fri, 2 Oct 2026 21:05:02 +0500 Subject: [PATCH 34/92] fix: avoid out-of-bounds access in HowManyTimesRotated on small/unrotated arrays (#7626) The old mid-1/mid+1 comparison indexed out of bounds for a 1-2 element array and never terminated correctly for an unrotated array. Replaced with a standard binary search for the rotation pivot. --- .../searches/HowManyTimesRotated.java | 29 +++++++++---------- .../searches/HowManyTimesRotatedTest.java | 18 ++++++++++++ 2 files changed, 31 insertions(+), 16 deletions(-) diff --git a/src/main/java/com/thealgorithms/searches/HowManyTimesRotated.java b/src/main/java/com/thealgorithms/searches/HowManyTimesRotated.java index dd01378f4d5f..81107de2929f 100644 --- a/src/main/java/com/thealgorithms/searches/HowManyTimesRotated.java +++ b/src/main/java/com/thealgorithms/searches/HowManyTimesRotated.java @@ -16,14 +16,15 @@ The position of the minimum element will give the number of times the array has been rotated from its initial sorted position. Eg. For [2,5,6,8,11,12,15,18], 1 rotation gives [5,6,8,11,12,15,18,2], 2 rotations - [6,8,11,12,15,18,2,5] and so on. Finding the minimum element will take O(N) time but, we can use - Binary Search to find the minimum element, we can reduce the complexity to O(log N). If we look - at the rotated array, to identify the minimum element (say a[i]), we observe that - a[i-1]>a[i] a[high], the minimum lies to the right, so low = mid + 1; otherwise it lies at mid + or to the left, so high = mid. This converges to the minimum's index without ever reading + a[mid-1] or a[mid+1], so it also works on arrays of size 0-2 and unrotated arrays. Some other test cases: 1. [1,2,3,4] Number of rotations: 0 or 4(Both valid) - 2. [15,17,2,3,5] Number of rotations: 3 + 2. [15,17,2,3,5] Number of rotations: 2 */ final class HowManyTimesRotated { private HowManyTimesRotated() { @@ -44,20 +45,16 @@ public static void main(String[] args) { public static int rotated(int[] a) { int low = 0; int high = a.length - 1; - int mid = 0; // low + (high-low)/2 = (low + high)/2 - while (low <= high) { - mid = low + (high - low) / 2; - - if (a[mid] < a[mid - 1] && a[mid] < a[mid + 1]) { - break; - } else if (a[mid] > a[mid - 1] && a[mid] < a[mid + 1]) { - high = mid + 1; - } else if (a[mid] > a[mid - 1] && a[mid] > a[mid + 1]) { - low = mid - 1; + while (low < high) { + int mid = low + (high - low) / 2; + if (a[mid] > a[high]) { + low = mid + 1; + } else { + high = mid; } } - return mid; + return low; } } diff --git a/src/test/java/com/thealgorithms/searches/HowManyTimesRotatedTest.java b/src/test/java/com/thealgorithms/searches/HowManyTimesRotatedTest.java index 7d52e9fb4eca..a212bceeff85 100644 --- a/src/test/java/com/thealgorithms/searches/HowManyTimesRotatedTest.java +++ b/src/test/java/com/thealgorithms/searches/HowManyTimesRotatedTest.java @@ -2,7 +2,9 @@ import static org.junit.jupiter.api.Assertions.assertEquals; +import java.util.concurrent.TimeUnit; import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.Timeout; public class HowManyTimesRotatedTest { @@ -13,4 +15,20 @@ public void testHowManyTimesRotated() { int[] arr2 = {15, 17, 2, 3, 5}; assertEquals(2, HowManyTimesRotated.rotated(arr2)); } + + /** An unrotated (already sorted) array should resolve to 0 rotations without hanging. */ + @Test + @Timeout(value = 5, unit = TimeUnit.SECONDS, threadMode = Timeout.ThreadMode.SEPARATE_THREAD) + public void testHowManyTimesRotatedOnUnrotatedArray() { + int[] arr = {2, 5, 6, 8, 11, 12, 15, 18}; + assertEquals(0, HowManyTimesRotated.rotated(arr)); + } + + /** Arrays of size 1 and 2 should not throw ArrayIndexOutOfBoundsException. */ + @Test + public void testHowManyTimesRotatedOnSmallArrays() { + assertEquals(0, HowManyTimesRotated.rotated(new int[] {5})); + assertEquals(0, HowManyTimesRotated.rotated(new int[] {1, 2})); + assertEquals(1, HowManyTimesRotated.rotated(new int[] {2, 1})); + } } From 030d3dd536cbf62eef2e9d28cc8740404bad7b07 Mon Sep 17 00:00:00 2001 From: Dark's Devil Date: Sat, 3 Oct 2026 03:08:53 +0530 Subject: [PATCH 35/92] Improve rotated binary search edge cases (#7623) --- .../searches/RotatedBinarySearch.java | 12 ++++- .../searches/RotatedBinarySearchTest.java | 46 +++++++++++++++++++ 2 files changed, 57 insertions(+), 1 deletion(-) diff --git a/src/main/java/com/thealgorithms/searches/RotatedBinarySearch.java b/src/main/java/com/thealgorithms/searches/RotatedBinarySearch.java index 86099b2fa2fa..4b9717c20fe4 100644 --- a/src/main/java/com/thealgorithms/searches/RotatedBinarySearch.java +++ b/src/main/java/com/thealgorithms/searches/RotatedBinarySearch.java @@ -12,7 +12,13 @@ *

* This is a modified binary search. When the array contains no duplicates, the * time complexity is {@code O(log n)}. With duplicates, the algorithm still - * works but may degrade to {@code O(n)} in the worst case. + * works but may degrade to {@code O(n)} in the worst case. The algorithm uses + * {@code O(1)} additional space and returns {@code -1} for null or empty input, + * or when the key is not present. + * + * @param array sorted array rotated at an unknown pivot + * @param key value to search for + * @return an index containing {@code key}, or {@code -1} if it is not present * * @see Search in rotated sorted array * @see SearchAlgorithm @@ -21,6 +27,10 @@ public final class RotatedBinarySearch implements SearchAlgorithm { @Override public > int find(T[] array, T key) { + if (array == null || array.length == 0 || key == null) { + return -1; + } + int left = 0; int right = array.length - 1; diff --git a/src/test/java/com/thealgorithms/searches/RotatedBinarySearchTest.java b/src/test/java/com/thealgorithms/searches/RotatedBinarySearchTest.java index 1e6ab4c37fcc..f18a0805eb22 100644 --- a/src/test/java/com/thealgorithms/searches/RotatedBinarySearchTest.java +++ b/src/test/java/com/thealgorithms/searches/RotatedBinarySearchTest.java @@ -50,4 +50,50 @@ void shouldHandleDuplicates() { assertTrue(index >= 0 && index < array.length); assertEquals(3, array[index]); } + + @Test + void shouldReturnMinusOneForNullArray() { + RotatedBinarySearch search = new RotatedBinarySearch(); + assertEquals(-1, search.find(null, 1)); + } + + @Test + void shouldReturnMinusOneForEmptyArray() { + RotatedBinarySearch search = new RotatedBinarySearch(); + assertEquals(-1, search.find(new Integer[0], 1)); + } + + @Test + void shouldFindElementInSingleElementArray() { + RotatedBinarySearch search = new RotatedBinarySearch(); + assertEquals(0, search.find(new Integer[] {7}, 7)); + } + + @Test + void shouldReturnMinusOneWhenSingleElementArrayDoesNotContainKey() { + RotatedBinarySearch search = new RotatedBinarySearch(); + assertEquals(-1, search.find(new Integer[] {7}, 8)); + } + + @Test + void shouldFindElementAtRotationPivot() { + RotatedBinarySearch search = new RotatedBinarySearch(); + Integer[] array = {4, 5, 6, 7, 0, 1, 2}; + assertEquals(4, search.find(array, 0)); + } + + @Test + void shouldFindElementsAtBothEnds() { + RotatedBinarySearch search = new RotatedBinarySearch(); + Integer[] array = {4, 5, 6, 7, 0, 1, 2}; + assertEquals(0, search.find(array, 4)); + assertEquals(6, search.find(array, 2)); + } + + @Test + void shouldReturnMinusOneForMissingKeyInAllDuplicatesArray() { + RotatedBinarySearch search = new RotatedBinarySearch(); + Integer[] array = {2, 2, 2, 2, 2, 2, 2, 2}; + assertEquals(-1, search.find(array, 3)); + } } From 2105b5652a541cbf5db0904d0cfebbaf487e4c5f Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sat, 3 Oct 2026 08:38:16 +0300 Subject: [PATCH 36/92] chore(deps): bump org.apache.commons:commons-lang3 from 3.20.0 to 3.21.0 (#7627) Bumps org.apache.commons:commons-lang3 from 3.20.0 to 3.21.0. --- updated-dependencies: - dependency-name: org.apache.commons:commons-lang3 dependency-version: 3.21.0 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index b90bf89fc14f..63a188874af3 100644 --- a/pom.xml +++ b/pom.xml @@ -48,7 +48,7 @@ org.apache.commons commons-lang3 - 3.20.0 + 3.21.0 org.apache.commons From 922c4d39944c96a3888b3e69e6413d274c1fd77f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dilara=20=C3=87etin?= <155580901+dilaraacetin@users.noreply.github.com> Date: Sun, 4 Oct 2026 17:32:10 +0300 Subject: [PATCH 37/92] feat(ciphers): add Merkle signature scheme (#7629) --- .../ciphers/MerkleSignatureScheme.java | 261 ++++++++++++++++++ .../ciphers/MerkleSignatureSchemeTest.java | 195 +++++++++++++ 2 files changed, 456 insertions(+) create mode 100644 src/main/java/com/thealgorithms/ciphers/MerkleSignatureScheme.java create mode 100644 src/test/java/com/thealgorithms/ciphers/MerkleSignatureSchemeTest.java diff --git a/src/main/java/com/thealgorithms/ciphers/MerkleSignatureScheme.java b/src/main/java/com/thealgorithms/ciphers/MerkleSignatureScheme.java new file mode 100644 index 000000000000..783dc2863d7e --- /dev/null +++ b/src/main/java/com/thealgorithms/ciphers/MerkleSignatureScheme.java @@ -0,0 +1,261 @@ +package com.thealgorithms.ciphers; + +import java.security.MessageDigest; +import java.security.NoSuchAlgorithmException; + +/** + * The Merkle signature scheme (MSS) turns a one-time signature scheme into a many-time scheme. + * + *

Key generation creates {@code 2^h} Winternitz one-time key pairs and hashes each WOTS public + * key into a leaf of a binary hash tree of height {@code h}. The tree root is the single MSS public + * key. Every signature uses the next unused leaf, so one key pair can sign {@code 2^h} messages. + * + *

A signature contains the leaf index, the WOTS signature, the WOTS public key of that leaf and + * the authentication path: the {@code h} sibling hashes needed to recompute the root from the leaf. + * The verifier checks the WOTS signature, hashes the WOTS public key into the leaf and walks up the + * tree with the authentication path. Including the WOTS public key in the signature is an + * educational simplification; XMSS instead recomputes it from the WOTS signature. + * + *

MSS is the core of XMSS (RFC 8391). This implementation is educational and must not be used in + * production. + * + *

Reference: Wikipedia: Merkle signature scheme + * + * @author dilaraacetin + * @see WinternitzSignature + * @see LamportSignature + */ +public final class MerkleSignatureScheme { + + // SHA-256 output length in bytes + private static final int HASH_BYTES = 32; + private static final int MIN_HEIGHT = 2; + private static final int MAX_HEIGHT = 10; + private static final int DEFAULT_HEIGHT = 4; + private static final int DEFAULT_W = 16; + + private final int height; + private final WinternitzSignature[] oneTimeKeys; + // tree[level][node]: level 0 holds the leaves, level h holds the root + private final byte[][][] tree; + private int nextLeafIndex; + + /** + * Generates a new key pair with height {@code h = 4} (16 signatures) and {@code w = 16}. + */ + public MerkleSignatureScheme() { + this(DEFAULT_HEIGHT, DEFAULT_W); + } + + /** + * Generates a new key pair that can sign {@code 2^h} messages. + * + * @param h the tree height; must be between 2 and 10 + * @param w the Winternitz parameter of the one-time keys; must be 4, 16 or 256 + * @throws IllegalArgumentException if {@code h} or {@code w} is not supported + */ + public MerkleSignatureScheme(int h, int w) { + if (h < MIN_HEIGHT || h > MAX_HEIGHT) { + throw new IllegalArgumentException("h must be between " + MIN_HEIGHT + " and " + MAX_HEIGHT + ", got " + h); + } + this.height = h; + int leafCount = 1 << h; + oneTimeKeys = new WinternitzSignature[leafCount]; + tree = new byte[h + 1][][]; + tree[0] = new byte[leafCount][]; + for (int i = 0; i < leafCount; i++) { + oneTimeKeys[i] = new WinternitzSignature(w); + tree[0][i] = hashPublicKey(oneTimeKeys[i].getPublicKey()); + } + for (int level = 1; level <= h; level++) { + tree[level] = new byte[tree[level - 1].length / 2][]; + for (int i = 0; i < tree[level].length; i++) { + tree[level][i] = hash(tree[level - 1][2 * i], tree[level - 1][2 * i + 1]); + } + } + } + + /** + * Returns a copy of the public key, which is the root of the Merkle tree. + * + * @return the 32-byte tree root + */ + public byte[] getPublicKey() { + return tree[height][0].clone(); + } + + /** + * Returns how many messages this key pair can still sign. + * + * @return the number of unused one-time keys + */ + public int remainingSignatures() { + return oneTimeKeys.length - nextLeafIndex; + } + + /** + * Signs a message with the next unused one-time key. + * + * @param message the message to sign + * @return the Merkle signature + * @throws IllegalArgumentException if the message is null + * @throws IllegalStateException if all {@code 2^h} one-time keys have been used + */ + public MerkleSignature sign(byte[] message) { + if (message == null) { + throw new IllegalArgumentException("message must not be null"); + } + if (nextLeafIndex >= oneTimeKeys.length) { + throw new IllegalStateException("All " + oneTimeKeys.length + " signatures of this key pair have been used"); + } + int leafIndex = nextLeafIndex++; + WinternitzSignature oneTimeKey = oneTimeKeys[leafIndex]; + byte[][] wotsSignature = oneTimeKey.sign(message); + + // collect the sibling of the current node on every level, from the leaf up to the root + byte[][] authPath = new byte[height][]; + int index = leafIndex; + for (int level = 0; level < height; level++) { + authPath[level] = tree[level][index ^ 1]; + index >>= 1; + } + return new MerkleSignature(leafIndex, wotsSignature, oneTimeKey.getPublicKey(), authPath); + } + + /** + * Verifies a Merkle signature against a public key (tree root). The tree height is taken from + * the length of the authentication path. + * + * @param message the signed message + * @param signature the signature to check + * @param publicKey the tree root of the signer + * @param w the Winternitz parameter used to create the key pair; must be 4, 16 or 256 + * @return true if the signature is valid for the message and public key, false otherwise + * @throws IllegalArgumentException if an argument is null, {@code w} is unsupported, or the + * public key or WOTS part of the signature is malformed + */ + public static boolean verify(byte[] message, MerkleSignature signature, byte[] publicKey, int w) { + if (message == null) { + throw new IllegalArgumentException("message must not be null"); + } + if (signature == null) { + throw new IllegalArgumentException("signature must not be null"); + } + if (publicKey == null || publicKey.length != HASH_BYTES) { + throw new IllegalArgumentException("publicKey must be exactly " + HASH_BYTES + " bytes long"); + } + if (!WinternitzSignature.verify(message, signature.wotsSignature, signature.wotsPublicKey, w)) { + return false; + } + + byte[] node = hashPublicKey(signature.wotsPublicKey); + int index = signature.leafIndex; + for (byte[] sibling : signature.authPath) { + // an even index is a left child, an odd index a right child + node = (index & 1) == 0 ? hash(node, sibling) : hash(sibling, node); + index >>= 1; + } + return MessageDigest.isEqual(node, publicKey); + } + + /** + * A Merkle signature: leaf index, WOTS signature, WOTS public key and authentication path. + * All arrays are copied on construction and on access. + */ + public static final class MerkleSignature { + private final int leafIndex; + private final byte[][] wotsSignature; + private final byte[][] wotsPublicKey; + private final byte[][] authPath; + + /** + * Creates a signature from its parts. + * + * @param leafIndex the index of the leaf used for signing + * @param wotsSignature the Winternitz signature of the message + * @param wotsPublicKey the Winternitz public key of the leaf + * @param authPath the sibling hashes from the leaf up to the root + * @throws IllegalArgumentException if an argument is null, the authentication path length is + * not between 2 and 10, an authentication path value is not 32 bytes long, or the leaf + * index is outside the tree + */ + public MerkleSignature(int leafIndex, byte[][] wotsSignature, byte[][] wotsPublicKey, byte[][] authPath) { + if (authPath == null || authPath.length < MIN_HEIGHT || authPath.length > MAX_HEIGHT) { + throw new IllegalArgumentException("authPath must contain between " + MIN_HEIGHT + " and " + MAX_HEIGHT + " values"); + } + for (byte[] sibling : authPath) { + if (sibling == null || sibling.length != HASH_BYTES) { + throw new IllegalArgumentException("authPath values must be exactly " + HASH_BYTES + " bytes long"); + } + } + if (leafIndex < 0 || leafIndex >= 1 << authPath.length) { + throw new IllegalArgumentException("leafIndex must be between 0 and " + ((1 << authPath.length) - 1) + ", got " + leafIndex); + } + this.leafIndex = leafIndex; + this.wotsSignature = deepCopy(wotsSignature, "wotsSignature"); + this.wotsPublicKey = deepCopy(wotsPublicKey, "wotsPublicKey"); + this.authPath = deepCopy(authPath, "authPath"); + } + + /** + * @return the index of the leaf used for signing + */ + public int getLeafIndex() { + return leafIndex; + } + + /** + * @return a copy of the Winternitz signature + */ + public byte[][] getWotsSignature() { + return deepCopy(wotsSignature, "wotsSignature"); + } + + /** + * @return a copy of the Winternitz public key of the leaf + */ + public byte[][] getWotsPublicKey() { + return deepCopy(wotsPublicKey, "wotsPublicKey"); + } + + /** + * @return a copy of the authentication path, ordered from the leaf level up to the root + */ + public byte[][] getAuthPath() { + return deepCopy(authPath, "authPath"); + } + } + + /** + * Hashes a WOTS public key into a Merkle leaf. Shared by key generation and verification. + */ + private static byte[] hashPublicKey(byte[][] wotsPublicKey) { + return hash(wotsPublicKey); + } + + private static byte[] hash(byte[]... parts) { + try { + MessageDigest digest = MessageDigest.getInstance("SHA-256"); + for (byte[] part : parts) { + digest.update(part); + } + return digest.digest(); + } catch (NoSuchAlgorithmException e) { + throw new AssertionError("SHA-256 is required by the Java SE specification", e); + } + } + + private static byte[][] deepCopy(byte[][] values, String name) { + if (values == null) { + throw new IllegalArgumentException(name + " must not be null"); + } + byte[][] copy = new byte[values.length][]; + for (int i = 0; i < values.length; i++) { + if (values[i] == null) { + throw new IllegalArgumentException(name + " values must not be null"); + } + copy[i] = values[i].clone(); + } + return copy; + } +} diff --git a/src/test/java/com/thealgorithms/ciphers/MerkleSignatureSchemeTest.java b/src/test/java/com/thealgorithms/ciphers/MerkleSignatureSchemeTest.java new file mode 100644 index 000000000000..dfa59e18e9c8 --- /dev/null +++ b/src/test/java/com/thealgorithms/ciphers/MerkleSignatureSchemeTest.java @@ -0,0 +1,195 @@ +package com.thealgorithms.ciphers; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.nio.charset.StandardCharsets; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.CsvSource; +import org.junit.jupiter.params.provider.ValueSource; + +class MerkleSignatureSchemeTest { + + private static final byte[] MESSAGE = "hello merkle".getBytes(StandardCharsets.UTF_8); + + @Test + void testValidSignatureVerifies() { + MerkleSignatureScheme keyPair = new MerkleSignatureScheme(); + + MerkleSignatureScheme.MerkleSignature signature = keyPair.sign(MESSAGE); + + assertTrue(MerkleSignatureScheme.verify(MESSAGE, signature, keyPair.getPublicKey(), 16)); + } + + @Test + void testEveryLeafSignsAndVerifies() { + MerkleSignatureScheme keyPair = new MerkleSignatureScheme(4, 16); + byte[] publicKey = keyPair.getPublicKey(); + + for (int i = 0; i < 16; i++) { + byte[] message = ("message " + i).getBytes(StandardCharsets.UTF_8); + MerkleSignatureScheme.MerkleSignature signature = keyPair.sign(message); + + assertEquals(i, signature.getLeafIndex()); + assertEquals(4, signature.getAuthPath().length); + assertTrue(MerkleSignatureScheme.verify(message, signature, publicKey, 16)); + } + } + + @Test + void testSigningBeyondCapacityThrowsException() { + MerkleSignatureScheme keyPair = new MerkleSignatureScheme(2, 16); + for (int i = 0; i < 4; i++) { + keyPair.sign(MESSAGE); + } + + assertThrows(IllegalStateException.class, () -> keyPair.sign(MESSAGE)); + } + + @Test + void testRemainingSignaturesDecreases() { + MerkleSignatureScheme keyPair = new MerkleSignatureScheme(2, 16); + + for (int expected = 4; expected > 0; expected--) { + assertEquals(expected, keyPair.remainingSignatures()); + keyPair.sign(MESSAGE); + } + assertEquals(0, keyPair.remainingSignatures()); + } + + @Test + void testTamperedMessageFailsVerification() { + MerkleSignatureScheme keyPair = new MerkleSignatureScheme(); + MerkleSignatureScheme.MerkleSignature signature = keyPair.sign(MESSAGE); + byte[] tampered = MESSAGE.clone(); + + tampered[0] ^= 0x01; + + assertFalse(MerkleSignatureScheme.verify(tampered, signature, keyPair.getPublicKey(), 16)); + } + + @Test + void testTamperedWotsSignatureFailsVerification() { + MerkleSignatureScheme keyPair = new MerkleSignatureScheme(); + MerkleSignatureScheme.MerkleSignature signature = keyPair.sign(MESSAGE); + byte[][] wotsSignature = signature.getWotsSignature(); + + wotsSignature[5][0] ^= 0x01; + MerkleSignatureScheme.MerkleSignature tampered = new MerkleSignatureScheme.MerkleSignature(signature.getLeafIndex(), wotsSignature, signature.getWotsPublicKey(), signature.getAuthPath()); + + assertFalse(MerkleSignatureScheme.verify(MESSAGE, tampered, keyPair.getPublicKey(), 16)); + } + + @Test + void testTamperedAuthPathFailsVerification() { + MerkleSignatureScheme keyPair = new MerkleSignatureScheme(); + MerkleSignatureScheme.MerkleSignature signature = keyPair.sign(MESSAGE); + byte[][] authPath = signature.getAuthPath(); + + authPath[2][0] ^= 0x01; + MerkleSignatureScheme.MerkleSignature tampered = new MerkleSignatureScheme.MerkleSignature(signature.getLeafIndex(), signature.getWotsSignature(), signature.getWotsPublicKey(), authPath); + + assertFalse(MerkleSignatureScheme.verify(MESSAGE, tampered, keyPair.getPublicKey(), 16)); + } + + @Test + void testChangedLeafIndexFailsVerification() { + MerkleSignatureScheme keyPair = new MerkleSignatureScheme(); + MerkleSignatureScheme.MerkleSignature signature = keyPair.sign(MESSAGE); + + MerkleSignatureScheme.MerkleSignature tampered = new MerkleSignatureScheme.MerkleSignature(signature.getLeafIndex() + 1, signature.getWotsSignature(), signature.getWotsPublicKey(), signature.getAuthPath()); + + assertFalse(MerkleSignatureScheme.verify(MESSAGE, tampered, keyPair.getPublicKey(), 16)); + } + + @Test + void testDifferentPublicKeyDoesNotVerify() { + MerkleSignatureScheme keyPair1 = new MerkleSignatureScheme(); + MerkleSignatureScheme keyPair2 = new MerkleSignatureScheme(); + + MerkleSignatureScheme.MerkleSignature signature = keyPair1.sign(MESSAGE); + + assertFalse(MerkleSignatureScheme.verify(MESSAGE, signature, keyPair2.getPublicKey(), 16)); + } + + @ParameterizedTest + @CsvSource({"2, 4", "2, 16", "4, 4", "4, 16", "6, 4", "6, 16"}) + void testSignAndVerifyForDifferentParameters(int h, int w) { + MerkleSignatureScheme keyPair = new MerkleSignatureScheme(h, w); + + MerkleSignatureScheme.MerkleSignature first = keyPair.sign(MESSAGE); + MerkleSignatureScheme.MerkleSignature second = keyPair.sign(MESSAGE); + + assertEquals((1 << h) - 2, keyPair.remainingSignatures()); + assertEquals(h, first.getAuthPath().length); + assertTrue(MerkleSignatureScheme.verify(MESSAGE, first, keyPair.getPublicKey(), w)); + assertTrue(MerkleSignatureScheme.verify(MESSAGE, second, keyPair.getPublicKey(), w)); + } + + @ParameterizedTest + @ValueSource(ints = {0, 1, 11, -4}) + void testUnsupportedHeightThrowsException(int h) { + assertThrows(IllegalArgumentException.class, () -> new MerkleSignatureScheme(h, 16)); + } + + @ParameterizedTest + @ValueSource(ints = {0, 3, 15}) + void testUnsupportedWThrowsException(int w) { + assertThrows(IllegalArgumentException.class, () -> new MerkleSignatureScheme(2, w)); + } + + @Test + void testNullAndMalformedInput() { + MerkleSignatureScheme keyPair = new MerkleSignatureScheme(2, 16); + byte[] publicKey = keyPair.getPublicKey(); + MerkleSignatureScheme.MerkleSignature signature = keyPair.sign(MESSAGE); + byte[][] wotsSignature = signature.getWotsSignature(); + byte[][] wotsPublicKey = signature.getWotsPublicKey(); + byte[][] authPath = signature.getAuthPath(); + + assertThrows(IllegalArgumentException.class, () -> keyPair.sign(null)); + assertThrows(IllegalArgumentException.class, () -> MerkleSignatureScheme.verify(null, signature, publicKey, 16)); + assertThrows(IllegalArgumentException.class, () -> MerkleSignatureScheme.verify(MESSAGE, null, publicKey, 16)); + assertThrows(IllegalArgumentException.class, () -> MerkleSignatureScheme.verify(MESSAGE, signature, null, 16)); + assertThrows(IllegalArgumentException.class, () -> MerkleSignatureScheme.verify(MESSAGE, signature, new byte[31], 16)); + assertThrows(IllegalArgumentException.class, () -> MerkleSignatureScheme.verify(MESSAGE, signature, publicKey, 4)); + + assertThrows(IllegalArgumentException.class, () -> new MerkleSignatureScheme.MerkleSignature(0, null, wotsPublicKey, authPath)); + assertThrows(IllegalArgumentException.class, () -> new MerkleSignatureScheme.MerkleSignature(0, wotsSignature, null, authPath)); + assertThrows(IllegalArgumentException.class, () -> new MerkleSignatureScheme.MerkleSignature(0, wotsSignature, wotsPublicKey, null)); + assertThrows(IllegalArgumentException.class, () -> new MerkleSignatureScheme.MerkleSignature(0, wotsSignature, wotsPublicKey, new byte[1][32])); + assertThrows(IllegalArgumentException.class, () -> new MerkleSignatureScheme.MerkleSignature(0, wotsSignature, wotsPublicKey, new byte[11][32])); + assertThrows(IllegalArgumentException.class, () -> new MerkleSignatureScheme.MerkleSignature(0, wotsSignature, wotsPublicKey, new byte[2][31])); + assertThrows(IllegalArgumentException.class, () -> new MerkleSignatureScheme.MerkleSignature(0, wotsSignature, wotsPublicKey, new byte[2][])); + assertThrows(IllegalArgumentException.class, () -> new MerkleSignatureScheme.MerkleSignature(0, new byte[67][], wotsPublicKey, authPath)); + assertThrows(IllegalArgumentException.class, () -> new MerkleSignatureScheme.MerkleSignature(-1, wotsSignature, wotsPublicKey, authPath)); + assertThrows(IllegalArgumentException.class, () -> new MerkleSignatureScheme.MerkleSignature(4, wotsSignature, wotsPublicKey, authPath)); + } + + @Test + void testModifyingReturnedArraysDoesNotChangeInternalState() { + MerkleSignatureScheme keyPair = new MerkleSignatureScheme(2, 16); + MerkleSignatureScheme.MerkleSignature signature = keyPair.sign(MESSAGE); + + keyPair.getPublicKey()[0] ^= 0x01; + signature.getWotsSignature()[0][0] ^= 0x01; + signature.getWotsPublicKey()[0][0] ^= 0x01; + signature.getAuthPath()[0][0] ^= 0x01; + + assertTrue(MerkleSignatureScheme.verify(MESSAGE, signature, keyPair.getPublicKey(), 16)); + } + + @Test + void testSignaturesUseDifferentLeaves() { + MerkleSignatureScheme keyPair = new MerkleSignatureScheme(2, 16); + + MerkleSignatureScheme.MerkleSignature first = keyPair.sign(MESSAGE); + MerkleSignatureScheme.MerkleSignature second = keyPair.sign(MESSAGE); + + assertEquals(0, first.getLeafIndex()); + assertEquals(1, second.getLeafIndex()); + } +} From 2fdcde75a497bdedcd5385bda224b4fb80ea3d15 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dilara=20=C3=87etin?= <155580901+dilaraacetin@users.noreply.github.com> Date: Sun, 4 Oct 2026 22:37:46 +0300 Subject: [PATCH 38/92] Feature/lwe encryption (#7631) * feat(ciphers): add LWE (Regev) encryption * test(ciphers): add tests for LWE encryption --------- Co-authored-by: Oleksandr Klymenko <19151554+alxkm@users.noreply.github.com> --- .../thealgorithms/ciphers/LWEEncryption.java | 216 ++++++++++++++++++ .../ciphers/LWEEncryptionTest.java | 122 ++++++++++ 2 files changed, 338 insertions(+) create mode 100644 src/main/java/com/thealgorithms/ciphers/LWEEncryption.java create mode 100644 src/test/java/com/thealgorithms/ciphers/LWEEncryptionTest.java diff --git a/src/main/java/com/thealgorithms/ciphers/LWEEncryption.java b/src/main/java/com/thealgorithms/ciphers/LWEEncryption.java new file mode 100644 index 000000000000..bf552c605af0 --- /dev/null +++ b/src/main/java/com/thealgorithms/ciphers/LWEEncryption.java @@ -0,0 +1,216 @@ +package com.thealgorithms.ciphers; + +import java.security.SecureRandom; + +/** + * Public-key encryption based on the Learning With Errors (LWE) problem, as proposed by Regev (2005). + * + *

Toy parameters for educational purposes only — NOT secure for real-world use. + * + *

The LWE problem: given many noisy samples {@code b = A·s + e (mod q)} with a random matrix + * {@code A} and small random errors {@code e}, it is hard to recover the secret vector {@code s}. + * Without the errors, {@code s} could be found with Gaussian elimination. + * + *

The public key is {@code (A, b)} and the private key is {@code s}. To encrypt a bit, a random + * subset {@code r} of the samples is summed: {@code u = rᵀ·A} and {@code v = r·b + bit·⌊q/2⌋}. + * Decryption computes {@code v - u·s = r·e + bit·⌊q/2⌋}: a value close to 0 means bit 0, a value + * close to {@code q/2} means bit 1. + * + *

Decryption is always correct because the remaining noise is bounded: {@code r} is a 0/1 vector + * and {@code |e_i| ≤ B}, so {@code |r·e| ≤ m·B = 384 < q/4 ≈ 832}. + * + *

The modulus {@code q = 3329} is the one used by Kyber / ML-KEM (FIPS 203), which uses the + * module-lattice version of this construction with discrete Gaussian-like noise and much larger + * parameters. For simplicity, one instance holds both the public and the private key; in real use + * they are kept separately. + * + *

Reference: Wikipedia: Learning with errors + * + * @author dilaraacetin + */ +public final class LWEEncryption { + + // dimension of the secret vector + private static final int N = 32; + // modulus, same as Kyber / ML-KEM + private static final int Q = 3329; + // number of samples in the public key + private static final int M = 128; + // errors are uniform in [-B, B] + private static final int B = 3; + private static final int BITS_PER_BYTE = 8; + + private final SecureRandom random = new SecureRandom(); + private final int[][] a; + private final int[] b; + private final int[] s; + + /** + * Generates a new key pair. + * + * @throws IllegalStateException if the parameters do not guarantee correct decryption + */ + public LWEEncryption() { + checkDecryptionBound(M, B, Q); + s = new int[N]; + for (int j = 0; j < N; j++) { + s[j] = random.nextInt(Q); + } + a = new int[M][N]; + b = new int[M]; + for (int i = 0; i < M; i++) { + long sum = 0; + for (int j = 0; j < N; j++) { + a[i][j] = random.nextInt(Q); + sum += (long) a[i][j] * s[j]; + } + int error = random.nextInt(2 * B + 1) - B; + // b_i = A_i·s + e_i (mod q) + b[i] = (int) Math.floorMod(sum + error, (long) Q); + } + } + + /** + * Encrypts a single bit. Encryption is randomized, so the same bit gives different ciphertexts. + * + * @param bit the bit to encrypt, 0 or 1 + * @return the ciphertext {@code (u, v)} + * @throws IllegalArgumentException if {@code bit} is not 0 or 1 + */ + public Ciphertext encryptBit(int bit) { + if (bit != 0 && bit != 1) { + throw new IllegalArgumentException("bit must be 0 or 1, got " + bit); + } + long[] u = new long[N]; + long v = (long) bit * (Q / 2); + for (int i = 0; i < M; i++) { + // r_i is 0 or 1: add sample i or skip it + if (random.nextBoolean()) { + for (int j = 0; j < N; j++) { + u[j] += a[i][j]; + } + v += b[i]; + } + } + int[] reduced = new int[N]; + for (int j = 0; j < N; j++) { + reduced[j] = (int) Math.floorMod(u[j], (long) Q); + } + return new Ciphertext(reduced, (int) Math.floorMod(v, (long) Q)); + } + + /** + * Decrypts a single bit. + * + * @param ciphertext the ciphertext to decrypt + * @return the decrypted bit, 0 or 1 + * @throws IllegalArgumentException if the ciphertext is null + */ + public int decryptBit(Ciphertext ciphertext) { + if (ciphertext == null) { + throw new IllegalArgumentException("ciphertext must not be null"); + } + long dot = 0; + for (int j = 0; j < N; j++) { + dot += (long) ciphertext.u[j] * s[j]; + } + // d = r·e + bit·⌊q/2⌋ (mod q); floorMod keeps it non-negative + int d = (int) Math.floorMod(ciphertext.v - dot, (long) Q); + return d >= Q / 4 && d < 3 * Q / 4 ? 1 : 0; + } + + /** + * Encrypts a message bit by bit, most significant bit of each byte first. + * + * @param message the message to encrypt + * @return eight ciphertexts per message byte + * @throws IllegalArgumentException if the message is null or empty + */ + public Ciphertext[] encrypt(byte[] message) { + if (message == null || message.length == 0) { + throw new IllegalArgumentException("message must not be null or empty"); + } + Ciphertext[] ciphertexts = new Ciphertext[message.length * BITS_PER_BYTE]; + for (int i = 0; i < message.length; i++) { + for (int k = 0; k < BITS_PER_BYTE; k++) { + ciphertexts[i * BITS_PER_BYTE + k] = encryptBit((message[i] >> (7 - k)) & 1); + } + } + return ciphertexts; + } + + /** + * Decrypts a message encrypted with {@link #encrypt(byte[])}. + * + * @param ciphertexts eight ciphertexts per message byte + * @return the decrypted message + * @throws IllegalArgumentException if the array is null, empty, contains null, or its length is + * not a multiple of 8 + */ + public byte[] decrypt(Ciphertext[] ciphertexts) { + if (ciphertexts == null || ciphertexts.length == 0) { + throw new IllegalArgumentException("ciphertexts must not be null or empty"); + } + if (ciphertexts.length % BITS_PER_BYTE != 0) { + throw new IllegalArgumentException("ciphertexts length must be a multiple of 8, got " + ciphertexts.length); + } + byte[] message = new byte[ciphertexts.length / BITS_PER_BYTE]; + for (int i = 0; i < message.length; i++) { + int value = 0; + for (int k = 0; k < BITS_PER_BYTE; k++) { + value = (value << 1) | decryptBit(ciphertexts[i * BITS_PER_BYTE + k]); + } + message[i] = (byte) value; + } + return message; + } + + /** + * Checks that the maximum decryption noise {@code m·B} stays below {@code q/4}. + * + * @throws IllegalStateException if decryption could fail with these parameters + */ + static void checkDecryptionBound(int samples, int errorBound, int modulus) { + if (samples * errorBound >= modulus / 4) { + throw new IllegalStateException("m * B must be less than q / 4 for correct decryption"); + } + } + + /** + * An LWE ciphertext {@code (u, v)} for one bit. Immutable: the array is copied on construction + * and on access. + */ + public static final class Ciphertext { + private final int[] u; + private final int v; + + /** + * Creates a ciphertext. + * + * @param u the vector part, of length 32 + * @param v the scalar part + * @throws IllegalArgumentException if {@code u} is null or does not have length 32 + */ + public Ciphertext(int[] u, int v) { + if (u == null || u.length != N) { + throw new IllegalArgumentException("u must contain exactly " + N + " values"); + } + this.u = u.clone(); + this.v = v; + } + + /** + * @return a copy of the vector part + */ + public int[] getU() { + return u.clone(); + } + + /** + * @return the scalar part + */ + public int getV() { + return v; + } + } +} diff --git a/src/test/java/com/thealgorithms/ciphers/LWEEncryptionTest.java b/src/test/java/com/thealgorithms/ciphers/LWEEncryptionTest.java new file mode 100644 index 000000000000..56b3188361f3 --- /dev/null +++ b/src/test/java/com/thealgorithms/ciphers/LWEEncryptionTest.java @@ -0,0 +1,122 @@ +package com.thealgorithms.ciphers; + +import static org.junit.jupiter.api.Assertions.assertArrayEquals; +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; + +import java.nio.charset.StandardCharsets; +import java.security.SecureRandom; +import java.util.Arrays; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +class LWEEncryptionTest { + + @ParameterizedTest + @ValueSource(ints = {0, 1}) + void testBitRoundTrip(int bit) { + LWEEncryption lwe = new LWEEncryption(); + + for (int i = 0; i < 100; i++) { + assertEquals(bit, lwe.decryptBit(lwe.encryptBit(bit))); + } + } + + @Test + void testTextMessageRoundTrip() { + LWEEncryption lwe = new LWEEncryption(); + byte[] message = "Hello, PQC!".getBytes(StandardCharsets.UTF_8); + + assertArrayEquals(message, lwe.decrypt(lwe.encrypt(message))); + } + + @Test + void testRandomMessageRoundTrip() { + LWEEncryption lwe = new LWEEncryption(); + byte[] message = new byte[1024]; + new SecureRandom().nextBytes(message); + + assertArrayEquals(message, lwe.decrypt(lwe.encrypt(message))); + } + + @Test + void testEncryptionIsRandomized() { + LWEEncryption lwe = new LWEEncryption(); + + LWEEncryption.Ciphertext first = lwe.encryptBit(1); + LWEEncryption.Ciphertext second = lwe.encryptBit(1); + + assertFalse(Arrays.equals(toArray(first), toArray(second))); + } + + @Test + void testWrongKeyDoesNotDecrypt() { + LWEEncryption sender = new LWEEncryption(); + LWEEncryption other = new LWEEncryption(); + byte[] message = "sixteen byte msg".getBytes(StandardCharsets.UTF_8); + + byte[] decrypted = other.decrypt(sender.encrypt(message)); + + assertFalse(Arrays.equals(message, decrypted)); + } + + @ParameterizedTest + @ValueSource(bytes = {(byte) 0b10110001, (byte) 0xFF, (byte) 0x80, 0x00, 0x01, 0x7F}) + void testSingleByteBitOrder(byte value) { + LWEEncryption lwe = new LWEEncryption(); + + assertArrayEquals(new byte[] {value}, lwe.decrypt(lwe.encrypt(new byte[] {value}))); + } + + @Test + void testInvalidInput() { + LWEEncryption lwe = new LWEEncryption(); + LWEEncryption.Ciphertext[] sevenCiphertexts = Arrays.copyOf(lwe.encrypt(new byte[] {1}), 7); + LWEEncryption.Ciphertext[] withNull = lwe.encrypt(new byte[] {1}); + withNull[3] = null; + + assertThrows(IllegalArgumentException.class, () -> lwe.encryptBit(2)); + assertThrows(IllegalArgumentException.class, () -> lwe.encryptBit(-1)); + assertThrows(IllegalArgumentException.class, () -> lwe.encrypt(null)); + assertThrows(IllegalArgumentException.class, () -> lwe.encrypt(new byte[0])); + assertThrows(IllegalArgumentException.class, () -> lwe.decryptBit(null)); + assertThrows(IllegalArgumentException.class, () -> lwe.decrypt(null)); + assertThrows(IllegalArgumentException.class, () -> lwe.decrypt(new LWEEncryption.Ciphertext[0])); + assertThrows(IllegalArgumentException.class, () -> lwe.decrypt(sevenCiphertexts)); + assertThrows(IllegalArgumentException.class, () -> lwe.decrypt(withNull)); + assertThrows(IllegalArgumentException.class, () -> new LWEEncryption.Ciphertext(null, 0)); + assertThrows(IllegalArgumentException.class, () -> new LWEEncryption.Ciphertext(new int[31], 0)); + assertThrows(IllegalArgumentException.class, () -> new LWEEncryption.Ciphertext(new int[33], 0)); + } + + @Test + void testCiphertextIsImmutable() { + int[] u = new int[32]; + Arrays.fill(u, 7); + LWEEncryption.Ciphertext ciphertext = new LWEEncryption.Ciphertext(u, 5); + int[] expected = u.clone(); + + u[0] = 100; + ciphertext.getU()[1] = 200; + + assertArrayEquals(expected, ciphertext.getU()); + assertEquals(5, ciphertext.getV()); + } + + @Test + void testDecryptionBoundCheck() { + LWEEncryption.checkDecryptionBound(128, 3, 3329); + + assertThrows(IllegalStateException.class, () -> LWEEncryption.checkDecryptionBound(128, 7, 3329)); + } + + // u followed by v, so that two ciphertexts can be compared with a single Arrays.equals + private static int[] toArray(LWEEncryption.Ciphertext ciphertext) { + int[] u = ciphertext.getU(); + int[] values = Arrays.copyOf(u, u.length + 1); + values[u.length] = ciphertext.getV(); + return values; + } +} From 68dc5f54dde2ffadd1f3a1ccfc6f60946c6cb101 Mon Sep 17 00:00:00 2001 From: tianrking <10758833+tianrking@users.noreply.github.com> Date: Mon, 5 Oct 2026 05:14:43 +0800 Subject: [PATCH 39/92] fix: preserve KDTree deletion traversal and split invariants (#7633) Descend using the same split direction as insert and search, move remaining left-only children to the right of their minimum replacement, and stop traversal once the selected node is handled. Cover leaf and subtree deletion, nested successors, left-only replacement reuse, missing and final points, and deletion-order reference checks for bulk-built and inserted 1D/2D/3D trees. Fixes #7632 --- .../datastructures/trees/KDTree.java | 6 +- .../trees/KDTreeDeletionTest.java | 165 ++++++++++++++++++ 2 files changed, 169 insertions(+), 2 deletions(-) create mode 100644 src/test/java/com/thealgorithms/datastructures/trees/KDTreeDeletionTest.java diff --git a/src/main/java/com/thealgorithms/datastructures/trees/KDTree.java b/src/main/java/com/thealgorithms/datastructures/trees/KDTree.java index 5190e82f74ef..f2bab248ff28 100644 --- a/src/main/java/com/thealgorithms/datastructures/trees/KDTree.java +++ b/src/main/java/com/thealgorithms/datastructures/trees/KDTree.java @@ -406,12 +406,14 @@ private Node delete(Node root, Node node) { } else if (root.left != null) { Node min = findMin(root.left, root.getAxis()); root.point = min.point; - root.left = delete(root.left, min); + root.right = delete(root.left, min); + root.left = null; } else { return null; } + return root; } - if (root.getAxisCoordinate() < node.point.getCoordinate(root.getAxis())) { + if (node.point.getCoordinate(root.getAxis()) < root.getAxisCoordinate()) { root.left = delete(root.left, node); } else { root.right = delete(root.right, node); diff --git a/src/test/java/com/thealgorithms/datastructures/trees/KDTreeDeletionTest.java b/src/test/java/com/thealgorithms/datastructures/trees/KDTreeDeletionTest.java new file mode 100644 index 000000000000..ee5d22f63b22 --- /dev/null +++ b/src/test/java/com/thealgorithms/datastructures/trees/KDTreeDeletionTest.java @@ -0,0 +1,165 @@ +package com.thealgorithms.datastructures.trees; + +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; +import java.util.Set; +import org.junit.jupiter.api.Assertions; +import org.junit.jupiter.api.Test; + +class KDTreeDeletionTest { + @Test + void deleteLeavesOnBothSides() { + for (int coordinate : new int[] {10, 30}) { + List points = pointsOf(20, 10, 30); + KDTree tree = insertedTree(points); + KDTree.Point deleted = pointOf(coordinate); + tree.delete(deleted); + points.remove(deleted); + assertContents(tree, points); + Assertions.assertFalse(tree.search(deleted).isPresent()); + } + } + + @Test + void deleteNonRootWithDescendants() { + for (int coordinate : new int[] {10, 30}) { + List points = pointsOf(20, 10, 30, 5, 15, 25, 35, 13, 27); + KDTree tree = insertedTree(points); + KDTree.Point deleted = pointOf(coordinate); + tree.delete(deleted); + points.remove(deleted); + assertContents(tree, points); + Assertions.assertFalse(tree.search(deleted).isPresent()); + } + } + + @Test + void deleteRootWithOnlyLeftSubtree() { + List points = pointsOf(20, 10, 15, 5); + KDTree tree = insertedTree(points); + KDTree.Point deleted = points.removeFirst(); + tree.delete(deleted); + assertContents(tree, points); + Assertions.assertFalse(tree.search(deleted).isPresent()); + KDTree.Point inserted = pointOf(12); + tree.insert(inserted); + points.add(inserted); + assertContents(tree, points); + tree.delete(inserted); + points.remove(inserted); + assertContents(tree, points); + } + + @Test + void deleteRootWithNestedRightSuccessor() { + List points = pointsOf(20, 30, 25, 27, 40); + KDTree tree = insertedTree(points); + KDTree.Point deleted = points.removeFirst(); + tree.delete(deleted); + assertContents(tree, points); + Assertions.assertFalse(tree.search(deleted).isPresent()); + KDTree.Point successor = pointOf(25); + Assertions.assertEquals(successor, tree.getRoot().getPoint()); + tree.delete(successor); + points.remove(successor); + assertContents(tree, points); + Assertions.assertFalse(tree.search(successor).isPresent()); + } + + @Test + void deletingAbsentPointPreservesContents() { + List points = pointsOf(20, 10, 30); + KDTree tree = insertedTree(points); + Assertions.assertThrows(IllegalArgumentException.class, () -> tree.delete(pointOf(15))); + assertContents(tree, points); + for (KDTree.Point point : List.copyOf(points)) { + tree.delete(point); + points.remove(point); + assertContents(tree, points); + } + Assertions.assertNull(tree.getRoot()); + Assertions.assertThrows(IllegalArgumentException.class, () -> tree.delete(pointOf(20))); + Assertions.assertNull(tree.getRoot()); + } + + @Test + void deletionOrdersPreserveBuiltAndInsertedTrees() { + for (int dimension : new int[] {1, 2, 3}) { + List initial = new ArrayList<>(); + for (int index = 0; index < 15; index++) { + int[] coordinates = new int[dimension]; + for (int axis = 0; axis < dimension; axis++) { + coordinates[axis] = index * (axis + 1) % 17 - 8; + } + initial.add(new KDTree.Point(coordinates)); + } + for (boolean bulkBuild : new boolean[] {false, true}) { + for (int shift : new int[] {0, 4, 9}) { + List remaining = new ArrayList<>(initial); + List order = new ArrayList<>(initial); + Collections.rotate(order, shift); + KDTree tree = bulkBuild ? new KDTree(initial.toArray(KDTree.Point[] ::new)) : insertedTree(initial); + assertContents(tree, remaining); + for (KDTree.Point point : order) { + tree.delete(point); + remaining.remove(point); + assertContents(tree, remaining); + Assertions.assertFalse(tree.search(point).isPresent()); + } + Assertions.assertNull(tree.getRoot()); + } + } + } + } + + private static KDTree.Point pointOf(int coordinate) { + return new KDTree.Point(new int[] {coordinate, coordinate}); + } + + private static List pointsOf(int... coordinates) { + List points = new ArrayList<>(); + for (int coordinate : coordinates) { + points.add(pointOf(coordinate)); + } + return points; + } + + private static KDTree insertedTree(List points) { + KDTree tree = new KDTree(points.getFirst().getDimension()); + for (KDTree.Point point : points) { + tree.insert(point); + } + return tree; + } + + private static void assertContents(KDTree tree, List expected) { + List actual = new ArrayList<>(); + collectPoints(tree.getRoot(), actual); + Assertions.assertEquals(expected.size(), actual.size()); + Assertions.assertEquals(Set.copyOf(expected), Set.copyOf(actual)); + for (KDTree.Point point : expected) { + Assertions.assertTrue(tree.search(point).isPresent(), () -> "Surviving point is unreachable: " + point); + } + if (!expected.isEmpty()) { + for (int axis = 0; axis < expected.getFirst().getDimension(); axis++) { + int minimum = Integer.MAX_VALUE; + int maximum = Integer.MIN_VALUE; + for (KDTree.Point point : expected) { + minimum = Math.min(minimum, point.getCoordinate(axis)); + maximum = Math.max(maximum, point.getCoordinate(axis)); + } + Assertions.assertEquals(minimum, tree.findMin(axis).getCoordinate(axis)); + Assertions.assertEquals(maximum, tree.findMax(axis).getCoordinate(axis)); + } + } + } + + private static void collectPoints(KDTree.Node node, List points) { + if (node != null) { + points.add(node.getPoint()); + collectPoints(node.getLeft(), points); + collectPoints(node.getRight(), points); + } + } +} From 26db7bab681453fdf2fc44c67c6f50a0da7983c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dilara=20=C3=87etin?= <155580901+dilaraacetin@users.noreply.github.com> Date: Mon, 5 Oct 2026 23:37:20 +0300 Subject: [PATCH 40/92] Feature/hors signature (#7635) * feat(ciphers): add HORS few-time signature scheme * test(ciphers): add tests for HORS signature * fix(ciphers): require k as a verify parameter in HORS --- .../thealgorithms/ciphers/HorsSignature.java | 211 ++++++++++++++++++ .../ciphers/HorsSignatureTest.java | 201 +++++++++++++++++ 2 files changed, 412 insertions(+) create mode 100644 src/main/java/com/thealgorithms/ciphers/HorsSignature.java create mode 100644 src/test/java/com/thealgorithms/ciphers/HorsSignatureTest.java diff --git a/src/main/java/com/thealgorithms/ciphers/HorsSignature.java b/src/main/java/com/thealgorithms/ciphers/HorsSignature.java new file mode 100644 index 000000000000..64731cde76d2 --- /dev/null +++ b/src/main/java/com/thealgorithms/ciphers/HorsSignature.java @@ -0,0 +1,211 @@ +package com.thealgorithms.ciphers; + +import java.security.MessageDigest; +import java.security.NoSuchAlgorithmException; +import java.security.SecureRandom; + +/** + * HORS (Hash to Obtain Random Subset) is a hash-based few-time signature scheme by Reyzin and + * Reyzin (2002). + * + *

The private key consists of {@code t = 2^Ï„} random 32-byte secrets and the public key contains + * their SHA-256 hashes. To sign, the SHA-256 digest of the message is split into {@code k} chunks of + * {@code Ï„} bits (most significant bit first); each chunk is an index into the key, and the secrets + * at those {@code k} indices form the signature. The verifier derives the same indices and checks + * that each revealed secret hashes to the matching public-key value. The same index may appear more + * than once, as in the original scheme. Signing is deterministic. + * + *

HORS is a few-time scheme: each signature reveals {@code k} secrets, so after {@code r} + * signatures an attacker knows at most {@code r·k} of them. If all indices of another message fall + * into that set, its signature can be forged, so security decreases with every signature. + * + *

HORST compresses the large public key with a Merkle tree. FORS, used in SPHINCS+ and SLH-DSA + * (FIPS 205), uses a forest of trees instead, which also removes the repeated-index weakness. This + * implementation is educational and must not be used in production. + * + *

References: Reyzin and Reyzin, Better than BiBa, + * Wikipedia: Hash-based cryptography + * + * @author dilaraacetin + * @see LamportSignature + * @see WinternitzSignature + * @see MerkleSignatureScheme + */ +public final class HorsSignature { + + // SHA-256 output length in bytes + private static final int HASH_BYTES = 32; + private static final int DIGEST_BITS = 256; + private static final int MIN_T = 16; + private static final int MAX_T = 65536; + private static final int DEFAULT_T = 1024; + private static final int DEFAULT_K = 16; + + private final int k; + private final int tau; + private final byte[][] privateKey; + private final byte[][] publicKey; + + /** + * Generates a new key pair with {@code t = 1024} and {@code k = 16}. + */ + public HorsSignature() { + this(DEFAULT_T, DEFAULT_K); + } + + /** + * Generates a new key pair. + * + * @param t the number of secrets; a power of two between 16 and 65536 + * @param k the number of secrets revealed per signature; {@code k·log2(t)} must not exceed 256 + * @throws IllegalArgumentException if {@code t} or {@code k} is not supported + */ + public HorsSignature(int t, int k) { + this.tau = tauOf(t); + validateK(k, tau); + this.k = k; + SecureRandom secureRandom = new SecureRandom(); + privateKey = new byte[t][HASH_BYTES]; + publicKey = new byte[t][]; + for (int i = 0; i < t; i++) { + secureRandom.nextBytes(privateKey[i]); + publicKey[i] = hash(privateKey[i]); + } + } + + /** + * Returns a copy of the public key. + * + * @return {@code t} hash values, each 32 bytes long + */ + public byte[][] getPublicKey() { + return deepCopy(publicKey); + } + + /** + * Returns the number of secrets revealed per signature. Like {@code t}, it is part of the public + * key and is needed for verification. + * + * @return the parameter {@code k} + */ + public int getK() { + return k; + } + + /** + * Signs a message. Every signature reveals {@code k} secrets, so a key pair should only sign a + * few messages. + * + * @param message the message to sign + * @return the signature: {@code k} secrets of 32 bytes each + * @throws IllegalArgumentException if the message is null + */ + public byte[][] sign(byte[] message) { + if (message == null) { + throw new IllegalArgumentException("message must not be null"); + } + int[] indices = messageIndices(hash(message), k, tau); + byte[][] signature = new byte[k][]; + for (int j = 0; j < k; j++) { + signature[j] = privateKey[indices[j]].clone(); + } + return signature; + } + + /** + * Verifies a signature against a public key. {@code t} is taken from the public key length. + * {@code k} is part of the public key and must be supplied by the verifier: taking it from the + * signature would let an attacker submit a shorter signature that reveals fewer secrets. + * + * @param message the signed message + * @param signature the signature to check + * @param publicKey the public key of the signer + * @param k the number of secrets per signature used by the signer (see {@link #getK()}) + * @return true if the signature is valid for the message and public key, false otherwise + * @throws IllegalArgumentException if an argument is null, the public key length is not a + * supported {@code t}, {@code k} is not supported for this {@code t}, a value is not 32 + * bytes long, or the signature does not contain exactly {@code k} values + */ + public static boolean verify(byte[] message, byte[][] signature, byte[][] publicKey, int k) { + if (message == null) { + throw new IllegalArgumentException("message must not be null"); + } + validateValues(publicKey, "publicKey"); + validateValues(signature, "signature"); + int tau = tauOf(publicKey.length); + validateK(k, tau); + if (signature.length != k) { + throw new IllegalArgumentException("signature must contain exactly " + k + " values, got " + signature.length); + } + + int[] indices = messageIndices(hash(message), k, tau); + for (int j = 0; j < k; j++) { + if (!MessageDigest.isEqual(hash(signature[j]), publicKey[indices[j]])) { + return false; + } + } + return true; + } + + /** + * Splits the first {@code k·τ} bits of a digest into {@code k} unsigned {@code τ}-bit indices, + * most significant bit first. Shared by sign and verify. + */ + static int[] messageIndices(byte[] digest, int k, int tau) { + if ((long) k * tau > digest.length * 8L) { + throw new IllegalArgumentException("digest is too short for " + k + " indices of " + tau + " bits"); + } + int[] indices = new int[k]; + for (int j = 0; j < k; j++) { + int index = 0; + for (int i = 0; i < tau; i++) { + int bit = j * tau + i; + // bit 0 is the most significant bit of digest[0]; & 0xFF reads the byte as unsigned + index = (index << 1) | (((digest[bit / 8] & 0xFF) >> (7 - bit % 8)) & 1); + } + indices[j] = index; + } + return indices; + } + + private static int tauOf(int t) { + if (t < MIN_T || t > MAX_T || (t & (t - 1)) != 0) { + throw new IllegalArgumentException("t must be a power of two between " + MIN_T + " and " + MAX_T + ", got " + t); + } + return Integer.numberOfTrailingZeros(t); + } + + private static void validateK(int k, int tau) { + // k > DIGEST_BITS / tau is the same as k * tau > DIGEST_BITS, but cannot overflow + if (k < 1 || k > DIGEST_BITS / tau) { + throw new IllegalArgumentException("k must be at least 1 and k * log2(t) at most " + DIGEST_BITS + ", got k = " + k); + } + } + + private static void validateValues(byte[][] values, String name) { + if (values == null) { + throw new IllegalArgumentException(name + " must not be null"); + } + for (byte[] value : values) { + if (value == null || value.length != HASH_BYTES) { + throw new IllegalArgumentException(name + " values must be exactly " + HASH_BYTES + " bytes long"); + } + } + } + + private static byte[] hash(byte[] data) { + try { + return MessageDigest.getInstance("SHA-256").digest(data); + } catch (NoSuchAlgorithmException e) { + throw new AssertionError("SHA-256 is required by the Java SE specification", e); + } + } + + private static byte[][] deepCopy(byte[][] values) { + byte[][] copy = new byte[values.length][]; + for (int i = 0; i < values.length; i++) { + copy[i] = values[i].clone(); + } + return copy; + } +} diff --git a/src/test/java/com/thealgorithms/ciphers/HorsSignatureTest.java b/src/test/java/com/thealgorithms/ciphers/HorsSignatureTest.java new file mode 100644 index 000000000000..bb22a24a2a62 --- /dev/null +++ b/src/test/java/com/thealgorithms/ciphers/HorsSignatureTest.java @@ -0,0 +1,201 @@ +package com.thealgorithms.ciphers; + +import static org.junit.jupiter.api.Assertions.assertArrayEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.nio.charset.StandardCharsets; +import java.security.MessageDigest; +import java.security.NoSuchAlgorithmException; +import java.util.Arrays; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.CsvSource; + +class HorsSignatureTest { + + private static final byte[] MESSAGE = "hello hors".getBytes(StandardCharsets.UTF_8); + + @Test + void testValidSignatureVerifies() { + HorsSignature keyPair = new HorsSignature(); + + byte[][] signature = keyPair.sign(MESSAGE); + + assertTrue(HorsSignature.verify(MESSAGE, signature, keyPair.getPublicKey(), keyPair.getK())); + } + + @Test + void testSameKeySignsSeveralMessages() { + HorsSignature keyPair = new HorsSignature(); + byte[][] publicKey = keyPair.getPublicKey(); + + for (int i = 0; i < 5; i++) { + byte[] message = ("message " + i).getBytes(StandardCharsets.UTF_8); + byte[][] signature = keyPair.sign(message); + + assertTrue(HorsSignature.verify(message, signature, publicKey, keyPair.getK())); + } + } + + @Test + void testSigningIsDeterministic() { + HorsSignature keyPair = new HorsSignature(); + + assertArrayEquals(keyPair.sign(MESSAGE), keyPair.sign(MESSAGE)); + } + + @Test + void testTamperedMessageFailsVerification() { + HorsSignature keyPair = new HorsSignature(); + byte[][] signature = keyPair.sign(MESSAGE); + byte[] tampered = MESSAGE.clone(); + + tampered[0] ^= 0x01; + + assertFalse(HorsSignature.verify(tampered, signature, keyPair.getPublicKey(), keyPair.getK())); + } + + @Test + void testTamperedSignatureFailsVerification() { + HorsSignature keyPair = new HorsSignature(); + byte[][] signature = keyPair.sign(MESSAGE); + + signature[3][0] ^= 0x01; + + assertFalse(HorsSignature.verify(MESSAGE, signature, keyPair.getPublicKey(), keyPair.getK())); + } + + @Test + void testDifferentPublicKeyDoesNotVerify() { + HorsSignature keyPair1 = new HorsSignature(); + HorsSignature keyPair2 = new HorsSignature(); + + byte[][] signature = keyPair1.sign(MESSAGE); + + assertFalse(HorsSignature.verify(MESSAGE, signature, keyPair2.getPublicKey(), keyPair1.getK())); + } + + @Test + void testMessageIndicesWithByteAlignedTau() { + byte[] digest = new byte[32]; + digest[0] = (byte) 0xFF; + digest[1] = 0x00; + digest[2] = (byte) 0x80; + digest[3] = 0x7F; + + assertArrayEquals(new int[] {255, 0, 128, 127}, HorsSignature.messageIndices(digest, 4, 8)); + } + + @Test + void testMessageIndicesAcrossByteBoundaries() { + byte[] first = new byte[32]; + first[0] = (byte) 0xFF; + first[1] = (byte) 0xC0; + byte[] second = new byte[32]; + second[1] = 0x7F; + second[2] = (byte) 0xF0; + + // 11111111 11|000000 0000 -> [1023, 0] + assertArrayEquals(new int[] {1023, 0}, HorsSignature.messageIndices(first, 2, 10)); + // 00000000 01|111111 1111 -> [1, 1023] + assertArrayEquals(new int[] {1, 1023}, HorsSignature.messageIndices(second, 2, 10)); + } + + @Test + void testSignatureRevealsSecretsAtDerivedIndices() throws NoSuchAlgorithmException { + HorsSignature keyPair = new HorsSignature(); + byte[][] publicKey = keyPair.getPublicKey(); + + byte[][] signature = keyPair.sign(MESSAGE); + + int[] indices = HorsSignature.messageIndices(sha256(MESSAGE), 16, 10); + byte[][] expectedHashes = new byte[16][]; + byte[][] actualHashes = new byte[signature.length][]; + int[] expectedLengths = new int[16]; + int[] actualLengths = new int[signature.length]; + Arrays.fill(expectedLengths, 32); + for (int j = 0; j < signature.length; j++) { + actualHashes[j] = sha256(signature[j]); + actualLengths[j] = signature[j].length; + } + for (int j = 0; j < 16; j++) { + expectedHashes[j] = publicKey[indices[j]]; + } + + assertArrayEquals(expectedLengths, actualLengths); + assertArrayEquals(expectedHashes, actualHashes); + } + + @ParameterizedTest + @CsvSource({"16, 4", "256, 32", "1024, 16", "4096, 21"}) + void testSignAndVerifyForDifferentParameters(int t, int k) { + HorsSignature keyPair = new HorsSignature(t, k); + + byte[][] signature = keyPair.sign(MESSAGE); + + assertArrayEquals(new int[] {k, k, t}, new int[] {signature.length, keyPair.getK(), keyPair.getPublicKey().length}); + assertTrue(HorsSignature.verify(MESSAGE, signature, keyPair.getPublicKey(), k)); + } + + @ParameterizedTest + @CsvSource({"0, 16", "8, 2", "100, 4", "131072, 4", "1024, 0", "1024, 26", "1024, -1", "1024, 2147483647"}) + void testUnsupportedParametersThrowException(int t, int k) { + assertThrows(IllegalArgumentException.class, () -> new HorsSignature(t, k)); + } + + @Test + void testNullAndMalformedInput() { + HorsSignature keyPair = new HorsSignature(16, 4); + byte[][] publicKey = keyPair.getPublicKey(); + byte[][] signature = keyPair.sign(MESSAGE); + byte[][] nullValue = signature.clone(); + nullValue[0] = null; + byte[][] shortValue = signature.clone(); + shortValue[0] = new byte[31]; + byte[][] tooManyValues = new byte[65][32]; + + assertThrows(IllegalArgumentException.class, () -> keyPair.sign(null)); + assertThrows(IllegalArgumentException.class, () -> HorsSignature.verify(null, signature, publicKey, 4)); + assertThrows(IllegalArgumentException.class, () -> HorsSignature.verify(MESSAGE, null, publicKey, 4)); + assertThrows(IllegalArgumentException.class, () -> HorsSignature.verify(MESSAGE, nullValue, publicKey, 4)); + assertThrows(IllegalArgumentException.class, () -> HorsSignature.verify(MESSAGE, shortValue, publicKey, 4)); + assertThrows(IllegalArgumentException.class, () -> HorsSignature.verify(MESSAGE, new byte[0][], publicKey, 4)); + assertThrows(IllegalArgumentException.class, () -> HorsSignature.verify(MESSAGE, tooManyValues, publicKey, 4)); + assertThrows(IllegalArgumentException.class, () -> HorsSignature.verify(MESSAGE, signature, null, 4)); + assertThrows(IllegalArgumentException.class, () -> HorsSignature.verify(MESSAGE, signature, new byte[15][32], 4)); + assertThrows(IllegalArgumentException.class, () -> HorsSignature.verify(MESSAGE, signature, nullValue, 4)); + assertThrows(IllegalArgumentException.class, () -> HorsSignature.verify(MESSAGE, signature, publicKey, 3)); + assertThrows(IllegalArgumentException.class, () -> HorsSignature.verify(MESSAGE, signature, publicKey, 0)); + assertThrows(IllegalArgumentException.class, () -> HorsSignature.verify(MESSAGE, tooManyValues, publicKey, 65)); + assertThrows(IllegalArgumentException.class, () -> HorsSignature.messageIndices(new byte[1], 2, 8)); + } + + @Test + void testTruncatedSignatureIsRejected() { + HorsSignature keyPair = new HorsSignature(); + byte[][] truncated = Arrays.copyOf(keyPair.sign(MESSAGE), 1); + + assertThrows(IllegalArgumentException.class, () -> HorsSignature.verify(MESSAGE, truncated, keyPair.getPublicKey(), keyPair.getK())); + } + + @Test + void testModifyingReturnedArraysDoesNotChangeInternalState() { + HorsSignature keyPair = new HorsSignature(); + byte[][] expectedPublicKey = keyPair.getPublicKey(); + byte[][] expectedSignature = keyPair.sign(MESSAGE); + + keyPair.getPublicKey()[0][0] ^= 0x01; + keyPair.getPublicKey()[1] = new byte[32]; + keyPair.sign(MESSAGE)[0][0] ^= 0x01; + + assertArrayEquals(expectedPublicKey, keyPair.getPublicKey()); + assertArrayEquals(expectedSignature, keyPair.sign(MESSAGE)); + assertTrue(HorsSignature.verify(MESSAGE, expectedSignature, keyPair.getPublicKey(), keyPair.getK())); + } + + private static byte[] sha256(byte[] data) throws NoSuchAlgorithmException { + return MessageDigest.getInstance("SHA-256").digest(data); + } +} From f5772e30f1614ce15887a95c53a01fb01f4d803d Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 6 Oct 2026 09:44:06 +0200 Subject: [PATCH 41/92] chore(deps): bump com.puppycrawl.tools:checkstyle from 14.1.0 to 14.3.0 (#7636) Bumps [com.puppycrawl.tools:checkstyle](https://github.com/checkstyle/checkstyle) from 14.1.0 to 14.3.0. - [Release notes](https://github.com/checkstyle/checkstyle/releases) - [Commits](https://github.com/checkstyle/checkstyle/compare/checkstyle-14.1.0...checkstyle-14.3.0) --- updated-dependencies: - dependency-name: com.puppycrawl.tools:checkstyle dependency-version: 14.3.0 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 63a188874af3..5a166dbf4fe5 100644 --- a/pom.xml +++ b/pom.xml @@ -112,7 +112,7 @@ com.puppycrawl.tools checkstyle - 14.1.0 + 14.3.0 From 9d9e34884f6be3f1ffb0d69ceeea2b07393fa9ef Mon Sep 17 00:00:00 2001 From: Rohan Gangawane <147078292+Rohan45create@users.noreply.github.com> Date: Tue, 6 Oct 2026 20:54:42 +0530 Subject: [PATCH 42/92] Add Fenwick tree implementation and tests (#7637) * Add Fenwick tree implementation and tests * Fix FenwickTree test filename and add documentation link --- .../datastructures/trees/FenwickTree.java | 31 ++- .../datastructures/trees/FenwickTreeTest.java | 115 +++++++++++ "ts\"" | 179 ++++++++++++++++++ 3 files changed, 317 insertions(+), 8 deletions(-) create mode 100644 src/test/java/com/thealgorithms/datastructures/trees/FenwickTreeTest.java create mode 100644 "ts\"" diff --git a/src/main/java/com/thealgorithms/datastructures/trees/FenwickTree.java b/src/main/java/com/thealgorithms/datastructures/trees/FenwickTree.java index 5378a01f6642..e9c355baa4eb 100644 --- a/src/main/java/com/thealgorithms/datastructures/trees/FenwickTree.java +++ b/src/main/java/com/thealgorithms/datastructures/trees/FenwickTree.java @@ -1,29 +1,37 @@ package com.thealgorithms.datastructures.trees; +/** + * Fenwick Tree for point updates and prefix-sum queries in O(log n). + * + * @see Fenwick Tree + */ public class FenwickTree { - private int n; - private int[] fenTree; + private final int n; + private final int[] fenTree; - /* Constructor which takes the size of the array as a parameter */ + /** Creates a Fenwick tree with n elements, all initialized to zero. */ public FenwickTree(int n) { + if (n < 0) { + throw new IllegalArgumentException("Size must be non-negative"); + } this.n = n; this.fenTree = new int[n + 1]; } - /* A function which will add the element val at index i*/ + /** Adds val to the element at index i. */ public void update(int i, int val) { - // As index starts from 0, increment the index by 1 - i += 1; + checkIndex(i); + i += 1; // Convert to the internal 1-based index while (i <= n) { fenTree[i] += val; i += i & (-i); } } - /* A function which will return the cumulative sum from index 1 to index i*/ + /** Returns the sum of elements from index 0 to i. */ public int query(int i) { - // As index starts from 0, increment the index by 1 + checkIndex(i); i += 1; int cumSum = 0; while (i > 0) { @@ -32,4 +40,11 @@ public int query(int i) { } return cumSum; } + + // Check that the index is within the valid range. + private void checkIndex(int i) { + if (i < 0 || i >= n) { + throw new IndexOutOfBoundsException("Index " + i + " out of bounds for size " + n); + } + } } diff --git a/src/test/java/com/thealgorithms/datastructures/trees/FenwickTreeTest.java b/src/test/java/com/thealgorithms/datastructures/trees/FenwickTreeTest.java new file mode 100644 index 000000000000..47ef568e5d1f --- /dev/null +++ b/src/test/java/com/thealgorithms/datastructures/trees/FenwickTreeTest.java @@ -0,0 +1,115 @@ +package com.thealgorithms.datastructures.trees; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; + +import java.util.Random; +import org.junit.jupiter.api.Test; + +class FenwickTreeTest { + + @Test + void queryOnFreshTreeReturnsZero() { + FenwickTree tree = new FenwickTree(5); + for (int i = 0; i < 5; i++) { + assertEquals(0, tree.query(i)); + } + } + + @Test + void singleElementTree() { + FenwickTree tree = new FenwickTree(1); + tree.update(0, 7); + assertEquals(7, tree.query(0)); + } + + @Test + void prefixSumsAfterUpdates() { + FenwickTree tree = new FenwickTree(5); + int[] values = {3, 2, -1, 6, 5}; + for (int i = 0; i < values.length; i++) { + tree.update(i, values[i]); + } + assertEquals(3, tree.query(0)); + assertEquals(5, tree.query(1)); + assertEquals(4, tree.query(2)); + assertEquals(10, tree.query(3)); + assertEquals(15, tree.query(4)); + } + + @Test + void repeatedUpdatesOnSameIndexAccumulate() { + FenwickTree tree = new FenwickTree(4); + tree.update(2, 5); + tree.update(2, 3); + tree.update(2, -2); + assertEquals(0, tree.query(1)); + assertEquals(6, tree.query(2)); + assertEquals(6, tree.query(3)); + } + + @Test + void negativeValues() { + FenwickTree tree = new FenwickTree(3); + tree.update(0, -4); + tree.update(1, -6); + tree.update(2, 10); + assertEquals(-4, tree.query(0)); + assertEquals(-10, tree.query(1)); + assertEquals(0, tree.query(2)); + } + + @Test + void nonPowerOfTwoSize() { + int size = 13; + FenwickTree tree = new FenwickTree(size); + for (int i = 0; i < size; i++) { + tree.update(i, 1); + } + for (int i = 0; i < size; i++) { + assertEquals(i + 1, tree.query(i)); + } + } + + @Test + void matchesNaivePrefixSumOnRandomData() { + Random random = new Random(42); + int size = 100; + FenwickTree tree = new FenwickTree(size); + int[] naive = new int[size]; + + for (int step = 0; step < 500; step++) { + int index = random.nextInt(size); + int delta = random.nextInt(21) - 10; + tree.update(index, delta); + naive[index] += delta; + } + + int running = 0; + for (int i = 0; i < size; i++) { + running += naive[i]; + assertEquals(running, tree.query(i), "Mismatch at index " + i); + } + } + + @Test + void zeroSizeTreeRejectsAnyIndex() { + FenwickTree tree = new FenwickTree(0); + assertThrows(IndexOutOfBoundsException.class, () -> tree.update(0, 1)); + assertThrows(IndexOutOfBoundsException.class, () -> tree.query(0)); + } + + @Test + void negativeSizeThrows() { + assertThrows(IllegalArgumentException.class, () -> new FenwickTree(-1)); + } + + @Test + void outOfBoundsIndicesThrow() { + FenwickTree tree = new FenwickTree(5); + assertThrows(IndexOutOfBoundsException.class, () -> tree.update(-1, 1)); + assertThrows(IndexOutOfBoundsException.class, () -> tree.update(5, 1)); + assertThrows(IndexOutOfBoundsException.class, () -> tree.query(-1)); + assertThrows(IndexOutOfBoundsException.class, () -> tree.query(5)); + } +} diff --git "a/ts\"" "b/ts\"" new file mode 100644 index 000000000000..daddada971db --- /dev/null +++ "b/ts\"" @@ -0,0 +1,179 @@ +diff --git a/src/main/java/com/thealgorithms/datastructures/trees/FenwickTree.java b/src/main/java/com/thealgorithms/datastructures/trees/FenwickTree.java +index 5378a01..be8a92e 100644 +--- a/src/main/java/com/thealgorithms/datastructures/trees/FenwickTree.java ++++ b/src/main/java/com/thealgorithms/datastructures/trees/FenwickTree.java +@@ -1,29 +1,33 @@ + package com.thealgorithms.datastructures.trees; +  ++/** Fenwick Tree for point updates and prefix-sum queries in O(log n). */ + public class FenwickTree { +  +- private int n; +- private int[] fenTree; ++ private final int n; ++ private final int[] fenTree; +  +- /* Constructor which takes the size of the array as a parameter */ ++ /** Creates a Fenwick tree with n elements, all initialized to zero. */ + public FenwickTree(int n) { ++ if (n < 0) { ++ throw new IllegalArgumentException("Size must be non-negative"); ++ } + this.n = n; + this.fenTree = new int[n + 1]; + } +  +- /* A function which will add the element val at index i*/ ++ /** Adds val to the element at index i. */ + public void update(int i, int val) { +- // As index starts from 0, increment the index by 1 +- i += 1; ++ checkIndex(i); ++ i += 1; // Convert to the internal 1-based index + while (i <= n) { + fenTree[i] += val; + i += i & (-i); + } + } +  +- /* A function which will return the cumulative sum from index 1 to index i*/ ++ /** Returns the sum of elements from index 0 to i. */ + public int query(int i) { +- // As index starts from 0, increment the index by 1 ++ checkIndex(i); + i += 1; + int cumSum = 0; + while (i > 0) { +@@ -32,4 +36,11 @@ public class FenwickTree { + } + return cumSum; + } ++ ++ // Check that the index is within the valid range. ++ private void checkIndex(int i) { ++ if (i < 0 || i >= n) { ++ throw new IndexOutOfBoundsException("Index " + i + " out of bounds for size " + n); ++ } ++ } + } +diff --git a/src/test/java/com/thealgorithms/datastructures/trees/FenwickTree.java b/src/test/java/com/thealgorithms/datastructures/trees/FenwickTree.java +new file mode 100644 +index 0000000..47ef568 +--- /dev/null ++++ b/src/test/java/com/thealgorithms/datastructures/trees/FenwickTree.java +@@ -0,0 +1,115 @@ ++package com.thealgorithms.datastructures.trees; ++ ++import static org.junit.jupiter.api.Assertions.assertEquals; ++import static org.junit.jupiter.api.Assertions.assertThrows; ++ ++import java.util.Random; ++import org.junit.jupiter.api.Test; ++ ++class FenwickTreeTest { ++ ++ @Test ++ void queryOnFreshTreeReturnsZero() { ++ FenwickTree tree = new FenwickTree(5); ++ for (int i = 0; i < 5; i++) { ++ assertEquals(0, tree.query(i)); ++ } ++ } ++ ++ @Test ++ void singleElementTree() { ++ FenwickTree tree = new FenwickTree(1); ++ tree.update(0, 7); ++ assertEquals(7, tree.query(0)); ++ } ++ ++ @Test ++ void prefixSumsAfterUpdates() { ++ FenwickTree tree = new FenwickTree(5); ++ int[] values = {3, 2, -1, 6, 5}; ++ for (int i = 0; i < values.length; i++) { ++ tree.update(i, values[i]); ++ } ++ assertEquals(3, tree.query(0)); ++ assertEquals(5, tree.query(1)); ++ assertEquals(4, tree.query(2)); ++ assertEquals(10, tree.query(3)); ++ assertEquals(15, tree.query(4)); ++ } ++ ++ @Test ++ void repeatedUpdatesOnSameIndexAccumulate() { ++ FenwickTree tree = new FenwickTree(4); ++ tree.update(2, 5); ++ tree.update(2, 3); ++ tree.update(2, -2); ++ assertEquals(0, tree.query(1)); ++ assertEquals(6, tree.query(2)); ++ assertEquals(6, tree.query(3)); ++ } ++ ++ @Test ++ void negativeValues() { ++ FenwickTree tree = new FenwickTree(3); ++ tree.update(0, -4); ++ tree.update(1, -6); ++ tree.update(2, 10); ++ assertEquals(-4, tree.query(0)); ++ assertEquals(-10, tree.query(1)); ++ assertEquals(0, tree.query(2)); ++ } ++ ++ @Test ++ void nonPowerOfTwoSize() { ++ int size = 13; ++ FenwickTree tree = new FenwickTree(size); ++ for (int i = 0; i < size; i++) { ++ tree.update(i, 1); ++ } ++ for (int i = 0; i < size; i++) { ++ assertEquals(i + 1, tree.query(i)); ++ } ++ } ++ ++ @Test ++ void matchesNaivePrefixSumOnRandomData() { ++ Random random = new Random(42); ++ int size = 100; ++ FenwickTree tree = new FenwickTree(size); ++ int[] naive = new int[size]; ++ ++ for (int step = 0; step < 500; step++) { ++ int index = random.nextInt(size); ++ int delta = random.nextInt(21) - 10; ++ tree.update(index, delta); ++ naive[index] += delta; ++ } ++ ++ int running = 0; ++ for (int i = 0; i < size; i++) { ++ running += naive[i]; ++ assertEquals(running, tree.query(i), "Mismatch at index " + i); ++ } ++ } ++ ++ @Test ++ void zeroSizeTreeRejectsAnyIndex() { ++ FenwickTree tree = new FenwickTree(0); ++ assertThrows(IndexOutOfBoundsException.class, () -> tree.update(0, 1)); ++ assertThrows(IndexOutOfBoundsException.class, () -> tree.query(0)); ++ } ++ ++ @Test ++ void negativeSizeThrows() { ++ assertThrows(IllegalArgumentException.class, () -> new FenwickTree(-1)); ++ } ++ ++ @Test ++ void outOfBoundsIndicesThrow() { ++ FenwickTree tree = new FenwickTree(5); ++ assertThrows(IndexOutOfBoundsException.class, () -> tree.update(-1, 1)); ++ assertThrows(IndexOutOfBoundsException.class, () -> tree.update(5, 1)); ++ assertThrows(IndexOutOfBoundsException.class, () -> tree.query(-1)); ++ assertThrows(IndexOutOfBoundsException.class, () -> tree.query(5)); ++ } ++} From cb6f438d08e15b1d99778911cabfff966f130211 Mon Sep 17 00:00:00 2001 From: datpp Date: Fri, 9 Oct 2026 16:13:12 +0700 Subject: [PATCH 43/92] test: add white-box unit tests for Luhn.luhnCheck (#7641) * test: add white-box unit tests for Luhn.luhnCheck Cover the loop (zero, one and many iterations), both outcomes of the `i % 2 == 0` and `temp > 9` decisions, boundary values (8 / 10 after doubling), valid and invalid checksums, input immutability and null input. * test: drop null input case flagged by Infer Infer reports NULLPTR_DEREFERENCE for passing null to luhnCheck on purpose. The method does not document null handling, so the case is removed. --- .../com/thealgorithms/others/LuhnTest.java | 105 ++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 src/test/java/com/thealgorithms/others/LuhnTest.java diff --git a/src/test/java/com/thealgorithms/others/LuhnTest.java b/src/test/java/com/thealgorithms/others/LuhnTest.java new file mode 100644 index 000000000000..2e2c294a3352 --- /dev/null +++ b/src/test/java/com/thealgorithms/others/LuhnTest.java @@ -0,0 +1,105 @@ +package com.thealgorithms.others; + +import static org.junit.jupiter.api.Assertions.assertArrayEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import org.junit.jupiter.api.Test; + +/** + * White-box tests for {@link Luhn#luhnCheck(int[])}. + * + *

The method has one loop and two decisions: + *

    + *
  • D1: {@code i % 2 == 0} - whether the digit at index i is doubled
  • + *
  • D2: {@code temp > 9} - whether 9 is subtracted from the doubled digit
  • + *
+ * The tests below cover the loop executed zero, one and many times, both + * outcomes of each decision, and both outcomes of the final {@code sum % 10 == 0}. + */ +class LuhnTest { + + @Test + void testEmptyArraySkipsLoopAndIsValid() { + // Loop body never executes, sum stays 0 + assertTrue(Luhn.luhnCheck(new int[] {})); + } + + @Test + void testSingleZeroDigitIsValid() { + // One iteration: D1 true, D2 false (0 * 2 = 0) + assertTrue(Luhn.luhnCheck(new int[] {0})); + } + + @Test + void testSingleDigitDoubledWithoutSubtractionIsInvalid() { + // One iteration: D1 true, D2 false (4 * 2 = 8, upper boundary of temp <= 9) + assertFalse(Luhn.luhnCheck(new int[] {4})); + } + + @Test + void testSingleDigitDoubledWithSubtractionIsInvalid() { + // One iteration: D1 true, D2 true (5 * 2 = 10, lower boundary of temp > 9 -> 1) + assertFalse(Luhn.luhnCheck(new int[] {5})); + } + + @Test + void testTwoDigitsWithoutSubtraction() { + // i = 1: D1 false -> 2; i = 0: D1 true, D2 false -> 8; sum = 10 + assertTrue(Luhn.luhnCheck(new int[] {4, 2})); + } + + @Test + void testTwoDigitsWithSubtraction() { + // i = 1: D1 false -> 9; i = 0: D1 true, D2 true -> 10 - 9 = 1; sum = 10 + assertTrue(Luhn.luhnCheck(new int[] {5, 9})); + } + + @Test + void testTwoDigitsInvalidChecksum() { + // i = 1: D1 false -> 3; i = 0: D1 true, D2 false -> 8; sum = 11 + assertFalse(Luhn.luhnCheck(new int[] {4, 3})); + } + + @Test + void testMaxDigitDoubled() { + // i = 1: D1 false -> 0; i = 0: D1 true, D2 true -> 18 - 9 = 9; sum = 9 + assertFalse(Luhn.luhnCheck(new int[] {9, 0})); + // i = 1: D1 false -> 1; i = 0: D1 true, D2 true -> 9; sum = 10 + assertTrue(Luhn.luhnCheck(new int[] {9, 1})); + } + + @Test + void testValidCardNumbers() { + // Many iterations, all branch combinations exercised + assertTrue(Luhn.luhnCheck(new int[] {4, 5, 6, 1, 2, 6, 1, 2, 1, 2, 3, 4, 5, 4, 6, 7})); + assertTrue(Luhn.luhnCheck(new int[] {5, 2, 6, 5, 9, 2, 5, 1, 6, 1, 5, 1, 1, 4, 1, 2})); + assertTrue(Luhn.luhnCheck(new int[] {4, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1})); + } + + @Test + void testCardNumberWithTypoInLastDigitIsInvalid() { + assertFalse(Luhn.luhnCheck(new int[] {4, 5, 6, 1, 2, 6, 1, 2, 1, 2, 3, 4, 5, 4, 6, 4})); + } + + @Test + void testCardNumberWithSingleDigitErrorIsInvalid() { + // Error in a doubled position (index 0) + assertFalse(Luhn.luhnCheck(new int[] {3, 5, 6, 1, 2, 6, 1, 2, 1, 2, 3, 4, 5, 4, 6, 7})); + // Error in a non-doubled position (index 1) + assertFalse(Luhn.luhnCheck(new int[] {4, 6, 6, 1, 2, 6, 1, 2, 1, 2, 3, 4, 5, 4, 6, 7})); + } + + @Test + void testAllZerosIsValid() { + assertTrue(Luhn.luhnCheck(new int[16])); + } + + @Test + void testInputArrayIsNotModified() { + int[] digits = {5, 2, 6, 5, 9, 2, 5, 1, 6, 1, 5, 1, 1, 4, 1, 2}; + int[] copy = digits.clone(); + Luhn.luhnCheck(digits); + assertArrayEquals(copy, digits); + } +} From 5eb9d6634cfe84b1d53daf83187f8d11eca0bbb8 Mon Sep 17 00:00:00 2001 From: Oleksandr Klymenko Date: Fri, 9 Oct 2026 12:17:42 +0300 Subject: [PATCH 44/92] feat: add TDigest, every quantile of a stream from one sketch (#7642) P2QuantileEstimator tracks one quantile chosen in advance, in constant memory. A t-digest keeps a small list of centroids, each a mean and a weight, sorted by mean, and answers any quantile and the CDF afterwards from the same sketch. A centroid may absorb points only while it spans at most one unit of the scale function k(q) = d / (2 pi) * asin(2q - 1), and asin is steep at both ends, so centroids in the tails stay at one or a few points while those near the median are allowed to grow. The rank error is of the order of 1 / d around the median and shrinks towards q = 0 and q = 1, which is the trade latency percentiles want: p99.9 comes out nearly exact from a sketch of a few kilobytes. Insertions are buffered and folded into the centroid list in batches, so add is O(log d) amortised; quantile and cdf are O(d) and interpolate linearly between centroids, each treated as sitting at the centre of the weight it carries. The minimum and maximum are tracked separately and returned exactly for q = 0 and q = 1. Two digests merge the way partial sums do, so sketches built on separate shards combine into one. Non-finite samples, invalid weights, quantiles outside [0, 1] and a compression below 10 are refused; queries fold the pending buffer in first, so the class is documented as not thread-safe. Tests: on 100 000 uniform samples every tested quantile lands within 0.01 of the requested rank; on 200 000 Gaussian samples the rank error stays under a bound that narrows towards the tails, from 0.01 at the median to 0.0005 at q = 0.001 and q = 0.999; three shards merged answer within 0.01 of the true rank, with total weight, minimum and maximum exact; the centroid count stays at or below the compression after 200 000 samples for compressions of 20, 100 and 500; and weighted, sorted, constant and heavily duplicated input are covered. Signed-off-by: alxkm <19151554+alxkm@users.noreply.github.com> Co-authored-by: alxkm <19151554+alxkm@users.noreply.github.com> --- .../com/thealgorithms/streaming/TDigest.java | 540 ++++++++++++++++++ .../thealgorithms/streaming/TDigestTest.java | 391 +++++++++++++ 2 files changed, 931 insertions(+) create mode 100644 src/main/java/com/thealgorithms/streaming/TDigest.java create mode 100644 src/test/java/com/thealgorithms/streaming/TDigestTest.java diff --git a/src/main/java/com/thealgorithms/streaming/TDigest.java b/src/main/java/com/thealgorithms/streaming/TDigest.java new file mode 100644 index 000000000000..b1c826b1857c --- /dev/null +++ b/src/main/java/com/thealgorithms/streaming/TDigest.java @@ -0,0 +1,540 @@ +package com.thealgorithms.streaming; + +import java.util.Arrays; + +/** + * A t-digest: a small, mergeable sketch that answers any quantile of a stream, with + * much better accuracy at the tails than in the middle. + * + *

The sketch is a list of centroids, each holding a mean and a weight, kept sorted by mean. + * Together they approximate the distribution of everything ever added. What makes a t-digest more + * than a histogram is the rule that decides how big a centroid is allowed to be: instead of a fixed + * bucket width, the size limit is expressed through a scale function + * + *

+ * k(q) = compression / (2 * pi) * asin(2q - 1)
+ * 
+ * + *

and a centroid may absorb points only while it spans at most one unit of {@code k}. Because + * {@code asin} is steep near {@code q = 0} and {@code q = 1}, centroids near the tails are forced to + * stay tiny - often a single point - while centroids near the median are allowed to grow large. + * That is exactly the trade one wants in practice: the rank error is of the order of + * {@code 1 / compression} around the median and shrinks as {@code q} approaches 0 or 1, so + * {@code p99.9} comes out nearly exact. On smooth data the interpolation between centroids brings + * the error down by another order of magnitude, and the whole sketch still fits in a few kilobytes. + * + *

Insertions are buffered and folded into the centroid list in batches, which keeps the amortised + * cost per sample low. The minimum and the maximum are tracked separately and reported exactly. + * + * + * + * + * + * + * + * + *
Cost, with {@code d} the compression parameter
OperationComplexity
{@link #add(double)}O(log d) amortised
{@link #quantile(double)}, {@link #cdf(double)}O(d)
{@link #merge(TDigest)}O(d log d)
memoryO(d), independent of the stream length
+ * + *

Usage

+ * + *
{@code
+ * TDigest digest = new TDigest(100);
+ * for (double latency : latencies) {
+ *     digest.add(latency);
+ * }
+ * digest.quantile(0.5);   // median
+ * digest.quantile(0.999); // deep tail, the case t-digest is built for
+ * digest.cdf(250.0);      // share of samples below 250
+ *
+ * // Sketches computed on different shards combine the way partial sums do.
+ * shardA.merge(shardB);
+ * }
+ * + *

Query methods fold the pending insertion buffer in before answering, so they mutate internal + * state; they are not safe to call concurrently. This class is not thread-safe. + * + * @see P2QuantileEstimator for a constant-memory estimator of one fixed quantile + * @see T. Dunning, O. Ertl, Computing extremely accurate quantiles using t-digests + */ +public final class TDigest { + + /** Below roughly this value the scale function stops leaving room for a useful number of centroids. */ + private static final double MIN_COMPRESSION = 10.0; + + private static final double TWO_PI = 2.0 * Math.PI; + + /** Buffered points per centroid slot; larger buffers mean fewer, bigger merge passes. */ + private static final int BUFFER_FACTOR = 5; + + /** + * How many centroid slots to reserve per unit of compression. Repeated merges make centroids + * atomic, so they pack less tightly than the scale function alone would suggest: in practice the + * sketch settles around {@code 0.6 * compression} centroids rather than the ideal + * {@code compression / 2}. Twice the compression leaves ample headroom. + */ + private static final int CENTROID_SLOTS_PER_UNIT = 2; + + /** Below this length the parallel sort switches to insertion sort. */ + private static final int INSERTION_SORT_THRESHOLD = 16; + + private final double compression; + + private final double[] centroidMeans; + private final double[] centroidWeights; + private int centroidCount; + + private final double[] bufferMeans; + private final double[] bufferWeights; + private int bufferCount; + + private final double[] scratchMeans; + private final double[] scratchWeights; + + private double totalWeight; + private double min = Double.POSITIVE_INFINITY; + private double max = Double.NEGATIVE_INFINITY; + + /** + * Creates an empty digest with a compression of 100, a good default for most streams. + */ + public TDigest() { + this(100.0); + } + + /** + * Creates an empty digest. + * + * @param compression the size/accuracy trade-off; around {@code 0.6 * compression} centroids end + * up being kept, so larger values cost more memory and give smaller quantile errors + * @throws IllegalArgumentException if {@code compression} is smaller than 10 or not finite + */ + public TDigest(double compression) { + if (!(compression >= MIN_COMPRESSION) || !Double.isFinite(compression)) { + throw new IllegalArgumentException("The compression must be finite and at least " + MIN_COMPRESSION + ", but was " + compression); + } + this.compression = compression; + + int scale = (int) Math.ceil(compression) + 2; + int centroidCapacity = CENTROID_SLOTS_PER_UNIT * scale; + this.centroidMeans = new double[centroidCapacity]; + this.centroidWeights = new double[centroidCapacity]; + + int bufferCapacity = BUFFER_FACTOR * scale; + this.bufferMeans = new double[bufferCapacity]; + this.bufferWeights = new double[bufferCapacity]; + + this.scratchMeans = new double[centroidCapacity + bufferCapacity]; + this.scratchWeights = new double[centroidCapacity + bufferCapacity]; + } + + /** + * Adds one sample of unit weight. + * + * @param value the sample to add + * @throws IllegalArgumentException if {@code value} is NaN or infinite + */ + public void add(double value) { + add(value, 1.0); + } + + /** + * Adds a sample that stands for several observations of the same value. + * + * @param value the sample to add + * @param weight how many observations the sample represents, strictly positive + * @throws IllegalArgumentException if {@code value} is not finite or {@code weight} is not strictly positive + */ + public void add(double value, double weight) { + if (!Double.isFinite(value)) { + throw new IllegalArgumentException("Samples must be finite, but was " + value); + } + if (!(weight > 0.0) || !Double.isFinite(weight)) { + throw new IllegalArgumentException("The weight must be finite and positive, but was " + weight); + } + if (bufferCount == bufferMeans.length) { + flushBuffer(); + } + bufferMeans[bufferCount] = value; + bufferWeights[bufferCount] = weight; + bufferCount++; + min = Math.min(min, value); + max = Math.max(max, value); + } + + /** + * Adds every given sample with unit weight. + * + * @param values the samples to add + * @throws IllegalArgumentException if any value is NaN or infinite + * @throws NullPointerException if {@code values} is {@code null} + */ + public void addAll(double... values) { + for (double value : values) { + add(value); + } + } + + /** + * Folds another digest into this one. The result approximates the union of the two streams, which + * is what makes t-digests usable as a map-reduce style aggregate. + * + * @param other the digest to absorb; it is left unchanged apart from its pending buffer being folded in + * @throws NullPointerException if {@code other} is {@code null} + */ + public void merge(TDigest other) { + other.flushBuffer(); + for (int i = 0; i < other.centroidCount; i++) { + add(other.centroidMeans[i], other.centroidWeights[i]); + } + if (!other.isEmpty()) { + min = Math.min(min, other.min); + max = Math.max(max, other.max); + } + } + + /** + * Estimates the value below which the given fraction of the stream lies. + * + * @param q the requested quantile, between 0 and 1 inclusive + * @return the estimated quantile; exactly {@link #min()} for {@code q == 0} and {@link #max()} for {@code q == 1} + * @throws IllegalArgumentException if {@code q} is outside {@code [0, 1]} or is NaN + * @throws IllegalStateException if no sample has been added yet + */ + public double quantile(double q) { + if (!(q >= 0.0) || !(q <= 1.0)) { + throw new IllegalArgumentException("The quantile probability must lie in [0, 1], but was " + q); + } + flushBuffer(); + requireNonEmpty(); + if (centroidCount == 1) { + return centroidMeans[0]; + } + + double index = q * totalWeight; + if (index <= 0.0) { + return min; + } + if (index >= totalWeight) { + return max; + } + + // The centroids are treated as knots of a piecewise linear quantile function, each sitting at + // the centre of the weight it carries, with min and max closing the two ends. + double previousValue = min; + double previousIndex = 0.0; + double currentIndex = 0.0; + for (int i = 0; i < centroidCount; i++) { + currentIndex += i == 0 ? centroidWeights[0] / 2.0 : (centroidWeights[i - 1] + centroidWeights[i]) / 2.0; + if (index < currentIndex) { + return interpolate(previousIndex, previousValue, currentIndex, centroidMeans[i], index); + } + previousValue = centroidMeans[i]; + previousIndex = currentIndex; + } + return interpolate(previousIndex, previousValue, totalWeight, max, index); + } + + /** + * Estimates the fraction of the stream that is smaller than the given value, i.e. the empirical + * cumulative distribution function. + * + * @param value the value to look up + * @return a number in {@code [0, 1]} + * @throws IllegalArgumentException if {@code value} is NaN + * @throws IllegalStateException if no sample has been added yet + */ + public double cdf(double value) { + if (Double.isNaN(value)) { + throw new IllegalArgumentException("The value must not be NaN"); + } + flushBuffer(); + requireNonEmpty(); + if (value < min) { + return 0.0; + } + if (value > max) { + return 1.0; + } + if (max <= min) { + return 0.5; + } + + double previousValue = min; + double previousIndex = 0.0; + double currentIndex = 0.0; + for (int i = 0; i < centroidCount; i++) { + currentIndex += i == 0 ? centroidWeights[0] / 2.0 : (centroidWeights[i - 1] + centroidWeights[i]) / 2.0; + if (value < centroidMeans[i]) { + return interpolate(previousValue, previousIndex, centroidMeans[i], currentIndex, value) / totalWeight; + } + previousValue = centroidMeans[i]; + previousIndex = currentIndex; + } + return interpolate(previousValue, previousIndex, max, totalWeight, value) / totalWeight; + } + + /** + * Returns the smallest sample ever added, tracked exactly. + * + * @return the minimum + * @throws IllegalStateException if no sample has been added yet + */ + public double min() { + requireAnySample(); + return min; + } + + /** + * Returns the largest sample ever added, tracked exactly. + * + * @return the maximum + * @throws IllegalStateException if no sample has been added yet + */ + public double max() { + requireAnySample(); + return max; + } + + /** + * Returns the total weight of everything added, which for unweighted input is the number of + * samples. + * + * @return the accumulated weight + */ + public double totalWeight() { + double pending = 0.0; + for (int i = 0; i < bufferCount; i++) { + pending += bufferWeights[i]; + } + return totalWeight + pending; + } + + /** + * Returns how many centroids the sketch currently holds, after folding in pending insertions. + * + * @return the number of centroids, bounded by roughly {@code compression / 2} + */ + public int centroidCount() { + flushBuffer(); + return centroidCount; + } + + /** + * Returns the compression parameter. + * + * @return the value given at construction time + */ + public double compression() { + return compression; + } + + /** + * Tells whether the digest holds no samples. + * + * @return {@code true} if nothing has been added + */ + public boolean isEmpty() { + return centroidCount == 0 && bufferCount == 0; + } + + /** + * Forgets every sample. + */ + public void reset() { + centroidCount = 0; + bufferCount = 0; + totalWeight = 0.0; + min = Double.POSITIVE_INFINITY; + max = Double.NEGATIVE_INFINITY; + } + + @Override + public String toString() { + return "TDigest{compression=" + compression + ", weight=" + totalWeight() + ", centroids=" + (isEmpty() ? 0 : centroidCount()) + '}'; + } + + /** + * Folds every buffered point into the centroid list. + * + *

Buffer and centroids are concatenated, sorted by mean and then swept once from the smallest + * mean upwards. The sweep keeps filling the current output centroid while doing so would not push + * it past the weight limit given by the scale function at the quantile the centroid starts at; + * otherwise the centroid is closed and a new one is opened. + */ + private void flushBuffer() { + if (bufferCount == 0) { + return; + } + + int size = centroidCount + bufferCount; + System.arraycopy(centroidMeans, 0, scratchMeans, 0, centroidCount); + System.arraycopy(centroidWeights, 0, scratchWeights, 0, centroidCount); + System.arraycopy(bufferMeans, 0, scratchMeans, centroidCount, bufferCount); + System.arraycopy(bufferWeights, 0, scratchWeights, centroidCount, bufferCount); + bufferCount = 0; + sortByMean(scratchMeans, scratchWeights, 0, size - 1); + + double weight = 0.0; + for (int i = 0; i < size; i++) { + weight += scratchWeights[i]; + } + totalWeight = weight; + + int last = 0; + centroidMeans[0] = scratchMeans[0]; + centroidWeights[0] = scratchWeights[0]; + double weightOfClosedCentroids = 0.0; + double weightLimit = totalWeight * quantileLimit(0.0); + + for (int i = 1; i < size; i++) { + double projected = centroidWeights[last] + scratchWeights[i]; + boolean roomLeft = weightOfClosedCentroids + projected <= weightLimit; + if (roomLeft || last == centroidMeans.length - 1) { + centroidWeights[last] = projected; + centroidMeans[last] += (scratchMeans[i] - centroidMeans[last]) * scratchWeights[i] / projected; + } else { + weightOfClosedCentroids += centroidWeights[last]; + weightLimit = totalWeight * quantileLimit(weightOfClosedCentroids / totalWeight); + last++; + centroidMeans[last] = scratchMeans[i]; + centroidWeights[last] = scratchWeights[i]; + } + } + centroidCount = last + 1; + } + + /** + * Returns the quantile at which the centroid starting at quantile {@code q} must be closed, that + * is {@code kInverse(k(q) + 1)} for the scale function {@code k}. + */ + private double quantileLimit(double q) { + // Rounding in the running weight sum could push the ratio a hair outside [0, 1], which would + // turn asin into NaN and silently disable the size limit. + double bounded = Math.min(1.0, Math.max(0.0, q)); + double k = compression / TWO_PI * Math.asin(2.0 * bounded - 1.0) + 1.0; + double angle = k * TWO_PI / compression; + if (angle >= Math.PI / 2.0) { + return 1.0; + } + if (angle <= -Math.PI / 2.0) { + return 0.0; + } + return (Math.sin(angle) + 1.0) / 2.0; + } + + private void requireNonEmpty() { + if (centroidCount == 0) { + throw new IllegalStateException("The digest has not seen any sample yet"); + } + } + + private void requireAnySample() { + if (isEmpty()) { + throw new IllegalStateException("The digest has not seen any sample yet"); + } + } + + /** + * Linear interpolation between two knots, degenerating to the right knot when they coincide. + */ + private static double interpolate(double x0, double y0, double x1, double y1, double x) { + if (x1 <= x0) { + return y1; + } + return y0 + (x - x0) / (x1 - x0) * (y1 - y0); + } + + /** + * Sorts two parallel arrays by the values of the first one, using quicksort with a + * median-of-three pivot and an insertion sort for short ranges. + */ + private static void sortByMean(double[] means, double[] weights, int from, int to) { + int low = from; + int high = to; + while (low < high) { + if (high - low < INSERTION_SORT_THRESHOLD) { + insertionSort(means, weights, low, high); + return; + } + int pivotIndex = partition(means, weights, low, high); + // Recurse into the smaller half and loop on the larger one to keep the stack shallow. + if (pivotIndex - low < high - pivotIndex) { + sortByMean(means, weights, low, pivotIndex - 1); + low = pivotIndex + 1; + } else { + sortByMean(means, weights, pivotIndex + 1, high); + high = pivotIndex - 1; + } + } + } + + private static int partition(double[] means, double[] weights, int low, int high) { + int middle = low + (high - low) / 2; + if (means[middle] < means[low]) { + swap(means, weights, low, middle); + } + if (means[high] < means[low]) { + swap(means, weights, low, high); + } + if (means[high] < means[middle]) { + swap(means, weights, middle, high); + } + swap(means, weights, middle, high - 1); + double pivot = means[high - 1]; + + int store = low; + for (int i = low; i < high - 1; i++) { + if (means[i] < pivot) { + swap(means, weights, store, i); + store++; + } + } + swap(means, weights, store, high - 1); + return store; + } + + private static void insertionSort(double[] means, double[] weights, int low, int high) { + for (int i = low + 1; i <= high; i++) { + double mean = means[i]; + double weight = weights[i]; + int j = i - 1; + while (j >= low && means[j] > mean) { + means[j + 1] = means[j]; + weights[j + 1] = weights[j]; + j--; + } + means[j + 1] = mean; + weights[j + 1] = weight; + } + } + + private static void swap(double[] means, double[] weights, int i, int j) { + double mean = means[i]; + means[i] = means[j]; + means[j] = mean; + double weight = weights[i]; + weights[i] = weights[j]; + weights[j] = weight; + } + + /** + * Returns the centroid means, smallest first. Exposed for tests and for inspecting the shape of + * the sketch; the returned array is a copy. + * + * @return a copy of the centroid means + */ + double[] centroidMeansSnapshot() { + flushBuffer(); + return Arrays.copyOf(centroidMeans, centroidCount); + } + + /** + * Returns the centroid weights, aligned with {@link #centroidMeansSnapshot()}. + * + * @return a copy of the centroid weights + */ + double[] centroidWeightsSnapshot() { + flushBuffer(); + return Arrays.copyOf(centroidWeights, centroidCount); + } +} diff --git a/src/test/java/com/thealgorithms/streaming/TDigestTest.java b/src/test/java/com/thealgorithms/streaming/TDigestTest.java new file mode 100644 index 000000000000..6968513824c9 --- /dev/null +++ b/src/test/java/com/thealgorithms/streaming/TDigestTest.java @@ -0,0 +1,391 @@ +package com.thealgorithms.streaming; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import java.util.Arrays; +import java.util.Random; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +class TDigestTest { + + /** + * Fraction of the sample that is strictly smaller than the given value, i.e. the rank the digest + * actually hit. Comparing ranks rather than values is the meaningful way to score a quantile + * sketch: it is insensitive to how steep the distribution happens to be. + */ + private static double trueRank(double[] sortedValues, double value) { + int index = Arrays.binarySearch(sortedValues, value); + if (index < 0) { + index = -(index + 1); + } + return (double) index / sortedValues.length; + } + + private static double[] gaussianSample(int count, long seed) { + Random random = new Random(seed); + double[] values = new double[count]; + for (int i = 0; i < count; i++) { + values[i] = random.nextGaussian(); + } + return values; + } + + private static double[] uniformSample(int count, long seed) { + Random random = new Random(seed); + double[] values = new double[count]; + for (int i = 0; i < count; i++) { + values[i] = random.nextDouble(); + } + return values; + } + + @ParameterizedTest + @ValueSource(doubles = {9.0, 0.0, -5.0, Double.NaN, Double.POSITIVE_INFINITY}) + void rejectsInvalidCompression(double compression) { + assertThrows(IllegalArgumentException.class, () -> new TDigest(compression)); + } + + @Test + void queriesBeforeTheFirstSampleFail() { + TDigest digest = new TDigest(); + assertTrue(digest.isEmpty()); + assertEquals(0.0, digest.totalWeight()); + assertEquals(100.0, digest.compression()); + assertThrows(IllegalStateException.class, () -> digest.quantile(0.5)); + assertThrows(IllegalStateException.class, () -> digest.cdf(0.5)); + assertThrows(IllegalStateException.class, digest::min); + assertThrows(IllegalStateException.class, digest::max); + } + + @ParameterizedTest + @ValueSource(doubles = {Double.NaN, Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY}) + void rejectsNonFiniteSamples(double value) { + TDigest digest = new TDigest(); + assertThrows(IllegalArgumentException.class, () -> digest.add(value)); + } + + @ParameterizedTest + @ValueSource(doubles = {0.0, -1.0, Double.NaN, Double.POSITIVE_INFINITY}) + void rejectsInvalidWeights(double weight) { + TDigest digest = new TDigest(); + assertThrows(IllegalArgumentException.class, () -> digest.add(1.0, weight)); + } + + @ParameterizedTest + @ValueSource(doubles = {-0.1, 1.1, Double.NaN}) + void rejectsInvalidQuantiles(double q) { + TDigest digest = new TDigest(); + digest.add(1.0); + assertThrows(IllegalArgumentException.class, () -> digest.quantile(q)); + } + + @Test + void rejectsNaNInCdf() { + TDigest digest = new TDigest(); + digest.add(1.0); + assertThrows(IllegalArgumentException.class, () -> digest.cdf(Double.NaN)); + } + + @Test + void aSingleSampleAnswersEveryQuantile() { + TDigest digest = new TDigest(); + digest.add(4.0); + assertEquals(4.0, digest.quantile(0.0)); + assertEquals(4.0, digest.quantile(0.5)); + assertEquals(4.0, digest.quantile(1.0)); + assertEquals(4.0, digest.min()); + assertEquals(4.0, digest.max()); + assertEquals(1.0, digest.totalWeight()); + assertEquals(1, digest.centroidCount()); + } + + @Test + void aConstantStreamCollapsesIntoOneValue() { + TDigest digest = new TDigest(); + for (int i = 0; i < 10_000; i++) { + digest.add(3.5); + } + assertEquals(3.5, digest.quantile(0.1), 1e-12); + assertEquals(3.5, digest.quantile(0.9), 1e-12); + assertEquals(0.5, digest.cdf(3.5), 1e-12); + } + + @Test + void extremesAreExact() { + double[] values = gaussianSample(20_000, 11L); + TDigest digest = new TDigest(); + digest.addAll(values); + + double[] sorted = values.clone(); + Arrays.sort(sorted); + assertEquals(sorted[0], digest.min(), 0.0); + assertEquals(sorted[sorted.length - 1], digest.max(), 0.0); + assertEquals(sorted[0], digest.quantile(0.0), 0.0); + assertEquals(sorted[sorted.length - 1], digest.quantile(1.0), 0.0); + assertEquals(0.0, digest.cdf(sorted[0] - 1.0)); + assertEquals(1.0, digest.cdf(sorted[sorted.length - 1] + 1.0)); + } + + @ParameterizedTest + @ValueSource(doubles = {0.001, 0.01, 0.1, 0.25, 0.5, 0.75, 0.9, 0.99, 0.999}) + @DisplayName("hits the requested rank of a uniform stream") + void hitsTheRequestedRankOnUniformData(double q) { + double[] values = uniformSample(100_000, 20240517L); + TDigest digest = new TDigest(100.0); + digest.addAll(values); + + double[] sorted = values.clone(); + Arrays.sort(sorted); + assertEquals(q, trueRank(sorted, digest.quantile(q)), 0.01, "requested q=" + q); + } + + @ParameterizedTest + @ValueSource(doubles = {0.001, 0.01, 0.1, 0.5, 0.9, 0.99, 0.999}) + @DisplayName("is far more accurate in the tails than in the middle, by design") + void isMostAccurateInTheTails(double q) { + double[] values = gaussianSample(200_000, 4242L); + TDigest digest = new TDigest(200.0); + digest.addAll(values); + + double[] sorted = values.clone(); + Arrays.sort(sorted); + double rankError = Math.abs(trueRank(sorted, digest.quantile(q)) - q); + + // The tolerance follows the shape of the scale function: it shrinks as q approaches 0 or 1. + double allowedRankError = 0.01 * Math.max(0.05, 4.0 * q * (1.0 - q)); + assertTrue(rankError <= allowedRankError, "q=" + q + " rank error " + rankError + " exceeded " + allowedRankError); + } + + @Test + void quantilesAreMonotonic() { + TDigest digest = new TDigest(); + digest.addAll(gaussianSample(50_000, 777L)); + + double previous = digest.quantile(0.0); + for (int i = 1; i <= 1_000; i++) { + double current = digest.quantile(i / 1_000.0); + assertTrue(current >= previous, "quantile decreased at q=" + i / 1_000.0); + previous = current; + } + } + + @Test + @DisplayName("the cdf inverts the quantile function") + void cdfAgreesWithQuantile() { + TDigest digest = new TDigest(200.0); + digest.addAll(uniformSample(100_000, 314159L)); + + for (int step = 1; step <= 19; step++) { + double q = step * 0.05; + assertEquals(q, digest.cdf(digest.quantile(q)), 0.02, "at q=" + q); + } + } + + @Test + void cdfMatchesTheEmpiricalDistribution() { + double[] values = uniformSample(50_000, 2718L); + TDigest digest = new TDigest(); + digest.addAll(values); + + double[] sorted = values.clone(); + Arrays.sort(sorted); + for (int step = 1; step <= 19; step++) { + double x = step * 0.05; + assertEquals(trueRank(sorted, x), digest.cdf(x), 0.02, "at x=" + x); + } + } + + @Test + @DisplayName("a weighted sample stands for that many observations") + void supportsWeightedSamples() { + TDigest weighted = new TDigest(); + TDigest repeated = new TDigest(); + for (int i = 0; i < 100; i++) { + weighted.add(i, 10.0); + for (int repeat = 0; repeat < 10; repeat++) { + repeated.add(i); + } + } + + assertEquals(1_000.0, weighted.totalWeight(), 1e-9); + assertEquals(repeated.totalWeight(), weighted.totalWeight(), 1e-9); + assertEquals(repeated.quantile(0.5), weighted.quantile(0.5), 2.0); + } + + @Test + @DisplayName("merging shard digests approximates a digest of the whole stream") + void mergesLikeAPartialAggregate() { + double[] values = gaussianSample(120_000, 5150L); + TDigest whole = new TDigest(200.0); + TDigest shardA = new TDigest(200.0); + TDigest shardB = new TDigest(200.0); + TDigest shardC = new TDigest(200.0); + for (int i = 0; i < values.length; i++) { + whole.add(values[i]); + if (i % 3 == 0) { + shardA.add(values[i]); + } else if (i % 3 == 1) { + shardB.add(values[i]); + } else { + shardC.add(values[i]); + } + } + + shardA.merge(shardB); + shardA.merge(shardC); + + assertEquals(whole.totalWeight(), shardA.totalWeight(), 1e-9); + assertEquals(whole.min(), shardA.min(), 0.0); + assertEquals(whole.max(), shardA.max(), 0.0); + + double[] sorted = values.clone(); + Arrays.sort(sorted); + for (double q : new double[] {0.01, 0.1, 0.5, 0.9, 0.99}) { + assertEquals(q, trueRank(sorted, shardA.quantile(q)), 0.01, "merged digest at q=" + q); + } + } + + @Test + void mergingAnEmptyDigestChangesNothing() { + TDigest digest = new TDigest(); + digest.addAll(1.0, 2.0, 3.0, 4.0, 5.0); + double median = digest.quantile(0.5); + + digest.merge(new TDigest()); + assertEquals(median, digest.quantile(0.5), 0.0); + assertEquals(5.0, digest.totalWeight()); + } + + @ParameterizedTest + @ValueSource(doubles = {20.0, 100.0, 500.0}) + @DisplayName("the sketch stays small no matter how long the stream is") + void keepsTheCentroidCountBounded(double compression) { + TDigest digest = new TDigest(compression); + digest.addAll(gaussianSample(200_000, 8L)); + + assertTrue(digest.centroidCount() <= compression, "kept " + digest.centroidCount() + " centroids for compression " + compression); + assertEquals(digest.centroidCount(), digest.centroidMeansSnapshot().length); + assertEquals(digest.centroidCount(), digest.centroidWeightsSnapshot().length); + + double[] means = digest.centroidMeansSnapshot(); + for (int i = 1; i < means.length; i++) { + assertTrue(means[i - 1] <= means[i], "centroids are not sorted at index " + i); + } + assertEquals(digest.totalWeight(), Arrays.stream(digest.centroidWeightsSnapshot()).sum(), 1e-6); + } + + @Test + @DisplayName("a higher compression buys accuracy") + void higherCompressionIsMoreAccurate() { + double[] values = gaussianSample(200_000, 6060L); + double[] sorted = values.clone(); + Arrays.sort(sorted); + + TDigest coarse = new TDigest(20.0); + TDigest fine = new TDigest(500.0); + coarse.addAll(values); + fine.addAll(values); + + double coarseError = Math.abs(trueRank(sorted, coarse.quantile(0.5)) - 0.5); + double fineError = Math.abs(trueRank(sorted, fine.quantile(0.5)) - 0.5); + assertTrue(fineError <= coarseError, "coarse=" + coarseError + " fine=" + fineError); + } + + @Test + void handlesSortedInput() { + TDigest digest = new TDigest(); + for (int i = 1; i <= 100_000; i++) { + digest.add(i); + } + assertEquals(50_000.0, digest.quantile(0.5), 1_000.0); + assertEquals(1.0, digest.min()); + assertEquals(100_000.0, digest.max()); + } + + @Test + void resetForgetsEverything() { + TDigest digest = new TDigest(); + digest.addAll(gaussianSample(1_000, 3L)); + digest.reset(); + + assertTrue(digest.isEmpty()); + assertEquals(0.0, digest.totalWeight()); + assertThrows(IllegalStateException.class, () -> digest.quantile(0.5)); + + digest.addAll(1.0, 2.0, 3.0); + assertEquals(3.0, digest.totalWeight()); + assertEquals(2.0, digest.quantile(0.5), 0.5); + } + + @Test + void toStringMentionsTheState() { + TDigest digest = new TDigest(); + assertTrue(digest.toString().contains("centroids=0"), digest.toString()); + digest.addAll(1.0, 2.0, 3.0); + assertFalse(digest.isEmpty()); + assertTrue(digest.toString().contains("weight=3.0"), digest.toString()); + } + + @Test + @DisplayName("the very edges of the quantile function interpolate towards the tracked extremes") + void interpolatesTowardsTheExtremes() { + double[] values = uniformSample(100_000, 161803L); + TDigest digest = new TDigest(); + digest.addAll(values); + + double[] sorted = values.clone(); + Arrays.sort(sorted); + double deepTail = digest.quantile(0.999999); + assertTrue(deepTail <= digest.max(), "the estimate must not exceed the maximum"); + assertTrue(deepTail >= sorted[sorted.length - 10], "the deep tail should sit among the largest samples"); + + assertEquals(1.0, digest.cdf(digest.max()), 1e-9); + assertEquals(0.0, digest.cdf(digest.min()), 0.01); + } + + @Test + @DisplayName("a stream made of two repeated values keeps its quantiles sane") + void handlesHeavilyDuplicatedValues() { + TDigest digest = new TDigest(); + for (int i = 0; i < 20_000; i++) { + digest.add(i % 2 == 0 ? 1.0 : 2.0); + } + + assertEquals(1.0, digest.min()); + assertEquals(2.0, digest.max()); + assertTrue(digest.quantile(0.25) <= 1.5, "the lower quarter is made of ones"); + assertTrue(digest.quantile(0.75) >= 1.5, "the upper quarter is made of twos"); + assertTrue(digest.cdf(1.5) >= 0.0 && digest.cdf(1.5) <= 1.0); + } + + @Test + @DisplayName("weights spanning eighteen orders of magnitude still give sane, monotone quantiles") + void survivesWildlyDisparateWeights() { + TDigest digest = new TDigest(50.0); + digest.add(0.0, 1e12); + for (int i = 1; i <= 10_000; i++) { + digest.add(i, 1e-6); + } + + // A point mass this dominant is the regime where the packing rule degenerates into one centroid + // per sample, so it is also the regime that decides whether the centroid array is large enough. + assertEquals(1e12 + 10_000 * 1e-6, digest.totalWeight(), 1.0); + assertEquals(0.0, digest.min()); + assertEquals(10_000.0, digest.max()); + assertEquals(0.0, digest.quantile(0.5), 1e-6, "essentially all the weight sits at zero"); + assertTrue(digest.quantile(0.999999) > 0.0, "the tail must not collapse onto the bulk"); + + double previous = digest.quantile(0.0); + for (int i = 1; i <= 1_000; i++) { + double current = digest.quantile(i / 1_000.0); + assertTrue(current >= previous, "quantiles stopped being monotonic at q=" + i / 1_000.0); + previous = current; + } + } +} From e43ec3897e48f23843972d02cd05a5bb1b6864a2 Mon Sep 17 00:00:00 2001 From: Vedant Hemraj Kapgate Date: Sun, 11 Oct 2026 01:46:44 +0530 Subject: [PATCH 45/92] Add Duval's Lyndon factorization algorithm (#7639) * Add Duval Lyndon factorization * Test Lyndon factorization * Handle null input explicitly in Lyndon factorization * Align null-input test with explicit validation --- .../strings/LyndonFactorization.java | 61 +++++++++++++++++++ .../strings/LyndonFactorizationTest.java | 35 +++++++++++ 2 files changed, 96 insertions(+) create mode 100644 src/main/java/com/thealgorithms/strings/LyndonFactorization.java create mode 100644 src/test/java/com/thealgorithms/strings/LyndonFactorizationTest.java diff --git a/src/main/java/com/thealgorithms/strings/LyndonFactorization.java b/src/main/java/com/thealgorithms/strings/LyndonFactorization.java new file mode 100644 index 000000000000..3eb13b00d0fb --- /dev/null +++ b/src/main/java/com/thealgorithms/strings/LyndonFactorization.java @@ -0,0 +1,61 @@ +package com.thealgorithms.strings; + +import java.util.ArrayList; +import java.util.List; + +/** + * Factorizes a string into its Lyndon words using Duval's algorithm. + * + *

Duval's algorithm runs in O(n) time and uses O(1) auxiliary working + * space, excluding the returned list and its strings. + * + *

Reference: + * https://cp-algorithms.com/string/lyndon_factorization.html + */ +public final class LyndonFactorization { + private LyndonFactorization() { + } + + /** + * Returns the standard Lyndon factorization of {@code text}. + * + *

The returned factors are in non-increasing lexicographic order + * according to Java's UTF-16 code-unit ordering. + * + * @param text input string to factorize + * @return Lyndon factors in non-increasing lexicographic order + * @throws IllegalArgumentException if {@code text} is null + */ + public static List factorize(String text) { + if (text == null) { + throw new IllegalArgumentException("text must not be null"); + } + + List factors = new ArrayList<>(); + int n = text.length(); + int start = 0; + + while (start < n) { + int candidate = start + 1; + int match = start; + + while (candidate < n && text.charAt(match) <= text.charAt(candidate)) { + if (text.charAt(match) < text.charAt(candidate)) { + match = start; + } else { + match++; + } + candidate++; + } + + int length = candidate - match; + + while (start <= match) { + factors.add(text.substring(start, start + length)); + start += length; + } + } + + return factors; + } +} diff --git a/src/test/java/com/thealgorithms/strings/LyndonFactorizationTest.java b/src/test/java/com/thealgorithms/strings/LyndonFactorizationTest.java new file mode 100644 index 000000000000..4ecb86e2a99c --- /dev/null +++ b/src/test/java/com/thealgorithms/strings/LyndonFactorizationTest.java @@ -0,0 +1,35 @@ +package com.thealgorithms.strings; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; + +import java.util.List; +import org.junit.jupiter.api.Test; + +class LyndonFactorizationTest { + + @Test + void factorizesBanana() { + assertEquals(List.of("b", "an", "an", "a"), LyndonFactorization.factorize("banana")); + } + + @Test + void factorizesRepeatedPattern() { + assertEquals(List.of("ab", "ab", "ab"), LyndonFactorization.factorize("ababab")); + } + + @Test + void factorizesSingleCharacter() { + assertEquals(List.of("a"), LyndonFactorization.factorize("a")); + } + + @Test + void factorizesEmptyString() { + assertEquals(List.of(), LyndonFactorization.factorize("")); + } + + @Test + void rejectsNullInput() { + assertThrows(IllegalArgumentException.class, () -> LyndonFactorization.factorize(null)); + } +} From 8dbdc51edea193d103fe212c897f1a84ae479ce6 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 16 Oct 2026 09:24:58 +0300 Subject: [PATCH 46/92] chore(deps): bump github/codeql-action from 4.38.2 to 4.38.3 in /.github/workflows (#7645) chore(deps): bump github/codeql-action in /.github/workflows Bumps [github/codeql-action](https://github.com/github/codeql-action) from 4.38.2 to 4.38.3. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](https://github.com/github/codeql-action/compare/v4.38.2...v4.38.3) --- updated-dependencies: - dependency-name: github/codeql-action dependency-version: 4.38.3 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/codeql.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 82963c044afb..763cc4980982 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -30,7 +30,7 @@ jobs: distribution: 'temurin' - name: Initialize CodeQL - uses: github/codeql-action/init@v4.38.2 + uses: github/codeql-action/init@v4.38.3 with: languages: 'java-kotlin' @@ -38,7 +38,7 @@ jobs: run: mvn --batch-mode --update-snapshots verify - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4.38.2 + uses: github/codeql-action/analyze@v4.38.3 with: category: "/language:java-kotlin" @@ -55,12 +55,12 @@ jobs: uses: actions/checkout@v7 - name: Initialize CodeQL - uses: github/codeql-action/init@v4.38.2 + uses: github/codeql-action/init@v4.38.3 with: languages: 'actions' - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4.38.2 + uses: github/codeql-action/analyze@v4.38.3 with: category: "/language:actions" ... From 0ab112410e7f3bb57cca28987671f08503244771 Mon Sep 17 00:00:00 2001 From: Kaan Hascan <133219984+kaanhascan@users.noreply.github.com> Date: Mon, 19 Oct 2026 09:00:52 +0300 Subject: [PATCH 47/92] chore: remove accidental file breaking Windows checkout (#7646) --- "ts\"" | 179 --------------------------------------------------------- 1 file changed, 179 deletions(-) delete mode 100644 "ts\"" diff --git "a/ts\"" "b/ts\"" deleted file mode 100644 index daddada971db..000000000000 --- "a/ts\"" +++ /dev/null @@ -1,179 +0,0 @@ -diff --git a/src/main/java/com/thealgorithms/datastructures/trees/FenwickTree.java b/src/main/java/com/thealgorithms/datastructures/trees/FenwickTree.java -index 5378a01..be8a92e 100644 ---- a/src/main/java/com/thealgorithms/datastructures/trees/FenwickTree.java -+++ b/src/main/java/com/thealgorithms/datastructures/trees/FenwickTree.java -@@ -1,29 +1,33 @@ - package com.thealgorithms.datastructures.trees; -  -+/** Fenwick Tree for point updates and prefix-sum queries in O(log n). */ - public class FenwickTree { -  -- private int n; -- private int[] fenTree; -+ private final int n; -+ private final int[] fenTree; -  -- /* Constructor which takes the size of the array as a parameter */ -+ /** Creates a Fenwick tree with n elements, all initialized to zero. */ - public FenwickTree(int n) { -+ if (n < 0) { -+ throw new IllegalArgumentException("Size must be non-negative"); -+ } - this.n = n; - this.fenTree = new int[n + 1]; - } -  -- /* A function which will add the element val at index i*/ -+ /** Adds val to the element at index i. */ - public void update(int i, int val) { -- // As index starts from 0, increment the index by 1 -- i += 1; -+ checkIndex(i); -+ i += 1; // Convert to the internal 1-based index - while (i <= n) { - fenTree[i] += val; - i += i & (-i); - } - } -  -- /* A function which will return the cumulative sum from index 1 to index i*/ -+ /** Returns the sum of elements from index 0 to i. */ - public int query(int i) { -- // As index starts from 0, increment the index by 1 -+ checkIndex(i); - i += 1; - int cumSum = 0; - while (i > 0) { -@@ -32,4 +36,11 @@ public class FenwickTree { - } - return cumSum; - } -+ -+ // Check that the index is within the valid range. -+ private void checkIndex(int i) { -+ if (i < 0 || i >= n) { -+ throw new IndexOutOfBoundsException("Index " + i + " out of bounds for size " + n); -+ } -+ } - } -diff --git a/src/test/java/com/thealgorithms/datastructures/trees/FenwickTree.java b/src/test/java/com/thealgorithms/datastructures/trees/FenwickTree.java -new file mode 100644 -index 0000000..47ef568 ---- /dev/null -+++ b/src/test/java/com/thealgorithms/datastructures/trees/FenwickTree.java -@@ -0,0 +1,115 @@ -+package com.thealgorithms.datastructures.trees; -+ -+import static org.junit.jupiter.api.Assertions.assertEquals; -+import static org.junit.jupiter.api.Assertions.assertThrows; -+ -+import java.util.Random; -+import org.junit.jupiter.api.Test; -+ -+class FenwickTreeTest { -+ -+ @Test -+ void queryOnFreshTreeReturnsZero() { -+ FenwickTree tree = new FenwickTree(5); -+ for (int i = 0; i < 5; i++) { -+ assertEquals(0, tree.query(i)); -+ } -+ } -+ -+ @Test -+ void singleElementTree() { -+ FenwickTree tree = new FenwickTree(1); -+ tree.update(0, 7); -+ assertEquals(7, tree.query(0)); -+ } -+ -+ @Test -+ void prefixSumsAfterUpdates() { -+ FenwickTree tree = new FenwickTree(5); -+ int[] values = {3, 2, -1, 6, 5}; -+ for (int i = 0; i < values.length; i++) { -+ tree.update(i, values[i]); -+ } -+ assertEquals(3, tree.query(0)); -+ assertEquals(5, tree.query(1)); -+ assertEquals(4, tree.query(2)); -+ assertEquals(10, tree.query(3)); -+ assertEquals(15, tree.query(4)); -+ } -+ -+ @Test -+ void repeatedUpdatesOnSameIndexAccumulate() { -+ FenwickTree tree = new FenwickTree(4); -+ tree.update(2, 5); -+ tree.update(2, 3); -+ tree.update(2, -2); -+ assertEquals(0, tree.query(1)); -+ assertEquals(6, tree.query(2)); -+ assertEquals(6, tree.query(3)); -+ } -+ -+ @Test -+ void negativeValues() { -+ FenwickTree tree = new FenwickTree(3); -+ tree.update(0, -4); -+ tree.update(1, -6); -+ tree.update(2, 10); -+ assertEquals(-4, tree.query(0)); -+ assertEquals(-10, tree.query(1)); -+ assertEquals(0, tree.query(2)); -+ } -+ -+ @Test -+ void nonPowerOfTwoSize() { -+ int size = 13; -+ FenwickTree tree = new FenwickTree(size); -+ for (int i = 0; i < size; i++) { -+ tree.update(i, 1); -+ } -+ for (int i = 0; i < size; i++) { -+ assertEquals(i + 1, tree.query(i)); -+ } -+ } -+ -+ @Test -+ void matchesNaivePrefixSumOnRandomData() { -+ Random random = new Random(42); -+ int size = 100; -+ FenwickTree tree = new FenwickTree(size); -+ int[] naive = new int[size]; -+ -+ for (int step = 0; step < 500; step++) { -+ int index = random.nextInt(size); -+ int delta = random.nextInt(21) - 10; -+ tree.update(index, delta); -+ naive[index] += delta; -+ } -+ -+ int running = 0; -+ for (int i = 0; i < size; i++) { -+ running += naive[i]; -+ assertEquals(running, tree.query(i), "Mismatch at index " + i); -+ } -+ } -+ -+ @Test -+ void zeroSizeTreeRejectsAnyIndex() { -+ FenwickTree tree = new FenwickTree(0); -+ assertThrows(IndexOutOfBoundsException.class, () -> tree.update(0, 1)); -+ assertThrows(IndexOutOfBoundsException.class, () -> tree.query(0)); -+ } -+ -+ @Test -+ void negativeSizeThrows() { -+ assertThrows(IllegalArgumentException.class, () -> new FenwickTree(-1)); -+ } -+ -+ @Test -+ void outOfBoundsIndicesThrow() { -+ FenwickTree tree = new FenwickTree(5); -+ assertThrows(IndexOutOfBoundsException.class, () -> tree.update(-1, 1)); -+ assertThrows(IndexOutOfBoundsException.class, () -> tree.update(5, 1)); -+ assertThrows(IndexOutOfBoundsException.class, () -> tree.query(-1)); -+ assertThrows(IndexOutOfBoundsException.class, () -> tree.query(5)); -+ } -+} From d9b86d1992b8bd4cadbd832822c792628117e69d Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 19 Oct 2026 21:06:17 +0000 Subject: [PATCH 48/92] chore(deps-dev): bump com.github.spotbugs:spotbugs-maven-plugin from 4.10.4.1 to 4.10.5.0 (#7647) chore(deps-dev): bump com.github.spotbugs:spotbugs-maven-plugin Bumps [com.github.spotbugs:spotbugs-maven-plugin](https://github.com/spotbugs/spotbugs-maven-plugin) from 4.10.4.1 to 4.10.5.0. - [Release notes](https://github.com/spotbugs/spotbugs-maven-plugin/releases) - [Commits](https://github.com/spotbugs/spotbugs-maven-plugin/compare/spotbugs-maven-plugin-4.10.4.1...spotbugs-maven-plugin-4.10.5.0) --- updated-dependencies: - dependency-name: com.github.spotbugs:spotbugs-maven-plugin dependency-version: 4.10.5.0 dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 5a166dbf4fe5..21dd79ad17b1 100644 --- a/pom.xml +++ b/pom.xml @@ -119,7 +119,7 @@ com.github.spotbugs spotbugs-maven-plugin - 4.10.4.1 + 4.10.5.0 spotbugs-exclude.xml true From f8207cc34ca0bd5694cce3120a9741ee50b2d2e8 Mon Sep 17 00:00:00 2001 From: Hardik K Date: Wed, 21 Oct 2026 21:11:35 +0530 Subject: [PATCH 49/92] fix(searches): support duplicates and null safety in LowerBound and UpperBound (#7648) * fix(searches): find first occurrence in LowerBound with duplicate values When multiple elements equal to key exist, LowerBound should return the index of the first such value per its specification. Continue searching the left partition when comp <= 0 instead of prematurely returning the median element. * fix(searches): add null and empty array safety to LowerBound and UpperBound Guard against NullPointerException and empty array bounds access in LowerBound and UpperBound find methods when array is null/empty or key is null. * test(searches): add unit tests for LowerBound duplicate values and null safety Verify LowerBound returns the first occurrence for duplicate elements, and handles empty arrays, null arrays, and null keys gracefully in LowerBound and UpperBound. * docs(searches): document null return behavior, update best-case complexity, and test UpperBound duplicates --- .../thealgorithms/searches/LowerBound.java | 13 ++++----- .../thealgorithms/searches/UpperBound.java | 7 +++-- .../searches/LowerBoundTest.java | 27 +++++++++++++++++++ .../searches/UpperBoundTest.java | 15 +++++++++++ 4 files changed, 54 insertions(+), 8 deletions(-) diff --git a/src/main/java/com/thealgorithms/searches/LowerBound.java b/src/main/java/com/thealgorithms/searches/LowerBound.java index 5a1401edd3c2..7325082c223b 100644 --- a/src/main/java/com/thealgorithms/searches/LowerBound.java +++ b/src/main/java/com/thealgorithms/searches/LowerBound.java @@ -13,7 +13,7 @@ * This is an extension of BinarySearch. * *

- * Worst-case performance O(log n) Best-case performance O(1) Average + * Worst-case performance O(log n) Best-case performance O(log n) Average * performance O(log n) Worst-case space complexity O(1) * * @author Pratik Padalia (https://github.com/15pratik) @@ -26,10 +26,13 @@ class LowerBound implements SearchAlgorithm { * @param array is an array where the LowerBound value is to be found * @param key is an element for which the LowerBound is to be found * @param is any comparable type - * @return index of the LowerBound element + * @return index of the first element not less than key, or 0 if array is null/empty or key is null */ @Override public > int find(T[] array, T key) { + if (array == null || array.length == 0 || key == null) { + return 0; + } return search(array, key, 0, array.length - 1); } @@ -51,10 +54,8 @@ private > int search(T[] array, T key, int left, int rig int median = (left + right) >>> 1; int comp = key.compareTo(array[median]); - if (comp == 0) { - return median; - } else if (comp < 0) { - // median position can be a possible solution + if (comp <= 0) { + // key is less than or equal to array[median], median position can be a possible solution return search(array, key, left, median); } else { // key we are looking is greater, so we must look on the right of median position diff --git a/src/main/java/com/thealgorithms/searches/UpperBound.java b/src/main/java/com/thealgorithms/searches/UpperBound.java index ec52c7a0ae5c..5344f22994b1 100644 --- a/src/main/java/com/thealgorithms/searches/UpperBound.java +++ b/src/main/java/com/thealgorithms/searches/UpperBound.java @@ -13,7 +13,7 @@ * This is an extension of BinarySearch. * *

- * Worst-case performance O(log n) Best-case performance O(1) Average + * Worst-case performance O(log n) Best-case performance O(log n) Average * performance O(log n) Worst-case space complexity O(1) * * @author Pratik Padalia (https://github.com/15pratik) @@ -26,10 +26,13 @@ class UpperBound implements SearchAlgorithm { * @param array is an array where the UpperBound value is to be found * @param key is an element for which the UpperBound is to be found * @param is any comparable type - * @return index of the UpperBound element + * @return index of the first element greater than key, last index if no such element exists, or 0 if array is null/empty or key is null */ @Override public > int find(T[] array, T key) { + if (array == null || array.length == 0 || key == null) { + return 0; + } return search(array, key, 0, array.length - 1); } diff --git a/src/test/java/com/thealgorithms/searches/LowerBoundTest.java b/src/test/java/com/thealgorithms/searches/LowerBoundTest.java index 30f4a5cb257c..058ea08cf614 100644 --- a/src/test/java/com/thealgorithms/searches/LowerBoundTest.java +++ b/src/test/java/com/thealgorithms/searches/LowerBoundTest.java @@ -56,4 +56,31 @@ void testLowerBoundNonExistentValue() { assertEquals(4, lowerBound.find(array, 7), "Lower bound for 7 should be at index 4"); assertEquals(0, lowerBound.find(array, 0), "Lower bound for 0 should be at index 0"); } + + /** + * Test finding the lower bound for an element with duplicate occurrences. + * Lower bound should point to the FIRST element not less than key. + */ + @Test + void testLowerBoundDuplicates() { + LowerBound lowerBound = new LowerBound(); + Integer[] arrayWithDuplicates = {1, 2, 2, 2, 3, 4, 5}; + + assertEquals(1, lowerBound.find(arrayWithDuplicates, 2), "Lower bound for 2 should be at index 1 (first occurrence)"); + + Integer[] allSame = {2, 2, 2, 2, 2}; + assertEquals(0, lowerBound.find(allSame, 2), "Lower bound for 2 in all-same array should be at index 0"); + } + + /** + * Test edge cases: empty array, null array, and null key. + */ + @Test + void testLowerBoundNullAndEmptyEdgeCases() { + LowerBound lowerBound = new LowerBound(); + Integer[] emptyArray = {}; + assertEquals(0, lowerBound.find(emptyArray, 5), "Lower bound for an empty array should be 0"); + assertEquals(0, lowerBound.find(null, 5), "Lower bound for a null array should be 0"); + assertEquals(0, lowerBound.find(new Integer[] {1, 2, 3}, null), "Lower bound for a null key should be 0"); + } } diff --git a/src/test/java/com/thealgorithms/searches/UpperBoundTest.java b/src/test/java/com/thealgorithms/searches/UpperBoundTest.java index dc0cbdd97e19..4f5eddbe924f 100644 --- a/src/test/java/com/thealgorithms/searches/UpperBoundTest.java +++ b/src/test/java/com/thealgorithms/searches/UpperBoundTest.java @@ -57,6 +57,15 @@ void testUpperBoundMultipleValues() { assertTrue(arrayWithDuplicates[index] > key, "Element at the upper bound index should be greater than the key."); } + @Test + void testUpperBoundDuplicates() { + Integer[] arrayWithDuplicates = {1, 2, 2, 2, 3}; + assertEquals(4, upperBound.find(arrayWithDuplicates, 2), "Upper bound for 2 in {1, 2, 2, 2, 3} should be at index 4"); + + Integer[] allSame = {2, 2, 2, 2, 2}; + assertEquals(4, upperBound.find(allSame, 2), "Upper bound for 2 in all-same array should be at last index 4"); + } + @Test void testUpperBoundLowerThanMin() { int key = 0; // Test with a key lower than the minimum element @@ -96,4 +105,10 @@ void testUpperBoundSingleElementArray() { index = upperBound.find(singleElementArray, 15); assertEquals(0, index, "Upper bound for 15 in a single element array should be 0."); } + + @Test + void testUpperBoundNullArrayAndKey() { + assertEquals(0, upperBound.find(null, 5), "Upper bound for a null array should be 0."); + assertEquals(0, upperBound.find(new Integer[] {1, 2, 3}, null), "Upper bound for a null key should be 0."); + } } From ff360047c5de460a20bd3dbd3715f211bb7a00f4 Mon Sep 17 00:00:00 2001 From: Hardik K Date: Wed, 21 Oct 2026 22:20:13 +0530 Subject: [PATCH 50/92] fix(searches): refine recursion bounds and add null safety to TernarySearch (#7649) --- .../thealgorithms/searches/TernarySearch.java | 56 ++++++++++------- .../searches/TernarySearchTest.java | 62 +++++++++++++++++++ 2 files changed, 96 insertions(+), 22 deletions(-) diff --git a/src/main/java/com/thealgorithms/searches/TernarySearch.java b/src/main/java/com/thealgorithms/searches/TernarySearch.java index 4d9f55ea9917..1071d172ef21 100644 --- a/src/main/java/com/thealgorithms/searches/TernarySearch.java +++ b/src/main/java/com/thealgorithms/searches/TernarySearch.java @@ -3,38 +3,44 @@ import com.thealgorithms.devutils.searches.SearchAlgorithm; /** - * A ternary search algorithm is a technique in computer science for finding the - * minimum or maximum of a unimodal function The algorithm determines either - * that the minimum or maximum cannot be in the first third of the domain or - * that it cannot be in the last third of the domain, then repeats on the - * remaining third. + * A ternary search algorithm is a divide-and-conquer algorithm that searches for + * a key in a sorted array by dividing the search domain into three parts. * *

- * Worst-case performance Θ(log3(N)) Best-case performance O(1) Average - * performance Θ(log3(N)) Worst-case space complexity O(1) + * Worst-case performance: Θ(log3(N))
+ * Best-case performance: O(1)
+ * Average performance: Θ(log3(N))
+ * Worst-case space complexity: O(log3(N)) * * @author Podshivalov Nikita (https://github.com/nikitap492) * @see SearchAlgorithm * @see IterativeBinarySearch */ -public class TernarySearch implements SearchAlgorithm { +public final class TernarySearch implements SearchAlgorithm { /** - * @param arr The **Sorted** array in which we will search the element. + * Searches for a value in a sorted array using ternary search. + * + * @param arr The sorted array in which we will search for the element. * @param value The value that we want to search for. - * @return The index of the element if found. Else returns -1. + * @return The index of the element if found. Returns -1 if the array is null or empty, if value is null, or if not found. */ @Override public > int find(T[] arr, T value) { + if (arr == null || arr.length == 0 || value == null) { + return -1; + } return ternarySearch(arr, value, 0, arr.length - 1); } /** - * @param arr The **Sorted** array in which we will search the element. + * Recursively searches for the specified key within the range [start, end]. + * + * @param arr The sorted array in which we will search the element. * @param key The value that we want to search for. - * @param start The starting index from which we will start Searching. - * @param end The ending index till which we will Search. - * @return Returns the index of the Element if found. Else returns -1. + * @param start The starting index from which we will start searching. + * @param end The ending index till which we will search. + * @return Returns the index of the element if found. Else returns -1. */ private > int ternarySearch(T[] arr, T key, int start, int end) { if (start > end) { @@ -45,16 +51,22 @@ private > int ternarySearch(T[] arr, T key, int start, i /* Second boundary: add 2/3 of length to start */ int mid2 = start + 2 * (end - start) / 3; - if (key.compareTo(arr[mid1]) == 0) { + int cmp1 = key.compareTo(arr[mid1]); + if (cmp1 == 0) { return mid1; - } else if (key.compareTo(arr[mid2]) == 0) { + } + + int cmp2 = key.compareTo(arr[mid2]); + if (cmp2 == 0) { return mid2; - } /* Search the first (1/3) rd part of the array.*/ else if (key.compareTo(arr[mid1]) < 0) { - return ternarySearch(arr, key, start, --mid1); - } /* Search 3rd (1/3)rd part of the array */ else if (key.compareTo(arr[mid2]) > 0) { - return ternarySearch(arr, key, ++mid2, end); - } /* Search middle (1/3)rd part of the array */ else { - return ternarySearch(arr, key, mid1, mid2); + } + + if (cmp1 < 0) { + return ternarySearch(arr, key, start, mid1 - 1); + } else if (cmp2 > 0) { + return ternarySearch(arr, key, mid2 + 1, end); + } else { + return ternarySearch(arr, key, mid1 + 1, mid2 - 1); } } } diff --git a/src/test/java/com/thealgorithms/searches/TernarySearchTest.java b/src/test/java/com/thealgorithms/searches/TernarySearchTest.java index 367b595e55d9..fa62b3f8f847 100644 --- a/src/test/java/com/thealgorithms/searches/TernarySearchTest.java +++ b/src/test/java/com/thealgorithms/searches/TernarySearchTest.java @@ -1,6 +1,7 @@ package com.thealgorithms.searches; import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; import org.junit.jupiter.api.Test; @@ -78,4 +79,65 @@ void testEdgeCaseEmptyArray() { assertEquals(-1, index, "Should return -1 for an empty array"); } + + @Test + void testNullArrayReturnsMinusOne() { + TernarySearch search = new TernarySearch(); + assertEquals(-1, search.find(null, 5)); + } + + @Test + void testNullKeyReturnsMinusOne() { + Integer[] arr = {1, 2, 3, 4, 5}; + TernarySearch search = new TernarySearch(); + assertEquals(-1, search.find(arr, null)); + } + + @Test + void testSingleElementPresent() { + Integer[] arr = {42}; + TernarySearch search = new TernarySearch(); + assertEquals(0, search.find(arr, 42)); + } + + @Test + void testSingleElementAbsent() { + Integer[] arr = {42}; + TernarySearch search = new TernarySearch(); + assertEquals(-1, search.find(arr, 24)); + } + + @Test + void testTwoElements() { + Integer[] arr = {10, 20}; + TernarySearch search = new TernarySearch(); + assertEquals(0, search.find(arr, 10)); + assertEquals(1, search.find(arr, 20)); + assertEquals(-1, search.find(arr, 15)); + } + + @Test + void testMiddlePartitionSearch() { + Integer[] arr = {1, 3, 5, 7, 9, 11, 13, 15, 17, 19}; + TernarySearch search = new TernarySearch(); + assertEquals(3, search.find(arr, 7)); + assertEquals(4, search.find(arr, 9)); + assertEquals(5, search.find(arr, 11)); + } + + @Test + void testDuplicateElements() { + Integer[] arr = {1, 2, 2, 2, 3}; + TernarySearch search = new TernarySearch(); + int index = search.find(arr, 2); + assertTrue(index >= 1 && index <= 3, "Index should be one of the occurrences of 2"); + } + + @Test + void testGenericStrings() { + String[] words = {"apple", "banana", "cherry", "date", "elderberry"}; + TernarySearch search = new TernarySearch(); + assertEquals(2, search.find(words, "cherry")); + assertEquals(-1, search.find(words, "fig")); + } } From 18c99d90c3cd9e0f1b5c8d54d927a866b43604a2 Mon Sep 17 00:00:00 2001 From: Hardik K Date: Wed, 21 Oct 2026 22:42:46 +0530 Subject: [PATCH 51/92] fix(searches): handle null array safely and eliminate raw type warnings in FibonacciSearch (#7650) Co-authored-by: Oleksandr Klymenko <19151554+alxkm@users.noreply.github.com> --- .../com/thealgorithms/searches/FibonacciSearch.java | 10 ++++++---- .../thealgorithms/searches/FibonacciSearchTest.java | 9 +++++++++ 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/src/main/java/com/thealgorithms/searches/FibonacciSearch.java b/src/main/java/com/thealgorithms/searches/FibonacciSearch.java index fa91cd14a1af..4db6874f0c08 100644 --- a/src/main/java/com/thealgorithms/searches/FibonacciSearch.java +++ b/src/main/java/com/thealgorithms/searches/FibonacciSearch.java @@ -15,8 +15,7 @@ * Note: This algorithm requires that the input array be sorted. *

*/ -@SuppressWarnings({"rawtypes", "unchecked"}) -public class FibonacciSearch implements SearchAlgorithm { +public final class FibonacciSearch implements SearchAlgorithm { /** * Finds the index of the specified key in a sorted array using Fibonacci search. @@ -24,11 +23,14 @@ public class FibonacciSearch implements SearchAlgorithm { * @param array The sorted array to search. * @param key The element to search for. * @param The type of the elements in the array, which must be comparable. - * @throws IllegalArgumentException if the input array is not sorted or empty, or if the key is null. + * @throws IllegalArgumentException if the input array is null, not sorted or empty, or if the key is null. * @return The index of the key if found, otherwise -1. */ @Override public > int find(T[] array, T key) { + if (array == null) { + throw new IllegalArgumentException("Input array must not be null."); + } if (array.length == 0) { throw new IllegalArgumentException("Input array must not be empty."); } @@ -76,7 +78,7 @@ public > int find(T[] array, T key) { return -1; } - private boolean isSorted(Comparable[] array) { + private > boolean isSorted(T[] array) { for (int i = 1; i < array.length; i++) { if (array[i - 1].compareTo(array[i]) > 0) { return false; diff --git a/src/test/java/com/thealgorithms/searches/FibonacciSearchTest.java b/src/test/java/com/thealgorithms/searches/FibonacciSearchTest.java index 04a270864223..f3056b216a7b 100644 --- a/src/test/java/com/thealgorithms/searches/FibonacciSearchTest.java +++ b/src/test/java/com/thealgorithms/searches/FibonacciSearchTest.java @@ -94,6 +94,15 @@ void testFibonacciSearchEmptyArray() { assertThrows(IllegalArgumentException.class, () -> fibonacciSearch.find(array, key), "An empty array should throw an IllegalArgumentException."); } + /** + * Test for Fibonacci search with a null array. + */ + @Test + void testFibonacciSearchNullArray() { + FibonacciSearch fibonacciSearch = new FibonacciSearch(); + assertThrows(IllegalArgumentException.class, () -> fibonacciSearch.find(null, 5), "A null array should throw an IllegalArgumentException."); + } + @Test void testFibonacciSearchUnsortedArray() { FibonacciSearch fibonacciSearch = new FibonacciSearch(); From 3c3f04e7e34fac0666adcc37f47efbd049d40d2f Mon Sep 17 00:00:00 2001 From: Hardik K Date: Wed, 21 Oct 2026 23:02:37 +0530 Subject: [PATCH 52/92] fix(searches): add null safety and make ExponentialSearch public (#7651) Co-authored-by: Oleksandr Klymenko <19151554+alxkm@users.noreply.github.com> --- .../searches/ExponentialSearch.java | 8 +-- .../searches/ExponentialSearchTest.java | 53 +++++++++++++++++++ 2 files changed, 57 insertions(+), 4 deletions(-) diff --git a/src/main/java/com/thealgorithms/searches/ExponentialSearch.java b/src/main/java/com/thealgorithms/searches/ExponentialSearch.java index e666b9148aaa..9405f5995687 100644 --- a/src/main/java/com/thealgorithms/searches/ExponentialSearch.java +++ b/src/main/java/com/thealgorithms/searches/ExponentialSearch.java @@ -19,7 +19,7 @@ * Note: This algorithm requires that the input array be sorted. *

*/ -class ExponentialSearch implements SearchAlgorithm { +public final class ExponentialSearch implements SearchAlgorithm { /** * Finds the index of the specified key in a sorted array using exponential search. @@ -31,13 +31,13 @@ class ExponentialSearch implements SearchAlgorithm { */ @Override public > int find(T[] array, T key) { - if (array.length == 0) { + if (array == null || array.length == 0 || key == null) { return -1; } - if (array[0].equals(key)) { + if (key.compareTo(array[0]) == 0) { return 0; } - if (array[array.length - 1].equals(key)) { + if (key.compareTo(array[array.length - 1]) == 0) { return array.length - 1; } diff --git a/src/test/java/com/thealgorithms/searches/ExponentialSearchTest.java b/src/test/java/com/thealgorithms/searches/ExponentialSearchTest.java index c6b07ca2b4d5..ed6f0f801bf4 100644 --- a/src/test/java/com/thealgorithms/searches/ExponentialSearchTest.java +++ b/src/test/java/com/thealgorithms/searches/ExponentialSearchTest.java @@ -1,6 +1,7 @@ package com.thealgorithms.searches; import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertTrue; import java.util.stream.IntStream; import org.junit.jupiter.api.Test; @@ -58,6 +59,17 @@ void testExponentialSearchSingleElementFound() { assertEquals(expectedIndex, exponentialSearch.find(array, key), "The index of the single element should be 0."); } + /** + * Test for exponential search with a single element not present. + */ + @Test + void testExponentialSearchSingleElementNotFound() { + ExponentialSearch exponentialSearch = new ExponentialSearch(); + Integer[] array = {1}; + int key = 2; // Key not present + assertEquals(-1, exponentialSearch.find(array, key), "The element should not be found in the array."); + } + /** * Test for exponential search with an empty array. */ @@ -70,6 +82,25 @@ void testExponentialSearchEmptyArray() { assertEquals(expectedIndex, exponentialSearch.find(array, key), "The element should not be found in an empty array."); } + /** + * Test for exponential search with a null array. + */ + @Test + void testExponentialSearchNullArray() { + ExponentialSearch exponentialSearch = new ExponentialSearch(); + assertEquals(-1, exponentialSearch.find(null, 5), "Should return -1 for null array."); + } + + /** + * Test for exponential search with a null key. + */ + @Test + void testExponentialSearchNullKey() { + ExponentialSearch exponentialSearch = new ExponentialSearch(); + Integer[] array = {1, 2, 3, 4, 5}; + assertEquals(-1, exponentialSearch.find(array, null), "Should return -1 for null key."); + } + /** * Test for exponential search on large array. */ @@ -123,4 +154,26 @@ void testExponentialSearchNotFoundReturnsMinusOne() { assertEquals(-1, exponentialSearch.find(array, 0), "A key below the minimum should give -1."); assertEquals(-1, exponentialSearch.find(array, 12), "A key above the maximum should give -1."); } + + /** + * Test for duplicate elements in the array. + */ + @Test + void testExponentialSearchDuplicates() { + ExponentialSearch exponentialSearch = new ExponentialSearch(); + Integer[] array = {1, 2, 2, 2, 3}; + int index = exponentialSearch.find(array, 2); + assertTrue(index >= 1 && index <= 3, "Index should be one of the occurrences of 2."); + } + + /** + * Test for generic Comparable types such as Strings. + */ + @Test + void testExponentialSearchStrings() { + ExponentialSearch exponentialSearch = new ExponentialSearch(); + String[] words = {"apple", "banana", "cherry", "date", "elderberry"}; + assertEquals(2, exponentialSearch.find(words, "cherry"), "Should find 'cherry' at index 2."); + assertEquals(-1, exponentialSearch.find(words, "fig"), "Should return -1 for absent word."); + } } From b526730bcec649472d0009caf4a42344033fbc22 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 22 Oct 2026 08:53:35 +0300 Subject: [PATCH 53/92] chore(deps): bump actions/setup-java from 6.0.1 to 6.1.0 in /.github/workflows (#7652) chore(deps): bump actions/setup-java in /.github/workflows Bumps [actions/setup-java](https://github.com/actions/setup-java) from 6.0.1 to 6.1.0. - [Release notes](https://github.com/actions/setup-java/releases) - [Commits](https://github.com/actions/setup-java/compare/v6.0.1...v6.1.0) --- updated-dependencies: - dependency-name: actions/setup-java dependency-version: 6.1.0 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/build.yml | 2 +- .github/workflows/codeql.yml | 2 +- .github/workflows/infer.yml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 9c582fbe0a3d..38d1471dcf13 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -10,7 +10,7 @@ jobs: steps: - uses: actions/checkout@v7 - name: Set up JDK - uses: actions/setup-java@v6.0.1 + uses: actions/setup-java@v6.1.0 with: java-version: 21 distribution: 'temurin' diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 763cc4980982..7d7a1e5755c2 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -24,7 +24,7 @@ jobs: uses: actions/checkout@v7 - name: Set up JDK - uses: actions/setup-java@v6.0.1 + uses: actions/setup-java@v6.1.0 with: java-version: 21 distribution: 'temurin' diff --git a/.github/workflows/infer.yml b/.github/workflows/infer.yml index 7b0973996a41..962c090ee699 100644 --- a/.github/workflows/infer.yml +++ b/.github/workflows/infer.yml @@ -18,7 +18,7 @@ jobs: - uses: actions/checkout@v7 - name: Set up JDK - uses: actions/setup-java@v6.0.1 + uses: actions/setup-java@v6.1.0 with: java-version: 21 distribution: 'temurin' From 2994ec327173331e340d0ee57b731a9f22578e87 Mon Sep 17 00:00:00 2001 From: Hardik K Date: Thu, 22 Oct 2026 14:54:22 +0530 Subject: [PATCH 54/92] fix(searches): fix null element skipping in SentinelLinearSearch (#7654) Co-authored-by: Oleksandr Klymenko <19151554+alxkm@users.noreply.github.com> --- .../searches/SentinelLinearSearch.java | 6 +++--- .../searches/SentinelLinearSearchTest.java | 21 +++++++++++++++++++ 2 files changed, 24 insertions(+), 3 deletions(-) diff --git a/src/main/java/com/thealgorithms/searches/SentinelLinearSearch.java b/src/main/java/com/thealgorithms/searches/SentinelLinearSearch.java index 473fc2c3f094..eb32669d1741 100644 --- a/src/main/java/com/thealgorithms/searches/SentinelLinearSearch.java +++ b/src/main/java/com/thealgorithms/searches/SentinelLinearSearch.java @@ -33,7 +33,7 @@ * @see LinearSearch * @see SearchAlgorithm */ -public class SentinelLinearSearch implements SearchAlgorithm { +public final class SentinelLinearSearch implements SearchAlgorithm { /** * Performs sentinel linear search on the given array. * @@ -65,8 +65,8 @@ public > int find(T[] array, T key) { int i = 0; // Search without bound checking since sentinel guarantees we'll find the key - // Null check for array element to prevent NPE when array contains null elements - while (array[i] != null && array[i].compareTo(key) != 0) { + // Null check for array element to skip nulls and prevent NPE when array contains null elements + while (array[i] == null || array[i].compareTo(key) != 0) { i++; } diff --git a/src/test/java/com/thealgorithms/searches/SentinelLinearSearchTest.java b/src/test/java/com/thealgorithms/searches/SentinelLinearSearchTest.java index 0da8e1c83997..087f7c9a5e2a 100644 --- a/src/test/java/com/thealgorithms/searches/SentinelLinearSearchTest.java +++ b/src/test/java/com/thealgorithms/searches/SentinelLinearSearchTest.java @@ -222,4 +222,25 @@ void testSentinelLinearSearchKeyEqualsLastElement() { Integer key = 3; // Key equals last element assertEquals(2, sentinelLinearSearch.find(array, key), "Should find the first occurrence at index 2, not the last."); } + + @Test + void testSentinelLinearSearchWithNullElementsPresent() { + SentinelLinearSearch sentinelLinearSearch = new SentinelLinearSearch(); + Integer[] array = {1, null, 3, 4}; + assertEquals(2, sentinelLinearSearch.find(array, 3), "Should correctly find element located after a null element."); + } + + @Test + void testSentinelLinearSearchWithNullElementsAbsent() { + SentinelLinearSearch sentinelLinearSearch = new SentinelLinearSearch(); + Integer[] array = {1, null, 3, 4}; + assertEquals(-1, sentinelLinearSearch.find(array, 5), "Should return -1 when key is absent even if null elements exist."); + } + + @Test + void testSentinelLinearSearchMultipleNullElements() { + SentinelLinearSearch sentinelLinearSearch = new SentinelLinearSearch(); + String[] array = {null, null, "target", null}; + assertEquals(2, sentinelLinearSearch.find(array, "target"), "Should correctly find target after multiple null elements."); + } } From 3d71df93280ba52187b607d65ee5d4540f74007d Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sat, 24 Oct 2026 14:48:22 +0200 Subject: [PATCH 55/92] chore(deps): bump github/codeql-action from 4.38.3 to 4.39.0 in /.github/workflows (#7656) chore(deps): bump github/codeql-action in /.github/workflows Bumps [github/codeql-action](https://github.com/github/codeql-action) from 4.38.3 to 4.39.0. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](https://github.com/github/codeql-action/compare/v4.38.3...v4.39.0) --- updated-dependencies: - dependency-name: github/codeql-action dependency-version: 4.39.0 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/codeql.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 7d7a1e5755c2..ae38aa619695 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -30,7 +30,7 @@ jobs: distribution: 'temurin' - name: Initialize CodeQL - uses: github/codeql-action/init@v4.38.3 + uses: github/codeql-action/init@v4.39.0 with: languages: 'java-kotlin' @@ -38,7 +38,7 @@ jobs: run: mvn --batch-mode --update-snapshots verify - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4.38.3 + uses: github/codeql-action/analyze@v4.39.0 with: category: "/language:java-kotlin" @@ -55,12 +55,12 @@ jobs: uses: actions/checkout@v7 - name: Initialize CodeQL - uses: github/codeql-action/init@v4.38.3 + uses: github/codeql-action/init@v4.39.0 with: languages: 'actions' - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4.38.3 + uses: github/codeql-action/analyze@v4.39.0 with: category: "/language:actions" ... From 773d745acb32e92dfb1bc890e88c19d8756651c4 Mon Sep 17 00:00:00 2001 From: Anwesha Date: Sat, 24 Oct 2026 21:47:40 +0530 Subject: [PATCH 56/92] Improve Javadoc for LinearSearch find method (#7657) Co-authored-by: Oleksandr Klymenko <19151554+alxkm@users.noreply.github.com> --- src/main/java/com/thealgorithms/searches/LinearSearch.java | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/main/java/com/thealgorithms/searches/LinearSearch.java b/src/main/java/com/thealgorithms/searches/LinearSearch.java index c5f6e6ba9776..3ec1768916e5 100644 --- a/src/main/java/com/thealgorithms/searches/LinearSearch.java +++ b/src/main/java/com/thealgorithms/searches/LinearSearch.java @@ -54,7 +54,8 @@ public class LinearSearch implements SearchAlgorithm { * * @param array List to be searched (can be unsorted) * @param value Key being searched for - * @return Location of the key, -1 if array is null or empty, or key not found + * @return the index of the matching element, or -1 if the array is null or empty, + * the value is null, or no matching element is found; null array elements are skipped */ @Override public > int find(T[] array, T value) { From 862de93168d075b950c475c5f7a96239ef161163 Mon Sep 17 00:00:00 2001 From: vanneladas rashmi Date: Sun, 25 Oct 2026 13:33:46 +0530 Subject: [PATCH 57/92] Update README to clarify directory content (#7658) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d60d5104c385..91766e523bca 100644 --- a/README.md +++ b/README.md @@ -17,4 +17,4 @@ These implementations are intended for learning purposes. As such, they may be l Please read our [Contribution Guidelines](CONTRIBUTING.md) before you contribute to this project. ## Algorithms -Our [directory](DIRECTORY.md) has the full list of applications. +Our [directory](DIRECTORY.md) contains the full list of algorithms implemented in Java. From 2dd1a0a189b0946736debe8cf3999324a0c78cdc Mon Sep 17 00:00:00 2001 From: Vedant Hemraj Kapgate Date: Sun, 25 Oct 2026 23:53:06 +0530 Subject: [PATCH 58/92] Add Booth's algorithm for minimal string rotation (#7644) * Add Booth's algorithm for minimal string rotation * Add tests for Booth's minimal rotation algorithm * Use constant-space comparisons in Booth's algorithm --- .../strings/BoothsAlgorithm.java | 69 +++++++++++++++++++ .../strings/BoothsAlgorithmTest.java | 45 ++++++++++++ 2 files changed, 114 insertions(+) create mode 100644 src/main/java/com/thealgorithms/strings/BoothsAlgorithm.java create mode 100644 src/test/java/com/thealgorithms/strings/BoothsAlgorithmTest.java diff --git a/src/main/java/com/thealgorithms/strings/BoothsAlgorithm.java b/src/main/java/com/thealgorithms/strings/BoothsAlgorithm.java new file mode 100644 index 000000000000..01c2f67a8569 --- /dev/null +++ b/src/main/java/com/thealgorithms/strings/BoothsAlgorithm.java @@ -0,0 +1,69 @@ +package com.thealgorithms.strings; + +/** + * Finds the lexicographically smallest cyclic rotation of a string using + * Booth's algorithm. + * + *

The algorithm compares candidate rotations without materializing them, + * running in O(n) time and O(1) auxiliary space.

+ * + * @see + * Lexicographically minimal string rotation + */ +public final class BoothsAlgorithm { + private BoothsAlgorithm() { + } + + /** + * Returns the starting index of the lexicographically smallest cyclic + * rotation of {@code input}. If several rotations are equal and minimal, + * the algorithm returns the smallest starting index among them. + * + *

For example, the smallest rotation of {@code "baca"} is + * {@code "abac"}, which starts at index {@code 3}.

+ * + * @param input the string whose minimal cyclic rotation is sought + * @return the starting index of the minimal rotation, or {@code 0} for an + * empty string + * @throws IllegalArgumentException if {@code input} is {@code null} + */ + public static int minimalRotationIndex(String input) { + if (input == null) { + throw new IllegalArgumentException("Input string must not be null"); + } + + int length = input.length(); + if (length == 0) { + return 0; + } + + int first = 0; + int second = 1; + int offset = 0; + + while (first < length && second < length && offset < length) { + char firstChar = input.charAt((first + offset) % length); + char secondChar = input.charAt((second + offset) % length); + + if (firstChar == secondChar) { + offset++; + continue; + } + + if (firstChar > secondChar) { + first += offset + 1; + if (first <= second) { + first = second + 1; + } + } else { + second += offset + 1; + if (second <= first) { + second = first + 1; + } + } + offset = 0; + } + + return Math.min(first, second); + } +} diff --git a/src/test/java/com/thealgorithms/strings/BoothsAlgorithmTest.java b/src/test/java/com/thealgorithms/strings/BoothsAlgorithmTest.java new file mode 100644 index 000000000000..19ff58eb0988 --- /dev/null +++ b/src/test/java/com/thealgorithms/strings/BoothsAlgorithmTest.java @@ -0,0 +1,45 @@ +package com.thealgorithms.strings; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; + +import org.junit.jupiter.api.Test; + +public class BoothsAlgorithmTest { + + @Test + public void testMinimalRotationIndexForExample() { + assertEquals(3, BoothsAlgorithm.minimalRotationIndex("baca")); + } + + @Test + public void testEmptyString() { + assertEquals(0, BoothsAlgorithm.minimalRotationIndex("")); + } + + @Test + public void testSingleCharacter() { + assertEquals(0, BoothsAlgorithm.minimalRotationIndex("x")); + } + + @Test + public void testRepeatedCharacters() { + assertEquals(0, BoothsAlgorithm.minimalRotationIndex("aaaaa")); + } + + @Test + public void testPeriodicString() { + assertEquals(1, BoothsAlgorithm.minimalRotationIndex("baba")); + assertEquals(1, BoothsAlgorithm.minimalRotationIndex("cabcab")); + } + + @Test + public void testStringAlreadyHasMinimalRotationAtStart() { + assertEquals(0, BoothsAlgorithm.minimalRotationIndex("abc")); + } + + @Test + public void testNullInput() { + assertThrows(IllegalArgumentException.class, () -> BoothsAlgorithm.minimalRotationIndex(null)); + } +} From 976cebc723837cd689af8f6358f7052bc477de6a Mon Sep 17 00:00:00 2001 From: Hardik K Date: Mon, 26 Oct 2026 00:05:41 +0530 Subject: [PATCH 59/92] fix(searches): add null safety and Comparable consistency to JumpSearch (#7653) --- .../thealgorithms/searches/JumpSearch.java | 8 +++-- .../searches/JumpSearchTest.java | 36 +++++++++++++++++++ 2 files changed, 42 insertions(+), 2 deletions(-) diff --git a/src/main/java/com/thealgorithms/searches/JumpSearch.java b/src/main/java/com/thealgorithms/searches/JumpSearch.java index 4253f4182db1..5e4c6da15f86 100644 --- a/src/main/java/com/thealgorithms/searches/JumpSearch.java +++ b/src/main/java/com/thealgorithms/searches/JumpSearch.java @@ -56,7 +56,7 @@ * @see BinarySearch * @see LinearSearch */ -public class JumpSearch implements SearchAlgorithm { +public final class JumpSearch implements SearchAlgorithm { /** * Jump Search algorithm implementation. @@ -67,6 +67,10 @@ public class JumpSearch implements SearchAlgorithm { */ @Override public > int find(T[] array, T key) { + if (array == null || array.length == 0 || key == null) { + return -1; + } + int length = array.length; int blockSize = (int) Math.sqrt(length); @@ -78,7 +82,7 @@ public > int find(T[] array, T key) { // Perform linear search within the identified block for (int i = limit - blockSize; i <= limit && i < length; i++) { - if (array[i].equals(key)) { + if (array[i] != null && key.compareTo(array[i]) == 0) { return i; } } diff --git a/src/test/java/com/thealgorithms/searches/JumpSearchTest.java b/src/test/java/com/thealgorithms/searches/JumpSearchTest.java index a5ce93b8a3af..3ecbaeb14dbf 100644 --- a/src/test/java/com/thealgorithms/searches/JumpSearchTest.java +++ b/src/test/java/com/thealgorithms/searches/JumpSearchTest.java @@ -139,4 +139,40 @@ void testJumpSearchFindsEveryElement() { } } } + + @Test + void testJumpSearchNullArray() { + JumpSearch jumpSearch = new JumpSearch(); + assertEquals(-1, jumpSearch.find(null, 5), "Searching in a null array should return -1."); + } + + @Test + void testJumpSearchNullKey() { + JumpSearch jumpSearch = new JumpSearch(); + Integer[] array = {1, 2, 3}; + assertEquals(-1, jumpSearch.find(array, null), "Searching for a null key should return -1."); + } + + @Test + void testJumpSearchSingleElementAbsent() { + JumpSearch jumpSearch = new JumpSearch(); + Integer[] array = {10}; + assertEquals(-1, jumpSearch.find(array, 5), "Searching for an absent key in single element array should return -1."); + } + + @Test + void testJumpSearchStringArray() { + JumpSearch jumpSearch = new JumpSearch(); + String[] array = {"apple", "banana", "cherry", "date", "elderberry"}; + assertEquals(2, jumpSearch.find(array, "cherry"), "The index of 'cherry' should be 2."); + assertEquals(-1, jumpSearch.find(array, "fig"), "Key 'fig' should not be found."); + } + + @Test + void testJumpSearchDuplicates() { + JumpSearch jumpSearch = new JumpSearch(); + Integer[] array = {1, 2, 2, 2, 3, 4, 5}; + int index = jumpSearch.find(array, 2); + assertEquals(2, array[index], "The element at the returned index should equal the target key."); + } } From 96ed2d7970606b51014afd25212c6c86d2af6255 Mon Sep 17 00:00:00 2001 From: Hardik K Date: Mon, 26 Oct 2026 00:42:58 +0530 Subject: [PATCH 60/92] fix(searches): support rectangular matrices and null safety in SearchInARowAndColWiseSortedMatrix (#7655) * fix(searches): support rectangular matrices and null safety in SearchInARowAndColWiseSortedMatrix * style: format SearchInARowAndColWiseSortedMatrixTest with clang-format --- .../SearchInARowAndColWiseSortedMatrix.java | 74 +++++++++++-------- ...earchInARowAndColWiseSortedMatrixTest.java | 32 ++++++++ 2 files changed, 74 insertions(+), 32 deletions(-) diff --git a/src/main/java/com/thealgorithms/searches/SearchInARowAndColWiseSortedMatrix.java b/src/main/java/com/thealgorithms/searches/SearchInARowAndColWiseSortedMatrix.java index b53c7e5256ca..20a07adafd26 100644 --- a/src/main/java/com/thealgorithms/searches/SearchInARowAndColWiseSortedMatrix.java +++ b/src/main/java/com/thealgorithms/searches/SearchInARowAndColWiseSortedMatrix.java @@ -1,32 +1,42 @@ -package com.thealgorithms.searches; - -public class SearchInARowAndColWiseSortedMatrix { - /** - * Search a key in row and column wise sorted matrix - * - * @param matrix matrix to be searched - * @param value Key being searched for - * @author Sadiul Hakim : https://github.com/sadiul-hakim - */ - public int[] search(int[][] matrix, int value) { - int n = matrix.length; - // This variable iterates over rows - int i = 0; - // This variable iterates over columns - int j = n - 1; - int[] result = {-1, -1}; - while (i < n && j >= 0) { - if (matrix[i][j] == value) { - result[0] = i; - result[1] = j; - return result; - } - if (value > matrix[i][j]) { - i++; - } else { - j--; - } - } - return result; - } -} +package com.thealgorithms.searches; + +public final class SearchInARowAndColWiseSortedMatrix { + /** + * Search a key in row and column wise sorted matrix + * + * @param matrix matrix to be searched + * @param value Key being searched for + * @return row and column indices if found, otherwise {-1, -1} + * @author Sadiul Hakim : https://github.com/sadiul-hakim + */ + public int[] search(int[][] matrix, int value) { + if (matrix == null || matrix.length == 0 || matrix[0] == null || matrix[0].length == 0) { + return new int[] {-1, -1}; + } + + int rows = matrix.length; + int cols = matrix[0].length; + // This variable iterates over rows + int i = 0; + // This variable iterates over columns, starting from top-right corner + int j = cols - 1; + int[] result = {-1, -1}; + while (i < rows && j >= 0) { + if (matrix[i] == null || j >= matrix[i].length) { + i++; + continue; + } + if (matrix[i][j] == value) { + result[0] = i; + result[1] = j; + return result; + } + if (value > matrix[i][j]) { + i++; + } else { + j--; + } + } + return result; + } +} diff --git a/src/test/java/com/thealgorithms/searches/SearchInARowAndColWiseSortedMatrixTest.java b/src/test/java/com/thealgorithms/searches/SearchInARowAndColWiseSortedMatrixTest.java index 88227804b775..e37eec82cb8e 100644 --- a/src/test/java/com/thealgorithms/searches/SearchInARowAndColWiseSortedMatrixTest.java +++ b/src/test/java/com/thealgorithms/searches/SearchInARowAndColWiseSortedMatrixTest.java @@ -63,4 +63,36 @@ void testSearchInColWiseSortedMatrix() { int[] expected = {1, 1}; // Found at (1, 1) assertArrayEquals(expected, searcher.search(matrix, value), "Value should be found in the column-wise sorted matrix"); } + + @Test + void testSearchInNullMatrix() { + assertArrayEquals(new int[] {-1, -1}, searcher.search(null, 5), "Should return {-1, -1} for null matrix"); + } + + @Test + void testSearchInMatrixWithEmptyRows() { + int[][] matrix = {{}}; + assertArrayEquals(new int[] {-1, -1}, searcher.search(matrix, 5), "Should return {-1, -1} for matrix with empty first row"); + } + + @Test + void testSearchInRectangularMatrixMoreColsThanRowsFound() { + int[][] matrix = {{1, 3, 5, 7, 9}, {2, 4, 6, 8, 10}}; + int[] expected = {0, 4}; // Value 9 is at row 0, col 4 + assertArrayEquals(expected, searcher.search(matrix, 9), "Value 9 should be found at row 0, col 4"); + } + + @Test + void testSearchInRectangularMatrixMoreRowsThanColsFound() { + int[][] matrix = {{1, 5}, {2, 6}, {3, 7}, {4, 8}}; + int[] expected = {2, 0}; // Value 3 is at row 2, col 0 + assertArrayEquals(expected, searcher.search(matrix, 3), "Value 3 should be found at row 2, col 0"); + } + + @Test + void testSearchInRectangularMatrixNotFound() { + int[][] matrix = {{1, 3, 5}, {2, 4, 6}, {7, 8, 9}, {10, 11, 12}}; + int[] expected = {-1, -1}; + assertArrayEquals(expected, searcher.search(matrix, 15), "Value 15 should not be found"); + } } From 12f69b38dc094a24116335c75f2baf5323999a05 Mon Sep 17 00:00:00 2001 From: Rishavbhattarai <67967801+Rishavbhattarai@users.noreply.github.com> Date: Tue, 27 Oct 2026 13:00:08 +0545 Subject: [PATCH 61/92] fix(sorts): keep duplicate values in TreeSort (#7661) --- .../com/thealgorithms/sorts/TreeSort.java | 49 ++++++++++--------- .../com/thealgorithms/sorts/TreeSortTest.java | 13 ++++- 2 files changed, 38 insertions(+), 24 deletions(-) diff --git a/src/main/java/com/thealgorithms/sorts/TreeSort.java b/src/main/java/com/thealgorithms/sorts/TreeSort.java index 6f4e5509489d..1c0b407c7f84 100644 --- a/src/main/java/com/thealgorithms/sorts/TreeSort.java +++ b/src/main/java/com/thealgorithms/sorts/TreeSort.java @@ -3,6 +3,8 @@ import static com.thealgorithms.sorts.SortUtils.print; import com.thealgorithms.datastructures.trees.BSTRecursiveGeneric; +import java.util.ArrayList; +import java.util.Arrays; import java.util.List; /** @@ -30,38 +32,39 @@ public > List sort(List unsortedList) { } private > T[] doTreeSortArray(T[] unsortedArray) { - // create a generic BST tree - BSTRecursiveGeneric tree = new BSTRecursiveGeneric(); - - // add all elements to the tree - for (T element : unsortedArray) { - tree.add(element); - } - - // get the sorted list by inorder traversal of the tree - List sortedList = tree.inorderSort(); - - // add the elements back to the initial array - int i = 0; - for (T element : sortedList) { - unsortedArray[i++] = element; - } - - // return the array - return unsortedArray; + // sort through the list path and copy the result back into the initial array + List sortedList = doTreeSortList(Arrays.asList(unsortedArray)); + return sortedList.toArray(unsortedArray); } private > List doTreeSortList(Iterable unsortedList) { - // create a generic BST tree - BSTRecursiveGeneric tree = new BSTRecursiveGeneric(); + // the BST ignores duplicate keys, so pair every element with its position to keep equal values apart + BSTRecursiveGeneric> tree = new BSTRecursiveGeneric<>(); // add all elements to the tree + int position = 0; for (T element : unsortedList) { - tree.add(element); + tree.add(new Keyed<>(element, position++)); } // get the sorted list by inorder traversal of the tree and return it - return tree.inorderSort(); + List sortedList = new ArrayList<>(); + for (Keyed keyed : tree.inorderSort()) { + sortedList.add(keyed.value()); + } + return sortedList; + } + + /** + * An element plus its original position. Equal elements are ordered by position, + * which also makes the sort stable. + */ + private record Keyed>(T value, int position) implements Comparable> { + @Override + public int compareTo(Keyed other) { + int byValue = value.compareTo(other.value); + return byValue != 0 ? byValue : Integer.compare(position, other.position); + } } public static void main(String[] args) { diff --git a/src/test/java/com/thealgorithms/sorts/TreeSortTest.java b/src/test/java/com/thealgorithms/sorts/TreeSortTest.java index 5fb4c18e953e..6cede929ea51 100644 --- a/src/test/java/com/thealgorithms/sorts/TreeSortTest.java +++ b/src/test/java/com/thealgorithms/sorts/TreeSortTest.java @@ -9,9 +9,20 @@ * @see TreeSort */ -public class TreeSortTest { +public class TreeSortTest extends SortingAlgorithmTest { private TreeSort treeSort = new TreeSort(); + @Override + SortAlgorithm getSortAlgorithm() { + return new TreeSort(); + } + + @Test + public void treeSortKeepsDuplicates() { + Integer[] array = {-1, -1, 0}; + assertArrayEquals(new Integer[] {-1, -1, 0}, treeSort.sort(array)); + } + @Test public void treeSortEmptyArray() { Integer[] inputArray = {}; From 6f19dd4eed9ed426c87dcdcb80f0c0dacbfa9f7c Mon Sep 17 00:00:00 2001 From: Rishavbhattarai <67967801+Rishavbhattarai@users.noreply.github.com> Date: Tue, 27 Oct 2026 13:16:34 +0545 Subject: [PATCH 62/92] fix(sorts): stop SwapSort looping forever on duplicate values (#7660) Co-authored-by: Oleksandr Klymenko <19151554+alxkm@users.noreply.github.com> --- src/main/java/com/thealgorithms/sorts/SwapSort.java | 7 ++++++- .../java/com/thealgorithms/sorts/SwapSortTest.java | 13 +++++++++++++ 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/src/main/java/com/thealgorithms/sorts/SwapSort.java b/src/main/java/com/thealgorithms/sorts/SwapSort.java index b5c1c3892546..169fba93fc57 100644 --- a/src/main/java/com/thealgorithms/sorts/SwapSort.java +++ b/src/main/java/com/thealgorithms/sorts/SwapSort.java @@ -17,7 +17,12 @@ public > T[] sort(T[] array) { final int amountSmallerElements = this.getSmallerElementCount(array, index); if (amountSmallerElements > 0) { - SortUtils.swap(array, index, index + amountSmallerElements); + int target = index + amountSmallerElements; + // Skip slots that already hold an equal element, otherwise two equal values swap forever + while (array[target].compareTo(array[index]) == 0) { + target++; + } + SortUtils.swap(array, index, target); } else { index++; } diff --git a/src/test/java/com/thealgorithms/sorts/SwapSortTest.java b/src/test/java/com/thealgorithms/sorts/SwapSortTest.java index c1638a385940..e29bbc5f1b64 100644 --- a/src/test/java/com/thealgorithms/sorts/SwapSortTest.java +++ b/src/test/java/com/thealgorithms/sorts/SwapSortTest.java @@ -1,8 +1,21 @@ package com.thealgorithms.sorts; +import static org.junit.jupiter.api.Assertions.assertArrayEquals; + +import java.util.concurrent.TimeUnit; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.Timeout; + public class SwapSortTest extends SortingAlgorithmTest { @Override SortAlgorithm getSortAlgorithm() { return new SwapSort(); } + + @Test + @Timeout(value = 1, unit = TimeUnit.SECONDS, threadMode = Timeout.ThreadMode.SEPARATE_THREAD) + void shouldSortWhenDuplicateWouldBeSwappedOntoItsTwin() { + Integer[] array = {2, 2, 1, 1, 0, 0, 0}; + assertArrayEquals(new Integer[] {0, 0, 0, 1, 1, 2, 2}, new SwapSort().sort(array)); + } } From bd64e8d4028a8f50792528c1557f2d5118d39ef6 Mon Sep 17 00:00:00 2001 From: Rishavbhattarai <67967801+Rishavbhattarai@users.noreply.github.com> Date: Tue, 27 Oct 2026 13:40:39 +0545 Subject: [PATCH 63/92] fix(sorts): handle small arrays in FlashSort and empty arrays in DutchNationalFlagSort (#7662) Co-authored-by: Oleksandr Klymenko <19151554+alxkm@users.noreply.github.com> --- .../com/thealgorithms/sorts/DutchNationalFlagSort.java | 3 +++ src/main/java/com/thealgorithms/sorts/FlashSort.java | 3 ++- .../com/thealgorithms/sorts/DutchNationalFlagSortTest.java | 6 ++++++ src/test/java/com/thealgorithms/sorts/FlashSortTest.java | 7 +++++++ 4 files changed, 18 insertions(+), 1 deletion(-) diff --git a/src/main/java/com/thealgorithms/sorts/DutchNationalFlagSort.java b/src/main/java/com/thealgorithms/sorts/DutchNationalFlagSort.java index f7e12da06568..2e3a2fcea704 100644 --- a/src/main/java/com/thealgorithms/sorts/DutchNationalFlagSort.java +++ b/src/main/java/com/thealgorithms/sorts/DutchNationalFlagSort.java @@ -13,6 +13,9 @@ public class DutchNationalFlagSort implements SortAlgorithm { @Override public > T[] sort(T[] array) { + if (array.length == 0) { + return array; + } return dutchNationalFlagSort(array, array[(int) Math.ceil((array.length) / 2.0) - 1]); } diff --git a/src/main/java/com/thealgorithms/sorts/FlashSort.java b/src/main/java/com/thealgorithms/sorts/FlashSort.java index e8dbf8c42742..79c2d8b82700 100644 --- a/src/main/java/com/thealgorithms/sorts/FlashSort.java +++ b/src/main/java/com/thealgorithms/sorts/FlashSort.java @@ -76,7 +76,8 @@ private > void flashSort(T[] arr) { return; // All elements are the same } - final int m = (int) (classificationRatio * arr.length); + // At least one class, otherwise small arrays index into an empty classification table + final int m = Math.max(1, (int) (classificationRatio * arr.length)); final int[] classificationArray = new int[m]; diff --git a/src/test/java/com/thealgorithms/sorts/DutchNationalFlagSortTest.java b/src/test/java/com/thealgorithms/sorts/DutchNationalFlagSortTest.java index c7581e7c8f7b..d9c014e8b21d 100644 --- a/src/test/java/com/thealgorithms/sorts/DutchNationalFlagSortTest.java +++ b/src/test/java/com/thealgorithms/sorts/DutchNationalFlagSortTest.java @@ -109,4 +109,10 @@ void testOddStringsMidGivenDnfs() { dutchNationalFlagSort.sort(strings, "e"); assertArrayEquals(strings, stringsResult); } + + @Test + void testEmptyArray() { + Integer[] integers = {}; + assertArrayEquals(new Integer[] {}, new DutchNationalFlagSort().sort(integers)); + } } diff --git a/src/test/java/com/thealgorithms/sorts/FlashSortTest.java b/src/test/java/com/thealgorithms/sorts/FlashSortTest.java index 5b27975d3bea..6b4b1230925f 100644 --- a/src/test/java/com/thealgorithms/sorts/FlashSortTest.java +++ b/src/test/java/com/thealgorithms/sorts/FlashSortTest.java @@ -1,5 +1,6 @@ package com.thealgorithms.sorts; +import static org.junit.jupiter.api.Assertions.assertArrayEquals; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertThrows; @@ -59,6 +60,12 @@ public List dynamicTestsForSorting() { return dynamicTests; } + @Test + public void testArraysTooSmallForMoreThanOneClass() { + assertArrayEquals(new Integer[] {1, 2}, new FlashSort().sort(new Integer[] {2, 1})); + assertArrayEquals(new Integer[] {1, 2, 3, 4, 5}, new FlashSort(0.1).sort(new Integer[] {5, 3, 1, 4, 2})); + } + private List createDynamicTestsForRatio(double ratio) { List dynamicTests = new ArrayList<>(); for (TestMethod testMethod : getTestMethodsFromSuperClass()) { From a7a244157cf22e62a8f7c95fd6f6be5628edfa7a Mon Sep 17 00:00:00 2001 From: Rishavbhattarai <67967801+Rishavbhattarai@users.noreply.github.com> Date: Tue, 27 Oct 2026 14:06:47 +0545 Subject: [PATCH 64/92] fix(strings): use case-insensitive shift table in HorspoolSearch.findFirstInsensitive (#7663) Co-authored-by: Oleksandr Klymenko <19151554+alxkm@users.noreply.github.com> --- .../thealgorithms/strings/HorspoolSearch.java | 18 +++++++++++------- .../strings/HorspoolSearchTest.java | 7 +++++++ 2 files changed, 18 insertions(+), 7 deletions(-) diff --git a/src/main/java/com/thealgorithms/strings/HorspoolSearch.java b/src/main/java/com/thealgorithms/strings/HorspoolSearch.java index d9187cbf66c4..51dcdd804b25 100644 --- a/src/main/java/com/thealgorithms/strings/HorspoolSearch.java +++ b/src/main/java/com/thealgorithms/strings/HorspoolSearch.java @@ -95,7 +95,7 @@ public static Integer getLastComparisons() { * @return index of first occurrence of the pattern in the text */ private static int firstOccurrence(String pattern, String text, boolean caseSensitive) { - shiftValues = calcShiftValues(pattern); // build the bad symbol table + shiftValues = calcShiftValues(pattern, caseSensitive); // build the bad symbol table comparisons = 0; // reset comparisons if (pattern.length() == 0) { // return failure, if pattern empty @@ -113,7 +113,7 @@ private static int firstOccurrence(String pattern, String text, boolean caseSens char patternChar = pattern.charAt(i); char textChar = text.charAt((textIndex + i) - (pattern.length() - 1)); if (!charEquals(patternChar, textChar, caseSensitive)) { // bad character, shift pattern - textIndex += getShiftValue(text.charAt(textIndex)); + textIndex += getShiftValue(text.charAt(textIndex), caseSensitive); break; } i--; @@ -153,14 +153,15 @@ private static boolean charEquals(char c1, char c2, boolean caseSensitive) { * in the table, then it is not a rightmost occurrence, so it continues. * * @param pattern basis for the bad symbol table + * @param caseSensitive whether to build the table with case-sensitive keys * @return the bad symbol table */ - private static HashMap calcShiftValues(String pattern) { + private static HashMap calcShiftValues(String pattern, boolean caseSensitive) { patternLength = pattern.length(); HashMap table = new HashMap<>(); for (int i = pattern.length() - 2; i >= 0; i--) { // length - 2 is the index of the second to last character - char c = pattern.charAt(i); + char c = caseSensitive ? pattern.charAt(i) : Character.toLowerCase(pattern.charAt(i)); int finalI = i; table.computeIfAbsent(c, k -> pattern.length() - 1 - finalI); } @@ -173,11 +174,14 @@ private static HashMap calcShiftValues(String pattern) { * appropriate shift value for a given character * * @param c character + * @param caseSensitive whether the table was built with case-sensitive keys * @return shift value that corresponds to the character argument */ - private static Integer getShiftValue(char c) { - if (shiftValues.get(c) != null) { - return shiftValues.get(c); + private static Integer getShiftValue(char c, boolean caseSensitive) { + // the table holds lower-case keys for case-insensitive searches + char key = caseSensitive ? c : Character.toLowerCase(c); + if (shiftValues.get(key) != null) { + return shiftValues.get(key); } else { return patternLength; } diff --git a/src/test/java/com/thealgorithms/strings/HorspoolSearchTest.java b/src/test/java/com/thealgorithms/strings/HorspoolSearchTest.java index 9649a89a3325..d364e4923e70 100644 --- a/src/test/java/com/thealgorithms/strings/HorspoolSearchTest.java +++ b/src/test/java/com/thealgorithms/strings/HorspoolSearchTest.java @@ -61,6 +61,13 @@ void testFindFirstInsensitiveNotMatch() { assertEquals(-1, index); } + @Test + void testFindFirstInsensitiveWhenCaseDiffersFromPattern() { + assertEquals(1, HorspoolSearch.findFirstInsensitive("AB", "xab")); + assertEquals(1, HorspoolSearch.findFirstInsensitive("ab", "xAB")); + assertEquals(2, HorspoolSearch.findFirstInsensitive("ba", "bbBA")); + } + @Test void testGetLastComparisons() { HorspoolSearch.findFirst("World", "Hello World"); From 231979449940934d77c34ba8fa2cb7143de71916 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 29 Oct 2026 08:39:29 +0200 Subject: [PATCH 65/92] chore(deps): bump github/codeql-action from 4.39.0 to 4.39.1 in /.github/workflows (#7676) chore(deps): bump github/codeql-action in /.github/workflows Bumps [github/codeql-action](https://github.com/github/codeql-action) from 4.39.0 to 4.39.1. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](https://github.com/github/codeql-action/compare/v4.39.0...v4.39.1) --- updated-dependencies: - dependency-name: github/codeql-action dependency-version: 4.39.1 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/codeql.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index ae38aa619695..d9d9ed1e54e9 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -30,7 +30,7 @@ jobs: distribution: 'temurin' - name: Initialize CodeQL - uses: github/codeql-action/init@v4.39.0 + uses: github/codeql-action/init@v4.39.1 with: languages: 'java-kotlin' @@ -38,7 +38,7 @@ jobs: run: mvn --batch-mode --update-snapshots verify - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4.39.0 + uses: github/codeql-action/analyze@v4.39.1 with: category: "/language:java-kotlin" @@ -55,12 +55,12 @@ jobs: uses: actions/checkout@v7 - name: Initialize CodeQL - uses: github/codeql-action/init@v4.39.0 + uses: github/codeql-action/init@v4.39.1 with: languages: 'actions' - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4.39.0 + uses: github/codeql-action/analyze@v4.39.1 with: category: "/language:actions" ... From 410f08753505a0af9e46423396e8768bc97cbc1c Mon Sep 17 00:00:00 2001 From: Rishavbhattarai <67967801+Rishavbhattarai@users.noreply.github.com> Date: Fri, 30 Oct 2026 04:01:39 +0545 Subject: [PATCH 66/92] fix(lists): leave SkipList size unchanged when removing a missing element (#7666) --- .../datastructures/lists/SkipList.java | 3 +++ .../datastructures/lists/SkipListTest.java | 14 ++++++++++++++ 2 files changed, 17 insertions(+) diff --git a/src/main/java/com/thealgorithms/datastructures/lists/SkipList.java b/src/main/java/com/thealgorithms/datastructures/lists/SkipList.java index 0b4fcd91483c..7e03ca3856b5 100644 --- a/src/main/java/com/thealgorithms/datastructures/lists/SkipList.java +++ b/src/main/java/com/thealgorithms/datastructures/lists/SkipList.java @@ -121,6 +121,9 @@ public void remove(E e) { current = next; } } + if (layer < 0) { + return; // not found, nothing to unlink + } for (int i = 0; i <= layer; i++) { current.previous(i).setNext(i, current.next(i)); if (current.next(i) != null) { diff --git a/src/test/java/com/thealgorithms/datastructures/lists/SkipListTest.java b/src/test/java/com/thealgorithms/datastructures/lists/SkipListTest.java index 16d1a015a4d9..53707ffab1b6 100644 --- a/src/test/java/com/thealgorithms/datastructures/lists/SkipListTest.java +++ b/src/test/java/com/thealgorithms/datastructures/lists/SkipListTest.java @@ -106,6 +106,20 @@ void testClearViaRemovals() { assertEquals(0, skipList.size()); } + @Test + @DisplayName("Removing a missing element leaves the list unchanged") + void testRemoveMissing() { + skipList.remove("missing"); + assertEquals(0, skipList.size()); + + skipList.add("a"); + skipList.add("c"); + skipList.remove("b"); + assertEquals(2, skipList.size()); + assertEquals("a", skipList.get(0)); + assertEquals("c", skipList.get(1)); + } + private SkipList createSkipList() { SkipList s = new SkipList<>(); String[] values = {"a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k"}; From 7643e245b57a4f1da04460a0ff5c30c116f94e16 Mon Sep 17 00:00:00 2001 From: Rishavbhattarai <67967801+Rishavbhattarai@users.noreply.github.com> Date: Sun, 1 Nov 2026 23:18:05 +0545 Subject: [PATCH 67/92] fix(searches): support characters outside extended ASCII in BoyerMoore (#7664) --- .../com/thealgorithms/searches/BoyerMoore.java | 18 ++++++++---------- .../thealgorithms/searches/BoyerMooreTest.java | 7 +++++++ 2 files changed, 15 insertions(+), 10 deletions(-) diff --git a/src/main/java/com/thealgorithms/searches/BoyerMoore.java b/src/main/java/com/thealgorithms/searches/BoyerMoore.java index 6998021503cc..5c491210302b 100644 --- a/src/main/java/com/thealgorithms/searches/BoyerMoore.java +++ b/src/main/java/com/thealgorithms/searches/BoyerMoore.java @@ -1,5 +1,8 @@ package com.thealgorithms.searches; +import java.util.HashMap; +import java.util.Map; + /** * Boyer-Moore string search algorithm. * Efficient algorithm for substring search. @@ -7,21 +10,16 @@ */ public class BoyerMoore { - private final int radix; // Radix (number of possible characters) - private final int[] right; // Bad character rule table + private final Map right; // Bad character rule table: last index of each pattern character private final String pattern; public BoyerMoore(String pat) { this.pattern = pat; - this.radix = 256; - this.right = new int[radix]; - - for (int c = 0; c < radix; c++) { - right[c] = -1; - } + // A map instead of a 256-entry array, so characters outside extended ASCII work too + this.right = new HashMap<>(); for (int j = 0; j < pat.length(); j++) { - right[pat.charAt(j)] = j; + right.put(pat.charAt(j), j); } } @@ -40,7 +38,7 @@ public int search(String text) { char txtChar = text.charAt(i + j); char patChar = pattern.charAt(j); if (patChar != txtChar) { - skip = Math.max(1, j - right[txtChar]); + skip = Math.max(1, j - right.getOrDefault(txtChar, -1)); break; } } diff --git a/src/test/java/com/thealgorithms/searches/BoyerMooreTest.java b/src/test/java/com/thealgorithms/searches/BoyerMooreTest.java index 9021eacbb8ee..b89fa23b1195 100644 --- a/src/test/java/com/thealgorithms/searches/BoyerMooreTest.java +++ b/src/test/java/com/thealgorithms/searches/BoyerMooreTest.java @@ -52,4 +52,11 @@ public void testStaticSearchMethod() { int index = BoyerMoore.staticSearch(text, "CDE"); assertEquals(2, index); // Primera ocurrencia de "CDE" } + + @Test + public void testCharactersOutsideExtendedAscii() { + assertEquals(1, BoyerMoore.staticSearch("x中文", "中")); + assertEquals(-1, BoyerMoore.staticSearch("中文", "x")); + assertEquals(2, BoyerMoore.staticSearch("€ €uro", "€uro")); + } } From 8b49bc5046c6df87441f85aabb1f110fc8c03be6 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Sun, 1 Nov 2026 20:55:53 +0000 Subject: [PATCH 68/92] chore(deps): bump actions/setup-python from 7.0.0 to 7.1.0 in /.github/workflows (#7677) chore(deps): bump actions/setup-python in /.github/workflows Bumps [actions/setup-python](https://github.com/actions/setup-python) from 7.0.0 to 7.1.0. - [Release notes](https://github.com/actions/setup-python/releases) - [Commits](https://github.com/actions/setup-python/compare/v7.0.0...v7.1.0) --- updated-dependencies: - dependency-name: actions/setup-python dependency-version: 7.1.0 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/project_structure.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/project_structure.yml b/.github/workflows/project_structure.yml index a70c3240ce08..764832b7b6a6 100644 --- a/.github/workflows/project_structure.yml +++ b/.github/workflows/project_structure.yml @@ -16,7 +16,7 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v7 - - uses: actions/setup-python@v7.0.0 + - uses: actions/setup-python@v7.1.0 with: python-version: '3.13' From 6edd2d878947c7fb08a6f3286b316eca09fe9200 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 2 Nov 2026 23:50:13 +0200 Subject: [PATCH 69/92] chore(deps-dev): bump org.jacoco:jacoco-maven-plugin from 0.8.15 to 0.8.16 (#7727) chore(deps-dev): bump org.jacoco:jacoco-maven-plugin Bumps [org.jacoco:jacoco-maven-plugin](https://github.com/jacoco/jacoco) from 0.8.15 to 0.8.16. - [Release notes](https://github.com/jacoco/jacoco/releases) - [Commits](https://github.com/jacoco/jacoco/compare/v0.8.15...v0.8.16) --- updated-dependencies: - dependency-name: org.jacoco:jacoco-maven-plugin dependency-version: 0.8.16 dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 21dd79ad17b1..c31c3e7915eb 100644 --- a/pom.xml +++ b/pom.xml @@ -82,7 +82,7 @@ org.jacoco jacoco-maven-plugin - 0.8.15 + 0.8.16 From 36e6d6669120bee21b6cb73c7a9b5eb01469c137 Mon Sep 17 00:00:00 2001 From: NanditaMazz Date: Tue, 3 Nov 2026 17:52:16 +0530 Subject: [PATCH 70/92] test: add Fibonacci matrix exponentiation tests (#7719) * test: add Fibonacci matrix exponentiation tests * style: fix Fibonacci test formatting --- .../matrixexponentiation/FibonacciTest.java | 34 +++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 src/test/java/com/thealgorithms/matrix/matrixexponentiation/FibonacciTest.java diff --git a/src/test/java/com/thealgorithms/matrix/matrixexponentiation/FibonacciTest.java b/src/test/java/com/thealgorithms/matrix/matrixexponentiation/FibonacciTest.java new file mode 100644 index 000000000000..9f70940bde19 --- /dev/null +++ b/src/test/java/com/thealgorithms/matrix/matrixexponentiation/FibonacciTest.java @@ -0,0 +1,34 @@ +package com.thealgorithms.matrix.matrixexponentiation; +import static org.junit.jupiter.api.Assertions.assertArrayEquals; + +import java.math.BigDecimal; +import org.junit.jupiter.api.Test; +class FibonacciTest { + private static BigDecimal[][] matrix(String a, String b, String c, String d) { + return new BigDecimal[][] {{new BigDecimal(a), new BigDecimal(b)}, {new BigDecimal(c), new BigDecimal(d)}}; + } + @Test + void testFibZeroReturnsIdentityMatrix() { + assertArrayEquals(matrix("1", "0", "0", "1"), Fibonacci.fib(0)); + } + @Test + void testFibOne() { + assertArrayEquals(matrix("1", "1", "1", "0"), Fibonacci.fib(1)); + } + @Test + void testFibEvenInput() { + assertArrayEquals(matrix("2", "1", "1", "1"), Fibonacci.fib(2)); + } + @Test + void testFibOddInput() { + assertArrayEquals(matrix("3", "2", "2", "1"), Fibonacci.fib(3)); + } + @Test + void testFibTen() { + assertArrayEquals(matrix("89", "55", "55", "34"), Fibonacci.fib(10)); + } + @Test + void testFibLargeInput() { + assertArrayEquals(matrix("20365011074", "12586269025", "12586269025", "7778742049"), Fibonacci.fib(50)); + } +} From e6b2ecb50f8278c55ade38b947c5c82afdc68438 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 3 Nov 2026 13:01:25 +0000 Subject: [PATCH 71/92] chore(deps-dev): bump org.apache.maven.plugins:maven-surefire-plugin from 3.6.0 to 3.6.1 (#7700) chore(deps-dev): bump org.apache.maven.plugins:maven-surefire-plugin Bumps [org.apache.maven.plugins:maven-surefire-plugin](https://github.com/apache/maven-surefire) from 3.6.0 to 3.6.1. - [Release notes](https://github.com/apache/maven-surefire/releases) - [Commits](https://github.com/apache/maven-surefire/compare/surefire-3.6.0...surefire-3.6.1) --- updated-dependencies: - dependency-name: org.apache.maven.plugins:maven-surefire-plugin dependency-version: 3.6.1 dependency-type: direct:development update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index c31c3e7915eb..d7c7a0849fb8 100644 --- a/pom.xml +++ b/pom.xml @@ -61,7 +61,7 @@ maven-surefire-plugin - 3.6.0 + 3.6.1 From 4f535f583503c5225d3f2d8cb681b0cb0492bc5d Mon Sep 17 00:00:00 2001 From: Rishavbhattarai <67967801+Rishavbhattarai@users.noreply.github.com> Date: Wed, 4 Nov 2026 16:52:09 +0545 Subject: [PATCH 72/92] fix(searches): avoid int overflow and short-text crash in RabinKarpAlgorithm (#7665) --- .../thealgorithms/searches/RabinKarpAlgorithm.java | 11 ++++++++--- .../searches/RabinKarpAlgorithmTest.java | 2 +- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/src/main/java/com/thealgorithms/searches/RabinKarpAlgorithm.java b/src/main/java/com/thealgorithms/searches/RabinKarpAlgorithm.java index 81e16dbbbf07..35d696f2a2f2 100644 --- a/src/main/java/com/thealgorithms/searches/RabinKarpAlgorithm.java +++ b/src/main/java/com/thealgorithms/searches/RabinKarpAlgorithm.java @@ -13,9 +13,14 @@ public static int search(String pattern, String text, int primeNumber) { int index = -1; // -1 here represents not found int patternLength = pattern.length(); int textLength = text.length(); - int hashForPattern = 0; - int hashForText = 0; - int h = 1; + if (patternLength > textLength) { + return index; + } + + // long, so hash * ALPHABET_SIZE cannot overflow for large primes such as 1_000_000_007 + long hashForPattern = 0; + long hashForText = 0; + long h = 1; // The value of h would be "pow(d, patternLength-1)%primeNumber" for (int i = 0; i < patternLength - 1; i++) { diff --git a/src/test/java/com/thealgorithms/searches/RabinKarpAlgorithmTest.java b/src/test/java/com/thealgorithms/searches/RabinKarpAlgorithmTest.java index 40e1acce9c3a..3e2314ad89cd 100644 --- a/src/test/java/com/thealgorithms/searches/RabinKarpAlgorithmTest.java +++ b/src/test/java/com/thealgorithms/searches/RabinKarpAlgorithmTest.java @@ -8,7 +8,7 @@ class RabinKarpAlgorithmTest { @ParameterizedTest - @CsvSource({"This is an example for rabin karp algorithmn, algorithmn, 101", "AAABBDDG, AAA, 137", "AAABBCCBB, BBCC, 101", "AAABBCCBB, BBCC, 131", "AAAABBBBCCC, CCC, 41", "ABCBCBCAAB, AADB, 293", "Algorithm The Algorithm, Algorithm, 101"}) + @CsvSource({"This is an example for rabin karp algorithmn, algorithmn, 101", "AAABBDDG, AAA, 137", "AAABBCCBB, BBCC, 101", "AAABBCCBB, BBCC, 131", "AAAABBBBCCC, CCC, 41", "ABCBCBCAAB, AADB, 293", "Algorithm The Algorithm, Algorithm, 101", "nzdjsjggwx, jggw, 1000000007", "AB, ABC, 101"}) void rabinKarpAlgorithmTestExample(String txt, String pat, int q) { int indexFromOurAlgorithm = RabinKarpAlgorithm.search(pat, txt, q); int indexFromLinearSearch = txt.indexOf(pat); From 51a0156d8431f1e93021fa9a3dd6ef0533d04880 Mon Sep 17 00:00:00 2001 From: Bhumit Peswani Date: Thu, 5 Nov 2026 18:45:16 +0530 Subject: [PATCH 73/92] fix(maths): prevent infinite recursion on negative inputs in BinomialCoefficient (#7730) --- .../com/thealgorithms/maths/BinomialCoefficient.java | 5 +++++ .../thealgorithms/maths/BinomialCoefficientTest.java | 10 ++++++++++ 2 files changed, 15 insertions(+) diff --git a/src/main/java/com/thealgorithms/maths/BinomialCoefficient.java b/src/main/java/com/thealgorithms/maths/BinomialCoefficient.java index 1de39adbc18a..a7caf7efa44f 100644 --- a/src/main/java/com/thealgorithms/maths/BinomialCoefficient.java +++ b/src/main/java/com/thealgorithms/maths/BinomialCoefficient.java @@ -21,9 +21,14 @@ private BinomialCoefficient() { * @param numberOfObjects Number of objects to be chosen from total_objects * @return number of ways in which no_of_objects objects can be chosen from total_objects * objects + * @throws IllegalArgumentException if totalObjects or numberOfObjects is negative */ public static int binomialCoefficient(int totalObjects, int numberOfObjects) { + if (totalObjects < 0 || numberOfObjects < 0) { + throw new IllegalArgumentException("Arguments must be non-negative."); + } + // Base Case if (numberOfObjects > totalObjects) { return 0; diff --git a/src/test/java/com/thealgorithms/maths/BinomialCoefficientTest.java b/src/test/java/com/thealgorithms/maths/BinomialCoefficientTest.java index 58cfcbad57fb..29081f01b26a 100644 --- a/src/test/java/com/thealgorithms/maths/BinomialCoefficientTest.java +++ b/src/test/java/com/thealgorithms/maths/BinomialCoefficientTest.java @@ -1,6 +1,7 @@ package com.thealgorithms.maths; import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; import org.junit.jupiter.api.Test; @@ -12,5 +13,14 @@ void testBinomialCoefficient() { assertEquals(792, BinomialCoefficient.binomialCoefficient(12, 5)); assertEquals(84, BinomialCoefficient.binomialCoefficient(9, 3)); assertEquals(1, BinomialCoefficient.binomialCoefficient(17, 17)); + assertEquals(0, BinomialCoefficient.binomialCoefficient(5, 6)); + assertEquals(1, BinomialCoefficient.binomialCoefficient(0, 0)); + } + + @Test + void testNegativeInputs() { + assertThrows(IllegalArgumentException.class, () -> BinomialCoefficient.binomialCoefficient(5, -1)); + assertThrows(IllegalArgumentException.class, () -> BinomialCoefficient.binomialCoefficient(-1, 5)); + assertThrows(IllegalArgumentException.class, () -> BinomialCoefficient.binomialCoefficient(-5, -2)); } } From 0a76bf8db406f8c6b6569cd83bfc31b3e118460f Mon Sep 17 00:00:00 2001 From: Hardik K Date: Thu, 5 Nov 2026 23:57:49 +0530 Subject: [PATCH 74/92] fix(searches): fix out-of-bounds in single-row and single-column in BinarySearch2dArray (#7724) --- .../searches/BinarySearch2dArray.java | 9 +++- .../searches/BinarySearch2dArrayTest.java | 53 ++++++++++++++++++- 2 files changed, 58 insertions(+), 4 deletions(-) diff --git a/src/main/java/com/thealgorithms/searches/BinarySearch2dArray.java b/src/main/java/com/thealgorithms/searches/BinarySearch2dArray.java index aa938447b864..317db0dead05 100644 --- a/src/main/java/com/thealgorithms/searches/BinarySearch2dArray.java +++ b/src/main/java/com/thealgorithms/searches/BinarySearch2dArray.java @@ -28,13 +28,13 @@ private BinarySearch2dArray() { * @return An array containing the row and column indices of the target, or [-1, * -1] if the target is not found. */ - static int[] binarySearch(int[][] arr, int target) { + public static int[] binarySearch(int[][] arr, int target) { int rowCount = arr.length; int colCount = arr[0].length; // Edge case: If there's only one row, search that row directly. if (rowCount == 1) { - return binarySearch(arr, target, 0, 0, colCount); + return binarySearch(arr, target, 0, 0, colCount - 1); } // Set initial boundaries for binary search on rows. @@ -70,6 +70,11 @@ else if (arr[midRow][midCol] < target) { return new int[] {endRow, midCol}; } + // Edge case: If there is only one column, target cannot be outside midCol. + if (colCount == 1) { + return new int[] {-1, -1}; + } + // If target is smaller than the element in the left of startRow, perform a // binary search on the left of startRow. if (target <= arr[startRow][midCol - 1]) { diff --git a/src/test/java/com/thealgorithms/searches/BinarySearch2dArrayTest.java b/src/test/java/com/thealgorithms/searches/BinarySearch2dArrayTest.java index dec2c86de9c7..236e1be5cc23 100644 --- a/src/test/java/com/thealgorithms/searches/BinarySearch2dArrayTest.java +++ b/src/test/java/com/thealgorithms/searches/BinarySearch2dArrayTest.java @@ -1,5 +1,6 @@ package com.thealgorithms.searches; +import static org.junit.jupiter.api.Assertions.assertArrayEquals; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertThrows; @@ -84,7 +85,7 @@ public void binarySearch2dArrayTestLowerSide() { // valid test case public void binarySearch2dArrayTestNotFound() { int[][] arr = {{1, 2, 3, 4}, {5, 6, 7, 8}, {9, 10, 11, 12}}; - int target = 101; + int target = 100; int[] ans = BinarySearch2dArray.binarySearch(arr, target); System.out.println(Arrays.toString(ans)); @@ -93,7 +94,7 @@ public void binarySearch2dArrayTestNotFound() { } /** - * Test if the method works with input arrays consisting only of one row. + * Test if the method works with an array that only has one row. */ @Test public void binarySearch2dArrayTestOneRow() { @@ -154,4 +155,52 @@ public void binarySearch2dArrayTestEmptyArray() { // Assert that an empty array is not valid input for the method. assertThrows(ArrayIndexOutOfBoundsException.class, () -> BinarySearch2dArray.binarySearch(arr, target)); } + + @Test + public void binarySearch2dArrayTestSingleRowTargetNotFoundGreater() { + int[][] arr = {{1, 2, 3, 4}}; + int target = 10; + int[] ans = BinarySearch2dArray.binarySearch(arr, target); + assertArrayEquals(new int[] {-1, -1}, ans); + } + + @Test + public void binarySearch2dArrayTestSingleRowTargetNotFoundSmaller() { + int[][] arr = {{1, 2, 3, 4}}; + int target = 0; + int[] ans = BinarySearch2dArray.binarySearch(arr, target); + assertArrayEquals(new int[] {-1, -1}, ans); + } + + @Test + public void binarySearch2dArrayTestSingleColumnPresent() { + int[][] arr = {{1}, {3}, {5}}; + int target = 3; + int[] ans = BinarySearch2dArray.binarySearch(arr, target); + assertArrayEquals(new int[] {1, 0}, ans); + } + + @Test + public void binarySearch2dArrayTestSingleColumnNotFound() { + int[][] arr = {{1}, {3}, {5}}; + int target = 4; + int[] ans = BinarySearch2dArray.binarySearch(arr, target); + assertArrayEquals(new int[] {-1, -1}, ans); + } + + @Test + public void binarySearch2dArrayTestSingleElementPresent() { + int[][] arr = {{42}}; + int target = 42; + int[] ans = BinarySearch2dArray.binarySearch(arr, target); + assertArrayEquals(new int[] {0, 0}, ans); + } + + @Test + public void binarySearch2dArrayTestSingleElementNotFound() { + int[][] arr = {{42}}; + int target = 10; + int[] ans = BinarySearch2dArray.binarySearch(arr, target); + assertArrayEquals(new int[] {-1, -1}, ans); + } } From 8b19b878dbeb1caf06fc41d86c8c07c162bc69a2 Mon Sep 17 00:00:00 2001 From: Bhumit Peswani Date: Fri, 6 Nov 2026 02:25:37 +0530 Subject: [PATCH 75/92] fix(dynamicprogramming): handle n=0 and negative inputs safely in CatalanNumber (#7731) --- .../thealgorithms/dynamicprogramming/CatalanNumber.java | 8 ++++++++ .../dynamicprogramming/CatalanNumberTest.java | 8 ++++++++ 2 files changed, 16 insertions(+) diff --git a/src/main/java/com/thealgorithms/dynamicprogramming/CatalanNumber.java b/src/main/java/com/thealgorithms/dynamicprogramming/CatalanNumber.java index d01066f611bd..b21beafba746 100644 --- a/src/main/java/com/thealgorithms/dynamicprogramming/CatalanNumber.java +++ b/src/main/java/com/thealgorithms/dynamicprogramming/CatalanNumber.java @@ -21,8 +21,16 @@ private CatalanNumber() { * n > 50, BigInteger class should be used instead long * * @return catalanArray[n] the nth Catalan number + * @throws IllegalArgumentException if n is negative */ static long findNthCatalan(int n) { + if (n < 0) { + throw new IllegalArgumentException("n must be non-negative"); + } + if (n <= 1) { + return 1; + } + // Array to store the results of subproblems i.e Catalan numbers from [1...n-1] long[] catalanArray = new long[n + 1]; diff --git a/src/test/java/com/thealgorithms/dynamicprogramming/CatalanNumberTest.java b/src/test/java/com/thealgorithms/dynamicprogramming/CatalanNumberTest.java index a065bb8c2a10..08dcde5decb6 100644 --- a/src/test/java/com/thealgorithms/dynamicprogramming/CatalanNumberTest.java +++ b/src/test/java/com/thealgorithms/dynamicprogramming/CatalanNumberTest.java @@ -1,6 +1,7 @@ package com.thealgorithms.dynamicprogramming; import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; import org.junit.jupiter.api.Test; @@ -8,7 +9,14 @@ public class CatalanNumberTest { @Test public void testCatalanNumber() { + assertEquals(1, CatalanNumber.findNthCatalan(0)); + assertEquals(1, CatalanNumber.findNthCatalan(1)); assertEquals(42, CatalanNumber.findNthCatalan(5)); assertEquals(16796, CatalanNumber.findNthCatalan(10)); } + + @Test + public void testNegativeInput() { + assertThrows(IllegalArgumentException.class, () -> CatalanNumber.findNthCatalan(-1)); + } } From 1e59594d8dee696a85cad5561cc6a533b6824930 Mon Sep 17 00:00:00 2001 From: Nithin U <106614289+NithinU2802@users.noreply.github.com> Date: Sat, 7 Nov 2026 15:36:30 +0530 Subject: [PATCH 76/92] To Fix maze recursion boundary validation with code improvements (#7672) * HeavyLightDecomposition Update * HeavyLightDecompositionTest Update * Update DIRECTORY.md * Improving Code Coverage Update * Format Update * Format Update * Format code with clang-format * Fix Multiple Variable Declarations * Multiple Variable Declarations * Build Failure Update * Revert Changes * New Line Update * Array to List Conversion * fix: handle maze boundaries with validation and improvements * fix: to update lint issue * Patch: to improve test coverage * test: to avoid Infer null dereference warning * patch: to improve test coverage --- .../backtracking/MazeRecursion.java | 162 +++++++++--------- .../backtracking/MazeRecursionTest.java | 99 +++++++++++ 2 files changed, 183 insertions(+), 78 deletions(-) diff --git a/src/main/java/com/thealgorithms/backtracking/MazeRecursion.java b/src/main/java/com/thealgorithms/backtracking/MazeRecursion.java index 8247172e7ee0..00c3fedca71f 100644 --- a/src/main/java/com/thealgorithms/backtracking/MazeRecursion.java +++ b/src/main/java/com/thealgorithms/backtracking/MazeRecursion.java @@ -4,122 +4,128 @@ * This class contains methods to solve a maze using recursive backtracking. * The maze is represented as a 2D array where walls, paths, and visited/dead * ends are marked with different integers. - * - * The goal is to find a path from a starting position to the target position - * (map[6][5]) while navigating through the maze. */ public final class MazeRecursion { + private static final int[][] FIRST_STRATEGY_DIRECTIONS = {{1, 0}, {0, 1}, {-1, 0}, {0, -1}}; + private static final int[][] SECOND_STRATEGY_DIRECTIONS = {{-1, 0}, {0, 1}, {1, 0}, {0, -1}}; private MazeRecursion() { } /** - * This method solves the maze using the "down -> right -> up -> left" - * movement strategy. + * Solves the maze using the "down -> right -> up -> left" movement strategy, + * starting at (1, 1) and targeting (6, 5). * - * @param map The 2D array representing the maze (walls, paths, etc.) - * @return The solved maze with paths marked, or null if no solution exists. + * @param map the 2D array representing the maze (walls, paths, etc.) + * @return the solved maze with paths marked, or null if no solution exists or a fixed endpoint is outside the maze + * @throws IllegalArgumentException if the maze is null, empty, or not rectangular */ public static int[][] solveMazeUsingFirstStrategy(int[][] map) { - if (setWay(map, 1, 1)) { + validateMaze(map); + if (!isInBounds(map, 1, 1) || !isInBounds(map, 6, 5)) { + return null; + } + if (map[6][5] == 2) { return map; } - return null; + return solve(map, 1, 1, 6, 5, FIRST_STRATEGY_DIRECTIONS) ? map : null; } /** - * This method solves the maze using the "up -> right -> down -> left" - * movement strategy. + * Solves the maze using the "up -> right -> down -> left" movement strategy, + * starting at (1, 1) and targeting (6, 5). * - * @param map The 2D array representing the maze (walls, paths, etc.) - * @return The solved maze with paths marked, or null if no solution exists. + * @param map the 2D array representing the maze (walls, paths, etc.) + * @return the solved maze with paths marked, or null if no solution exists or a fixed endpoint is outside the maze + * @throws IllegalArgumentException if the maze is null, empty, or not rectangular */ public static int[][] solveMazeUsingSecondStrategy(int[][] map) { - if (setWay2(map, 1, 1)) { + validateMaze(map); + if (!isInBounds(map, 1, 1) || !isInBounds(map, 6, 5)) { + return null; + } + if (map[6][5] == 2) { return map; } - return null; + return solve(map, 1, 1, 6, 5, SECOND_STRATEGY_DIRECTIONS) ? map : null; } /** - * Attempts to find a path through the maze using a "down -> right -> up -> left" - * movement strategy. The path is marked with '2' for valid paths and '3' for dead ends. + * Solves the maze using the "down -> right -> up -> left" movement strategy. * - * @param map The 2D array representing the maze (walls, paths, etc.) - * @param i The current x-coordinate of the ball (row index) - * @param j The current y-coordinate of the ball (column index) - * @return True if a path is found to (6,5), otherwise false + * @param map the 2D array representing the maze (0 = open, non-zero = blocked) + * @param startRow the starting row + * @param startColumn the starting column + * @param goalRow the goal row + * @param goalColumn the goal column + * @return the solved maze with paths marked, or null if no solution exists + * @throws IllegalArgumentException if the maze is null, empty, not rectangular, + * or a coordinate is outside the maze */ - private static boolean setWay(int[][] map, int i, int j) { - if (map[6][5] == 2) { - return true; + public static int[][] solveMazeUsingFirstStrategy(int[][] map, int startRow, int startColumn, int goalRow, int goalColumn) { + validateCoordinates(map, startRow, startColumn, goalRow, goalColumn); + return solve(map, startRow, startColumn, goalRow, goalColumn, FIRST_STRATEGY_DIRECTIONS) ? map : null; + } + + /** + * Solves the maze using the "up -> right -> down -> left" movement strategy. + * + * @param map the 2D array representing the maze (0 = open, non-zero = blocked) + * @param startRow the starting row + * @param startColumn the starting column + * @param goalRow the goal row + * @param goalColumn the goal column + * @return the solved maze with paths marked, or null if no solution exists + * @throws IllegalArgumentException if the maze is null, empty, not rectangular, + * or a coordinate is outside the maze + */ + public static int[][] solveMazeUsingSecondStrategy(int[][] map, int startRow, int startColumn, int goalRow, int goalColumn) { + validateCoordinates(map, startRow, startColumn, goalRow, goalColumn); + return solve(map, startRow, startColumn, goalRow, goalColumn, SECOND_STRATEGY_DIRECTIONS) ? map : null; + } + + private static boolean solve(int[][] map, int row, int column, int goalRow, int goalColumn, int[][] directions) { + if (!isInBounds(map, row, column) || map[row][column] != 0) { + return false; } - // If the current position is unvisited (0), explore it - if (map[i][j] == 0) { - // Mark the current position as '2' - map[i][j] = 2; + map[row][column] = 2; + if (row == goalRow && column == goalColumn) { + return true; + } - // Move down - if (setWay(map, i + 1, j)) { - return true; - } - // Move right - else if (setWay(map, i, j + 1)) { - return true; - } - // Move up - else if (setWay(map, i - 1, j)) { - return true; - } - // Move left - else if (setWay(map, i, j - 1)) { + for (int[] direction : directions) { + if (solve(map, row + direction[0], column + direction[1], goalRow, goalColumn, directions)) { return true; } - - map[i][j] = 3; // Mark as dead end (3) if no direction worked - return false; } + + map[row][column] = 3; return false; } - /** - * Attempts to find a path through the maze using an alternative movement - * strategy "up -> right -> down -> left". - * - * @param map The 2D array representing the maze (walls, paths, etc.) - * @param i The current x-coordinate of the ball (row index) - * @param j The current y-coordinate of the ball (column index) - * @return True if a path is found to (6,5), otherwise false - */ - private static boolean setWay2(int[][] map, int i, int j) { - if (map[6][5] == 2) { - return true; + private static int validateMaze(int[][] map) { + if (map == null || map.length == 0 || map[0] == null || map[0].length == 0) { + throw new IllegalArgumentException("Maze must not be null or empty."); } - if (map[i][j] == 0) { - map[i][j] = 2; - - // Move up - if (setWay2(map, i - 1, j)) { - return true; - } - // Move right - else if (setWay2(map, i, j + 1)) { - return true; - } - // Move down - else if (setWay2(map, i + 1, j)) { - return true; - } - // Move left - else if (setWay2(map, i, j - 1)) { - return true; + int columnCount = map[0].length; + for (int[] row : map) { + if (row == null || row.length != columnCount) { + throw new IllegalArgumentException("Maze must be a non-empty rectangular matrix."); } + } + return columnCount; + } - map[i][j] = 3; // Mark as dead end (3) if no direction worked - return false; + private static void validateCoordinates(int[][] map, int startRow, int startColumn, int goalRow, int goalColumn) { + int columnCount = validateMaze(map); + if (startRow < 0 || startRow >= map.length || startColumn < 0 || startColumn >= columnCount || goalRow < 0 || goalRow >= map.length || goalColumn < 0 || goalColumn >= columnCount) { + throw new IllegalArgumentException("Start and goal coordinates must be inside the maze."); } - return false; + } + + private static boolean isInBounds(int[][] map, int row, int column) { + return row >= 0 && row < map.length && column >= 0 && column < map[row].length; } } diff --git a/src/test/java/com/thealgorithms/backtracking/MazeRecursionTest.java b/src/test/java/com/thealgorithms/backtracking/MazeRecursionTest.java index b8e77fb38bad..7d8a0c66c262 100644 --- a/src/test/java/com/thealgorithms/backtracking/MazeRecursionTest.java +++ b/src/test/java/com/thealgorithms/backtracking/MazeRecursionTest.java @@ -1,6 +1,9 @@ package com.thealgorithms.backtracking; import static org.junit.jupiter.api.Assertions.assertArrayEquals; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertSame; +import static org.junit.jupiter.api.Assertions.assertThrows; import org.junit.jupiter.api.Test; @@ -10,6 +13,102 @@ */ public class MazeRecursionTest { + @Test + public void testSmallMazeWithExplicitCoordinates() { + int[][] firstStrategyMaze = {{0, 0}, {0, 0}}; + int[][] secondStrategyMaze = {{0, 0}, {0, 0}}; + + assertArrayEquals(new int[][] {{2, 0}, {2, 2}}, MazeRecursion.solveMazeUsingFirstStrategy(firstStrategyMaze, 0, 0, 1, 1)); + assertArrayEquals(new int[][] {{2, 2}, {0, 2}}, MazeRecursion.solveMazeUsingSecondStrategy(secondStrategyMaze, 0, 0, 1, 1)); + } + + @Test + public void testLegacyMethodsReturnNullWhenFixedGoalIsOutsideMaze() { + assertNull(MazeRecursion.solveMazeUsingFirstStrategy(new int[1][1])); + assertNull(MazeRecursion.solveMazeUsingSecondStrategy(new int[1][1])); + assertNull(MazeRecursion.solveMazeUsingFirstStrategy(new int[2][2])); + assertNull(MazeRecursion.solveMazeUsingSecondStrategy(new int[2][2])); + } + + @Test + public void testLegacyMethodsReturnNullWhenFixedGoalRowOrColumnIsOutsideMaze() { + assertNull(MazeRecursion.solveMazeUsingFirstStrategy(new int[7][5])); + assertNull(MazeRecursion.solveMazeUsingSecondStrategy(new int[6][6])); + } + + @Test + public void testLegacyMethodsReturnNullWhenNoPathExists() { + int[][] firstStrategyMaze = new int[7][6]; + int[][] secondStrategyMaze = new int[7][6]; + firstStrategyMaze[1][1] = 1; + secondStrategyMaze[1][1] = 1; + + assertNull(MazeRecursion.solveMazeUsingFirstStrategy(firstStrategyMaze)); + assertNull(MazeRecursion.solveMazeUsingSecondStrategy(secondStrategyMaze)); + } + + @Test + public void testLegacyMethodsAcceptAlreadyMarkedGoal() { + int[][] firstStrategyMaze = new int[7][6]; + int[][] secondStrategyMaze = new int[7][6]; + firstStrategyMaze[6][5] = 2; + secondStrategyMaze[6][5] = 2; + + assertSame(firstStrategyMaze, MazeRecursion.solveMazeUsingFirstStrategy(firstStrategyMaze)); + assertSame(secondStrategyMaze, MazeRecursion.solveMazeUsingSecondStrategy(secondStrategyMaze)); + } + + @Test + public void testNoPathExistsWithExplicitCoordinates() { + int[][] maze = {{0, 1}, {1, 0}}; + + assertNull(MazeRecursion.solveMazeUsingFirstStrategy(maze, 0, 0, 1, 1)); + } + + @Test + public void testExplicitCoordinatesMustBeInsideMaze() { + assertThrows(IllegalArgumentException.class, () -> MazeRecursion.solveMazeUsingFirstStrategy(new int[2][2], 0, 0, 2, 1)); + } + + @Test + public void testEachStartAndGoalCoordinateMustBeInsideMaze() { + int[][] maze = new int[2][2]; + + assertThrows(IllegalArgumentException.class, () -> MazeRecursion.solveMazeUsingFirstStrategy(maze, -1, 0, 1, 1)); + assertThrows(IllegalArgumentException.class, () -> MazeRecursion.solveMazeUsingFirstStrategy(maze, 2, 0, 1, 1)); + assertThrows(IllegalArgumentException.class, () -> MazeRecursion.solveMazeUsingFirstStrategy(maze, 0, -1, 1, 1)); + assertThrows(IllegalArgumentException.class, () -> MazeRecursion.solveMazeUsingFirstStrategy(maze, 0, 2, 1, 1)); + assertThrows(IllegalArgumentException.class, () -> MazeRecursion.solveMazeUsingFirstStrategy(maze, 0, 0, -1, 1)); + assertThrows(IllegalArgumentException.class, () -> MazeRecursion.solveMazeUsingFirstStrategy(maze, 0, 0, 2, 1)); + assertThrows(IllegalArgumentException.class, () -> MazeRecursion.solveMazeUsingFirstStrategy(maze, 0, 0, 1, -1)); + assertThrows(IllegalArgumentException.class, () -> MazeRecursion.solveMazeUsingFirstStrategy(maze, 0, 0, 1, 2)); + } + + @Test + public void testMazeMustNotBeNullOrEmpty() { + assertThrows(IllegalArgumentException.class, () -> MazeRecursion.solveMazeUsingFirstStrategy(null)); + assertThrows(IllegalArgumentException.class, () -> MazeRecursion.solveMazeUsingFirstStrategy(new int[0][0])); + assertThrows(IllegalArgumentException.class, () -> MazeRecursion.solveMazeUsingFirstStrategy(new int[][] {null})); + assertThrows(IllegalArgumentException.class, () -> MazeRecursion.solveMazeUsingFirstStrategy(new int[][] {new int[0]})); + } + + @Test + public void testMazeMustBeRectangular() { + assertThrows(IllegalArgumentException.class, () -> MazeRecursion.solveMazeUsingFirstStrategy(new int[][] {{0, 0}, {0}}, 0, 0, 1, 0)); + } + + @Test + public void testBlockedStartAndGoalHaveNoSolution() { + assertNull(MazeRecursion.solveMazeUsingFirstStrategy(new int[][] {{1, 0}, {0, 0}}, 0, 0, 1, 1)); + assertNull(MazeRecursion.solveMazeUsingSecondStrategy(new int[][] {{0, 0}, {0, 1}}, 0, 0, 1, 1)); + } + + @Test + public void testOpenSingleCellMazeIsAlreadySolved() { + assertArrayEquals(new int[][] {{2}}, MazeRecursion.solveMazeUsingFirstStrategy(new int[][] {{0}}, 0, 0, 0, 0)); + assertArrayEquals(new int[][] {{2}}, MazeRecursion.solveMazeUsingSecondStrategy(new int[][] {{0}}, 0, 0, 0, 0)); + } + @Test public void testSolveMazeUsingFirstAndSecondStrategy() { int[][] map = new int[8][7]; From dbcf156bac36bbf5669717e5073fc658d94ae033 Mon Sep 17 00:00:00 2001 From: Bhumit Peswani Date: Sun, 8 Nov 2026 15:14:26 +0530 Subject: [PATCH 77/92] fix(maths): prevent intermediate integer overflow in CatalanNumbers (#7732) --- .../thealgorithms/maths/CatalanNumbers.java | 25 +++++++++++-------- .../maths/CatalanNumbersTest.java | 6 +++-- 2 files changed, 19 insertions(+), 12 deletions(-) diff --git a/src/main/java/com/thealgorithms/maths/CatalanNumbers.java b/src/main/java/com/thealgorithms/maths/CatalanNumbers.java index 387756bdfa0c..2f304d1c2b3c 100644 --- a/src/main/java/com/thealgorithms/maths/CatalanNumbers.java +++ b/src/main/java/com/thealgorithms/maths/CatalanNumbers.java @@ -1,38 +1,43 @@ package com.thealgorithms.maths; +import java.math.BigInteger; + /** * Calculate Catalan Numbers */ public final class CatalanNumbers { + private static final int MAX_SUPPORTED_INDEX = 35; + private CatalanNumbers() { } /** - * Calculate the nth Catalan number using a recursive formula. + * Calculate the nth Catalan number using the factorial formula. * * @param n the index of the Catalan number to compute * @return the nth Catalan number + * @throws IllegalArgumentException if n is negative or exceeds the maximum supported index for long */ public static long catalan(final int n) { if (n < 0) { throw new IllegalArgumentException("Index must be non-negative"); } - return factorial(2 * n) / (factorial(n + 1) * factorial(n)); + if (n > MAX_SUPPORTED_INDEX) { + throw new IllegalArgumentException("Index exceeds maximum supported value for long"); + } + return factorial(2 * n).divide(factorial(n + 1).multiply(factorial(n))).longValueExact(); } /** - * Calculate the factorial of a number. + * Calculate the factorial of a number using BigInteger to prevent integer overflow. * * @param n the number to compute the factorial for - * @return the factorial of n + * @return the factorial of n as BigInteger */ - private static long factorial(final int n) { - if (n == 0 || n == 1) { - return 1; - } - long result = 1; + private static BigInteger factorial(final int n) { + BigInteger result = BigInteger.ONE; for (int i = 2; i <= n; i++) { - result *= i; + result = result.multiply(BigInteger.valueOf(i)); } return result; } diff --git a/src/test/java/com/thealgorithms/maths/CatalanNumbersTest.java b/src/test/java/com/thealgorithms/maths/CatalanNumbersTest.java index 2248ffd93732..cf8b1ddabc98 100644 --- a/src/test/java/com/thealgorithms/maths/CatalanNumbersTest.java +++ b/src/test/java/com/thealgorithms/maths/CatalanNumbersTest.java @@ -19,7 +19,8 @@ class CatalanNumbersTest { * [input number, expected Catalan number for that input] */ static Stream catalanNumbersProvider() { - return Stream.of(new Object[] {0, 1}, new Object[] {1, 1}, new Object[] {2, 2}, new Object[] {3, 5}, new Object[] {4, 14}, new Object[] {5, 42}, new Object[] {6, 132}, new Object[] {7, 429}, new Object[] {8, 1430}, new Object[] {9, 4862}, new Object[] {10, 16796}); + return Stream.of(new Object[] {0, 1L}, new Object[] {1, 1L}, new Object[] {2, 2L}, new Object[] {3, 5L}, new Object[] {4, 14L}, new Object[] {5, 42L}, new Object[] {6, 132L}, new Object[] {7, 429L}, new Object[] {8, 1430L}, new Object[] {9, 4862L}, new Object[] {10, 16796L}, + new Object[] {11, 58786L}, new Object[] {15, 9694845L}, new Object[] {35, 3116285494907301262L}); } /** @@ -28,7 +29,7 @@ static Stream catalanNumbersProvider() { */ @ParameterizedTest @MethodSource("catalanNumbersProvider") - void testCatalanNumbers(int input, int expected) { + void testCatalanNumbers(int input, long expected) { assertEquals(expected, CatalanNumbers.catalan(input), () -> String.format("Catalan number for input %d should be %d", input, expected)); } @@ -39,5 +40,6 @@ void testCatalanNumbers(int input, int expected) { void testIllegalInput() { assertThrows(IllegalArgumentException.class, () -> CatalanNumbers.catalan(-1)); assertThrows(IllegalArgumentException.class, () -> CatalanNumbers.catalan(-5)); + assertThrows(IllegalArgumentException.class, () -> CatalanNumbers.catalan(36)); } } From defae1e45c21f6e0fe0dca98fbbcdaca40468427 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 9 Nov 2026 23:54:57 +0200 Subject: [PATCH 78/92] chore(deps): bump com.puppycrawl.tools:checkstyle from 14.3.0 to 14.4.0 (#7744) Bumps [com.puppycrawl.tools:checkstyle](https://github.com/checkstyle/checkstyle) from 14.3.0 to 14.4.0. - [Release notes](https://github.com/checkstyle/checkstyle/releases) - [Commits](https://github.com/checkstyle/checkstyle/compare/checkstyle-14.3.0...checkstyle-14.4.0) --- updated-dependencies: - dependency-name: com.puppycrawl.tools:checkstyle dependency-version: 14.4.0 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index d7c7a0849fb8..2af08520649a 100644 --- a/pom.xml +++ b/pom.xml @@ -112,7 +112,7 @@ com.puppycrawl.tools checkstyle - 14.3.0 + 14.4.0 From b2af1db6dcae46521e97a6331eae8cea61933080 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 10 Nov 2026 22:51:17 +0100 Subject: [PATCH 79/92] chore(deps): bump github/codeql-action from 4.39.1 to 4.39.2 in /.github/workflows (#7745) chore(deps): bump github/codeql-action in /.github/workflows Bumps [github/codeql-action](https://github.com/github/codeql-action) from 4.39.1 to 4.39.2. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](https://github.com/github/codeql-action/compare/v4.39.1...v4.39.2) --- updated-dependencies: - dependency-name: github/codeql-action dependency-version: 4.39.2 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/codeql.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index d9d9ed1e54e9..b28bc592e849 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -30,7 +30,7 @@ jobs: distribution: 'temurin' - name: Initialize CodeQL - uses: github/codeql-action/init@v4.39.1 + uses: github/codeql-action/init@v4.39.2 with: languages: 'java-kotlin' @@ -38,7 +38,7 @@ jobs: run: mvn --batch-mode --update-snapshots verify - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4.39.1 + uses: github/codeql-action/analyze@v4.39.2 with: category: "/language:java-kotlin" @@ -55,12 +55,12 @@ jobs: uses: actions/checkout@v7 - name: Initialize CodeQL - uses: github/codeql-action/init@v4.39.1 + uses: github/codeql-action/init@v4.39.2 with: languages: 'actions' - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4.39.1 + uses: github/codeql-action/analyze@v4.39.2 with: category: "/language:actions" ... From c3ce690a8a8f284d380a4c29a92fe43a9730f3d2 Mon Sep 17 00:00:00 2001 From: kevin <5299031+kevin9327@users.noreply.github.com> Date: Thu, 12 Nov 2026 06:28:31 +0900 Subject: [PATCH 80/92] fix(conversions): reject non-hex digits in HexToOct.hexToDecimal (#7748) --- src/main/java/com/thealgorithms/conversions/HexToOct.java | 4 ++++ .../java/com/thealgorithms/conversions/HexToOctTest.java | 8 ++++++++ 2 files changed, 12 insertions(+) diff --git a/src/main/java/com/thealgorithms/conversions/HexToOct.java b/src/main/java/com/thealgorithms/conversions/HexToOct.java index d3a672d37424..ef696d305ee4 100644 --- a/src/main/java/com/thealgorithms/conversions/HexToOct.java +++ b/src/main/java/com/thealgorithms/conversions/HexToOct.java @@ -14,6 +14,7 @@ private HexToOct() { * * @param hex The Hexadecimal number as a String. * @return The Decimal equivalent as an integer. + * @throws IllegalArgumentException if the string contains a character that is not a hexadecimal digit */ public static int hexToDecimal(String hex) { String hexDigits = "0123456789ABCDEF"; @@ -23,6 +24,9 @@ public static int hexToDecimal(String hex) { for (int i = 0; i < hex.length(); i++) { char hexChar = hex.charAt(i); int digitValue = hexDigits.indexOf(hexChar); + if (digitValue == -1) { + throw new IllegalArgumentException("Invalid hexadecimal digit: " + hexChar); + } decimalValue = 16 * decimalValue + digitValue; } diff --git a/src/test/java/com/thealgorithms/conversions/HexToOctTest.java b/src/test/java/com/thealgorithms/conversions/HexToOctTest.java index b3f94b19b6e6..5793b640316b 100644 --- a/src/test/java/com/thealgorithms/conversions/HexToOctTest.java +++ b/src/test/java/com/thealgorithms/conversions/HexToOctTest.java @@ -1,6 +1,7 @@ package com.thealgorithms.conversions; import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; import org.junit.jupiter.api.Test; @@ -30,4 +31,11 @@ public void testHexToOctal() { assertEquals(0, HexToOct.hexToOctal("0")); assertEquals(7777, HexToOct.hexToOctal("FFF")); } + + @Test + public void testInvalidHexDigitThrows() { + assertThrows(IllegalArgumentException.class, () -> HexToOct.hexToDecimal("1G")); + assertThrows(IllegalArgumentException.class, () -> HexToOct.hexToDecimal("0x1A")); + assertThrows(IllegalArgumentException.class, () -> HexToOct.hexToOctal("Z")); + } } From c46808958406c3b74726542fc9ad7e8038fe924e Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 11 Nov 2026 23:54:41 +0200 Subject: [PATCH 81/92] chore(deps): bump actions/setup-java from 6.1.0 to 6.2.0 in /.github/workflows (#7749) chore(deps): bump actions/setup-java in /.github/workflows Bumps [actions/setup-java](https://github.com/actions/setup-java) from 6.1.0 to 6.2.0. - [Release notes](https://github.com/actions/setup-java/releases) - [Commits](https://github.com/actions/setup-java/compare/v6.1.0...v6.2.0) --- updated-dependencies: - dependency-name: actions/setup-java dependency-version: 6.2.0 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/build.yml | 2 +- .github/workflows/codeql.yml | 2 +- .github/workflows/infer.yml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 38d1471dcf13..e83512b89972 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -10,7 +10,7 @@ jobs: steps: - uses: actions/checkout@v7 - name: Set up JDK - uses: actions/setup-java@v6.1.0 + uses: actions/setup-java@v6.2.0 with: java-version: 21 distribution: 'temurin' diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index b28bc592e849..88c7618dc4f7 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -24,7 +24,7 @@ jobs: uses: actions/checkout@v7 - name: Set up JDK - uses: actions/setup-java@v6.1.0 + uses: actions/setup-java@v6.2.0 with: java-version: 21 distribution: 'temurin' diff --git a/.github/workflows/infer.yml b/.github/workflows/infer.yml index 962c090ee699..0b7b1209e4a8 100644 --- a/.github/workflows/infer.yml +++ b/.github/workflows/infer.yml @@ -18,7 +18,7 @@ jobs: - uses: actions/checkout@v7 - name: Set up JDK - uses: actions/setup-java@v6.1.0 + uses: actions/setup-java@v6.2.0 with: java-version: 21 distribution: 'temurin' From 02ebe075d60622e63f6807a56907e99795e89ffe Mon Sep 17 00:00:00 2001 From: Aman Mohamed Ali <69119173+spidervirus@users.noreply.github.com> Date: Thu, 12 Nov 2026 13:21:37 +0400 Subject: [PATCH 82/92] fix(maths): correct coordinate subtraction in DistanceFormula.euclideanDistance (#7747) --- .../thealgorithms/maths/DistanceFormula.java | 2 +- .../maths/DistanceFormulaTest.java | 21 ++++++++++++++++--- 2 files changed, 19 insertions(+), 4 deletions(-) diff --git a/src/main/java/com/thealgorithms/maths/DistanceFormula.java b/src/main/java/com/thealgorithms/maths/DistanceFormula.java index f7e2c7629551..b6c09c2cdb82 100644 --- a/src/main/java/com/thealgorithms/maths/DistanceFormula.java +++ b/src/main/java/com/thealgorithms/maths/DistanceFormula.java @@ -6,7 +6,7 @@ private DistanceFormula() { public static double euclideanDistance(double x1, double y1, double x2, double y2) { double dX = Math.pow(x2 - x1, 2); - double dY = Math.pow(y2 - x1, 2); + double dY = Math.pow(y2 - y1, 2); return Math.sqrt(dX + dY); } diff --git a/src/test/java/com/thealgorithms/maths/DistanceFormulaTest.java b/src/test/java/com/thealgorithms/maths/DistanceFormulaTest.java index 66f3b7b03938..d761326558a4 100644 --- a/src/test/java/com/thealgorithms/maths/DistanceFormulaTest.java +++ b/src/test/java/com/thealgorithms/maths/DistanceFormulaTest.java @@ -14,17 +14,32 @@ void euclideanTest1() { @Test void euclideanTest2() { - Assertions.assertEquals(7.0710678118654755, DistanceFormula.euclideanDistance(1, 3, 8, 0)); + Assertions.assertEquals(7.615773105863909, DistanceFormula.euclideanDistance(1, 3, 8, 0)); } @Test void euclideanTest3() { - Assertions.assertEquals(110.91911467371168, DistanceFormula.euclideanDistance(2.4, 9.1, 55.1, 100)); + Assertions.assertEquals(105.07188015829927, DistanceFormula.euclideanDistance(2.4, 9.1, 55.1, 100)); } @Test void euclideanTest4() { - Assertions.assertEquals(19022.067605809836, DistanceFormula.euclideanDistance(1000, 13, 20000, 84)); + Assertions.assertEquals(19000.13265743163, DistanceFormula.euclideanDistance(1000, 13, 20000, 84)); + } + + @Test + void euclideanTestZeroDistance() { + Assertions.assertEquals(0.0, DistanceFormula.euclideanDistance(0, 0, 0, 0)); + } + + @Test + void euclideanTestPythagoreanTriple() { + Assertions.assertEquals(5.0, DistanceFormula.euclideanDistance(0, 0, 3, 4)); + } + + @Test + void euclideanTestNegativeCoordinates() { + Assertions.assertEquals(5.0, DistanceFormula.euclideanDistance(-1, -2, 2, 2)); } @Test From 3c4f19d4d847cdbee406137d6ddea88a3bcf8373 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 09:25:23 +0000 Subject: [PATCH 83/92] chore(deps): bump github/codeql-action from 4.39.2 to 4.39.3 in /.github/workflows (#7750) chore(deps): bump github/codeql-action in /.github/workflows Bumps [github/codeql-action](https://github.com/github/codeql-action) from 4.39.2 to 4.39.3. - [Release notes](https://github.com/github/codeql-action/releases) - [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md) - [Commits](https://github.com/github/codeql-action/compare/v4.39.2...v4.39.3) --- updated-dependencies: - dependency-name: github/codeql-action dependency-version: 4.39.3 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/codeql.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index 88c7618dc4f7..66d626f52876 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -30,7 +30,7 @@ jobs: distribution: 'temurin' - name: Initialize CodeQL - uses: github/codeql-action/init@v4.39.2 + uses: github/codeql-action/init@v4.39.3 with: languages: 'java-kotlin' @@ -38,7 +38,7 @@ jobs: run: mvn --batch-mode --update-snapshots verify - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4.39.2 + uses: github/codeql-action/analyze@v4.39.3 with: category: "/language:java-kotlin" @@ -55,12 +55,12 @@ jobs: uses: actions/checkout@v7 - name: Initialize CodeQL - uses: github/codeql-action/init@v4.39.2 + uses: github/codeql-action/init@v4.39.3 with: languages: 'actions' - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v4.39.2 + uses: github/codeql-action/analyze@v4.39.3 with: category: "/language:actions" ... From 07c7ea317f67fe27c6830fc2cea652c65f19f225 Mon Sep 17 00:00:00 2001 From: Hardik K Date: Thu, 12 Nov 2026 14:59:32 +0530 Subject: [PATCH 84/92] fix(searches): add null safety and empty matrix handling to RowColumnWiseSorted2dArrayBinarySearch (#7725) * fix(searches): add null safety and empty matrix handling to RowColumnWiseSorted2dArrayBinarySearch * refactor(searches): scope validation to rectangular matrices per review --- ...owColumnWiseSorted2dArrayBinarySearch.java | 6 ++- ...lumnWiseSorted2dArrayBinarySearchTest.java | 52 +++++++++++++++++++ 2 files changed, 57 insertions(+), 1 deletion(-) diff --git a/src/main/java/com/thealgorithms/searches/RowColumnWiseSorted2dArrayBinarySearch.java b/src/main/java/com/thealgorithms/searches/RowColumnWiseSorted2dArrayBinarySearch.java index ecdcd36adf21..4b66cf2a220e 100644 --- a/src/main/java/com/thealgorithms/searches/RowColumnWiseSorted2dArrayBinarySearch.java +++ b/src/main/java/com/thealgorithms/searches/RowColumnWiseSorted2dArrayBinarySearch.java @@ -20,7 +20,7 @@ * doesn't exist in the array, an array * {-1, -1} will be returned. */ -public class RowColumnWiseSorted2dArrayBinarySearch implements MatrixSearchAlgorithm { +public final class RowColumnWiseSorted2dArrayBinarySearch implements MatrixSearchAlgorithm { @Override public > int[] find(T[][] matrix, T key) { @@ -28,6 +28,10 @@ public > int[] find(T[][] matrix, T key) { } public static > int[] search(T[][] matrix, T target) { + if (matrix == null || matrix.length == 0 || matrix[0] == null || matrix[0].length == 0 || target == null) { + return new int[] {-1, -1}; + } + int rowPointer = 0; // The pointer at 0th row int colPointer = matrix[0].length - 1; // The pointer at end column diff --git a/src/test/java/com/thealgorithms/searches/RowColumnWiseSorted2dArrayBinarySearchTest.java b/src/test/java/com/thealgorithms/searches/RowColumnWiseSorted2dArrayBinarySearchTest.java index 8d1423cbeeb0..6740baeb3c89 100644 --- a/src/test/java/com/thealgorithms/searches/RowColumnWiseSorted2dArrayBinarySearchTest.java +++ b/src/test/java/com/thealgorithms/searches/RowColumnWiseSorted2dArrayBinarySearchTest.java @@ -237,4 +237,56 @@ public void rowColumnSorted2dArrayBinarySearchTestTallMatrixNotFound() { assertEquals(expected[0], ans[0]); assertEquals(expected[1], ans[1]); } + + @Test + public void testNullMatrixReturnsNotFound() { + int[] ans = RowColumnWiseSorted2dArrayBinarySearch.search(null, 5); + int[] expected = {-1, -1}; + assertEquals(expected[0], ans[0]); + assertEquals(expected[1], ans[1]); + } + + @Test + public void testEmptyMatrixReturnsNotFound() { + Integer[][] matrix = {}; + int[] ans = RowColumnWiseSorted2dArrayBinarySearch.search(matrix, 5); + int[] expected = {-1, -1}; + assertEquals(expected[0], ans[0]); + assertEquals(expected[1], ans[1]); + } + + @Test + public void testEmptyFirstRowReturnsNotFound() { + Integer[][] matrix = {{}}; + int[] ans = RowColumnWiseSorted2dArrayBinarySearch.search(matrix, 5); + int[] expected = {-1, -1}; + assertEquals(expected[0], ans[0]); + assertEquals(expected[1], ans[1]); + } + + @Test + public void testNullTargetReturnsNotFound() { + int[] ans = RowColumnWiseSorted2dArrayBinarySearch.search(WIDE_RECTANGULAR_MATRIX, null); + int[] expected = {-1, -1}; + assertEquals(expected[0], ans[0]); + assertEquals(expected[1], ans[1]); + } + + @Test + public void testNullFirstRowReturnsNotFound() { + Integer[][] matrix = {null}; + int[] ans = RowColumnWiseSorted2dArrayBinarySearch.search(matrix, 5); + int[] expected = {-1, -1}; + assertEquals(expected[0], ans[0]); + assertEquals(expected[1], ans[1]); + } + + @Test + public void testFindMethodThroughInterface() { + RowColumnWiseSorted2dArrayBinarySearch searcher = new RowColumnWiseSorted2dArrayBinarySearch(); + int[] ans = searcher.find(WIDE_RECTANGULAR_MATRIX, 35); + int[] expected = {1, 2}; + assertEquals(expected[0], ans[0]); + assertEquals(expected[1], ans[1]); + } } From e9957eaf70a4250c680be42952b96ced7859d028 Mon Sep 17 00:00:00 2001 From: S ROSHAN KUMAR Date: Fri, 13 Nov 2026 13:50:06 +0530 Subject: [PATCH 85/92] feat: add MoveZeroes algorithm with tests (#7738) feat: add move-zeroes algorithm with tests --- .../com/thealgorithms/misc/MoveZeroes.java | 28 +++++++++++++++ .../thealgorithms/misc/MoveZeroesTest.java | 36 +++++++++++++++++++ 2 files changed, 64 insertions(+) create mode 100644 src/main/java/com/thealgorithms/misc/MoveZeroes.java create mode 100644 src/test/java/com/thealgorithms/misc/MoveZeroesTest.java diff --git a/src/main/java/com/thealgorithms/misc/MoveZeroes.java b/src/main/java/com/thealgorithms/misc/MoveZeroes.java new file mode 100644 index 000000000000..31d6eb8dad98 --- /dev/null +++ b/src/main/java/com/thealgorithms/misc/MoveZeroes.java @@ -0,0 +1,28 @@ +package com.thealgorithms.misc; + +/** + * Moves all zeroes in an array to the end while maintaining the relative + * order of non-zero elements. The operation is performed in-place. + * + *

Example: [0, 1, 0, 3, 12] -> [1, 3, 12, 0, 0] + * + *

Time complexity: O(n), Space complexity: O(1) + * + * @see LeetCode #283 + */ +public final class MoveZeroes { + private MoveZeroes() { + } + + public static void moveZeroes(int[] nums) { + int insertPos = 0; + for (int num : nums) { + if (num != 0) { + nums[insertPos++] = num; + } + } + while (insertPos < nums.length) { + nums[insertPos++] = 0; + } + } +} diff --git a/src/test/java/com/thealgorithms/misc/MoveZeroesTest.java b/src/test/java/com/thealgorithms/misc/MoveZeroesTest.java new file mode 100644 index 000000000000..9c26e6b7340e --- /dev/null +++ b/src/test/java/com/thealgorithms/misc/MoveZeroesTest.java @@ -0,0 +1,36 @@ +package com.thealgorithms.misc; + +import static org.junit.jupiter.api.Assertions.assertArrayEquals; + +import org.junit.jupiter.api.Test; + +public class MoveZeroesTest { + + @Test + public void testMoveZeroes() { + int[] nums = {0, 1, 0, 3, 12}; + MoveZeroes.moveZeroes(nums); + assertArrayEquals(new int[] {1, 3, 12, 0, 0}, nums); + } + + @Test + public void testNoZeroes() { + int[] nums = {1, 2, 3}; + MoveZeroes.moveZeroes(nums); + assertArrayEquals(new int[] {1, 2, 3}, nums); + } + + @Test + public void testAllZeroes() { + int[] nums = {0, 0, 0}; + MoveZeroes.moveZeroes(nums); + assertArrayEquals(new int[] {0, 0, 0}, nums); + } + + @Test + public void testSingleElement() { + int[] nums = {0}; + MoveZeroes.moveZeroes(nums); + assertArrayEquals(new int[] {0}, nums); + } +} From 2f04e814eeb7fcf1af1c680ac29934bbb4fb23b1 Mon Sep 17 00:00:00 2001 From: hindAlsh Date: Fri, 13 Nov 2026 01:28:35 -0700 Subject: [PATCH 86/92] Add ChaCha20 stream cipher (#7754) * Add ChaCha20 stream cipher This implementation is intended for educational purposes and should not be used as a replacement for a vetted cryptographic library in production. * Test ChaCha20 implementation * Add test for ChaCha20 handling partial blocks * Refactor CONSTANTS and littleEndianInt method * Refactor ChaCha20Test for clarity and readability Refactored nonce and expected byte array initialization for clarity. Updated test methods to improve readability by reducing line breaks. --- .../com/thealgorithms/ciphers/ChaCha20.java | 136 ++++++++++++++++++ .../thealgorithms/ciphers/ChaCha20Test.java | 92 ++++++++++++ 2 files changed, 228 insertions(+) create mode 100644 src/main/java/com/thealgorithms/ciphers/ChaCha20.java create mode 100644 src/test/java/com/thealgorithms/ciphers/ChaCha20Test.java diff --git a/src/main/java/com/thealgorithms/ciphers/ChaCha20.java b/src/main/java/com/thealgorithms/ciphers/ChaCha20.java new file mode 100644 index 000000000000..5f9906d406d4 --- /dev/null +++ b/src/main/java/com/thealgorithms/ciphers/ChaCha20.java @@ -0,0 +1,136 @@ +package com.thealgorithms.ciphers; + +import java.util.Objects; + +/** + * Implements the ChaCha20 stream cipher described in RFC 8439. + * + *

This implementation is intended for educational purposes and should not + * be used as a replacement for a vetted cryptographic library in production. + * + * @see RFC 8439 + */ +public final class ChaCha20 { + + private static final int BLOCK_SIZE = 64; + private static final long MAX_COUNTER = 0xFFFF_FFFFL; + private static final int[] CONSTANTS = {0x61707865, 0x3320646e, 0x79622d32, 0x6b206574}; + + private ChaCha20() { + // Utility class + } + + /** + * Encrypts bytes with ChaCha20. Decryption uses the same operation. + * + * @param input plaintext bytes; must not be {@code null} + * @param key 32-byte key + * @param nonce 12-byte nonce + * @param initialCounter unsigned 32-bit initial block counter + * @return encrypted bytes + * @throws NullPointerException if an argument is {@code null} + * @throws IllegalArgumentException if a key, nonce, or counter is invalid, + * or the counter would overflow while processing the input + */ + public static byte[] encrypt(byte[] input, byte[] key, byte[] nonce, long initialCounter) { + validateInputs(input, key, nonce, initialCounter); + + long blockCount = (input.length + (long) BLOCK_SIZE - 1) / BLOCK_SIZE; + if (blockCount > 0 && initialCounter > MAX_COUNTER - (blockCount - 1)) { + throw new IllegalArgumentException("Counter would overflow"); + } + + byte[] output = new byte[input.length]; + for (int offset = 0; offset < input.length; offset += BLOCK_SIZE) { + long counter = initialCounter + offset / BLOCK_SIZE; + byte[] keyStream = block(key, nonce, counter); + int bytesToProcess = Math.min(BLOCK_SIZE, input.length - offset); + + for (int i = 0; i < bytesToProcess; i++) { + output[offset + i] = (byte) (input[offset + i] ^ keyStream[i]); + } + } + return output; + } + + /** + * Decrypts bytes with ChaCha20. This is identical to encryption. + * + * @param input ciphertext bytes; must not be {@code null} + * @param key 32-byte key + * @param nonce 12-byte nonce + * @param initialCounter unsigned 32-bit initial block counter + * @return decrypted bytes + */ + public static byte[] decrypt(byte[] input, byte[] key, byte[] nonce, long initialCounter) { + return encrypt(input, key, nonce, initialCounter); + } + + private static void validateInputs(byte[] input, byte[] key, byte[] nonce, long counter) { + Objects.requireNonNull(input, "input must not be null"); + Objects.requireNonNull(key, "key must not be null"); + Objects.requireNonNull(nonce, "nonce must not be null"); + + if (key.length != 32) { + throw new IllegalArgumentException("Key must be 32 bytes"); + } + if (nonce.length != 12) { + throw new IllegalArgumentException("Nonce must be 12 bytes"); + } + if (counter < 0 || counter > MAX_COUNTER) { + throw new IllegalArgumentException("Counter must be an unsigned 32-bit value"); + } + } + + private static byte[] block(byte[] key, byte[] nonce, long counter) { + int[] state = new int[16]; + System.arraycopy(CONSTANTS, 0, state, 0, CONSTANTS.length); + + for (int i = 0; i < 8; i++) { + state[4 + i] = littleEndianInt(key, i * 4); + } + + state[12] = (int) counter; + state[13] = littleEndianInt(nonce, 0); + state[14] = littleEndianInt(nonce, 4); + state[15] = littleEndianInt(nonce, 8); + + int[] workingState = state.clone(); + for (int i = 0; i < 10; i++) { + quarterRound(workingState, 0, 4, 8, 12); + quarterRound(workingState, 1, 5, 9, 13); + quarterRound(workingState, 2, 6, 10, 14); + quarterRound(workingState, 3, 7, 11, 15); + + quarterRound(workingState, 0, 5, 10, 15); + quarterRound(workingState, 1, 6, 11, 12); + quarterRound(workingState, 2, 7, 8, 13); + quarterRound(workingState, 3, 4, 9, 14); + } + + byte[] output = new byte[BLOCK_SIZE]; + for (int i = 0; i < workingState.length; i++) { + int word = workingState[i] + state[i]; + output[i * 4] = (byte) word; + output[i * 4 + 1] = (byte) (word >>> 8); + output[i * 4 + 2] = (byte) (word >>> 16); + output[i * 4 + 3] = (byte) (word >>> 24); + } + return output; + } + + static void quarterRound(int[] state, int a, int b, int c, int d) { + state[a] += state[b]; + state[d] = Integer.rotateLeft(state[d] ^ state[a], 16); + state[c] += state[d]; + state[b] = Integer.rotateLeft(state[b] ^ state[c], 12); + state[a] += state[b]; + state[d] = Integer.rotateLeft(state[d] ^ state[a], 8); + state[c] += state[d]; + state[b] = Integer.rotateLeft(state[b] ^ state[c], 7); + } + + private static int littleEndianInt(byte[] bytes, int offset) { + return (bytes[offset] & 0xFF) | ((bytes[offset + 1] & 0xFF) << 8) | ((bytes[offset + 2] & 0xFF) << 16) | ((bytes[offset + 3] & 0xFF) << 24); + } +} diff --git a/src/test/java/com/thealgorithms/ciphers/ChaCha20Test.java b/src/test/java/com/thealgorithms/ciphers/ChaCha20Test.java new file mode 100644 index 000000000000..61d7c17ec663 --- /dev/null +++ b/src/test/java/com/thealgorithms/ciphers/ChaCha20Test.java @@ -0,0 +1,92 @@ +package com.thealgorithms.ciphers; + +import static org.junit.jupiter.api.Assertions.assertArrayEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; + +import org.junit.jupiter.api.Test; + +class ChaCha20Test { + + @Test + void quarterRoundMatchesRfc8439Vector() { + int[] state = {0x11111111, 0x01020304, 0x9b8d6f43, 0x01234567}; + + ChaCha20.quarterRound(state, 0, 1, 2, 3); + + assertArrayEquals(new int[] {0xea2a92f4, 0xcb1cf8ce, 0x4581472e, 0x5881c4bb}, state); + } + + @Test + void encryptingZeroesMatchesRfc8439BlockVector() { + byte[] key = new byte[32]; + for (int i = 0; i < key.length; i++) { + key[i] = (byte) i; + } + + byte[] nonce = {0, 0, 0, 9, 0, 0, 0, 0x4a, 0, 0, 0, 0}; + byte[] expected = {0x10, (byte) 0xf1, (byte) 0xe7, (byte) 0xe4, (byte) 0xd1, 0x3b, 0x59, 0x15, 0x50, 0x0f, (byte) 0xdd, 0x1f, (byte) 0xa3, 0x20, 0x71, (byte) 0xc4, (byte) 0xc7, (byte) 0xd1, (byte) 0xf4, (byte) 0xc7, 0x33, (byte) 0xc0, 0x68, 0x03, 0x04, 0x22, (byte) 0xaa, (byte) 0x9a, + (byte) 0xc3, (byte) 0xd4, 0x6c, 0x4e, (byte) 0xd2, (byte) 0x82, 0x64, 0x46, 0x07, (byte) 0x9f, (byte) 0xaa, 0x09, 0x14, (byte) 0xc2, (byte) 0xd7, 0x05, (byte) 0xd9, (byte) 0x8b, 0x02, (byte) 0xa2, (byte) 0xb5, 0x12, (byte) 0x9c, (byte) 0xd1, (byte) 0xde, 0x16, 0x4e, (byte) 0xb9, + (byte) 0xcb, (byte) 0xd0, (byte) 0x83, (byte) 0xe8, (byte) 0xa2, 0x50, 0x3c, 0x4e}; + + byte[] actual = ChaCha20.encrypt(new byte[64], key, nonce, 1); + + assertArrayEquals(expected, actual); + } + + @Test + void decryptRestoresInputAcrossMultipleBlocks() { + byte[] input = new byte[130]; + for (int i = 0; i < input.length; i++) { + input[i] = (byte) (i * 3); + } + + byte[] key = new byte[32]; + byte[] nonce = new byte[12]; + + byte[] encrypted = ChaCha20.encrypt(input, key, nonce, 7); + byte[] decrypted = ChaCha20.decrypt(encrypted, key, nonce, 7); + + assertArrayEquals(input, decrypted); + } + + @Test + void handlesPartialBlocksAroundBlockBoundary() { + for (int length : new int[] {1, 63, 65}) { + byte[] input = new byte[length]; + for (int i = 0; i < input.length; i++) { + input[i] = (byte) (i + 1); + } + + byte[] key = new byte[32]; + byte[] nonce = new byte[12]; + byte[] encrypted = ChaCha20.encrypt(input, key, nonce, 0); + + assertArrayEquals(input, ChaCha20.decrypt(encrypted, key, nonce, 0)); + } + } + + @Test + void emptyInputReturnsEmptyOutput() { + assertArrayEquals(new byte[0], ChaCha20.encrypt(new byte[0], new byte[32], new byte[12], 1)); + } + + @Test + void maximumCounterCanProcessOneBlock() { + byte[] input = new byte[64]; + + assertArrayEquals(input, ChaCha20.decrypt(ChaCha20.encrypt(input, new byte[32], new byte[12], 0xFFFF_FFFFL), new byte[32], new byte[12], 0xFFFF_FFFFL)); + } + + @Test + void counterOverflowIsRejected() { + assertThrows(IllegalArgumentException.class, () -> ChaCha20.encrypt(new byte[65], new byte[32], new byte[12], 0xFFFF_FFFFL)); + } + + @Test + void invalidKeyNonceAndCounterAreRejected() { + assertThrows(IllegalArgumentException.class, () -> ChaCha20.encrypt(new byte[1], new byte[31], new byte[12], 0)); + assertThrows(IllegalArgumentException.class, () -> ChaCha20.encrypt(new byte[1], new byte[32], new byte[11], 0)); + assertThrows(IllegalArgumentException.class, () -> ChaCha20.encrypt(new byte[1], new byte[32], new byte[12], -1)); + assertThrows(IllegalArgumentException.class, () -> ChaCha20.encrypt(new byte[1], new byte[32], new byte[12], 0x1_0000_0000L)); + } +} From 402d3b056554cbb973c488941df0307b257bdc1b Mon Sep 17 00:00:00 2001 From: S ROSHAN KUMAR Date: Sat, 14 Nov 2026 14:44:29 +0530 Subject: [PATCH 87/92] feat: add RightSideViewOfBinaryTree algorithm with tests (#7734) * feat: add RightSideViewOfBinaryTree algorithm with tests * fix: correct input array for testRightSkewedTree --- .../trees/RightSideViewOfBinaryTree.java | 56 +++++++++++++++++ .../trees/RightSideViewOfBinaryTreeTest.java | 60 +++++++++++++++++++ 2 files changed, 116 insertions(+) create mode 100644 src/main/java/com/thealgorithms/datastructures/trees/RightSideViewOfBinaryTree.java create mode 100644 src/test/java/com/thealgorithms/datastructures/trees/RightSideViewOfBinaryTreeTest.java diff --git a/src/main/java/com/thealgorithms/datastructures/trees/RightSideViewOfBinaryTree.java b/src/main/java/com/thealgorithms/datastructures/trees/RightSideViewOfBinaryTree.java new file mode 100644 index 000000000000..6bb965aad4d6 --- /dev/null +++ b/src/main/java/com/thealgorithms/datastructures/trees/RightSideViewOfBinaryTree.java @@ -0,0 +1,56 @@ +package com.thealgorithms.datastructures.trees; + +import java.util.ArrayList; +import java.util.LinkedList; +import java.util.List; +import java.util.Queue; + +/** + * Given the root of a binary tree, returns the values of the nodes visible + * from the right side (the last node of each level in a level-order traversal). + * + *

Example: + *

+ *      1
+ *     / \
+ *    2   3
+ *     \   \
+ *      5   4
+ * Right side view: [1, 3, 4]
+ * 
+ * + *

Time complexity: O(n), Space complexity: O(n) + * + * @see LeetCode #199 + */ +public final class RightSideViewOfBinaryTree { + private RightSideViewOfBinaryTree() { + } + + public static List rightSideView(BinaryTree.Node root) { + List result = new ArrayList<>(); + if (root == null) { + return result; + } + + Queue queue = new LinkedList<>(); + queue.add(root); + + while (!queue.isEmpty()) { + int levelSize = queue.size(); + for (int i = 0; i < levelSize; i++) { + BinaryTree.Node node = queue.poll(); + if (i == levelSize - 1) { + result.add(node.data); + } + if (node.left != null) { + queue.add(node.left); + } + if (node.right != null) { + queue.add(node.right); + } + } + } + return result; + } +} diff --git a/src/test/java/com/thealgorithms/datastructures/trees/RightSideViewOfBinaryTreeTest.java b/src/test/java/com/thealgorithms/datastructures/trees/RightSideViewOfBinaryTreeTest.java new file mode 100644 index 000000000000..ded92d4d8de5 --- /dev/null +++ b/src/test/java/com/thealgorithms/datastructures/trees/RightSideViewOfBinaryTreeTest.java @@ -0,0 +1,60 @@ +package com.thealgorithms.datastructures.trees; + +import static org.junit.jupiter.api.Assertions.assertEquals; + +import java.util.Collections; +import java.util.List; +import org.junit.jupiter.api.Test; + +public class RightSideViewOfBinaryTreeTest { + + @Test + public void testNullRoot() { + assertEquals(Collections.emptyList(), RightSideViewOfBinaryTree.rightSideView(null)); + } + + @Test + public void testSingleNode() { + final BinaryTree.Node root = TreeTestUtils.createTree(new Integer[] {1}); + assertEquals(List.of(1), RightSideViewOfBinaryTree.rightSideView(root)); + } + + /* + 1 + / \ + 2 3 + \ \ + 5 4 + */ + @Test + public void testRightSideView() { + final BinaryTree.Node root = TreeTestUtils.createTree(new Integer[] {1, 2, 3, null, 5, null, 4}); + assertEquals(List.of(1, 3, 4), RightSideViewOfBinaryTree.rightSideView(root)); + } + + /* + 1 + / + 2 + / + 3 + */ + @Test + public void testLeftSkewedTree() { + final BinaryTree.Node root = TreeTestUtils.createTree(new Integer[] {1, 2, null, 3}); + assertEquals(List.of(1, 2, 3), RightSideViewOfBinaryTree.rightSideView(root)); + } + + /* + 1 + \ + 2 + \ + 3 + */ + @Test + public void testRightSkewedTree() { + final BinaryTree.Node root = TreeTestUtils.createTree(new Integer[] {1, null, 2, null, 3}); + assertEquals(List.of(1, 2, 3), RightSideViewOfBinaryTree.rightSideView(root)); + } +} From 401e25388def688d457ccab49dd84dd97d9d1b49 Mon Sep 17 00:00:00 2001 From: Hardik K Date: Sat, 14 Nov 2026 14:48:41 +0530 Subject: [PATCH 88/92] fix(searches): fix boundary safety and null checks in SaddlebackSearch (#7726) --- .../searches/SaddlebackSearch.java | 25 ++++++++-- .../searches/SaddlebackSearchTest.java | 49 +++++++++++++++++++ 2 files changed, 69 insertions(+), 5 deletions(-) diff --git a/src/main/java/com/thealgorithms/searches/SaddlebackSearch.java b/src/main/java/com/thealgorithms/searches/SaddlebackSearch.java index 192c4d26c735..9455636a4c9c 100644 --- a/src/main/java/com/thealgorithms/searches/SaddlebackSearch.java +++ b/src/main/java/com/thealgorithms/searches/SaddlebackSearch.java @@ -19,24 +19,39 @@ private SaddlebackSearch() { } /** - * This method performs Saddleback Search + * Searches for a key in a row-wise and column-wise sorted 2D array starting from the bottom-left corner. + * + * @param arr The sorted matrix. + * @param key The element to search for. + * @throws IllegalArgumentException if the array is null or empty. + * @return The index (row and column) of the element if found. Else returns {-1, -1}. + */ + public static int[] find(int[][] arr, int key) { + if (arr == null || arr.length == 0) { + throw new IllegalArgumentException("Array is empty"); + } + return find(arr, arr.length - 1, 0, key); + } + + /** + * This method performs Saddleback Search starting from the specified row and column. * * @param arr The **Sorted** array in which we will search the element. * @param row the current row. * @param col the current column. * @param key the element that we want to search for. - * @throws IllegalArgumentException if the array is empty. + * @throws IllegalArgumentException if the array is null or empty. * @return The index(row and column) of the element if found. Else returns * -1 -1. */ - static int[] find(int[][] arr, int row, int col, int key) { - if (arr.length == 0) { + public static int[] find(int[][] arr, int row, int col, int key) { + if (arr == null || arr.length == 0) { throw new IllegalArgumentException("Array is empty"); } // array to store the answer row and column int[] ans = {-1, -1}; - if (row < 0 || col >= arr[row].length) { + if (row < 0 || row >= arr.length || arr[row] == null || col < 0 || col >= arr[row].length) { return ans; } if (arr[row][col] == key) { diff --git a/src/test/java/com/thealgorithms/searches/SaddlebackSearchTest.java b/src/test/java/com/thealgorithms/searches/SaddlebackSearchTest.java index ec22cbf38152..e4e6b2bf107d 100644 --- a/src/test/java/com/thealgorithms/searches/SaddlebackSearchTest.java +++ b/src/test/java/com/thealgorithms/searches/SaddlebackSearchTest.java @@ -82,4 +82,53 @@ void testFindSingleElementNotExists() { int[] result = SaddlebackSearch.find(arr, 0, 0, 10); assertArrayEquals(new int[] {-1, -1}, result, "Element 10 should not be found in single element array"); } + + /** + * Test convenience method searching from the bottom-left corner automatically. + */ + @Test + void testFindWithConvenienceMethod() { + int[][] arr = {{-10, -5, -3, 4, 9}, {-6, -2, 0, 5, 10}, {-4, -1, 1, 6, 12}, {2, 3, 7, 8, 13}, {100, 120, 130, 140, 150}}; + int[] result = SaddlebackSearch.find(arr, 4); + assertArrayEquals(new int[] {0, 3}, result, "Element 4 should be found at (0, 3) using convenience overload"); + } + + /** + * Test searching in a null array throws IllegalArgumentException. + */ + @Test + void testFindWithNullArray() { + assertThrows(IllegalArgumentException.class, () -> SaddlebackSearch.find(null, 4)); + assertThrows(IllegalArgumentException.class, () -> SaddlebackSearch.find(null, 0, 0, 4)); + } + + /** + * Test row index out of bounds returns {-1, -1}. + */ + @Test + void testFindWithRowOutOfBounds() { + int[][] arr = {{1, 2}, {3, 4}}; + int[] result = SaddlebackSearch.find(arr, 5, 0, 3); + assertArrayEquals(new int[] {-1, -1}, result, "Row index out of bounds should return {-1, -1}"); + } + + /** + * Test negative column index returns {-1, -1}. + */ + @Test + void testFindWithNegativeColumn() { + int[][] arr = {{1, 2}, {3, 4}}; + int[] result = SaddlebackSearch.find(arr, 1, -1, 3); + assertArrayEquals(new int[] {-1, -1}, result, "Negative column index should return {-1, -1}"); + } + + /** + * Test null row in matrix returns {-1, -1} safely. + */ + @Test + void testFindWithNullRowInMatrix() { + int[][] arr = {{1, 2}, null, {5, 6}}; + int[] result = SaddlebackSearch.find(arr, 1, 0, 5); + assertArrayEquals(new int[] {-1, -1}, result, "Null row in matrix should safely return {-1, -1}"); + } } From a0062057ff1f346b9d6324e732bc84b6d9d32ed2 Mon Sep 17 00:00:00 2001 From: Prasad Pitke <120767959+Prasad-Pitke@users.noreply.github.com> Date: Sat, 14 Nov 2026 15:20:39 +0530 Subject: [PATCH 89/92] Detect overflow in Pow.pow (#7752) Use Math.multiplyExact for overflow handling in pow --- src/main/java/com/thealgorithms/maths/Pow.java | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/main/java/com/thealgorithms/maths/Pow.java b/src/main/java/com/thealgorithms/maths/Pow.java index 377b37ac4569..33dda5ba2ddc 100644 --- a/src/main/java/com/thealgorithms/maths/Pow.java +++ b/src/main/java/com/thealgorithms/maths/Pow.java @@ -22,6 +22,7 @@ private Pow() { * @param b the exponent to which the base {@code a} is raised. Must be a non-negative integer. * @return the result of {@code a}{@code b} as a {@code long}. * @throws IllegalArgumentException if {@code b} is negative. + * @throws ArithmeticException if the result overflows a {@code long}. */ public static long pow(int a, int b) { if (b < 0) { @@ -29,7 +30,7 @@ public static long pow(int a, int b) { } long result = 1; for (int i = 1; i <= b; i++) { - result *= a; + result = Math.multiplyExact(result, (long) a); } return result; } From 33f6e94cf1c3800f34c945061bbcbed0f8692e7f Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 17 Nov 2026 00:03:49 +0200 Subject: [PATCH 90/92] chore(deps): bump org.apache.commons:commons-lang3 from 3.21.0 to 3.22.0 (#7759) Bumps org.apache.commons:commons-lang3 from 3.21.0 to 3.22.0. --- updated-dependencies: - dependency-name: org.apache.commons:commons-lang3 dependency-version: 3.22.0 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 2af08520649a..f33ae0f435a7 100644 --- a/pom.xml +++ b/pom.xml @@ -48,7 +48,7 @@ org.apache.commons commons-lang3 - 3.21.0 + 3.22.0 org.apache.commons From b42e5df87251019f8836b2799ced4c6e20c4c6f8 Mon Sep 17 00:00:00 2001 From: Oleksandr Klymenko Date: Tue, 17 Nov 2026 19:45:52 +0200 Subject: [PATCH 91/92] feat: add TimestampOrderChecker, out of order and duplicate timestamps (#7733) Windowed algorithms assume time moves forward. When it does not, nothing fails loudly: a window holds samples that never coexisted, a rate is computed over a negative interval, a duplicate is counted twice. Retries, buffers flushed after a reconnect, several producers writing into one topic and a clock stepped backwards all cause this, and the cheap defence is to check the order explicitly. Each timestamp is compared with the previous one and classified as INCREASING, DUPLICATE or BACKWARDS. The checker only reports, it does not reorder or drop anything, so lastTimestamp is always the most recent sample, not the largest. It also keeps the worst backwards step, which is what you need to size a reordering buffer. O(1) time per sample and O(1) state; non-finite timestamps are refused. Tests: the first timestamp is always accepted, an ordered stream has no violations, duplicates and backwards steps are counted separately, the worst step is the largest one and not the last one, the stream is not reordered, scan returns one verdict per timestamp, and reset restores the initial state. Signed-off-by: alxkm <19151554+alxkm@users.noreply.github.com> Co-authored-by: alxkm <19151554+alxkm@users.noreply.github.com> --- .../streaming/TimestampOrderChecker.java | 203 ++++++++++++++++++ .../streaming/TimestampOrderCheckerTest.java | 139 ++++++++++++ 2 files changed, 342 insertions(+) create mode 100644 src/main/java/com/thealgorithms/streaming/TimestampOrderChecker.java create mode 100644 src/test/java/com/thealgorithms/streaming/TimestampOrderCheckerTest.java diff --git a/src/main/java/com/thealgorithms/streaming/TimestampOrderChecker.java b/src/main/java/com/thealgorithms/streaming/TimestampOrderChecker.java new file mode 100644 index 000000000000..b220c82542d4 --- /dev/null +++ b/src/main/java/com/thealgorithms/streaming/TimestampOrderChecker.java @@ -0,0 +1,203 @@ +package com.thealgorithms.streaming; + +/** + * Watches the timestamps of a stream for samples that arrive out of order or twice. + * + *

Every windowed algorithm assumes that time moves forward. When it does not, nothing crashes: + * the window simply holds samples that never coexisted, a rate is computed over a negative interval, + * and a duplicate counts twice in an average. Retries, buffers flushed after a reconnect, several + * producers writing into one topic and a clock stepped backwards all produce exactly that, and the + * only cheap defence is to check the order explicitly. + * + *

Each timestamp is compared with the one immediately before it and classified as + * {@link Order#INCREASING}, {@link Order#DUPLICATE} or {@link Order#BACKWARDS}. The checker reports, + * it does not reorder or drop anything, so {@link #lastTimestamp()} is always the most recent sample + * and not the largest one seen. + * + *

Besides the counters it keeps the worst backwards step, which is what a caller needs in order to + * size a reordering buffer: a stream whose worst violation is 20 milliseconds can be repaired by + * holding samples for 20 milliseconds, while one that jumps back an hour cannot be repaired at all. + * + *

Usage

+ * + *
{@code
+ * TimestampOrderChecker checker = new TimestampOrderChecker();
+ * for (double timestamp : timestamps) {
+ *     if (checker.accept(timestamp).isViolation()) {
+ *         quarantine(timestamp);
+ *     }
+ * }
+ * }
+ * + *

Each sample costs O(1) time and the checker keeps O(1) state. This class is not thread-safe. + * + * @see Monotonic function + */ +public final class TimestampOrderChecker { + + private double lastTimestamp; + private double worstBackwardsStep; + private boolean started; + private long count; + private long duplicateCount; + private long backwardsCount; + private Order lastOrder = Order.INCREASING; + + /** + * Feeds the timestamp of one sample. + * + * @param timestamp when the sample arrived + * @return how this timestamp relates to the previous one; the first one is always + * {@link Order#INCREASING} + * @throws IllegalArgumentException if {@code timestamp} is NaN or infinite + */ + public Order accept(double timestamp) { + if (!Double.isFinite(timestamp)) { + throw new IllegalArgumentException("Timestamps must be finite, but was " + timestamp); + } + + Order order = Order.INCREASING; + if (started) { + if (timestamp == lastTimestamp) { + order = Order.DUPLICATE; + duplicateCount++; + } else if (timestamp < lastTimestamp) { + order = Order.BACKWARDS; + backwardsCount++; + worstBackwardsStep = Math.max(worstBackwardsStep, lastTimestamp - timestamp); + } + } + + lastTimestamp = timestamp; + started = true; + count++; + lastOrder = order; + return order; + } + + /** + * Runs the checker over a whole series of timestamps. + * + * @param timestamps the timestamps to inspect + * @return a new array of the same length holding the verdict for every timestamp + * @throws IllegalArgumentException if a timestamp is NaN or infinite + * @throws NullPointerException if {@code timestamps} is {@code null} + */ + public Order[] scan(double[] timestamps) { + Order[] verdicts = new Order[timestamps.length]; + for (int i = 0; i < timestamps.length; i++) { + verdicts[i] = accept(timestamps[i]); + } + return verdicts; + } + + /** + * Returns the verdict on the most recent timestamp. + * + * @return the last verdict, {@link Order#INCREASING} before the first timestamp + */ + public Order lastOrder() { + return lastOrder; + } + + /** + * Tells whether every timestamp so far moved forward. + * + * @return {@code true} if neither a duplicate nor a backwards step has been seen + */ + public boolean isOrdered() { + return duplicateCount == 0 && backwardsCount == 0; + } + + /** + * Returns the timestamp of the most recent sample, which is not necessarily the largest one seen. + * + * @return the last timestamp + * @throws IllegalStateException if no timestamp has been accepted yet + */ + public double lastTimestamp() { + if (!started) { + throw new IllegalStateException("The checker has not seen any timestamp yet"); + } + return lastTimestamp; + } + + /** + * Returns the largest distance a timestamp ever jumped backwards, which is how long a reordering + * buffer would have to hold a sample to repair this stream. + * + * @return the worst backwards step, {@code 0} if the stream never went backwards + */ + public double worstBackwardsStep() { + return worstBackwardsStep; + } + + /** + * Returns how many timestamps have been inspected since the last reset. + * + * @return the sample count + */ + public long count() { + return count; + } + + /** + * Returns how many timestamps repeated the one before them. + * + * @return the duplicate count + */ + public long duplicateCount() { + return duplicateCount; + } + + /** + * Returns how many timestamps were smaller than the one before them. + * + * @return the backwards count + */ + public long backwardsCount() { + return backwardsCount; + } + + /** + * Forgets every timestamp seen so far. + */ + public void reset() { + lastTimestamp = 0.0; + worstBackwardsStep = 0.0; + started = false; + count = 0; + duplicateCount = 0; + backwardsCount = 0; + lastOrder = Order.INCREASING; + } + + @Override + public String toString() { + return "TimestampOrderChecker{samples=" + count + ", duplicates=" + duplicateCount + ", backwards=" + backwardsCount + ", worstStep=" + worstBackwardsStep + "}"; + } + + /** + * How a timestamp relates to the one before it. + */ + public enum Order { + + /** The timestamp moved forward, which is the only healthy case. */ + INCREASING, + + /** The timestamp repeats the previous one. */ + DUPLICATE, + + /** The timestamp is older than the previous one. */ + BACKWARDS; + + /** + * Tells whether this verdict reports a broken timeline. + * + * @return {@code true} for {@link #DUPLICATE} and {@link #BACKWARDS} + */ + public boolean isViolation() { + return this != INCREASING; + } + } +} diff --git a/src/test/java/com/thealgorithms/streaming/TimestampOrderCheckerTest.java b/src/test/java/com/thealgorithms/streaming/TimestampOrderCheckerTest.java new file mode 100644 index 000000000000..43867ccd15b6 --- /dev/null +++ b/src/test/java/com/thealgorithms/streaming/TimestampOrderCheckerTest.java @@ -0,0 +1,139 @@ +package com.thealgorithms.streaming; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import com.thealgorithms.streaming.TimestampOrderChecker.Order; +import org.junit.jupiter.api.Assertions; +import org.junit.jupiter.api.DisplayName; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.params.ParameterizedTest; +import org.junit.jupiter.params.provider.ValueSource; + +class TimestampOrderCheckerTest { + + @ParameterizedTest + @ValueSource(doubles = {Double.NaN, Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY}) + void rejectsNonFiniteTimestamps(double timestamp) { + TimestampOrderChecker checker = new TimestampOrderChecker(); + assertThrows(IllegalArgumentException.class, () -> checker.accept(timestamp)); + } + + @Test + void startsEmpty() { + TimestampOrderChecker checker = new TimestampOrderChecker(); + + assertEquals(0, checker.count()); + assertEquals(Order.INCREASING, checker.lastOrder()); + assertTrue(checker.isOrdered()); + assertEquals(0.0, checker.worstBackwardsStep()); + assertThrows(IllegalStateException.class, checker::lastTimestamp); + } + + @Test + void theFirstTimestampIsAlwaysAccepted() { + TimestampOrderChecker checker = new TimestampOrderChecker(); + + assertEquals(Order.INCREASING, checker.accept(-500.0)); + assertEquals(-500.0, checker.lastTimestamp()); + } + + @Test + void anOrderedStreamHasNoViolations() { + TimestampOrderChecker checker = new TimestampOrderChecker(); + + for (int i = 0; i < 20; i++) { + assertEquals(Order.INCREASING, checker.accept(i)); + } + assertTrue(checker.isOrdered()); + assertEquals(20, checker.count()); + } + + @Test + void reportsADuplicate() { + TimestampOrderChecker checker = new TimestampOrderChecker(); + checker.accept(10.0); + + assertEquals(Order.DUPLICATE, checker.accept(10.0)); + assertEquals(1, checker.duplicateCount()); + assertEquals(0, checker.backwardsCount()); + assertFalse(checker.isOrdered()); + } + + @Test + void reportsAStepBackwards() { + TimestampOrderChecker checker = new TimestampOrderChecker(); + checker.accept(10.0); + + assertEquals(Order.BACKWARDS, checker.accept(7.5)); + assertEquals(1, checker.backwardsCount()); + assertEquals(2.5, checker.worstBackwardsStep()); + } + + @Test + @DisplayName("the worst backwards step is the largest one, not the last one") + void keepsTheWorstBackwardsStep() { + TimestampOrderChecker checker = new TimestampOrderChecker(); + + checker.scan(new double[] {100.0, 60.0, 61.0, 59.0, 200.0, 199.0}); + + assertEquals(3, checker.backwardsCount()); + assertEquals(40.0, checker.worstBackwardsStep()); + } + + @Test + @DisplayName("the checker reports without reordering, so the last timestamp is the most recent one") + void doesNotReorderTheStream() { + TimestampOrderChecker checker = new TimestampOrderChecker(); + + checker.accept(100.0); + checker.accept(50.0); + + assertEquals(50.0, checker.lastTimestamp()); + assertEquals(Order.INCREASING, checker.accept(60.0), "the next sample is compared with the previous one, not with the maximum"); + } + + @Test + void scanReportsOneVerdictPerTimestamp() { + TimestampOrderChecker checker = new TimestampOrderChecker(); + + Order[] verdicts = checker.scan(new double[] {1.0, 2.0, 2.0, 1.5, 3.0}); + + Assertions.assertArrayEquals(new Order[] {Order.INCREASING, Order.INCREASING, Order.DUPLICATE, Order.BACKWARDS, Order.INCREASING}, verdicts); + } + + @Test + void theVerdictKnowsWhetherItIsAViolation() { + assertFalse(Order.INCREASING.isViolation()); + assertTrue(Order.DUPLICATE.isViolation()); + assertTrue(Order.BACKWARDS.isViolation()); + } + + @Test + void resetRestoresTheInitialState() { + TimestampOrderChecker checker = new TimestampOrderChecker(); + checker.scan(new double[] {5.0, 4.0, 4.0}); + + checker.reset(); + + assertEquals(0, checker.count()); + assertEquals(0, checker.duplicateCount()); + assertEquals(0, checker.backwardsCount()); + assertEquals(0.0, checker.worstBackwardsStep()); + assertTrue(checker.isOrdered()); + assertThrows(IllegalStateException.class, checker::lastTimestamp); + } + + @Test + void toStringMentionsTheState() { + TimestampOrderChecker checker = new TimestampOrderChecker(); + checker.scan(new double[] {5.0, 4.0}); + + String text = checker.toString(); + + assertTrue(text.contains("TimestampOrderChecker")); + assertTrue(text.contains("backwards=1")); + } +} From e79b0f106477774020d4c5c2738f0854ff3d2444 Mon Sep 17 00:00:00 2001 From: Aman Mohamed Ali <69119173+spidervirus@users.noreply.github.com> Date: Wed, 18 Nov 2026 03:01:34 +0400 Subject: [PATCH 92/92] fix(maths): ensure non-composite inputs are rejected in SmithNumber (#7756) - Reject numbers <= 3 as Smith numbers must be composite (greater than 3) - Fix bug where isSmithNumber(0) incorrectly returned true - Prevent integer overflow in trial division loop condition by using (long) i * i - Add comprehensive test cases covering non-composite inputs (negative numbers, 0, 1), primes, and valid Smith numbers --- src/main/java/com/thealgorithms/maths/SmithNumber.java | 5 ++--- src/test/java/com/thealgorithms/maths/SmithNumberTest.java | 4 ++-- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/src/main/java/com/thealgorithms/maths/SmithNumber.java b/src/main/java/com/thealgorithms/maths/SmithNumber.java index c06e0023d9bb..41d7bebed257 100644 --- a/src/main/java/com/thealgorithms/maths/SmithNumber.java +++ b/src/main/java/com/thealgorithms/maths/SmithNumber.java @@ -18,10 +18,9 @@ private SmithNumber() { private static int primeFactorDigitSum(int n) { int sum = 0; - int num = n; // Factorize the number using trial division - for (int i = 2; i * i <= num; i++) { + for (int i = 2; (long) i * i <= n; i++) { while (n % i == 0) { // while i divides n sum += SumOfDigits.sumOfDigits(i); // add sum of digits of factor n /= i; // divide n by the factor @@ -43,7 +42,7 @@ private static int primeFactorDigitSum(int n) { * @return {@code true} if {@code number} is a Smith number, otherwise false */ public static boolean isSmithNumber(int number) { - if (PrimeCheck.isPrime(number)) { + if (number <= 3 || PrimeCheck.isPrime(number)) { return false; // Smith numbers must be composite } diff --git a/src/test/java/com/thealgorithms/maths/SmithNumberTest.java b/src/test/java/com/thealgorithms/maths/SmithNumberTest.java index 4e2ba0b88e33..b073cda880fb 100644 --- a/src/test/java/com/thealgorithms/maths/SmithNumberTest.java +++ b/src/test/java/com/thealgorithms/maths/SmithNumberTest.java @@ -9,13 +9,13 @@ class SmithNumberTest { @ParameterizedTest - @CsvSource({"4", "22", "121", "562", "985", "4937775"}) + @CsvSource({"4", "22", "27", "58", "85", "94", "121", "562", "985", "4937775"}) void positiveSmithNumbersTest(int n) { assertTrue(SmithNumber.isSmithNumber(n)); } @ParameterizedTest - @CsvSource({"2", "11", "100", "550", "999", "1234557"}) + @CsvSource({"-22", "-4", "-1", "0", "1", "2", "3", "5", "6", "8", "9", "10", "11", "100", "550", "999", "1234557"}) void negativeSmithNumbersTest(int n) { assertFalse(SmithNumber.isSmithNumber(n)); }