odem_rs_util/si/

stats.rs

//! Enables compatibility between `uom` SI units and statistical collections.
//!
//! This module provides additional functionality that allows SI quantities
//! from [`uom`] to be used with [`RandomVariable`] collections. It ensures that
//! SI units can be formatted, displayed, and used in statistical analyses
//! within ODEM-rs.
//!
//! ## Example Usage
//!
//! ```
//! use odem_rs_util::{si::{time::*, UnitExt as _}, random_variable::RandomVariable};
//!
//! let mut rv = RandomVariable::new::<2>();
//! rv.tabulate(second::new(3.0));
//! rv.tabulate(second::new(5.0));
//!
//! let formatted = rv.display(minute); // display using SI unit of minute
//! println!("{:?}", formatted);
//! ```
//!
//! ## Notes
//! - This functionality is enabled via the **"uom"** feature flag.
//! - The display methods (`display`, `display_full`) allow formatting results
//!   in different styles.
//! - The `uom_compatible!` macro ensures compatibility across a wide range of
//!   SI dimensions.

use uom::{
	Conversion,
	fmt::DisplayStyle,
	num_traits::{AsPrimitive, FromPrimitive, Num},
	si::{self, Dimension, Quantity, Unit, Units, fmt::QuantityArguments},
};

use crate::random_variable::{RandomVariable, Sample};
use core::{borrow::Borrow, fmt, marker::PhantomData};

/// A displayable representation of a [`RandomVariable`] using SI units.
///
/// This struct allows statistical results to be formatted with appropriate
/// units, either in an **abbreviated** (e.g., "5 m/s") or **descriptive**
/// (e.g., "5 meters per second") style.
///
/// # Example
///
/// ```
/// use odem_rs_util::{
///     si::{velocity::*, UnitExt as _},
///     random_variable::RandomVariable,
/// };
///
/// let mut rv = RandomVariable::new::<2>();
/// rv.tabulate(meter_per_second::new(12.0));
///
/// let formatted = rv.display(knot);
/// println!("{:?}", formatted); // Outputs statistics in knots
/// ```
pub struct RandomQuantity<B, D, U, V, N, const M: usize>
where
	B: Borrow<RandomVariable<Quantity<D, U, V>, M>>,
	D: Dimension + ?Sized,
	U: Units<V> + ?Sized,
	V: Num + Conversion<V>,
	Quantity<D, U, V>: Sample,
{
	/// Reference to the random variable containing statistical samples.
	rv: B,
	/// The [`DisplayStyle`] used to format the unit.
	style: DisplayStyle,
	/// The unit type used for formatting.
	unit: N,
	/// Marker for the borrowed `Quantity`.
	_marker: PhantomData<Quantity<D, U, V>>,
}

impl<B, D, U, V, N, const M: usize> RandomQuantity<B, D, U, V, N, M>
where
	B: Borrow<RandomVariable<Quantity<D, U, V>, M>>,
	D: Dimension + ?Sized,
	U: Units<V> + ?Sized,
	V: Num + Conversion<V>,
	Quantity<D, U, V>: Sample,
{
	const fn new(rv: B, style: DisplayStyle, unit: N) -> Self {
		Self {
			rv,
			style,
			unit,
			_marker: PhantomData,
		}
	}

	/// Extracts the inner [`Quantity`].
	pub fn into_inner(self) -> B {
		self.rv
	}
}

/// A trait to indicate which [dimensions] a [unit] is compatible
/// with.
///
/// Unfortunately, the `uom`-crate doesn't ship with a meta-function like this,
/// so we have to improvise.
///
/// [dimensions]: Dimension
/// [unit]: Unit
pub trait Compatible<D: Dimension + ?Sized>: Unit {
	/// Creates a statically type-checked and displayable object that can be
	/// used for formatting [Quantities](Quantity).
	fn format_args<U: Units<V> + ?Sized, V: Num + Conversion<V>>(
		self,
		value: Quantity<D, U, V>,
		style: DisplayStyle,
	) -> QuantityArguments<D, U, V, Self>;
}

// allow SI quantities to be used in RandomVariables
impl<D, U, V> Sample for Quantity<D, U, V>
where
	D: Dimension + ?Sized,
	U: Units<V> + ?Sized,
	V: Conversion<V> + Num + AsPrimitive<f64> + FromPrimitive + PartialEq + PartialOrd,
{
	fn quantify(&self) -> f64 {
		self.value.as_()
	}

	fn qualify(val: f64) -> Self {
		Quantity {
			dimension: PhantomData,
			units: PhantomData,
			value: V::from_f64(val).unwrap(),
		}
	}
}

// extend RandomVariables with display-methods for compatible SI quantities
impl<D, U, V, const M: usize> RandomVariable<Quantity<D, U, V>, M>
where
	Quantity<D, U, V>: Sample,
	D: Dimension + ?Sized,
	U: Units<V> + ?Sized,
	V: Conversion<V> + Num,
{
	/// Returns a borrowed [displayable](fmt::Debug) object that can be used
	/// as a format argument and displays the computed statistical moments
	/// with units of measurement in [abbreviated] form.
	///
	/// [abbreviated]: DisplayStyle::Abbreviation
	pub fn display<N>(&self, unit: N) -> RandomQuantity<&'_ Self, D, U, V, N, M>
	where
		N: Compatible<D> + Conversion<V, T = <V as Conversion<V>>::T>,
	{
		RandomQuantity::new(self, DisplayStyle::Abbreviation, unit)
	}

	/// Returns an owning [displayable](fmt::Debug) object that can be used
	/// as a format argument and displays the computed statistical moments
	/// with units of measurement in [abbreviated] form.
	///
	/// [abbreviated]: DisplayStyle::Abbreviation
	pub fn displayed<N>(self, unit: N) -> RandomQuantity<Self, D, U, V, N, M>
	where
		N: Compatible<D> + Conversion<V, T = <V as Conversion<V>>::T>,
	{
		RandomQuantity::new(self, DisplayStyle::Abbreviation, unit)
	}

	/// Returns a borrowed [displayable](fmt::Debug) object that can be used
	/// as a format argument and displays the computed statistical moments
	/// with units of measurement in [descriptive] form.
	///
	/// [descriptive]: DisplayStyle::Description
	pub fn display_full<N>(&self, unit: N) -> RandomQuantity<&'_ Self, D, U, V, N, M>
	where
		N: Compatible<D> + Conversion<V, T = <V as Conversion<V>>::T>,
	{
		RandomQuantity::new(self, DisplayStyle::Description, unit)
	}

	/// Returns an owned [displayable](fmt::Debug) object that can be used
	/// as a format argument and displays the computed statistical moments
	/// with units of measurement in [descriptive] form.
	///
	/// [descriptive]: DisplayStyle::Description
	pub fn displayed_full<N>(self, unit: N) -> RandomQuantity<Self, D, U, V, N, M>
	where
		N: Compatible<D> + Conversion<V, T = <V as Conversion<V>>::T>,
	{
		RandomQuantity::new(self, DisplayStyle::Description, unit)
	}
}

/// Generates a `Debug` implementation for the `RandomQuantity` display helper.
macro_rules! impl_debug_fmt {
	($($n:tt),* $(,)?) => {$(
		impl<B, D, U, V, N> fmt::Debug for RandomQuantity<B, D, U, V, N, $n>
		where
			Quantity<D, U, V>: Sample,
			B: Borrow<RandomVariable<Quantity<D, U, V>, $n>>,
			D: Dimension + ?Sized,
			U: Units<V> + ?Sized,
			V: Conversion<V> + Num + fmt::Debug,
			N: Compatible<D> + Conversion<V, T = <V as Conversion<V>>::T>,
		{
			fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
				let mut dbs = f.debug_struct("RandomVariable");
				let rv = self.rv.borrow();
				let len = rv.count();

				dbs.field("n", &len);

				if len > 0 {
					impl_debug_fmt!(@inner_impl self, rv, dbs, $n);
				}

				dbs.finish()
			}
		}
	)*};

	(@inner_impl $self:ident, $rv:ident, $debug:ident, 0) => {
		$debug
			.field("min", &$self.unit.format_args($rv.min().unwrap(), $self.style))
			.field("max", &$self.unit.format_args($rv.max().unwrap(), $self.style));
	};

	(@inner_impl $self:ident, $rv:ident, $debug:ident, 1) => {
		impl_debug_fmt!(@inner_impl $self, $rv, $debug, 0);
		$debug.field(
			"mean",
			&$self.unit.format_args(Quantity::qualify($rv.mean()), $self.style)
		);
	};

	(@inner_impl $self:ident, $rv:ident, $debug:ident, 2) => {
		impl_debug_fmt!(@inner_impl $self, $rv, $debug, 1);
		#[cfg(any(feature = "std", feature = "libm"))]
		{
			$debug.field(
				"sdev",
				&$self.unit.format_args(Quantity::qualify($rv.std_dev()), $self.style)
			);
		}
		#[cfg(not(any(feature = "std", feature = "libm")))]
		{
			$debug.field("variance", &$rv.variance());
		}
	};

	(@inner_impl $self:ident, $rv:ident, $debug:ident, 3) => {
		impl_debug_fmt!(@inner_impl $self, $rv, $debug, 2);
		$debug.field("skew", &$rv.skew());
	};

	(@inner_impl $self:ident, $rv:ident, $debug:ident, 4) => {
		impl_debug_fmt!(@inner_impl $self, $rv, $debug, 3);
		$debug.field("kurt", &$rv.kurtosis());
	};
}

// display (dimension-) compatible RandomQuantities
impl_debug_fmt!(0, 1, 2);

#[cfg(any(feature = "std", feature = "libm"))]
impl_debug_fmt!(3, 4);

/// Extends `uom` SI quantities to be compatible with simulation statistics.
///
/// This macro ensures that SI dimensions can be properly formatted and
/// displayed when used in statistical computations.
macro_rules! uom_compatible {
	($U:ident, $T:ident) => {
		impl<T> Compatible<::uom::si::$U::Dimension> for T
		where
			T: si::$U::Unit,
		{
			fn format_args<U: si::Units<V> + ?Sized, V: Num + Conversion<V>>(
				self,
				value: si::$U::$T<U, V>,
				style: DisplayStyle,
			) -> QuantityArguments<si::$U::Dimension, U, V, Self> {
				value.into_format_args(self, style)
			}
		}
	};
}

// implement the glue trait for all si quantities
super::uom_quantity!(uom_compatible!);