This is an automated email from the ASF dual-hosted git repository.
asf-gitbox-commits pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-statistics.git
The following commit(s) were added to refs/heads/master by this push:
new cd5bf159 Update documentation on possible long runtimes
cd5bf159 is described below
commit cd5bf15991b4a120376c39ce7c9943174770c7b4
Author: Alex Herbert <[email protected]>
AuthorDate: Thu Aug 27 21:55:55 2026 +0100
Update documentation on possible long runtimes
---
.../statistics/distribution/ZipfDistribution.java | 19 +++++++++++++++++++
src/changes/changes.xml | 4 ++++
2 files changed, 23 insertions(+)
diff --git
a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/ZipfDistribution.java
b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/ZipfDistribution.java
index 0e92d16e..8d92e1aa 100644
---
a/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/ZipfDistribution.java
+++
b/commons-statistics-distribution/src/main/java/org/apache/commons/statistics/distribution/ZipfDistribution.java
@@ -34,6 +34,20 @@ import
org.apache.commons.rng.sampling.distribution.RejectionInversionZipfSample
* <a
href="https://en.wikipedia.org/wiki/Harmonic_number#Generalized_harmonic_numbers";>
* generalized harmonic number</a> of order N of s.
*
+ * <p><strong>Note:</strong> The generalized harmonic number \( H_{N,s} \) is
computed
+ * by direct summation of \( N \) terms. Construction of the distribution, and
each
+ * call to {@link #getMean()} or {@link #getVariance()}, is \( O(N) \); each
call to
+ * {@link #cumulativeProbability(int) cumulativeProbability(x)} or
+ * {@link #survivalProbability(int) survivalProbability(x)} is \( O(x) \) (the
+ * partial harmonic sum is not cached between calls); the inverse probability
+ * functions perform a search using \( O(\log N) \) cumulative probability
+ * evaluations. A number of elements of order 2<sup>31</sup> requires billions
of
+ * {@code Math.pow} evaluations for construction alone. Take this run-time
cost into
+ * account when the parameters are derived from untrusted input, and bound the
number
+ * of elements accordingly. Sampling (see {@link
#createSampler(UniformRandomProvider)
+ * createSampler}) uses a rejection method with a cost per sample that does
not depend
+ * on the number of elements.
+ *
* @see <a href="https://en.wikipedia.org/wiki/Zipf's_law">Zipf distribution
(Wikipedia)</a>
*/
public final class ZipfDistribution extends AbstractDiscreteDistribution {
@@ -61,6 +75,11 @@ public final class ZipfDistribution extends
AbstractDiscreteDistribution {
/**
* Creates a Zipf distribution.
*
+ * <p><strong>Note:</strong> Construction computes the normalizing constant
+ * \( H_{N,s} \) by direct summation of {@code numberOfElements} terms and
is
+ * {@code O(numberOfElements)}. See the {@linkplain ZipfDistribution
class-level}
+ * documentation for details.
+ *
* @param numberOfElements Number of elements.
* @param exponent Exponent.
* @return the distribution
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index 94d4e1bb..1b442813 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -53,6 +53,10 @@ If the output is not quite correct, check for invisible
trailing spaces!
</properties>
<body>
<release version="1.4" date="TBD" description="Adds new features (requires
Java 8).">
+ <action dev="aherbert" type="update" due-to="Security scan, Alex
Herbert">
+ "ZipfDistribution": Update documentation on possible long runtimes when
+ using the distribution with a large number of elements.
+ </action>
<action dev="aherbert" type="update" due-to="Security scan, Alex
Herbert">
"UnconditionedExactTest": Update documentation on possible long
runtime and
high memory consumption for large table counts. For performance
sensitive
