View Javadoc
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.source32;
18  
19  import java.util.Arrays;
20  import org.apache.commons.rng.core.util.NumberFactory;
21  
22  /**
23   * Port from Marsaglia's <a href="https://en.wikipedia.org/wiki/Multiply-with-carry">
24   * "Multiply-With-Carry" algorithm</a>.
25   *
26   * <p>
27   * Implementation is based on the (non-portable!) C code reproduced on
28   * <a href="http://school.anhb.uwa.edu.au/personalpages/kwessen/shared/Marsaglia03.html">
29   * that page</a>.
30   * </p>
31   *
32   * @see <a href="https://en.wikipedia.org/wiki/Multiply-with-carry">Multiply with carry (Wikipedia)</a>
33   * @since 1.0
34   */
35  public class MultiplyWithCarry256 extends IntProvider {
36      /** Length of the state array. */
37      private static final int Q_SIZE = 256;
38      /** Size of the seed. */
39      private static final int SEED_SIZE = Q_SIZE + 1;
40      /** Multiply. */
41      private static final long A = 809430660;
42      /** State. */
43      private final int[] state = new int[Q_SIZE];
44      /** Current index in "state" array. */
45      private int index;
46      /** Carry. */
47      private int carry;
48  
49      /**
50       * Creates a new instance.
51       *
52       * @param seed Seed.
53       * If the length is larger than 257, only the first 257 elements will
54       * be used; if smaller, the remaining elements will be automatically
55       * set.
56       */
57      public MultiplyWithCarry256(int[] seed) {
58          setSeedInternal(seed);
59      }
60  
61      /** {@inheritDoc} */
62      @Override
63      protected byte[] getStateInternal() {
64          final int[] s = Arrays.copyOf(state, SEED_SIZE + 1);
65          s[SEED_SIZE - 1] = carry;
66          s[SEED_SIZE] = index;
67  
68          return NumberFactory.makeByteArray(s);
69      }
70  
71      /** {@inheritDoc} */
72      @Override
73      protected void setStateInternal(byte[] s) {
74          checkStateSize(s, (SEED_SIZE + 1) * 4);
75  
76          final int[] tmp = NumberFactory.makeIntArray(s);
77  
78          System.arraycopy(tmp, 0, state, 0, Q_SIZE);
79          carry = tmp[SEED_SIZE - 1];
80          index = tmp[SEED_SIZE];
81      }
82  
83      /**
84       * Seeds the RNG.
85       *
86       * @param seed Seed.
87       */
88      private void setSeedInternal(int[] seed) {
89          // Reset the whole state of this RNG (i.e. "state" and "index").
90          // Filling procedure is not part of the reference code.
91          final int[] tmp = new int[SEED_SIZE];
92          fillState(tmp, seed);
93  
94          // First element of the "seed" is the initial "carry".
95          final int c = tmp[0];
96          // Marsaglia's recommendation: 0 <= carry < A.
97          carry = (int) ((c < 0 ? -c : c) % A);
98  
99          // Initial state.
100         System.arraycopy(tmp, 1, state, 0, Q_SIZE);
101 
102         // Initial index.
103         index = Q_SIZE;
104     }
105 
106     /** {@inheritDoc} */
107     @Override
108     public int next() {
109         if (index == Q_SIZE) { // Whole state used up.
110             // Refill.
111             for (int i = 0; i < Q_SIZE; i++) {
112                 final long t = A * (state[i] & 0xffffffffL) + carry;
113                 carry = (int) (t >> 32);
114                 state[i] = (int) t;
115             }
116 
117             // Reset current index.
118             index = 0;
119         }
120 
121         return state[index++];
122     }
123 }