class_docstr: 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 Owen scrambling. Otherwise no scrambling is done.
      Default is True.
  seed : {None, int, `numpy.random.Generator`}, optional
      If `seed` is None the `numpy.random.Generator` singleton is used.
      If `seed` is an int, a new ``Generator`` instance is used,
      seeded with `seed`.
      If `seed` is already a ``Generator`` instance then that instance is
      used.
  
  Notes
  -----
  Sobol' sequences [1]_ provide :math:`n=2^m` low discrepancy points in
  :math:`[0,1)^{d}`. Scrambling them [2]_ makes them suitable for singular
  integrands, provides a means of error estimation, and can improve their
  rate of convergence.
  
  There are many versions of Sobol' sequences depending on their
  'direction numbers'. This code uses direction numbers from [3]_. 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 [4]_.
  
     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 will repeat.
     Currently :math:`B=30`.
  
  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] Art B. Owen. Scrambling Sobol and Niederreiter-Xing points.
     Journal of Complexity, 14(4):466-489, December 1998.
  
  .. [3] S. Joe and F. Y. Kuo. Constructing sobol sequences with better
     two-dimensional projections. SIAM Journal on Scientific Computing,
     30(5):2635-2654, 2008.
  
  .. [4] 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]])
class_docstr_tok: ["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","Owen","scrambling",".","Otherwise","no","scrambling","is","done",".","Default","is","True",".","seed",":","{","None",",","int",",","`","numpy.random.Generator","`","}",",","optional","If","`","seed","`","is","None","the","`","numpy.random.Generator","`","singleton","is","used",".","If","`","seed","`","is","an","int",",","a","new","``","Generator","``","instance","is","used",",","seeded","with","`","seed","`",".","If","`","seed","`","is","already","a","``","Generator","``","instance","then","that","instance","is","used",".","Notes","--","--","-","Sobol","'","sequences","[","1","]","_","provide",":","math",":","`","n=2^m","`","low","discrepancy","points","in",":","math",":","`","[","0,1",")","^","{","d","}","`",".","Scrambling","them","[","2","]","_","makes","them","suitable","for","singular","integrands",",","provides","a","means","of","error","estimation",",","and","can","improve","their","rate","of","convergence",".","There","are","many","versions","of","Sobol","'","sequences","depending","on","their","'direction","numbers","'",".","This","code","uses","direction","numbers","from","[","3","]","_",".","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","[","4","]","_",".","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","will","repeat",".","Currently",":","math",":","`","B=30","`",".","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","]","Art","B.","Owen",".","Scrambling","Sobol","and","Niederreiter-Xing","points",".","Journal","of","Complexity",",","14","(","4",")",":466-489",",","December","1998",".","..","[","3","]","S.","Joe","and","F.","Y.","Kuo",".","Constructing","sobol","sequences","with","better","two-dimensional","projections",".","SIAM","Journal","on","Scientific","Computing",",","30","(","5",")",":2635-2654",",","2008",".","..","[","4","]","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","]","]",")"]
docstr: 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.
code: def random_base2(self, m: IntNumber) -> np.ndarray:
      """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.
  
      """
      n = 2**m
  
      total_n = self.num_generated + n
      if not (total_n & (total_n - 1) == 0):
          raise ValueError(
              "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.".format(
                  self.num_generated, m, total_n
              )
          )
  
      return self.random(n)
  
imports: from __future__ import annotations
  import os
  import copy
  import numbers
  from abc import ABC, abstractmethod
  import math
  from typing import ClassVar, List, Optional, overload, TYPE_CHECKING
  import warnings
  import numpy
  import scipy.stats
  from scipy._lib._util import rng_integers
  from scipy.stats._sobol import initialize_v, _cscramble, _fill_p_cumulative, _draw, _fast_forward, _categorize, initialize_direction_numbers, _MAXDIM, _MAXBIT
  from scipy.stats._qmc_cy import _cy_wrapper_centered_discrepancy, _cy_wrapper_wrap_around_discrepancy, _cy_wrapper_mixture_discrepancy, _cy_wrapper_l2_star_discrepancy, _cy_wrapper_update_discrepancy
label_desc: Use image node_id 4 for calling the Sobol obj's underlying member method code with example usage: obj.random_base2(m) and returns: self