class

Geometric

extendsDistribution

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

source

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))

. Converted to probs via the sigmoid at construction. 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.0)
>>> d.sample((4,))
Tensor([...])
>>> d.log_prob(lucid.tensor(2.0))
Tensor(...)

Methods (6)

dunder

init

→None

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

source

Construct a Geometric distribution.

Exactly one of probs or logits must be provided. If logits is given, it is converted to probs via the sigmoid transform and stored as self.probs.

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))

. Converted to probs at construction time. 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.0)

prop

mean

→Tensor

mean: Tensor

source

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.0)

prop

variance

→Tensor

variance: Tensor

source

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.0)

sample

→Tensor

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

source

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

>>> d = Geometric(probs=0.5)
>>> x = d.sample((1000,))
>>> x.mean()  # approximately 1.0

log_prob

→Tensor

log_prob(value: Tensor)

source

Log-probability of value under the Geometric distribution.

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

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)

entropy

→Tensor

entropy()

source

Shannon entropy of the Geometric distribution (in nats).

H(X) = \frac{-(1-p)\log(1-p) - p \log p}{p}

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()
Tensor(1.3863)