Lucid3.0
class

Gamma

extendsExponentialFamily
Gamma(concentration: Tensor | float, rate: Tensor | float, validate_args: bool | None = None)
source

Gamma distribution on (0,∞)(0, \infty) — shape/rate parameterisation.

Two-parameter continuous distribution that generalises the lucid.distributions.Exponential (shape α=1\alpha = 1) and lucid.distributions.Chi2 (shape k/2k/2, rate 1/21/2). Widely used as the conjugate prior for the rate parameter of a Poisson likelihood and for positive-valued measurements such as waiting times, life-times, and rainfall amounts.

Parameters

concentrationTensor or float
Shape (concentration) parameter α>0\alpha > 0. Sometimes called kk. When α\alpha is a positive integer the Gamma equals the Erlang distribution (sum of α\alpha IID Exponentials).
rateTensor or float
Rate (inverse-scale) parameter β>0\beta > 0. Equivalent scale parameterisation: θ=1/β\theta = 1/\beta.
validate_argsbool= None
If True, validate parameter constraints at construction time.

Notes

Probability density on x>0x > 0:

p(x;α,β)=βαΓ(α)xα−1e−βxp(x; \alpha, \beta) = \frac{\beta^\alpha}{\Gamma(\alpha)} x^{\alpha - 1} e^{-\beta x}

Moments:

E[X]=αβ,Var[X]=αβ2,Mode=max⁡(α−1,0)β\mathbb{E}[X] = \frac{\alpha}{\beta}, \qquad \mathrm{Var}[X] = \frac{\alpha}{\beta^2}, \qquad \mathrm{Mode} = \frac{\max(\alpha - 1, 0)}{\beta}

Entropy:

H[X]=α−log⁡β+log⁡Γ(α)+(1−α)ψ(α)H[X] = \alpha - \log \beta + \log \Gamma(\alpha) + (1 - \alpha)\psi(\alpha)

where ψ\psi is the digamma function.

Special cases and relations:

  • Gamma(1,β)=Exponential(β)\mathrm{Gamma}(1, \beta) = \mathrm{Exponential}(\beta)
  • Gamma(k/2,1/2)=χ2(k)\mathrm{Gamma}(k/2, 1/2) = \chi^2(k)
  • Sum of independent Gammas with the same rate adds shapes: Gamma(α1,β)+Gamma(α2,β)=Gamma(α1+α2,β)\mathrm{Gamma}(\alpha_1, \beta) + \mathrm{Gamma}(\alpha_2, \beta) = \mathrm{Gamma}(\alpha_1 + \alpha_2, \beta).
  • The ratio Gα/(Gα+Gβ)G_\alpha/(G_\alpha + G_\beta) is Beta(α,β)\mathrm{Beta}(\alpha, \beta).

Sampling uses Marsaglia–Tsang acceptance-rejection — accept rate is consistently above 95 %, so eight retry rounds are more than enough. Because the kernel is rejection-based, has_rsample = False and samples are detached.

Examples

>>> import lucid
>>> from lucid.distributions import Gamma
>>> d = Gamma(concentration=2.0, rate=1.0)
>>> d.mean  # α/β
Tensor(2.0)
>>> d.sample((4,))
Tensor([...])
>>> d.log_prob(lucid.tensor(1.5))
Tensor(...)

Methods (7)

dunder

__init__

→None
__init__(concentration: Tensor | float, rate: Tensor | float, validate_args: bool | None = None)
source

Construct a Gamma distribution.

Parameters

concentrationTensor | float
Shape (concentration) parameter α>0\alpha > 0. Also known as the shape parameter kk.
rateTensor | float
Rate (inverse-scale) parameter β>0\beta > 0. The scale is θ=1/β\theta = 1/\beta.
validate_argsbool | None= None
If True, validate parameter constraints at construction time.

Notes

The Gamma distribution has PDF:

p(x;α,β)=βαΓ(α)xα−1e−βx,x>0p(x; \alpha, \beta) = \frac{\beta^\alpha}{\Gamma(\alpha)} x^{\alpha-1} e^{-\beta x}, \quad x > 0

Special cases include:

  • Gamma(1,β)=Exponential(β)\text{Gamma}(1, \beta) = \text{Exponential}(\beta)
  • Gamma(k/2,1/2)=χ2(k)\text{Gamma}(k/2, 1/2) = \chi^2(k)

Sampling uses the Marsaglia–Tsang acceptance-rejection algorithm (see module docstring); the accept rate is > 95 % so eight retry rounds are more than sufficient.

Examples

>>> from lucid.distributions import Gamma
>>> d = Gamma(concentration=2.0, rate=1.0)
>>> d.mean  # α/β = 2.0
Tensor(2.0)
prop

mean

→Tensor
mean: Tensor
source

Expected value of the Gamma distribution.

E[X]=αβE[X] = \frac{\alpha}{\beta}

Returns

Tensor

Mean α/β\alpha/\beta, shape batch_shape.

Examples

>>> Gamma(concentration=3.0, rate=2.0).mean
Tensor(1.5)
prop

mode

→Tensor
mode: Tensor
source

Mode of the Gamma distribution.

mode=max⁡(α−1,  0)β\text{mode} = \frac{\max(\alpha - 1,\; 0)}{\beta}

The mode is zero for α≤1\alpha \leq 1 (the density is monotonically decreasing from infinity) and positive for α>1\alpha > 1.

Returns

Tensor

Mode max⁡(α−1,0)/β\max(\alpha-1, 0)/\beta, shape batch_shape.

Examples

>>> Gamma(concentration=3.0, rate=1.0).mode
Tensor(2.0)
prop

variance

→Tensor
variance: Tensor
source

Variance of the Gamma distribution.

Var⁡[X]=αβ2\operatorname{Var}[X] = \frac{\alpha}{\beta^2}

Returns

Tensor

Variance α/β2\alpha/\beta^2, shape batch_shape.

Examples

>>> Gamma(concentration=4.0, rate=2.0).variance
Tensor(1.0)
fn

sample

→Tensor
sample(sample_shape: tuple[int, ...] = ())
source

Draw samples from the Gamma distribution.

Delegates to _sample_standard_gamma (Marsaglia–Tsang algorithm) and scales by 1/β1/\beta to obtain Gamma(α,β)\text{Gamma}(\alpha, \beta) samples. The result is detached since the rejection-based sampler does not support reparameterisation.

Parameters

sample_shapetuple[int, ...]= ()
Leading shape dimensions for the sample batch. Default is ().

Returns

Tensor

Non-negative samples of shape sample_shape + batch_shape.

Examples

>>> d = Gamma(concentration=2.0, rate=1.0)
>>> x = d.sample((500,))
>>> x.mean()  # approximately 2.0
fn

log_prob

→Tensor
log_prob(value: Tensor)
source

Log-density of value under the Gamma distribution.

log⁡p(x;α,β)=αlog⁡β+(α−1)log⁡x−βx−log⁡Γ(α)\log p(x; \alpha, \beta) = \alpha \log \beta + (\alpha - 1) \log x - \beta x - \log \Gamma(\alpha)

Parameters

valueTensor
Positive real values x>0x > 0.

Returns

Tensor

Element-wise log-densities, shape batch_shape.

Examples

>>> Gamma(concentration=1.0, rate=1.0).log_prob(lucid.tensor(1.0))
Tensor(-1.0)
fn

entropy

→Tensor
entropy()
source

Shannon entropy of the Gamma distribution (in nats).

H(X)=α−log⁡β+log⁡Γ(α)+(1−α)ψ(α)H(X) = \alpha - \log \beta + \log \Gamma(\alpha) + (1 - \alpha) \psi(\alpha)

where ψ\psi is the digamma function.

Returns

Tensor

Entropy in nats, shape batch_shape.

Examples

>>> Gamma(concentration=1.0, rate=1.0).entropy()  # Exp(1): H = 1
Tensor(1.0)