coeus-ops 0.13.0

Numerical tensor operators for Coeus.
Documentation
// ── Mean reduction ──

use crate::backend_ops::BackendOps;
use coeus_core::{BackendError, Scalar};
use coeus_tensor::Tensor;

/// Mean of all elements.
///
/// # Examples
///
/// ```
/// use coeus_tensor::Tensor;
/// use coeus_core::SequentialBackend;
/// use coeus_ops::mean;
///
/// let backend = SequentialBackend::new();
/// let a = Tensor::<f32, SequentialBackend>::from_slice([2, 3], &[1.0, 2.0, 3.0, 4.0, 5.0, 6.0])
///     .expect("example tensor allocation succeeds");
/// let result = mean(&a, &backend).expect("valid mean inputs");
/// assert!((result - 3.5).abs() < 1e-5);
/// ```
#[inline]
pub fn mean<T: Scalar + coeus_core::FloatElement + leto_ops::Scalar, B: BackendOps<T> + Default>(
    a: &Tensor<T, B>,
    backend: &B,
) -> Result<T, B::Error> {
    if a.numel() == 0 {
        return Ok(T::ZERO / <T as coeus_core::FloatElement>::from_f64(0.0));
    }
    let reshaped = if a.is_contiguous() && a.layout().offset() == 0 {
        let crossover = backend.host_staging_crossover();
        if crossover > 0 && a.numel() < crossover {
            return super::staging::staged_scalar(a, backend, mean);
        }
        a.reshape([a.numel()])
    } else {
        let contiguous = a.to_contiguous_on(backend)?;
        contiguous.reshape([a.numel()])
    };
    let reduced = mean_axis(&reshaped, 0, backend)?;
    let mut host_scalar = [T::ZERO];
    backend.copy_to_host(reduced.storage(), &mut host_scalar)?;
    Ok(host_scalar[0])
}

/// Mean along a specific axis.
///
/// # Examples
///
/// ```
/// use coeus_tensor::Tensor;
/// use coeus_core::SequentialBackend;
/// use coeus_ops::mean_axis;
///
/// let backend = SequentialBackend::new();
/// let a = Tensor::<f32, SequentialBackend>::from_slice([2, 3], &[1.0, 2.0, 3.0, 4.0, 5.0, 6.0])
///     .expect("example tensor allocation succeeds");
/// let result = mean_axis(&a, 1, &backend).expect("valid reduction axis");
/// assert_eq!(result.shape(), &[2, 1]);
/// let s = result.as_slice();
/// assert!((s[0] - 2.0).abs() < 1e-5);
/// assert!((s[1] - 5.0).abs() < 1e-5);
/// ```
#[inline]
pub fn mean_axis<T: Scalar + coeus_core::FloatElement, B: BackendOps<T> + Default>(
    a: &Tensor<T, B>,
    axis: usize,
    backend: &B,
) -> Result<Tensor<T, B>, B::Error> {
    if axis >= a.ndim() {
        return Err(B::Error::from(BackendError::AxisOutOfRange {
            operation: "mean_axis",
            axis,
            rank: a.ndim(),
        }));
    }

    let mut out_shape = a.shape_cloned();
    out_shape[axis] = 1;

    // SAFETY: The following operation writes every output element before it is read.
    let mut out = unsafe { Tensor::alloc_on(out_shape, backend) }?;

    let (out_storage, out_layout) = out.storage_mut_and_layout()?;
    backend.reduce_mean(a.storage(), a.layout(), axis, out_storage, out_layout)?;

    Ok(out)
}