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 */
017package org.apache.commons.math3.random;
018
019import java.io.Serializable;
020
021import org.apache.commons.math3.exception.NotStrictlyPositiveException;
022import org.apache.commons.math3.util.FastMath;
023
024/** Base class for random number generators that generates bits streams.
025 *
026 * @version $Id: BitsStreamGenerator.java 1454897 2013-03-10 19:02:54Z luc $
027 * @since 2.0
028 */
029public abstract class BitsStreamGenerator
030    implements RandomGenerator,
031               Serializable {
032    /** Serializable version identifier */
033    private static final long serialVersionUID = 20130104L;
034    /** Next gaussian. */
035    private double nextGaussian;
036
037    /**
038     * Creates a new random number generator.
039     */
040    public BitsStreamGenerator() {
041        nextGaussian = Double.NaN;
042    }
043
044    /** {@inheritDoc} */
045    public abstract void setSeed(int seed);
046
047    /** {@inheritDoc} */
048    public abstract void setSeed(int[] seed);
049
050    /** {@inheritDoc} */
051    public abstract void setSeed(long seed);
052
053    /** Generate next pseudorandom number.
054     * <p>This method is the core generation algorithm. It is used by all the
055     * public generation methods for the various primitive types {@link
056     * #nextBoolean()}, {@link #nextBytes(byte[])}, {@link #nextDouble()},
057     * {@link #nextFloat()}, {@link #nextGaussian()}, {@link #nextInt()},
058     * {@link #next(int)} and {@link #nextLong()}.</p>
059     * @param bits number of random bits to produce
060     * @return random bits generated
061     */
062    protected abstract int next(int bits);
063
064    /** {@inheritDoc} */
065    public boolean nextBoolean() {
066        return next(1) != 0;
067    }
068
069    /** {@inheritDoc} */
070    public void nextBytes(byte[] bytes) {
071        int i = 0;
072        final int iEnd = bytes.length - 3;
073        while (i < iEnd) {
074            final int random = next(32);
075            bytes[i]     = (byte) (random & 0xff);
076            bytes[i + 1] = (byte) ((random >>  8) & 0xff);
077            bytes[i + 2] = (byte) ((random >> 16) & 0xff);
078            bytes[i + 3] = (byte) ((random >> 24) & 0xff);
079            i += 4;
080        }
081        int random = next(32);
082        while (i < bytes.length) {
083            bytes[i++] = (byte) (random & 0xff);
084            random     = random >> 8;
085        }
086    }
087
088    /** {@inheritDoc} */
089    public double nextDouble() {
090        final long high = ((long) next(26)) << 26;
091        final int  low  = next(26);
092        return (high | low) * 0x1.0p-52d;
093    }
094
095    /** {@inheritDoc} */
096    public float nextFloat() {
097        return next(23) * 0x1.0p-23f;
098    }
099
100    /** {@inheritDoc} */
101    public double nextGaussian() {
102
103        final double random;
104        if (Double.isNaN(nextGaussian)) {
105            // generate a new pair of gaussian numbers
106            final double x = nextDouble();
107            final double y = nextDouble();
108            final double alpha = 2 * FastMath.PI * x;
109            final double r      = FastMath.sqrt(-2 * FastMath.log(y));
110            random       = r * FastMath.cos(alpha);
111            nextGaussian = r * FastMath.sin(alpha);
112        } else {
113            // use the second element of the pair already generated
114            random = nextGaussian;
115            nextGaussian = Double.NaN;
116        }
117
118        return random;
119
120    }
121
122    /** {@inheritDoc} */
123    public int nextInt() {
124        return next(32);
125    }
126
127    /**
128     * {@inheritDoc}
129     * <p>This default implementation is copied from Apache Harmony
130     * java.util.Random (r929253).</p>
131     *
132     * <p>Implementation notes: <ul>
133     * <li>If n is a power of 2, this method returns
134     * {@code (int) ((n * (long) next(31)) >> 31)}.</li>
135     *
136     * <li>If n is not a power of 2, what is returned is {@code next(31) % n}
137     * with {@code next(31)} values rejected (i.e. regenerated) until a
138     * value that is larger than the remainder of {@code Integer.MAX_VALUE / n}
139     * is generated. Rejection of this initial segment is necessary to ensure
140     * a uniform distribution.</li></ul></p>
141     */
142    public int nextInt(int n) throws IllegalArgumentException {
143        if (n > 0) {
144            if ((n & -n) == n) {
145                return (int) ((n * (long) next(31)) >> 31);
146            }
147            int bits;
148            int val;
149            do {
150                bits = next(31);
151                val = bits % n;
152            } while (bits - val + (n - 1) < 0);
153            return val;
154        }
155        throw new NotStrictlyPositiveException(n);
156    }
157
158    /** {@inheritDoc} */
159    public long nextLong() {
160        final long high  = ((long) next(32)) << 32;
161        final long  low  = ((long) next(32)) & 0xffffffffL;
162        return high | low;
163    }
164
165    /**
166     * Returns a pseudorandom, uniformly distributed <tt>long</tt> value
167     * between 0 (inclusive) and the specified value (exclusive), drawn from
168     * this random number generator's sequence.
169     *
170     * @param n the bound on the random number to be returned.  Must be
171     * positive.
172     * @return  a pseudorandom, uniformly distributed <tt>long</tt>
173     * value between 0 (inclusive) and n (exclusive).
174     * @throws IllegalArgumentException  if n is not positive.
175     */
176    public long nextLong(long n) throws IllegalArgumentException {
177        if (n > 0) {
178            long bits;
179            long val;
180            do {
181                bits = ((long) next(31)) << 32;
182                bits = bits | (((long) next(32)) & 0xffffffffL);
183                val  = bits % n;
184            } while (bits - val + (n - 1) < 0);
185            return val;
186        }
187        throw new NotStrictlyPositiveException(n);
188    }
189
190    /**
191     * Clears the cache used by the default implementation of
192     * {@link #nextGaussian}.
193     */
194    public void clear() {
195        nextGaussian = Double.NaN;
196    }
197
198}