Metadata-Version: 2.1
Name: qilum
Version: 1.0.0
Summary: Statistical supplementary package to numpy, scipy, ...
Home-page: https://www.qilum.com/
Author: Damien Loison
Author-email: loison.damien@gmail.com
License: UNKNOWN
Description: Qilum is a statistical and utility library supplementing existing statistical libraries 
        including numpy [1] and scipy [2]. 
        We use numba library [3] to speed up some calculations.
        
        In this first version, we provide several random number generators. They are based on the 
        C++ LOPOR library [4] 
        and the article Canonical local algorithms for spin systems: heat bath 
        and Hasting methods [5].
        We respect the scipy.stats random number generator interface and any of the scipy.stats classes can be used to initialize qilum classes. 
        
        The main classes are:
         
        * **Dist_reject**. Construct an exact generator for any probability functions. This is the fastest method when you do not know how to calculate or inverse the cumulative [5].
        
        * **Dist_sum**. Construct a sum of known distributions  
        
        * **Dist_scale**. Apply scaling for x and y, for any distributions, even negative scaling for x 
        
        * **Dist_cubicSpline**. Create an approximate random number generator for any functions using cubic spline. If you need an exact random number generator, use Dist_reject. The *Dist_cubicSpline* can be used instead of *scipy.stats.rv_histogram*, if you need a smooth function
        
        * **Dist_walker**. Create a very fast random number generator for discrete distributions.  
        
        * In addition, we expose the function **f_walker** which calculates the parameters of the Walker algorithm [6]
        
        The most up-to-date Qilum documentation can be found at https://www.qilum.com
        
        The source code can be found at https://bitbucket.org/daminou_fr/qilum
        
        
        * Example: Discrete Walker distribution Dist_walker
        
        ~~~~
        # Define a discrete distribution with Walker algorithm 
        import qilum.stats as qs
        walker = qs.Dist_walker(probabilities=[0.2, 0.5, 0.3], values=[0, 10, 2])
        # and call the random number generator
        rans = walker.rvs(size=100000)
        ~~~~
        
        * Example: Sum of distributions Dist_sum
        
        ~~~~
        # exponential distributions left and right types
        exp_left  = qs.Dist_scale(scipy.stats.expon(),loc_x=-1.000001, scale_x=-1, scale_y=2, name='Exp+')
        exp_right = qs.Dist_scale(scipy.stats.expon(),loc_x= -1, scale_x= 1, scale_y=2, name='Exp-')
        # sum of the distributions
        dist_sum = qs.Dist_sum([exp_left, exp_right]); 
        # random numbers
        rans = dist_sum.rvs(100)
        ~~~~
        
        * Example: Rejection method distribution Dist_reject
        
        ~~~~
        # generate a random generator for f_f(x)     
        def f_f(xs): return np.where((xs<-5) | (xs>5), 0, 3.*np.exp(-np.power(xs,4)/10.))
        # find a step function above f_f(x)
        xs = np.linspace(-6,6, 1001)
        ys = f_f(xs)
        xs_step, ys_step = qs.f_max(xs, ys, 20)    
        ys_step *= 1.2 # just to be sure that our step function >= f_f() 
        # create a distribution for this step function:
        hist_dist = scipy.stats.rv_histogram((ys_step, xs_step))
        # scale this diribution
        cumulative = qs.f_cumulative(xs_step, ys_step)[-1]
        dist_step = qs.Dist_scale(hist_dist, scale_y = cumulative, name='dist_step')
        # create dist_reject 
        dist_reject = qs.Dist_reject(dist_step, f_f)
        # random numbers
        rans = dist_reject.rvs(100)
        ~~~~
        
        
        References:
        
        [1] numpy:  https://numpy.org
        
        [2] scipy https://www.scipy.org/
        
        [3] numba http://numba.pydata.org
        
        [4] C++ LOPOR library: http://www.damienloison.com/finance/LOPOR/index.html 
        
        [5] Canonical local algorithms for spin systems: heat bath 
        and Hasting methods: http://www.damienloison.com/articles/reference26.pdf
        
        [6] A.J. Walker, ACM Transaction on Mathematical Software 3 (1977) 253
        
        
Keywords: statistic random number generator scipy
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
