From fc266424806307c17658b316982dda185da87bd9 Mon Sep 17 00:00:00 2001 From: Phil Steitz Date: Mon, 14 Jun 2004 23:15:15 +0000 Subject: [PATCH] Formatting only. Removed tabs and trailing spaces. git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/math/trunk@141292 13f79535-47bb-0310-9956-ffa450edef68 --- .../math/random/EmpiricalDistribution.java | 82 +++---- .../random/EmpiricalDistributionImpl.java | 108 ++++----- .../commons/math/random/RandomData.java | 174 +++++++------- .../commons/math/random/RandomDataImpl.java | 214 +++++++++--------- .../commons/math/random/ValueServer.java | 158 ++++++------- .../apache/commons/math/random/package.html | 4 +- 6 files changed, 370 insertions(+), 370 deletions(-) diff --git a/src/java/org/apache/commons/math/random/EmpiricalDistribution.java b/src/java/org/apache/commons/math/random/EmpiricalDistribution.java index 55a2523b2..938a5b91c 100644 --- a/src/java/org/apache/commons/math/random/EmpiricalDistribution.java +++ b/src/java/org/apache/commons/math/random/EmpiricalDistribution.java @@ -1,12 +1,12 @@ /* * Copyright 2003-2004 The Apache Software Foundation. - * + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * + * * http://www.apache.org/licenses/LICENSE-2.0 - * + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -28,8 +28,8 @@ import org.apache.commons.math.stat.univariate.SummaryStatistics; * empirical probability distribution -- a probability distribution derived * from observed data without making any assumptions about the functional form * of the population distribution that the data come from.

- * Implementations of this interface maintain data structures, called - * distribution digests, that describe empirical distributions and + * Implementations of this interface maintain data structures, called + * distribution digests, that describe empirical distributions and * support the following operations:

- * Applications can use EmpiricalDistribution implementations to + * Applications can use EmpiricalDistribution implementations to * build grouped frequnecy histograms representing the input data or to * generate random values "like" those in the input file -- i.e., the values * generated will follow the distribution of the values in the file. - * @version $Revision: 1.17 $ $Date: 2004/04/12 02:27:49 $ + * @version $Revision: 1.18 $ $Date: 2004/06/14 23:15:14 $ */ public interface EmpiricalDistribution { - + /** * Computes the empirical distribution from the provided * array of numbers. * @param dataArray the data array */ - void load(double[] dataArray); - + void load(double[] dataArray); + /** * Computes the empirical distribution from the input file. * @param filePath fully qualified name of a file in the local file system * @throws IOException if an IO error occurs */ - void load(String filePath) throws IOException; - + void load(String filePath) throws IOException; + /** * Computes the empirical distribution from the input file. * @param file the input file * @throws IOException if an IO error occurs */ void load(File file) throws IOException; - + /** * Computes the empirical distribution using data read from a URL. * @param url url of the input file * @throws IOException if an IO error occurs */ void load(URL url) throws IOException; - - /** + + /** * Generates a random value from this distribution. * Preconditions: * @return the random value. * @throws IllegalStateException if the distribution has not been loaded */ - double getNextValue() throws IllegalStateException; - - - /** + double getNextValue() throws IllegalStateException; + + + /** * Returns a DescriptiveStatistics describing this distribution. * Preconditions: @@ -93,23 +93,23 @@ public interface EmpiricalDistribution { * @throws IllegalStateException if the distribution has not been loaded */ SummaryStatistics getSampleStats() throws IllegalStateException; - - /** + + /** * Loads a saved distribution from a file. * @param file File reference for a file containing a digested distribution * @throws IOException if an error occurs reading the file */ - void loadDistribution(File file) throws IOException; - - /** + void loadDistribution(File file) throws IOException; + + /** * Loads a saved distribution from a file. - * @param filePath fully qualified file path for a file - * containing a digested distribution + * @param filePath fully qualified file path for a file + * containing a digested distribution * @throws IOException if an error occurs reading the file */ - void loadDistribution(String filePath) throws IOException; - - /** + void loadDistribution(String filePath) throws IOException; + + /** * Saves distribution to a file. Overwrites the file if it exists. * Preconditions: @@ -117,10 +117,10 @@ public interface EmpiricalDistribution { * @throws IOException if an error occurs reading the file * @throws IllegalStateException if the distribution has not been loaded */ - void saveDistribution(String filePath) throws + void saveDistribution(String filePath) throws IOException,IllegalStateException; - - /** + + /** * Saves distribution to a file. Overwrites the file if it exists. * Preconditions: @@ -129,32 +129,32 @@ public interface EmpiricalDistribution { * @throws IllegalStateException if the distribution has not been loaded */ void saveDistribution(File file) throws IOException,IllegalStateException; - + /** * property indicating whether or not the distribution has been loaded * @return true if the distribution has been loaded */ - boolean isLoaded(); - - /** + boolean isLoaded(); + + /** * Returns the number of bins * @return the number of bins. */ int getBinCount(); - - /** + + /** * Returns a list of Univariates containing statistics describing the * values in each of the bins. The ArrayList is indexed on the bin number. * @return ArrayList of bin statistics. */ ArrayList getBinStats(); - - /** + + /** * Returns the array of upper bounds for the bins. Bins are:
* [min,upperBounds[0]],(upperBounds[0],upperBounds[1]],..., * (upperBounds[binCount-1],max] * @return array of bin upper bounds */ double[] getUpperBounds(); - + } diff --git a/src/java/org/apache/commons/math/random/EmpiricalDistributionImpl.java b/src/java/org/apache/commons/math/random/EmpiricalDistributionImpl.java index a1a814fae..6fda10eb4 100644 --- a/src/java/org/apache/commons/math/random/EmpiricalDistributionImpl.java +++ b/src/java/org/apache/commons/math/random/EmpiricalDistributionImpl.java @@ -1,12 +1,12 @@ /* * Copyright 2003-2004 The Apache Software Foundation. - * + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * + * * http://www.apache.org/licenses/LICENSE-2.0 - * + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -30,11 +30,11 @@ import org.apache.commons.math.stat.univariate.SummaryStatistics; /** * Implements EmpiricalDistribution interface. This implementation - * uses what amounts to the + * uses what amounts to the * * Variable Kernel Method with Gaussian smoothing:

* Digesting the input file - *

  1. Pass the file once to compute min and max.
    2. + *
    1. Pass the file once to compute min and max.
      2. *
    2. Divide the range from min-max into binCount "bins."
      3. *
    3. Pass the data file again, computing bin counts and univariate * statistics (mean, std dev.) for each of the bins
      4. @@ -53,39 +53,39 @@ import org.apache.commons.math.stat.univariate.SummaryStatistics; * entry per line. *

      * - * @version $Revision: 1.20 $ $Date: 2004/06/02 00:20:21 $ + * @version $Revision: 1.21 $ $Date: 2004/06/14 23:15:14 $ */ public class EmpiricalDistributionImpl implements Serializable, EmpiricalDistribution { /** Serializable version identifier */ static final long serialVersionUID = -6773236347582113490L; - + /** List of DescriptiveStatistics objects characterizing the bins */ private ArrayList binStats = null; - + /** Sample statistics */ SummaryStatistics sampleStats = null; - + /** number of bins */ private int binCount = 1000; - + /** is the distribution loaded? */ private boolean loaded = false; - + /** upper bounds of subintervals in (0,1) "belonging" to the bins */ private double[] upperBounds = null; - + /** RandomData instance to use in repeated calls to getNext() */ private RandomData randomData = new RandomDataImpl(); - - /** + + /** * Creates a new EmpiricalDistribution with the default bin count */ public EmpiricalDistributionImpl() { binStats = new ArrayList(); } - - /** + + /** * Creates a new EmpiricalDistribution with the specified bin count * @param binCount number of bins */ @@ -106,12 +106,12 @@ public class EmpiricalDistributionImpl implements Serializable, EmpiricalDistrib throw new RuntimeException(e.getMessage()); } loaded = true; - + } - + public void load(String filePath) throws IOException { - BufferedReader in = - new BufferedReader(new InputStreamReader(new FileInputStream(filePath))); + BufferedReader in = + new BufferedReader(new InputStreamReader(new FileInputStream(filePath))); try { DataAdapter da = new StreamDataAdapter(in); try { @@ -119,16 +119,16 @@ public class EmpiricalDistributionImpl implements Serializable, EmpiricalDistrib } catch (Exception e) { throw new IOException(e.getMessage()); } - in = new BufferedReader(new InputStreamReader(new FileInputStream(filePath))); + in = new BufferedReader(new InputStreamReader(new FileInputStream(filePath))); fillBinStats(in); loaded = true; } finally { if (in != null) try {in.close();} catch (Exception ex) {}; } } - + public void load(URL url) throws IOException { - BufferedReader in = + BufferedReader in = new BufferedReader(new InputStreamReader(url.openStream())); try { DataAdapter da = new StreamDataAdapter(in); @@ -144,7 +144,7 @@ public class EmpiricalDistributionImpl implements Serializable, EmpiricalDistrib if (in != null) try {in.close();} catch (Exception ex) {}; } } - + public void load(File file) throws IOException { BufferedReader in = new BufferedReader(new FileReader(file)); try { @@ -165,20 +165,20 @@ public class EmpiricalDistributionImpl implements Serializable, EmpiricalDistrib }; } } - + /** - * Provides methods for computing sampleStats and - * beanStats abstracting the source of data. + * Provides methods for computing sampleStats and + * beanStats abstracting the source of data. */ private abstract class DataAdapter{ - public abstract void computeBinStats(double min, double delta) + public abstract void computeBinStats(double min, double delta) throws Exception; public abstract void computeStats() throws Exception; } /** * Factory of DataAdapter objects. For every supported source * of data (array of doubles, file, etc.) an instance of the proper object - * is returned. + * is returned. */ private class DataAdapterFactory{ public DataAdapter getAdapter(Object in) { @@ -206,7 +206,7 @@ public class EmpiricalDistributionImpl implements Serializable, EmpiricalDistrib /** * Computes binStats */ - public void computeBinStats(double min, double delta) + public void computeBinStats(double min, double delta) throws IOException { String str = null; double val = 0.0d; @@ -263,17 +263,17 @@ public class EmpiricalDistributionImpl implements Serializable, EmpiricalDistrib for (int i = 0; i < inputArray.length; i++) { SummaryStatistics stats = (SummaryStatistics) binStats.get( - Math.max((int) Math.ceil((inputArray[i] - min) / delta) + Math.max((int) Math.ceil((inputArray[i] - min) / delta) - 1, 0)); stats.addValue(inputArray[i]); } - } + } } /** * Fills binStats array (second pass through data file). */ - private void fillBinStats(Object in) throws IOException { + private void fillBinStats(Object in) throws IOException { // Load array of bin upper bounds -- evenly spaced from min - max double min = sampleStats.getMin(); double max = sampleStats.getMax(); @@ -284,7 +284,7 @@ public class EmpiricalDistributionImpl implements Serializable, EmpiricalDistrib binUpperBounds[i] = binUpperBounds[i-1] + delta; } binUpperBounds[binCount -1] = max; - + // Initialize binStats ArrayList if (!binStats.isEmpty()) { binStats.clear(); @@ -293,7 +293,7 @@ public class EmpiricalDistributionImpl implements Serializable, EmpiricalDistrib SummaryStatistics stats = SummaryStatistics.newInstance(); binStats.add(i,stats); } - + // Filling data in binStats Array DataAdapterFactory aFactory = new DataAdapterFactory(); DataAdapter da = aFactory.getAdapter(in); @@ -306,7 +306,7 @@ public class EmpiricalDistributionImpl implements Serializable, EmpiricalDistrib throw new IOException(e.getMessage()); } } - + // Assign upperBounds based on bin counts upperBounds = new double[binCount]; upperBounds[0] = @@ -319,27 +319,27 @@ public class EmpiricalDistributionImpl implements Serializable, EmpiricalDistrib } upperBounds[binCount-1] = 1.0d; } - + /** * Generates a random value from this distribution * @return the random value. * @throws IllegalStateException if the distribution has not been loaded */ - public double getNextValue() throws IllegalStateException { - + public double getNextValue() throws IllegalStateException { + if (!loaded) { throw new IllegalStateException("distribution not loaded"); } - + // Start with a uniformly distributed random number in (0,1) double x = Math.random(); - + // Use this to select the bin and generate a Gaussian within the bin for (int i = 0; i < binCount; i++) { if (x <= upperBounds[i]) { SummaryStatistics stats = (SummaryStatistics)binStats.get(i); - if (stats.getN() > 0) { - if (stats.getStandardDeviation() > 0) { // more than one obs + if (stats.getN() > 0) { + if (stats.getStandardDeviation() > 0) { // more than one obs return randomData.nextGaussian (stats.getMean(),stats.getStandardDeviation()); } else { @@ -350,41 +350,41 @@ public class EmpiricalDistributionImpl implements Serializable, EmpiricalDistrib } throw new RuntimeException("No bin selected"); } - + public void loadDistribution(String filePath) throws IOException { throw new UnsupportedOperationException("Not Implemented yet :-("); } - + public void loadDistribution(File file) throws IOException { throw new UnsupportedOperationException("Not Implemented yet :-("); } - - public void saveDistribution(String filePath) throws + + public void saveDistribution(String filePath) throws IOException,IllegalStateException { throw new UnsupportedOperationException("Not Implemented yet :-("); } - - public void saveDistribution(File file) throws + + public void saveDistribution(File file) throws IOException,IllegalStateException { throw new UnsupportedOperationException("Not Implemented yet :-("); } - + public SummaryStatistics getSampleStats() { return sampleStats; } - + public int getBinCount() { return binCount; } - + public ArrayList getBinStats() { return binStats; } - + public double[] getUpperBounds() { return upperBounds; } - + public boolean isLoaded() { return loaded; } diff --git a/src/java/org/apache/commons/math/random/RandomData.java b/src/java/org/apache/commons/math/random/RandomData.java index 8de2d7333..d98565e2a 100644 --- a/src/java/org/apache/commons/math/random/RandomData.java +++ b/src/java/org/apache/commons/math/random/RandomData.java @@ -1,12 +1,12 @@ /* * Copyright 2003-2004 The Apache Software Foundation. - * + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * + * * http://www.apache.org/licenses/LICENSE-2.0 - * + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -19,58 +19,37 @@ import java.util.Collection; /** * Random data generation utilities - * @version $Revision: 1.9 $ $Date: 2004/04/11 19:00:45 $ + * @version $Revision: 1.10 $ $Date: 2004/06/14 23:15:15 $ */ -public interface RandomData { +public interface RandomData { /** * Generates a random string of hex characters of length * len. *

      - * The generated string will be random, but not cryptographically - * secure. To generate cryptographically secure strings, use + * The generated string will be random, but not cryptographically + * secure. To generate cryptographically secure strings, use * nextSecureHexString *

      * Preconditions:

        - *
      • len > 0 (otherwise an IllegalArgumentException - * is thrown.)
        • - *
      - * - * @param len the length of the string to be generated - * @return random string of hex characters of length len - */ - String nextHexString(int len); - - /** - * Generates a uniformly distributed random integer between - * lower and upper (endpoints included). - *

      - * The generated integer will be random, but not cryptographically secure. - * To generate cryptographically secure integer sequences, use - * nextSecureInt. - *

      - * Preconditions:

        - *
      • lower < upper (otherwise an IllegalArgumentException + *
      • len > 0 (otherwise an IllegalArgumentException * is thrown.)
        • *
      * - * @param lower lower bound for generated integer - * @param upper upper bound for generated integer - * @return a random integer greater than or equal to lower - * and less than or equal to upper. + * @param len the length of the string to be generated + * @return random string of hex characters of length len */ - int nextInt(int lower, int upper); - + String nextHexString(int len); + /** - * Generates a uniformly distributed random long integer between + * Generates a uniformly distributed random integer between * lower and upper (endpoints included). *

      - * The generated long integer values will be random, but not - * cryptographically secure. - * To generate cryptographically secure sequences of longs, use - * nextSecureLong + * The generated integer will be random, but not cryptographically secure. + * To generate cryptographically secure integer sequences, use + * nextSecureInt. *

      * Preconditions:

        - *
      • lower < upper (otherwise an IllegalArgumentException + *
      • lower < upper (otherwise an IllegalArgumentException * is thrown.)
        • *
      * @@ -79,39 +58,60 @@ public interface RandomData { * @return a random integer greater than or equal to lower * and less than or equal to upper. */ - long nextLong(long lower, long upper); - + int nextInt(int lower, int upper); + /** - * Generates a random string of hex characters from a secure random + * Generates a uniformly distributed random long integer between + * lower and upper (endpoints included). + *

      + * The generated long integer values will be random, but not + * cryptographically secure. + * To generate cryptographically secure sequences of longs, use + * nextSecureLong + *

      + * Preconditions:

        + *
      • lower < upper (otherwise an IllegalArgumentException + * is thrown.)
        • + *
      + * + * @param lower lower bound for generated integer + * @param upper upper bound for generated integer + * @return a random integer greater than or equal to lower + * and less than or equal to upper. + */ + long nextLong(long lower, long upper); + + /** + * Generates a random string of hex characters from a secure random * sequence. *

      - * If cryptographic security is not required, + * If cryptographic security is not required, * use nextHexString(). *

      * Preconditions:

        - *
      • len > 0 (otherwise an IllegalArgumentException + *
      • len > 0 (otherwise an IllegalArgumentException * is thrown.)
        • *
      * @param len length of return string * @return the random hex string */ - String nextSecureHexString(int len); - + String nextSecureHexString(int len); + /** - * Generates a uniformly distributed random integer between - * lower and upper (endpoints included) + * Generates a uniformly distributed random integer between + * lower and upper (endpoints included) * from a secure random sequence. *

      - * Sequences of integers generated using this method will be - * cryptographically secure. If cryptographic security is not required, - * nextInt should be used instead of this method. + * Sequences of integers generated using this method will be + * cryptographically secure. If cryptographic security is not required, + * nextInt should be used instead of this method. *

      * Definition: * * Secure Random Sequence *

      * Preconditions:

        - *
      • lower < upper (otherwise an IllegalArgumentException + *
      • lower < upper (otherwise an IllegalArgumentException * is thrown.)
        • *
      * @@ -120,12 +120,12 @@ public interface RandomData { * @return a random integer greater than or equal to lower * and less than or equal to upper. */ - int nextSecureInt(int lower, int upper); - + int nextSecureInt(int lower, int upper); + /** * Generates a random long integer between lower * and upper (endpoints included).

      - * Sequences of long values generated using this method will be + * Sequences of long values generated using this method will be * cryptographically secure. If cryptographic security is not required, * nextLong should be used instead of this method. *

      @@ -134,7 +134,7 @@ public interface RandomData { * Secure Random Sequence *

      * Preconditions:

        - *
      • lower < upper (otherwise an IllegalArgumentException + *
      • lower < upper (otherwise an IllegalArgumentException * is thrown.)
        • *
      * @@ -143,36 +143,36 @@ public interface RandomData { * @return a long integer greater than or equal to lower * and less than or equal to upper. */ - long nextSecureLong(long lower, long upper); - - /** - * Generates a random value from the Poisson distribution with + long nextSecureLong(long lower, long upper); + + /** + * Generates a random value from the Poisson distribution with * the given mean. *

      - * Definition: + * Definition: * * Poisson Distribution *

      * Preconditions:

        - *
      • The specified mean must be positive (otherwise an + *
      • The specified mean must be positive (otherwise an * IllegalArgumentException is thrown.)
        • *
      * @param mean Mean of the distribution * @return poisson deviate with the specified mean */ - long nextPoisson(double mean); - - /** + long nextPoisson(double mean); + + /** * Generates a random value from the * Normal (or Gaussian) distribution with the given mean * and standard deviation. *

      - * Definition: + * Definition: * * Normal Distribution *

      * Preconditions:

        - *
      • sigma > 0 (otherwise an IllegalArgumentException + *
      • sigma > 0 (otherwise an IllegalArgumentException * is thrown.)
        • *
      * @param mu Mean of the distribution @@ -180,38 +180,38 @@ public interface RandomData { * @return random value from Gaussian distribution with mean = mu, * standard deviation = sigma */ - double nextGaussian(double mu, double sigma); - + double nextGaussian(double mu, double sigma); + /** * Generates a random value from the exponential distribution * with expected value = mean. *

      - * Definition: + * Definition: * * Exponential Distribution *

      * Preconditions:

        - *
      • mu >= 0 (otherwise an IllegalArgumentException + *
      • mu >= 0 (otherwise an IllegalArgumentException * is thrown.)
        • *
      * @param mean Mean of the distribution * @return random value from exponential distribution */ - double nextExponential(double mean); - + double nextExponential(double mean); + /** * Generates a uniformly distributed random value from the open interval * (lower,upper) (i.e., endpoints excluded). *

      - * Definition: + * Definition: * - * Uniform Distribution lower and - * upper - lower are the + * Uniform Distribution lower and + * upper - lower are the * * location and scale parameters, respectively. *

      * Preconditions:

        - *
      • lower < upper (otherwise an IllegalArgumentException + *
      • lower < upper (otherwise an IllegalArgumentException * is thrown.)
        • *
      * @@ -221,14 +221,14 @@ public interface RandomData { * and upper (exclusive) */ double nextUniform(double lower, double upper); - + /** * Generates an integer array of length k whose entries * are selected randomly, without repetition, from the integers - * 0 through n-1 (inclusive). + * 0 through n-1 (inclusive). *

      * Generated arrays represent permutations - * of n taken k at a time. + * of n taken k at a time. *

      * Preconditions:

        *
      • k <= n
        • @@ -236,35 +236,35 @@ public interface RandomData { *
      * If the preconditions are not met, an IllegalArgumentException is * thrown. - * + * * @param n domain of the permutation * @param k size of the permutation - * @return random k-permutation of n + * @return random k-permutation of n */ int[] nextPermutation(int n, int k); - + /** * Returns an array of k objects selected randomly - * from the Collection c. + * from the Collection c. *

      * Sampling from c * is without replacement; but if c contains identical * objects, the sample may include repeats. If all elements of - * c are distinct, the resulting object array represents a + * c are distinct, the resulting object array represents a * * Simple Random Sample of size * k from the elements of c. - *

      + *

      * Preconditions:

        *
      • k must be less than or equal to the size of c
        • *
      • c must not be empty
        • *
      * If the preconditions are not met, an IllegalArgumentException is * thrown. - * + * * @param c collection to be sampled * @param k size of the sample - * @return random sample of k elements from c + * @return random sample of k elements from c */ Object[] nextSample(Collection c, int k); } diff --git a/src/java/org/apache/commons/math/random/RandomDataImpl.java b/src/java/org/apache/commons/math/random/RandomDataImpl.java index d8e50de81..9cc44a2d1 100644 --- a/src/java/org/apache/commons/math/random/RandomDataImpl.java +++ b/src/java/org/apache/commons/math/random/RandomDataImpl.java @@ -1,12 +1,12 @@ /* * Copyright 2003-2004 The Apache Software Foundation. - * + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * + * * http://www.apache.org/licenses/LICENSE-2.0 - * + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -25,22 +25,22 @@ import java.util.Random; import java.util.Collection; /** - * Implements the RandomData interface using - * java.util.Random and - * java.util.Random.SecureRandom instances to generate data. + * Implements the RandomData interface using + * java.util.Random and + * java.util.Random.SecureRandom instances to generate data. *

      - * Supports reseeding the underlying + * Supports reseeding the underlying * * PRNG. The SecurityProvider and Algorithm * used by the SecureRandom instance can also be reset. *

      - * For details on the PRNGs, see the JDK documentation for - * java.util.Random and + * For details on the PRNGs, see the JDK documentation for + * java.util.Random and * java.util.Random.SecureRandom *

      * Usage Notes:

        *
      • - * Instance variables are used to maintain Random and + * Instance variables are used to maintain Random and * SecureRandom instances used in data generation. Therefore, * to generate a random sequence of values or strings, you should use just * one RandomDataImpl instance repeatedly.
        • @@ -55,38 +55,38 @@ import java.util.Collection; * the appropriate generator. If you do not explicitly seed the generator, it * is by default seeded with the current time in milliseconds *
      • - * The reSeed and reSeedSecure methods delegate - * to the corresponding methods on the underlying Random and - * SecureRandom instances. Therefore, the contracts of these - * methods are as defined in the JDK documentation. In particular, - * reSeed(long) fully resets the initial state of the non-secure - * random number generator (so that reseeding with a specific value always + * The reSeed and reSeedSecure methods delegate + * to the corresponding methods on the underlying Random and + * SecureRandom instances. Therefore, the contracts of these + * methods are as defined in the JDK documentation. In particular, + * reSeed(long) fully resets the initial state of the non-secure + * random number generator (so that reseeding with a specific value always * results in the same subsequent random sequence); whereas reSeedSecure(long) - * does not reinitialize the secure random number generator - * (so secure sequences started with calls to reseedSecure(long) won't be + * does not reinitialize the secure random number generator + * (so secure sequences started with calls to reseedSecure(long) won't be * identical).
      - * - * @version $Revision: 1.14 $ $Date: 2004/06/02 00:20:21 $ + * + * @version $Revision: 1.15 $ $Date: 2004/06/14 23:15:15 $ */ public class RandomDataImpl implements RandomData, Serializable { - + /** Serializable version identifier */ static final long serialVersionUID = -626730818244969716L; /** underlying random number generator */ private Random rand = null; - + /** underlying secure random number generator */ private SecureRandom secRand = null; - + /** * Construct a RandomDataImpl. */ public RandomDataImpl() { } - + /** - * Algorithm Description: hex strings are generated + * Algorithm Description: hex strings are generated * using a 2-step process.
        *
      1. * len/2+1 binary bytes are generated using the underlying Random
        2. @@ -99,28 +99,28 @@ public class RandomDataImpl implements RandomData, Serializable { if (len <= 0) { throw new IllegalArgumentException("length must be positive"); } - + //Get a random number generator Random ran = getRan(); - + //Initialize output buffer StringBuffer outBuffer = new StringBuffer(); - + //Get int(len/2)+1 random bytes byte[] randomBytes = new byte[(len / 2) + 1]; ran.nextBytes(randomBytes); - + //Convert each byte to 2 hex digits for (int i = 0; i < randomBytes.length; i++) { Integer c = new Integer(randomBytes[i]); - + /* Add 128 to byte value to make interval 0-255 before * doing hex conversion. * This guarantees <= 2 hex digits from toHexString() * toHexString would otherwise add 2^32 to negative arguments. */ String hex = Integer.toHexString(c.intValue() + 128); - + // Make sure we add 2 hex digits for each byte if (hex.length() == 1) { hex = "0" + hex; @@ -136,7 +136,7 @@ public class RandomDataImpl implements RandomData, Serializable { * @param lower the lower bound. * @param upper the upper bound. * @return the random integer. - */ + */ public int nextInt(int lower, int upper) { if (lower >= upper) { throw new IllegalArgumentException @@ -145,14 +145,14 @@ public class RandomDataImpl implements RandomData, Serializable { Random rand = getRan(); return lower + (int) (rand.nextDouble() * (upper - lower + 1)); } - + /** * Generate a random long value uniformly distributed between * lower and upper, inclusive. * @param lower the lower bound. * @param upper the upper bound. * @return the random integer. - */ + */ public long nextLong(long lower, long upper) { if (lower >= upper) { throw new IllegalArgumentException @@ -161,19 +161,19 @@ public class RandomDataImpl implements RandomData, Serializable { Random rand = getRan(); return lower + (long) (rand.nextDouble() * (upper - lower + 1)); } - + /** - * Algorithm Description: hex strings are generated in + * Algorithm Description: hex strings are generated in * 40-byte segments using a 3-step process.
          *
        1. - * 20 random bytes are generated using the underlying + * 20 random bytes are generated using the underlying * SecureRandom.
          2. *
        2. * SHA-1 hash is applied to yield a 20-byte binary digest.
          3. *
        3. * Each byte of the binary digest is converted to 2 hex digits
        *

        - * TODO: find external reference or provide justification for the claim + * TODO: find external reference or provide justification for the claim * that this yields a cryptographically secure sequence of hex strings. * @param len the desired string length. * @return the random string. @@ -182,7 +182,7 @@ public class RandomDataImpl implements RandomData, Serializable { if (len <= 0) { throw new IllegalArgumentException("length must be positive"); } - + // Get SecureRandom and setup Digest provider SecureRandom secRan = getSecRan(); MessageDigest alg = null; @@ -191,31 +191,31 @@ public class RandomDataImpl implements RandomData, Serializable { } catch (NoSuchAlgorithmException ex) { return null; // gulp FIXME? -- this *should* never fail. } - alg.reset(); - + alg.reset(); + //Compute number of iterations required (40 bytes each) int numIter = (len / 40) + 1; - + StringBuffer outBuffer = new StringBuffer(); for (int iter = 1; iter < numIter + 1; iter++) { byte[] randomBytes = new byte[40]; secRan.nextBytes(randomBytes); alg.update(randomBytes); - + //Compute hash -- will create 20-byte binary hash byte hash[] = alg.digest(); - + //Loop over the hash, converting each byte to 2 hex digits for (int i = 0; i < hash.length; i++) { Integer c = new Integer(hash[i]); - + /* Add 128 to byte value to make interval 0-255 * This guarantees <= 2 hex digits from toHexString() - * toHexString would otherwise add 2^32 to negative + * toHexString would otherwise add 2^32 to negative * arguments */ String hex = Integer.toHexString(c.intValue() + 128); - + //Keep strings uniform length -- guarantees 40 bytes if (hex.length() == 1) { hex = "0" + hex; @@ -225,7 +225,7 @@ public class RandomDataImpl implements RandomData, Serializable { } return outBuffer.toString().substring(0, len); } - + /** * Generate a random int value uniformly distributed between * lower and upper, inclusive. This algorithm @@ -233,7 +233,7 @@ public class RandomDataImpl implements RandomData, Serializable { * @param lower the lower bound. * @param upper the upper bound. * @return the random integer. - */ + */ public int nextSecureInt(int lower, int upper) { if (lower >= upper) { throw new IllegalArgumentException @@ -242,7 +242,7 @@ public class RandomDataImpl implements RandomData, Serializable { SecureRandom sec = getSecRan(); return lower + (int) (sec.nextDouble() * (upper - lower + 1)); } - + /** * Generate a random long value uniformly distributed between * lower and upper, inclusive. This algorithm @@ -250,7 +250,7 @@ public class RandomDataImpl implements RandomData, Serializable { * @param lower the lower bound. * @param upper the upper bound. * @return the random integer. - */ + */ public long nextSecureLong(long lower, long upper) { if (lower >= upper) { throw new IllegalArgumentException @@ -259,16 +259,16 @@ public class RandomDataImpl implements RandomData, Serializable { SecureRandom sec = getSecRan(); return lower + (long) (sec.nextDouble() * (upper - lower + 1)); } - - /** + + /** * Generates a random long value from the Poisson distribution with the given mean. *

        * Algorithm Description: - * Uses simulation of a Poisson process using Uniform deviates, as - * described + * Uses simulation of a Poisson process using Uniform deviates, as + * described * * here. - *

        + *

        * The Poisson process (and hence value returned) is bounded by 1000 * mean. * @param mean mean of the Poisson distribution. * @return the random Poisson value. @@ -282,7 +282,7 @@ public class RandomDataImpl implements RandomData, Serializable { double r = 1.0d; double rnd = 1.0d; Random rand = getRan(); - while (n < 1000 * mean) { + while (n < 1000 * mean) { rnd = rand.nextDouble(); r = r * rnd; if (r >= p) { @@ -293,9 +293,9 @@ public class RandomDataImpl implements RandomData, Serializable { } return n; } - + /** - * Generate a random value from a Normal distribution. This algorithm + * Generate a random value from a Normal distribution. This algorithm * generates random values for the general Normal distribution with the * given mean, mu and the given standard deviation, * sigma. @@ -310,10 +310,10 @@ public class RandomDataImpl implements RandomData, Serializable { Random rand = getRan(); return sigma * rand.nextGaussian() + mu; } - + /** - * Algorithm Description: Uses the - * + * Algorithm Description: Uses the + * * Inversion Method to generate exponential from uniform deviates. * @param mean the mean of the distribution. * @return the random Exponential value. @@ -330,12 +330,12 @@ public class RandomDataImpl implements RandomData, Serializable { } return -mean * Math.log(unif); } - + /** - * Algorithm Description: scales the output of + * Algorithm Description: scales the output of * Random.nextDouble(), but rejects 0 values (i.e., will generate another - * random double if Random.nextDouble() returns 0). - * This is necessary to provide a symmetric output interval + * random double if Random.nextDouble() returns 0). + * This is necessary to provide a symmetric output interval * (both endpoints excluded). * @param lower the lower bound. * @param upper the upper bound. @@ -347,21 +347,21 @@ public class RandomDataImpl implements RandomData, Serializable { ("lower bound must be <= upper bound"); } Random rand = getRan(); - + // insure nextDouble() isn't 0.0 double u = rand.nextDouble(); while(u <= 0.0){ u = rand.nextDouble(); } - + return lower + u * (upper - lower); } - - /** + + /** * Returns the static Random used to generate random data. *

        * Creates and initializes if null. - * + * * @return the static Random used to generate random data */ private Random getRan() { @@ -371,8 +371,8 @@ public class RandomDataImpl implements RandomData, Serializable { } return rand; } - - /** + + /** * Returns the static SecureRandom used to generate secure random data. *

        * Creates and initializes if null. @@ -386,7 +386,7 @@ public class RandomDataImpl implements RandomData, Serializable { } return secRand; } - + /** * Reseeds the random number generator with the supplied seed. *

        @@ -400,11 +400,11 @@ public class RandomDataImpl implements RandomData, Serializable { } rand.setSeed(seed); } - + /** * Reseeds the secure random number generator with the current time - * in milliseconds. - *

        + * in milliseconds. + *

        * Will create and initialize if null. */ public void reSeedSecure() { @@ -413,7 +413,7 @@ public class RandomDataImpl implements RandomData, Serializable { } secRand.setSeed(System.currentTimeMillis()); } - + /** * Reseeds the secure random number generator with the supplied seed. *

        @@ -427,7 +427,7 @@ public class RandomDataImpl implements RandomData, Serializable { } secRand.setSeed(seed); } - + /** * Reseeds the random number generator with the current time * in milliseconds. @@ -438,29 +438,29 @@ public class RandomDataImpl implements RandomData, Serializable { } rand.setSeed(System.currentTimeMillis()); } - + /** * Sets the PRNG algorithm for the underlying SecureRandom instance - * using the Security Provider API. The Security Provider API is defined in + * using the Security Provider API. The Security Provider API is defined in * * Java Cryptography Architecture API Specification & Reference. *

        - * USAGE NOTE: This method carries significant + * USAGE NOTE: This method carries significant * overhead and may take several seconds to execute. *

        * * @param algorithm the name of the PRNG algorithm - * @param provider the name of the provider - * @throws NoSuchAlgorithmException if the specified algorithm + * @param provider the name of the provider + * @throws NoSuchAlgorithmException if the specified algorithm * is not available - * @throws NoSuchProviderException if the specified provider + * @throws NoSuchProviderException if the specified provider * is not installed */ - public void setSecureAlgorithm(String algorithm, String provider) + public void setSecureAlgorithm(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException { secRand = SecureRandom.getInstance(algorithm, provider); } - + /** * Uses a 2-cycle permutation shuffle to generate a random permutation. * The shuffling process is described @@ -474,35 +474,35 @@ public class RandomDataImpl implements RandomData, Serializable { if (k > n) { throw new IllegalArgumentException ("permutation k exceeds n"); - } + } if (k == 0) { throw new IllegalArgumentException ("permutation k must be > 0"); } - + int[] index = getNatural(n); shuffle(index, n - k); int[] result = new int[k]; for (int i = 0; i < k; i++) { result[i] = index[n - i - 1]; } - + return result; } - + /** * Uses a 2-cycle permutation shuffle to generate a random permutation. - * Algorithm Description: Uses a 2-cycle permutation - * shuffle to generate a random permutation of c.size() and - * then returns the elements whose indexes correspond to the elements of - * the generated permutation. - * This technique is described, and proven to generate random samples, + * Algorithm Description: Uses a 2-cycle permutation + * shuffle to generate a random permutation of c.size() and + * then returns the elements whose indexes correspond to the elements of + * the generated permutation. + * This technique is described, and proven to generate random samples, * * here * @param c Collection to sample from. * @param k sample size. * @return the random sample. - */ + */ public Object[] nextSample(Collection c, int k) { int len = c.size(); if (k > len) { @@ -513,22 +513,22 @@ public class RandomDataImpl implements RandomData, Serializable { throw new IllegalArgumentException ("sample size must be > 0"); } - + Object[] objects = c.toArray(); int[] index = nextPermutation(len, k); Object[] result = new Object[k]; for (int i = 0; i < k; i++) { result[i] = objects[index[i]]; - } + } return result; } - + //------------------------Private methods---------------------------------- - - /** + + /** * Uses a 2-cycle permutation shuffle to randomly re-order the last elements * of list. - * + * * @param list list to be shuffled * @param end element past which shuffling begins */ @@ -536,16 +536,16 @@ public class RandomDataImpl implements RandomData, Serializable { int target = 0; for (int i = list.length - 1 ; i >= end; i--) { if (i == 0) { - target = 0; + target = 0; } else { target = nextInt(0, i); } int temp = list[target]; list[target] = list[i]; list[i] = temp; - } + } } - + /** * Returns an array representing n. * @@ -559,5 +559,5 @@ public class RandomDataImpl implements RandomData, Serializable { } return natural; } - + } \ No newline at end of file diff --git a/src/java/org/apache/commons/math/random/ValueServer.java b/src/java/org/apache/commons/math/random/ValueServer.java index da39d4eb1..07ff81fc6 100644 --- a/src/java/org/apache/commons/math/random/ValueServer.java +++ b/src/java/org/apache/commons/math/random/ValueServer.java @@ -1,12 +1,12 @@ /* * Copyright 2003-2004 The Apache Software Foundation. - * + * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at - * + * * http://www.apache.org/licenses/LICENSE-2.0 - * + * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. @@ -26,74 +26,74 @@ import java.net.MalformedURLException; * Generates values for use in simulation applications. *

        * How values are generated is determined by the mode - * property. - *

        + * property. + *

        * Supported mode values are:

          *
        • DIGEST_MODE -- uses an empirical distribution
          • - *
        • REPLAY_MODE -- replays data from valuesFileURL
          • + *
        • REPLAY_MODE -- replays data from valuesFileURL
          • *
        • UNIFORM_MODE -- generates uniformly distributed random values with * mean = mu
          • *
        • EXPONENTIAL_MODE -- generates exponentially distributed random values * with mean = mu
          • *
        • GAUSSIAN_MODE -- generates Gaussian distributed random values with - * mean = mu and + * mean = mu and * standard deviation = sigma
          • - *
        • CONSTANT_MODE -- returns mu every time.
        + *
      2. CONSTANT_MODE -- returns mu every time.
        3. * - * @version $Revision: 1.12 $ $Date: 2004/02/21 21:35:15 $ + * @version $Revision: 1.13 $ $Date: 2004/06/14 23:15:15 $ * */ public class ValueServer implements Serializable { /** mode determines how values are generated */ private int mode = 5; - + /** URI to raw data values */ private URL valuesFileURL = null; - + /** Mean for use with non-data-driven modes */ private double mu = 0.0; - + /** Standard deviation for use with GAUSSIAN_MODE */ private double sigma = 0.0; - + /** Empirical probability distribution for use with DIGEST_MODE */ private EmpiricalDistribution empiricalDistribution = null; - + /** file pointer for REPLAY_MODE */ private BufferedReader filePointer = null; - + /** RandomDataImpl to use for random data generation */ private RandomDataImpl randomData = new RandomDataImpl(); - + // Data generation modes ====================================== - + /** Use empirical distribution */ - public static final int DIGEST_MODE = 0; - + public static final int DIGEST_MODE = 0; + /** Replay data from valuesFilePath */ - public static final int REPLAY_MODE = 1; - + public static final int REPLAY_MODE = 1; + /** Uniform random deviates with mean = mu */ - public static final int UNIFORM_MODE = 2; - + public static final int UNIFORM_MODE = 2; + /** Exponential random deviates with mean = mu */ - public static final int EXPONENTIAL_MODE = 3; - + public static final int EXPONENTIAL_MODE = 3; + /** Gaussian random deviates with mean = mu, std dev = sigma */ - public static final int GAUSSIAN_MODE = 4; - + public static final int GAUSSIAN_MODE = 4; + /** Always return mu */ - public static final int CONSTANT_MODE = 5; - + public static final int CONSTANT_MODE = 5; + /** Creates new ValueServer */ public ValueServer() { } - /** + /** * Returns the next generated value, generated according - * to the mode value (see MODE constants). + * to the mode value (see MODE constants). * - * @return generated value + * @return generated value * @throws IOException in REPLAY_MODE if a file I/O error occurs */ public double getNext() throws IOException { @@ -108,7 +108,7 @@ public class ValueServer implements Serializable { ("Bad mode: " + mode); } } - + /** * Fills the input array with values generated using getNext() repeatedly. * @@ -120,9 +120,9 @@ public class ValueServer implements Serializable { values[i] = getNext(); } } - + /** - * Returns an array of length length with values generated + * Returns an array of length length with values generated * using getNext() repeatedly. * * @param length length of output array @@ -135,9 +135,9 @@ public class ValueServer implements Serializable { out[i] = getNext(); } return out; - } - - /** + } + + /** * Computes the empirical distribution using values from the file * in valuesFileURL, using the default number of bins. *

        @@ -153,8 +153,8 @@ public class ValueServer implements Serializable { empiricalDistribution = new EmpiricalDistributionImpl(); empiricalDistribution.load(valuesFileURL); } - - /** + + /** * Computes the empirical distribution using values from the file * in valuesFileURL and binCount bins. *

        @@ -168,28 +168,28 @@ public class ValueServer implements Serializable { * distribution * @throws IOException if an error occurs reading the input file */ - public void computeDistribution(int binCount) + public void computeDistribution(int binCount) throws IOException { empiricalDistribution = new EmpiricalDistributionImpl(binCount); empiricalDistribution.load(valuesFileURL); mu = empiricalDistribution.getSampleStats().getMean(); sigma = empiricalDistribution.getSampleStats().getStandardDeviation(); } - + /** Getter for property mode. * @return Value of property mode. */ public int getMode() { return mode; } - + /** Setter for property mode. * @param mode New value of property mode. */ public void setMode(int mode) { this.mode = mode; } - + /** * Getter for valuesFileURL * @return Value of property valuesFileURL. @@ -197,7 +197,7 @@ public class ValueServer implements Serializable { public URL getValuesFileURL() { return valuesFileURL; } - + /** * Sets the valuesFileURL using a string URL representation * @param url String representation for new valuesFileURL. @@ -206,7 +206,7 @@ public class ValueServer implements Serializable { public void setValuesFileURL(String url) throws MalformedURLException { this.valuesFileURL = new URL(url); } - + /** * Sets the valuesFileURL * @param url New value of property valuesFileURL. @@ -214,15 +214,15 @@ public class ValueServer implements Serializable { public void setValuesFileURL(URL url) { this.valuesFileURL = url; } - + /** Getter for property empiricalDistribution. * @return Value of property empiricalDistribution. */ public EmpiricalDistribution getEmpiricalDistribution() { return empiricalDistribution; - } - - /** + } + + /** * Opens valuesFileURL to use in REPLAY_MODE. * * @throws IOException if an error occurs opening the file @@ -231,8 +231,8 @@ public class ValueServer implements Serializable { public void openReplayFile() throws IOException { resetReplayFile(); } - - /** + + /** * Resets REPLAY_MODE file pointer to the beginning of the valuesFileURL. * * @throws IOException if an error occurs opening the file @@ -246,8 +246,8 @@ public class ValueServer implements Serializable { } filePointer = new BufferedReader(new InputStreamReader(valuesFileURL.openStream())); } - - /** + + /** * Closes valuesFileURL after use in REPLAY_MODE. * * @throws IOException if an error occurs closing the file @@ -256,66 +256,66 @@ public class ValueServer implements Serializable { if (filePointer != null) { filePointer.close(); filePointer = null; - } + } } - + /** Getter for property mu. * @return Value of property mu. */ public double getMu() { return mu; } - + /** Setter for property mu. * @param mu New value of property mu. */ public void setMu(double mu) { this.mu = mu; } - + /** Getter for property sigma. * @return Value of property sigma. */ public double getSigma() { return sigma; } - + /** Setter for property sigma. * @param sigma New value of property sigma. */ public void setSigma(double sigma) { this.sigma = sigma; } - + //------------- private methods --------------------------------- - - /** + + /** * Gets a random value in DIGEST_MODE. *

        * Preconditions:

          *
        • Before this method is called, computeDistribution() - * must have completed successfully; otherwise an + * must have completed successfully; otherwise an * IllegalStateException will be thrown
        * - * @return next random value from the empirical distribution digest + * @return next random value from the empirical distribution digest */ private double getNextDigest() { if ((empiricalDistribution == null) || (empiricalDistribution.getBinStats().size() == 0)) { throw new IllegalStateException("Digest not initialized"); } - return empiricalDistribution.getNextValue(); + return empiricalDistribution.getNextValue(); } - + /** * Gets next sequential value from the valuesFileURL. *

        * Throws an IOException if the read fails. *

        - * This method will open the valuesFileURL if there is no + * This method will open the valuesFileURL if there is no * replay file open. *

        - * The valuesFileURL will be closed and reopened to wrap around + * The valuesFileURL will be closed and reopened to wrap around * from EOF to BOF if EOF is encountered. * * @return next value from the replay file @@ -330,29 +330,29 @@ public class ValueServer implements Serializable { closeReplayFile(); resetReplayFile(); str = filePointer.readLine(); - } + } return new Double(str).doubleValue(); } - - /** - * Gets a uniformly distributed random value with mean = mu. + + /** + * Gets a uniformly distributed random value with mean = mu. * * @return random uniform value */ private double getNextUniform() { return randomData.nextUniform(0, 2 * mu); } - - /** - * Gets an exponentially distributed random value with mean = mu. + + /** + * Gets an exponentially distributed random value with mean = mu. * * @return random exponential value */ private double getNextExponential() { - return randomData.nextExponential(mu); + return randomData.nextExponential(mu); } - - /** + + /** * Gets a Gaussian distributed random value with mean = mu * and standard deviation = sigma. * @@ -361,5 +361,5 @@ public class ValueServer implements Serializable { private double getNextGaussian() { return randomData.nextGaussian(mu, sigma); } - + } diff --git a/src/java/org/apache/commons/math/random/package.html b/src/java/org/apache/commons/math/random/package.html index ac0c11ef6..00abf5795 100644 --- a/src/java/org/apache/commons/math/random/package.html +++ b/src/java/org/apache/commons/math/random/package.html @@ -14,6 +14,6 @@ See the License for the specific language governing permissions and limitations under the License. --> - - Random number and random data generators. + + Random number and random data generators.