Classe « Sobol »

Informations générales

Héritage

builtins.object
    ABC
        QMCEngine
            Sobol

Définition

class Sobol(QMCEngine):

help(Sobol)

Engine for generating (scrambled) Sobol' sequences.

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

* `random_base2`: safely draw :math:`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.

    .. versionadded:: 1.9.0
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.

    .. versionadded:: 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 than `numpy.random.Generator` are
    passed to `numpy.random.default_rng` to instantiate a ``Generator``.

    .. versionchanged:: 1.15.0

        As part of the `SPEC-007 <https://scientific-python.org/specs/spec-0007/>`_
        transition from use of `numpy.random.RandomState` to
        `numpy.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.

Notes
-----
Sobol' sequences [1]_ provide :math:`n=2^m` low discrepancy points in
:math:`[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/.

.. warning::

   Sobol' sequences are a quadrature rule and they lose their balance
   properties if one uses a sample size that is not a power of 2, or skips
   the first point, or thins the sequence [5]_.

   If :math:`n=2^m` points are not enough then one should take :math:`2^M`
   points for :math:`M>m`. When scrambling, the number R of independent
   replicates does not have to be a power of 2.

   Sobol' sequences are generated to some number :math:`B` of bits.
   After :math:`2^B` points have been generated, the sequence would
   repeat. Hence, an error is raised.
   The number of bits can be controlled with the parameter `bits`.

References
----------
.. [1] I. M. Sobol', "The distribution of points in a cube and the accurate
   evaluation of integrals." Zh. Vychisl. Mat. i Mat. Phys., 7:784-802,
   1967.
.. [2] J. Matousek, "On the L2-discrepancy for anchored boxes."
   J. of Complexity 14, 527-556, 1998.
.. [3] Art B. Owen, "Scrambling Sobol and Niederreiter-Xing points."
   Journal of Complexity, 14(4):466-489, December 1998.
.. [4] S. Joe and F. Y. Kuo, "Constructing sobol sequences with better
   two-dimensional projections." SIAM Journal on Scientific Computing,
   30(5):2635-2654, 2008.
.. [5] Art B. Owen, "On dropping the first Sobol' point."
   :arxiv:`2008.08051`, 2020.

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]])

Constructeur(s)

Signature du constructeur	Description
__init__(self, d: int \| numpy.integer, *, scramble: bool = True, bits: int \| numpy.integer \| None = None, rng: int \| numpy.integer \| numpy.random._generator.Generator \| numpy.random.mtrand.RandomState \| None = None, optimization: Optional[Literal['random-cd', 'lloyd']] = None) -> None

Liste des attributs statiques

Nom de l'attribut	Valeur
MAXDIM	21201

Liste des opérateurs

Opérateurs hérités de la classe object

__eq__, __ge__, __gt__, __le__, __lt__, __ne__

Liste des méthodes

Toutes les méthodes Méthodes d'instance Méthodes statiques

Signature de la méthode	Description
fast_forward(self, n: int \| numpy.integer) -> 'Sobol'	Fast-forward the sequence by `n` positions. _{[extrait de fast_forward.__doc__]}
random_base2(self, m: int \| numpy.integer) -> numpy.ndarray	Draw point(s) from the Sobol' sequence. _{[extrait de random_base2.__doc__]}
reset(self) -> 'Sobol'	Reset the engine to base state. _{[extrait de reset.__doc__]}