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.JumpableUniformRandomProvider; 022import org.apache.commons.rng.SplittableUniformRandomProvider; 023import org.apache.commons.rng.UniformRandomProvider; 024import org.apache.commons.rng.core.util.NumberFactory; 025import org.apache.commons.rng.core.util.RandomStreams; 026 027/** 028 * A 64-bit all purpose generator. 029 * 030 * <p>This is a member of the LXM family of generators: L=Linear congruential generator; 031 * X=Xor based generator; and M=Mix. This member uses a 128-bit LCG and 256-bit Xor-based 032 * generator. It is named as {@code "L128X256MixRandom"} in the {@code java.util.random} 033 * package introduced in JDK 17; the LXM family is described in further detail in: 034 * 035 * <blockquote>Steele and Vigna (2021) LXM: better splittable pseudorandom number generators 036 * (and almost as fast). Proceedings of the ACM on Programming Languages, Volume 5, 037 * Article 148, pp 1–31.</blockquote> 038 * 039 * <p>Memory footprint is 512 bits and the period is 2<sup>128</sup> (2<sup>256</sup> - 1). 040 * 041 * <p>This generator implements 042 * {@link org.apache.commons.rng.LongJumpableUniformRandomProvider LongJumpableUniformRandomProvider}. 043 * In addition instances created with a different additive parameter for the LCG are robust 044 * against accidental correlation in a multi-threaded setting. The additive parameters must be 045 * different in the most significant 127-bits. 046 * 047 * <p>This generator implements 048 * {@link org.apache.commons.rng.SplittableUniformRandomProvider SplittableUniformRandomProvider}. 049 * The stream of generators created using the {@code splits} methods support parallelisation 050 * and are robust against accidental correlation by using unique values for the additive parameter 051 * for each instance in the same stream. The primitive streaming methods support parallelisation 052 * but with no assurances of accidental correlation; each thread uses a new instance with a 053 * randomly initialised state. 054 * 055 * @see <a href="https://doi.org/10.1145/3485525">Steele & Vigna (2021) Proc. ACM Programming 056 * Languages 5, 1-31</a> 057 * @see <a href="https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/random/package-summary.html"> 058 * JDK 17 java.util.random javadoc</a> 059 * @since 1.5 060 */ 061public class L128X256Mix extends AbstractL128 implements SplittableUniformRandomProvider { 062 /** Size of the seed vector. */ 063 private static final int SEED_SIZE = 8; 064 /** Size of the XBG state vector. */ 065 private static final int XBG_STATE_SIZE = 4; 066 /** Low half of 128-bit LCG multiplier. */ 067 private static final long ML = LXMSupport.M128L; 068 069 /** State 0 of the XBG. */ 070 private long x0; 071 /** State 1 of the XBG. */ 072 private long x1; 073 /** State 2 of the XBG. */ 074 private long x2; 075 /** State 3 of the XBG. */ 076 private long x3; 077 078 /** 079 * Creates a new instance. 080 * 081 * @param seed Initial seed. 082 * If the length is larger than 8, only the first 8 elements will 083 * be used; if smaller, the remaining elements will be automatically 084 * set. A seed containing all zeros in the last four elements 085 * will create a non-functional XBG sub-generator and a low 086 * quality output with a period of 2<sup>128</sup>. 087 * 088 * <p>The 1st and 2nd elements are used to set the LCG increment; the least significant bit 089 * is set to odd to ensure a full period LCG. The 3rd and 4th elements are used 090 * to set the LCG state.</p> 091 */ 092 public L128X256Mix(long[] seed) { 093 super(seed = extendSeed(seed, SEED_SIZE)); 094 x0 = seed[4]; 095 x1 = seed[5]; 096 x2 = seed[6]; 097 x3 = seed[7]; 098 } 099 100 /** 101 * Creates a new instance using an 8 element seed. 102 * A seed containing all zeros in the last four elements 103 * will create a non-functional XBG sub-generator and a low 104 * quality output with a period of 2<sup>128</sup>. 105 * 106 * <p>The 1st and 2nd elements are used to set the LCG increment; the least significant bit 107 * is set to odd to ensure a full period LCG. The 3rd and 4th elements are used 108 * to set the LCG state.</p> 109 * 110 * @param seed0 Initial seed element 0. 111 * @param seed1 Initial seed element 1. 112 * @param seed2 Initial seed element 2. 113 * @param seed3 Initial seed element 3. 114 * @param seed4 Initial seed element 4. 115 * @param seed5 Initial seed element 5. 116 * @param seed6 Initial seed element 6. 117 * @param seed7 Initial seed element 7. 118 */ 119 public L128X256Mix(long seed0, long seed1, long seed2, long seed3, 120 long seed4, long seed5, long seed6, long seed7) { 121 super(seed0, seed1, seed2, seed3); 122 x0 = seed4; 123 x1 = seed5; 124 x2 = seed6; 125 x3 = seed7; 126 } 127 128 /** 129 * Creates a copy instance. 130 * 131 * @param source Source to copy. 132 */ 133 protected L128X256Mix(L128X256Mix source) { 134 super(source); 135 x0 = source.x0; 136 x1 = source.x1; 137 x2 = source.x2; 138 x3 = source.x3; 139 } 140 141 /** {@inheritDoc} */ 142 @Override 143 protected byte[] getStateInternal() { 144 return composeStateInternal(NumberFactory.makeByteArray( 145 new long[] {x0, x1, x2, x3}), 146 super.getStateInternal()); 147 } 148 149 /** {@inheritDoc} */ 150 @Override 151 protected void setStateInternal(byte[] s) { 152 final byte[][] c = splitStateInternal(s, XBG_STATE_SIZE * Long.BYTES); 153 final long[] tmp = NumberFactory.makeLongArray(c[0]); 154 x0 = tmp[0]; 155 x1 = tmp[1]; 156 x2 = tmp[2]; 157 x3 = tmp[3]; 158 super.setStateInternal(c[1]); 159 } 160 161 /** {@inheritDoc} */ 162 @Override 163 public long next() { 164 // LXM generate. 165 // Old state is used for the output allowing parallel pipelining 166 // on processors that support multiple concurrent instructions. 167 168 long s0 = x0; 169 final long sh = lsh; 170 171 // Mix 172 final long z = LXMSupport.lea64(sh + s0); 173 174 // LCG update 175 // The LCG is, in effect, "s = m * s + a" where m = ((1LL << 64) + ML) 176 final long sl = lsl; 177 final long al = lal; 178 final long u = ML * sl; 179 // High half 180 lsh = ML * sh + LXMSupport.unsignedMultiplyHigh(ML, sl) + sl + lah + 181 // Carry propagation 182 LXMSupport.unsignedAddHigh(u, al); 183 // Low half 184 lsl = u + al; 185 186 // XBG update 187 long s1 = x1; 188 long s2 = x2; 189 long s3 = x3; 190 191 final long t = s1 << 17; 192 193 s2 ^= s0; 194 s3 ^= s1; 195 s1 ^= s2; 196 s0 ^= s3; 197 198 s2 ^= t; 199 200 s3 = Long.rotateLeft(s3, 45); 201 202 x0 = s0; 203 x1 = s1; 204 x2 = s2; 205 x3 = s3; 206 207 return z; 208 } 209 210 /** 211 * {@inheritDoc} 212 * 213 * <p>The jump size is the equivalent of moving the state <em>backwards</em> by 214 * (2<sup>256</sup> - 1) positions. It can provide up to 2<sup>128</sup> 215 * non-overlapping subsequences. 216 */ 217 @Override 218 public UniformRandomProvider jump() { 219 return super.jump(); 220 } 221 222 /** 223 * {@inheritDoc} 224 * 225 * <p>The jump size is the equivalent of moving the state <em>backwards</em> by 226 * 2<sup>64</sup> (2<sup>256</sup> - 1) positions. It can provide up to 227 * 2<sup>64</sup> non-overlapping subsequences of length 2<sup>64</sup> 228 * (2<sup>256</sup> - 1); each subsequence can provide up to 2<sup>64</sup> 229 * non-overlapping subsequences of length (2<sup>256</sup> - 1) using the 230 * {@link #jump()} method. 231 */ 232 @Override 233 public JumpableUniformRandomProvider longJump() { 234 return super.longJump(); 235 } 236 237 /** {@inheritDoc} */ 238 @Override 239 AbstractL128 copy() { 240 // This exists to ensure the jump function performed in the super class returns 241 // the correct class type. It should not be public. 242 return new L128X256Mix(this); 243 } 244 245 /** {@inheritDoc} */ 246 @Override 247 public SplittableUniformRandomProvider split(UniformRandomProvider source) { 248 return create(source.nextLong(), source); 249 } 250 251 /** {@inheritDoc} */ 252 @Override 253 public Stream<SplittableUniformRandomProvider> splits(long streamSize, SplittableUniformRandomProvider source) { 254 return RandomStreams.generateWithSeed(streamSize, source, L128X256Mix::create); 255 } 256 257 /** 258 * Create a new instance using the given {@code seed} and {@code source} of randomness 259 * to initialise the instance. 260 * 261 * @param seed Seed used to initialise the instance. 262 * @param source Source of randomness used to initialise the instance. 263 * @return A new instance. 264 */ 265 private static SplittableUniformRandomProvider create(long seed, UniformRandomProvider source) { 266 // LCG state. The addition lower-half uses the input seed. 267 // The LCG addition parameter is set to odd so left-shift the seed. 268 final long s0 = source.nextLong(); 269 final long s1 = seed << 1; 270 final long s2 = source.nextLong(); 271 final long s3 = source.nextLong(); 272 // XBG state must not be all zero 273 long x0 = source.nextLong(); 274 long x1 = source.nextLong(); 275 long x2 = source.nextLong(); 276 long x3 = source.nextLong(); 277 if ((x0 | x1 | x2 | x3) == 0) { 278 // SplitMix style seed ensures at least one non-zero value 279 long z = s3; 280 x0 = LXMSupport.lea64(z); 281 x1 = LXMSupport.lea64(z += LXMSupport.GOLDEN_RATIO_64); 282 x2 = LXMSupport.lea64(z += LXMSupport.GOLDEN_RATIO_64); 283 x3 = LXMSupport.lea64(z + LXMSupport.GOLDEN_RATIO_64); 284 } 285 // The LCG addition parameter is set to odd so left-shift the seed 286 return new L128X256Mix(s0, s1, s2, s3, x0, x1, x2, x3); 287 } 288}