Main Content

# qrandstream

Quasirandom number stream

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

example

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

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

 `qrand` Generate quasirandom points from stream `rand` Generate quasirandom points from stream `reset` Reset state

## Examples

collapse all

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.

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.

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