QMCEngine#
- class scipy.stats.qmc.QMCEngine(d, *, optimization=None, rng=None)[source]#
A generic Quasi-Monte Carlo sampler class meant for subclassing.
QMCEngine is a base class to construct a specific Quasi-Monte Carlo sampler. It cannot be used directly as a sampler.
- Parameters:
- dint
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.
Added in version 1.10.0.
- rng
numpy.random.Generator, optional Pseudorandom number generator state. When rng is None, a new
numpy.random.Generatoris created using entropy from the operating system. Types other thannumpy.random.Generatorare passed tonumpy.random.default_rngto instantiate aGenerator.Changed in version 1.15.0: As part of the SPEC-007 transition from use of
numpy.random.RandomStatetonumpy.random.Generator, this keyword was changed from seed to rng. For an interim period, both keywords will continue to work, although only one may be specified at a time. After the interim period, function calls using the seed keyword will emit warnings. Following a deprecation period, the seed keyword will be removed.
Methods
fast_forward(n)Fast-forward the sequence by n positions.
integers(l_bounds, *[, u_bounds, n, ...])Draw n integers from l_bounds (inclusive) to u_bounds (exclusive), or if endpoint=True, l_bounds (inclusive) to u_bounds (inclusive).
random([n, workers])Draw n in the half-open interval
[0, 1).reset()Reset the engine to base state.
Notes
By convention samples are distributed over the half-open interval
[0, 1). Instances of the class can access the attributes:dfor the dimension; andrngfor the random number generator.Subclassing
When subclassing
QMCEngineto create a new sampler,__init__andrandommust be redefined.__init__(d, rng=None): at least fix the dimension. If the sampler does not take advantage of arng(deterministic methods like Halton), this parameter can be omitted._random(n, *, workers=1): drawnfrom the engine.workersis used for parallelism. SeeHaltonfor 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), thenfast_forward(n)is skipping thenfirst 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
QMCEngineto define the sampling strategy we want to use, we can create an instance to sample from.>>> engine = RandomEngine(2) >>> engine.random(5) array([[0.22733602, 0.31675834], # random [0.79736546, 0.67625467], [0.39110955, 0.33281393], [0.59830875, 0.18673419], [0.67275604, 0.94180287]])
We can also reset the state of the generator and resample again.
>>> _ = engine.reset() >>> engine.random(5) array([[0.22733602, 0.31675834], # random [0.79736546, 0.67625467], [0.39110955, 0.33281393], [0.59830875, 0.18673419], [0.67275604, 0.94180287]])