1use crate::backend_ops::BackendOps;
17use crate::binary;
18use coeus_core::{Float, FloatElement};
19use coeus_tensor::Tensor;
20
21#[inline]
23fn axis_count(shape: &[usize], axis: usize) -> usize {
24 shape[axis]
25}
26#[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#[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#[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#[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#[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#[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#[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#[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}