source: src/main/java/agents/anac/y2019/harddealer/math3/random/RandomData.java

Last change on this file was 204, checked in by Katsuhide Fujita, 5 years ago

Fixed errors of ANAC2019 agents

  • Property svn:executable set to *
File size: 11.5 KB
Line 
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
18package agents.anac.y2019.harddealer.math3.random;
19import java.util.Collection;
20
21import agents.anac.y2019.harddealer.math3.exception.NotANumberException;
22import agents.anac.y2019.harddealer.math3.exception.NotFiniteNumberException;
23import agents.anac.y2019.harddealer.math3.exception.NotStrictlyPositiveException;
24import agents.anac.y2019.harddealer.math3.exception.NumberIsTooLargeException;
25
26/**
27 * Random data generation utilities.
28 * @deprecated to be removed in 4.0. Use {@link RandomDataGenerator} directly
29 */
30@Deprecated
31public interface RandomData {
32 /**
33 * Generates a random string of hex characters of length {@code len}.
34 * <p>
35 * The generated string will be random, but not cryptographically
36 * secure. To generate cryptographically secure strings, use
37 * {@link #nextSecureHexString(int)}.
38 * </p>
39 *
40 * @param len the length of the string to be generated
41 * @return a random string of hex characters of length {@code len}
42 * @throws NotStrictlyPositiveException
43 * if {@code len <= 0}
44 */
45 String nextHexString(int len) throws NotStrictlyPositiveException;
46
47 /**
48 * Generates a uniformly distributed random integer between {@code lower}
49 * and {@code upper} (endpoints included).
50 * <p>
51 * The generated integer will be random, but not cryptographically secure.
52 * To generate cryptographically secure integer sequences, use
53 * {@link #nextSecureInt(int, int)}.
54 * </p>
55 *
56 * @param lower lower bound for generated integer
57 * @param upper upper bound for generated integer
58 * @return a random integer greater than or equal to {@code lower}
59 * and less than or equal to {@code upper}
60 * @throws NumberIsTooLargeException if {@code lower >= upper}
61 */
62 int nextInt(int lower, int upper) throws NumberIsTooLargeException;
63
64 /**
65 * Generates a uniformly distributed random long integer between
66 * {@code lower} and {@code upper} (endpoints included).
67 * <p>
68 * The generated long integer values will be random, but not
69 * cryptographically secure. To generate cryptographically secure sequences
70 * of longs, use {@link #nextSecureLong(long, long)}.
71 * </p>
72 *
73 * @param lower lower bound for generated long integer
74 * @param upper upper bound for generated long integer
75 * @return a random long integer greater than or equal to {@code lower} and
76 * less than or equal to {@code upper}
77 * @throws NumberIsTooLargeException if {@code lower >= upper}
78 */
79 long nextLong(long lower, long upper) throws NumberIsTooLargeException;
80
81 /**
82 * Generates a random string of hex characters from a secure random
83 * sequence.
84 * <p>
85 * If cryptographic security is not required, use
86 * {@link #nextHexString(int)}.
87 * </p>
88 *
89 * @param len the length of the string to be generated
90 * @return a random string of hex characters of length {@code len}
91 * @throws NotStrictlyPositiveException if {@code len <= 0}
92 */
93 String nextSecureHexString(int len) throws NotStrictlyPositiveException;
94
95 /**
96 * Generates a uniformly distributed random integer between {@code lower}
97 * and {@code upper} (endpoints included) from a secure random sequence.
98 * <p>
99 * Sequences of integers generated using this method will be
100 * cryptographically secure. If cryptographic security is not required,
101 * {@link #nextInt(int, int)} should be used instead of this method.</p>
102 * <p>
103 * <strong>Definition</strong>:
104 * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
105 * Secure Random Sequence</a></p>
106 *
107 * @param lower lower bound for generated integer
108 * @param upper upper bound for generated integer
109 * @return a random integer greater than or equal to {@code lower} and less
110 * than or equal to {@code upper}.
111 * @throws NumberIsTooLargeException if {@code lower >= upper}.
112 */
113 int nextSecureInt(int lower, int upper) throws NumberIsTooLargeException;
114
115 /**
116 * Generates a uniformly distributed random long integer between
117 * {@code lower} and {@code upper} (endpoints included) from a secure random
118 * sequence.
119 * <p>
120 * Sequences of long values generated using this method will be
121 * cryptographically secure. If cryptographic security is not required,
122 * {@link #nextLong(long, long)} should be used instead of this method.</p>
123 * <p>
124 * <strong>Definition</strong>:
125 * <a href="http://en.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator">
126 * Secure Random Sequence</a></p>
127 *
128 * @param lower lower bound for generated integer
129 * @param upper upper bound for generated integer
130 * @return a random long integer greater than or equal to {@code lower} and
131 * less than or equal to {@code upper}.
132 * @throws NumberIsTooLargeException if {@code lower >= upper}.
133 */
134 long nextSecureLong(long lower, long upper) throws NumberIsTooLargeException;
135
136 /**
137 * Generates a random value from the Poisson distribution with the given
138 * mean.
139 * <p>
140 * <strong>Definition</strong>:
141 * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda366j.htm">
142 * Poisson Distribution</a></p>
143 *
144 * @param mean the mean of the Poisson distribution
145 * @return a random value following the specified Poisson distribution
146 * @throws NotStrictlyPositiveException if {@code mean <= 0}.
147 */
148 long nextPoisson(double mean) throws NotStrictlyPositiveException;
149
150 /**
151 * Generates a random value from the Normal (or Gaussian) distribution with
152 * specified mean and standard deviation.
153 * <p>
154 * <strong>Definition</strong>:
155 * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3661.htm">
156 * Normal Distribution</a></p>
157 *
158 * @param mu the mean of the distribution
159 * @param sigma the standard deviation of the distribution
160 * @return a random value following the specified Gaussian distribution
161 * @throws NotStrictlyPositiveException if {@code sigma <= 0}.
162 */
163 double nextGaussian(double mu, double sigma) throws NotStrictlyPositiveException;
164
165 /**
166 * Generates a random value from the exponential distribution
167 * with specified mean.
168 * <p>
169 * <strong>Definition</strong>:
170 * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3667.htm">
171 * Exponential Distribution</a></p>
172 *
173 * @param mean the mean of the distribution
174 * @return a random value following the specified exponential distribution
175 * @throws NotStrictlyPositiveException if {@code mean <= 0}.
176 */
177 double nextExponential(double mean) throws NotStrictlyPositiveException;
178
179 /**
180 * Generates a uniformly distributed random value from the open interval
181 * {@code (lower, upper)} (i.e., endpoints excluded).
182 * <p>
183 * <strong>Definition</strong>:
184 * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm">
185 * Uniform Distribution</a> {@code lower} and {@code upper - lower} are the
186 * <a href = "http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm">
187 * location and scale parameters</a>, respectively.</p>
188 *
189 * @param lower the exclusive lower bound of the support
190 * @param upper the exclusive upper bound of the support
191 * @return a uniformly distributed random value between lower and upper
192 * (exclusive)
193 * @throws NumberIsTooLargeException if {@code lower >= upper}
194 * @throws NotFiniteNumberException if one of the bounds is infinite
195 * @throws NotANumberException if one of the bounds is NaN
196 */
197 double nextUniform(double lower, double upper)
198 throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException;
199
200 /**
201 * Generates a uniformly distributed random value from the interval
202 * {@code (lower, upper)} or the interval {@code [lower, upper)}. The lower
203 * bound is thus optionally included, while the upper bound is always
204 * excluded.
205 * <p>
206 * <strong>Definition</strong>:
207 * <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm">
208 * Uniform Distribution</a> {@code lower} and {@code upper - lower} are the
209 * <a href = "http://www.itl.nist.gov/div898/handbook/eda/section3/eda364.htm">
210 * location and scale parameters</a>, respectively.</p>
211 *
212 * @param lower the lower bound of the support
213 * @param upper the exclusive upper bound of the support
214 * @param lowerInclusive {@code true} if the lower bound is inclusive
215 * @return uniformly distributed random value in the {@code (lower, upper)}
216 * interval, if {@code lowerInclusive} is {@code false}, or in the
217 * {@code [lower, upper)} interval, if {@code lowerInclusive} is
218 * {@code true}
219 * @throws NumberIsTooLargeException if {@code lower >= upper}
220 * @throws NotFiniteNumberException if one of the bounds is infinite
221 * @throws NotANumberException if one of the bounds is NaN
222 */
223 double nextUniform(double lower, double upper, boolean lowerInclusive)
224 throws NumberIsTooLargeException, NotFiniteNumberException, NotANumberException;
225
226 /**
227 * Generates an integer array of length {@code k} whose entries are selected
228 * randomly, without repetition, from the integers {@code 0, ..., n - 1}
229 * (inclusive).
230 * <p>
231 * Generated arrays represent permutations of {@code n} taken {@code k} at a
232 * time.</p>
233 *
234 * @param n the domain of the permutation
235 * @param k the size of the permutation
236 * @return a random {@code k}-permutation of {@code n}, as an array of
237 * integers
238 * @throws NumberIsTooLargeException if {@code k > n}.
239 * @throws NotStrictlyPositiveException if {@code k <= 0}.
240 */
241 int[] nextPermutation(int n, int k)
242 throws NumberIsTooLargeException, NotStrictlyPositiveException;
243
244 /**
245 * Returns an array of {@code k} objects selected randomly from the
246 * Collection {@code c}.
247 * <p>
248 * Sampling from {@code c} is without replacement; but if {@code c} contains
249 * identical objects, the sample may include repeats. If all elements of
250 * {@code c} are distinct, the resulting object array represents a
251 * <a href="http://rkb.home.cern.ch/rkb/AN16pp/node250.html#SECTION0002500000000000000000">
252 * Simple Random Sample</a> of size {@code k} from the elements of
253 * {@code c}.</p>
254 *
255 * @param c the collection to be sampled
256 * @param k the size of the sample
257 * @return a random sample of {@code k} elements from {@code c}
258 * @throws NumberIsTooLargeException if {@code k > c.size()}.
259 * @throws NotStrictlyPositiveException if {@code k <= 0}.
260 */
261 Object[] nextSample(Collection<?> c, int k)
262 throws NumberIsTooLargeException, NotStrictlyPositiveException;
263
264}
Note: See TracBrowser for help on using the repository browser.