class

HalfCauchy

extendsDistribution

HalfCauchy(scale: Tensor | float, validate_args: bool | None = None)

source edit

Half-Cauchy distribution — the absolute value of a zero-location Cauchy.

If $X \sim \operatorname{Cauchy}(0, s)$ then $|X| \sim \operatorname{HalfCauchy}(s)$ . The distribution is supported on $[0, \infty)$ and has no finite moments (mean and variance are undefined, like the full Cauchy).

It is a popular weakly-informative prior for scale parameters in Bayesian hierarchical models — heavy tails allow occasional large scales while the mode at zero permits near-zero scales.

Parameters

scaleTensor | float

Scale parameter

s > 0

. This is the half-width at half-maximum of the Cauchy density folded onto

[0, \infty)

validate_argsbool | None= None

If True, validate parameter constraints at construction time.

Attributes

scaleTensor

Scale parameter

s

Notes

PDF:

p(x; s) = \frac{2}{\pi s \left(1 + (x/s)^2\right)}, \quad x \geq 0

Log-PDF:

\log p(x) = \log 2 + \log\operatorname{Cauchy}(x; 0, s)

where the right-hand side is the log-density of the full Cauchy evaluated at $x$ .

Neither the mean nor the variance exists because the Cauchy distribution lacks finite moments of any positive order.

Reparameterised sampling folds a Cauchy sample via abs, so gradients propagate through the scale parameter.

Examples

>>> import lucid
>>> from lucid.distributions import HalfCauchy
>>> dist = HalfCauchy(scale=1.0)
>>> samples = dist.rsample((200,))
>>> bool((samples >= 0.0).all())
True

Used by 2

Constructors

dunder

init

→None

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

source edit

Initialise a HalfCauchy distribution.

Parameters

scaleTensor | float

Scale parameter

s > 0

. The half-width at half-maximum of the Cauchy density folded onto

[0, \infty)

validate_argsbool | None= None

If True, validate parameter constraints at construction time.

Properties

prop

mean

→Tensor

mean: Tensor

source edit

Mean of the half-Cauchy — infinite.

Folding the Cauchy onto $[0, \infty)$ removes the cancellation that made the full distribution's mean undefined and leaves a single divergent tail, so the answer is $+\infty$ rather than NaN.

Returns

Tensor

Tensor of inf with shape batch_shape.

prop

mode

→Tensor

mode: Tensor

source edit

Mode of the half-Cauchy distribution: 0, where the density peaks.

prop

stddev

→Tensor

stddev: Tensor

source edit

Standard deviation of the half-Cauchy — infinite.

prop

variance

→Tensor

variance: Tensor

source edit

Variance of the half-Cauchy — infinite.

Instance methods

cdf

→Tensor

cdf(value: Tensor)

source edit

Cumulative distribution function of the half-Cauchy distribution.

F(x) = \frac{2}{\pi} \arctan\!\left(\frac{x}{s}\right), \quad x \geq 0

Returns probabilities in $[0, 1]$ ; 0 below 0.

Examples

>>> HalfCauchy(scale=1.0).cdf(lucid.tensor(1.0))  # the median is s
tensor(0.5)

entropy

→Tensor

entropy()

source edit

Entropy of the half-Cauchy distribution.

H[X] = \ln(2\pi s)

The full Cauchy's $\ln(4\pi s)$ less $\ln 2$ : folding halves the support and doubles the density on it.

Returns

Tensor

Entropy values of shape batch_shape (nats).

Examples

>>> HalfCauchy(scale=1.0).entropy()  # ln(2 pi)
tensor(1.838)

icdf

→Tensor

icdf(value: Tensor)

source edit

Quantile function of the half-Cauchy distribution.

Q(p) = s \tan\!\left(\frac{\pi p}{2}\right)

Returns quantiles in $[0, \infty]$ .

Examples

>>> HalfCauchy(scale=1.0).icdf(lucid.tensor(0.5))
tensor(1.)

log_prob

→Tensor

log_prob(value: Tensor)

source edit

Log-probability density of the HalfCauchy distribution.

\log p(x) = \log 2 + \log\operatorname{Cauchy}(x; 0, s)

Parameters

valueTensor

Non-negative points

x \geq 0

at which to evaluate.

Returns

Tensor

Log-density values of the same shape as value; -inf below 0, where the density is 0.

rsample

→Tensor

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

source edit

Draw reparameterised samples by folding a Cauchy sample.

Computes abs of a zero-location Cauchy sample, so gradients propagate through the scale parameter.

Parameters

sample_shapetuple[int, ...]= ()

Leading shape of the output sample batch.

Returns

Tensor

Non-negative samples of shape (*sample_shape, *batch_shape).

class

HalfCauchy

extendsDistribution

HalfCauchy(scale: Tensor | float, validate_args: bool | None = None)

source edit

Half-Cauchy distribution — the absolute value of a zero-location Cauchy.

It is a popular weakly-informative prior for scale parameters in Bayesian hierarchical models — heavy tails allow occasional large scales while the mode at zero permits near-zero scales.

Parameters

scaleTensor | float

Scale parameter

s > 0

. This is the half-width at half-maximum of the Cauchy density folded onto

[0, \infty)

validate_argsbool | None= None

If True, validate parameter constraints at construction time.

Attributes

scaleTensor

Scale parameter

s

Notes

PDF:

p(x; s) = \frac{2}{\pi s \left(1 + (x/s)^2\right)}, \quad x \geq 0

Log-PDF:

\log p(x) = \log 2 + \log\operatorname{Cauchy}(x; 0, s)

where the right-hand side is the log-density of the full Cauchy evaluated at $x$ .

Neither the mean nor the variance exists because the Cauchy distribution lacks finite moments of any positive order.

Reparameterised sampling folds a Cauchy sample via abs, so gradients propagate through the scale parameter.

Examples

>>> import lucid
>>> from lucid.distributions import HalfCauchy
>>> dist = HalfCauchy(scale=1.0)
>>> samples = dist.rsample((200,))
>>> bool((samples >= 0.0).all())
True

Used by 2

Constructors

dunder

init

→None

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

source edit

Initialise a HalfCauchy distribution.

Parameters

scaleTensor | float

Scale parameter

s > 0

. The half-width at half-maximum of the Cauchy density folded onto

[0, \infty)

validate_argsbool | None= None

If True, validate parameter constraints at construction time.

Properties

prop

mean

→Tensor

mean: Tensor

source edit

Mean of the half-Cauchy — infinite.

Folding the Cauchy onto $[0, \infty)$ removes the cancellation that made the full distribution's mean undefined and leaves a single divergent tail, so the answer is $+\infty$ rather than NaN.

Returns

Tensor

Tensor of inf with shape batch_shape.

prop

mode

→Tensor

mode: Tensor

source edit

Mode of the half-Cauchy distribution: 0, where the density peaks.

prop

stddev

→Tensor

stddev: Tensor

source edit

Standard deviation of the half-Cauchy — infinite.

prop

variance

→Tensor

variance: Tensor

source edit

Variance of the half-Cauchy — infinite.

Instance methods

cdf

→Tensor

cdf(value: Tensor)

source edit

Cumulative distribution function of the half-Cauchy distribution.

F(x) = \frac{2}{\pi} \arctan\!\left(\frac{x}{s}\right), \quad x \geq 0

Returns probabilities in $[0, 1]$ ; 0 below 0.

Examples

>>> HalfCauchy(scale=1.0).cdf(lucid.tensor(1.0))  # the median is s
tensor(0.5)

entropy

→Tensor

entropy()

source edit

Entropy of the half-Cauchy distribution.

H[X] = \ln(2\pi s)

The full Cauchy's $\ln(4\pi s)$ less $\ln 2$ : folding halves the support and doubles the density on it.

Returns

Tensor

Entropy values of shape batch_shape (nats).

Examples

>>> HalfCauchy(scale=1.0).entropy()  # ln(2 pi)
tensor(1.838)

icdf

→Tensor

icdf(value: Tensor)

source edit

Quantile function of the half-Cauchy distribution.

Q(p) = s \tan\!\left(\frac{\pi p}{2}\right)

Returns quantiles in $[0, \infty]$ .

Examples

>>> HalfCauchy(scale=1.0).icdf(lucid.tensor(0.5))
tensor(1.)

log_prob

→Tensor

log_prob(value: Tensor)

source edit

Log-probability density of the HalfCauchy distribution.

\log p(x) = \log 2 + \log\operatorname{Cauchy}(x; 0, s)

Parameters

valueTensor

Non-negative points

x \geq 0

at which to evaluate.

Returns

Tensor

Log-density values of the same shape as value; -inf below 0, where the density is 0.

rsample

→Tensor

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

source edit

Draw reparameterised samples by folding a Cauchy sample.

Computes abs of a zero-location Cauchy sample, so gradients propagate through the scale parameter.

Parameters

sample_shapetuple[int, ...]= ()

Leading shape of the output sample batch.

Returns

Tensor

Non-negative samples of shape (*sample_shape, *batch_shape).