bundles / scipy latest / scipy / stats / _qmc / Sobol

ABCMeta

`scipy.stats._qmc:Sobol`

source: build-install/usr/lib/python3.14/site-packages/scipy/stats/_qmc.py:1605

Signature

def Sobol(d: int, *, scramble: bool = True, bits: IntNumber | None = None, rng: SeedType = None, optimization: Literal['random-cd', 'lloyd'] | None = None, seed = None) → None

Members

Summary

Engine for generating (scrambled) Sobol' sequences.

Extended Summary

Sobol' sequences are low-discrepancy, quasi-random numbers. Points can be drawn using two methods:

random_base2: safely draw $n = 2^{m}$ points. This method guarantees the balance properties of the sequence.
random: draw an arbitrary number of points from the sequence. See warning below.

Parameters

d : int

Dimensionality of the sequence. Max dimensionality is 21201.

scramble : bool, optional

If True, use LMS+shift scrambling. Otherwise, no scrambling is done. Default is True.

bits : int, optional

Number of bits of the generator. Control the maximum number of points that can be generated, which is 2**bits. Maximal value is 64. It does not correspond to the return type, which is always np.float64 to prevent points from repeating themselves. Default is None, which for backward compatibility, corresponds to 30.

optimization : {None, "random-cd", "lloyd"}, optional

Whether to use an optimization scheme to improve the quality after sampling. Note that this is a post-processing step that does not guarantee that all properties of the sample will be conserved. Default is None.

random-cd: random permutations of coordinates to lower the centered discrepancy. The best sample based on the centered discrepancy is constantly updated. Centered discrepancy-based sampling shows better space-filling robustness toward 2D and 3D subprojections compared to using other discrepancy measures.
lloyd: Perturb samples using a modified Lloyd-Max algorithm. The process converges to equally spaced samples.

rng : `numpy.random.Generator`, optional

Pseudorandom number generator state. When rng is None, a new numpy.random.Generator is created using entropy from the operating system. Types other than numpy.random.Generator are passed to numpy.random.default_rng to instantiate a Generator.

Notes

Sobol' sequences ^[1] provide $n = 2^{m}$ low discrepancy points in $[0, 1)^{d}$ . Scrambling them ^[3] makes them suitable for singular integrands, provides a means of error estimation, and can improve their rate of convergence. The scrambling strategy which is implemented is a (left) linear matrix scramble (LMS) followed by a digital random shift (LMS+shift) ^[2].

There are many versions of Sobol' sequences depending on their 'direction numbers'. This code uses direction numbers from ^[4]. Hence, the maximum number of dimension is 21201. The direction numbers have been precomputed with search criterion 6 and can be retrieved at https://web.maths.unsw.edu.au/~fkuo/sobol/.

Examples

Generate samples from a low discrepancy sequence of Sobol'.

from scipy.stats import qmc
sampler = qmc.Sobol(d=2, scramble=False)
sample = sampler.random_base2(m=3)
sample

✓

array([[0.   , 0.   ],
       [0.5  , 0.5  ],
       [0.75 , 0.25 ],
       [0.25 , 0.75 ],
       [0.375, 0.375],
       [0.875, 0.875],
       [0.625, 0.125],
       [0.125, 0.625]])

Compute the quality of the sample using the discrepancy criterion.

qmc.discrepancy(sample)

✓

0.013882107204860938

To continue an existing design, extra points can be obtained by calling again `random_base2`. Alternatively, you can skip some points like:

_ = sampler.reset()
_ = sampler.fast_forward(4)
sample_continued = sampler.random_base2(m=2)
sample_continued

✓

array([[0.375, 0.375],
       [0.875, 0.875],
       [0.625, 0.125],
       [0.125, 0.625]])

Finally, samples can be scaled to bounds.

l_bounds = [0, 2]
u_bounds = [10, 5]
qmc.scale(sample_continued, l_bounds, u_bounds)

✓

array([[3.75 , 3.125],
       [8.75 , 4.625],
       [6.25 , 2.375],
       [1.25 , 3.875]])

Aliases

scipy.stats._qmc.Sobol