org.apache.commons.math3.random

## Class ValueServer

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

  - 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
    Modifier and Type | Field and 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 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

    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
    Modifier and Type | Method and 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`.
    `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:

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