Package jsl.utilities.random.rng

Interface RNStreamProviderIfc

  • All Known Implementing Classes:
    RNStreamProvider
    public interface RNStreamProviderIfc
    An interface to define the ability to provide random number streams (RNStreamIfc) Conceptualizes this process as making a sequence of streams, numbered 1, 2, 3, ... for use in generating pseudo-random numbers that can be controlled.

    • Method Detail

      • defaultRNStream

        default RNStreamIfc defaultRNStream()
        It is useful to designate one of the streams in the sequence of streams as the default stream from the provider. When clients don't care to get new streams, this method guarantees that the same stream is returned every time.
        Returns:
        the default stream from this provider

      • defaultRNStreamNumber

        int defaultRNStreamNumber()
        The sequence number associated with the default random number stream. This allows clients to know what stream number has been assigned to the default.
        Returns:
        the stream number of the default random number stream for this provider

      • nextRNStream

        RNStreamIfc nextRNStream()
        Tells the provider to make and return the next RNStreamIfc in the sequence of streams
        Returns:
        the made stream

      • lastRNStreamNumber

        int lastRNStreamNumber()
        Each call to nextStream() makes another stream in the sequence of streams. This method should return the number of streams provided by the provider. If nextStream() is called once, then lastRNStreamNumber() should return 1. If nextStream() is called twice then lastRNStreamNumber() should return 2, etc. Thus, this method returns the number in the sequence associated with the last stream made. If lastRNStreamNumber() returns 0, then no streams have been provided.
        Returns:
        the number in the sequence associated with the last stream made

      • rnStream

        RNStreamIfc rnStream​(int i)
        Tells the provider to return the ith stream of the sequence of streams that it provides. If i is greater than lastRNStreamNumber() then lastRNStreamNumber() is advanced according to the additional number of streams. For example, if lastRNStreamNumber() = 10 and i = 15, then streams 11, 12, 13, 14, 15 are assumed provided and stream 15 is returned and lastRNStreamNumber() now equals 15. If i is less than or equal to lastRNStreamNumber(), then no new streams are created, lastRNStreamNumber() stays at its current value and the ith stream is returned.
        Parameters:
        i - the ith stream in the sequence of provided streams, must be 1, 2, 3 ...
        Returns:
        the ith RNStreamIfc provided in the sequence of streams

      • getStreamNumber

        int getStreamNumber​(RNStreamIfc stream)
        Parameters:
        stream - the stream to find the number for
        Returns:
        the stream number of the stream for this provider or -1 if the stream has not been provided by this provider. Valid stream numbers start at 1.

      • hasProvided

        default boolean hasProvided​(RNStreamIfc stream)
        Parameters:
        stream - the stream to find the number for
        Returns:
        true if this provider has provided the stream

      • advanceStreamMechanism

        void advanceStreamMechanism​(int n)
        Advances the state of the provider through n streams. Acts as if n streams were created, without actually creating the streams. lastRNStreamNumber() remains the same after calling this method. In other words, this method should act as if nextRNStream() was not called but advance the underlying stream mechanism as if n streams had been provided.
        Parameters:
        n - the number of times to advance

      • resetRNStreamSequence

        void resetRNStreamSequence()
        Causes the provider to act as if it has never created any streams. Thus, the next call to nextRNStream() after the reset should return the 1st stream in the sequence of streams that this provider would normally provide in the order in which they would be provided.

      • resetAllStreamsToStart

        default void resetAllStreamsToStart()
        Causes all streams that have been provided to be reset to the start of their stream. Thus, the individual streams act as if they have not generated any pseudo-random numbers. Note: This call only effects previously provided streams.

      • resetAllStreamsToStartOfCurrentSubStream

        default void resetAllStreamsToStartOfCurrentSubStream()
        Causes all streams that have been provided to be reset to the start of their current sub-stream. Thus, the individual streams act as if they have not generated any pseudo-random numbers relative to their current sub-stream. Note: This call only effects previously provided streams.

      • advanceAllStreamsToNextSubstream

        default void advanceAllStreamsToNextSubstream()
        Causes all streams that have been provided to advance to the start of their next sub-stream. Thus, the individual streams skip any pseudo-random numbers in their current sub-stream and are positioned at the beginning of their next sub-stream. Note: This call only effects previously provided streams.

      • setAllStreamsAntitheticOption

        default void setAllStreamsAntitheticOption​(boolean option)
        Causes all streams that have been provided to change their antithetic option to the supplied value. Any new streams provided after this call will not necessarily have the same antithetic option as previous streams if this method is called in the interim. Note: This call only effects previously provided streams.
        Parameters:
        option - true means that the streams will now produce antithetic variates from the current position in their stream