# 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

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