Package jsl.modeling.elements.variable

Class RandomVariable

  • All Implemented Interfaces:
    RandomElementIfc, ObservableIfc, StreamOptionIfc, GetNameIfc, GetValueIfc, IdentityIfc, RandomIfc, GetRandomNumberStreamIfc, RNStreamControlIfc, SetRandomNumberStreamIfc, SampleIfc
    Direct Known Subclasses:
    NHPPTimeBtwEventRV
    public class RandomVariable
extends ModelElement
implements RandomIfc, RandomElementIfc
    A random variable (RandomVariable) is a function that maps a probability space to a real number. A random variable uses a RandomIfc to provide the underlying mapping to a real number via the getValue() method.

    To construct a RandomVariable the user must provide an instance of a class that implements the RandomIfc interface as the initial random source. This source is used to initialize the source of randomness for each replication.

    WARNING: For efficiency, this class uses a direct reference to the supplied initial random source. It simply wraps the supplied object reference to a random source so that it can be utilized within the JSL model. Because of the direct reference to the random source, a change to the state of the random source will be reflected in the use of that instance within this class. Thus, mutating the state of the random source will also see those mutations reflected in the usage of this class. This may or not be what is expected by the client. For example, mutating the state of the initial random source during a replication may cause each replication to start with different initial conditions.

    Using the setRandomSource() method allows the user to change the source of randomness during a replication. The source of randomness during a replication is set to the reference of the initial random source at the beginning of each replication. This ensures that each replication uses the same random source during the replication. However, the user may call the setRandomSource() method to immediately change the source of randomness during the replication. This change is in effect only during the current replication. At the beginning of each replication, the source of randomness is set to the reference to the initial random source. This ensures that each replication uses the same random source. For this reason, the use of setInitialRandomSource() should be limited to before or after running a simulation experiment.

    The initial source is used to set up the source used during the replication. If the client changes the reference to the initial source, this change does not become effective until the beginning of the next replication. In other words, the random source used during the replication is unaffected. However, the client might mutate the initial random source during a replication. If this occurs, those changes are immediately reflected within the current replication and all subsequent replications. Again, mutating the initial random source during a replication is generally a bad idea unless you really know what you are doing.

    Changing the initial random source between experiments is very common. For example, to set up an experiment that has different random characteristics the client can and should change the source of randomness (either by mutating the random source or by supplying a reference to a different random source.

    • Field Detail

      • myResetStartStreamOption

        protected boolean myResetStartStreamOption
        indicates whether or not the random variable's distribution has it stream reset to the default stream, or not prior to each experiment. Resetting allows each experiment to use the same underlying random numbers i.e. common random numbers, this is the default

        Setting it to true indicates that it does reset

      • myAdvanceToNextSubStreamOption

        protected boolean myAdvanceToNextSubStreamOption
        indicates whether or not the random variable's distribution has it stream reset to the next sub-stream stream, or not, prior to each replication. Resetting allows each replication to better ensure that each replication will be start at the same place in the sub-streams, thereby, improving synchronization when using common random numbers.

        Setting it to true indicates that it does jump to the next sub-stream, true is the default

      • myRandomSource

        protected RandomIfc myRandomSource
        RandomIfc provides a reference to the underlying source of randomness during the replication

      • myInitialRandomSource

        protected RandomIfc myInitialRandomSource
        RandomIfc provides a reference to the underlying source of randomness to initialize each replication.

      • myCaptureResponseFlag

        protected boolean myCaptureResponseFlag
        A flag to indicate whether or not a ResponseVariable should be created and used to capture the randomly generated values. Useful for control variate implementation

      • myResponse

        protected ResponseVariable myResponse
        Used to capture the randomly generated values if the capture response flag is true

      • myInitialRandomSourceChangeWarning

        protected boolean myInitialRandomSourceChangeWarning
        Controls whether warning of changing the initial random source during a replication is logged, default is true.

    • Constructor Detail

      • RandomVariable

        public RandomVariable​(ModelElement parent,
                      RandomIfc initialSource)
        Constructs a RandomVariable given the supplied reference to the underlying source of randomness Throws a NullPointerException if the supplied randomness is null
        Parameters:
        parent - The parent ModelElement
        initialSource - The reference to the underlying source of randomness

      • RandomVariable

        public RandomVariable​(ModelElement parent,
                      RandomIfc initialSource,
                      java.lang.String name)
        Constructs a RandomVariable given the supplied reference to the underlying source of randomness Throws a NullPointerException if the supplied randomness is null
        Parameters:
        parent - The parent ModelElement
        initialSource - The reference to the underlying source of randomness
        name - A string to label the RandomVariable

    • Method Detail

      • getInitialRandomSourceChangeWarningOption

        public final boolean getInitialRandomSourceChangeWarningOption()
        Returns:
        true means the option will be logged

      • setInitialRandomSourceChangeWarningOption

        public final void setInitialRandomSourceChangeWarningOption​(boolean flag)
        Controls whether or not the change of the initial random source will be logged if made during the replication
        Parameters:
        flag - true means warning will be logged

      • setRandomNumberStream

        public void setRandomNumberStream​(RNStreamIfc stream)
        Changes the stream for the *initial random source*.
        Specified by:
        setRandomNumberStream in interface SetRandomNumberStreamIfc
        Parameters:
        stream - the reference to the random number stream, must not be null

      • setResetStartStreamOption

        public final void setResetStartStreamOption​(boolean b)
        Description copied from interface: StreamOptionIfc
        Sets the reset start stream option, true means that it will be reset to the starting stream
        Specified by:
        setResetStartStreamOption in interface StreamOptionIfc
        Parameters:
        b - true means reset

      • getResetNextSubStreamOption

        public final boolean getResetNextSubStreamOption()
        Description copied from interface: StreamOptionIfc
        Gets the current reset next sub-stream option true means, that it is set to jump to the next sub-stream after each replication
        Specified by:
        getResetNextSubStreamOption in interface StreamOptionIfc
        Returns:
        the option

      • setResetNextSubStreamOption

        public final void setResetNextSubStreamOption​(boolean b)
        Description copied from interface: StreamOptionIfc
        Sets the current reset next sub-stream option true means, that it is set to jump to the next sub-stream after each replication
        Specified by:
        setResetNextSubStreamOption in interface StreamOptionIfc
        Parameters:
        b - true means reset

      • setAntitheticOption

        public final void setAntitheticOption​(boolean flag)
        Description copied from interface: RNStreamControlIfc
        Tells the stream to start producing antithetic variates
        Specified by:
        setAntitheticOption in interface RNStreamControlIfc
        Parameters:
        flag - true means that it produces antithetic variates.

      • resetStartStream

        public final void resetStartStream()
        Description copied from interface: RNStreamControlIfc
        The resetStartStream method will position the RNG at the beginning of its stream. This is the same location in the stream as assigned when the RNG was created and initialized.
        Specified by:
        resetStartStream in interface RNStreamControlIfc

      • getInitialRandomSource

        public final RandomIfc getInitialRandomSource()
        Gets the underlying RVariableIfc for the RandomVariable. This is the source to which each replication will be initialized
        Returns:
        a RVariableIfc

      • setInitialRandomSource

        public final void setInitialRandomSource​(RandomIfc source)
        Sets the underlying RandomIfc source for the RandomVariable. This is the source to which each replication will be initialized. This is only used when the replication is initialized. Changing the reference has no effect during a replication, since the random variable will continue to use the reference returned by getRandomSource(). Please also see the discussion in the class documentation.

        WARNING: If this is used during an experiment to change the characteristics of the random source, then each replication may not necessarily start in the same initial state. It is recommended that this be used only prior to executing experiments.

        Parameters:
        source - the reference to the random source, must not be null

      • turnOnResponseCapture

        public final void turnOnResponseCapture()
        Turns on the capturing of the generated random values with a ResponseVariable

      • getCapturedResponse

        public final java.util.Optional<ResponseVariable> getCapturedResponse()
        If the capturing of the random variable generated values is turned on (turnOnResponseCapture()), then this allows the response to be retrieved.
        Returns:
        an optional holding the ResponseVariable

      • getCaptureResponseFlag

        public final boolean getCaptureResponseFlag()
        Returns:
        true means that the values are being captured via a ResponseVariable

      • getRandomSource

        public final RandomIfc getRandomSource()
        Gets the underlying RandomIfc for the RandomVariable currently being used during the replication
        Returns:
        a RandomIfc

      • setRandomSource

        public final void setRandomSource​(RandomIfc source)
        Sets the underlying RandomIfc source for the RandomVariable. This changes the source for the current replication only. The random variable will start to use this source immediately; however if a replication is started after this method is called, the random source will be reassigned to the initial random source before the next replication is executed.

        To set the random source for the entire experiment (all replications) use the setInitialRandomSource() method

        Parameters:
        source - the reference to the random source, must not be null

      • getValue

        public double getValue()
        Each call to getValue() returns a new observation
        Specified by:
        getValue in interface GetValueIfc
        Returns:
        The value.

      • getSumOfValues

        public double getSumOfValues​(int n)
        Returns the sum of n random draws of the random variable if n <= 0, then the sum is 0.0
        Parameters:
        n - the number to sum
        Returns:
        the sum

      • sample

        public final double sample()
        Specified by:
        sample in interface SampleIfc
        Returns:
        generates a random value

      • asString

        public java.lang.String asString()
        Description copied from class: ModelElement
        Allows sub-classes to provide more detail than toString() to represent the ModelElement as a String
        Overrides:
        asString in class ModelElement
        Returns:
        a detailed String representation

      • removedFromModel

        protected void removedFromModel()
        Description copied from class: ModelElement
        This method should be overridden by subclasses that need actions performed when a model element is removed from a model
        Overrides:
        removedFromModel in class ModelElement

      • beforeExperiment

        protected void beforeExperiment()
        before any replications reset the underlying random number generator to the starting stream
        Overrides:
        beforeExperiment in class ModelElement

      • afterReplication

        protected void afterReplication()
        after each replication reset the underlying random number generator to the next sub-stream
        Overrides:
        afterReplication in class ModelElement