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.Generator
is created using entropy from the operating system. Types other thannumpy.random.Generator
are passed tonumpy.random.default_rng
to instantiate aGenerator
.Changed in version 1.15.0: As part of the SPEC-007 transition from use of
numpy.random.RandomState
tonumpy.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:d
for the dimension; andrng
for the random number generator.Subclassing
When subclassing
QMCEngine
to create a new sampler,__init__
andrandom
must 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)
: drawn
from the engine.workers
is used for parallelism. SeeHalton
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), thenfast_forward(n)
is skipping then
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.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]])