qdflow.util.distribution

This module contains classes defining random vairable distributions.

Single variable distributions inherit from Distribution and define a draw() method. This method takes a numpy random generator and uses it to draw one or more random values from the distribution.

Examples

>>> from qdflow.util import distribution
>>> import numpy as np
>>> rng = np.random.default_rng()

>>> mean, stdev = 5, 2
>>> normal_dist = distribution.Normal(mean, stdev)
>>> normal_dist.draw(rng)
5.137    # random

Multiple values can be drawn at once via the size parameter:

>>> normal_dist.draw(rng, size=(2,3))
array([[3.825, 6.440, 4.821],
       [2.739, 5.512, 7.807]])    # random

Distributions can be combined together with each other, as well as with scalars via arithmatic operators +, -, *, and /.

>>> dist_1 = distribution.Uniform(1,5)
>>> dist_2 = distribution.Uniform(3,7)
>>> combined_dist = 2 * dist_1 - dist_2
>>> combined_dist.draw(rng, size=4)
array([-2.311, 1.339, 4.067, 0.713])    # random

This module also provides a framework for multivariable distributions, via the class CorrelatedDistribution. After defining a correlated distribution, a set of linked, dependent, single-variable distributions can be obtained with the dependent_distributions() function. Drawing from each of these distributions yields a set of random, correlated values.

>>> normal_dist = distribution.Normal(5, 2)
>>> matrix = np.array([[-1], [2]])
>>> correlated_dist = distribution.MatrixCorrelated(matrix, [normal_dist])
>>> dist_1, dist_2 = correlated_dist.dependent_distributions()
>>> result_1 = dist_1.draw(rng, size=3)
>>> result_1
array([-5.813, -1.782, -6.021])    # random

>>> result_2 = dist_2.draw(rng, size=3)
>>> result_2
array([11.626, 3.564, 12.042])    # NOT random, correlated with result_1

result_1 and result_2 are random, but dependent on each other.

>>> result_2 / -2
array([-5.813, -1.782, -6.021])    # equal to result_1

Classes

AbsDistribution(dist)

A distribution defined by the absolute value of the value drawn from another distribution.

Binary(p, success, fail)

A binary (Bernoulli) distribution, which returns success with probability p, and fail otherwise.

CorrelatedDistribution()

An abstract class which defines a random distribution in multiple, correlated variables.

Delta(value)

A delta-function distribution which always returns value.

DifferenceDistribution(dist_1, dist_2)

A distribution defined by the difference of the values drawn from two other distributions.

Discrete(a[, b])

A uniform discrete distribution, which returns a value between min (inclusive) and max (exclusive).

Distribution()

An abstract class which defines a random distribution.

FullyCorrelated(dist, n)

A CorrelatedDistribution which returns n copies of the value drawn from a Distribution.

LogNormal(mu, sigma)

A log-normal distribution defined by mu and sigma.

LogUniform(min, max)

A log-uniform (reciprocal) distribution between min and max.

MatrixCorrelated(matrix, distributions)

A CorrelatedDistribution which draws values from one or more distributions, then returns variables given by linear combinatons of those values.

NegationDistribution(dist)

A distribution defined by the negation of the value drawn from another distribution.

Normal(mean, stdev)

A normal distribution with the specified mean and standard deviation.

ProductDistribution(dist_1, dist_2)

A distribution defined by the product of the values drawn from two other distributions.

QuotientDistribution(dist_1, dist_2)

A distribution defined by the quotient of the values drawn from two other distributions.

SphericallyCorrelated(n[, radius])

A CorrelatedDistribution which returns n variables drawn uniformly from the surface of an n-dimensional hypershphere with the given radius (or radius drawn from the given Distribution).

SumDistribution(dist_1, dist_2)

A distribution defined by the sum of the values drawn from two other distributions.

Uniform(min, max)

A uniform distribution with range [min, max).

Exceptions

DependentDistributionWarning

A warning raised when CorrelatedDistribution.DependentDistribution.draw() is called unexpectedly.