001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018package org.apache.commons.rng.core.source64;
019
020import java.util.stream.Stream;
021import org.apache.commons.rng.SplittableUniformRandomProvider;
022import org.apache.commons.rng.UniformRandomProvider;
023import org.apache.commons.rng.core.util.RandomStreams;
024
025/**
026 * A 64-bit all purpose generator.
027 *
028 * <p>This is a member of the LXM family of generators: L=Linear congruential generator;
029 * X=Xor based generator; and M=Mix. This member uses a 64-bit LCG and 128-bit Xor-based
030 * generator. It is named as {@code "L64X128StarStarRandom"} in the {@code java.util.random}
031 * package introduced in JDK 17; the LXM family is described in further detail in:
032 *
033 * <blockquote>Steele and Vigna (2021) LXM: better splittable pseudorandom number generators
034 * (and almost as fast). Proceedings of the ACM on Programming Languages, Volume 5,
035 * Article 148, pp 1–31.</blockquote>
036 *
037 * <p>Memory footprint is 256 bits and the period is 2<sup>64</sup> (2<sup>128</sup> - 1).
038 *
039 * <p>This generator implements
040 * {@link org.apache.commons.rng.LongJumpableUniformRandomProvider LongJumpableUniformRandomProvider}.
041 * In addition instances created with a different additive parameter for the LCG are robust
042 * against accidental correlation in a multi-threaded setting. The additive parameters must be
043 * different in the most significant 63-bits.
044 *
045 * @see <a href="https://doi.org/10.1145/3485525">Steele &amp; Vigna (2021) Proc. ACM Programming
046 *      Languages 5, 1-31</a>
047 * @see <a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/package-summary.html">
048 *      JDK 17 java.util.random javadoc</a>
049 * @since 1.5
050 */
051public class L64X128StarStar extends AbstractL64X128 implements SplittableUniformRandomProvider {
052    /**
053     * Creates a new instance.
054     *
055     * @param seed Initial seed.
056     * If the length is larger than 4, only the first 4 elements will
057     * be used; if smaller, the remaining elements will be automatically
058     * set. A seed containing all zeros in the last two elements
059     * will create a non-functional XBG sub-generator and a low
060     * quality output with a period of 2<sup>64</sup>.
061     *
062     * <p>The 1st element is used to set the LCG increment; the least significant bit
063     * is set to odd to ensure a full period LCG. The 2nd element is used
064     * to set the LCG state.</p>
065     */
066    public L64X128StarStar(long[] seed) {
067        super(seed);
068    }
069
070    /**
071     * Creates a new instance using a 4 element seed.
072     * A seed containing all zeros in the last two elements
073     * will create a non-functional XBG sub-generator and a low
074     * quality output with a period of 2<sup>64</sup>.
075     *
076     * <p>The 1st element is used to set the LCG increment; the least significant bit
077     * is set to odd to ensure a full period LCG. The 2nd element is used
078     * to set the LCG state.</p>
079     *
080     * @param seed0 Initial seed element 0.
081     * @param seed1 Initial seed element 1.
082     * @param seed2 Initial seed element 2.
083     * @param seed3 Initial seed element 3.
084     */
085    public L64X128StarStar(long seed0, long seed1, long seed2, long seed3) {
086        super(seed0, seed1, seed2, seed3);
087    }
088
089    /**
090     * Creates a copy instance.
091     *
092     * @param source Source to copy.
093     */
094    protected L64X128StarStar(L64X128StarStar source) {
095        super(source);
096    }
097
098    /** {@inheritDoc} */
099    @Override
100    public long next() {
101        // LXM generate.
102        // Old state is used for the output allowing parallel pipelining
103        // on processors that support multiple concurrent instructions.
104
105        final long s0 = x0;
106        final long s = ls;
107
108        // Mix
109        final long z = Long.rotateLeft((s + s0) * 5, 7) * 9;
110
111        // LCG update
112        ls = M * s + la;
113
114        // XBG update
115        long s1 = x1;
116
117        s1 ^= s0;
118        x0 = Long.rotateLeft(s0, 24) ^ s1 ^ (s1 << 16); // a, b
119        x1 = Long.rotateLeft(s1, 37); // c
120
121        return z;
122    }
123
124    /** {@inheritDoc} */
125    @Override
126    protected L64X128StarStar copy() {
127        // This exists to ensure the jump function performed in the super class returns
128        // the correct class type. It should not be public.
129        return new L64X128StarStar(this);
130    }
131
132    /** {@inheritDoc} */
133    @Override
134    public SplittableUniformRandomProvider split(UniformRandomProvider source) {
135        return create(source.nextLong(), source);
136    }
137
138    /** {@inheritDoc} */
139    @Override
140    public Stream<SplittableUniformRandomProvider> splits(long streamSize, SplittableUniformRandomProvider source) {
141        return RandomStreams.generateWithSeed(streamSize, source, L64X128StarStar::create);
142    }
143
144    /**
145     * Create a new instance using the given {@code seed} and {@code source} of randomness
146     * to initialise the instance.
147     *
148     * @param seed Seed used to initialise the instance.
149     * @param source Source of randomness used to initialise the instance.
150     * @return A new instance.
151     */
152    private static SplittableUniformRandomProvider create(long seed, UniformRandomProvider source) {
153        // LCG state. The addition uses the input seed.
154        // The LCG addition parameter is set to odd so left-shift the seed.
155        final long s0 = seed << 1;
156        final long s1 = source.nextLong();
157        // XBG state must not be all zero
158        long x0 = source.nextLong();
159        long x1 = source.nextLong();
160        if ((x0 | x1) == 0) {
161            // SplitMix style seed ensures at least one non-zero value
162            x0 = LXMSupport.lea64(s1);
163            x1 = LXMSupport.lea64(s1 + LXMSupport.GOLDEN_RATIO_64);
164        }
165        return new L64X128StarStar(s0, s1, x0, x1);
166    }
167}