Skip to main content

tk_pg_utils/
lib.rs

1//! This crate provides utility functions for working with
2//! pg-libs
3
4/// Absolute tolerance used for approximate floating-point comparisons.
5const EPS: f64 = 2e-9;
6
7/// Compute the Clifford angle in quarter turns for a half-turn input value.
8///
9/// # Arguments
10///
11/// - `value` (`f64`) - The half-turn value.
12///
13/// # Returns
14///
15/// - `Option<u8>` - The Clifford angle is expressed as a number of quarter turns (0, 1, 2, 3) if the value is a valid Clifford angle, otherwise `None`.
16///
17pub fn cliff_angle(value: f64) -> Option<u8> {
18    let x = value.rem_euclid(2.0);
19    let qt = x * 2.0;
20    let rounded = qt.round();
21    if (qt - rounded).abs() <= EPS {
22        Some((rounded as u8) % 4)
23    } else {
24        None
25    }
26}
27
28/// Test whether a value is approximately 0 modulo n
29///
30/// # Arguments
31///
32/// - `value` (`f64`) - The value to test.
33/// - `n` (`f64`) - The modulus value.
34///
35/// # Returns
36///
37/// - `bool` - `true` if the value is approximately 0 modulo n, otherwise `false`.
38///
39/// # Panics
40///
41/// Panics if `n` is zero or not finite.
42///
43pub fn equiv_0(value: f64, n: f64) -> bool {
44    if !n.is_finite() || n == 0.0 {
45        panic!("equiv_0 requires a finite, non-zero modulus");
46    }
47    let remainder = value.rem_euclid(n);
48    remainder <= EPS || n.abs() - remainder <= EPS
49}
50
51#[cfg(test)]
52mod tests {
53    use super::*;
54
55    #[test]
56    fn test_cliff_angle_basic() {
57        assert_eq!(cliff_angle(0.0), Some(0));
58        assert_eq!(cliff_angle(0.5), Some(1));
59        assert_eq!(cliff_angle(1.0), Some(2));
60        assert_eq!(cliff_angle(1.5), Some(3));
61    }
62
63    #[test]
64    fn test_cliff_angle_wrapping() {
65        assert_eq!(cliff_angle(2.0), Some(0));
66        assert_eq!(cliff_angle(2.5), Some(1));
67        assert_eq!(cliff_angle(4.0), Some(0));
68    }
69
70    #[test]
71    fn test_cliff_angle_negative() {
72        assert_eq!(cliff_angle(-0.5), Some(3));
73        assert_eq!(cliff_angle(-1.0), Some(2));
74        assert_eq!(cliff_angle(-1.5), Some(1));
75        assert_eq!(cliff_angle(-2.0), Some(0));
76    }
77
78    #[test]
79    fn test_cliff_angle_non_clifford() {
80        assert_eq!(cliff_angle(0.25), None);
81        assert_eq!(cliff_angle(0.1), None);
82        assert_eq!(cliff_angle(1.3), None);
83        assert_eq!(cliff_angle(f64::NAN), None);
84        assert_eq!(cliff_angle(f64::INFINITY), None);
85        assert_eq!(cliff_angle(f64::NEG_INFINITY), None);
86    }
87
88    #[test]
89    fn test_cliff_angle_tolerance() {
90        const EPS: f64 = 1e-9;
91        assert_eq!(cliff_angle(0.5 + EPS * 0.9), Some(1));
92        assert_eq!(cliff_angle(0.5 - EPS * 0.9), Some(1));
93        assert_eq!(cliff_angle(0.5 + EPS * 1.1), None);
94    }
95
96    #[test]
97    fn test_equiv_0_multiples() {
98        assert!(equiv_0(0.0, 2.0));
99        assert!(equiv_0(4.0, 2.0));
100        assert!(equiv_0(-6.0, 3.0));
101        assert!(equiv_0(0.25, 0.25));
102        assert!(equiv_0(0.5, 0.25));
103        assert!(!equiv_0(1.0, 2.0));
104        assert!(!equiv_0(-1.0, 2.0));
105    }
106
107    #[test]
108    fn test_equiv_0_tolerance() {
109        assert!(equiv_0(1e-9, 2.0));
110        assert!(equiv_0(-1e-9, 2.0));
111        assert!(equiv_0(2.0 - 1e-9, 2.0));
112        assert!(equiv_0(2.0 + 1e-9, 2.0));
113        assert!(!equiv_0(3e-9, 2.0));
114        assert!(!equiv_0(-3e-9, 2.0));
115    }
116
117    #[test]
118    #[should_panic(expected = "equiv_0 requires a finite, non-zero modulus")]
119    fn test_equiv_0_zero_modulus() {
120        equiv_0(0.0, 0.0);
121    }
122
123    #[test]
124    fn test_equiv_0_negative_modulus() {
125        assert!(equiv_0(4.0, -2.0));
126        assert!(equiv_0(2.0 - 1e-9, -2.0));
127        assert!(!equiv_0(1.0, -2.0));
128    }
129
130    #[test]
131    #[should_panic(expected = "equiv_0 requires a finite, non-zero modulus")]
132    fn test_equiv_0_nan_modulus() {
133        equiv_0(0.0, f64::NAN);
134    }
135
136    #[test]
137    #[should_panic(expected = "equiv_0 requires a finite, non-zero modulus")]
138    fn test_equiv_0_infinite_modulus() {
139        equiv_0(0.0, f64::INFINITY);
140    }
141
142    #[test]
143    fn test_equiv_0_non_finite_values() {
144        assert!(!equiv_0(f64::NAN, 2.0));
145        assert!(!equiv_0(f64::INFINITY, 2.0));
146        assert!(!equiv_0(f64::NEG_INFINITY, 2.0));
147    }
148}