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 */
017
018 package org.apache.commons.math.random;
019 import java.util.Collection;
020
021 /**
022 * Random data generation utilities.
023 * @version $Revision: 780975 $ $Date: 2009-06-02 11:05:37 +0200 (mar. 02 juin 2009) $
024 */
025 public interface RandomData {
026 /**
027 * Generates a random string of hex characters of length
028 * <code>len</code>.
029 * <p>
030 * The generated string will be random, but not cryptographically
031 * secure. To generate cryptographically secure strings, use
032 * <code>nextSecureHexString</code></p>
033 * <p>
034 * <strong>Preconditions</strong>:<ul>
035 * <li><code>len > 0</code> (otherwise an IllegalArgumentException
036 * is thrown.)</li>
037 * </ul></p>
038 *
039 * @param len the length of the string to be generated
040 * @return random string of hex characters of length <code>len</code>
041 */
042 String nextHexString(int len);
043
044 /**
045 * Generates a uniformly distributed random integer between
046 * <code>lower</code> and <code>upper</code> (endpoints included).
047 * <p>
048 * The generated integer will be random, but not cryptographically secure.
049 * To generate cryptographically secure integer sequences, use
050 * <code>nextSecureInt</code>.</p>
051 * <p>
052 * <strong>Preconditions</strong>:<ul>
053 * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
054 * is thrown.)</li>
055 * </ul></p>
056 *
057 * @param lower lower bound for generated integer
058 * @param upper upper bound for generated integer
059 * @return a random integer greater than or equal to <code>lower</code>
060 * and less than or equal to <code>upper</code>.
061 */
062 int nextInt(int lower, int upper);
063
064 /**
065 * Generates a uniformly distributed random long integer between
066 * <code>lower</code> and <code>upper</code> (endpoints included).
067 * <p>
068 * The generated long integer values will be random, but not
069 * cryptographically secure.
070 * To generate cryptographically secure sequences of longs, use
071 * <code>nextSecureLong</code></p>
072 * <p>
073 * <strong>Preconditions</strong>:<ul>
074 * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
075 * is thrown.)</li>
076 * </ul></p>
077 *
078 * @param lower lower bound for generated integer
079 * @param upper upper bound for generated integer
080 * @return a random integer greater than or equal to <code>lower</code>
081 * and less than or equal to <code>upper</code>.
082 */
083 long nextLong(long lower, long upper);
084
085 /**
086 * Generates a random string of hex characters from a secure random
087 * sequence.
088 * <p>
089 * If cryptographic security is not required,
090 * use <code>nextHexString()</code>.</p>
091 * <p>
092 * <strong>Preconditions</strong>:<ul>
093 * <li><code>len > 0</code> (otherwise an IllegalArgumentException
094 * is thrown.)</li>
095 * </ul></p>
096 * @param len length of return string
097 * @return the random hex string
098 */
099 String nextSecureHexString(int len);
100
101 /**
102 * Generates a uniformly distributed random integer between
103 * <code>lower</code> and <code>upper</code> (endpoints included)
104 * from a secure random sequence.
105 * <p>
106 * Sequences of integers generated using this method will be
107 * cryptographically secure. If cryptographic security is not required,
108 * <code>nextInt</code> should be used instead of this method.</p>
109 * <p>
110 * <strong>Definition</strong>:
111 * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
112 * Secure Random Sequence</a></p>
113 * <p>
114 * <strong>Preconditions</strong>:<ul>
115 * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
116 * is thrown.)</li>
117 * </ul></p>
118 *
119 * @param lower lower bound for generated integer
120 * @param upper upper bound for generated integer
121 * @return a random integer greater than or equal to <code>lower</code>
122 * and less than or equal to <code>upper</code>.
123 */
124 int nextSecureInt(int lower, int upper);
125
126 /**
127 * Generates a random long integer between <code>lower</code>
128 * and <code>upper</code> (endpoints included).
129 * <p>
130 * Sequences of long values generated using this method will be
131 * cryptographically secure. If cryptographic security is not required,
132 * <code>nextLong</code> should be used instead of this method.</p>
133 * <p>
134 * <strong>Definition</strong>:
135 * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
136 * Secure Random Sequence</a></p>
137 * <p>
138 * <strong>Preconditions</strong>:<ul>
139 * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
140 * is thrown.)</li>
141 * </ul></p>
142 *
143 * @param lower lower bound for generated integer
144 * @param upper upper bound for generated integer
145 * @return a long integer greater than or equal to <code>lower</code>
146 * and less than or equal to <code>upper</code>.
147 */
148 long nextSecureLong(long lower, long upper);
149
150 /**
151 * Generates a random value from the Poisson distribution with
152 * the given mean.
153 * <p>
154 * <strong>Definition</strong>:
155 * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda366j.htm">
156 * Poisson Distribution</a></p>
157 * <p>
158 * <strong>Preconditions</strong>: <ul>
159 * <li>The specified mean <i>must</i> be positive (otherwise an
160 * IllegalArgumentException is thrown.)</li>
161 * </ul></p>
162 * @param mean Mean of the distribution
163 * @return poisson deviate with the specified mean
164 */
165 long nextPoisson(double mean);
166
167 /**
168 * Generates a random value from the
169 * Normal (or Gaussian) distribution with the given mean
170 * and standard deviation.
171 * <p>
172 * <strong>Definition</strong>:
173 * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3661.htm">
174 * Normal Distribution</a></p>
175 * <p>
176 * <strong>Preconditions</strong>: <ul>
177 * <li><code>sigma > 0</code> (otherwise an IllegalArgumentException
178 * is thrown.)</li>
179 * </ul></p>
180 * @param mu Mean of the distribution
181 * @param sigma Standard deviation of the distribution
182 * @return random value from Gaussian distribution with mean = mu,
183 * standard deviation = sigma
184 */
185 double nextGaussian(double mu, double sigma);
186
187 /**
188 * Generates a random value from the exponential distribution
189 * with expected value = <code>mean</code>.
190 * <p>
191 * <strong>Definition</strong>:
192 * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3667.htm">
193 * Exponential Distribution</a></p>
194 * <p>
195 * <strong>Preconditions</strong>: <ul>
196 * <li><code>mu >= 0</code> (otherwise an IllegalArgumentException
197 * is thrown.)</li>
198 * </ul></p>
199 * @param mean Mean of the distribution
200 * @return random value from exponential distribution
201 */
202 double nextExponential(double mean);
203
204 /**
205 * Generates a uniformly distributed random value from the open interval
206 * (<code>lower</code>,<code>upper</code>) (i.e., endpoints excluded).
207 * <p>
208 * <strong>Definition</strong>:
209 * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm">
210 * Uniform Distribution</a> <code>lower</code> and
211 * <code>upper - lower</code> are the
212 * <a href = "http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm">
213 * location and scale parameters</a>, respectively.</p>
214 * <p>
215 * <strong>Preconditions</strong>:<ul>
216 * <li><code>lower < upper</code> (otherwise an IllegalArgumentException
217 * is thrown.)</li>
218 * </ul></p>
219 *
220 * @param lower lower endpoint of the interval of support
221 * @param upper upper endpoint of the interval of support
222 * @return uniformly distributed random value between lower
223 * and upper (exclusive)
224 */
225 double nextUniform(double lower, double upper);
226
227 /**
228 * Generates an integer array of length <code>k</code> whose entries
229 * are selected randomly, without repetition, from the integers <code>
230 * 0 through n-1</code> (inclusive).
231 * <p>
232 * Generated arrays represent permutations
233 * of <code>n</code> taken <code>k</code> at a time.</p>
234 * <p>
235 * <strong>Preconditions:</strong><ul>
236 * <li> <code>k <= n</code></li>
237 * <li> <code>n > 0</code> </li>
238 * </ul>
239 * If the preconditions are not met, an IllegalArgumentException is
240 * thrown.</p>
241 *
242 * @param n domain of the permutation
243 * @param k size of the permutation
244 * @return random k-permutation of n
245 */
246 int[] nextPermutation(int n, int k);
247
248 /**
249 * Returns an array of <code>k</code> objects selected randomly
250 * from the Collection <code>c</code>.
251 * <p>
252 * Sampling from <code>c</code>
253 * is without replacement; but if <code>c</code> contains identical
254 * objects, the sample may include repeats. If all elements of <code>
255 * c</code> are distinct, the resulting object array represents a
256 * <a href="http://rkb.home.cern.ch/rkb/AN16pp/node250.html#SECTION0002500000000000000000">
257 * Simple Random Sample</a> of size
258 * <code>k</code> from the elements of <code>c</code>.</p>
259 * <p>
260 * <strong>Preconditions:</strong><ul>
261 * <li> k must be less than or equal to the size of c </li>
262 * <li> c must not be empty </li>
263 * </ul>
264 * If the preconditions are not met, an IllegalArgumentException is
265 * thrown.</p>
266 *
267 * @param c collection to be sampled
268 * @param k size of the sample
269 * @return random sample of k elements from c
270 */
271 Object[] nextSample(Collection<?> c, int k);
272 }