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.

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

### Field Summary

Fields
`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 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 java.net.URL` `valuesFileURL` URI to raw data values.

### Constructor Summary

Constructors
Constructor and 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

Methods
`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 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 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

#### 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