You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by ah...@apache.org on 2021/07/23 21:11:51 UTC
[commons-rng] 03/03: Add shape and composite samplers to the
documentation
This is an automated email from the ASF dual-hosted git repository.
aherbert pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-rng.git
commit 811866dc0d0ef2fb04688e75c4524995e07496df
Author: Alex Herbert <ah...@apache.org>
AuthorDate: Fri Jul 23 22:11:43 2021 +0100
Add shape and composite samplers to the documentation
Updated the userguide and the sampling module overview page.
---
commons-rng-sampling/src/site/xdoc/index.xml | 44 +++++++++++++++++++++-
src/site/apt/userguide/rng.apt | 56 ++++++++++++++++++++++++++--
2 files changed, 95 insertions(+), 5 deletions(-)
diff --git a/commons-rng-sampling/src/site/xdoc/index.xml b/commons-rng-sampling/src/site/xdoc/index.xml
index 1dc2ab3..fe9c3c3 100644
--- a/commons-rng-sampling/src/site/xdoc/index.xml
+++ b/commons-rng-sampling/src/site/xdoc/index.xml
@@ -41,13 +41,13 @@
<source class="prettyprint">import org.apache.commons.rng.UniformRandomProvider;
import org.apache.commons.rng.sampling.distribution.ContinuousSampler;
-import org.apache.commons.rng.sampling.distribution.MarsagliaNormalizedGaussianSampler;
+import org.apache.commons.rng.sampling.distribution.ZigguratSampler.Gaussian;
public class NormalDeviates {
private final ContinuousSampler normalizedGaussian;
public NormalDeviates(UniformRandomProvider rng) {
- normalizedGaussian = MarsagliaNormalizedGaussianSampler.of(rng);
+ normalizedGaussian = ZigguratSampler.Gaussian.of(rng);
}
public double sample(double mean,
@@ -59,6 +59,46 @@ public class NormalDeviates {
</p>
<p>
+ Utilities are provided to sample from generic collections.
+ </p>
+
+ <p>
+ Example:
+
+<source class="prettyprint">import org.apache.commons.rng.UniformRandomProvider;
+import java.util.HashSet;
+import org.apache.commons.rng.sampling.CollectionSampler;
+
+HashSet<String> list = new HashSet<String>();
+list.add("Apache");
+list.add("Commons");
+list.add("RNG");
+
+CollectionSampler<String> sampler = new CollectionSampler<String>(RandomSource.MWC_256.create(),
+ list);
+String word = sampler.sample();
+</source>
+ </p>
+
+ <p>
+ The module also contains classes to generate coordinate samples from geometric shapes
+ such as inside a ball, box or triangle or on the surface of a sphere.
+ </p>
+
+ <p>
+ Example:
+
+<source class="prettyprint">import org.apache.commons.rng.UniformRandomProvider;
+import org.apache.commons.rng.sampling.UnitSphereSampler;
+
+int dimension = 3;
+UnitSphereSampler sampler = new UnitSphereSampler(dimension , RandomSource.KISS.create());
+
+double[] vector = sampler.sample();
+</source>
+ </p>
+
+ <p>
Browse the <a href="apidocs/index.html">Javadoc</a> for more information.
</p>
</section>
diff --git a/src/site/apt/userguide/rng.apt b/src/site/apt/userguide/rng.apt
index 47e8537..556f977 100644
--- a/src/site/apt/userguide/rng.apt
+++ b/src/site/apt/userguide/rng.apt
@@ -63,8 +63,9 @@
* {{{../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/package-summary.html}Sampling}} (requires Java 6)
- This module provides implementations that generate a sequence of numbers according to some
- specified probability distribution, and utilities to sample from a generic collection of items.
+ This module provides implementations that: generate a sequence of numbers according to some
+ specified probability distribution; sample coordinates from geometric shapes; sample
+ from generic collections of items; and other sampling utilities.
It is an example of usage of the API provided in the <<<commons-rng-client-api>>> module.
* Examples
@@ -417,7 +418,7 @@ list.add("Commons");
list.add("RNG");
CollectionSampler<String> sampler = new CollectionSampler<String>(RandomSource.MWC_256.create(),
- list, 1);
+ list);
String word = sampler.sample();
+--------------------------+
@@ -439,6 +440,55 @@ List<String> sample = ListSampler.sample(rng, list, k);
ListSampler.shuffle(rng, list)
+--------------------------+
+ * Sampling from geometric shapes:
+ {{{../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/shape/BoxSampler.html}Box}},
+ {{{../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/shape/UnitBallSampler.html}Ball}},
+ {{{../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/shape/LineSampler.html}Line}},
+ {{{../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/shape/TriangleSampler.html}Triangle}}, and
+ {{{../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/shape/TetrahedronSampler.html}Tetrahedron}}.
+
++--------------------------+
+import org.apache.commons.rng.sampling.shape.BoxSampler;
+
+double[] lower = {1, 2, 3};
+double[] upper = {15, 16, 17}
+BoxSampler sampler = BoxSampler.of(RandomSource.KISS.create(),
+ lower, upper);
+double[] coordinate = sampler.sample();
++--------------------------+
+
+ * The
+ {{{../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/CompositeSamplers.html}CompositeSamplers}}
+ utility class can create a composite sampler that is a weighted combination of samplers
+ that return the same type.
+
+ The following example will create a sampler to uniformly sample the border of a triangle
+ using the line segment lengths as weights:
+
++--------------------------+
+import org.apache.commons.rng.sampling.shape.LineSampler;
+
+UniformRandomProvider rng = RandomSource.JSF_64.create();
+
+// Triangle vertices
+double[] a = {1.23, 4.56};
+double[] b = {6.78, 9.01};
+double[] c = {3.45, 2.34};
+// Line lengths
+double ab = Math.hypot(a[0] - b[0], a[1] - b[1]);
+double bc = Math.hypot(b[0] - c[0], b[1] - c[1]);
+double ca = Math.hypot(c[0] - a[0], c[1] - a[1]);
+
+ObjectSampler<double[]> sampler =
+ CompositeSamplers.<double[]>newObjectSamplerBuilder()
+ .add(LineSampler.of(rng, a, b), ab)
+ .add(LineSampler.of(rng, b, c), bc)
+ .add(LineSampler.of(rng, c, a), ca)
+ .build(rng);
+
+double[] coordinate = sampler.sample();
++--------------------------+
+
[]