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

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 .

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

## Algorithms

expand all

 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.

 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.

 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.

 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.

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