| Server IP : 35.80.110.71 / Your IP : 216.73.216.221 Web Server : Apache/2.4.58 (Ubuntu) System : Linux ip-172-31-21-44 6.17.0-1019-aws #19~24.04.1-Ubuntu SMP Tue Jun 23 18:53:06 UTC 2026 x86_64 User : ubuntu ( 1000) PHP Version : 8.3.31 Disable Function : NONE MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : OFF | Sudo : ON | Pkexec : OFF Directory : /lib/python3/dist-packages/scipy/stats/__pycache__/ |
Upload File : |
�
x�f`p � �V � d Z ddlmZ ddlZddlZddlZddlZddlZddlm Z m
Z
ddl m Z ddl
mZmZmZmZmZ ddlZerddlm
Z ddlmZmZmZmZ ddl m Z ddlm Z m Z dd l m!Z!m"Z" dd
l#m$Z$ d d l%m&Z&m'Z'm(Z(m)Z)m*Z*m+Z+m,Z, d d
l-m.Z.m/Z/m0Z0m1Z1m2Z2m3Z3m4Z4 g d�Z5ed8d9d�� Z6ed:d�� Z6d;d�Z6dd� d<d�Z7ddd d� d=d�Z8 d>d�Z9 d?d�Z:d@d�Z;dAd�Z<dd � dBd �Z= dCddddd d � dDd �Z> G d � d!e � Z? G d"� d#e?� Z@ G d$� d%e?� ZA G d&� d'e?� ZB G d(� d)e?� ZC G d*� d+� ZD G d,� d-� ZE dEd.�ZF dFd/�ZGdGd0�ZH dHd1�ZId2d3dd4� dId5�ZJdJdKd6�ZK dLd7�ZLy)Mz&Quasi-Monte Carlo engines and helpers.� )� annotationsN)�ABC�abstractmethod)�partial)�Callable�ClassVar�Literal�overload�
TYPE_CHECKING)�
DecimalNumber�
GeneratorType� IntNumber�SeedType)� rng_integers�
_rng_spawn)�distance�Voronoi)�gammainc� )�
_initialize_v�
_cscramble�_fill_p_cumulative�_draw�
_fast_forward� _categorize�_MAXDIM)� _cy_wrapper_centered_discrepancy�#_cy_wrapper_wrap_around_discrepancy� _cy_wrapper_mixture_discrepancy� _cy_wrapper_l2_star_discrepancy� _cy_wrapper_update_discrepancy� _cy_van_der_corput_scrambled�_cy_van_der_corput)
�scale� discrepancy�update_discrepancy� QMCEngine�Sobol�Halton�LatinHypercube� PoissonDisk�MultinomialQMC�MultivariateNormalQMCc � � y �N� ��seeds �2/usr/lib/python3/dist-packages/scipy/stats/_qmc.py�check_random_stater4 3 � � �� c � � y r/ r0 r1 s r3 r4 r4 8 r5 r6 c �4 � | �*t | t j t j f� r t j
j
| � S t | t j
j t j
j f� r| S t | �d�� �)a) Turn `seed` into a `numpy.random.Generator` instance.
Parameters
----------
seed : {None, int, `numpy.random.Generator`, `numpy.random.RandomState`}, optional # noqa
If `seed` is an int or None, a new `numpy.random.Generator` is
created using ``np.random.default_rng(seed)``.
If `seed` is already a ``Generator`` or ``RandomState`` instance, then
the provided instance is used.
Returns
-------
seed : {`numpy.random.Generator`, `numpy.random.RandomState`}
Random number generator.
z9 cannot be used to seed a numpy.random.Generator instance)
�
isinstance�numbers�Integral�np�integer�random� default_rng� RandomState� Generator�
ValueErrorr1 s r3 r4 r4 > sy � �" �|�z�$��)9�)9�2�:�:�(F�G��y�y�$�$�T�*�*� �D�2�9�9�0�0�"�)�)�2E�2E�F� G�� ��D�8� $<� <� =� =r6 F)�reversec � � t j | � } | j dk( s t d� �t ||| j
d �� \ }}|s<| j
� dkD s| j � dk r t d� �| ||z
z |z S t j | |k\ � rt j | |k � s t d� �| |z
||z
z S ) a� Sample scaling from unit hypercube to different bounds.
To convert a sample from :math:`[0, 1)` to :math:`[a, b), b>a`,
with :math:`a` the lower bounds and :math:`b` the upper bounds.
The following transformation is used:
.. math::
(b - a) \cdot \text{sample} + a
Parameters
----------
sample : array_like (n, d)
Sample to scale.
l_bounds, u_bounds : array_like (d,)
Lower and upper bounds (resp. :math:`a`, :math:`b`) of transformed
data. If `reverse` is True, range of the original data to transform
to the unit hypercube.
reverse : bool, optional
Reverse the transformation from different bounds to the unit hypercube.
Default is False.
Returns
-------
sample : array_like (n, d)
Scaled sample.
Examples
--------
Transform 3 samples in the unit hypercube to bounds:
>>> from scipy.stats import qmc
>>> l_bounds = [-2, 0]
>>> u_bounds = [6, 5]
>>> sample = [[0.5 , 0.75],
... [0.5 , 0.5],
... [0.75, 0.25]]
>>> sample_scaled = qmc.scale(sample, l_bounds, u_bounds)
>>> sample_scaled
array([[2. , 3.75],
[2. , 2.5 ],
[4. , 1.25]])
And convert back to the unit hypercube:
>>> sample_ = qmc.scale(sample_scaled, l_bounds, u_bounds, reverse=True)
>>> sample_
array([[0.5 , 0.75],
[0.5 , 0.5 ],
[0.75, 0.25]])
� �Sample is not a 2D arrayr )�l_bounds�u_bounds�d� �?� � Sample is not in unit hypercubezSample is out of bounds) r< �asarray�ndimrB �_validate_bounds�shape�max�min�all)�samplerG rH rC �lower�uppers r3 r$ r$ X s� � �v �Z�Z��
�F� �;�;�!� ��3�4�4�#��H�� � �Q���L�E�5� � �J�J�L�2� �6�:�:�<�"�#4� � >�?� ?���� �'�%�/�/� ���v���'�B�F�F�6�U�?�,C� � 6�7� 7����5�5�=�1�1r6 �CD)� iterative�method�workersc �~ � t j | t j d�� } | j dk( s t d� �| j � dkD s| j
� dk r t d� �t |� }t t t t d�}||v r || | ||� � S t |�d
t |� ��� �) a� Discrepancy of a given sample.
Parameters
----------
sample : array_like (n, d)
The sample to compute the discrepancy from.
iterative : bool, optional
Must be False if not using it for updating the discrepancy.
Default is False. Refer to the notes for more details.
method : str, optional
Type of discrepancy, can be ``CD``, ``WD``, ``MD`` or ``L2-star``.
Refer to the notes for more details. Default is ``CD``.
workers : int, optional
Number of workers to use for parallel processing. If -1 is given all
CPU threads are used. Default is 1.
Returns
-------
discrepancy : float
Discrepancy.
Notes
-----
The discrepancy is a uniformity criterion used to assess the space filling
of a number of samples in a hypercube. A discrepancy quantifies the
distance between the continuous uniform distribution on a hypercube and the
discrete uniform distribution on :math:`n` distinct sample points.
The lower the value is, the better the coverage of the parameter space is.
For a collection of subsets of the hypercube, the discrepancy is the
difference between the fraction of sample points in one of those
subsets and the volume of that subset. There are different definitions of
discrepancy corresponding to different collections of subsets. Some
versions take a root mean square difference over subsets instead of
a maximum.
A measure of uniformity is reasonable if it satisfies the following
criteria [1]_:
1. It is invariant under permuting factors and/or runs.
2. It is invariant under rotation of the coordinates.
3. It can measure not only uniformity of the sample over the hypercube,
but also the projection uniformity of the sample over non-empty
subset of lower dimension hypercubes.
4. There is some reasonable geometric meaning.
5. It is easy to compute.
6. It satisfies the Koksma-Hlawka-like inequality.
7. It is consistent with other criteria in experimental design.
Four methods are available:
* ``CD``: Centered Discrepancy - subspace involves a corner of the
hypercube
* ``WD``: Wrap-around Discrepancy - subspace can wrap around bounds
* ``MD``: Mixture Discrepancy - mix between CD/WD covering more criteria
* ``L2-star``: L2-star discrepancy - like CD BUT variant to rotation
See [2]_ for precise definitions of each method.
Lastly, using ``iterative=True``, it is possible to compute the
discrepancy as if we had :math:`n+1` samples. This is useful if we want
to add a point to a sampling and check the candidate which would give the
lowest discrepancy. Then you could just update the discrepancy with
each candidate using `update_discrepancy`. This method is faster than
computing the discrepancy for a large number of candidates.
References
----------
.. [1] Fang et al. "Design and modeling for computer experiments".
Computer Science and Data Analysis Series, 2006.
.. [2] Zhou Y.-D. et al. "Mixture discrepancy for quasi-random point sets."
Journal of Complexity, 29 (3-4) , pp. 283-301, 2013.
.. [3] T. T. Warnock. "Computational investigations of low discrepancy
point sets." Applications of Number Theory to Numerical
Analysis, Academic Press, pp. 319-343, 1972.
Examples
--------
Calculate the quality of the sample using the discrepancy:
>>> import numpy as np
>>> from scipy.stats import qmc
>>> space = np.array([[1, 3], [2, 6], [3, 2], [4, 5], [5, 1], [6, 4]])
>>> l_bounds = [0.5, 0.5]
>>> u_bounds = [6.5, 6.5]
>>> space = qmc.scale(space, l_bounds, u_bounds, reverse=True)
>>> space
array([[0.08333333, 0.41666667],
[0.25 , 0.91666667],
[0.41666667, 0.25 ],
[0.58333333, 0.75 ],
[0.75 , 0.08333333],
[0.91666667, 0.58333333]])
>>> qmc.discrepancy(space)
0.008142039609053464
We can also compute iteratively the ``CD`` discrepancy by using
``iterative=True``.
>>> disc_init = qmc.discrepancy(space[:-1], iterative=True)
>>> disc_init
0.04769081147119336
>>> qmc.update_discrepancy(space[-1], space[:-1], disc_init)
0.008142039609053513
�C��dtype�orderrE rF rJ rK rL )rW �WD�MDzL2-star�rZ z* is not a valid method. It must be one of )
r< rM �float64rN rB rQ rR �_validate_workersr r r r �set)rT rX rY rZ �methodss r3 r% r% � s� � �b �Z�Z��b�j�j��
<�F� �;�;�!� ��3�4�4��
�
� �r��v�z�z�|�b� 0��:�;�;� ��(�G� /�1�-�2� �G� ��� �w�v��v�y�'�B�B��F�:� & � ��\� ,�.� /� /r6 c �H � t j |t j d�� }t j | t j d�� } |j dk( s t d� �|j � dkD s|j
� dk r t d� �| j dk( s t d � �t j | d
k\ � rt j | dk � s t d � �| j d
|j d k7 r t d � �t | ||� S )
a� Update the centered discrepancy with a new sample.
Parameters
----------
x_new : array_like (1, d)
The new sample to add in `sample`.
sample : array_like (n, d)
The initial sample.
initial_disc : float
Centered discrepancy of the `sample`.
Returns
-------
discrepancy : float
Centered discrepancy of the sample composed of `x_new` and `sample`.
Examples
--------
We can also compute iteratively the discrepancy by using
``iterative=True``.
>>> import numpy as np
>>> from scipy.stats import qmc
>>> space = np.array([[1, 3], [2, 6], [3, 2], [4, 5], [5, 1], [6, 4]])
>>> l_bounds = [0.5, 0.5]
>>> u_bounds = [6.5, 6.5]
>>> space = qmc.scale(space, l_bounds, u_bounds, reverse=True)
>>> disc_init = qmc.discrepancy(space[:-1], iterative=True)
>>> disc_init
0.04769081147119336
>>> qmc.update_discrepancy(space[-1], space[:-1], disc_init)
0.008142039609053513
r\ r] rE rF rJ rK rL r zx_new is not a 1D arrayr z x_new is not in unit hypercubez&x_new and sample must be broadcastable)
r< rM rc rN rB rQ rR rS rP r! )�x_newrT � initial_discs r3 r& r& 5 s� � �L �Z�Z��b�j�j��
<�F� �J�J�u�B�J�J�c� :�E� �;�;�!� ��3�4�4��
�
� �r��v�z�z�|�b� 0��:�;�;� �:�:��?��2�3�3� �F�F�5�A�:� �2�6�6�%�1�*�#5��9�:�:� �{�{�1�~�� � �a� �(��A�B�B� )�%�� � F�Fr6 c � � | j d }| dz
}d|dz z t j ddt ||dd�f � z t |� z t ||dd�f |z
� z
z d�� z }d|dz z t j ddt ||dd�f � z t |� z t ||dd�f |z
� z
z d�� z }d|dz z t j dt ||dd�f � z � z d|z t j ddt ||dd�f � z z d||dd�f dz z z
� z z
} d|dz z t j dt ||dd�f � z � z d|z t j ddt ||dd�f � z z d||dd�f dz z z
� z z
}
dt |||f � z t |dd�|f � z t |||f |dd�|f z
� z
} dt |||f � z t |dd�|f � z t |||f |dd�|f z
� z
} | | z }
|
|z }||
z }dt |||f � z dt |||f � z z }dt |||f � z
dt |||f � z
z }t j dt ||dd�f � z � }t j dt ||dd�f � z � }t j ddt ||dd�f � z z d||dd�f dz z z
� }t j ddt ||dd�f � z z d||dd�f dz z z
� }||z |dz z d|z |z |z |z z
}||dz |z z d|z ||z |z z z
}||z
|z |z
}t j |t
� � }d
|||g< t
|| � }||z | z
|z |
z
d|z z }|S ) a� Centered discrepancy after an elementary perturbation of a LHS.
An elementary perturbation consists of an exchange of coordinates between
two points: ``sample[i1, k] <-> sample[i2, k]``. By construction,
this operation conserves the LHS properties.
Parameters
----------
sample : array_like (n, d)
The sample (before permutation) to compute the discrepancy from.
i1 : int
The first line of the elementary permutation.
i2 : int
The second line of the elementary permutation.
k : int
The column of the elementary permutation.
disc : float
Centered discrepancy of the design before permutation.
Returns
-------
discrepancy : float
Centered discrepancy of the design after permutation.
References
----------
.. [1] Jin et al. "An efficient algorithm for constructing optimal design
of computer experiments", Journal of Statistical Planning and
Inference, 2005.
r � �?rJ g @Nr ��axisrE �r^ F)rP r< �prod�abs�ones�bool�sum)rT �i1�i2�k�disc�n�z_ij�c_i1j�c_i2j�c_i1i1�c_i2i2�num�denum�gamma�c_p_i1j�c_p_i2j�alpha�beta�g_i1�g_i2�h_i1�h_i2�c_p_i1i1�c_p_i2i2�sum_�mask�disc_eps r3 �_perturb_discrepancyr� r si � �B � � �Q��A� �C�<�D� �!�r�'�\��w�w�s�b�3�t�B��E�{�#3� 3� #�D� � *�,/��R��U� �d�0B�,C� D� E�KL�N�N�E� �!�r�'�\��w�w�s�b�3�t�B��E�{�#3� 3� #�D� � *�,/��R��U� �d�0B�,C� D� E�KL�N�N�E�
�1��6�k�B�G�G�A��D��Q��K�(8�$8� 9�9��Q������c�C��R��U� �,<�&<�!<�#&��b�!�e���)9�#9�":� ;� ;�;�F� �1��6�k�B�G�G�A��D��Q��K�(8�$8� 9�9��Q������c�C��R��U� �,<�&<�!<�#&��b�!�e���)9�#9�":� ;� ;�;�F�
�s�4��A��;� � �#�d�1�a�4�j�/� 1�
��b�!�e��t�A�q�D�z�)�
*� +�C�
��T�"�a�%�[�!�
!�C��Q��T�
�O�
3��4��A��;��a��d��+�,�-�E� �%�K�E� �e�m�G��e�m�G�
��T�"�a�%�[�!�
!�a�#�d�2�q�5�k�*:�&:� ;�E�
��D��Q��K� � �Q��T�"�a�%�[�)9�%9� :�D�
�7�7�2��D��Q��K�(�(� )�D�
�7�7�2��D��Q��K�(�(� )�D�
�7�7�2��c�$�r�1�u�+� .�.�.���R��U� �q�8H�1I�I� J�D�
�7�7�2��c�$�r�1�u�+� .�.�.���R��U� �q�8H�1I�I� J�D� �� �!�q�&�)�B��J��,=��,D�q�,H�H�H��!�q�&�E�)�*�r�D�y�A��I��<L�/M�N�H� �U�?�W� $�u� ,�D�
�7�7�1�D� !�D��D�"�b��N� �t�D�z�?�D��h���'�(�2�V�;�a�$�h�F�G� �Nr6 c �x � t j | dz | dz dk( z t �� }t dt | dz � dz dz � D ]; }d|z dz dz }d|||z dz dd|z �< d|||d|dz z z
d z z dz dd|z �< �= t j
dddt j |� d
dd z dz dz f S ) a� Prime numbers from 2 to *n*.
Parameters
----------
n : int
Sup bound with ``n >= 6``.
Returns
-------
primes : list(int)
Primes in ``2 <= p < n``.
Notes
-----
Taken from [1]_ by P.T. Roy, written consent given on 23.04.2021
by the original author, Bruno Astrolino, for free use in SciPy under
the 3-clause BSD.
References
----------
.. [1] `StackOverflow <https://stackoverflow.com/questions/2068372>`_.
� � rE rn r rk FN� r )r< rq rr �range�int�r_�nonzero)rx �sieve�irv s r3 �primes_from_2_tor� � s� � �0
�G�G�A��F�a�!�e�q�j�)�� 6�E�
�1�c�!�s�(�m�q�(�1�,�
-� =��
��E�A�I��M��#(��a�!�e�q�j� �!�a�%� � �7<��a�1�q�A��E�{�?�Q�&�'�1�,�3�a�!�e�3�4�=� �5�5��A��R�Z�Z�� .�q� 1�!�"� 5�5��9�Q�>�?� @�@r6 c � � g d�d| }t |� | k r(d} t |� d| }t |� | k( r |S |dz
}�%|S )z�List of the n-first prime numbers.
Parameters
----------
n : int
Number of prime numbers wanted.
Returns
-------
primes : list(int)
List of primes.
)�rE r� � � � �
� � � � � �% �) �+ �/ �5 �; �= �C �G �I �O �S �Y �a �e �g �k �m �q � � � � � � � � � � � � � � �� �� �� �� �� �� �� �� �� � i i i
i i i i i% i3 i7 i9 i= iK iQ i[ i] ia ig io iu i{ i i� i� i� i� i� i� i� i� i� i� i� i� i� i� i� i� i� i� i� i� i� i i i i# i- i3 i9 i; iA iK iQ iW iY i_ ie ii ik iw i� i� i� i� i� i� i� i� i� i� i� i� i� i� i� i� i� i� i� i� i i i i i) i+ i5 i7 i; i= iG iU iY i[ i_ im iq is iw i� i� i� i� i� i� i� i� i� i� i� i� i� i� Ni� i� )�lenr� )rx �primes�
big_numbers r3 �n_primesr� � si � � 1� 24�!� 5�F� �6�{�Q���
�!�%�j�1�"�1�5�F��6�{�a� �� �M�
�$� �J� "� �Mr6 )� random_statec � � t |� }t j dt j | � z � dz
}t j
t j | � d |d�� }|D ] }|j |� � |S )a� Permutations for scrambling a Van der Corput sequence.
Parameters
----------
base : int
Base of the sequence.
random_state : {None, int, `numpy.random.Generator`}, optional
If `seed` is an int or None, a new `numpy.random.Generator` is
created using ``np.random.default_rng(seed)``.
If `seed` is already a ``Generator`` instance, then the provided
instance is used.
Returns
-------
permutations : array_like
Permutation indices.
Notes
-----
In Algorithm 1 of Owen 2017, a permutation of `np.arange(base)` is
created for each positive integer `k` such that `1 - base**-k < 1`
using floating-point arithmetic. For double precision floats, the
condition `1 - base**-k < 1` can also be written as `base**-k >
2**-54`, which makes it more apparent how many permutations we need
to create.
�6 r Nr rl )r4 �math�ceil�log2r< �repeat�arange�shuffle)�baser� �rng�count� permutations�perms r3 � _van_der_corput_permutationsr� sp � �: �\�
*�C� �I�I�b�4�9�9�T�?�*� +�a� /�E��9�9�R�Y�Y�t�_�T� 2�E��B�L� � �� � � �D��� �r6 )� start_index�scrambler� r2 rZ c � � |dk r t d� �|r4|�t ||�� }nt j |� }t | ||||� S t | |||� S )aw Van der Corput sequence.
Pseudo-random number generator based on a b-adic expansion.
Scrambling uses permutations of the remainders (see [1]_). Multiple
permutations are applied to construct a point. The sequence of
permutations has to be the same for all points of the sequence.
Parameters
----------
n : int
Number of element of the sequence.
base : int, optional
Base of the sequence. Default is 2.
start_index : int, optional
Index to start the sequence from. Default is 0.
scramble : bool, optional
If True, use Owen scrambling. Otherwise no scrambling is done.
Default is True.
permutations : array_like, optional
Permutations used for scrambling.
seed : {None, int, `numpy.random.Generator`}, optional
If `seed` is an int or None, a new `numpy.random.Generator` is
created using ``np.random.default_rng(seed)``.
If `seed` is already a ``Generator`` instance, then the provided
instance is used.
workers : int, optional
Number of workers to use for parallel processing. If -1 is
given all CPU threads are used. Default is 1.
Returns
-------
sequence : list (n,)
Sequence of Van der Corput.
References
----------
.. [1] A. B. Owen. "A randomized Halton algorithm in R",
:arxiv:`1706.02808`, 2017.
rE z'base' must be at least 2�r� r� )rB r� r< rM r" r# )rx r� r� r� r� r2 rZ s r3 �van_der_corputr� 9 sm � �d �a�x��4�5�5�� � �7��� �L� �:�:�l�3�L�+�A�t�[�,8�'�C� C� "�!�T�;��@�@r6 c � � e Zd ZdZeddd� dd�� Ze ddd� dd�� Z ddd� dd�Zddd dd
� dd �Zdd �Z dd
�Z
y)r' a� 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
----------
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.
.. versionadded:: 1.10.0
seed : {None, int, `numpy.random.Generator`}, optional
If `seed` is an int or None, a new `numpy.random.Generator` is
created using ``np.random.default_rng(seed)``.
If `seed` is already a ``Generator`` instance, then the provided
instance is used.
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 (used for the
``seed``).
**Subclassing**
When subclassing `QMCEngine` to create a new sampler, ``__init__`` and
``random`` must be redefined.
* ``__init__(d, seed=None)``: at least fix the dimension. If the sampler
does not take advantage of a ``seed`` (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, seed=None):
... super().__init__(d=d, seed=seed)
...
...
... def _random(self, n=1, *, workers=1):
... return self.rng.random((n, self.d))
...
...
... def reset(self):
... super().__init__(d=self.d, seed=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]])
N)� optimizationr2 c � � t j t |� t j � r|dk r t d� �|| _ t
|t j j � rt |d� d | _
nt |� | _
t j | j � | _ d| _ dd| j ddd d�}t! ||� | _ y ) Nr z&d must be a non-negative integer valuer �d i' ��h㈵��>�
)�
n_nochange�n_itersr� �tol�maxiter�
qhull_options)r< �
issubdtype�typer= rB rI r9 r> rA r r� r4 �copy�deepcopy�rng_seed�
num_generated�_select_optimizer�optimization_method)�selfrI r� r2 �configs r3 �__init__zQMCEngine.__init__� s� � � �}�}�T�!�W�b�j�j�1�Q��U� � E�F� F���� �d�B�I�I� /� /� 0�!�$��*�1�-�D�H� *�$�/�D�H� �
�
�d�h�h�/��
� ��� � ��8�8� �� !�
�� $5�\�6�#J�� r6 r rb c � � y r/ r0 )r� rx rZ s r3 �_randomzQMCEngine._random s � � r6 c � � | j ||�� }| j �| j |� }| xj |z
c_ |S )aM Draw `n` in the half-open interval ``[0, 1)``.
Parameters
----------
n : int, optional
Number of samples to generate in the parameter space.
Default is 1.
workers : int, optional
Only supported with `Halton`.
Number of workers to use for parallel processing. If -1 is
given all CPU threads are used. Default is 1. It becomes faster
than one worker for `n` greater than :math:`10^3`.
Returns
-------
sample : array_like (n, d)
QMC sample.
rb )r� r� r� )r� rx rZ rT s r3 r> zQMCEngine.random sH � �, � � �a�� �1�� � #� #� /��-�-�f�5�F� ���a� ���
r6 F)rH rx �endpointrZ c �2 � |�|}d}t j |� }t j |� }|r|dz }t j |j t j � r.t j |j t j � s
d}t |� �t
| t � r| j ||�� }n| j |�� }t |||�� }t j |� j t j � }|S )a?
Draw `n` integers from `l_bounds` (inclusive) to `u_bounds`
(exclusive), or if endpoint=True, `l_bounds` (inclusive) to
`u_bounds` (inclusive).
Parameters
----------
l_bounds : int or array-like of ints
Lowest (signed) integers to be drawn (unless ``u_bounds=None``,
in which case this parameter is 0 and this value is used for
`u_bounds`).
u_bounds : int or array-like of ints, optional
If provided, one above the largest (signed) integer to be drawn
(see above for behavior if ``u_bounds=None``).
If array-like, must contain integer values.
n : int, optional
Number of samples to generate in the parameter space.
Default is 1.
endpoint : bool, optional
If true, sample from the interval ``[l_bounds, u_bounds]`` instead
of the default ``[l_bounds, u_bounds)``. Defaults is False.
workers : int, optional
Number of workers to use for parallel processing. If -1 is
given all CPU threads are used. Only supported when using `Halton`
Default is 1.
Returns
-------
sample : array_like (n, d)
QMC sample.
Notes
-----
It is safe to just use the same ``[0, 1)`` to integer mapping
with QMC that you would use with MC. You still get unbiasedness,
a strong law of large numbers, an asymptotically infinite variance
reduction and a finite sample variance bound.
To convert a sample from :math:`[0, 1)` to :math:`[a, b), b>a`,
with :math:`a` the lower bounds and :math:`b` the upper bounds,
the following transformation is used:
.. math::
\text{floor}((b - a) \cdot \text{sample} + a)
r r zD'u_bounds' and 'l_bounds' must be integers or array-like of integers)rx rZ �rx )rG rH )
r< �
atleast_1dr� r^ r= rB r9 r) r> r$ �floor�astype�int64)r� rG rH rx r rZ �messagerT s r3 �integerszQMCEngine.integers+ s� � �p � � �H��H��=�=��*���=�=��*�� � �!�|�H��
�
�h�n�n�b�j�j�9��M�M�(�.�.�"�*�*�=�1�G� �W�%� %� �d�F� #��[�[�1�g�[�6�F��[�[�1�[�%�F��v��8�D�����&�!�(�(����2���
r6 c �r � t j | j � }t |� | _ d| _ | S )z�Reset the engine to base state.
Returns
-------
engine : QMCEngine
Engine reset to its base state.
r )r� r� r� r4 r� r� )r� r2 s r3 �resetzQMCEngine.reset} s/ � � �}�}�T�]�]�+��%�d�+��� ���� r6 c �* � | j |�� | S )a
Fast-forward the sequence by `n` positions.
Parameters
----------
n : int
Number of points to skip in the sequence.
Returns
-------
engine : QMCEngine
Engine reset to its base state.
r )r> �r� rx s r3 � fast_forwardzQMCEngine.fast_forward� s � �
� � �a� ��� r6 )rI r r� �$Literal['random-cd', 'lloyd'] | Noner2 r �return�None�r �rx r rZ r r �
np.ndarray) rG �
npt.ArrayLikerH �npt.ArrayLike | Nonerx r r rr rZ r r r )r r' )rx r r r' ) �__name__�
__module__� __qualname__�__doc__r r� r� r> r r
r
r0 r6 r3 r' r' } s � �c�J �
>B� � "K� �"K� ;� "K�
� "K�
�
"K� �"K�H � � �89� �� �,5� � � � � � ��89����,5�� ��B *.�� � �P� �P� '� P�
� P� �
P� �P�
�P�d � r6 r' c �d � � e Zd ZdZdddd� d
� fd�Zd d�Z d dd� d
d �Z� xZS )r) a�
Halton sequence.
Pseudo-random number generator that generalize the Van der Corput sequence
for multiple dimensions. The Halton sequence uses the base-two Van der
Corput sequence for the first dimension, base-three for its second and
base-:math:`n` for its n-dimension.
Parameters
----------
d : int
Dimension of the parameter space.
scramble : bool, optional
If True, use Owen scrambling. Otherwise no scrambling is done.
Default is True.
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
seed : {None, int, `numpy.random.Generator`}, optional
If `seed` is an int or None, a new `numpy.random.Generator` is
created using ``np.random.default_rng(seed)``.
If `seed` is already a ``Generator`` instance, then the provided
instance is used.
Notes
-----
The Halton sequence has severe striping artifacts for even modestly
large dimensions. These can be ameliorated by scrambling. Scrambling
also supports replication-based error estimates and extends
applicabiltiy to unbounded integrands.
References
----------
.. [1] Halton, "On the efficiency of certain quasi-random sequences of
points in evaluating multi-dimensional integrals", Numerische
Mathematik, 1960.
.. [2] A. B. Owen. "A randomized Halton algorithm in R",
:arxiv:`1706.02808`, 2017.
Examples
--------
Generate samples from a low discrepancy sequence of Halton.
>>> from scipy.stats import qmc
>>> sampler = qmc.Halton(d=2, scramble=False)
>>> sample = sampler.random(n=5)
>>> sample
array([[0. , 0. ],
[0.5 , 0.33333333],
[0.25 , 0.66666667],
[0.75 , 0.11111111],
[0.125 , 0.44444444]])
Compute the quality of the sample using the discrepancy criterion.
>>> qmc.discrepancy(sample)
0.088893711419753
If some wants to continue an existing design, extra points can be obtained
by calling again `random`. Alternatively, you can skip some points like:
>>> _ = sampler.fast_forward(5)
>>> sample_continued = sampler.random(n=5)
>>> sample_continued
array([[0.3125 , 0.37037037],
[0.8125 , 0.7037037 ],
[0.1875 , 0.14814815],
[0.6875 , 0.48148148],
[0.4375 , 0.81481481]])
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.125 , 3.11111111],
[8.125 , 4.11111111],
[1.875 , 2.44444444],
[6.875 , 3.44444444],
[4.375 , 4.44444444]])
TN)r� r� r2 c �� �� |d|d�| _ t �| � |||�� || _ t |� D �cg c]
}t |� �� c}| _ || _ | j � y c c}w )NT)rI r� r� �rI r� r2 ) �
_init_quad�superr� r2 r� r� r� r� �_initialize_permutations)r� rI r� r� r2 �bdim� __class__s �r3 r� zHalton.__init__� se �� � !"�t�+7�9���
���1�<�d��C��� � ,4�A�;�7�4�S��Y�7�� � ��
� �%�%�'�� 8s �A%c �� � dgt | j � z | _ | j rDt | j � D ]+ \ }}t || j �� }|| j |< �- yy)zxInitialize permutations for all Van der Corput sequences.
Permutations are only needed for scrambling.
Nr� )r� r� �
_permutationsr� � enumerater� r� )r� r� r r� s r3 r z Halton._initialize_permutations
sh � �
%)�6�C�� � �N�#:��� �=�=�$�T�Y�Y�/�
5���4� ;� �D�H�H� � � )5��"�"�1�%�
5� r6 r rb c �D � t |� }t | j � D ��cg c]7 \ }}t ||| j | j
| j | |�� ��9 }}}t j |� j j || j � S c c}}w )a Draw `n` in the half-open interval ``[0, 1)``.
Parameters
----------
n : int, optional
Number of samples to generate in the parameter space. Default is 1.
workers : int, optional
Number of workers to use for parallel processing. If -1 is
given all CPU threads are used. Default is 1. It becomes faster
than one worker for `n` greater than :math:`10^3`.
Returns
-------
sample : array_like (n, d)
QMC sample.
)r� r� r� rZ ) rd r$ r� r� r� r� r# r< �array�T�reshaperI )r� rx rZ r� r rT s r3 r� zHalton._random s� � �( $�G�,�� "+�4�9�9�!5� 7� �a�� !��D�d�6H�6H�*.�-�-�.2�.@�.@��.C�)0�2� 7�� 7� �x�x�� �!�!�)�)�!�T�V�V�4�4��
7s �<B )
rI r r� rr r� r r2 r r r �r r r r )r r r r r� r r� �
__classcell__�r! s @r3 r) r) � su �� �\�~ 15�=A� �(��(�)-�(�:�(� �(�
� (�" 5� � 5�89� 5�� 5�,5� 5� � 5r6 r) c �| � � e Zd ZdZdddddd� d � fd�Z d
dd� dd �Zd
dd
�Zddd �Z� xZS )r* a�! Latin hypercube sampling (LHS).
A Latin hypercube sample [1]_ generates :math:`n` points in
:math:`[0,1)^{d}`. Each univariate marginal distribution is stratified,
placing exactly one point in :math:`[j/n, (j+1)/n)` for
:math:`j=0,1,...,n-1`. They are still applicable when :math:`n << d`.
Parameters
----------
d : int
Dimension of the parameter space.
centered : bool, optional
Center samples within cells of a multi-dimensional grid.
Default is False.
.. deprecated:: 1.10.0
`centered` is deprecated as of SciPy 1.10.0 and will be removed in
1.12.0. Use `scramble` instead. ``centered=True`` corresponds to
``scramble=False``.
scramble : bool, optional
When False, center samples within cells of a multi-dimensional grid.
Otherwise, samples are randomly placed within cells of the grid.
.. note::
Setting ``scramble=False`` does not ensure deterministic output.
For that, use the `seed` parameter.
Default is True.
.. versionadded:: 1.10.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.8.0
.. versionchanged:: 1.10.0
Add ``lloyd``.
strength : {1, 2}, optional
Strength of the LHS. ``strength=1`` produces a plain LHS while
``strength=2`` produces an orthogonal array based LHS of strength 2
[7]_, [8]_. In that case, only ``n=p**2`` points can be sampled,
with ``p`` a prime number. It also constrains ``d <= p + 1``.
Default is 1.
.. versionadded:: 1.8.0
seed : {None, int, `numpy.random.Generator`}, optional
If `seed` is an int or None, a new `numpy.random.Generator` is
created using ``np.random.default_rng(seed)``.
If `seed` is already a ``Generator`` instance, then the provided
instance is used.
Notes
-----
When LHS is used for integrating a function :math:`f` over :math:`n`,
LHS is extremely effective on integrands that are nearly additive [2]_.
With a LHS of :math:`n` points, the variance of the integral is always
lower than plain MC on :math:`n-1` points [3]_. There is a central limit
theorem for LHS on the mean and variance of the integral [4]_, but not
necessarily for optimized LHS due to the randomization.
:math:`A` is called an orthogonal array of strength :math:`t` if in each
n-row-by-t-column submatrix of :math:`A`: all :math:`p^t` possible
distinct rows occur the same number of times. The elements of :math:`A`
are in the set :math:`\{0, 1, ..., p-1\}`, also called symbols.
The constraint that :math:`p` must be a prime number is to allow modular
arithmetic. Increasing strength adds some symmetry to the sub-projections
of a sample. With strength 2, samples are symmetric along the diagonals of
2D sub-projections. This may be undesirable, but on the other hand, the
sample dispersion is improved.
Strength 1 (plain LHS) brings an advantage over strength 0 (MC) and
strength 2 is a useful increment over strength 1. Going to strength 3 is
a smaller increment and scrambled QMC like Sobol', Halton are more
performant [7]_.
To create a LHS of strength 2, the orthogonal array :math:`A` is
randomized by applying a random, bijective map of the set of symbols onto
itself. For example, in column 0, all 0s might become 2; in column 1,
all 0s might become 1, etc.
Then, for each column :math:`i` and symbol :math:`j`, we add a plain,
one-dimensional LHS of size :math:`p` to the subarray where
:math:`A^i = j`. The resulting matrix is finally divided by :math:`p`.
References
----------
.. [1] Mckay et al., "A Comparison of Three Methods for Selecting Values
of Input Variables in the Analysis of Output from a Computer Code."
Technometrics, 1979.
.. [2] M. Stein, "Large sample properties of simulations using Latin
hypercube sampling." Technometrics 29, no. 2: 143-151, 1987.
.. [3] A. B. Owen, "Monte Carlo variance of scrambled net quadrature."
SIAM Journal on Numerical Analysis 34, no. 5: 1884-1910, 1997
.. [4] Loh, W.-L. "On Latin hypercube sampling." The annals of statistics
24, no. 5: 2058-2080, 1996.
.. [5] Fang et al. "Design and modeling for computer experiments".
Computer Science and Data Analysis Series, 2006.
.. [6] Damblin et al., "Numerical studies of space filling designs:
optimization of Latin Hypercube Samples and subprojection properties."
Journal of Simulation, 2013.
.. [7] A. B. Owen , "Orthogonal arrays for computer experiments,
integration and visualization." Statistica Sinica, 1992.
.. [8] B. Tang, "Orthogonal Array-Based Latin Hypercubes."
Journal of the American Statistical Association, 1993.
.. [9] Susan K. Seaholm et al. "Latin hypercube sampling and the
sensitivity analysis of a Monte Carlo epidemic model".
Int J Biomed Comput, 23(1-2), 97-112,
:doi:`10.1016/0020-7101(88)90067-0`, 1988.
Examples
--------
In [9]_, a Latin Hypercube sampling strategy was used to sample a
parameter space to study the importance of each parameter of an epidemic
model. Such analysis is also called a sensitivity analysis.
Since the dimensionality of the problem is high (6), it is computationally
expensive to cover the space. When numerical experiments are costly,
QMC enables analysis that may not be possible if using a grid.
The six parameters of the model represented the probability of illness,
the probability of withdrawal, and four contact probabilities,
The authors assumed uniform distributions for all parameters and generated
50 samples.
Using `scipy.stats.qmc.LatinHypercube` to replicate the protocol, the
first step is to create a sample in the unit hypercube:
>>> from scipy.stats import qmc
>>> sampler = qmc.LatinHypercube(d=6)
>>> sample = sampler.random(n=50)
Then the sample can be scaled to the appropriate bounds:
>>> l_bounds = [0.000125, 0.01, 0.0025, 0.05, 0.47, 0.7]
>>> u_bounds = [0.000375, 0.03, 0.0075, 0.15, 0.87, 0.9]
>>> sample_scaled = qmc.scale(sample, l_bounds, u_bounds)
Such a sample was used to run the model 50 times, and a polynomial
response surface was constructed. This allowed the authors to study the
relative importance of each parameter across the range of
possibilities of every other parameter.
In this computer experiment, they showed a 14-fold reduction in the number
of samples required to maintain an error below 2% on their response surface
when compared to a grid sampling.
Below are other examples showing alternative ways to construct LHS
with even better coverage of the space.
Using a base LHS as a baseline.
>>> sampler = qmc.LatinHypercube(d=2)
>>> sample = sampler.random(n=5)
>>> qmc.discrepancy(sample)
0.0196... # random
Use the `optimization` keyword argument to produce a LHS with
lower discrepancy at higher computational cost.
>>> sampler = qmc.LatinHypercube(d=2, optimization="random-cd")
>>> sample = sampler.random(n=5)
>>> qmc.discrepancy(sample)
0.0176... # random
Use the `strength` keyword argument to produce an orthogonal array based
LHS of strength 2. In this case, the number of sample points must be the
square of a prime number.
>>> sampler = qmc.LatinHypercube(d=2, strength=2)
>>> sample = sampler.random(n=9)
>>> qmc.discrepancy(sample)
0.00526... # random
Options could be combined to produce an optimized centered
orthogonal array based LHS. After optimization, the result would not
be guaranteed to be of strength 2.
FTr N)�centeredr� �strengthr� r2 c �( �� |rd}t j dd�� |d||d�| _ t �
| � |||�� || _ | j | j d�} || | _ y # t $ r!}|�d t |� ��} t | � |�d }~ww xY w)
NFz�'centered' is deprecated and will be removed in SciPy 1.12. Please use 'scramble' instead. 'centered=True' corresponds to 'scramble=False'.rE ��
stacklevelT)rI r� r. r� )rI r2 r� )r rE z, is not a valid strength. It must be one of ) �warnings�warnr r r� r� � _random_lhs�_random_oa_lhs�
lhs_method�KeyErrorre rB ) r� rI r- r� r. r� r2 �lhs_method_strength�excr r! s �r3 r� zLatinHypercube.__init__� s� �� � � �H� �M�M�(� �
� !"�t��+7�9���
���1�4�l��C� ��
� � � ��"�"�
��
/�(;�H�(E�D�O��� /�"� � & � !�"5� 6� 9�;�G� �W�%�3� .�� /�s �
A' �' B�0 B � Brb c �( � | j |� }|S r/ )r6 )r� rx rZ �lhss r3 r� zLatinHypercube._random s � � �o�o�a� ���
r6 c � � | j sd}n(| j j || j f�� }t j
t j d|dz � | j df� }t | j � D ]$ }| j j ||dd�f � �& |j }||z
|z }|S )zBase LHS algorithm.rk ��sizer N)
r� r� �uniformrI r< �tiler� r� r� r' )r� rx �samples�permsr� s r3 r4 zLatinHypercube._random_lhs# s� � ��}�}�*-�G��h�h�&�&�Q����K�&�8�G����� � �!�Q��U�+� ���� �%���t�v�v� � *�A� �H�H� � �U�1�a�4�[� )� *������7�?�a�'���r6 c �� � t j |� j t � }|dz }|dz }t |dz � }||vs||k7 rt d|dd dz � �� �| j |dz kD r t d� �t j ||ft �� }t j t j |� d� }t j t j |� d �
� j d d� |dd�dd�f< t d|� D ]9 }t j |dd�d f ||dd�df z z |� |dd�d|z dz
f< �; t j ||ft �� } t |� D ]0 }
| j j# |� } | |dd�|
f | dd�|
f< �2 t j ||f� � } t% d| j& d| j �
� }
t |� D ]f }
t |� D ]V }|dd�|
f |k( }|
j) |� j+ � }||dd�|
f | z | dd�|
f |< |
j- � }
�X �h | |z } | dd�d| j �f S )z)Orthogonal array based LHS of strength 2.rE r z8n is not the square of a prime number. Close values are ���Nz*n is too small for d. Must be n > (d-1)**2)rP r^ )rE r ���rl r )rP )rI r� r. r2 )r< �sqrtr r� r� rB rI �zerosr@ r� �stack�meshgridr( r� �mod�emptyr� � permutationr* r� r> �flattenr
)r� rx �p�n_row�n_colr� � oa_sample�arrays�p_�
oa_sample_�jrB �
oa_lhs_sample�
lhs_enginerv �idxr; s r3 r5 z LatinHypercube._random_oa_lhs3 sw � � �G�G�A�J� � �c� "���1����A���!�!�a�%�(�� �F�?�a�5�j� � � %�b�c�{�A�~� .�0��
� �6�6�A��E�>� � I�J� J��H�H�E�5�>��=� � ������1� �v�.�� �8�8�B�K�K��$8�)+� -�-4�W�R��^� �!�R�a�R�%����1�+� C�B�#%�6�6�)�A�q�D�/�,.�y��A���,>�+?�@A�$C�I�a��2��a��i� � C�
�X�X�U�E�N�#�>�
��u� � 6�A��H�H�(�(��+�E� $�Y�q�!�t�_� 5�J�q�!�t� � 6�
����u�~�6�
�#�a�$�-�-�!�)-���3�
��u� � 0�A��1�X�
0�� ��1��o��*�� �'�'��*�2�2�4��+.��1�a�4� ��1E�+E�
�a��d�#�C�(� '� -� -� /�
�
0� 0� ���
� �Q������Z�(�(r6 )rI r r- rr r� rr r. r� r� r r2 r r r r r �rx r r r )r� ) r r r r r� r� r4 r5 r* r+ s @r3 r* r* : s� �� �~�B 16� ��=A� � /�� /�)-� /�� /� � /� ;� /�
� /�
�
/�F ��89����,5�� �� � -)� -)r6 r* c � � � e Zd ZU dZeZded< ddddd� d� fd�Zdd�Z dd d
� dd �Z dd �Z
d� fd
� Z dd�Z � xZ
S )r( a� 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
seed : {None, int, `numpy.random.Generator`}, optional
If `seed` is an int or None, a new `numpy.random.Generator` is
created using ``np.random.default_rng(seed)``.
If `seed` is already a ``Generator`` instance, then the provided
instance is used.
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]])
z
ClassVar[int]�MAXDIMTN)r� �bitsr2 r� c � �� |d||d�| _ t �| � |||�� || j kD rt d| j � d�� �|| _ | | j
�d| _ | j
dk rt j | _ nCd| j
cxk rdk r#n t d � �t j | _ n t d � �d
| j
z | _
t
j || j
f| j � � | _ t | j || j
� � |s't
j || j � � | _ n| j � | j j! � | _ d
d
| j
z z | _ | j" | j$ z j' dd� | _ | j( j+ t j, � | _ y )NT)rI r� r\ r� r z$Maximum supported dimensionality is �.� � �@ z Maximum supported 'bits' is 64rE rn )�dimr\ rJ r rE )r r r� r[ rB r\ r< �uint32�dtype_i�uint64�maxnrG �_svr �_shift� _scrambler� �_quasi�_scaler( � _first_pointr rc )r� rI r� r\ r2 r� r! s �r3 r� zSobol.__init__� s� �� � !"�t�T�+7�9��� ���1�<�d��C� �t�{�{�?� �6�t�{�{�m�1�E��
� �� � � �9�9� ��D�I� �9�9��?� �9�9�D�L�
�$�)�)�
!�r�
!� � =�>� >� �9�9�D�L� � =�>� >��t�y�y�L�� � "�x�x��D�I�I��d�l�l� K����d�h�h�A�D�I�I�6��&(�h�h�q�� � �&E�D�K�
�N�N� ��k�k�&�&�(�� � �A����N�*�� � !�[�[�4�;�;� 6� ?� ?��2� F��� � -� -� 4� 4�R�Z�Z� @��r6 c � � t j t | j d| j | j
f| j �� dt j | j
| j �� z � | _ t j t | j d| j | j
| j
f| j �� � }t | j | j
|| j �� y)z&Scramble the sequence using LMS+shift.rE )r> r^ rn )rb r\ �ltm�svN) r< �dotr r� rI r\ rd r� rh �trilr rg )r� rn s r3 ri zSobol._scramble" s� � � �f�f� ����1�D�F�F�D�I�I�+>� #�|�|�
-�
����4�9�9�D�L�L�9� 9�
�� � �g�g�l�4�8�8�Q�)-������D�I�I�(F�)-� � �7� 8�� ����T�Y�Y�����
r6 r rb c
�Z � t j || j ft j �� }|dk( r|S | j |z }|| j
kD r\d| j � d| j
� d| j � d| j � d|� d|� d�
}| j d k7 r|d
z
}t |� �| j dk( r�||d z
z dk( st j d d
�� |d k( r| j }|S t |d z
| j | j | j | j | j |�� t j | j |g� d| }|S t || j d z
| j | j | j | j |�� |S )a$ Draw next point(s) in the Sobol' sequence.
Parameters
----------
n : int, optional
Number of samples to generate in the parameter space. Default is 1.
Returns
-------
sample : array_like (n, d)
Sobol' sample.
rn r z At most 2**�=z# distinct points can be generated. z0 points have been previously generated, then: n=�+z. ra zConsider increasing `bits`.r zEThe balance properties of Sobol' points require n to be a power of 2.rE r0 )rx �num_genrb r$ ro �quasirT N)r< rK rI rc r� rf r\ rB r2 r3 rl r rk rg rj � concatenate)r� rx rZ rT �total_n�msgs r3 r� z
Sobol._random3 s� � � �X�X�q�$�&�&�k���� D�� ��6��M��$�$�q�(�� �T�Y�Y� � �d�i�i�[��$�)�)�� 5 � "� 0� 0� 1� 2&�&*�&8�&8�%9��1�#�Q�w�i�r�K�
�
�y�y�B���4�4�� �S�/� !� � � �� "���Q��K�1�$��
�
� 7�CD�F� �A�v� �*�*��" �
� ��!�e�T�%7�%7�T�V�V� �+�+�$�(�(�$�+�+�!��
� � ��&�&��/���1��� �
�
��T� /� /�!� 3�����k�k�d�h�h�d�k�k� �
� �
r6 c � � d|z }| j |z }||dz
z dk( s&t dj | j ||� � �| j |� S )a� Draw point(s) from the Sobol' sequence.
This function draws :math:`n=2^m` points in the parameter space
ensuring the balance properties of the sequence.
Parameters
----------
m : int
Logarithm in base 2 of the number of samples; i.e., n = 2^m.
Returns
-------
sample : array_like (n, d)
Sobol' sample.
rE r r z�The balance properties of Sobol' points require n to be a power of 2. {0} points have been previously generated, then: n={0}+2**{1}={2}. If you still want to do this, the function 'Sobol.random()' can be used.)r� rB �formatr> )r� �mrx rx s r3 � random_base2zSobol.random_base2m sh � �"
��F���$�$�q�(���7�Q�;�'�1�,� � =�
%�f�T�%7�%7��G� D� F�
F� �{�{�1�~� r6 c �b �� t �| � � | j j � | _ | S )z�Reset the engine to base state.
Returns
-------
engine : Sobol
Engine reset to its base state.
)r r
rh r� rj �r� r! s �r3 r
z Sobol.reset� s' �� � ��
���k�k�&�&�(�� �� r6 c �< � | j dk( r<t |dz
| j | j | j | j �� n;t || j dz
| j | j | j �� | xj |z
c_ | S )a Fast-forward the sequence by `n` positions.
Parameters
----------
n : int
Number of points to skip in the sequence.
Returns
-------
engine : Sobol
The fast-forwarded engine.
r r )rx ru rb ro rv )r� r rI rg rj r s r3 r
zSobol.fast_forward� s� � � � � �� "� ��a�%��!3�!3�����8�8�4�;�;�
�
��T� /� /�!� 3�����8�8�4�;�;�
�
���a� ��� r6 ) rI r r� rr r\ �IntNumber | Noner2 r r� r r r r) r r )r| r r r )r r( )rx r r r( )r r r r r r[ �__annotations__r� ri r� r} r
r
r* r+ s @r3 r( r( c s� �� �H�T $�F�M�#� 15�!%��=A�0A��0A�)-�0A� �0A�-5�0A� ;�0A�
� 0A�d
�$ �8�89�8��8�,5�8� �8�t �< �r6 r( c � � � e Zd ZdZdddddd� d� fd�Zd� Z dd d
� dd �Zdd �Zd� fd
� Z d dd�Z d dd�Z
� xZ S )r+ a� Poisson disk sampling.
Parameters
----------
d : int
Dimension of the parameter space.
radius : float
Minimal distance to keep between points when sampling new candidates.
hypersphere : {"volume", "surface"}, optional
Sampling strategy to generate potential candidates to be added in the
final sample. Default is "volume".
* ``volume``: original Bridson algorithm as described in [1]_.
New candidates are sampled *within* the hypersphere.
* ``surface``: only sample the surface of the hypersphere.
ncandidates : int
Number of candidates to sample per iteration. More candidates result
in a denser sampling as more candidates can be accepted per iteration.
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
seed : {None, int, `numpy.random.Generator`}, optional
If `seed` is an int or None, a new `numpy.random.Generator` is
created using ``np.random.default_rng(seed)``.
If `seed` is already a ``Generator`` instance, then the provided
instance is used.
Notes
-----
Poisson disk sampling is an iterative sampling strategy. Starting from
a seed sample, `ncandidates` are sampled in the hypersphere
surrounding the seed. Candidates bellow a certain `radius` or outside the
domain are rejected. New samples are added in a pool of sample seed. The
process stops when the pool is empty or when the number of required
samples is reached.
The maximum number of point that a sample can contain is directly linked
to the `radius`. As the dimension of the space increases, a higher radius
spreads the points further and help overcome the curse of dimensionality.
See the :ref:`quasi monte carlo tutorial <quasi-monte-carlo>` for more
details.
.. warning::
The algorithm is more suitable for low dimensions and sampling size
due to its iterative nature and memory requirements.
Selecting a small radius with a high dimension would
mean that the space could contain more samples than using lower
dimension or a bigger radius.
Some code taken from [2]_, written consent given on 31.03.2021
by the original author, Shamis, for free use in SciPy under
the 3-clause BSD.
References
----------
.. [1] Robert Bridson, "Fast Poisson Disk Sampling in Arbitrary
Dimensions." SIGGRAPH, 2007.
.. [2] `StackOverflow <https://stackoverflow.com/questions/66047540>`__.
Examples
--------
Generate a 2D sample using a `radius` of 0.2.
>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from matplotlib.collections import PatchCollection
>>> from scipy.stats import qmc
>>>
>>> rng = np.random.default_rng()
>>> radius = 0.2
>>> engine = qmc.PoissonDisk(d=2, radius=radius, seed=rng)
>>> sample = engine.random(20)
Visualizing the 2D sample and showing that no points are closer than
`radius`. ``radius/2`` is used to visualize non-intersecting circles.
If two samples are exactly at `radius` from each other, then their circle
of radius ``radius/2`` will touch.
>>> fig, ax = plt.subplots()
>>> _ = ax.scatter(sample[:, 0], sample[:, 1])
>>> circles = [plt.Circle((xi, yi), radius=radius/2, fill=False)
... for xi, yi in sample]
>>> collection = PatchCollection(circles, match_original=True)
>>> ax.add_collection(collection)
>>> _ = ax.set(aspect='equal', xlabel=r'$x_1$', ylabel=r'$x_2$',
... xlim=[0, 1], ylim=[0, 1])
>>> plt.show()
Such visualization can be seen as circle packing: how many circle can
we put in the space. It is a np-hard problem. The method `fill_space`
can be used to add samples until no more samples can be added. This is
a hard problem and parameters may need to be adjusted manually. Beware of
the dimension: as the dimensionality increases, the number of samples
required to fill the space increases exponentially
(curse-of-dimensionality).
g�������?�volumer_ N)�radius� hypersphere� ncandidatesr� r2 c �� �� |||||d�| _ t �
| � |||�� | j | j d�} || | _ |dk( rdnd| _ || _
| j dz | _ || _ t j d� � 5 | j t j | j � z | _ t j$ t j& | j � | j" z � j) t* � | _ d d d � | j/ � y # t $ r!}|�dt |� ��} t | � |�d }~ww xY w# 1 sw Y �GxY w)
N)rI r� r� r� r� r )r� �surfacez? is not a valid hypersphere sampling method. It must be one of r� rE gj�t��?�ignore)�divide)r r r� �_hypersphere_volume_sample�_hypersphere_surface_sample�hypersphere_methodr7 re rB �
radius_factorr� �radius_squaredr� r< �errstaterF rI � cell_sizer� rq r r� � grid_size�_initialize_grid_pool) r� rI r� r� r� r� r2 �hypersphere_sampler9 r r! s �r3 r� zPoissonDisk.__init__$ sR �� � !"�V�*5�*5�+7�9��� ���1�<�d��C� �5�5��7�7�
��
/�&8��&E�D� #� #.��"9�Q�u��� �� � "�k�k�1�n��� '���
�[�[��
)� � !�[�[�2�7�7�4�6�6�?� :�D�N�����������$�.�.�8�9��f�S�k�
�N� �
�"�"�$��/ � /� �/� ".�.1�2D�.E�-H�J�
� �W�%�3� .�� /��" � �s$ �
D- � B E�- E�6 E�E�E#c � � g | _ t j t j | j | j
� t j �� | _ | j j t j � y)z Sampling pool and sample grid.rn N)
� sample_poolr< rK �appendr� rI �float32� sample_grid�fill�nan�r� s r3 r� z!PoissonDisk._initialize_grid_poolU sT � � ��� �8�8� �I�I�d�n�n�d�f�f� -��*�*�
���
��� � �b�f�f�%r6 r rb c �2 � � � |dk( s� j dk( r!t j |� j f� S dd�}dd� fd�
}d � � fd� }g � t � j � dk( r. |� j
j
� j � � d}nd}t � j � r�||k r�t � j
t � j � � }� j | }� j |= � j |� j � j z � j � } | D ]( }
||
� s� ||
� r� ||
� |dz
}||k\ s�( n t � j � r||k r��� xj |z
c_ t j � � S )
a� Draw `n` in the interval ``[0, 1]``.
Note that it can return fewer samples if the space is full.
See the note section of the class.
Parameters
----------
n : int, optional
Number of samples to generate in the parameter space. Default is 1.
Returns
-------
sample : array_like (n, d)
QMC sample.
r c �R � | j � dk xr | j � dk\ S )NrJ rK )rQ rR �rT s r3 � in_limitsz&PoissonDisk._random.<locals>.in_limitsw s# � ��J�J�L�B�&�@�V�Z�Z�\�R�-?� @r6 c � �� | �j z j t � }t j ||z
t j
�j t �� � }t j ||z dz �j � }t j �j t |� d � syt �j � D �cg c] }t || || � �� }}t j d�� 5 t j t j t j" | �j t |� z
� �j �� �j$ k � r
ddd� y ddd� y c c}w # 1 sw Y y xY w)
zz
Check if there are samples closer than ``radius_squared`` to the
`candidate` sample.
rn r r Tr� )�invalidrl NF)r� r r� r< �maximumrG rI �minimumr� �isnanr� �tupler� �slicer� �anyrs �squarer� )� candidaterx �indices�ind_min�ind_maxr� �ar� s �r3 �in_neighborhoodz,PoissonDisk._random.<locals>.in_neighborhoodz s= �� �
!�4�>�>�1�9�9�#�>�G��j�j��1��b�h�h�t�v�v�S�.I�J�G��j�j��1��q� �$�.�.�A�G� �8�8�D� ,� ,�U�7�^� <�Q� ?�@��8=�d�f�f�
�F�1��w�q�z�7�1�:�.�F�A�F� ���X�.�
��6�6��F�F�� � �)�d�.>�.>�u�Q�x�.H�"H�I� !�V�V�� �+�+�,�� �
�
��
� �� G�
� �s � E?�=A/F�F
c �� �� �j j | � | �j z j t � }| �j
t
|� < �j | � y r/ )r� r� r� r r� r� r� )r� r� � curr_sampler� s ��r3 �
add_samplez'PoissonDisk._random.<locals>.add_sample� sR �� � � � � #� #�I� .� �4�>�>�1�9�9�#�>�G�/8�D� � �U�7�^� ,� � � �y� )r6 r )rT r r rr �rE )r� r rx r� r rr )r� r r r )rI r< rK r� r� r� r> r r� r� r� r� r� r& ) r� rx rZ r� r� r� � num_drawn�
idx_center�center�
candidatesr� r� s ` @r3 r� zPoissonDisk._randoma sj �� �&
��6�T�V�V�q�[��8�8�Q����K�(� (� A� �8 *� )+� � �t� � � �A� %� �t�x�x���t�v�v�.� /��I��I� �$�"�"�#� �A�
�%�d�h�h��D�4D�4D�0E�F�J��%�%�j�1�F�� � ��,� �0�0��� � �d�&8�&8�8�$�:J�:J��J�
(�
� � �Y�'�� �0J� �y�)� ��N�I� �A�~� �
� �$�"�"�#� �A�
�(
���i�'���x�x� �$�$r6 c �@ � | j t j � S )a Draw ``n`` samples in the interval ``[0, 1]``.
Unlike `random`, this method will try to add points until
the space is full. Depending on ``candidates`` (and to a lesser extent
other parameters), some empty areas can still be present in the sample.
.. warning::
This can be extremely slow in high dimensions or if the
``radius`` is very small-with respect to the dimensionality.
Returns
-------
sample : array_like (n, d)
QMC sample.
)r> r< �infr� s r3 �
fill_spacezPoissonDisk.fill_space� s � �$ �{�{�2�6�6�"�"r6 c �D �� t �| � � | j � | S )z�Reset the engine to base state.
Returns
-------
engine : PoissonDisk
Engine reset to its base state.
)r r
r� r s �r3 r
zPoissonDisk.reset� s �� � ��
�� �"�"�$�� r6 c � � | j j || j f�� }t j |dz d�� }|t | j dz |dz � d| j z z z t j |� z }t j |j dd� d| j f� }|t j ||� z }|S )z$Uniform sampling within hypersphere.r= rE r rl rE )
r� �standard_normalrI r< rs r rF r@ r( �multiply) r� r� r� r� �x�ssq�fr�fr_tiledrN s r3 r� z&PoissonDisk._hypersphere_volume_sample� s� � �
�H�H� $� $�:�t�v�v�*>� $� ?���f�f�Q��T��"��
�h�t�v�v�a�x��Q��/�!�D�F�F�(�;�
;�b�g�g�c�l�
J���7�7� �J�J�r�1� ��4�6�6�{�
��
�R�[�[��H�-� -���r6 c �� � | j j || j f�� }|t j j |d�� dd�df z }|t j ||� z }|S )z.Uniform sampling on the hypersphere's surface.r= r rl N)r� r� rI r< �linalg�normr� )r� r� r� r� �vecrN s r3 r� z'PoissonDisk._hypersphere_surface_sample� sb � �
�h�h�&�&�Z����,@�&�A�� �r�y�y�~�~�c��~�*�1�d�7�3�3�� �R�[�[��f�-� -���r6 )rI r r� r r� z Literal['volume', 'surface']r� r r� r r2 r r r r r )r r )r r+ )r� r r� r r� r r r ) r r r r r� r� r� r� r
r� r� r* r+ s @r3 r+ r+ � s� �� �m�f !%�4<�!#�=A� �/%� �/%� � /%�
2� /%� �
/%� ;�/%� �/%�
�/%�b
&� �Z%�89�Z%��Z%�,5�Z%� �Z%�x#�( � !"�
� �
�*7�
� �
�
�
�" !"�� ��*7�� ��
�r6 r+ c �^ � e Zd ZdZ d ddddd� d
d�Zd d d�Zd
d�Zd d d�Zy)r- aj QMC sampling from a multivariate Normal :math:`N(\mu, \Sigma)`.
Parameters
----------
mean : array_like (d,)
The mean vector. Where ``d`` is the dimension.
cov : array_like (d, d), optional
The covariance matrix. If omitted, use `cov_root` instead.
If both `cov` and `cov_root` are omitted, use the identity matrix.
cov_root : array_like (d, d'), optional
A root decomposition of the covariance matrix, where ``d'`` may be less
than ``d`` if the covariance is not full rank. If omitted, use `cov`.
inv_transform : bool, optional
If True, use inverse transform instead of Box-Muller. Default is True.
engine : QMCEngine, optional
Quasi-Monte Carlo engine sampler. If None, `Sobol` is used.
seed : {None, int, `numpy.random.Generator`}, optional
Used only if `engine` is None.
If `seed` is an int or None, a new `numpy.random.Generator` is
created using ``np.random.default_rng(seed)``.
If `seed` is already a ``Generator`` instance, then the provided
instance is used.
Examples
--------
>>> import matplotlib.pyplot as plt
>>> from scipy.stats import qmc
>>> dist = qmc.MultivariateNormalQMC(mean=[0, 5], cov=[[1, 0], [0, 1]])
>>> sample = dist.random(512)
>>> _ = plt.scatter(sample[:, 0], sample[:, 1])
>>> plt.show()
NT)�cov_root�
inv_transform�enginer2 c � � t j |dd�� }|j d }|��t j |dd�� }|j d |j d k( s t d� �t j ||j � � s t d� � t j j |� j � }nC|�?t j |� }|j d |j d k( s
t d� �d }|| _ |s dt j |dz � z }
n|}
|�t# |
d d |�
� | _ n=t' |t( � r"|j* |
k7 r t d� �|| _ n t d� �|| _ || _ || _ y # t j j $ r� t j j |� \ }} t j |dk\ � s t d � �t j |d
d � }| t j |� z j � }Y ��3w xY w)NFr �r� �ndminr rE z/Dimension mismatch between mean and covariance.z#Covariance matrix is not symmetric.g:�0�yE�zCovariance matrix not PSD.rK Tr_ �rI r� r\ r2 z�Dimension of `engine` must be consistent with dimensions of mean and covariance. If `inv_transform` is False, it must be an even number.�F`engine` must be an instance of `scipy.stats.qmc.QMCEngine` or `None`.)r< r& rP rB �allclose� transposer� �cholesky� LinAlgError�eighrS �cliprF �
atleast_2d�_inv_transformr� r� r( r� r9 r' rI �_mean� _corr_matrix�_d) r� �mean�covr� r� r� r2 rI �eigval�eigvec�
engine_dims r3 r� z MultivariateNormalQMC.__init__ s � � �x�x��5��2�� �J�J�q�M�� �?��(�(�3�U�!�4�C� �:�:�a�=�C�I�I�a�L�0� � "/� 0� 0��;�;�s�C�M�M�O�4� �!F�G�G�
B� �9�9�-�-�c�2�<�<�>�� �
!��}�}�X�.�H��:�:�a�=�H�N�N�1�$5�5� � "/� 0� 0� �H� +��� ��T�Y�Y�q�1�u� -�-�J��J� �>� � �t�"�4��D�K� �� �
*��x�x�:�%� � "4� 5� 5� !�D�K� � F� G�
G� ��
� $�������S �9�9�(�(�
B�!#��� � ��!4�����v�v�f�� /�0�$�%A�B�B������d�3�� "�R�W�W�V�_� 4�?�?�A��
B�s � -F � B I� Ic �F � | j |� }| j |� S )a% Draw `n` QMC samples from the multivariate Normal.
Parameters
----------
n : int, optional
Number of samples to generate in the parameter space. Default is 1.
Returns
-------
sample : array_like (n, d)
Sample.
)�_standard_normal_samples�
_correlate)r� rx � base_sampless r3 r> z MultivariateNormalQMC.random\ s# � � �4�4�Q�7� ����|�,�,r6 c �p � | j � || j z | j z S || j z S r/ )r� r� )r� r� s r3 r� z MultivariateNormalQMC._correlatem s9 � � � � � (� �$�"3�"3�3�d�j�j�@� @� �$�*�*�,� ,r6 c �f � | j j |� }| j r(t j j dd|dz
z z � S t
j d|j d d� }t
j dt
j |dd�|f � z � }dt j z |dd�d|z f z }t
j |� }t
j |� }t
j ||z ||z gd� j! |d� }|dd�d| j" �f S ) a3 Draw `n` QMC samples from the standard Normal :math:`N(0, I_d)`.
Parameters
----------
n : int, optional
Number of samples to generate in the parameter space. Default is 1.
Returns
-------
sample : array_like (n, d)
Sample.
rk g�A��?r rE rE rD Nr )r� r> r� �statsr� �ppfr< r� rP rF �logr� �pi�cos�sinrH r( r� ) r� rx rA �even�Rs�thetasr� r� �transf_sampless r3 r� z.MultivariateNormalQMC._standard_normal_samplest s � � �+�+�$�$�Q�'�� � � � �:�:�>�>�#��w��}�(E�"E�F� F� �9�9�Q��
�
�b� 1�1�5�D�����b�f�f�W�Q��W�%5� 6�6�7�B�����[�7�1�a�$�h�;�#7�7�F��&�&��.�C��&�&��.�C� �X�X�r�C�x��c��&:�&(� *�*1�'�!�R�.�
� "�!�Y�t�w�w�Y�,�/� /r6 r/ )r� r r� r r� r r� rr r� �QMCEngine | Noner2 r r r r rY )r� r r r )r r r r r� r> r� r� r0 r6 r3 r- r- � su � � �F DH�?�-1�"&�'+� !� ?�%�?�,@�?�*�?� �?� %� ?�
� ?�
�
?�B-�"-� 0r6 r- c �< � e Zd ZdZddd� dd�Zddd�Zy) r, a9 QMC sampling from a multinomial distribution.
Parameters
----------
pvals : array_like (k,)
Vector of probabilities of size ``k``, where ``k`` is the number
of categories. Elements must be non-negative and sum to 1.
n_trials : int
Number of trials.
engine : QMCEngine, optional
Quasi-Monte Carlo engine sampler. If None, `Sobol` is used.
seed : {None, int, `numpy.random.Generator`}, optional
Used only if `engine` is None.
If `seed` is an int or None, a new `numpy.random.Generator` is
created using ``np.random.default_rng(seed)``.
If `seed` is already a ``Generator`` instance, then the provided
instance is used.
Examples
--------
Let's define 3 categories and for a given sample, the sum of the trials
of each category is 8. The number of trials per category is determined
by the `pvals` associated to each category.
Then, we sample this distribution 64 times.
>>> import matplotlib.pyplot as plt
>>> from scipy.stats import qmc
>>> dist = qmc.MultinomialQMC(
... pvals=[0.2, 0.4, 0.4], n_trials=10, engine=qmc.Halton(d=1)
... )
>>> sample = dist.random(64)
We can plot the sample and verify that the median of number of trials
for each category is following the `pvals`. That would be
``pvals * n_trials = [2, 4, 4]``.
>>> fig, ax = plt.subplots()
>>> ax.yaxis.get_major_locator().set_params(integer=True)
>>> _ = ax.boxplot(sample)
>>> ax.set(xlabel="Categories", ylabel="Trials")
>>> plt.show()
N)r� r2 c � � t j |dd�� | _ t j |� dk r t d� �t j
t j |� d� s t d� �|| _ |�t ddd|� � | _ y t |t � r"|j dk7 r t d
� �|| _ y t d � �) NFr r� r z'Elements of pvals must be non-negative.z Elements of pvals must sum to 1.Tr_ r� z Dimension of `engine` must be 1.r� )
r< r& �pvalsrR rB �isclosers �n_trialsr( r� r9 r' rI )r� r� r� r� r2 s r3 r� zMultinomialQMC.__init__� s� � �
�X�X�e�%�q�9��
�
�6�6�%�=�1� � � F�G� G��z�z�"�&�&��-��+� � ?�@� @� ��
� �>� ��d��$��D�K� �� �
*��x�x�1�}� �!C�D�D� �D�K� � F� G�
Gr6 c � � t j |t | j � f� }t |� D ]� }| j
j
| j � j � }t j | j t �� }t t j | j t �� |� t j | j t �� }t |||� |||< �� |S )a/ Draw `n` QMC samples from the multinomial distribution.
Parameters
----------
n : int, optional
Number of samples to generate in the parameter space. Default is 1.
Returns
-------
samples : array_like (n, pvals)
Sample.
rn )r< rK r� r� r� r� r> r� �ravel�
empty_like�floatr r& �
zeros_liker� r )r� rx rT r� �
base_draws� p_cumulative�sample_s r3 r> zMultinomialQMC.random� s� � � ���1�c�$�*�*�o�.�/���q�� �A� ���+�+�D�M�M�:�@�@�B�J� �=�=����5�A�L� �r�x�x��
�
�%� @�,� O��m�m�D�J�J�c�:�G� �
�L�'� :� �F�1�I�
� �
r6 )
r� r r� r r� r� r2 r r r r rY )r r r r r� r> r0 r6 r3 r, r, � sL � �*�\ '+� �G�"�G�.7�G�#�G� �G�
� G�.r6 r, c �� � t t d�}| �$ | j � } || }t
|fi |��}|S d}|S # t $ r!}| �dt |� ��}t |� |�d}~ww xY w)z#A factory for optimization methods.)z random-cd�lloydNz7 is not a valid optimization method. It must be one of )�
_random_cd�&_lloyd_centroidal_voronoi_tessellationrU r7 re rB r )r� r� r� �
optimizer_r9 r � optimizers r3 r� r� � s� � �
�7�0�� � � /�'�-�-�/�L�,�\�:�J� �J�1�&�1� � �� � � ��� � /�&�)� *� � 2�3�6�8�G� �W�%�3� .�� /�s �8 � A"� A � A"c �� � ~| j \ }}|dk( s|dk( rt j ||f� S |dk( s|dk( r| S t | � }d|dz
gd|dz
gd|dz
gf}d} d}
| |k r�|
|k r}|
dz
}
t |g|d ��ddi�} t |g|d ��ddi�} t |g|d ��ddi�}
t | | |
| |� }||k r | |
| f | | | f c| | | f< | |
| f< |}d} n| dz
} | |k r|
|k r�}| S )a� Optimal LHS on CD.
Create a base LHS and do random permutations of coordinates to
lower the centered discrepancy.
Because it starts with a normal LHS, it also works with the
`centered` keyword argument.
Two stopping criterion are used to stop the algorithm: at most,
`n_iters` iterations are performed; or if there is no improvement
for `n_nochange` consecutive iterations.
r r r TrE )rP r< rK r% r r� )� best_sampler� r� r� �kwargsrx rI � best_disc�bounds� n_nochange_�n_iters_�col�row_1�row_2rw s r3 r r sh � � � � � �D�A�q��A�v��a���x�x��A�� � ��A�v��a�����K�(�I��!�a�%�j��!�a�%�j��!�a�%�j��F� �K��H�
�
�
"�x�'�'9��A�
���3�:����:�T�:�� �S�<�6�!�9�<�t�<�� �S�<�6�!�9�<�t�<��#�K�$)�5�#�$-�/�� �)� ��E�3�J�'��U�C�Z�)@�
=�K��s�
� #�[����%<� �I��K� �1� �K�! �
�
"�x�'�'9�$ �r6 c �J � t j | d� j � S )N� cityblock)r �pdistrR r� s r3 �_l1_normr E s � � �>�>�&�+� .� 2� 2� 4�4r6 c � � t j | � }t | |�� }t |j � D ]a \ }}|j
| D �cg c]
}|dk7 s� |�� }}|j | } t j | d�� }
| | |
| | z
|z z ||< �c t j t j |dk\ |dk � d�� } || | | < | S c c}w )uf Lloyd-Max algorithm iteration.
Based on the implementation of Stéfan van der Walt:
https://github.com/stefanv/lloyd
which is:
Copyright (c) 2021-04-21 Stéfan van der Walt
https://github.com/stefanv/lloyd
MIT License
Parameters
----------
sample : array_like (n, d)
The sample to iterate on.
decay : float
Relaxation decay. A positive value would move the samples toward
their centroid, and negative value would move them away.
1 would move the samples to their centroid.
qhull_options : str
Additional options to pass to Qhull. See Qhull manual
for details. (Default: "Qbb Qc Qz Qj Qx" for ndim > 4 and
"Qbb Qc Qz Qj" otherwise.)
Returns
-------
sample : array_like (n, d)
The sample after an iteration of Lloyd's algorithm.
)r� rE r rl r )
r< r� r r$ � point_region�regions�verticesr� rS � logical_and) rT �decayr� �
new_sample�voronoi�iirX r� �region�verts�centroid�is_valids r3 �_lloyd_iterationr I s� � �H � � �v�&�J��f�M�:�G� �W� 1� 1�2� F���C� %�_�_�S� 1�=��Q�"�W�!�=��=� � � ��(�� �7�7�5�q�)�� ���x�&��*�'<��&E�E�
�2�� F�$ �v�v�b�n�n�Z�1�_�j�A�o�F�Q�O�H�!�(�+�F�8�� �M��% >s �
C�Cr� r� )r� r� r� c � � ~t j | � j � } | j dk( s t d� �| j
d dk\ s t d� �| j
� dkD s| j � dk r t d� �|�d}| j
d d k\ r|d
z
}| t j d � z }t |� D �cg c] }t j | |z � d z �� }}t | �
� }t |� D ]5 } t | || |�� } t | �
� }
t |
|z
� |k r | S |
}�7 | S c c}w )ac Approximate Centroidal Voronoi Tessellation.
Perturb samples in N-dimensions using Lloyd-Max algorithm.
Parameters
----------
sample : array_like (n, d)
The sample to iterate on. With ``n`` the number of samples and ``d``
the dimension. Samples must be in :math:`[0, 1]^d`, with ``d>=2``.
tol : float, optional
Tolerance for termination. If the min of the L1-norm over the samples
changes less than `tol`, it stops the algorithm. Default is 1e-5.
maxiter : int, optional
Maximum number of iterations. It will stop the algorithm even if
`tol` is above the threshold.
Too many iterations tend to cluster the samples as a hypersphere.
Default is 10.
qhull_options : str, optional
Additional options to pass to Qhull. See Qhull manual
for details. (Default: "Qbb Qc Qz Qj Qx" for ndim > 4 and
"Qbb Qc Qz Qj" otherwise.)
Returns
-------
sample : array_like (n, d)
The sample after being processed by Lloyd-Max algorithm.
Notes
-----
Lloyd-Max algorithm is an iterative process with the purpose of improving
the dispersion of samples. For given sample: (i) compute a Voronoi
Tessellation; (ii) find the centroid of each Voronoi cell; (iii) move the
samples toward the centroid of their respective cell. See [1]_, [2]_.
A relaxation factor is used to control how fast samples can move at each
iteration. This factor is starting at 2 and ending at 1 after `maxiter`
following an exponential decay.
The process converges to equally spaced samples. It implies that measures
like the discrepancy could suffer from too many iterations. On the other
hand, L1 and L2 distances should improve. This is especially true with
QMC methods which tend to favor the discrepancy over other criteria.
.. note::
The current implementation does not intersect the Voronoi Tessellation
with the boundaries. This implies that for a low number of samples,
empirically below 20, no Voronoi cell is touching the boundaries.
Hence, samples cannot be moved close to the boundaries.
Further improvements could consider the samples at infinity so that
all boundaries are segments of some Voronoi cells. This would fix
the computation of the centroid position.
.. warning::
The Voronoi Tessellation step is expensive and quickly becomes
intractable with dimensions as low as 10 even for a sample
of size as low as 1000.
.. versionadded:: 1.9.0
References
----------
.. [1] Lloyd. "Least Squares Quantization in PCM".
IEEE Transactions on Information Theory, 1982.
.. [2] Max J. "Quantizing for minimum distortion".
IEEE Transactions on Information Theory, 1960.
Examples
--------
>>> import numpy as np
>>> from scipy.spatial import distance
>>> rng = np.random.default_rng()
>>> sample = rng.random((128, 2))
.. note::
The samples need to be in :math:`[0, 1]^d`. `scipy.stats.qmc.scale`
can be used to scale the samples from their
original bounds to :math:`[0, 1]^d`. And back to their original bounds.
Compute the quality of the sample using the L1 criterion.
>>> def l1_norm(sample):
... return distance.pdist(sample, 'cityblock').min()
>>> l1_norm(sample)
0.00161... # random
Now process the sample using Lloyd's algorithm and check the improvement
on the L1. The value should increase.
>>> sample = _lloyd_centroidal_voronoi_tessellation(sample)
>>> l1_norm(sample)
0.0278... # random
rE z`sample` is not a 2D arrayr z `sample` dimension is not >= 2rJ rK z!`sample` is not in unit hypercubez Qbb Qc Qz QJr� z Qxg�������?g�������?r� )rT r r� )r< rM r� rN rB rP rQ rR r� r� �expr r rp ) rT r� r� r� r �rootr� r �l1_oldr� �l1_news r3 r r � sO � �T �
�Z�Z��
�
$�
$�
&�F� �;�;�!� ��5�6�6� �<�<��?�a� ��9�:�:� �
�
� �r��v�z�z�|�b� 0��<�=�=�� �&�
� �<�<��?�a� � �U� "�M�
�8�b�f�f�S�k� !�D�,1�'�N� ;�q�R�V�V�Q�B��I�
�s�
"� ;�E� ;�
�V�
$�F�
�7�^� ��!� �U�1�X� +�
��
��(�� �v��� �#� %� � �M� �F� � �M��!
<s �#Ec � � t | � } | dk( r#t j � } | � t d� �| S | dk rt d| � d�� �| S )a@ Validate `workers` based on platform and value.
Parameters
----------
workers : int, optional
Number of workers to use for parallel processing. If -1 is
given all CPU threads are used. Default is 1.
Returns
-------
Workers : int
Number of CPU used by the algorithm
rE zaCannot determine the number of cpus using os.cpu_count(), cannot use -1 for the number of workersr zInvalid number of workers: z, must be -1 or > 0)r� �os� cpu_count�NotImplementedErrorrB rb s r3 rd rd
sl � � �'�l�G��"�}��,�,�.�� �?�%�:��
� �N�
�A� ��6�w�i� @"� "� #� #� �Nr6 c �� � t j | |� }t j ||� }t j ||k � s t d� �||fS # t $ r}d}t |� |�d}~ww xY w)a Bounds input validation.
Parameters
----------
l_bounds, u_bounds : array_like (d,)
Lower and upper bounds.
d : int
Dimension to use for broadcasting.
Returns
-------
l_bounds, u_bounds : array_like (d,)
Lower and upper bounds.
zP'l_bounds' and 'u_bounds' must be broadcastable and respect the sample dimensionNz1Bounds are not consistent 'l_bounds' < 'u_bounds')r< � broadcast_torB rS )rG rH rI rU rV r9 ry s r3 rO rO <
st � �$'�����!�,������!�,�� �6�6�%�%�-� ��L�M�M� �%�<��� � '�'����o�3�&��'�s �,A � A1� A,�,A1).)r2 r� r znp.random.Generator)r2 r
r r
r/ )
rT r rG r rH r rC rr r r )
rT r rX rr rY z$Literal['CD', 'WD', 'MD', 'L2-star']rZ r r r� )rh r rT r ri r r r� )
rT r rt r� ru r� rv r� rw r� )rx r� r r )rx r r z list[int])r� r r� r r r r� )rx r r� r r� r r� rr r� r r2 r rZ r r r )r� r r� �dictr zCallable | None) r r r� r� r� r� r� r
r r, r r )rT r r r� )rT r r r� r� �strr r ) rT r r� r r� r r� z
str | Noner r, r r r )rZ r r r )rG r rH r rI r� r ztuple[np.ndarray, ...])Mr �
__future__r r� r� r: r' r2 �abcr r � functoolsr �typingr r r r
r �numpyr< � numpy.typing�npt�scipy._lib._utilr r
r r � scipy.statsr� r r �
scipy.spatialr r �
scipy.specialr �_sobolr r r r r r r �_qmc_cyr r r r r! r" r# �__all__r4 r$ r% r& r� r� r� r� r� r' r) r* r( r+ r- r, r� r r r r rd rO r0 r6 r3 �<module>r< sz �� ,� "� � � � � � #� �� � �� �� � � 5� +� "�� � �� � � 6��
��
��
��
��
=�> � P2� �P2��P2� �P2�
� P2� �
P2�l �7;� � G/� �G/� �G/� 5� G/�
� G/�
$)� G/�T:G� �:G� �:G� $�:G� ).�:G�zW� $�W�t A�@$�P 26�#�
�#�&.�#��#�P �AA� "#� �-1� � �AA� �AA��AA� � AA�
� AA� +�
AA� �AA� �AA� $.�AA�H]�� ]�@ Z5�Y� Z5�zf)�Y� f)�R N�I� N�b
A�)� A�H
Z0� Z0�zZ� Z�z�6��@D����84��4�&)�4�7:�4�AN�4��4� �4�n5�=� �=� �=� �=� � =�F �� $� R� �R�
�R� � R�
� R� �
R� �R�j�< �� �'4� �9<� �� r6