# sobolset

Sobol quasirandom point set

## Description

`sobolset` is a quasirandom point set object that produces points from the Sobol sequence. The Sobol sequence is a base-2 digital sequence that fills space in a highly uniform manner.

## Creation

### Syntax

``p = sobolset(d)``
``p = sobolset(d,Name,Value)``

### Description

````p = sobolset(d)` constructs a `d`-dimensional point set `p`, which is a `sobolset` object with default property settings. The input argument `d` corresponds to the `Dimensions` property of `p`.```

example

````p = sobolset(d,Name,Value)` sets properties of `p` using one or more name-value pair arguments. Enclose each property name in quotes. For example, `sobolset(5,'Leap',2)` creates a five-dimensional point set from the first point, fourth point, seventh point, tenth point, and so on.The returned object `p` encapsulates properties of a Sobol quasirandom sequence. The point set is finite, with a length determined by the `Skip` and `Leap` properties and by limits on the size of the point set indices (maximum value of 253). Values of the point set are generated whenever you access `p` using `net` or parenthesis indexing. Values are not stored within `p`.```

## Properties

expand all

Number of dimensions of the points in the point set, specified as a positive integer scalar in the interval [1,1111]. For example, each point in the point set `p` with `p.Dimensions = 5` has five values.

Use the `d` input argument to specify the number of dimensions when you create a point set using the `sobolset` function.

Use the `reduceDimensions` object function to reduce the number of dimensions after you create a point set.

Interval between points in the sequence, specified as a positive integer scalar. In other words, the `Leap` property of a point set 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 from the sequence.

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

Example: `p = sobolset(__,'Leap',50);`

Example: `p.Leap = 100;`

Point generation method, specified as `'standard'` or `'graycode'`. 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: `p = sobolset(__,'PointOrder','graycode');`

Example: `p.PointOrder = 'standard';`

Settings that control the scrambling of the sequence, specified as a structure with these fields:

• `Type` — A character vector containing the name of the scramble

• `Options` — A cell array of parameter values for the scramble

Use the `scramble` object function to set scrambles. For a list of valid scramble types, see the `type` input argument of `scramble`. An error occurs if you set an invalid scramble type for a given point set.

The `ScrambleMethod` property also accepts an empty matrix as a value. The software then clears all scrambling and sets the property to contain a `0x0` structure.

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 undesirable 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. Also, initial points often exhibit correlations among different dimensions, and these correlations disappear later in the sequence.

Example: `p = sobolset(__,'Skip',2e3);`

Example: `p.Skip = 1e3;`

Sequence type on which the quasirandom point set `p` is based, specified as `'Sobol'`.

## Object Functions

 `net` Generate quasirandom point set `reduceDimensions` Reduce dimensions of Sobol point set `scramble` Scramble quasirandom point set

You can also use the following MATLAB® functions with a `sobolset` object. The software treats the point set object like a matrix of multidimensional points.

 `length` Length of largest array dimension `size` Array size

## Examples

collapse all

Generate a three-dimensional Sobol point set, skip the first 1000 values, and then retain every 101st point.

`p = sobolset(3,'Skip',1e3,'Leap',1e2)`
```p = Sobol point set in 3 dimensions (89180190640991 points) Properties: Skip : 1000 Leap : 100 ScrambleMethod : none PointOrder : standard ```

Apply a random linear scramble combined with a random digital shift by using `scramble`.

`p = scramble(p,'MatousekAffineOwen')`
```p = Sobol point set in 3 dimensions (89180190640991 points) Properties: Skip : 1000 Leap : 100 ScrambleMethod : MatousekAffineOwen PointOrder : standard ```

Generate the first four points by using `net`.

`X0 = net(p,4)`
```X0 = 4×3 0.7601 0.5919 0.9529 0.1795 0.0856 0.0491 0.5488 0.0785 0.8483 0.3882 0.8771 0.8755 ```

Generate every third point, up to the eleventh point, by using parenthesis indexing.

`X = p(1:3:11,:)`
```X = 4×3 0.7601 0.5919 0.9529 0.3882 0.8771 0.8755 0.6905 0.4951 0.8464 0.1955 0.5679 0.3192 ```

## Tips

• The `Skip` and `Leap` properties are useful for parallel applications. For example, if you have a Parallel Computing Toolbox™ license, you can partition a sequence of points across N different workers by using the function `labindex` (Parallel Computing Toolbox). On each nth worker, set the `Skip` property of the point set to n – 1 and the `Leap` property to N – 1. The following code shows how to partition a sequence across three workers.

```Nworkers = 3; p = sobolset(10,'Leap',Nworkers-1); spmd(Nworkers) p.Skip = labindex - 1; % Compute something using points 1,4,7... % or points 2,5,8... or points 3,6,9... end```

expand all

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