Main Content

qrandstream

Quasirandom number stream

expand all in page

    Description

    The qrandstream function creates a qrandstream object, which represents a quasirandom number stream. After you create a qrandstream object, you can use it to generate quasirandom numbers and set the stream back to its initial state by using the object functions.

    Creation

    Syntax

    q = qrandstream(type,d)
    q = qrandstream(type,d,Name=Value)
    q = qrandstream(p)

    Description

    q = qrandstream(type,d) creates a d-dimensional quasirandom number stream of type type and stores the result in the qrandstream object q.

    example

    q = qrandstream(type,d,Name=Value) specifies additional options using one or more name-value arguments. For example, you can specify the interval between points and the number of initial points to skip in the sequence.

    example

    q = qrandstream(p) creates a quasirandom stream on the quasirandom point set object p. p must be a haltonset or sobolset object.

    example

    Input Arguments

    expand all

    Name of the sequence from which qrandstream generates quasirandom numbers, specified as "halton" or "sobol". Use this argument to create a quasirandom number stream from the Halton or Sobol sequence. For more information, see haltonset and sobolset.

    Example: "sobol"

    Data Types: char | string

    Dimension of the quasirandom number stream, specified as a positive integer.

    Example: 5

    Data Types: single | double

    Point set from which qrandstream generates quasirandom numbers, specified as a haltonset or sobolset object. Use the haltonset or sobolset function to create p.

    Name-Value Arguments

    Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

    Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

    Example: qrandstream("sobol",3,Skip=5,Leap=50) creates a three-dimensional quasirandom number stream that omits the first five points from a Sobol sequence, and then omits 50 points in the sequence after each generated number.

    Number of initial points in the sequence to omit from the point set, specified as a positive integer scalar.

    Initial points of a sequence sometimes exhibit unwanted properties. For example, the first point is often (0,0,0,...), which can cause the sequence to be unbalanced because the counterpart of the point, (1,1,1,...), never appears. Initial points often exhibit correlations among different dimensions, and these correlations disappear later in the sequence.

    Example: Skip=2e3

    Data Types: single | double

    Interval between points in the sequence, specified as a positive integer scalar. The Leap property of the point set in the qrandstream object specifies the number of points in the sequence to leap over and omit for every point taken. The default Leap value is 0, which corresponds to taking every point in the sequence.

    Leaping is a technique used to improve the quality of a point set. However, you must specify the Leap value carefully. Many Leap values create sequences that fail to touch on large sub-hyper-rectangles of the unit hypercube and, therefore, fail to produce a uniform quasirandom point set. For more information, see [4].

    Example: Leap=50

    Data Types: single | double

    Point generation method, specified as "standard" or "graycode". You can specify PointOrder only when type is "sobol".

    The PointOrder property specifies the order in which the Sobol sequence points are produced. When PointOrder is set to "standard", the points produced match the original Sobol sequence implementation. When PointOrder is set to "graycode", the sequence is generated by an implementation that uses the Gray code of the index instead of the index itself.

    You can use the "graycode" option for faster sequence generation, but the software then changes the order of the generated points. For more information on the Gray code implementation, see [1].

    Example: PointOrder="graycode"

    Properties

    expand all

    This property is read-only.

    Point set from which qrandstream generates quasirandom numbers, specified as a haltonset or sobolset object. You can specify PointSet when creating the qrandstream object by using the p input argument, or by using the type input argument. To view the properties of PointSet when PointSet is a haltonset object, see haltonset. When PointSet is a sobolset object, see sobolset.

    Index of the next number in the quasirandom number stream, specified as a positive integer. The initial value of State is 1. You can reset the State property to 1 by using the reset function.

    Data Types: double

    Object Functions

    qrandGenerate quasirandom points from stream
    randGenerate quasirandom points from stream
    resetReset state

    Examples

    collapse all

    Open Live Script

    Generate a two-dimensional random stream from a Sobol sequence.

    q = qrandstream("sobol",2)
    q = 
Sobol quasi-random stream in 2 dimensions

Point set properties:
              Skip : 0
              Leap : 0
    ScrambleMethod : none
        PointOrder : standard

    q is a qrandstream object that contains the point set and parameters for a two-dimensional quasirandom number stream.

    Open Live Script

    Create a quasirandom number stream from a Halton sequence. Omit the first 1000 points in the sequence from the stream and the next 100 points after each generated number. Generate points from the qrandstream object, and then set the stream back to its original state.

    q = qrandstream("halton",3,Skip=1e3,Leap=1e2)
    q = 
Halton quasi-random stream in 3 dimensions

Point set properties:
              Skip : 1000
              Leap : 100
    ScrambleMethod : none

    q is a qrandstream object that contains the point set and parameters for a three-dimensional quasirandom number stream. q generates numbers from the Halton sequence.

    Generate four points from q.

    X = qrand(q,4)
    X = 4×3

    0.0928    0.3475    0.0051
    0.6958    0.2035    0.2371
    0.3013    0.8496    0.4307
    0.9087    0.5629    0.6166

    The rows of X contain the first four points in the stream, and the columns of X correspond to the dimensions of the points.

    Display the State property of q.

    q.State
    ans = 
5

    The State property shows that the index of the next point in the number stream is 5.

    Reset State to 1 and generate another point from q.

    reset(q)
x1 = qrand(q)
    x1 = 1×3

    0.0928    0.3475    0.0051

    x1 is identical to the first row in X because they both contain the first point in the stream.

    Open Live Script

    Create a three-dimensional point set from a Sobol sequence and scramble the point set.

    s = sobolset(3);
p = scramble(s,"MatousekAffineOwen")
    p = 
Sobol point set in 3 dimensions (9007199254740992 points)

Properties:
              Skip : 0
              Leap : 0
    ScrambleMethod : MatousekAffineOwen
        PointOrder : standard

    p is a sobolset object that contains a point set created by scrambling a Sobol sequence.

    Create a quasirandom number stream from p.

    q = qrandstream(p)
    q = 
Sobol quasi-random stream in 3 dimensions

Point set properties:
              Skip : 0
              Leap : 0
    ScrambleMethod : MatousekAffineOwen
        PointOrder : standard

    q is a qrandstream object that generates points from the point set p.

    References

    [1] Bratley, P., and B. L. Fox. “Algorithm 659 Implementing Sobol's Quasirandom Sequence Generator.” ACM Transactions on Mathematical Software. Vol. 14, No. 1, 1988, pp. 88–100.

    [2] Hong, H. S., and F. J. Hickernell. “Algorithm 823: Implementing Scrambled Digital Sequences.” ACM Transactions on Mathematical Software. Vol. 29, No. 2, 2003, pp. 95–109.

    [3] Joe, S., and F. Y. Kuo. “Remark on Algorithm 659: Implementing Sobol's Quasirandom Sequence Generator.” ACM Transactions on Mathematical Software. Vol. 29, No. 1, 2003, pp. 49–57.

    [4] Kocis, L., and W. J. Whiten. “Computational Investigations of Low-Discrepancy Sequences.” ACM Transactions on Mathematical Software. Vol. 23, No. 2, 1997, pp. 266–294.

    [5] Matousek, J. “On the L2-Discrepancy for Anchored Boxes.” Journal of Complexity. Vol. 14, No. 4, 1998, pp. 527–556.

    Version History

    Introduced in R2008a

    See Also

    | |