Skip to main content

qualia_core_db/solvers/units/
dimension.rs

1//! Physical dimension as the 7-vector of SI base-dimension exponents.
2//!
3//! Order: length (m), mass (kg), time (s), electric current (A), thermodynamic
4//! temperature (K), amount of substance (mol), luminous intensity (cd). A `Dimension`
5//! is these seven signed exponents; products add exponents, quotients subtract,
6//! powers scale. All-zero is dimensionless.
7
8/// The seven SI base-dimension exponents.
9#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
10pub struct Dimension {
11    pub exponents: [i8; 7],
12}
13
14/// Indices into the exponent vector.
15pub const LENGTH: usize = 0;
16pub const MASS: usize = 1;
17pub const TIME: usize = 2;
18pub const CURRENT: usize = 3;
19pub const TEMPERATURE: usize = 4;
20pub const AMOUNT: usize = 5;
21pub const LUMINOSITY: usize = 6;
22
23impl Dimension {
24    /// Creates a default `Dimension`.
25    pub const fn new(exponents: [i8; 7]) -> Self {
26        Self { exponents }
27    }
28
29    /// A base dimension with exponent 1 at `index`.
30    const fn base(index: usize) -> Self {
31        let mut e = [0i8; 7];
32        e[index] = 1;
33        Self { exponents: e }
34    }
35
36    pub const DIMENSIONLESS: Dimension = Dimension::new([0; 7]);
37    pub const LENGTH: Dimension = Dimension::base(LENGTH);
38    pub const MASS: Dimension = Dimension::base(MASS);
39    pub const TIME: Dimension = Dimension::base(TIME);
40    pub const CURRENT: Dimension = Dimension::base(CURRENT);
41    pub const TEMPERATURE: Dimension = Dimension::base(TEMPERATURE);
42    pub const AMOUNT: Dimension = Dimension::base(AMOUNT);
43    pub const LUMINOSITY: Dimension = Dimension::base(LUMINOSITY);
44
45    /// Area = L², Volume = L³.
46    pub const AREA: Dimension = Dimension::new([2, 0, 0, 0, 0, 0, 0]);
47    pub const VOLUME: Dimension = Dimension::new([3, 0, 0, 0, 0, 0, 0]);
48    /// Velocity = L·T⁻¹, Acceleration = L·T⁻².
49    pub const VELOCITY: Dimension = Dimension::new([1, 0, -1, 0, 0, 0, 0]);
50    pub const ACCELERATION: Dimension = Dimension::new([1, 0, -2, 0, 0, 0, 0]);
51    /// Force = M·L·T⁻² (newton).
52    pub const FORCE: Dimension = Dimension::new([1, 1, -2, 0, 0, 0, 0]);
53    /// Energy = M·L²·T⁻² (joule); Power = M·L²·T⁻³ (watt).
54    pub const ENERGY: Dimension = Dimension::new([2, 1, -2, 0, 0, 0, 0]);
55    pub const POWER: Dimension = Dimension::new([2, 1, -3, 0, 0, 0, 0]);
56    /// Pressure = M·L⁻¹·T⁻² (pascal).
57    pub const PRESSURE: Dimension = Dimension::new([-1, 1, -2, 0, 0, 0, 0]);
58    /// Electric charge = T·A (coulomb).
59    pub const CHARGE: Dimension = Dimension::new([0, 0, 1, 1, 0, 0, 0]);
60    /// Frequency = T⁻¹ (hertz).
61    pub const FREQUENCY: Dimension = Dimension::new([0, 0, -1, 0, 0, 0, 0]);
62
63    /// `true` when dimensionless.
64    pub fn is_dimensionless(&self) -> bool {
65        self.exponents == [0; 7]
66    }
67
68    /// Dimension of a product: exponents add (saturating to keep `i8`).
69    pub fn mul(&self, other: &Dimension) -> Dimension {
70        let mut e = [0i8; 7];
71        for i in 0..7 {
72            e[i] = self.exponents[i].saturating_add(other.exponents[i]);
73        }
74        Dimension { exponents: e }
75    }
76
77    /// Dimension of a quotient: exponents subtract.
78    pub fn div(&self, other: &Dimension) -> Dimension {
79        let mut e = [0i8; 7];
80        for i in 0..7 {
81            e[i] = self.exponents[i].saturating_sub(other.exponents[i]);
82        }
83        Dimension { exponents: e }
84    }
85
86    /// Dimension raised to an integer power: exponents scale.
87    pub fn powi(&self, n: i32) -> Dimension {
88        let mut e = [0i8; 7];
89        for i in 0..7 {
90            e[i] = (self.exponents[i] as i32 * n).clamp(i8::MIN as i32, i8::MAX as i32) as i8;
91        }
92        Dimension { exponents: e }
93    }
94}
95
96#[cfg(test)]
97mod tests {
98    use super::*;
99
100    #[test]
101    fn products_and_quotients_compose() {
102        // velocity = length / time
103        assert_eq!(Dimension::LENGTH.div(&Dimension::TIME), Dimension::VELOCITY);
104        // force × length = energy (work)
105        assert_eq!(Dimension::FORCE.mul(&Dimension::LENGTH), Dimension::ENERGY);
106        // energy / time = power
107        assert_eq!(Dimension::ENERGY.div(&Dimension::TIME), Dimension::POWER);
108        // force / area = pressure
109        assert_eq!(Dimension::FORCE.div(&Dimension::AREA), Dimension::PRESSURE);
110    }
111
112    #[test]
113    fn powers_scale_exponents() {
114        assert_eq!(Dimension::LENGTH.powi(2), Dimension::AREA);
115        assert_eq!(Dimension::LENGTH.powi(3), Dimension::VOLUME);
116        // velocity² has dimension L²T⁻².
117        assert_eq!(
118            Dimension::VELOCITY.powi(2),
119            Dimension::new([2, 0, -2, 0, 0, 0, 0])
120        );
121    }
122
123    #[test]
124    fn dimensionless_detection() {
125        assert!(Dimension::DIMENSIONLESS.is_dimensionless());
126        // velocity / velocity = dimensionless
127        assert!(Dimension::VELOCITY
128            .div(&Dimension::VELOCITY)
129            .is_dimensionless());
130        assert!(!Dimension::FORCE.is_dimensionless());
131    }
132}