View Javadoc

1   /*
2    * Copyright 2005 The Apache Software Foundation.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.commons.math.random;
17  
18  /**
19   * Abstract class implementing the {@link  RandomGenerator} interface.
20   * Default implementations for all methods other than {@link #nextDouble()} and
21   * {@link #setSeed(long)} are provided. 
22   * <p>
23   * All data generation methods are based on <code>nextDouble().</code>
24   * Concrete implementations <strong>must</strong> override
25   * this method and <strong>should</strong> provide better / more
26   * performant implementations of the other methods if the underlying PRNG
27   * supplies them.
28   *
29   * @since 1.1
30   * @version $Revision: 209144 $ $Date: 2005-07-04 16:30:05 -0700 (Mon, 04 Jul 2005) $
31   */
32  public abstract class AbstractRandomGenerator implements RandomGenerator {
33      
34      /** 
35       * Cached random normal value.  The default implementation for 
36       * {@link #nextGaussian} generates pairs of values and this field caches the
37       * second value so that the full algorithm is not executed for every
38       * activation.  The value <code>Double.NaN</code> signals that there is
39       * no cached value.  Use {@link #clear} to clear the cached value.
40       */
41      private double cachedNormalDeviate = Double.NaN;
42      
43      /**
44       * Construct a RandomGenerator.
45       */
46      public AbstractRandomGenerator() {
47          super();
48          
49      }
50      
51      /**
52       * Clears the cache used by the default implementation of 
53       * {@link #nextGaussian}. Implemementations that do not override the
54       * default implementation of <code>nextGaussian</code> should call this
55       * method in the implementation of {@link #setSeed(long)}
56       */
57      public void clear() {
58          cachedNormalDeviate = Double.NaN;
59      }
60      
61      /**
62       * Sets the seed of the underyling random number generator using a 
63       * <code>long</code> seed.  Sequences of values generated starting with the
64       * same seeds should be identical.
65       * <p>
66       * Implementations that do not override the default implementation of 
67       * <code>nextGaussian</code> should include a call to {@link #clear} in the
68       * implementation of this method.
69       *
70       * @param seed the seed value
71       */
72      public abstract void setSeed(long seed);  
73  
74      /**
75       * Generates random bytes and places them into a user-supplied 
76       * byte array.  The number of random bytes produced is equal to 
77       * the length of the byte array.
78       * <p>
79       * The default implementation fills the array with bytes extracted from
80       * random integers generated using {@link #nextInt}.
81       * 
82       * @param bytes the non-null byte array in which to put the 
83       * random bytes
84       */
85      public void nextBytes(byte[] bytes) {
86          int bytesOut = 0;
87          while (bytesOut < bytes.length) {
88            int randInt = nextInt();
89            for (int i = 0; i < 3; i++) {
90                if ( i > 0) {
91                    randInt = randInt >> 8;
92                }
93                bytes[bytesOut++] = (byte) randInt;
94                if (bytesOut == bytes.length) {
95                    return;
96                }
97            }
98          }
99      }
100 
101      /**
102      * Returns the next pseudorandom, uniformly distributed <code>int</code>
103      * value from this random number generator's sequence.  
104      * All 2<font size="-1"><sup>32</sup></font> possible <tt>int</tt> values
105      * should be produced with  (approximately) equal probability. 
106      * <p>
107      * The default implementation provided here returns 
108      * <pre>
109      * <code>(int) (nextDouble() * Integer.MAX_VALUE)</code>
110      * </pre>
111      *
112      * @return the next pseudorandom, uniformly distributed <code>int</code>
113      *  value from this random number generator's sequence
114      */
115     public int nextInt() {
116         return (int) (nextDouble() * Integer.MAX_VALUE);
117     }
118 
119     /**
120      * Returns a pseudorandom, uniformly distributed <tt>int</tt> value
121      * between 0 (inclusive) and the specified value (exclusive), drawn from
122      * this random number generator's sequence. 
123      * <p>  
124      * The default implementation returns 
125      * <pre>
126      * <code>(int) (nextDouble() * n</code>
127      * </pre>
128      *
129      * @param n the bound on the random number to be returned.  Must be
130      * positive.
131      * @return  a pseudorandom, uniformly distributed <tt>int</tt>
132      * value between 0 (inclusive) and n (exclusive).
133      * @throws IllegalArgumentException if n is not positive.
134      */
135     public int nextInt(int n) {
136         if (n <= 0 ) {
137             throw new IllegalArgumentException("upper bound must be positive");
138         }
139         int result = (int) (nextDouble() * n);
140         return result < n ? result : n - 1;
141     }
142 
143      /**
144      * Returns the next pseudorandom, uniformly distributed <code>long</code>
145      * value from this random number generator's sequence.  All 
146      * 2<font size="-1"><sup>64</sup></font> possible <tt>long</tt> values 
147      * should be produced with (approximately) equal probability. 
148      * <p>  
149      * The default implementation returns 
150      * <pre>
151      * <code>(long) (nextDouble() * Long.MAX_VALUE)</code>
152      * </pre>
153      *
154      * @return  the next pseudorandom, uniformly distributed <code>long</code>
155      *value from this random number generator's sequence
156      */
157     public long nextLong() {
158         return (long) (nextDouble() * Long.MAX_VALUE);
159     }
160 
161     /**
162      * Returns the next pseudorandom, uniformly distributed
163      * <code>boolean</code> value from this random number generator's
164      * sequence.  
165      * <p>  
166      * The default implementation returns 
167      * <pre>
168      * <code>nextDouble() <= 0.5</code>
169      * </pre>
170      * 
171      * @return  the next pseudorandom, uniformly distributed
172      * <code>boolean</code> value from this random number generator's
173      * sequence
174      */
175     public boolean nextBoolean() {
176         return nextDouble() <= 0.5;
177     }
178 
179      /**
180      * Returns the next pseudorandom, uniformly distributed <code>float</code>
181      * value between <code>0.0</code> and <code>1.0</code> from this random
182      * number generator's sequence.  
183      * <p>  
184      * The default implementation returns 
185      * <pre>
186      * <code>(float) nextDouble() </code>
187      * </pre>
188      *
189      * @return  the next pseudorandom, uniformly distributed <code>float</code>
190      * value between <code>0.0</code> and <code>1.0</code> from this
191      * random number generator's sequence
192      */
193     public float nextFloat() {
194         return (float) nextDouble();
195     }
196 
197     /**
198      * Returns the next pseudorandom, uniformly distributed 
199      * <code>double</code> value between <code>0.0</code> and
200      * <code>1.0</code> from this random number generator's sequence.  
201      * <p>
202      * This method provides the underlying source of random data used by the
203      * other methods.   
204      *
205      * @return  the next pseudorandom, uniformly distributed 
206      *  <code>double</code> value between <code>0.0</code> and
207      *  <code>1.0</code> from this random number generator's sequence
208      */  
209     public abstract double nextDouble();  
210 
211     /**
212      * Returns the next pseudorandom, Gaussian ("normally") distributed
213      * <code>double</code> value with mean <code>0.0</code> and standard
214      * deviation <code>1.0</code> from this random number generator's sequence.
215      * <p>
216      * The default implementation uses the <em>Polar Method</em>
217      * due to G.E.P. Box, M.E. Muller and G. Marsaglia, as described in 
218      * D. Knuth, <u>The Art of Computer Programming</u>, 3.4.1C.
219      * <p>
220      * The algorithm generates a pair of independent random values.  One of
221      * these is cached for reuse, so the full algorithm is not executed on each
222      * activation.  Implementations that do not override this method should
223      * make sure to call {@link #clear} to clear the cached value in the 
224      * implementation of {@link #setSeed(long)}.
225      * 
226      * @return  the next pseudorandom, Gaussian ("normally") distributed
227      * <code>double</code> value with mean <code>0.0</code> and
228      * standard deviation <code>1.0</code> from this random number
229      *  generator's sequence
230      */
231     public double nextGaussian() {
232         if (!Double.isNaN(cachedNormalDeviate)) {
233             double dev = cachedNormalDeviate;
234             cachedNormalDeviate = Double.NaN;
235             return dev;
236         }
237         double v1 = 0;
238         double v2 = 0;
239         double s = 1;
240         while (s >=1 ) { 
241             v1 = 2 * nextDouble() - 1; 
242             v2 = 2 * nextDouble() - 1; 
243             s = v1 * v1 + v2 * v2;
244         }
245         if (s != 0) {
246             s = Math.sqrt(-2 * Math.log(s) / s);   
247         }
248         cachedNormalDeviate = v2 * s;
249         return v1 * s;      
250     }
251 }