1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package org.apache.commons.rng.core.source64; 19 20 import java.util.stream.Stream; 21 import org.apache.commons.rng.SplittableUniformRandomProvider; 22 import org.apache.commons.rng.UniformRandomProvider; 23 import org.apache.commons.rng.core.util.RandomStreams; 24 25 /** 26 * A 64-bit all purpose generator. 27 * 28 * <p>This is a member of the LXM family of generators: L=Linear congruential generator; 29 * X=Xor based generator; and M=Mix. This member uses a 64-bit LCG and 128-bit Xor-based 30 * generator. It is named as {@code "L64X128StarStarRandom"} in the {@code java.util.random} 31 * package introduced in JDK 17; the LXM family is described in further detail in: 32 * 33 * <blockquote>Steele and Vigna (2021) LXM: better splittable pseudorandom number generators 34 * (and almost as fast). Proceedings of the ACM on Programming Languages, Volume 5, 35 * Article 148, pp 1–31.</blockquote> 36 * 37 * <p>Memory footprint is 256 bits and the period is 2<sup>64</sup> (2<sup>128</sup> - 1). 38 * 39 * <p>This generator implements 40 * {@link org.apache.commons.rng.LongJumpableUniformRandomProvider LongJumpableUniformRandomProvider}. 41 * In addition instances created with a different additive parameter for the LCG are robust 42 * against accidental correlation in a multi-threaded setting. The additive parameters must be 43 * different in the most significant 63-bits. 44 * 45 * @see <a href="https://doi.org/10.1145/3485525">Steele & Vigna (2021) Proc. ACM Programming 46 * Languages 5, 1-31</a> 47 * @see <a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/package-summary.html"> 48 * JDK 17 java.util.random javadoc</a> 49 * @since 1.5 50 */ 51 public class L64X128StarStar extends AbstractL64X128 implements SplittableUniformRandomProvider { 52 /** 53 * Creates a new instance. 54 * 55 * @param seed Initial seed. 56 * If the length is larger than 4, only the first 4 elements will 57 * be used; if smaller, the remaining elements will be automatically 58 * set. A seed containing all zeros in the last two elements 59 * will create a non-functional XBG sub-generator and a low 60 * quality output with a period of 2<sup>64</sup>. 61 * 62 * <p>The 1st element is used to set the LCG increment; the least significant bit 63 * is set to odd to ensure a full period LCG. The 2nd element is used 64 * to set the LCG state.</p> 65 */ 66 public L64X128StarStar(long[] seed) { 67 super(seed); 68 } 69 70 /** 71 * Creates a new instance using a 4 element seed. 72 * A seed containing all zeros in the last two elements 73 * will create a non-functional XBG sub-generator and a low 74 * quality output with a period of 2<sup>64</sup>. 75 * 76 * <p>The 1st element is used to set the LCG increment; the least significant bit 77 * is set to odd to ensure a full period LCG. The 2nd element is used 78 * to set the LCG state.</p> 79 * 80 * @param seed0 Initial seed element 0. 81 * @param seed1 Initial seed element 1. 82 * @param seed2 Initial seed element 2. 83 * @param seed3 Initial seed element 3. 84 */ 85 public L64X128StarStar(long seed0, long seed1, long seed2, long seed3) { 86 super(seed0, seed1, seed2, seed3); 87 } 88 89 /** 90 * Creates a copy instance. 91 * 92 * @param source Source to copy. 93 */ 94 protected L64X128StarStar(L64X128StarStar source) { 95 super(source); 96 } 97 98 /** {@inheritDoc} */ 99 @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 }