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 package org.apache.commons.rng.core.source64;
18
19 import org.apache.commons.rng.core.util.NumberFactory;
20
21 /**
22 * A Permuted Congruential Generator (PCG) that is composed of a 64-bit Linear Congruential
23 * Generator (LCG) combined with the RXS-M-XS (random xorshift; multiply; xorshift) output
24 * transformation to create 64-bit output.
25 *
26 * <p>State size is 128 bits and the period is 2<sup>64</sup>.</p>
27 *
28 * <p><strong>Note:</strong> Although the seed size is 128 bits, only the first 64 are
29 * effective: in effect, two seeds that only differ by the last 64 bits may produce
30 * highly correlated sequences.
31 *
32 * @see <a href="http://www.pcg-random.org/">
33 * PCG, A Family of Better Random Number Generators</a>
34 * @since 1.3
35 */
36 public class PcgRxsMXs64 extends LongProvider {
37 /** Size of the seed array. */
38 private static final int SEED_SIZE = 2;
39 /** The default increment. */
40 private static final long DEFAULT_INCREMENT = 1442695040888963407L;
41
42 /** The state of the LCG. */
43 private long state;
44
45 /** The increment of the LCG. */
46 private long increment;
47
48 /**
49 * Creates a new instance using a default increment.
50 *
51 * @param seed Initial state.
52 * @since 1.4
53 */
54 public PcgRxsMXs64(Long seed) {
55 increment = DEFAULT_INCREMENT;
56 state = bump(seed + this.increment);
57 }
58
59 /**
60 * Creates a new instance.
61 *
62 * <p><strong>Note:</strong> Although the seed size is 128 bits, only the first 64 are
63 * effective: in effect, two seeds that only differ by the last 64 bits may produce
64 * highly correlated sequences.
65 *
66 * @param seed Initial seed.
67 * If the length is larger than 2, only the first 2 elements will
68 * be used; if smaller, the remaining elements will be automatically set.
69 *
70 * <p>The 1st element is used to set the LCG state. The 2nd element is used
71 * to set the LCG increment; the most significant bit
72 * is discarded by left shift and the increment is set to odd.</p>
73 */
74 public PcgRxsMXs64(long[] seed) {
75 if (seed.length < SEED_SIZE) {
76 final long[] tmp = new long[SEED_SIZE];
77 fillState(tmp, seed);
78 setSeedInternal(tmp);
79 } else {
80 setSeedInternal(seed);
81 }
82 }
83
84 /**
85 * Seeds the RNG.
86 *
87 * @param seed Seed.
88 */
89 private void setSeedInternal(long[] seed) {
90 // Ensure the increment is odd to provide a maximal period LCG.
91 this.increment = (seed[1] << 1) | 1;
92 this.state = bump(seed[0] + this.increment);
93 }
94
95 /**
96 * Provides the next state of the LCG.
97 *
98 * @param input Current state.
99 * @return next state
100 */
101 private long bump(long input) {
102 return input * 6364136223846793005L + increment;
103 }
104
105 /** {@inheritDoc} */
106 @Override
107 public long next() {
108 final long x = state;
109 state = bump(state);
110 final long word = ((x >>> ((x >>> 59) + 5)) ^ x) * -5840758589994634535L;
111 return (word >>> 43) ^ word;
112 }
113
114 /** {@inheritDoc} */
115 @Override
116 protected byte[] getStateInternal() {
117 // The increment is divided by 2 before saving.
118 // This transform is used in the reference PCG code; it prevents restoring from
119 // a byte state a non-odd increment that results in a sub-maximal period generator.
120 return composeStateInternal(NumberFactory.makeByteArray(
121 new long[] {state, increment >>> 1}),
122 super.getStateInternal());
123 }
124
125 /** {@inheritDoc} */
126 @Override
127 protected void setStateInternal(byte[] s) {
128 final byte[][] c = splitStateInternal(s, SEED_SIZE * 8);
129 final long[] tempseed = NumberFactory.makeLongArray(c[0]);
130 state = tempseed[0];
131 // Reverse the transform performed during getState to make the increment odd again.
132 increment = tempseed[1] << 1 | 1;
133 super.setStateInternal(c[1]);
134 }
135 }