Coverage Report - org.apache.commons.math.random.AbstractRandomGenerator

Classes in this File	Line Coverage	Branch Coverage	Complexity
AbstractRandomGenerator	97%	100%	1.9090909090909092;1.909

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$ $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	30	private double cachedNormalDeviate = Double.NaN;
42
43		/**
44		* Construct a RandomGenerator.
45		*/
46		public AbstractRandomGenerator() {
47	30	super();
48
49	30	}
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	6	cachedNormalDeviate = Double.NaN;
59	6	}
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	2004	int bytesOut = 0;
87	34004	while (bytesOut < bytes.length) {
88	34004	int randInt = nextInt();
89	134006	for (int i = 0; i < 3; i++) {
90	102006	if ( i > 0) {
91	68002	randInt = randInt >> 8;
92		}
93	102006	bytes[bytesOut++] = (byte) randInt;
94	102006	if (bytesOut == bytes.length) {
95	2004	return;
96		}
97		}
98		}
99	0	}
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	34004	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	2002	if (n <= 0 ) {
137	2	throw new IllegalArgumentException("upper bound must be positive");
138		}
139	2000	int result = (int) (nextDouble() * n);
140	2000	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	2000	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	2000	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	2000	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	20000	if (!Double.isNaN(cachedNormalDeviate)) {
233	10000	double dev = cachedNormalDeviate;
234	10000	cachedNormalDeviate = Double.NaN;
235	10000	return dev;
236		}
237	10000	double v1 = 0;
238	10000	double v2 = 0;
239	10000	double s = 1;
240	22785	while (s >=1 ) {
241	12785	v1 = 2 * nextDouble() - 1;
242	12785	v2 = 2 * nextDouble() - 1;
243	12785	s = v1 * v1 + v2 * v2;
244		}
245	10000	if (s != 0) {
246	10000	s = Math.sqrt(-2 * Math.log(s) / s);
247		}
248	10000	cachedNormalDeviate = v2 * s;
249	10000	return v1 * s;
250		}
251		}