class

Gumbel

extendsDistribution

Gumbel(loc: Tensor | float, scale: Tensor | float, validate_args: bool | None = None)

source edit

Gumbel (Type-I extreme value) distribution on $\mathbb{R}$ .

Continuous distribution that models the maximum (or minimum) of a sample drawn from a number of distributions with exponential-like tails. It is the limiting distribution of the maximum of IID exponential-tailed variables (Fisher–Tippett–Gnedenko theorem) and is the basis of the celebrated Gumbel-max trick for differentiable sampling from categorical distributions.

Parameters

locTensor or float

Location parameter

\mu \in \mathbb{R}

(mode of the density).

scaleTensor or float

Scale parameter

s > 0

validate_argsbool= None

If True, validate parameter constraints at construction time.

Notes

Probability density (with $z = (x - \mu)/s$ ):

p(x; \mu, s) = \frac{1}{s} \exp\!\bigl(-(z + e^{-z})\bigr)

Cumulative distribution:

F(x; \mu, s) = \exp\!\bigl(-e^{-z}\bigr)

Moments:

\mathbb{E}[X] = \mu + s\,\gamma_{\mathrm{E}}, \qquad \mathrm{Var}[X] = \frac{\pi^2 s^2}{6}

where $\gamma_{\mathrm{E}} \approx 0.5772$ is the Euler–Mascheroni constant. The mode is $\mu$ and the entropy is $\log s + \gamma_{\mathrm{E}} + 1$ .

Gumbel-softmax trick: if $g_i \sim \mathrm{Gumbel}(0, 1)$ IID and $\pi_i$ are category probabilities, then $\arg\max_i (\log \pi_i + g_i)$ is a sample from $\mathrm{Categorical}(\pi)$ . Replacing the argmax with a softmax yields a continuous relaxation that supports gradient flow through discrete choices (Jang et al., 2017; Maddison et al., 2017).

Examples

>>> import lucid
>>> from lucid.distributions import Gumbel
>>> d = Gumbel(loc=0.0, scale=1.0)
>>> d.rsample((4,)).shape
(4,)
>>> d.log_prob(lucid.tensor(0.0))  # -(0 + e^0)
tensor(-1.)

Used by 3

Constructors

dunder

init

→None

__init__(loc: Tensor | float, scale: Tensor | float, validate_args: bool | None = None)

source edit

Initialise a Gumbel distribution.

Parameters

locTensor | float

Location parameter

\mu \in \mathbb{R}

. Shifts the distribution along the real line.

scaleTensor | float

Scale parameter

s > 0

. Stretches the distribution.

validate_argsbool | None= None

If True, validate parameter constraints at construction time.

Properties

prop

mean

→Tensor

mean: Tensor

source edit

μ + s · γ where γ is the Euler–Mascheroni constant.

prop

mode

→Tensor

mode: Tensor

source edit

Mode of the Gumbel distribution.

Returns

Tensor

The location parameter $\mu$ , which coincides with the mode of the Gumbel PDF.

prop

variance

→Tensor

variance: Tensor

source edit

(π · s)² / 6.

Instance methods

cdf

→Tensor

cdf(value: Tensor)

source edit

Cumulative distribution function of the Gumbel distribution.

F(x) = \exp\!\left(-e^{-(x - \mu)/s}\right)

Returns probabilities in $[0, 1]$ .

Examples

>>> Gumbel(loc=0.0, scale=1.0).cdf(lucid.tensor(0.0))  # 1/e
tensor(0.3679)

entropy

→Tensor

entropy()

source edit

log(s) + γ + 1.

icdf

→Tensor

icdf(value: Tensor)

source edit

Quantile function of the Gumbel distribution.

Q(p) = \mu - s \ln(-\ln u), \qquad u = \epsilon_{\text{tiny}} + p\,(1 - \epsilon - \epsilon_{\text{tiny}})

The reference framework builds the Gumbel from a uniform on $[\epsilon_{\text{tiny}}, 1 - \epsilon]$ (the dtype's smallest normal number and machine epsilon) so that no draw is infinite, and its quantile function maps $[0, 1]$ onto that interval first. This does the same: the quantiles at 0 and 1 are finite — $\mu - 4.47 s$ and $\mu + 15.9 s$ in float32 — and every other one differs from the exact $\mu - s\ln(-\ln p)$ by a relative $\epsilon$ .

Returns quantiles.

Examples

>>> Gumbel(loc=0.0, scale=1.0).icdf(lucid.tensor(0.5))  # -ln(ln 2)
tensor(0.3665)

log_prob

→Tensor

log_prob(value: Tensor)

source edit

Log-probability density of the Gumbel distribution.

Parameters

valueTensor

Point(s)

x \in \mathbb{R}

at which to evaluate the density.

Returns

Tensor

Log-density $\log p(x) = -(z + e^{-z}) - \log s$ where $z = (x - \mu) / s$ .

rsample

→Tensor

rsample(sample_shape: tuple[int, ...] = ())

source edit

Reparameterised sample via the Gumbel icdf: μ − s · log(−log U).

class

Gumbel

extendsDistribution

Gumbel(loc: Tensor | float, scale: Tensor | float, validate_args: bool | None = None)

source edit

Gumbel (Type-I extreme value) distribution on $\mathbb{R}$ .

Parameters

locTensor or float

Location parameter

\mu \in \mathbb{R}

(mode of the density).

scaleTensor or float

Scale parameter

s > 0

validate_argsbool= None

If True, validate parameter constraints at construction time.

Notes

Probability density (with $z = (x - \mu)/s$ ):

p(x; \mu, s) = \frac{1}{s} \exp\!\bigl(-(z + e^{-z})\bigr)

Cumulative distribution:

F(x; \mu, s) = \exp\!\bigl(-e^{-z}\bigr)

Moments:

\mathbb{E}[X] = \mu + s\,\gamma_{\mathrm{E}}, \qquad \mathrm{Var}[X] = \frac{\pi^2 s^2}{6}

where $\gamma_{\mathrm{E}} \approx 0.5772$ is the Euler–Mascheroni constant. The mode is $\mu$ and the entropy is $\log s + \gamma_{\mathrm{E}} + 1$ .

Examples

>>> import lucid
>>> from lucid.distributions import Gumbel
>>> d = Gumbel(loc=0.0, scale=1.0)
>>> d.rsample((4,)).shape
(4,)
>>> d.log_prob(lucid.tensor(0.0))  # -(0 + e^0)
tensor(-1.)

Used by 3

Constructors

dunder

init

→None

__init__(loc: Tensor | float, scale: Tensor | float, validate_args: bool | None = None)

source edit

Initialise a Gumbel distribution.

Parameters

locTensor | float

Location parameter

\mu \in \mathbb{R}

. Shifts the distribution along the real line.

scaleTensor | float

Scale parameter

s > 0

. Stretches the distribution.

validate_argsbool | None= None

If True, validate parameter constraints at construction time.

Properties

prop

mean

→Tensor

mean: Tensor

source edit

μ + s · γ where γ is the Euler–Mascheroni constant.

prop

mode

→Tensor

mode: Tensor

source edit

Mode of the Gumbel distribution.

Returns

Tensor

The location parameter $\mu$ , which coincides with the mode of the Gumbel PDF.

prop

variance

→Tensor

variance: Tensor

source edit

(π · s)² / 6.

Instance methods

cdf

→Tensor

cdf(value: Tensor)

source edit

Cumulative distribution function of the Gumbel distribution.

F(x) = \exp\!\left(-e^{-(x - \mu)/s}\right)

Returns probabilities in $[0, 1]$ .

Examples

>>> Gumbel(loc=0.0, scale=1.0).cdf(lucid.tensor(0.0))  # 1/e
tensor(0.3679)

entropy

→Tensor

entropy()

source edit

log(s) + γ + 1.

icdf

→Tensor

icdf(value: Tensor)

source edit

Quantile function of the Gumbel distribution.

Q(p) = \mu - s \ln(-\ln u), \qquad u = \epsilon_{\text{tiny}} + p\,(1 - \epsilon - \epsilon_{\text{tiny}})

Returns quantiles.

Examples

>>> Gumbel(loc=0.0, scale=1.0).icdf(lucid.tensor(0.5))  # -ln(ln 2)
tensor(0.3665)

log_prob

→Tensor

log_prob(value: Tensor)

source edit

Log-probability density of the Gumbel distribution.

Parameters

valueTensor

Point(s)

x \in \mathbb{R}

at which to evaluate the density.

Returns

Tensor

Log-density $\log p(x) = -(z + e^{-z}) - \log s$ where $z = (x - \mu) / s$ .

rsample

→Tensor

rsample(sample_shape: tuple[int, ...] = ())

source edit

Reparameterised sample via the Gumbel icdf: μ − s · log(−log U).