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 org.apache.commons.rng.JumpableUniformRandomProvider;
21 import org.apache.commons.rng.LongJumpableUniformRandomProvider;
22 import org.apache.commons.rng.UniformRandomProvider;
23 import org.apache.commons.rng.core.util.NumberFactory;
24
25 /**
26 * This abstract class is a base for algorithms from the Xor-Shift-Rotate family of 64-bit
27 * generators with 512-bits of state.
28 *
29 * @see <a href="http://xoshiro.di.unimi.it/">xorshiro / xoroshiro generators</a>
30 * @since 1.3
31 */
32 abstract class AbstractXoShiRo512 extends LongProvider implements LongJumpableUniformRandomProvider {
33 /** Size of the state vector. */
34 private static final int SEED_SIZE = 8;
35 /** The coefficients for the jump function. */
36 private static final long[] JUMP_COEFFICIENTS = {
37 0x33ed89b6e7a353f9L, 0x760083d7955323beL, 0x2837f2fbb5f22faeL, 0x4b8c5674d309511cL,
38 0xb11ac47a7ba28c25L, 0xf1be7667092bcc1cL, 0x53851efdb6df0aafL, 0x1ebbc8b23eaf25dbL
39 };
40 /** The coefficients for the long jump function. */
41 private static final long[] LONG_JUMP_COEFFICIENTS = {
42 0x11467fef8f921d28L, 0xa2a819f2e79c8ea8L, 0xa8299fc284b3959aL, 0xb4d347340ca63ee1L,
43 0x1cb0940bedbff6ceL, 0xd956c5c4fa1f8e17L, 0x915e38fd4eda93bcL, 0x5b3ccdfa5d7daca5L
44 };
45
46 // State is maintained using variables rather than an array for performance
47
48 /** State 0 of the generator. */
49 protected long state0;
50 /** State 1 of the generator. */
51 protected long state1;
52 /** State 2 of the generator. */
53 protected long state2;
54 /** State 3 of the generator. */
55 protected long state3;
56 /** State 4 of the generator. */
57 protected long state4;
58 /** State 5 of the generator. */
59 protected long state5;
60 /** State 6 of the generator. */
61 protected long state6;
62 /** State 7 of the generator. */
63 protected long state7;
64
65 /**
66 * Creates a new instance.
67 *
68 * @param seed Initial seed.
69 * If the length is larger than 8, only the first 8 elements will
70 * be used; if smaller, the remaining elements will be automatically
71 * set. A seed containing all zeros will create a non-functional generator.
72 */
73 AbstractXoShiRo512(long[] seed) {
74 if (seed.length < SEED_SIZE) {
75 final long[] state = new long[SEED_SIZE];
76 fillState(state, seed);
77 setState(state);
78 } else {
79 setState(seed);
80 }
81 }
82
83 /**
84 * Creates a new instance using an 8 element seed.
85 * A seed containing all zeros will create a non-functional generator.
86 *
87 * @param seed0 Initial seed element 0.
88 * @param seed1 Initial seed element 1.
89 * @param seed2 Initial seed element 2.
90 * @param seed3 Initial seed element 3.
91 * @param seed4 Initial seed element 4.
92 * @param seed5 Initial seed element 5.
93 * @param seed6 Initial seed element 6.
94 * @param seed7 Initial seed element 7.
95 */
96 AbstractXoShiRo512(long seed0, long seed1, long seed2, long seed3,
97 long seed4, long seed5, long seed6, long seed7) {
98 state0 = seed0;
99 state1 = seed1;
100 state2 = seed2;
101 state3 = seed3;
102 state4 = seed4;
103 state5 = seed5;
104 state6 = seed6;
105 state7 = seed7;
106 }
107
108 /**
109 * Creates a copy instance.
110 *
111 * @param source Source to copy.
112 */
113 protected AbstractXoShiRo512(AbstractXoShiRo512 source) {
114 super(source);
115 state0 = source.state0;
116 state1 = source.state1;
117 state2 = source.state2;
118 state3 = source.state3;
119 state4 = source.state4;
120 state5 = source.state5;
121 state6 = source.state6;
122 state7 = source.state7;
123 }
124
125 /**
126 * Copies the state from the array into the generator state.
127 *
128 * @param state the new state
129 */
130 private void setState(long[] state) {
131 state0 = state[0];
132 state1 = state[1];
133 state2 = state[2];
134 state3 = state[3];
135 state4 = state[4];
136 state5 = state[5];
137 state6 = state[6];
138 state7 = state[7];
139 }
140
141 /** {@inheritDoc} */
142 @Override
143 protected byte[] getStateInternal() {
144 return composeStateInternal(NumberFactory.makeByteArray(
145 new long[] {state0, state1, state2, state3,
146 state4, state5, state6, state7}),
147 super.getStateInternal());
148 }
149
150 /** {@inheritDoc} */
151 @Override
152 protected void setStateInternal(byte[] s) {
153 final byte[][] c = splitStateInternal(s, SEED_SIZE * 8);
154
155 setState(NumberFactory.makeLongArray(c[0]));
156
157 super.setStateInternal(c[1]);
158 }
159
160 /** {@inheritDoc} */
161 @Override
162 public long next() {
163 final long result = nextOutput();
164
165 final long t = state1 << 11;
166
167 state2 ^= state0;
168 state5 ^= state1;
169 state1 ^= state2;
170 state7 ^= state3;
171 state3 ^= state4;
172 state4 ^= state5;
173 state0 ^= state6;
174 state6 ^= state7;
175
176 state6 ^= t;
177
178 state7 = Long.rotateLeft(state7, 21);
179
180 return result;
181 }
182
183 /**
184 * Use the current state to compute the next output from the generator.
185 * The output function shall vary with respect to different generators.
186 * This method is called from {@link #next()} before the current state is updated.
187 *
188 * @return the next output
189 */
190 protected abstract long nextOutput();
191
192 /**
193 * {@inheritDoc}
194 *
195 * <p>The jump size is the equivalent of 2<sup>256</sup>
196 * calls to {@link UniformRandomProvider#nextLong() nextLong()}. It can provide
197 * up to 2<sup>256</sup> non-overlapping subsequences.</p>
198 */
199 @Override
200 public UniformRandomProvider jump() {
201 final UniformRandomProvider copy = copy();
202 performJump(JUMP_COEFFICIENTS);
203 return copy;
204 }
205
206 /**
207 * {@inheritDoc}
208 *
209 * <p>The jump size is the equivalent of 2<sup>384</sup> calls to
210 * {@link UniformRandomProvider#nextLong() nextLong()}. It can provide up to
211 * 2<sup>128</sup> non-overlapping subsequences of length 2<sup>384</sup>; each
212 * subsequence can provide up to 2<sup>128</sup> non-overlapping subsequences of
213 * length 2<sup>256</sup> using the {@link #jump()} method.</p>
214 */
215 @Override
216 public JumpableUniformRandomProvider longJump() {
217 final JumpableUniformRandomProvider copy = copy();
218 performJump(LONG_JUMP_COEFFICIENTS);
219 return copy;
220 }
221 /**
222 * Create a copy.
223 *
224 * @return the copy
225 */
226 protected abstract AbstractXoShiRo512 copy();
227
228 /**
229 * Perform the jump to advance the generator state. Resets the cached state of the generator.
230 *
231 * @param jumpCoefficients Jump coefficients.
232 */
233 private void performJump(long[] jumpCoefficients) {
234 long s0 = 0;
235 long s1 = 0;
236 long s2 = 0;
237 long s3 = 0;
238 long s4 = 0;
239 long s5 = 0;
240 long s6 = 0;
241 long s7 = 0;
242 for (final long jc : jumpCoefficients) {
243 for (int b = 0; b < 64; b++) {
244 if ((jc & (1L << b)) != 0) {
245 s0 ^= state0;
246 s1 ^= state1;
247 s2 ^= state2;
248 s3 ^= state3;
249 s4 ^= state4;
250 s5 ^= state5;
251 s6 ^= state6;
252 s7 ^= state7;
253 }
254 next();
255 }
256 }
257 state0 = s0;
258 state1 = s1;
259 state2 = s2;
260 state3 = s3;
261 state4 = s4;
262 state5 = s5;
263 state6 = s6;
264 state7 = s7;
265 resetCachedState();
266 }
267 }