`scipy.stats._qmc:QMCEngine`

source: /scipy/stats/_qmc.py :802

Signature

   def     QMCEngine (    d  :  int | numpy.integer    ,  * ,     optimization  :  Literal['random-cd', 'lloyd'] | None    =  None   ,    rng  :  int | numpy.integer | numpy.random._generator.Generator | numpy.random.mtrand.RandomState | None    =  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)

✗

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

_ = engine.reset()

✓

engine.random(5)