Skip to main content

coeus_ops/reduction/
variance.rs

1// ── Variance and standard deviation reductions ──
2//
3// Composed from `BackendOps` primitives (`sub`, `mul`, `reduce(Mean)`,
4// `reduce(Sum)`, native `T::sqrt`) per SSOT — no new backend dispatch.
5//
6// Two-pass `mean · E[(x − μ)²]` form matches PyTorch's
7// `torch.var_mean`/`torch.std_mean` (Bessel-corrected when `unbiased=true`,
8// `correction=1`). Squared deviations route through `BinaryOp::Mul` (not
9// `BinaryOp::Pow`, which remains deferred per MS-62).
10//
11// Pair functions (`var_mean`, `std_mean`, `var_mean_axis`, `std_mean_axis`)
12// are the SSOT: the singleton variants (`var`, `std_dev`, `var_axis`,
13// `std_dev_axis`) delegate to them so the mean computation is never
14// duplicated.
15
16use crate::backend_ops::BackendOps;
17use crate::binary;
18use coeus_core::{Float, FloatElement};
19use coeus_tensor::Tensor;
20
21/// Number of elements along `axis` — the denominator for `var_axis` variants.
22#[inline]
23fn axis_count(shape: &[usize], axis: usize) -> usize {
24    shape[axis]
25}
26/// Variance over all elements with optional Bessel correction.
27///
28/// `unbiased = true` divides by `(N − 1)` (PyTorch/JAX default);
29/// `unbiased = false` divides by `N` (population variance).
30#[inline]
31pub fn var<T: Float + FloatElement + leto_ops::Scalar, B: BackendOps<T> + Default>(
32    a: &Tensor<T, B>,
33    unbiased: bool,
34    backend: &B,
35) -> Result<T, B::Error> {
36    Ok(var_mean(a, unbiased, backend)?.0)
37}
38
39/// Variance over all elements together with the scalar mean.
40///
41/// Returns `(variance, mean)`. The variance uses the same Bessel-corrected
42/// denominator as [`var`] (`unbiased=true` → divide by `N - 1`;
43/// `unbiased=false` → divide by `N`), matching PyTorch's
44/// `torch.var_mean(input, correction=...)` for flattened input.
45#[inline]
46pub fn var_mean<T: Float + FloatElement + leto_ops::Scalar, B: BackendOps<T> + Default>(
47    a: &Tensor<T, B>,
48    unbiased: bool,
49    backend: &B,
50) -> Result<(T, T), B::Error> {
51    let n = a.numel();
52    assert!(n > 0, "var_mean: empty tensor has no variance");
53
54    if a.is_contiguous() && a.layout().offset() == 0 {
55        let crossover = backend.host_staging_crossover();
56        if crossover > 0 && n < crossover {
57            return super::staging::staged_scalar(a, backend, |host, seq| {
58                var_mean(host, unbiased, seq)
59            });
60        }
61    }
62    let mu = super::mean(a, backend)?;
63    let flattened = if a.is_contiguous() && a.layout().offset() == 0 {
64        a.reshape([n])
65    } else {
66        a.to_contiguous_on(backend)?.reshape([n])
67    };
68    let mu_full = Tensor::full_on([n], mu, backend)?;
69    let dev = binary::sub(&flattened, &mu_full, backend)?;
70    let sq = binary::mul(&dev, &dev, backend)?;
71    let s = super::sum(&sq, backend)?;
72    let denom = if unbiased && n > 1 { n - 1 } else { n };
73    Ok((s / T::from_count(denom), mu))
74}
75
76/// Variance along a specific axis, reducing it to size 1.
77#[inline]
78pub fn var_axis<T: Float + FloatElement, B: BackendOps<T> + Default>(
79    a: &Tensor<T, B>,
80    axis: usize,
81    unbiased: bool,
82    backend: &B,
83) -> Result<Tensor<T, B>, B::Error> {
84    Ok(var_mean_axis(a, axis, unbiased, backend)?.0)
85}
86
87/// Standard deviation over all elements with optional Bessel correction.
88#[inline]
89pub fn std_dev<T: Float + FloatElement + leto_ops::Scalar, B: BackendOps<T> + Default>(
90    a: &Tensor<T, B>,
91    unbiased: bool,
92    backend: &B,
93) -> Result<T, B::Error> {
94    Ok(std_mean(a, unbiased, backend)?.0)
95}
96
97/// Standard deviation over all elements together with the scalar mean.
98///
99/// Returns `(std_dev, mean)`. Composed on [`var_mean`] and native `T::sqrt`;
100/// matches `torch.std_mean(input, correction=...)` for flattened input.
101#[inline]
102pub fn std_mean<T: Float + FloatElement + leto_ops::Scalar, B: BackendOps<T> + Default>(
103    a: &Tensor<T, B>,
104    unbiased: bool,
105    backend: &B,
106) -> Result<(T, T), B::Error> {
107    let (v, mu) = var_mean(a, unbiased, backend)?;
108    Ok((<T as Float>::sqrt(v), mu))
109}
110
111/// Standard deviation along a specific axis, reducing it to size 1.
112#[inline]
113pub fn std_dev_axis<T: Float + FloatElement, B: BackendOps<T> + Default>(
114    a: &Tensor<T, B>,
115    axis: usize,
116    unbiased: bool,
117    backend: &B,
118) -> Result<Tensor<T, B>, B::Error> {
119    Ok(std_mean_axis(a, axis, unbiased, backend)?.0)
120}
121
122/// Variance along `axis` together with the per-slice mean, computed in a single
123/// two-pass host fold.
124///
125/// Returns `(variance, mean)`. The mean is identical to
126/// [`mean_axis(a, axis, …)`](super::mean_axis) and the variance uses the same
127/// Bessel-corrected denominator as [`var_axis`] (`unbiased=true` → divide by
128/// `n − 1`, matching `torch.var_mean(input, dim, correction=1)`;
129/// `unbiased=false` → divide by `n`, matching `correction=0`).
130#[inline]
131#[expect(
132    clippy::type_complexity,
133    reason = "The paired tensor return preserves the established variance/mean API."
134)]
135pub fn var_mean_axis<T: Float + FloatElement, B: BackendOps<T> + Default>(
136    a: &Tensor<T, B>,
137    axis: usize,
138    unbiased: bool,
139    backend: &B,
140) -> Result<(Tensor<T, B>, Tensor<T, B>), B::Error> {
141    assert!(axis < a.ndim(), "var_mean_axis: axis {axis} out of bounds");
142    let n = axis_count(a.shape(), axis);
143    assert!(n > 0, "var_mean_axis: axis {axis} has zero elements");
144
145    let mu = super::mean_axis(a, axis, backend)?;
146    let dev = binary::sub(a, &mu, backend)?;
147    let sq = binary::mul(&dev, &dev, backend)?;
148    let s = super::sum_axis(&sq, axis, backend)?;
149    let denom = if unbiased && n > 1 { n - 1 } else { n };
150    let denom_full = Tensor::full_on(s.shape_cloned(), T::from_count(denom), backend)?;
151    let v = binary::div(&s, &denom_full, backend)?;
152    Ok((v, mu))
153}
154
155/// Standard deviation along `axis` together with the per-slice mean.
156///
157/// Returns `(std_dev, mean)`. Composed on [`var_mean_axis`] and native
158/// `T::sqrt`; matches `torch.std_mean(input, dim, correction=...)`.
159#[inline]
160#[expect(
161    clippy::type_complexity,
162    reason = "The paired tensor return preserves the established standard-deviation/mean API."
163)]
164pub fn std_mean_axis<T: Float + FloatElement, B: BackendOps<T> + Default>(
165    a: &Tensor<T, B>,
166    axis: usize,
167    unbiased: bool,
168    backend: &B,
169) -> Result<(Tensor<T, B>, Tensor<T, B>), B::Error> {
170    let (v, mu) = var_mean_axis(a, axis, unbiased, backend)?;
171    let std = crate::unary::sqrt(&v, backend)?;
172    Ok((std, mu))
173}