class_docstr: Fast sampling by numerical inversion of the CDF for a large class of
  continuous distributions in `scipy.stats`.
  
  Parameters
  ----------
  dist : rv_frozen object
      Frozen distribution object from `scipy.stats`. The list of supported
      distributions can be found in the Notes section. The shape parameters,
      `loc` and `scale` used to create the distributions must be scalars.
      For example, for the Gamma distribution with shape parameter `p`,
      `p` has to be a float, and for the beta distribution with shape
      parameters (a, b), both a and b have to be floats.
  domain : tuple of floats, optional
      If one wishes to sample from a truncated/conditional distribution,
      the domain has to be specified.
      The default is None. In that case, the random variates are not
      truncated, and the domain is inferred from the support of the
      distribution.
  ignore_shape_range : boolean, optional.
      If False, shape parameters that are outside of the valid range
      of values to ensure that the numerical accuracy (see Notes) is
      high, raise a ValueError. If True, any shape parameters that are valid
      for the distribution are accepted. This can be useful for testing.
      The default is False.
  random_state : {None, int, `numpy.random.Generator`,
                      `numpy.random.RandomState`}, optional
  
          A NumPy random number generator or seed for the underlying NumPy
          random number generator used to generate the stream of uniform
          random numbers.
          If `random_state` is None, it uses ``self.random_state``.
          If `random_state` is an int,
          ``np.random.default_rng(random_state)`` is used.
          If `random_state` is already a ``Generator`` or ``RandomState``
          instance then that instance is used.
  
  Attributes
  ----------
  loc : float
      The location parameter.
  random_state : {`numpy.random.Generator`, `numpy.random.RandomState`}
      The random state used in relevant methods like `rvs` (unless
      another `random_state` is passed as an argument to these methods).
  scale : float
      The scale parameter.
  
  Methods
  -------
  cdf
  evaluate_error
  ppf
  qrvs
  rvs
  support
  
  Notes
  -----
  The class creates an object for continuous distributions specified
  by `dist`. The method `rvs` uses a generator from
  `scipy.stats.sampling` that is created when the object is instantiated.
  In addition, the methods `qrvs` and `ppf` are added.
  `qrvs` generate samples based on quasi-random numbers from
  `scipy.stats.qmc`. `ppf` is the PPF based on the
  numerical inversion method in [1]_ (`NumericalInversePolynomial`) that is
  used to generate random variates.
  
  Supported distributions (`distname`) are:
  ``alpha``, ``anglit``, ``argus``, ``beta``, ``betaprime``, ``bradford``,
  ``burr``, ``burr12``, ``cauchy``, ``chi``, ``chi2``, ``cosine``,
  ``crystalball``, ``expon``, ``gamma``, ``gennorm``, ``geninvgauss``,
  ``gumbel_l``, ``gumbel_r``, ``hypsecant``, ``invgamma``, ``invgauss``,
  ``invweibull``, ``laplace``, ``logistic``, ``maxwell``, ``moyal``,
  ``norm``, ``pareto``, ``powerlaw``, ``t``, ``rayleigh``, ``semicircular``,
  ``wald``, ``weibull_max``, ``weibull_min``.
  
  `rvs` relies on the accuracy of the numerical inversion. If very extreme
  shape parameters are used, the numerical inversion might not work. However,
  for all implemented distributions, the admissible shape parameters have
  been tested, and an error will be raised if the user supplies values
  outside of the allowed range. The u-error should not exceed 1e-10 for all
  valid parameters. Note that warnings might be raised even if parameters
  are within the valid range when the object is instantiated.
  To check numerical accuracy, the method `evaluate_error` can be used.
  
  Note that all implemented distributions are also part of `scipy.stats`, and
  the object created by `FastGeneratorInversion` relies on methods like
  `ppf`, `cdf` and `pdf` from `rv_frozen`. The main benefit of using this
  class can be summarized as follows: Once the generator to sample random
  variates is created in the setup step, sampling and evaluation of
  the PPF using `ppf` are very fast,
  and performance is essentially independent of the distribution. Therefore,
  a substantial speed-up can be achieved for many distributions if large
  numbers of random variates are required. It is important to know that this
  fast sampling is achieved by inversion of the CDF. Thus, one uniform
  random variate is transformed into a non-uniform variate, which is an
  advantage for several simulation methods, e.g., when
  the variance reduction methods of common random variates or
  antithetic variates are be used ([2]_).
  
  In addition, inversion makes it possible to
  - to use a QMC generator from `scipy.stats.qmc` (method `qrvs`),
  - to generate random variates truncated to an interval. For example, if
  one aims to sample standard normal random variates from
  the interval (2, 4), this can be easily achieved by using the parameter
  `domain`.
  
  The location and scale that are initially defined by `dist`
  can be reset without having to rerun the setup
  step to create the generator that is used for sampling. The relation
  of the distribution `Y` with `loc` and `scale` to the standard
  distribution `X` (i.e., ``loc=0`` and ``scale=1``) is given by
  ``Y = loc + scale * X``.
  
  References
  ----------
  .. [1] Derflinger, Gerhard, Wolfgang Hörmann, and Josef Leydold.
         "Random variate  generation by numerical inversion when only the
         density is known." ACM Transactions on Modeling and Computer
         Simulation (TOMACS) 20.4 (2010): 1-25.
  .. [2] Hörmann, Wolfgang, Josef Leydold and Gerhard Derflinger.
         "Automatic nonuniform random number generation."
         Springer, 2004.
  
  Examples
  --------
  >>> import numpy as np
  >>> from scipy import stats
  >>> from scipy.stats.sampling import FastGeneratorInversion
  
  Let's start with a simple example to illustrate the main features:
  
  >>> gamma_frozen = stats.gamma(1.5)
  >>> gamma_dist = FastGeneratorInversion(gamma_frozen)
  >>> r = gamma_dist.rvs(size=1000)
  
  The mean should be approximately equal to the shape parameter 1.5:
  
  >>> r.mean()
  1.52423591130436  # may vary
  
  Similarly, we can draw a sample based on quasi-random numbers:
  
  >>> r = gamma_dist.qrvs(size=1000)
  >>> r.mean()
  1.4996639255942914  # may vary
  
  Compare the PPF against approximation `ppf`.
  
  >>> q = [0.001, 0.2, 0.5, 0.8, 0.999]
  >>> np.max(np.abs(gamma_frozen.ppf(q) - gamma_dist.ppf(q)))
  4.313394796895409e-08
  
  To confirm that the numerical inversion is accurate, we evaluate the
  approximation error (u-error), which should be below 1e-10 (for more
  details, refer to the documentation of `evaluate_error`):
  
  >>> gamma_dist.evaluate_error()
  (7.446320551265581e-11, nan)  # may vary
  
  Note that the location and scale can be changed without instantiating a
  new generator:
  
  >>> gamma_dist.loc = 2
  >>> gamma_dist.scale = 3
  >>> r = gamma_dist.rvs(size=1000)
  
  The mean should be approximately 2 + 3*1.5 = 6.5.
  
  >>> r.mean()
  6.399549295242894  # may vary
  
  Let us also illustrate how truncation can be applied:
  
  >>> trunc_norm = FastGeneratorInversion(stats.norm(), domain=(3, 4))
  >>> r = trunc_norm.rvs(size=1000)
  >>> 3 < r.min() < r.max() < 4
  True
  
  Check the mean:
  
  >>> r.mean()
  3.250433367078603  # may vary
  
  >>> stats.norm.expect(lb=3, ub=4, conditional=True)
  3.260454285589997
  
  In this particular, case, `scipy.stats.truncnorm` could also be used to
  generate truncated normal random variates.
class_docstr_tok: ["Fast","sampling","by","numerical","inversion","of","the","CDF","for","a","large","class","of","continuous","distributions","in","`","scipy.stats","`",".","Parameters","--","--","--","--","--","dist",":","rv_frozen","object","Frozen","distribution","object","from","`","scipy.stats","`",".","The","list","of","supported","distributions","can","be","found","in","the","Notes","section",".","The","shape","parameters",",","`","loc","`","and","`","scale","`","used","to","create","the","distributions","must","be","scalars",".","For","example",",","for","the","Gamma","distribution","with","shape","parameter","`","p","`",",","`","p","`","has","to","be","a","float",",","and","for","the","beta","distribution","with","shape","parameters","(","a",",","b",")",",","both","a","and","b","have","to","be","floats",".","domain",":","tuple","of","floats",",","optional","If","one","wishes","to","sample","from","a","truncated\/conditional","distribution",",","the","domain","has","to","be","specified",".","The","default","is","None",".","In","that","case",",","the","random","variates","are","not","truncated",",","and","the","domain","is","inferred","from","the","support","of","the","distribution",".","ignore_shape_range",":","boolean",",","optional",".","If","False",",","shape","parameters","that","are","outside","of","the","valid","range","of","values","to","ensure","that","the","numerical","accuracy","(","see","Notes",")","is","high",",","raise","a","ValueError",".","If","True",",","any","shape","parameters","that","are","valid","for","the","distribution","are","accepted",".","This","can","be","useful","for","testing",".","The","default","is","False",".","random_state",":","{","None",",","int",",","`","numpy.random.Generator","`",",","`","numpy.random.RandomState","`","}",",","optional","A","NumPy","random","number","generator","or","seed","for","the","underlying","NumPy","random","number","generator","used","to","generate","the","stream","of","uniform","random","numbers",".","If","`","random_state","`","is","None",",","it","uses","``","self.random_state","``",".","If","`","random_state","`","is","an","int",",","``","np.random.default_rng","(","random_state",")","``","is","used",".","If","`","random_state","`","is","already","a","``","Generator","``","or","``","RandomState","``","instance","then","that","instance","is","used",".","Attributes","--","--","--","--","--","loc",":","float","The","location","parameter",".","random_state",":","{","`","numpy.random.Generator","`",",","`","numpy.random.RandomState","`","}","The","random","state","used","in","relevant","methods","like","`","rvs","`","(","unless","another","`","random_state","`","is","passed","as","an","argument","to","these","methods",")",".","scale",":","float","The","scale","parameter",".","Methods","--","--","--","-","cdf","evaluate_error","ppf","qrvs","rvs","support","Notes","--","--","-","The","class","creates","an","object","for","continuous","distributions","specified","by","`","dist","`",".","The","method","`","rvs","`","uses","a","generator","from","`","scipy.stats.sampling","`","that","is","created","when","the","object","is","instantiated",".","In","addition",",","the","methods","`","qrvs","`","and","`","ppf","`","are","added",".","`","qrvs","`","generate","samples","based","on","quasi-random","numbers","from","`","scipy.stats.qmc","`",".","`","ppf","`","is","the","PPF","based","on","the","numerical","inversion","method","in","[","1","]","_","(","`","NumericalInversePolynomial","`",")","that","is","used","to","generate","random","variates",".","Supported","distributions","(","`","distname","`",")","are",":","``","alpha","``",",","``","anglit","``",",","``","argus","``",",","``","beta","``",",","``","betaprime","``",",","``","bradford","``",",","``","burr","``",",","``","burr12","``",",","``","cauchy","``",",","``","chi","``",",","``","chi2","``",",","``","cosine","``",",","``","crystalball","``",",","``","expon","``",",","``","gamma","``",",","``","gennorm","``",",","``","geninvgauss","``",",","``","gumbel_l","``",",","``","gumbel_r","``",",","``","hypsecant","``",",","``","invgamma","``",",","``","invgauss","``",",","``","invweibull","``",",","``","laplace","``",",","``","logistic","``",",","``","maxwell","``",",","``","moyal","``",",","``","norm","``",",","``","pareto","``",",","``","powerlaw","``",",","``","t","``",",","``","rayleigh","``",",","``","semicircular","``",",","``","wald","``",",","``","weibull_max","``",",","``","weibull_min","``",".","`","rvs","`","relies","on","the","accuracy","of","the","numerical","inversion",".","If","very","extreme","shape","parameters","are","used",",","the","numerical","inversion","might","not","work",".","However",",","for","all","implemented","distributions",",","the","admissible","shape","parameters","have","been","tested",",","and","an","error","will","be","raised","if","the","user","supplies","values","outside","of","the","allowed","range",".","The","u-error","should","not","exceed","1e-10","for","all","valid","parameters",".","Note","that","warnings","might","be","raised","even","if","parameters","are","within","the","valid","range","when","the","object","is","instantiated",".","To","check","numerical","accuracy",",","the","method","`","evaluate_error","`","can","be","used",".","Note","that","all","implemented","distributions","are","also","part","of","`","scipy.stats","`",",","and","the","object","created","by","`","FastGeneratorInversion","`","relies","on","methods","like","`","ppf","`",",","`","cdf","`","and","`","pdf","`","from","`","rv_frozen","`",".","The","main","benefit","of","using","this","class","can","be","summarized","as","follows",":","Once","the","generator","to","sample","random","variates","is","created","in","the","setup","step",",","sampling","and","evaluation","of","the","PPF","using","`","ppf","`","are","very","fast",",","and","performance","is","essentially","independent","of","the","distribution",".","Therefore",",","a","substantial","speed-up","can","be","achieved","for","many","distributions","if","large","numbers","of","random","variates","are","required",".","It","is","important","to","know","that","this","fast","sampling","is","achieved","by","inversion","of","the","CDF",".","Thus",",","one","uniform","random","variate","is","transformed","into","a","non-uniform","variate",",","which","is","an","advantage","for","several","simulation","methods",",","e.g.",",","when","the","variance","reduction","methods","of","common","random","variates","or","antithetic","variates","are","be","used","(","[","2","]","_",")",".","In","addition",",","inversion","makes","it","possible","to","-","to","use","a","QMC","generator","from","`","scipy.stats.qmc","`","(","method","`","qrvs","`",")",",","-","to","generate","random","variates","truncated","to","an","interval",".","For","example",",","if","one","aims","to","sample","standard","normal","random","variates","from","the","interval","(","2",",","4",")",",","this","can","be","easily","achieved","by","using","the","parameter","`","domain","`",".","The","location","and","scale","that","are","initially","defined","by","`","dist","`","can","be","reset","without","having","to","rerun","the","setup","step","to","create","the","generator","that","is","used","for","sampling",".","The","relation","of","the","distribution","`","Y","`","with","`","loc","`","and","`","scale","`","to","the","standard","distribution","`","X","`","(","i.e.",",","``","loc=0","``","and","``","scale=1","``",")","is","given","by","``","Y","=","loc","+","scale","*","X","``",".","References","--","--","--","--","--","..","[","1","]","Derflinger",",","Gerhard",",","Wolfgang","H\u00f6rmann",",","and","Josef","Leydold",".","``","Random","variate","generation","by","numerical","inversion","when","only","the","density","is","known",".","''","ACM","Transactions","on","Modeling","and","Computer","Simulation","(","TOMACS",")","20.4","(","2010",")",":","1-25",".","..","[","2","]","H\u00f6rmann",",","Wolfgang",",","Josef","Leydold","and","Gerhard","Derflinger",".","``","Automatic","nonuniform","random","number","generation",".","''","Springer",",","2004",".","Examples","--","--","--","--",">",">",">","import","numpy","as","np",">",">",">","from","scipy","import","stats",">",">",">","from","scipy.stats.sampling","import","FastGeneratorInversion","Let","'s","start","with","a","simple","example","to","illustrate","the","main","features",":",">",">",">","gamma_frozen","=","stats.gamma","(","1.5",")",">",">",">","gamma_dist","=","FastGeneratorInversion","(","gamma_frozen",")",">",">",">","r","=","gamma_dist.rvs","(","size=1000",")","The","mean","should","be","approximately","equal","to","the","shape","parameter","1.5",":",">",">",">","r.mean","(",")","1.52423591130436","#","may","vary","Similarly",",","we","can","draw","a","sample","based","on","quasi-random","numbers",":",">",">",">","r","=","gamma_dist.qrvs","(","size=1000",")",">",">",">","r.mean","(",")","1.4996639255942914","#","may","vary","Compare","the","PPF","against","approximation","`","ppf","`",".",">",">",">","q","=","[","0.001",",","0.2",",","0.5",",","0.8",",","0.999","]",">",">",">","np.max","(","np.abs","(","gamma_frozen.ppf","(","q",")","-","gamma_dist.ppf","(","q",")",")",")","4.313394796895409e-08","To","confirm","that","the","numerical","inversion","is","accurate",",","we","evaluate","the","approximation","error","(","u-error",")",",","which","should","be","below","1e-10","(","for","more","details",",","refer","to","the","documentation","of","`","evaluate_error","`",")",":",">",">",">","gamma_dist.evaluate_error","(",")","(","7.446320551265581e-11",",","nan",")","#","may","vary","Note","that","the","location","and","scale","can","be","changed","without","instantiating","a","new","generator",":",">",">",">","gamma_dist.loc","=","2",">",">",">","gamma_dist.scale","=","3",">",">",">","r","=","gamma_dist.rvs","(","size=1000",")","The","mean","should","be","approximately","2","+","3","*","1.5","=","6.5",".",">",">",">","r.mean","(",")","6.399549295242894","#","may","vary","Let","us","also","illustrate","how","truncation","can","be","applied",":",">",">",">","trunc_norm","=","FastGeneratorInversion","(","stats.norm","(",")",",","domain=","(","3",",","4",")",")",">",">",">","r","=","trunc_norm.rvs","(","size=1000",")",">",">",">","3","<","r.min","(",")","<","r.max","(",")","<","4","True","Check","the","mean",":",">",">",">","r.mean","(",")","3.250433367078603","#","may","vary",">",">",">","stats.norm.expect","(","lb=3",",","ub=4",",","conditional=True",")","3.260454285589997","In","this","particular",",","case",",","`","scipy.stats.truncnorm","`","could","also","be","used","to","generate","truncated","normal","random","variates","."]
docstr: Quasi-random variates of the given distribution.
  
  The `qmc_engine` is used to draw uniform quasi-random variates, and
  these are converted to quasi-random variates of the given distribution
  using inverse transform sampling.
  
  Parameters
  ----------
  size : int, tuple of ints, or None; optional
      Defines shape of random variates array. Default is ``None``.
  d : int or None, optional
      Defines dimension of uniform quasi-random variates to be
      transformed. Default is ``None``.
  qmc_engine : scipy.stats.qmc.QMCEngine(d=1), optional
      Defines the object to use for drawing
      quasi-random variates. Default is ``None``, which uses
      `scipy.stats.qmc.Halton(1)`.
  
  Returns
  -------
  rvs : ndarray or scalar
      Quasi-random variates. See Notes for shape information.
  
  Notes
  -----
  The shape of the output array depends on `size`, `d`, and `qmc_engine`.
  The intent is for the interface to be natural, but the detailed rules
  to achieve this are complicated.
  
  - If `qmc_engine` is ``None``, a `scipy.stats.qmc.Halton` instance is
    created with dimension `d`. If `d` is not provided, ``d=1``.
  - If `qmc_engine` is not ``None`` and `d` is ``None``, `d` is
    determined from the dimension of the `qmc_engine`.
  - If `qmc_engine` is not ``None`` and `d` is not ``None`` but the
    dimensions are inconsistent, a ``ValueError`` is raised.
  - After `d` is determined according to the rules above, the output
    shape is ``tuple_shape + d_shape``, where:
  
        - ``tuple_shape = tuple()`` if `size` is ``None``,
        - ``tuple_shape = (size,)`` if `size` is an ``int``,
        - ``tuple_shape = size`` if `size` is a sequence,
        - ``d_shape = tuple()`` if `d` is ``None`` or `d` is 1, and
        - ``d_shape = (d,)`` if `d` is greater than 1.
  
  The elements of the returned array are part of a low-discrepancy
  sequence. If `d` is 1, this means that none of the samples are truly
  independent. If `d` > 1, each slice ``rvs[..., i]`` will be of a
  quasi-independent sequence; see `scipy.stats.qmc.QMCEngine` for
  details. Note that when `d` > 1, the samples returned are still those
  of the provided univariate distribution, not a multivariate
  generalization of that distribution.
code: def qrvs(self, size=None, d=None, qmc_engine=None):
      """
      Quasi-random variates of the given distribution.
  
      The `qmc_engine` is used to draw uniform quasi-random variates, and
      these are converted to quasi-random variates of the given distribution
      using inverse transform sampling.
  
      Parameters
      ----------
      size : int, tuple of ints, or None; optional
          Defines shape of random variates array. Default is ``None``.
      d : int or None, optional
          Defines dimension of uniform quasi-random variates to be
          transformed. Default is ``None``.
      qmc_engine : scipy.stats.qmc.QMCEngine(d=1), optional
          Defines the object to use for drawing
          quasi-random variates. Default is ``None``, which uses
          `scipy.stats.qmc.Halton(1)`.
  
      Returns
      -------
      rvs : ndarray or scalar
          Quasi-random variates. See Notes for shape information.
  
      Notes
      -----
      The shape of the output array depends on `size`, `d`, and `qmc_engine`.
      The intent is for the interface to be natural, but the detailed rules
      to achieve this are complicated.
  
      - If `qmc_engine` is ``None``, a `scipy.stats.qmc.Halton` instance is
        created with dimension `d`. If `d` is not provided, ``d=1``.
      - If `qmc_engine` is not ``None`` and `d` is ``None``, `d` is
        determined from the dimension of the `qmc_engine`.
      - If `qmc_engine` is not ``None`` and `d` is not ``None`` but the
        dimensions are inconsistent, a ``ValueError`` is raised.
      - After `d` is determined according to the rules above, the output
        shape is ``tuple_shape + d_shape``, where:
  
            - ``tuple_shape = tuple()`` if `size` is ``None``,
            - ``tuple_shape = (size,)`` if `size` is an ``int``,
            - ``tuple_shape = size`` if `size` is a sequence,
            - ``d_shape = tuple()`` if `d` is ``None`` or `d` is 1, and
            - ``d_shape = (d,)`` if `d` is greater than 1.
  
      The elements of the returned array are part of a low-discrepancy
      sequence. If `d` is 1, this means that none of the samples are truly
      independent. If `d` > 1, each slice ``rvs[..., i]`` will be of a
      quasi-independent sequence; see `scipy.stats.qmc.QMCEngine` for
      details. Note that when `d` > 1, the samples returned are still those
      of the provided univariate distribution, not a multivariate
      generalization of that distribution.
  
      """
      qmc_engine, d = _validate_qmc_input(
          qmc_engine, d, self.random_state
      )
      # mainly copied from unuran_wrapper.pyx.templ
      # `rvs` is flexible about whether `size` is an int or tuple, so this
      # should be, too.
      try:
          if size is None:
              tuple_size = (1,)
          else:
              tuple_size = tuple(size)
      except TypeError:
          tuple_size = (size,)
      # we do not use rng.qrvs directly since we need to be
      # able to apply the ppf to 1 - u
      N = 1 if size is None else np.prod(size)
      u = qmc_engine.random(N)
      if self._mirror_uniform:
          u = 1 - u
      qrvs = self._ppf(u)
      if self._rvs_transform is not None:
          qrvs = self._rvs_transform(qrvs, *self._frozendist.args)
      if size is None:
          qrvs = qrvs.squeeze()[()]
      else:
          if d == 1:
              qrvs = qrvs.reshape(tuple_size)
          else:
              qrvs = qrvs.reshape(tuple_size + (d,))
      return self.loc + self.scale * qrvs
  
imports: import math
  import numbers
  import numpy
  from scipy import stats
  from scipy import special
  from ._qmc import check_random_state, Halton, QMCEngine
  from ._unuran.unuran_wrapper import NumericalInversePolynomial
  from scipy._lib._util import check_random_state
label_desc: Use image node_id 12 for calling the FastGeneratorInversion obj's underlying member method code with example usage: obj.qrvs(size, d, qmc_engine) and returns: unknown