class

Binomial

extendsDistribution

Binomial(total_count: Tensor | int = 1, probs: Tensor | float | None = None, logits: Tensor | float | None = None, validate_args: bool | None = None)

source edit

Binomial distribution over the number of successes in n independent trials.

Binomial(total_count=n, probs=p) models the count of successes when each of $n$ i.i.d. Bernoulli trials has success probability $p$ . Parameterisation is via either probs (in $[0, 1]$ ) or logits (the log-odds $\log(p/(1-p)) \in \mathbb{R}$ ); exactly one must be supplied.

Parameters

total_countTensor | int= 1

Number of trials

n \geq 0

. Default is 1 (reduces to Bernoulli).

probsTensor | float | None= None

Success probability

p \in [0, 1]

. Mutually exclusive with logits.

logitsTensor | float | None= None

Log-odds

l = \log(p / (1-p)) \in \mathbb{R}

. Mutually exclusive with probs.

validate_argsbool | None= None

If True, validate parameter constraints at construction time.

Attributes

total_countTensor

Number of trials

n

, broadcast against the probability.

probsTensor

Success probability — stored when given, otherwise derived from logits on access.

logitsTensor

Log-odds — stored when given, otherwise derived from probs on access.

Notes

PMF:

P(X = k) = \binom{n}{k} p^k (1-p)^{n-k}, \quad k \in \{0, 1, \ldots, n\}

Log-PMF via logits (numerically stable form):

\log P(X = k) = \log\binom{n}{k} + k \, l - n \log(1 + e^l)

where $l = \operatorname{logit}(p)$ and the binomial coefficient is evaluated via $\log \Gamma(n+1) - \log\Gamma(k+1) - \log\Gamma(n-k+1)$ .

Moments:

Mean: $E[X] = np$
Variance: $\operatorname{Var}[X] = np(1-p)$

Sampling strategy: for $n \leq 25$ Bernoulli draws are summed exactly along a dedicated axis. For larger $n$ a Normal approximation is used with the result rounded and clamped to $[0, n]$ .

Examples

>>> import lucid
>>> from lucid.distributions import Binomial
>>> dist = Binomial(total_count=10, probs=0.3)
>>> samples = dist.sample((50,))
>>> samples.shape
(50,)
>>> # PMF at k=3
>>> dist.log_prob(lucid.tensor(3.0)).exp()
tensor(0.2668)

Used by 3

Constructors

dunder

init

→None

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

source edit

Initialise a Binomial distribution.

Parameters

total_countTensor | int= 1

Number of trials

n \geq 0

. Default is 1 (reduces to Bernoulli).

probsTensor | float | None= None

Success probability

p \in [0, 1]

. Mutually exclusive with logits.

logitsTensor | float | None= None

Log-odds

l = \log(p / (1-p)) \in \mathbb{R}

. Mutually exclusive with probs.

validate_argsbool | None= None

If True, validate parameter constraints at construction time.

Raises

ValueError

If both or neither of probs and logits are provided.

Properties

prop

mean

→Tensor

mean: Tensor

source edit

Mean of the Binomial distribution: $E[X] = np$ .

Returns

Tensor

Mean values of shape batch_shape.

prop

mode

→Tensor

mode: Tensor

source edit

Mode of the Binomial distribution: $\min(\lfloor (n+1) p \rfloor, n)$ .

prop

support

→Constraint

support: Constraint

source edit

Support of the Binomial distribution: $\{0, 1, \ldots, n\}$ .

Returns

Constraint

integer_interval(0, total_count) — the bound is the total_count tensor, so each batch member is held to its own $n$ .

prop

variance

→Tensor

variance: Tensor

source edit

Variance of the Binomial distribution: $\operatorname{Var}[X] = np(1-p)$ .

Returns

Tensor

Variance values of shape batch_shape.

Instance methods

entropy

→Tensor

entropy()

source edit

Shannon entropy of the Binomial distribution (in nats).

H = -\sum_{k=0}^{n} P(X = k) \log P(X = k)

summed over the whole support, as the reference framework sums it.

Returns

Tensor

Entropy in nats, shape batch_shape.

Raises

NotImplementedError

If total_count differs across the batch: the support is enumerated once, for one

n

, as in the reference.

Examples

>>> Binomial(total_count=2, probs=0.5).entropy()  # 1.5 ln 2
tensor(1.04)

enumerate_support

→Tensor

enumerate_support(expand: bool = True)

source edit

The counts $0, \ldots, n$ along axis 0, when total_count is homogeneous across the batch.

log_prob

→Tensor

log_prob(value: Tensor)

source edit

Log-probability of the given counts under the Binomial distribution.

Computed via logits for numerical stability:

\log P(X = k) = \log\binom{n}{k} + k \, l - n \log(1 + e^l)

where $l = \operatorname{logit}(p)$ and the binomial coefficient is evaluated via $\log\Gamma$ .

Parameters

valueTensor

Count values

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

Returns

Tensor

Log-probability values of the same shape as value.

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. log_prob does not use this attribute: it keeps the exact, possibly infinite, log-odds that its degenerate-probability guards are written around.

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 Binomial distribution.

Uses an exact strategy for small $n$ (sum of Bernoulli draws) and a Normal approximation with rounding for large $n$ .

Parameters

sample_shapetuple[int, ...]= ()

Leading shape of the output sample batch.

Returns

Tensor

Non-negative integer samples in $\{0, 1, \ldots, n\}$ , shape (*sample_shape, *batch_shape).

>>> import lucid >>> from lucid.distributions import Binomial >>> dist = Binomial(total_count=10, probs=0.3) >>> samples = dist.sample((50,)) >>> samples.shape (50,) >>> # PMF at k=3 >>> dist.log_prob(lucid.tensor(3.0)).exp() tensor(0.2668)

dunder

init

→None

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

source edit

Initialise a Binomial distribution.

Parameters

total_countTensor | int= 1

Number of trials

n \geq 0

. Default is 1 (reduces to Bernoulli).

probsTensor | float | None= None

Success probability

p \in [0, 1]

. Mutually exclusive with logits.

logitsTensor | float | None= None

Log-odds

l = \log(p / (1-p)) \in \mathbb{R}

. Mutually exclusive with probs.

validate_argsbool | None= None

If True, validate parameter constraints at construction time.

Raises

ValueError

If both or neither of probs and logits are provided.