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.

  • Field Details

    • DIGEST_MODE

      public static final int DIGEST_MODE
      Use empirical distribution.
      See Also:

    • REPLAY_MODE

      public static final int REPLAY_MODE
      Replay data from valuesFilePath.
      See Also:

    • UNIFORM_MODE

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

    • EXPONENTIAL_MODE

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

    • GAUSSIAN_MODE

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

    • CONSTANT_MODE

      public static final int CONSTANT_MODE
      Always return mu
      See Also:

    • 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 RandomDataGenerator randomData
      RandomDataImpl to use for random data generation.

  • Constructor Details

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

    • 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
      NullPointerException - if the valuesFileURL has not been set.

    • 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