`scipy.stats._qmc:QMCEngine`

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

Signature

def QMCEngine(d: int, *, optimization: Literal['random-cd', 'lloyd'] | None = None, rng: SeedType = None, seed = None) → None

Members

Summary

A generic Quasi-Monte Carlo sampler class meant for subclassing.

Extended Summary

QMCEngine is a base class to construct a specific Quasi-Monte Carlo sampler. It cannot be used directly as a sampler.

Parameters

d : int

Dimension of the parameter space.

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

By convention samples are distributed over the half-open interval [0, 1). Instances of the class can access the attributes: d for the dimension; and rng for the random number generator.

Subclassing

When subclassing QMCEngine to create a new sampler, __init__ and random must be redefined.

__init__(d, rng=None): at least fix the dimension. If the sampler does not take advantage of a rng (deterministic methods like Halton), this parameter can be omitted.
_random(n, *, workers=1): draw n from the engine. workers is used for parallelism. See Halton for example.

Optionally, two other methods can be overwritten by subclasses:

reset: Reset the engine to its original state.
fast_forward: If the sequence is deterministic (like Halton sequence), then fast_forward(n) is skipping the n first draw.

Examples

To create a random sampler based on ``np.random.random``, we would do the following:

from scipy.stats import qmc
class RandomEngine(qmc.QMCEngine):
    def __init__(self, d, rng=None):
        super().__init__(d=d, rng=rng)


    def _random(self, n=1, *, workers=1):
        return self.rng.random((n, self.d))


    def reset(self):
        super().__init__(d=self.d, rng=self.rng_seed)
        return self


    def fast_forward(self, n):
        self.random(n)
        return self

✓

After subclassing `QMCEngine` to define the sampling strategy we want to use, we can create an instance to sample from.

engine = RandomEngine(2)

✓

engine.random(5)

✗

array([[0.87395, 0.6948 ],
       [0.45687, 0.34078],
       [0.801  , 0.51961],
       [0.34212, 0.9004 ],
       [0.47201, 0.7109 ]])

We can also reset the state of the generator and resample again.

_ = engine.reset()

✓

engine.random(5)

✗

array([[0.82276, 0.31488],
       [0.19813, 0.97404],
       [0.36767, 0.17388],
       [0.77992, 0.27604],
       [0.09667, 0.68428]])

Aliases

scipy.stats._qmc.QMCEngine