From 6ddf4769919bb32cc43c5bf43e2f4e7526d3cda0 Mon Sep 17 00:00:00 2001 From: Gilles Date: Fri, 11 Mar 2016 01:51:58 +0100 Subject: [PATCH] MATH-1335. New package "o.a.c.m.rng" contains RNG core functionality (uniform distribution). Utilities to interface with stress test suites. Userguide: benchmarks and stress test suites reports (MATH-1327). --- .../commons/math4/rng/RandomSource.java | 417 ++ .../math4/rng/UniformRandomProvider.java | 118 + .../math4/rng/internal/BaseProvider.java | 141 + .../math4/rng/internal/ProviderBuilder.java | 346 ++ .../math4/rng/internal/StateSettable.java | 49 + .../math4/rng/internal/package-info.java | 51 + .../rng/internal/source32/AbstractWell.java | 208 + .../rng/internal/source32/ISAACRandom.java | 270 ++ .../rng/internal/source32/IntProvider.java | 137 + .../rng/internal/source32/JDKRandom.java | 95 + .../internal/source32/MersenneTwister.java | 230 + .../internal/source32/RandomIntSource.java | 30 + .../rng/internal/source32/Well1024a.java | 78 + .../rng/internal/source32/Well19937a.java | 80 + .../rng/internal/source32/Well19937c.java | 85 + .../rng/internal/source32/Well44497a.java | 83 + .../rng/internal/source32/Well44497b.java | 90 + .../math4/rng/internal/source32/Well512a.java | 78 + .../rng/internal/source32/package-info.java | 52 + .../rng/internal/source64/LongProvider.java | 141 + .../internal/source64/MersenneTwister64.java | 201 + .../internal/source64/RandomLongSource.java | 30 + .../rng/internal/source64/SplitMix64.java | 78 + .../math4/rng/internal/source64/TwoCmres.java | 310 ++ .../internal/source64/XorShift1024Star.java | 108 + .../rng/internal/source64/package-info.java | 52 + .../math4/rng/internal/util/Int2Long.java | 37 + .../math4/rng/internal/util/IntArray2Int.java | 41 + .../rng/internal/util/IntArray2LongArray.java | 44 + .../math4/rng/internal/util/Long2Int.java | 36 + .../rng/internal/util/Long2IntArray.java | 50 + .../rng/internal/util/Long2LongArray.java | 56 + .../rng/internal/util/LongArray2IntArray.java | 43 + .../rng/internal/util/LongArray2Long.java | 41 + .../math4/rng/internal/util/LongMixInt.java | 50 + .../math4/rng/internal/util/LongMixLong.java | 56 + .../rng/internal/util/NoOpConverter.java | 40 + .../rng/internal/util/NumberFactory.java | 327 ++ .../rng/internal/util/SeedConverter.java | 35 + .../internal/util/SeedConverterComposer.java | 56 + .../math4/rng/internal/util/SeedFactory.java | 262 ++ .../math4/rng/internal/util/package-info.java | 22 + .../commons/math4/rng/package-info.java | 95 + src/site/apt/userguide/rng.apt | 228 + .../txt/userguide/rng/stress/dh/run_1/dh_1 | 146 + .../txt/userguide/rng/stress/dh/run_1/dh_10 | 139 + .../txt/userguide/rng/stress/dh/run_1/dh_11 | 148 + .../txt/userguide/rng/stress/dh/run_1/dh_12 | 172 + .../txt/userguide/rng/stress/dh/run_1/dh_13 | 168 + .../txt/userguide/rng/stress/dh/run_1/dh_2 | 139 + .../txt/userguide/rng/stress/dh/run_1/dh_3 | 173 + .../txt/userguide/rng/stress/dh/run_1/dh_4 | 140 + .../txt/userguide/rng/stress/dh/run_1/dh_5 | 140 + .../txt/userguide/rng/stress/dh/run_1/dh_6 | 146 + .../txt/userguide/rng/stress/dh/run_1/dh_7 | 204 + .../txt/userguide/rng/stress/dh/run_1/dh_8 | 201 + .../txt/userguide/rng/stress/dh/run_1/dh_9 | 143 + .../txt/userguide/rng/stress/dh/run_2/dh_1 | 146 + .../txt/userguide/rng/stress/dh/run_2/dh_10 | 172 + .../txt/userguide/rng/stress/dh/run_2/dh_11 | 259 ++ .../txt/userguide/rng/stress/dh/run_2/dh_12 | 168 + .../txt/userguide/rng/stress/dh/run_2/dh_13 | 261 ++ .../txt/userguide/rng/stress/dh/run_2/dh_2 | 140 + .../txt/userguide/rng/stress/dh/run_2/dh_3 | 139 + .../txt/userguide/rng/stress/dh/run_2/dh_4 | 171 + .../txt/userguide/rng/stress/dh/run_2/dh_5 | 143 + .../txt/userguide/rng/stress/dh/run_2/dh_6 | 260 ++ .../txt/userguide/rng/stress/dh/run_2/dh_7 | 143 + .../txt/userguide/rng/stress/dh/run_2/dh_8 | 800 ++++ .../txt/userguide/rng/stress/dh/run_2/dh_9 | 175 + .../txt/userguide/rng/stress/tu/run_1/tu_1 | 3882 +++++++++++++++++ .../txt/userguide/rng/stress/tu/run_1/tu_10 | 3803 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_1/tu_11 | 3795 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_1/tu_12 | 3803 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_1/tu_13 | 3802 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_1/tu_2 | 3803 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_1/tu_3 | 3807 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_1/tu_4 | 3806 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_1/tu_5 | 3804 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_1/tu_6 | 3804 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_1/tu_7 | 3803 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_1/tu_8 | 3804 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_1/tu_9 | 3802 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_2/tu_1 | 3879 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_2/tu_10 | 3803 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_2/tu_11 | 3795 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_2/tu_12 | 3795 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_2/tu_13 | 3795 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_2/tu_2 | 3803 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_2/tu_3 | 3808 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_2/tu_4 | 3805 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_2/tu_5 | 3804 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_2/tu_6 | 3803 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_2/tu_7 | 3803 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_2/tu_8 | 3803 ++++++++++++++++ .../txt/userguide/rng/stress/tu/run_2/tu_9 | 3795 ++++++++++++++++ src/site/site.xml | 1 + src/site/xdoc/userguide/index.xml | 7 + .../math4/rng/Providers32ParametricTest.java | 64 + .../math4/rng/Providers64ParametricTest.java | 64 + .../rng/ProvidersCommonParametricTest.java | 667 +++ .../commons/math4/rng/ProvidersList.java | 157 + .../internal/source32/ISAACRandomTest.java | 389 ++ .../rng/internal/source32/JDKRandomTest.java | 38 + .../source32/MersenneTwisterTest.java | 240 + .../rng/internal/source32/Well1024aTest.java | 71 + .../rng/internal/source32/Well19937aTest.java | 109 + .../rng/internal/source32/Well19937cTest.java | 109 + .../rng/internal/source32/Well44497aTest.java | 109 + .../rng/internal/source32/Well44497bTest.java | 109 + .../rng/internal/source32/Well512aTest.java | 69 + .../source64/MersenneTwister64Test.java | 239 + .../rng/internal/source64/SplitMix64Test.java | 45 + .../rng/internal/source64/TwoCmresTest.java | 55 + .../source64/XorShift1024StarTest.java | 55 + .../rng/internal/util/NumberFactoryTest.java | 164 + .../rng/internal/util/SeedFactoryTest.java | 111 + src/userguide/README | 15 +- src/userguide/c/rng/stdin2testu01.c | 127 + .../math4/userguide/rng/GeneratorsList.java | 57 + .../userguide/rng/RandomStressTester.java | 280 ++ src/userguide/pom.xml | 30 + 122 files changed, 112502 insertions(+), 1 deletion(-) create mode 100644 src/main/java/org/apache/commons/math4/rng/RandomSource.java create mode 100644 src/main/java/org/apache/commons/math4/rng/UniformRandomProvider.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/BaseProvider.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/ProviderBuilder.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/StateSettable.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/package-info.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/source32/AbstractWell.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/source32/ISAACRandom.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/source32/IntProvider.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/source32/JDKRandom.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/source32/MersenneTwister.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/source32/RandomIntSource.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/source32/Well1024a.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/source32/Well19937a.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/source32/Well19937c.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/source32/Well44497a.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/source32/Well44497b.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/source32/Well512a.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/source32/package-info.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/source64/LongProvider.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/source64/MersenneTwister64.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/source64/RandomLongSource.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/source64/SplitMix64.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/source64/TwoCmres.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/source64/XorShift1024Star.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/source64/package-info.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/util/Int2Long.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/util/IntArray2Int.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/util/IntArray2LongArray.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/util/Long2Int.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/util/Long2IntArray.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/util/Long2LongArray.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/util/LongArray2IntArray.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/util/LongArray2Long.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/util/LongMixInt.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/util/LongMixLong.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/util/NoOpConverter.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/util/NumberFactory.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/util/SeedConverter.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/util/SeedConverterComposer.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/util/SeedFactory.java create mode 100644 src/main/java/org/apache/commons/math4/rng/internal/util/package-info.java create mode 100644 src/main/java/org/apache/commons/math4/rng/package-info.java create mode 100644 src/site/apt/userguide/rng.apt create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_1/dh_1 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_1/dh_10 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_1/dh_11 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_1/dh_12 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_1/dh_13 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_1/dh_2 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_1/dh_3 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_1/dh_4 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_1/dh_5 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_1/dh_6 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_1/dh_7 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_1/dh_8 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_1/dh_9 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_2/dh_1 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_2/dh_10 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_2/dh_11 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_2/dh_12 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_2/dh_13 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_2/dh_2 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_2/dh_3 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_2/dh_4 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_2/dh_5 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_2/dh_6 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_2/dh_7 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_2/dh_8 create mode 100644 src/site/resources/txt/userguide/rng/stress/dh/run_2/dh_9 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_1/tu_1 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_1/tu_10 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_1/tu_11 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_1/tu_12 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_1/tu_13 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_1/tu_2 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_1/tu_3 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_1/tu_4 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_1/tu_5 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_1/tu_6 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_1/tu_7 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_1/tu_8 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_1/tu_9 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_2/tu_1 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_2/tu_10 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_2/tu_11 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_2/tu_12 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_2/tu_13 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_2/tu_2 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_2/tu_3 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_2/tu_4 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_2/tu_5 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_2/tu_6 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_2/tu_7 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_2/tu_8 create mode 100644 src/site/resources/txt/userguide/rng/stress/tu/run_2/tu_9 create mode 100644 src/test/java/org/apache/commons/math4/rng/Providers32ParametricTest.java create mode 100644 src/test/java/org/apache/commons/math4/rng/Providers64ParametricTest.java create mode 100644 src/test/java/org/apache/commons/math4/rng/ProvidersCommonParametricTest.java create mode 100644 src/test/java/org/apache/commons/math4/rng/ProvidersList.java create mode 100644 src/test/java/org/apache/commons/math4/rng/internal/source32/ISAACRandomTest.java create mode 100644 src/test/java/org/apache/commons/math4/rng/internal/source32/JDKRandomTest.java create mode 100644 src/test/java/org/apache/commons/math4/rng/internal/source32/MersenneTwisterTest.java create mode 100644 src/test/java/org/apache/commons/math4/rng/internal/source32/Well1024aTest.java create mode 100644 src/test/java/org/apache/commons/math4/rng/internal/source32/Well19937aTest.java create mode 100644 src/test/java/org/apache/commons/math4/rng/internal/source32/Well19937cTest.java create mode 100644 src/test/java/org/apache/commons/math4/rng/internal/source32/Well44497aTest.java create mode 100644 src/test/java/org/apache/commons/math4/rng/internal/source32/Well44497bTest.java create mode 100644 src/test/java/org/apache/commons/math4/rng/internal/source32/Well512aTest.java create mode 100644 src/test/java/org/apache/commons/math4/rng/internal/source64/MersenneTwister64Test.java create mode 100644 src/test/java/org/apache/commons/math4/rng/internal/source64/SplitMix64Test.java create mode 100644 src/test/java/org/apache/commons/math4/rng/internal/source64/TwoCmresTest.java create mode 100644 src/test/java/org/apache/commons/math4/rng/internal/source64/XorShift1024StarTest.java create mode 100644 src/test/java/org/apache/commons/math4/rng/internal/util/NumberFactoryTest.java create mode 100644 src/test/java/org/apache/commons/math4/rng/internal/util/SeedFactoryTest.java create mode 100644 src/userguide/c/rng/stdin2testu01.c create mode 100644 src/userguide/java/org/apache/commons/math4/userguide/rng/GeneratorsList.java create mode 100644 src/userguide/java/org/apache/commons/math4/userguide/rng/RandomStressTester.java diff --git a/src/main/java/org/apache/commons/math4/rng/RandomSource.java b/src/main/java/org/apache/commons/math4/rng/RandomSource.java new file mode 100644 index 000000000..087960cdd --- /dev/null +++ b/src/main/java/org/apache/commons/math4/rng/RandomSource.java @@ -0,0 +1,417 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.commons.math4.rng; + +import org.apache.commons.math4.exception.MathUnsupportedOperationException; +import org.apache.commons.math4.rng.internal.ProviderBuilder; +import org.apache.commons.math4.rng.internal.BaseProvider; +import org.apache.commons.math4.rng.internal.util.SeedFactory; +import org.apache.commons.math4.rng.internal.source64.TwoCmres; + +/** + * This class provides the API for creating generators of random numbers. + *

+ * Usage examples: + *


+ *  UniformRandomProvider rng = RandomSource.create(RandomSource.MT);
+ * 
+ * or + *

+ *  final int[] seed = new int[] { 196, 9, 0, 226  };
+ *  UniformRandomProvider rng = RandomSource.create(RandomSource.MT, seed);
+ * 
+ * or + *

+ *  final int[] seed = RandomSource.createIntArray(256);
+ *  UniformRandomProvider rng = RandomSource.create(RandomSource.MT, seed);
+ * 
+ * where the first argument to method {@code create} is the identifier + * of the generator's concrete implementation, and the second the is the + * (optional) seed. + *
+ * In the first form, a random seed will be {@link SeedFactory generated + * automatically}; the random seed generation step is explicit in the + * third form. + *

+ * + *

+ * Seeding is the procedure by which a value (or set of values) is + * used to initialize a generator instance. + * The requirement that a given seed will always result in the same + * internal state allows to create different instances of a generator + * that will produce the same sequence of pseudo-random numbers. + *

+ * + *

+ * The type of data used as a seed depends on the concrete implementation + * as some types may not provide enough information to fully initialize + * the generator's internal state. + *
+ * The reference algorithm's seeding procedure (if provided) operates + * on a value of a (single) native type: + * Each concrete implementation's constructor creates an instance using + * the native type whose information contents is used to set the + * internal state. + *
+ * When the seed value passed by the caller is of the native type, it is + * expected that the sequences produced will be the same as those + * produced by other implementations of the algorithm. + *
+ * However, when the seed value passed by the caller is not of the native + * type, a transformation is performed by this library and the resulting + * native type value will not contain more information than the + * original seed value. + * If the algorithm's native type is "simpler" than the type passed by + * the caller, then some (unuse) information will even be lost. + *
+ * The transformation from non-native to native seed type is arbitrary, + * as long as it does not reduce the amount of information required by + * the algorithm to initialize its state. + * The consequence of the transformation is that the sequences produced + * by this library may not be the same as the sequences produced by other + * implementations of the same algorithm! + *

+ * + *

+ * This class provides methods to generate random seeds (single values + * or arrays of values, of {@code int} or {@code long} types) that can + * be passed to the {@link RandomSource#create(RandomSource,Object,Object[]) + * generators factory method}. + *
+ * Although the seed-generating methods defined in this class will likely + * return different values for all calls, there is no guarantee that the + * produced seed will result always in a "good" sequence of numbers, even + * if the generator is good. + * The only way to ensure that the selected seed will make the generator + * produce a "good" sequence is to submit that sequence to a series of + * stringent tests, as provided by tools such as + * dieharder + * or TestU01. + *

+ * + *

+ * The current implementations have no provision for producing non-overlapping + * sequences. + * For parallel applications, a possible workaround is that each thread uses + * a generator of a different type (see {@link #TWO_CMRES_SELECT}). + *

+ * + *

+ * Note: + * Seeding is not equivalent to restoring the internal state of an + * already initialized generator. + * Indeed, generators can have a state that is more complex than the + * seed, and seeding is thus a transformation (from seed to state). + * Implementations do not provide the inverse transformation (from + * state to seed), hence it is not generally possible to know the seed + * that would initialize a new generator instance to the current state + * of another instance. + * Reseeding is also inefficient if the purpose is to continue the + * same sequence where another instance left off, as it would require + * to "replay" all the calls performed by that other instance (and it + * would require to know the number of calls to the primary source of + * randomness, which is also not usually accessible). + *
+ * This factory thus provides a method for + * {@link #saveState(UniformRandomProvider) saving} the internal + * state of a generator. + * The state is encapsulated in an {@link State "opaque object"} to be + * used for {@link #restoreState(UniformRandomProvider,State) restoring} + * a generator (of the same type) to an identical state (e.g. to allow + * persistent storage, or to continue a sequence from where the original + * instance left off.). + *

+ * + * @since 4.0 + */ +public enum RandomSource { + /** + * Source of randomness is {@link org.apache.commons.math4.rng.internal.source32.JDKRandom}. + * Native seed type: {@code Long}. + */ + JDK(ProviderBuilder.RandomSourceInternal.JDK), + /** + * Source of randomness is {@link org.apache.commons.math4.rng.internal.source32.Well512a}. + * Native seed type: {@code int[]}. + */ + WELL_512_A(ProviderBuilder.RandomSourceInternal.WELL_512_A), + /** + * Source of randomness is {@link org.apache.commons.math4.rng.internal.source32.Well1024a}. + * Native seed type: {@code int[]}. + */ + WELL_1024_A(ProviderBuilder.RandomSourceInternal.WELL_1024_A), + /** + * Source of randomness is {@link org.apache.commons.math4.rng.internal.source32.Well19937a}. + * Native seed type: {@code int[]}. + */ + WELL_19937_A(ProviderBuilder.RandomSourceInternal.WELL_19937_A), + /** + * Source of randomness is {@link org.apache.commons.math4.rng.internal.source32.Well19937c}. + * Native seed type: {@code int[]}. + */ + WELL_19937_C(ProviderBuilder.RandomSourceInternal.WELL_19937_C), + /** + * Source of randomness is {@link org.apache.commons.math4.rng.internal.source32.Well44497a}. + * Native seed type: {@code int[]}. + */ + WELL_44497_A(ProviderBuilder.RandomSourceInternal.WELL_44497_A), + /** + * Source of randomness is {@link org.apache.commons.math4.rng.internal.source32.Well44497b}. + * Native seed type: {@code int[]}. + */ + WELL_44497_B(ProviderBuilder.RandomSourceInternal.WELL_44497_B), + /** + * Source of randomness is {@link org.apache.commons.math4.rng.internal.source32.MersenneTwister}. + * Native seed type: {@code int[]}. + */ + MT(ProviderBuilder.RandomSourceInternal.MT), + /** + * Source of randomness is {@link org.apache.commons.math4.rng.internal.source32.ISAACRandom}. + * Native seed type: {@code int[]}. + */ + ISAAC(ProviderBuilder.RandomSourceInternal.ISAAC), + /** + * Source of randomness is {@link org.apache.commons.math4.rng.internal.source64.SplitMix64}. + * Native seed type: {@code Long}. + */ + SPLIT_MIX_64(ProviderBuilder.RandomSourceInternal.SPLIT_MIX_64), + /** + * Source of randomness is {@link org.apache.commons.math4.rng.internal.source64.XorShift1024Star}. + * Native seed type: {@code long[]}. + */ + XOR_SHIFT_1024_S(ProviderBuilder.RandomSourceInternal.XOR_SHIFT_1024_S), + /** + * Source of randomness is {@link org.apache.commons.math4.rng.internal.source64.TwoCmres}. + * Native seed type: {@code Integer}. + */ + TWO_CMRES(ProviderBuilder.RandomSourceInternal.TWO_CMRES), + /** + * Source of randomness is {@link org.apache.commons.math4.rng.internal.source64.TwoCmres}, + * with explicit selection of the two subcycle generators. + * Native seed type: {@code Integer}. + */ + TWO_CMRES_SELECT(ProviderBuilder.RandomSourceInternal.TWO_CMRES_SELECT), + /** + * Source of randomness is {@link org.apache.commons.math4.rng.internal.source64.MersenneTwister64}. + * Native seed type: {@code long[]}. + */ + MT_64(ProviderBuilder.RandomSourceInternal.MT_64); + + /** Internal identifier. */ + private final ProviderBuilder.RandomSourceInternal internalIdentifier; + + /** + * @param id Internal identifier. + */ + RandomSource(ProviderBuilder.RandomSourceInternal id) { + internalIdentifier = id; + } + + /** + * @return the internal identifier. + */ + ProviderBuilder.RandomSourceInternal getInternalIdentifier() { + return internalIdentifier; + } + + /** + * Checks whether the type of given {@code seed} is the native type + * of the implementation. + * + * @param seed Seed value. + * @return {@code true} if the seed can be passed to the builder + * for this RNG type. + */ + public boolean isNativeSeed(Object seed) { + return internalIdentifier.isNativeSeed(seed); + } + + /** + * Marker interface used to define the "save" and "restore" + * functionality of the generators. + */ + public interface State {} + + /** + * Creates a random number generator with a random seed. + * + *

+ * Example of usage: + *


+     *  UniformRandomProvider rng = RandomSource.create(Source.MT);
+     * 
+ *

+ * + * @param source {@link RandomSource RNG type}. + * @return the RNG. + */ + public static UniformRandomProvider create(RandomSource source) { + return create(source, null); + } + + /** + * Creates a random number generator with the given {@code seed}. + * + *

+ * Example of usage: + *


+     *  UniformRandomProvider rng = RandomSource.create(Source.TWO_CMRES_SELECT, 26219, 6, 9);
+     * 
+ *

+ * + *

+ * Valid types for the {@code seed} are: + *

+ *

+ * + *

+ * Notes: + *