histogram(input: Tensor, bins: int | Sequence[float] | Tensor = 100, range: tuple[float, float] | None = None, weight: Tensor | None = None, density: bool = False)Implementing kernel
C++ engine symbols that back this Python API.Compute a 1-D histogram of input values.
Everything happens on input's device, without reading a value back
to the host: the range, when not given, is the input's extremes as
tensors; each value's bin is its position on the uniform grid,
corrected against the edges themselves, or a searchsorted over
explicit edges; and the bins fill with one scatter_add.
Parameters
inputTensor100).
Otherwise the increasing bin edges (length bins_n + 1).rangetuple[float, float]= None(lo, hi). Values outside the range are dropped. Ignored
when bins gives the edges. None (default) →
(input.min(), input.max()). A range of zero width is widened
to (lo - 0.5, hi + 0.5).densitybool= FalseTrue divide by total count × bin width to yield a
probability density that integrates to 1. Default False.input. When supplied, sums weights per
bin rather than counting. Default None.Returns
tuple of Tensor(hist, bin_edges), both in input's floating dtype (the
default float dtype for an integer input) and on its device.
hist holds counts, weight sums or densities; bin_edges has
length bins + 1. Every bin is half-open but the last, which
holds its right edge. When the range comes from an input
holding a NaN or an infinity, hist is all NaN — the reference
refuses there, which would take a read back to the host.
Raises
ValueErrorbins is not positive or its edges are fewer than two, the
given range is not finite or its lo exceeds its hi, or
weight has another number of elements than input.Examples
>>> import lucid
>>> hist, edges = lucid.histogram(lucid.tensor([1.0, 2.0, 1.0, 4.0]), bins=4)
>>> hist
tensor([2., 1., 0., 1.])
>>> edges
tensor([1., 1.75, 2.5, 3.25, 4.])