class

Geometric

extendsDistribution

Geometric(probs: Tensor | float | None = None, logits: Tensor | float | None = None, validate_args: bool | None = None)

source edit

Geometric distribution: number of failures before the first success.

Models the number of failed Bernoulli trials $X \in \{0, 1, 2, \ldots\}$ preceding the first success in an unbounded sequence of independent trials with success probability $p$ . This is the shifted convention (counting failures); the alternative convention counts trials including the success and starts at $1$ .

Parameters

probsTensor or float= None

Success probability

p \in (0, 1]

per trial. Mutually exclusive with logits.

logitsTensor or float= None

Log-odds

\ell = \log(p/(1-p))

; probs is then derived from it on access. Mutually exclusive with probs.

validate_argsbool= None

If True, validate parameter constraints at construction time.

Notes

Probability mass function:

P(X = k \mid p) = p (1 - p)^k, \quad k = 0, 1, 2, \ldots

Moments:

\mathbb{E}[X] = \frac{1 - p}{p}, \qquad \mathrm{Var}[X] = \frac{1 - p}{p^2}

Memoryless property — the Geometric is the only discrete distribution with the memoryless property:

P(X \geq m + n \mid X \geq m) = P(X \geq n)

Continuous analogue: lucid.distributions.Exponential (the only continuous memoryless distribution).

The expected number of trials (including the success) is $1/p$ ; entropy grows without bound as $p \to 0$ and is zero at $p = 1$ .

Examples

>>> import lucid
>>> from lucid.distributions import Geometric
>>> d = Geometric(probs=0.25)
>>> d.mean  # (1 - p)/p = 3.0
tensor(3.)
>>> d.sample((4,)).shape
(4,)
>>> d.log_prob(lucid.tensor(2.0))  # 2 log(0.75) + log(0.25)
tensor(-1.962)

Used by 2

Constructors

dunder

init

→None

__init__(probs: Tensor | float | None = None, logits: Tensor | float | None = None, validate_args: bool | None = None)

source edit

Construct a Geometric distribution.

Exactly one of probs or logits must be provided. The one given is stored; the other is derived from it on access.

Parameters

probsTensor | float | None= None

Success probability

p \in (0, 1]

of a single Bernoulli trial. Mutually exclusive with logits.

logitsTensor | float | None= None

Log-odds

\ell = \log(p / (1-p))

. Mutually exclusive with probs.

validate_argsbool | None= None

If True, validate parameter constraints at construction time.

Raises

ValueError

If both or neither of probs / logits are provided.

Notes

The support is $\{0, 1, 2, \ldots\}$ representing the number of failures before the first success. The PMF is:

P(X = k) = (1 - p)^k \, p, \quad k = 0, 1, 2, \ldots

Examples

>>> from lucid.distributions import Geometric
>>> d = Geometric(probs=0.25)
>>> d.mean  # E[X] = (1-p)/p = 3
tensor(3.)

Properties

prop

mean

→Tensor

mean: Tensor

source edit

Expected number of failures before the first success.

E[X] = \frac{1 - p}{p}

Returns

Tensor

Mean $(1-p)/p$ , shape batch_shape.

Examples

>>> Geometric(probs=0.5).mean
tensor(1.)

prop

mode

→Tensor

mode: Tensor

source edit

Mode of the Geometric distribution: 0 failures, for every p.

$P(X = k) = (1 - p)^k p$ decreases in $k$ .

prop

variance

→Tensor

variance: Tensor

source edit

Variance of the number of failures before the first success.

\operatorname{Var}[X] = \frac{1 - p}{p^2}

Returns

Tensor

Variance $(1-p)/p^2$ , shape batch_shape.

Examples

>>> Geometric(probs=0.5).variance
tensor(2.)

Instance methods

entropy

→Tensor

entropy()

source edit

Shannon entropy of the Geometric distribution (in nats).

H(X) = \frac{-(1-p)\log(1-p) - p \log p}{p} = \frac{\operatorname{softplus}(\ell) - p\,\ell}{p}

The numerator is the Bernoulli entropy, evaluated in its logits form so that $p = 1$ gives (almost exactly) 0 rather than 0 · log 0 = NaN.

The entropy grows without bound as $p \to 0$ (more uncertainty over many possible outcomes) and is zero at $p = 1$ (certain success on first trial).

Returns

Tensor

Entropy in nats, shape batch_shape.

Examples

>>> Geometric(probs=0.5).entropy()  # 2 log(2)
tensor(1.386)

log_prob

→Tensor

log_prob(value: Tensor)

source edit

Log-probability of value under the Geometric distribution.

\log P(X = k) = k \log(1-p) + \log p

with $k \log(1-p)$ taken as 0 at $k = 0$ , so $p = 1$ scores its only outcome as $\log 1 = 0$ rather than 0 · (-inf) = NaN.

Parameters

valueTensor

Non-negative integer outcomes

k \in \{0, 1, 2, \ldots\}

Returns

Tensor

Element-wise log-probabilities, shape batch_shape.

Examples

>>> d = Geometric(probs=0.5)
>>> d.log_prob(lucid.tensor(0.0))  # log(0.5) ≈ -0.693
tensor(-0.6931)

logits

→Tensor

logits()

source edit

Log-odds $\log(p/(1-p))$ — as given, or derived on access.

Derived from probs clamped one epsilon inside $[0, 1]$ , as the reference framework derives it.

probs

→Tensor

probs()

source edit

Success probability — as given, or sigmoid(logits) on access.

sample

→Tensor

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

source edit

Draw samples from the Geometric distribution.

Uses the inverse-CDF trick: if $U \sim \text{Uniform}(0, 1)$ ,

X = \left\lfloor \frac{\log U}{\log(1 - p)} \right\rfloor

A small epsilon clamp guards against $U = 0$ which would produce $-\infty$ . The returned tensor is detached since the Geometric is discrete.

Parameters

sample_shapetuple[int, ...]= ()

Leading shape dimensions for the sample batch. The full output shape is sample_shape + batch_shape. Default is ().

Returns

Tensor

Non-negative integer samples of shape sample_shape + batch_shape.

Examples

>>> lucid.manual_seed(0)
>>> d = Geometric(probs=0.5)
>>> x = d.sample((1000,))
>>> x.shape
(1000,)
>>> bool((x.mean() - 1.0).abs() < 0.2)  # the sample mean approaches (1-p)/p
True

>>> import lucid >>> from lucid.distributions import Geometric >>> d = Geometric(probs=0.25) >>> d.mean # (1 - p)/p = 3.0 tensor(3.) >>> d.sample((4,)).shape (4,) >>> d.log_prob(lucid.tensor(2.0)) # 2 log(0.75) + log(0.25) tensor(-1.962)

dunder

init

→None

__init__(probs: Tensor | float | None = None, logits: Tensor | float | None = None, validate_args: bool | None = None)

source edit

Construct a Geometric distribution.

Exactly one of probs or logits must be provided. The one given is stored; the other is derived from it on access.

Parameters

probsTensor | float | None= None

Success probability

p \in (0, 1]

of a single Bernoulli trial. Mutually exclusive with logits.

logitsTensor | float | None= None

Log-odds

\ell = \log(p / (1-p))

. Mutually exclusive with probs.

validate_argsbool | None= None

If True, validate parameter constraints at construction time.

Raises

ValueError

If both or neither of probs / logits are provided.

Notes

The support is $\{0, 1, 2, \ldots\}$ representing the number of failures before the first success. The PMF is:

P(X = k) = (1 - p)^k \, p, \quad k = 0, 1, 2, \ldots

Examples

>>> from lucid.distributions import Geometric
>>> d = Geometric(probs=0.25)
>>> d.mean  # E[X] = (1-p)/p = 3
tensor(3.)