v3.0.0: Exact square roots and faster wide-type paths

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "fixed_analytics"
-version = "2.1.0"
+version = "3.0.0"
 edition = "2024"
 rust-version = "1.95"
 authors = ["David Gathercole"]
@@ -23,7 +23,7 @@ verify-no-panic = ["dep:no-panic"]
 
 [dependencies]
 fixed = "1.31"
-no-panic = { version = "0.1", optional = true }
+no-panic = { version = "0.1.37", optional = true }
 
 [dev-dependencies]
 criterion = { version = "0.8", features = ["html_reports"] }

README.md

@@ -30,14 +30,14 @@ Requires Rust 1.95 or later.
 
 ```toml
 [dependencies]
-fixed_analytics = "2.1.0"
+fixed_analytics = "3.0.0"
 ```
 
 For `no_std` environments:
 
 ```toml
 [dependencies]
-fixed_analytics = { version = "2.0.1", default-features = false }
+fixed_analytics = { version = "3.0.0", default-features = false }
 ```
 
 ## Available Functions
@@ -51,7 +51,7 @@ fixed_analytics = { version = "2.0.1", default-features = false }
 |----------|-----------------|-------------------|
 | Trigonometric | `sin`, `cos`, `tan`, `sin_cos`, `atan`, `atan2` | `asin`, `acos` |
 | Hyperbolic | `sinh`, `cosh`, `tanh`, `sinh_cosh`, `asinh` | `acosh`, `atanh`, `acoth`, `coth` |
-| Exponential | `exp`, `pow2` | `ln`, `log2`, `log10` |
+| Exponential | `exp`, `pow2` | `ln`, `log2`, `log10`, `pow` |
 | Algebraic | — | `sqrt` |
 
 Functions are calculated via polynomial evaluation, CORDIC, and Newton-Raphson techniques. Complete absence of panic is verified at the linker level via the [`no-panic`](https://github.com/dtolnay/no-panic) crate.
@@ -82,21 +82,21 @@ Relative error statistics measured against MPFR reference implementations. Accur
 | sin | 6.06e-4 | 8.78e-5 | 1.28e-3 | 1.16e-8 | 1.68e-9 | 2.43e-8 |
 | cos | 6.45e-4 | 9.03e-5 | 1.38e-3 | 1.22e-8 | 1.72e-9 | 2.64e-8 |
 | tan | 7.20e-5 | 3.57e-5 | 2.20e-4 | 1.28e-9 | 3.98e-10 | 3.03e-9 |
-| asin | 1.85e-4 | 3.60e-5 | 4.75e-4 | 4.49e-9 | 7.35e-10 | 8.89e-9 |
-| acos | 2.33e-5 | 1.47e-5 | 6.86e-5 | 4.51e-10 | 2.71e-10 | 1.38e-9 |
-| atan | 1.50e-5 | 1.23e-5 | 3.45e-5 | 3.01e-10 | 2.44e-10 | 7.05e-10 |
+| asin | 1.13e-4 | 2.80e-5 | 3.83e-4 | 3.68e-9 | 5.72e-10 | 6.40e-9 |
+| acos | 1.79e-5 | 1.17e-5 | 4.81e-5 | 3.50e-10 | 2.11e-10 | 1.04e-9 |
+| atan | 7.79e-6 | 6.49e-6 | 1.82e-5 | 1.88e-10 | 1.51e-10 | 4.38e-10 |
 | sinh | 9.80e-5 | 6.23e-5 | 2.79e-4 | 1.52e-9 | 9.64e-10 | 4.29e-9 |
 | cosh | 9.40e-5 | 5.75e-5 | 2.77e-4 | 1.44e-9 | 8.90e-10 | 4.25e-9 |
 | tanh | 1.60e-5 | 1.32e-5 | 2.56e-5 | 2.25e-10 | 1.22e-10 | 3.90e-10 |
 | coth | 6.68e-6 | 3.54e-6 | 1.80e-5 | 1.41e-10 | 1.16e-10 | 2.74e-10 |
-| asinh | 6.44e-4 | 4.83e-4 | 1.75e-3 | 1.03e-8 | 7.59e-9 | 2.85e-8 |
-| acosh | 6.74e-4 | 5.21e-4 | 1.80e-3 | 1.05e-8 | 7.96e-9 | 2.88e-8 |
-| atanh | 3.01e-4 | 5.90e-5 | 6.25e-4 | 6.68e-9 | 1.32e-9 | 1.44e-8 |
-| acoth | 2.10e-3 | 1.33e-3 | 6.67e-3 | 4.26e-8 | 2.62e-8 | 1.39e-7 |
+| asinh | 2.42e-5 | 1.61e-5 | 5.08e-5 | 6.27e-10 | 5.01e-10 | 1.19e-9 |
+| acosh | 1.87e-5 | 1.48e-5 | 4.65e-5 | 5.29e-10 | 4.75e-10 | 1.11e-9 |
+| atanh | 2.21e-4 | 3.99e-5 | 3.33e-4 | 3.63e-9 | 7.20e-10 | 6.24e-9 |
+| acoth | 1.21e-3 | 6.85e-4 | 4.09e-3 | 1.94e-8 | 1.23e-8 | 6.28e-8 |
 | exp | 5.98e-3 | 1.47e-5 | 4.13e-2 | 9.49e-8 | 1.50e-9 | 6.50e-7 |
-| ln | 1.35e-5 | 8.76e-6 | 2.97e-5 | 4.50e-10 | 3.48e-10 | 9.17e-10 |
-| log2 | 1.33e-5 | 8.48e-6 | 2.92e-5 | 3.46e-10 | 2.24e-10 | 7.21e-10 |
-| log10 | 1.44e-5 | 9.28e-6 | 3.14e-5 | 4.49e-10 | 3.27e-10 | 9.07e-10 |
+| ln | 1.18e-5 | 7.61e-6 | 2.09e-5 | 4.35e-10 | 3.78e-10 | 6.47e-10 |
+| log2 | 9.98e-6 | 6.72e-6 | 2.01e-5 | 1.92e-10 | 1.31e-10 | 3.90e-10 |
+| log10 | 1.25e-5 | 8.96e-6 | 2.36e-5 | 4.06e-10 | 3.57e-10 | 6.39e-10 |
 | pow2 | 3.62e-4 | 2.24e-5 | 2.37e-3 | 5.64e-9 | 4.29e-10 | 3.67e-8 |
-| sqrt | 1.77e-7 | 1.16e-7 | 4.74e-7 | 2.70e-12 | 1.78e-12 | 7.16e-12 |
+| sqrt | 8.88e-8 | 5.80e-8 | 2.42e-7 | 1.37e-12 | 8.85e-13 | 3.62e-12 |
 <!-- ACCURACY_END -->

benches/benchmarks.rs

@@ -1,68 +1,84 @@
-//! Benchmarks for CORDIC functions.
+//! Benchmarks for CORDIC functions, on `I16F16` and on `I64F64`.
 
 #![allow(missing_docs, reason = "benchmark code does not need documentation")]
 
 use std::hint::black_box;
 
 use criterion::{Criterion, criterion_group, criterion_main};
-use fixed::types::I16F16;
+use fixed::types::{I16F16, I64F64};
 use fixed_analytics::{
-    acos, acosh, acoth, asin, asinh, atan, atan2, atanh, cos, cosh, coth, exp, ln, log2, log10,
-    sin, sin_cos, sinh, sinh_cosh, sqrt, tan, tanh,
+    CordicNumber, acos, acosh, acoth, asin, asinh, atan, atan2, atanh, cos, cosh, coth, exp, ln,
+    log2, log10, pow, pow2, sin, sin_cos, sinh, sinh_cosh, sqrt, tan, tanh,
 };
 
-fn bench_circular(c: &mut Criterion) {
-    let angle = I16F16::from_num(0.5);
-    let x = I16F16::from_num(0.5);
+fn bench_type<T: CordicNumber>(c: &mut Criterion, name: &str) {
+    let angle = T::from_num(0.5);
+    let large_angle = T::from_num(1000.0);
+    let x = T::from_num(0.5);
+    let large_x = T::from_num(1.5);
+    let pos_x = T::from_num(2.0);
+    let big = T::from_num(50.0);
+    let small = T::from_num(0.005);
 
-    c.bench_function("sin", |b| b.iter(|| sin(black_box(angle))));
-    c.bench_function("cos", |b| b.iter(|| cos(black_box(angle))));
-    c.bench_function("tan", |b| b.iter(|| tan(black_box(angle))));
-    c.bench_function("sin_cos", |b| b.iter(|| sin_cos(black_box(angle))));
-    c.bench_function("asin", |b| b.iter(|| asin(black_box(x))));
-    c.bench_function("acos", |b| b.iter(|| acos(black_box(x))));
-    c.bench_function("atan", |b| b.iter(|| atan(black_box(x))));
-    c.bench_function("atan2", |b| {
-        b.iter(|| atan2(black_box(x), black_box(I16F16::ONE)));
-    });
+    {
+        let mut g = c.benchmark_group(format!("{name}/circular"));
+        g.bench_function("sin", |b| b.iter(|| sin(black_box(angle))));
+        g.bench_function("cos", |b| b.iter(|| cos(black_box(angle))));
+        g.bench_function("tan", |b| b.iter(|| tan(black_box(angle))));
+        g.bench_function("sin_cos", |b| b.iter(|| sin_cos(black_box(angle))));
+        g.bench_function("sin_cos_large", |b| {
+            b.iter(|| sin_cos(black_box(large_angle)));
+        });
+        g.bench_function("asin", |b| b.iter(|| asin(black_box(x))));
+        g.bench_function("acos", |b| b.iter(|| acos(black_box(x))));
+        g.bench_function("atan", |b| b.iter(|| atan(black_box(x))));
+        g.bench_function("atan2", |b| {
+            b.iter(|| atan2(black_box(x), black_box(T::one())));
+        });
+        g.finish();
+    }
+    {
+        let mut g = c.benchmark_group(format!("{name}/hyperbolic"));
+        g.bench_function("sinh", |b| b.iter(|| sinh(black_box(x))));
+        g.bench_function("cosh", |b| b.iter(|| cosh(black_box(x))));
+        g.bench_function("tanh", |b| b.iter(|| tanh(black_box(x))));
+        g.bench_function("coth", |b| b.iter(|| coth(black_box(x))));
+        g.bench_function("sinh_cosh", |b| b.iter(|| sinh_cosh(black_box(x))));
+        g.bench_function("asinh", |b| b.iter(|| asinh(black_box(x))));
+        g.bench_function("asinh_large", |b| b.iter(|| asinh(black_box(big))));
+        g.bench_function("acosh", |b| b.iter(|| acosh(black_box(large_x))));
+        g.bench_function("atanh", |b| b.iter(|| atanh(black_box(x))));
+        g.bench_function("acoth", |b| b.iter(|| acoth(black_box(large_x))));
+        g.finish();
+    }
+    {
+        let mut g = c.benchmark_group(format!("{name}/exponential"));
+        g.bench_function("exp", |b| b.iter(|| exp(black_box(x))));
+        g.bench_function("pow2", |b| b.iter(|| pow2(black_box(x))));
+        g.bench_function("ln", |b| b.iter(|| ln(black_box(pos_x))));
+        g.bench_function("log2", |b| b.iter(|| log2(black_box(pos_x))));
+        g.bench_function("log10", |b| b.iter(|| log10(black_box(pos_x))));
+        g.bench_function("pow", |b| {
+            b.iter(|| pow(black_box(pos_x), black_box(x)));
+        });
+        g.finish();
+    }
+    {
+        let mut g = c.benchmark_group(format!("{name}/algebraic"));
+        g.bench_function("sqrt", |b| b.iter(|| sqrt(black_box(pos_x))));
+        g.bench_function("sqrt_large", |b| b.iter(|| sqrt(black_box(big))));
+        g.bench_function("sqrt_small", |b| b.iter(|| sqrt(black_box(small))));
+        g.finish();
+    }
 }
 
-fn bench_hyperbolic(c: &mut Criterion) {
-    let x = I16F16::from_num(0.5);
-    let large_x = I16F16::from_num(1.5);
-
-    c.bench_function("sinh", |b| b.iter(|| sinh(black_box(x))));
-    c.bench_function("cosh", |b| b.iter(|| cosh(black_box(x))));
-    c.bench_function("tanh", |b| b.iter(|| tanh(black_box(x))));
-    c.bench_function("coth", |b| b.iter(|| coth(black_box(x))));
-    c.bench_function("sinh_cosh", |b| b.iter(|| sinh_cosh(black_box(x))));
-    c.bench_function("asinh", |b| b.iter(|| asinh(black_box(x))));
-    c.bench_function("acosh", |b| b.iter(|| acosh(black_box(large_x))));
-    c.bench_function("atanh", |b| b.iter(|| atanh(black_box(x))));
-    c.bench_function("acoth", |b| b.iter(|| acoth(black_box(large_x))));
+fn bench_i16f16(c: &mut Criterion) {
+    bench_type::<I16F16>(c, "I16F16");
 }
 
-fn bench_exponential(c: &mut Criterion) {
-    let x = I16F16::from_num(0.5);
-    let pos_x = I16F16::from_num(2.0);
-
-    c.bench_function("exp", |b| b.iter(|| exp(black_box(x))));
-    c.bench_function("ln", |b| b.iter(|| ln(black_box(pos_x))));
-    c.bench_function("log2", |b| b.iter(|| log2(black_box(pos_x))));
-    c.bench_function("log10", |b| b.iter(|| log10(black_box(pos_x))));
-}
-
-fn bench_algebraic(c: &mut Criterion) {
-    let x = I16F16::from_num(2.0);
-
-    c.bench_function("sqrt", |b| b.iter(|| sqrt(black_box(x))));
+fn bench_i64f64(c: &mut Criterion) {
+    bench_type::<I64F64>(c, "I64F64");
 }
 
-criterion_group!(
-    benches,
-    bench_circular,
-    bench_hyperbolic,
-    bench_exponential,
-    bench_algebraic
-);
+criterion_group!(benches, bench_i16f16, bench_i64f64);
 criterion_main!(benches);

codecov.yml

@@ -20,4 +20,5 @@ comment:
   behavior: default
 
 ignore:
-  - "benches/**/*"
+  - "benches"
+  - "src/bin"

src/bin/verify_no_panic.rs

@@ -1,26 +1,25 @@
-//! Binary that instantiates every public function with a concrete type.
+//! Binary that instantiates every public function with concrete types.
 //!
 //! This exists solely to trigger monomorphization so that `no_panic`'s
 //! linker-level check can verify that no panic paths survive optimization.
-//! It is only compiled under the `verify-no-panic` feature.
+//! It is only compiled under the `verify-no-panic` feature, for three
+//! layouts that compile to different code: `I16F16`, `I24F8` (more integer
+//! than fractional bits) and `I64F64` (128-bit).
 
 #[cfg(not(feature = "verify-no-panic"))]
 compile_error!("this binary should only be built with --features verify-no-panic");
 
-use fixed::types::I16F16;
+use fixed::types::{I16F16, I24F8, I64F64};
+use fixed_analytics::CordicNumber;
 use fixed_analytics::bounded::{NonNegative, OpenUnitInterval};
 use fixed_analytics::ops::algebraic::sqrt_nonneg;
 use fixed_analytics::ops::hyperbolic::atanh_open;
 use fixed_analytics::{
     acos, acosh, acoth, asin, asinh, atan, atan2, atanh, cos, cosh, coth, exp, ln, log2, log10,
-    pow2, sin, sin_cos, sinh, sinh_cosh, sqrt, tan, tanh,
+    pow, pow2, sin, sin_cos, sinh, sinh_cosh, sqrt, tan, tanh,
 };
 
-fn main() {
-    // Use black_box to prevent the optimizer from eliminating calls entirely.
-    let x = std::hint::black_box(I16F16::from_num(0.5));
-    let y = std::hint::black_box(I16F16::from_num(0.25));
-
+fn exercise<T: CordicNumber>(x: T, y: T, two: T) {
     // Total functions (return T)
     let _ = std::hint::black_box(sin(x));
     let _ = std::hint::black_box(cos(x));
@@ -35,6 +34,7 @@ fn main() {
     let _ = std::hint::black_box(tanh(x));
     let _ = std::hint::black_box(sinh_cosh(x));
     let _ = std::hint::black_box(asinh(x));
+    let _ = std::hint::black_box(asinh(two));
 
     // Fallible functions (return Result<T>)
     let _ = std::hint::black_box(asin(x));
@@ -43,14 +43,36 @@ fn main() {
     let _ = std::hint::black_box(ln(x));
     let _ = std::hint::black_box(log2(x));
     let _ = std::hint::black_box(log10(x));
-    let _ = std::hint::black_box(acosh(I16F16::from_num(2)));
+    let _ = std::hint::black_box(acosh(two));
     let _ = std::hint::black_box(atanh(x));
     let _ = std::hint::black_box(coth(x));
-    let _ = std::hint::black_box(acoth(I16F16::from_num(2)));
+    let _ = std::hint::black_box(acoth(two));
+    let _ = std::hint::black_box(pow(two, x));
 
     // Type-safe wrapper functions
-    let nn = NonNegative::new(x).unwrap();
-    let _ = std::hint::black_box(sqrt_nonneg(nn));
-    let ou = OpenUnitInterval::new(x).unwrap();
-    let _ = std::hint::black_box(atanh_open(ou));
+    if let Some(nn) = NonNegative::new(x) {
+        let _ = std::hint::black_box(sqrt_nonneg(nn));
+    }
+    if let Some(ou) = OpenUnitInterval::new(x) {
+        let _ = std::hint::black_box(atanh_open(ou));
+    }
+}
+
+fn main() {
+    // Use black_box to prevent the optimizer from eliminating calls entirely.
+    exercise(
+        std::hint::black_box(I16F16::from_num(0.5)),
+        std::hint::black_box(I16F16::from_num(0.25)),
+        std::hint::black_box(I16F16::from_num(2)),
+    );
+    exercise(
+        std::hint::black_box(I24F8::from_num(0.5)),
+        std::hint::black_box(I24F8::from_num(0.25)),
+        std::hint::black_box(I24F8::from_num(2)),
+    );
+    exercise(
+        std::hint::black_box(I64F64::from_num(0.5)),
+        std::hint::black_box(I64F64::from_num(0.25)),
+        std::hint::black_box(I64F64::from_num(2)),
+    );
 }

src/bounded.rs

@@ -103,6 +103,13 @@ impl<T: CordicNumber> UnitInterval<T> {
         (value >= -one && value <= one).then_some(Self(value))
     }
 
+    /// Constructs `1 / x` where `x >= 1`, which is always in (0, 1].
+    #[inline]
+    #[must_use]
+    pub fn from_reciprocal(x: AtLeastOne<T>) -> Self {
+        Self(T::one().div(x.0))
+    }
+
     /// Unwraps the inner value.
     #[inline]
     #[must_use]
@@ -259,6 +266,15 @@ mod tests {
         assert!(UnitInterval::new(I16F16::from_num(-1.1)).is_none());
     }
 
+    #[test]
+    fn unit_interval_from_reciprocal() {
+        let at_least = AtLeastOne::new(I16F16::from_num(4)).unwrap();
+        assert_eq!(
+            UnitInterval::from_reciprocal(at_least).get(),
+            I16F16::from_num(0.25)
+        );
+    }
+
     #[test]
     fn unit_interval_get() {
         let unit = UnitInterval::new(I16F16::from_num(0.5)).unwrap();