Author: aherbert
Date: Tue Apr 21 14:19:42 2026
New Revision: 1092799
Log:
Use prettyprint for code sections
Modified:
websites/production/commons/content/proper/commons-rng/userguide/rng.html
Modified:
websites/production/commons/content/proper/commons-rng/userguide/rng.html
==============================================================================
--- websites/production/commons/content/proper/commons-rng/userguide/rng.html
Tue Apr 21 12:38:47 2026 (r1092798)
+++ websites/production/commons/content/proper/commons-rng/userguide/rng.html
Tue Apr 21 14:19:42 2026 (r1092799)
@@ -279,56 +279,56 @@
<p>Please refer to the generated documentation (of the appropriate module) for
details on the API illustrated by the following examples.</p>
<ul>
<li>Random number generator objects are instantiated through factory methods
defined in <code>RandomSource</code>, an <code>enum</code> that declares <a
href="../commons-rng-simple/apidocs/org/apache/commons/rng/simple/RandomSource.html#enum.constant.detail">all
the available implementations</a>.
-<pre><code>import org.apache.commons.rng.UniformRandomProvider;
+<pre class="prettyprint"><code>import
org.apache.commons.rng.UniformRandomProvider;
import org.apache.commons.rng.simple.RandomSource;
UniformRandomProvider rng =
RandomSource.XO_RO_SHI_RO_128_PP.create();</code></pre></li>
<li>A generator can return a randomly selected element from a range of
possible values of some Java (primitive) type.
-<pre><code>boolean isOn = rng.nextBoolean(); // "true" or
"false".</code></pre>
-<pre><code>int n = rng.nextInt(); // Integer.MIN_VALUE <= n <=
Integer.MAX_VALUE.
+<pre class="prettyprint"><code>boolean isOn = rng.nextBoolean(); //
"true" or "false".</code></pre>
+<pre class="prettyprint"><code>int n = rng.nextInt(); //
Integer.MIN_VALUE <= n <= Integer.MAX_VALUE.
int m = rng.nextInt(max); // 0 <= m < max.
int l = rng.nextInt(min, max); // min <= l < max.</code></pre>
-<pre><code>long n = rng.nextLong(); // Long.MIN_VALUE <= n <=
Long.MAX_VALUE.
+<pre class="prettyprint"><code>long n = rng.nextLong(); //
Long.MIN_VALUE <= n <= Long.MAX_VALUE.
long m = rng.nextLong(max); // 0 <= m < max.
long l = rng.nextLong(min, max); // min <= l < max.</code></pre>
-<pre><code>float x = rng.nextFloat(); // 0 <= x < 1.
+<pre class="prettyprint"><code>float x = rng.nextFloat(); // 0 <= x
< 1.
float y = rng.nextFloat(max); // 0 <= y < max.
float z = rng.nextFloat(min, max); // min <= z < max.</code></pre>
-<pre><code>double x = rng.nextDouble(); // 0 <= x < 1.
+<pre class="prettyprint"><code>double x = rng.nextDouble(); // 0 <=
x < 1.
double y = rng.nextDouble(max); // 0 <= y < max.
double z = rng.nextDouble(min, max); // min <= z < max.</code></pre></li>
<li>A generator can fill a given <code>byte</code> array with random values.
-<pre><code>byte[] a = new byte[47];
+<pre class="prettyprint"><code>byte[] a = new byte[47];
// The elements of "a" are replaced with random values from the
interval [-128, 127].
rng.nextBytes(a);</code></pre>
-<pre><code>byte[] a = new byte[47];
+<pre class="prettyprint"><code>byte[] a = new byte[47];
// Replace 3 elements of the array (at indices 15, 16 and 17) with random
values.
rng.nextBytes(a, 15, 3);</code></pre></li>
<li>A generator can return a stream of primitive values.
-<pre><code>IntStream s1 = rng.ints(); // [Integer.MIN_VALUE,
Integer.MAX_VALUE]
+<pre class="prettyprint"><code>IntStream s1 = rng.ints(); //
[Integer.MIN_VALUE, Integer.MAX_VALUE]
IntStream s2 = rng.ints(max); // [0, max)
IntStream s3 = rng.ints(min, max); // [min, max)</code></pre>
-<pre><code>LongStream s1 = rng.longs(); // [Long.MIN_VALUE,
Long.MAX_VALUE]
+<pre class="prettyprint"><code>LongStream s1 = rng.longs(); //
[Long.MIN_VALUE, Long.MAX_VALUE]
LongStream s2 = rng.longs(max); // [0, max)
LongStream s3 = rng.longs(min, max); // [min, max)</code></pre>
-<pre><code>DoubleStream s1 = rng.doubles(); // [0, 1)
+<pre class="prettyprint"><code>DoubleStream s1 = rng.doubles(); // [0,
1)
DoubleStream s2 = rng.doubles(max); // [0, max)
DoubleStream s3 = rng.doubles(min, max); // [min, max)</code></pre>
<p>Streams can be limited by a stream size argument.</p>
-<pre><code>// Roll a die 1000 times
+<pre class="prettyprint"><code>// Roll a die 1000 times
int[] rolls = rng.ints(1000, 1, 7).toArray();</code></pre>
<p>It should be noted that streams returned by the interface default
implementation perform repeat calls to the relevant <code>next</code>
generation method and may have a performance overhead. Efficient streams can be
created using an instance of a sampler which can precompute coefficients on
construction (see the <a
href="../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/package-summary.html">sampling</a>
module).</p></li>
<li>The <code>UniformRandomProvider</code> interface provides default
implementations for all generation methods except <code>nextLong</code>.
Implementation of a new generator must only provide a 64-bit source of
randomness.
-<pre><code>UniformRandomProvider rng = new
SecureRandom()::nextLong;</code></pre>
+<pre class="prettyprint"><code>UniformRandomProvider rng = new
SecureRandom()::nextLong;</code></pre>
<p>Abstract classes for a 32-bit or 64-bit source of randomness, with
additional functionality not present in the interface, are provided in the <a
href="../commons-rng-core/apidocs/org/apache/commons/rng/core/package-summary.html">core</a>
module.</p></li>
<li>In order to generate reproducible sequences, generators must be
instantiated with a user-defined seed.
-<pre><code>UniformRandomProvider rng =
RandomSource.SPLIT_MIX_64.create(5776);</code></pre>
+<pre class="prettyprint"><code>UniformRandomProvider rng =
RandomSource.SPLIT_MIX_64.create(5776);</code></pre>
<p>If no seed is passed, a random seed is generated implicitly.</p>
<p>Convenience methods are provided for explicitly generating random seeds of
the various types.</p>
-<pre><code>int seed = RandomSource.createInt();</code></pre>
-<pre><code>long seed = RandomSource.createLong();</code></pre>
-<pre><code>int[] seed = RandomSource.createIntArray(128); // Length of
returned array is 128.</code></pre>
-<pre><code>long[] seed = RandomSource.createLongArray(128); // Length of
returned array is 128.</code></pre></li>
+<pre class="prettyprint"><code>int seed =
RandomSource.createInt();</code></pre>
+<pre class="prettyprint"><code>long seed =
RandomSource.createLong();</code></pre>
+<pre class="prettyprint"><code>int[] seed = RandomSource.createIntArray(128);
// Length of returned array is 128.</code></pre>
+<pre class="prettyprint"><code>long[] seed =
RandomSource.createLongArray(128); // Length of returned array is
128.</code></pre></li>
<li>Any of the following types can be passed to the <code>create</code> method
as the "seed" argument:
<ul>
<li><code>int</code> or <code>Integer</code></li>
@@ -336,9 +336,9 @@ int[] rolls = rng.ints(1000, 1, 7).toArr
<li><code>int[]</code></li>
<li><code>long[]</code></li>
<li><code>byte[]</code></li></ul>
-<pre><code>UniformRandomProvider rng =
RandomSource.ISAAC.create(5776);</code></pre>
-<pre><code>UniformRandomProvider rng = RandomSource.ISAAC.create(new int[] {
6, 7, 7, 5, 6, 1, 0, 2 });</code></pre>
-<pre><code>UniformRandomProvider rng = RandomSource.ISAAC.create(new long[] {
0x638a3fd83bc0e851L, 0x9730fd12c75ae247L });</code></pre>
+<pre class="prettyprint"><code>UniformRandomProvider rng =
RandomSource.ISAAC.create(5776);</code></pre>
+<pre class="prettyprint"><code>UniformRandomProvider rng =
RandomSource.ISAAC.create(new int[] { 6, 7, 7, 5, 6, 1, 0, 2 });</code></pre>
+<pre class="prettyprint"><code>UniformRandomProvider rng =
RandomSource.ISAAC.create(new long[] { 0x638a3fd83bc0e851L, 0x9730fd12c75ae247L
});</code></pre>
<p>Note however that, upon initialization, the underlying generation
algorithm</p>
<ul>
<li>may not use all the information contents of the seed,</li>
@@ -346,19 +346,19 @@ int[] rolls = rng.ints(1000, 1, 7).toArr
<p>In both cases, the behavior is not standard but should not change between
releases of the library (bugs notwithstanding).</p>
<p>Each RNG implementation has a single "native" seed; when the seed
argument passed to the <code>create</code> method is not of the native type, it
is automatically converted. The conversion preserves the information contents
but is otherwise not specified (i.e. different releases of the library may use
different conversion procedures).</p>
<p>Hence, if reproducibility of the generated sequences across successive
releases of the library is necessary, users should ensure that they use native
seeds.</p>
-<pre><code>long seed = 9246234616L;
+<pre class="prettyprint"><code>long seed = 9246234616L;
if (!RandomSource.TWO_CMRES.isNativeSeed(seed)) {
throw new IllegalArgumentException("Seed is not native");
}</code></pre>
<p>For each available implementation, the native seed type is specified in the
<a
href="../commons-rng-simple/apidocs/org/apache/commons/rng/simple/RandomSource.html#enum.constant.detail">Javadoc</a>.</p></li>
<li>Whenever a random source implementation is parameterized, the custom
arguments are passed after the seed.
-<pre><code>int seed = 96912062;
+<pre class="prettyprint"><code>int seed = 96912062;
int first = 7; // Subcycle identifier.
int second = 4; // Subcycle identifier.
UniformRandomProvider rng = RandomSource.TWO_CMRES_SELECT.create(seed, first,
second);</code></pre>
<p>In the above example, valid "subcycle identifiers" are in the
interval [0, 13].</p></li>
<li>The current state of a generator can be <a
href="../commons-rng-client-api/apidocs/org/apache/commons/rng/RestorableUniformRandomProvider.html#saveState--">saved</a>
and <a
href="../commons-rng-client-api/apidocs/org/apache/commons/rng/RestorableUniformRandomProvider.html#restoreState-org.apache.commons.rng.RandomProviderState-">restored</a>
later on.
-<pre><code>import org.apache.commons.rng.RestorableUniformRandomProvider;
+<pre class="prettyprint"><code>import
org.apache.commons.rng.RestorableUniformRandomProvider;
import org.apache.commons.rng.RandomProviderState;
RestorableUniformRandomProvider rng =
RandomSource.XO_RO_SHI_RO_128_PP.create();
@@ -368,7 +368,7 @@ rng.restoreState(state);
double y = rng.nextDouble(); // x == y.</code></pre></li>
<li>The <code>UniformRandomProvider</code> objects returned from the
<code>create</code> methods do not implement the
<code>java.io.Serializable</code> interface.
<p>However, users can easily set up a custom serialization scheme if the
random source is known at both ends of the communication channel. This would be
useful namely to save the state to persistent storage, and restore it such that
the sequence will continue from where it left off.</p>
-<pre><code>import org.apache.commons.rng.RestorableUniformRandomProvider;
+<pre class="prettyprint"><code>import
org.apache.commons.rng.RestorableUniformRandomProvider;
import org.apache.commons.rng.simple.RandomSource;
import org.apache.commons.rng.core.RandomProviderDefaultState;
@@ -392,7 +392,7 @@ RestorableUniformRandomProvider rngNew =
// Restore original state on the new instance.
rngNew.restoreState(stateNew);</code></pre></li>
<li>The <code>JumpableUniformRandomProvider</code> interface allows creation
of a copy of the generator and advances the state of the current generator a
large number of steps in a single jump. This can be used to create a set of
generators that will not overlap in their output sequence for the length of the
jump for use in parallel computations.
-<pre><code>import org.apache.commons.rng.UniformRandomProvider;
+<pre class="prettyprint"><code>import
org.apache.commons.rng.UniformRandomProvider;
import org.apache.commons.rng.JumpableUniformRandomProvider;
import org.apache.commons.rng.simple.RandomSource;
import java.util.concurrent.ForkJoinPool;
@@ -410,7 +410,7 @@ jumpable.jumps(streamSize).forEach(rng -
});</code></pre>
<p>Note that here the stream of RNGs is sequential; each RNG is used within a
potentially long-running task that can run concurrently with other tasks using
an executor service.</p></li>
<li>The <code>ArbitrarilyJumpableUniformRandomProvider</code> interface allows
creation of a copy of the generator and advances the state of the current
generator an <i>arbitrary</i> number of steps in a single jump. Jump distances
are supported using a <code>double</code> or using a power-of-2. Streams of
jumpable generators can be created using a <code>double</code> distance. Since
each copy generator is also an
<code>ArbitrarilyJumpableUniformRandomProvider</code> with care it is possible
to further distribute generators within the original jump distance and use the
entire state cycle in different ways.
-<pre><code>import org.apache.commons.rng.UniformRandomProvider;
+<pre class="prettyprint"><code>import
org.apache.commons.rng.UniformRandomProvider;
import org.apache.commons.rng.ArbitrarilyJumpableUniformRandomProvider;
import org.apache.commons.rng.simple.RandomSource;
@@ -446,7 +446,7 @@ copy.jumpPowerOfTwo(logDistance - 4);
// The copy matches the jumped generator
assert copy.nextLong() == jumpable.nextLong();</code></pre>
<p>In the above examples, the source is known to implement the appropriate
jumpable interface. Not all generators support this functionality. You can
determine if a <code>RandomSource</code> is jumpable without creating one using
the instance methods <code>isJumpable()</code>, <code>isLongJumpable()</code>
and <code>isArbitrarilyJumpable</code>.</p>
-<pre><code>import org.apache.commons.rng.simple.RandomSource;
+<pre class="prettyprint"><code>import
org.apache.commons.rng.simple.RandomSource;
public void initialise(RandomSource source) {
if (!source.isJumpable()) {
@@ -460,7 +460,7 @@ public void initialise(RandomSource sour
<li>The number of bits required to generate a random value differing from the
number of bits generated by the underlying source of randomness. For example
generation of a 64-bit <code>long</code> value using a 32-bit source of
randomness.</li></ul>
<p>Users are advised to use jumping generators with care to avoid overlapping
output of multiple generators in parallel computations. A cautious approach is
to use a jump distance far larger than the expected output length used by each
generator.</p></li>
<li>The <code>SplittableUniformRandomProvider</code> interface allows
splitting a generator into two objects (the original and a new instance) each
of which implements the same interface (and can be recursively split
indefinitely). This can be used for parallel computations where the number of
forks is unknown. These generators provide support for parallel streams. It
should be noted that in general creation of a new generator instance may result
in correlation of the output sequence with an existing generator. The
generators that support this interface have algorithms designed to minimise
correlation between instances. In particular the stream of generators provided
by recursive splitting of a parallel stream are robust to collision of their
sequence output.
-<pre><code>import org.apache.commons.rng.UniformRandomProvider;
+<pre class="prettyprint"><code>import
org.apache.commons.rng.UniformRandomProvider;
import org.apache.commons.rng.SplittableUniformRandomProvider;
import org.apache.commons.rng.simple.RandomSource;
@@ -475,7 +475,7 @@ jumpable.splits(streamSize).parallel().f
});</code></pre>
<p>Note that here the stream of RNGs is parallel; each RNG is used within a
potentially long-running task that can run concurrently with other tasks if the
enclosing stream parallel support utilises multiple threads.</p>
<p>In the above example, the source is known to implement the
<code>SplittableUniformRandomProvider</code> interface. Not all generators
support this functionality. You can determine if a <code>RandomSource</code> is
splittable without creating one using the instance method
<code>isSplittable()</code>.</p>
-<pre><code>import org.apache.commons.rng.simple.RandomSource;
+<pre class="prettyprint"><code>import
org.apache.commons.rng.simple.RandomSource;
public void initialise(RandomSource source) {
if (!source.isSplittable()) {
@@ -484,21 +484,21 @@ public void initialise(RandomSource sour
// ...
}</code></pre></li>
<li>Generation of <a href="./dist_density_approx.html">random deviates</a> for
various <a
href="../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/distribution/package-summary.html">distributions</a>.
-<pre><code>import
org.apache.commons.rng.sampling.distribution.ContinuousSampler;
+<pre class="prettyprint"><code>import
org.apache.commons.rng.sampling.distribution.ContinuousSampler;
import org.apache.commons.rng.sampling.distribution.GaussianSampler;
import org.apache.commons.rng.sampling.distribution.ZigguratSampler;
ContinuousSampler sampler =
GaussianSampler.of(ZigguratSampler.NormalizedGaussian.of(RandomSource.ISAAC.create()),
45.6, 2.3);
double random = sampler.sample();</code></pre>
-<pre><code>import org.apache.commons.rng.sampling.distribution.DiscreteSampler;
+<pre class="prettyprint"><code>import
org.apache.commons.rng.sampling.distribution.DiscreteSampler;
import
org.apache.commons.rng.sampling.distribution.RejectionInversionZipfSampler;
DiscreteSampler sampler =
RejectionInversionZipfSampler.of(RandomSource.ISAAC.create(),
5, 1.2);
int random = sampler.sample();</code></pre></li>
<li>Sampler interfaces are provided for generation of the primitive types
<code>int</code>, <code>long</code>, and <code>double</code> and objects of
type <code>T</code>. The <code>samples</code> method creates a stream of sample
values using the Java 8 streaming API:
-<pre><code>import org.apache.commons.rng.sampling.distribution.PoissonSampler;
+<pre class="prettyprint"><code>import
org.apache.commons.rng.sampling.distribution.PoissonSampler;
import org.apache.commons.rng.simple.RandomSource;
double mean = 15.5;
@@ -506,7 +506,7 @@ int streamSize = 100;
int[] counts = PoissonSampler.of(RandomSource.L64_X128_MIX.create(), mean)
.samples(streamSize)
.toArray();</code></pre>
-<pre><code>import org.apache.commons.rng.sampling.distribution.ZigguratSampler;
+<pre class="prettyprint"><code>import
org.apache.commons.rng.sampling.distribution.ZigguratSampler;
import org.apache.commons.rng.simple.RandomSource;
// Lower-truncated Normal distribution samples
@@ -517,7 +517,7 @@ double[] samples = ZigguratSampler.Norma
.limit(100)
.toArray();</code></pre></li>
<li>The <code>SharedStateSampler</code> interface allows creation of a copy of
the sampler using a new generator. The samplers share only their immutable
state and can be used in parallel computations.
-<pre><code>import org.apache.commons.rng.UniformRandomProvider;
+<pre class="prettyprint"><code>import
org.apache.commons.rng.UniformRandomProvider;
import
org.apache.commons.rng.sampling.distribution.MarsagliaTsangWangDiscreteSampler;
import org.apache.commons.rng.sampling.distribution.SharedStateDiscreteSampler;
import org.apache.commons.rng.simple.RandomSource;
@@ -532,7 +532,7 @@ SharedStateDiscreteSampler sampler1 = Ma
SharedStateDiscreteSampler sampler2 =
sampler1.withUniformRandomProvider(source.create());</code></pre>
<p>All samplers support the <code>SharedStateSampler</code> interface.</p></li>
<li><a
href="../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/PermutationSampler.html">Permutation</a>,
<a
href="../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/CombinationSampler.html">Combination</a>,
<a
href="../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/CollectionSampler.html">sampling
from a <code>Collection</code></a> and shuffling utilities.
-<pre><code>import org.apache.commons.rng.sampling.PermutationSampler;
+<pre class="prettyprint"><code>import
org.apache.commons.rng.sampling.PermutationSampler;
import org.apache.commons.rng.sampling.CombinationSampler;
// 3 elements from the (0, 1, 2, 3, 4, 5) tuplet.
@@ -550,7 +550,7 @@ CombinationSampler combinationSampler =
n, k);
// n! / (k! (n - k)!) = 20 combinations.
int[] combination = combinationSampler.sample();</code></pre>
-<pre><code>import java.util.HashSet;
+<pre class="prettyprint"><code>import java.util.HashSet;
import org.apache.commons.rng.sampling.CollectionSampler;
HashSet<String> elements = new HashSet<>();
@@ -561,7 +561,7 @@ elements.add("RNG");
CollectionSampler<String> sampler = new
CollectionSampler<>(RandomSource.MWC_256.create(),
elements);
String word = sampler.sample();</code></pre>
-<pre><code>import java.util.Arrays;
+<pre class="prettyprint"><code>import java.util.Arrays;
import java.util.List;
import org.apache.commons.rng.UniformRandomProvider;
import org.apache.commons.rng.sampling.ListSampler;
@@ -577,7 +577,7 @@ List<String> sample = ListSampler.
// Shuffle the list
ListSampler.shuffle(rng, list)</code></pre></li>
<li>Sampling from geometric shapes: <a
href="../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/shape/BoxSampler.html">Box</a>,
<a
href="../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/shape/UnitBallSampler.html">Ball</a>,
<a
href="../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/shape/LineSampler.html">Line</a>,
<a
href="../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/shape/TriangleSampler.html">Triangle</a>,
and <a
href="../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/shape/TetrahedronSampler.html">Tetrahedron</a>.
-<pre><code>import org.apache.commons.rng.sampling.shape.BoxSampler;
+<pre class="prettyprint"><code>import
org.apache.commons.rng.sampling.shape.BoxSampler;
double[] lower = {1, 2, 3};
double[] upper = {15, 16, 17};
@@ -587,7 +587,7 @@ double[] coordinate = sampler.sample();
double[][] coordinates =
sampler.samples(100).toArray(double[][]::new);</code></pre></li>
<li>The <a
href="../commons-rng-sampling/apidocs/org/apache/commons/rng/sampling/CompositeSamplers.html">CompositeSamplers</a>
utility class can create a composite sampler that is a weighted combination of
samplers that return the same type.
<p>The following example will create a sampler to uniformly sample the border
of a triangle using the line segment lengths as weights:</p>
-<pre><code>import org.apache.commons.rng.sampling.shape.LineSampler;
+<pre class="prettyprint"><code>import
org.apache.commons.rng.sampling.shape.LineSampler;
UniformRandomProvider rng = RandomSource.JSF_64.create();
