Categorical
DistributionCategorical(probs: Tensor | None = None, logits: Tensor | None = None, validate_args: bool | None = None)Categorical distribution — a discrete distribution over K labelled outcomes.
Categorical(probs=p) or Categorical(logits=l) defines a distribution
over the integer set where is the
number of categories. Exactly one of probs or logits must be given.
Parameters
(..., K). Rows are automatically normalised to sum to 1.
Mutually exclusive with logits.(..., K).
The distribution uses internally to convert to
normalised probabilities. Mutually exclusive with probs.validate_argsbool | None= NoneTrue, validate parameter constraints at construction time.Attributes
Notes
PMF:
Parameterisations are related by:
Entropy:
Mean is not well-defined for a general Categorical (the labels have no
canonical metric), so mean returns a NaN tensor of the batch shape.
Sampling uses the Gumbel-max trick: add i.i.d. noise to the log-probabilities and take the argmax. This is equivalent to ancestral sampling and avoids cumulative-sum + binary-search.
The batch dimensions of the input correspond to independent distributions.
For example, probs of shape (B, K) yields a batch of
Categorical distributions.
Examples
>>> import lucid
>>> from lucid.distributions import Categorical
>>> # Uniform over 4 categories
>>> dist = Categorical(probs=lucid.tensor([0.25, 0.25, 0.25, 0.25]))
>>> samples = dist.sample((10,))
>>> # Batch of 2 distributions
>>> dist_b = Categorical(logits=lucid.zeros(2, 5))
>>> dist_b.batch_shape, dist_b.event_shape
((2,), ())Used by 4
Constructors
1__init__
→None__init__(probs: Tensor | None = None, logits: Tensor | None = None, validate_args: bool | None = None)Initialise a Categorical distribution.
Parameters
(..., K). Rows are
automatically normalised to sum to 1. Mutually exclusive with
logits.(..., K). Converted
to probabilities via softmax internally. Mutually exclusive with
probs.validate_argsbool | None= NoneTrue, validate parameter constraints at construction time.Raises
ValueErrorprobs and logits are provided.Properties
4Mean of the Categorical distribution (undefined — returns NaN).
The Categorical distribution assigns labels with no inherent ordering
or metric, so the mean is not well-defined. This property returns a
NaN tensor of the batch shape to match expected behaviour.
Returns
TensorTensor of float('nan') values with shape batch_shape.
Standard deviation of the Categorical distribution (NaN).
The square root of variance, which is NaN for the reason
given there.
Returns
TensorTensor of float('nan') with shape batch_shape.
Support of the distribution: integer interval .
Returns
ConstraintAn integer_interval constraint from 0 to K - 1.
Variance of the Categorical distribution (undefined — NaN).
A variance is a squared distance, and the labels this distribution
assigns have no metric to measure one with — the same reason
mean is NaN. Returned rather than raised so the moment
composes with the rest of the API the way the reference framework's
does; a caller who wants an error can test for NaN.
Returns
TensorTensor of float('nan') with shape batch_shape.
Instance methods
5Shannon entropy of the Categorical distribution.
Returns
TensorEntropy values of shape batch_shape (nats).
Log-probabilities — as given, or derived from probs on access.
Derived as log(probs) with probs clamped one epsilon inside
[0, 1], as the reference framework derives it, so a category of
probability zero gets a large negative logit rather than -inf.
Normalised probabilities — as given, or softmax(logits).
Draw samples from the Categorical distribution.
Uses the Gumbel-max trick: add i.i.d. noise to the log-probabilities and take the argmax, which is equivalent to ancestral sampling but avoids cumulative-sum and binary search.
Parameters
sample_shapetuple[int, ...]= ()Returns
TensorInteger tensor of shape (*sample_shape, *batch_shape) with
values in . The result is detached
(no gradients flow through discrete samples).