Package org.apache.commons.math3.random

Class ValueServer

java.lang.Object

org.apache.commons.math3.random.ValueServer

public class ValueServer
extends java.lang.Object

Generates values for use in simulation applications.

How values are generated is determined by the mode property.

Supported mode values are:

• DIGEST_MODE -- uses an empirical distribution
• 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 standard deviation = sigma
• CONSTANT_MODE -- returns mu every time.

Field Summary

Fields

Modifier and Type	Field	Description
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 java.io.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 RandomDataGenerator	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 java.net.URL	valuesFileURL	URI to raw data values.

Constructor Summary

Constructors

Constructor	Description
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

Modifier and Type	Method	Description
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.
java.net.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(java.lang.String url)	Sets the values file URL using a string URL representation.
void	setValuesFileURL(java.net.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 java.net.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 java.io.BufferedReader filePointer

File pointer for REPLAY_MODE.

randomData

private final RandomDataGenerator randomData

RandomDataImpl to use for random data generation.

Constructor Detail

ValueServer

public ValueServer()

Creates new ValueServer

ValueServer

@Deprecated
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 java.io.IOException,
                      MathIllegalStateException,
                      MathIllegalArgumentException

Returns the next generated value, generated according to the mode value (see MODE constants).

Returns:

generated value

Throws:

java.io.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 java.io.IOException,
                 MathIllegalStateException,
                 MathIllegalArgumentException

Fills the input array with values generated using getNext() repeatedly.

Parameters:

values - array to be filled

Throws:

java.io.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 java.io.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:

java.io.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 java.io.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:

java.io.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,
                                java.io.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

java.io.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 java.net.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(java.lang.String url)
                      throws java.net.MalformedURLException

Sets the values file URL using a string URL representation.

Parameters:

url - String representation for new valuesFileURL.

Throws:

java.net.MalformedURLException - if url is not well formed

setValuesFileURL

public void setValuesFileURL(java.net.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 java.io.IOException

Resets REPLAY_MODE file pointer to the beginning of the valuesFileURL.

Throws:

java.io.IOException - if an error occurs opening the file

java.lang.NullPointerException - if the valuesFileURL has not been set.

closeReplayFile

public void closeReplayFile()
                     throws java.io.IOException

Closes valuesFileURL after use in REPLAY_MODE.

Throws:

java.io.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:

• Before this method is called, computeDistribution() must have completed successfully; otherwise an IllegalStateException will be thrown

Returns:

next random value from the empirical distribution digest

Throws:

MathIllegalStateException - if digest has not been initialized

getNextReplay

private double getNextReplay()
                      throws java.io.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:

java.io.IOException - if there is a problem reading from the file

MathIllegalStateException - if URL contains no data

java.lang.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