org.apache.commons.math3.random
Class ValueServer

java.lang.Object
  extended by org.apache.commons.math3.random.ValueServer

public class ValueServer
extends Object

Generates values for use in simulation applications.

How values are generated is determined by the mode property.

Supported mode values are:

Version:
$Id: ValueServer.java 1422350 2012-12-15 20:47:47Z psteitz $

Field Summary
static int CONSTANT_MODE
          Always return mu
static int DIGEST_MODE
          Use empirical distribution.
private  EmpiricalDistribution empiricalDistribution
          Empirical probability distribution for use with DIGEST_MODE.
static int EXPONENTIAL_MODE
          Exponential random deviates with mean = μ.
private  BufferedReader filePointer
          File pointer for REPLAY_MODE.
static int GAUSSIAN_MODE
          Gaussian random deviates with mean = μ, std dev = σ.
private  int mode
          mode determines how values are generated.
private  double mu
          Mean for use with non-data-driven modes.
private  RandomDataImpl randomData
          RandomDataImpl to use for random data generation.
static int REPLAY_MODE
          Replay data from valuesFilePath.
private  double sigma
          Standard deviation for use with GAUSSIAN_MODE.
static int UNIFORM_MODE
          Uniform random deviates with mean = μ.
private  URL valuesFileURL
          URI to raw data values.
 
Constructor Summary
ValueServer()
          Creates new ValueServer
ValueServer(RandomDataImpl randomData)
          Deprecated. use ValueServer(RandomGenerator)
ValueServer(RandomGenerator generator)
          Construct a ValueServer instance using a RandomGenerator as its source of random data.
 
Method Summary
 void closeReplayFile()
          Closes valuesFileURL after use in REPLAY_MODE.
 void computeDistribution()
          Computes the empirical distribution using values from the file in valuesFileURL, using the default number of bins.
 void computeDistribution(int binCount)
          Computes the empirical distribution using values from the file in valuesFileURL and binCount bins.
 void fill(double[] values)
          Fills the input array with values generated using getNext() repeatedly.
 double[] fill(int length)
          Returns an array of length length with values generated using getNext() repeatedly.
 EmpiricalDistribution getEmpiricalDistribution()
          Returns the EmpiricalDistribution used when operating in 0.
 int getMode()
          Returns the data generation mode.
 double getMu()
          Returns the mean used when operating in GAUSSIAN_MODE, EXPONENTIAL_MODE or UNIFORM_MODE.
 double getNext()
          Returns the next generated value, generated according to the mode value (see MODE constants).
private  double getNextDigest()
          Gets a random value in DIGEST_MODE.
private  double getNextExponential()
          Gets an exponentially distributed random value with mean = mu.
private  double getNextGaussian()
          Gets a Gaussian distributed random value with mean = mu and standard deviation = sigma.
private  double getNextReplay()
          Gets next sequential value from the valuesFileURL.
private  double getNextUniform()
          Gets a uniformly distributed random value with mean = mu.
 double getSigma()
          Returns the standard deviation used when operating in GAUSSIAN_MODE.
 URL getValuesFileURL()
          Returns the URL for the file used to build the empirical distribution when using DIGEST_MODE.
 void reSeed(long seed)
          Reseeds the random data generator.
 void resetReplayFile()
          Resets REPLAY_MODE file pointer to the beginning of the valuesFileURL.
 void setMode(int mode)
          Sets the data generation mode.
 void setMu(double mu)
          Sets the mean used in data generation.
 void setSigma(double sigma)
          Sets the standard deviation used in GAUSSIAN_MODE.
 void setValuesFileURL(String url)
          Sets the values file URL using a string URL representation.
 void setValuesFileURL(URL url)
          Sets the the values file URL.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DIGEST_MODE

public static final int DIGEST_MODE
Use empirical distribution.

See Also:
Constant Field Values

REPLAY_MODE

public static final int REPLAY_MODE
Replay data from valuesFilePath.

See Also:
Constant Field Values

UNIFORM_MODE

public static final int UNIFORM_MODE
Uniform random deviates with mean = μ.

See Also:
Constant Field Values

EXPONENTIAL_MODE

public static final int EXPONENTIAL_MODE
Exponential random deviates with mean = μ.

See Also:
Constant Field Values

GAUSSIAN_MODE

public static final int GAUSSIAN_MODE
Gaussian random deviates with mean = μ, std dev = σ.

See Also:
Constant Field Values

CONSTANT_MODE

public static final int CONSTANT_MODE
Always return mu

See Also:
Constant Field Values

mode

private int mode
mode determines how values are generated.


valuesFileURL

private URL valuesFileURL
URI to raw data values.


mu

private double mu
Mean for use with non-data-driven modes.


sigma

private double sigma
Standard deviation for use with GAUSSIAN_MODE.


empiricalDistribution

private EmpiricalDistribution empiricalDistribution
Empirical probability distribution for use with DIGEST_MODE.


filePointer

private BufferedReader filePointer
File pointer for REPLAY_MODE.


randomData

private final RandomDataImpl randomData
RandomDataImpl to use for random data generation.

Constructor Detail

ValueServer

public ValueServer()
Creates new ValueServer


ValueServer

public ValueServer(RandomDataImpl randomData)
Deprecated. use ValueServer(RandomGenerator)

Construct a ValueServer instance using a RandomDataImpl as its source of random data.

Parameters:
randomData - the RandomDataImpl instance used to source random data
Since:
3.0

ValueServer

public ValueServer(RandomGenerator generator)
Construct a ValueServer instance using a RandomGenerator as its source of random data.

Parameters:
generator - source of random data
Since:
3.1
Method Detail

getNext

public double getNext()
               throws IOException,
                      MathIllegalStateException,
                      MathIllegalArgumentException
Returns the next generated value, generated according to the mode value (see MODE constants).

Returns:
generated value
Throws:
IOException - in REPLAY_MODE if a file I/O error occurs
MathIllegalStateException - if mode is not recognized
MathIllegalArgumentException - if the underlying random generator thwrows one

fill

public void fill(double[] values)
          throws IOException,
                 MathIllegalStateException,
                 MathIllegalArgumentException
Fills the input array with values generated using getNext() repeatedly.

Parameters:
values - array to be filled
Throws:
IOException - in REPLAY_MODE if a file I/O error occurs
MathIllegalStateException - if mode is not recognized
MathIllegalArgumentException - if the underlying random generator thwrows one

fill

public double[] fill(int length)
              throws IOException,
                     MathIllegalStateException,
                     MathIllegalArgumentException
Returns an array of length length with values generated using getNext() repeatedly.

Parameters:
length - length of output array
Returns:
array of generated values
Throws:
IOException - in REPLAY_MODE if a file I/O error occurs
MathIllegalStateException - if mode is not recognized
MathIllegalArgumentException - if the underlying random generator thwrows one

computeDistribution

public void computeDistribution()
                         throws IOException,
                                ZeroException,
                                NullArgumentException
Computes the empirical distribution using values from the file in valuesFileURL, using the default number of bins.

valuesFileURL must exist and be readable by *this at runtime.

This method must be called before using getNext() with mode = DIGEST_MODE

Throws:
IOException - if an I/O error occurs reading the input file
NullArgumentException - if the valuesFileURL has not been set
ZeroException - if URL contains no data

computeDistribution

public void computeDistribution(int binCount)
                         throws NullArgumentException,
                                IOException,
                                ZeroException
Computes the empirical distribution using values from the file in valuesFileURL and binCount bins.

valuesFileURL must exist and be readable by this process at runtime.

This method must be called before using getNext() with mode = DIGEST_MODE

Parameters:
binCount - the number of bins used in computing the empirical distribution
Throws:
NullArgumentException - if the valuesFileURL has not been set
IOException - if an error occurs reading the input file
ZeroException - if URL contains no data

getMode

public int getMode()
Returns the data generation mode. See the class javadoc for description of the valid values of this property.

Returns:
Value of property mode.

setMode

public void setMode(int mode)
Sets the data generation mode.

Parameters:
mode - New value of the data generation mode.

getValuesFileURL

public URL getValuesFileURL()
Returns the URL for the file used to build the empirical distribution when using DIGEST_MODE.

Returns:
Values file URL.

setValuesFileURL

public void setValuesFileURL(String url)
                      throws MalformedURLException
Sets the values file URL using a string URL representation.

Parameters:
url - String representation for new valuesFileURL.
Throws:
MalformedURLException - if url is not well formed

setValuesFileURL

public void setValuesFileURL(URL url)
Sets the the values file URL.

The values file must be an ASCII text file containing one valid numeric entry per line.

Parameters:
url - URL of the values file.

getEmpiricalDistribution

public EmpiricalDistribution getEmpiricalDistribution()
Returns the EmpiricalDistribution used when operating in 0.

Returns:
EmpircalDistribution built by computeDistribution()

resetReplayFile

public void resetReplayFile()
                     throws IOException
Resets REPLAY_MODE file pointer to the beginning of the valuesFileURL.

Throws:
IOException - if an error occurs opening the file

closeReplayFile

public void closeReplayFile()
                     throws IOException
Closes valuesFileURL after use in REPLAY_MODE.

Throws:
IOException - if an error occurs closing the file

getMu

public double getMu()
Returns the mean used when operating in GAUSSIAN_MODE, EXPONENTIAL_MODE or UNIFORM_MODE. When operating in CONSTANT_MODE, this is the constant value always returned. Calling computeDistribution() sets this value to the overall mean of the values in the values file.

Returns:
Mean used in data generation.

setMu

public void setMu(double mu)
Sets the mean used in data generation. Note that calling this method after computeDistribution() has been called will have no effect on data generated in DIGEST_MODE.

Parameters:
mu - new Mean value.

getSigma

public double getSigma()
Returns the standard deviation used when operating in GAUSSIAN_MODE. Calling computeDistribution() sets this value to the overall standard deviation of the values in the values file. This property has no effect when the data generation mode is not GAUSSIAN_MODE.

Returns:
Standard deviation used when operating in GAUSSIAN_MODE.

setSigma

public void setSigma(double sigma)
Sets the standard deviation used in GAUSSIAN_MODE.

Parameters:
sigma - New standard deviation.

reSeed

public void reSeed(long seed)
Reseeds the random data generator.

Parameters:
seed - Value with which to reseed the RandomDataImpl used to generate random data.

getNextDigest

private double getNextDigest()
                      throws MathIllegalStateException
Gets a random value in DIGEST_MODE.

Preconditions:

Returns:
next random value from the empirical distribution digest
Throws:
MathIllegalStateException - if digest has not been initialized

getNextReplay

private double getNextReplay()
                      throws IOException,
                             MathIllegalStateException
Gets next sequential value from the valuesFileURL.

Throws an IOException if the read fails.

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

The valuesFileURL will be closed and reopened to wrap around from EOF to BOF if EOF is encountered. EOFException (which is a kind of IOException) may still be thrown if the valuesFileURL is empty.

Returns:
next value from the replay file
Throws:
IOException - if there is a problem reading from the file
MathIllegalStateException - if URL contains no data
NumberFormatException - if an invalid numeric string is encountered in the file

getNextUniform

private double getNextUniform()
                       throws MathIllegalArgumentException
Gets a uniformly distributed random value with mean = mu.

Returns:
random uniform value
Throws:
MathIllegalArgumentException - if the underlying random generator thwrows one

getNextExponential

private double getNextExponential()
                           throws MathIllegalArgumentException
Gets an exponentially distributed random value with mean = mu.

Returns:
random exponential value
Throws:
MathIllegalArgumentException - if the underlying random generator thwrows one

getNextGaussian

private double getNextGaussian()
                        throws MathIllegalArgumentException
Gets a Gaussian distributed random value with mean = mu and standard deviation = sigma.

Returns:
random Gaussian value
Throws:
MathIllegalArgumentException - if the underlying random generator thwrows one


Copyright (c) 2003-2013 Apache Software Foundation