docs

Author: tgross35

crates/libm-test/examples/plot_domains.rs

@@ -2,7 +2,7 @@
 //! to plot them. Requires Julia with the `CairoMakie` dependency.
 //!
 //! Note that running in release mode by default generates a _lot_ more datapoints, which
-//! causes plotting to be extremely slow (some simplification to done in the script).
+//! causes plotting to be extremely slow (some simplification to be done in the script).
 
 use std::io::{BufWriter, Write};
 use std::path::Path;
@@ -21,9 +21,9 @@ fn main() {
     }
 
     let jl_script = Path::new(&env::var("CARGO_MANIFEST_DIR").unwrap()).join(JL_PLOT);
-
     let mut j_args = Vec::new();
 
+    // Plot a few domains with some functions that use them.
     plot_one::<SqrtDomain>(out_dir, "sqrt", &mut j_args);
     plot_one::<TrigDomain>(out_dir, "cos", &mut j_args);
     plot_one::<Unbounded>(out_dir, "cbrt", &mut j_args);
@@ -36,6 +36,7 @@ fn main() {
     cmd.arg(jl_script).args(j_args).status().unwrap();
 }
 
+/// Plot a single domain.
 fn plot_one<D: Domain<f32>>(out_dir: &Path, name: &str, j_args: &mut Vec<String>) {
     let base_name = out_dir.join(format!("domain-inputs-{name}"));
     let text_file = base_name.with_extension("txt");

crates/libm-test/src/domain.rs

@@ -1,9 +1,7 @@
-#![allow(unused)]
-
 use std::fmt;
 use std::ops::{self, Bound};
 
-use crate::{Float, MathOp, MinInt, op};
+use crate::Float;
 
 /// A trait to be implemented on types representing a function's domain.
 ///
@@ -26,7 +24,8 @@ where
         std::iter::empty()
     }
 
-    /// Points to check closer around, often zeros of the derivative.
+    /// Additional points to check closer around. These can be e.g. undefined asymptotes or
+    /// inflection points.
     fn check_points() -> impl Iterator<Item = T> {
         std::iter::empty()
     }
@@ -174,12 +173,13 @@ macro_rules! impl_has_domain {
     };
 }
 
-/// Tie the functions together with their domains.
+// Tie functions together with their domains.
 impl_has_domain! {
     acos => InvTrigPeriodic;
     acosh => ACoshDomain;
     asin => InvTrigPeriodic;
     asinh => Unbounded;
+    // TODO asymptotes
     atan => Unbounded;
     atanh => ATanhDomain;
     cbrt => Unbounded;

crates/libm-test/src/gen/domain.rs

@@ -1,16 +1,14 @@
-/*
-Does the following:
-
-- Check 100 values near each of the bounds
-- If there are defined asymptotes, check those
-- Figure out a number of tests to do within the domain. If exhaustive, check all (but skip
-  NaNs?)
-- Check near zero if defined
-- If unbounded, ensure that real inputs do not produce any NaNs
-- If periodic, check that results are identical for a few periods (?)
-
-
-*/
+//! A generator that makes use of the `Domain` trait
+//!
+//! Does the following:
+//!
+//! - Check 100 values near each of the bounds (default)
+//! - If there are defined asymptotes, check those
+//! - Figure out a number of tests to do within the domain. If exhaustive, check all (but skip
+//!   NaNs?)
+//! - Check near zero if defined
+//! - If unbounded, ensure that real inputs do not produce any NaNs
+//! - If periodic, check that results are identical for a few periods (?)
 
 use std::iter;
 use std::ops::Bound;
@@ -42,15 +40,16 @@ const NTESTS: usize = {
     }
 };
 
-// /// Some functions have infinite asymptotes, limit how many we check.
-// const MAX_ASYMPTOTES: usize = 10;
+/// Some functions have infinite asymptotes, limit how many we check.
+const MAX_ASYMPTOTES: usize = 10;
 
 /// Create a test case iterator.
 pub fn get_test_cases<F: Float, D: Domain<F>>() -> impl Iterator<Item = (F,)>
 where
     F::Int: TryFrom<usize>,
 {
-    // Figure out the ranges we will test on
+    // We generate logspaced inputs within a specific range. Use the function domain
+    // by default but if the function is periodic, check only within that period.
     let (start, end) = D::PERIODIC.unwrap_or(D::DEFINED);
     let range_start = match start {
         Bound::Included(v) => v,
@@ -64,9 +63,12 @@ where
     };
 
     let steps = F::Int::try_from(NTESTS).unwrap_or(F::Int::MAX);
+
+    // Always check near bounds in addition to the logspace
     near_bounds::<F, D>().into_iter().chain(logspace(range_start, range_end, steps)).map(|v| (v,))
 }
 
+/// Create a vector full of values near interesting (bounds, asymptotes, etc).
 fn near_bounds<F: Float, D: Domain<F>>() -> Vec<F> {
     let mut values = Vec::new();
 
@@ -105,15 +107,19 @@ fn near_bounds<F: Float, D: Domain<F>>() -> Vec<F> {
         around(x, &mut values);
     }
 
-    // Max, min, and infinities are interesting
+    // Values around min and max are interesting
+    values.extend(count_up(F::MIN).take(AROUND));
+    values.extend(count_down(F::MAX).take(AROUND));
+
+    // Check some special values that aren't included in the above ranges
+    values.push(F::NAN);
     values.push(F::MIN);
     values.push(F::MAX);
     values.push(F::INFINITY);
     values.push(F::NEG_INFINITY);
     values.push(F::NEG_ZERO);
-    values.extend(count_up(F::MIN).take(AROUND));
-    values.extend(count_down(F::MAX).take(AROUND));
 
+    // Check period endpoints (as we define them) if available
     if let Some((start, end)) = D::PERIODIC {
         validate_bound(start);
         validate_bound(end);
@@ -122,6 +128,8 @@ fn near_bounds<F: Float, D: Domain<F>>() -> Vec<F> {
         around_bound(end, &mut values);
 
         let p = D::period().unwrap();
+
+        // Check the same points for a few period to make sure there is no drift
         for mul in [one / two, one, three / two, two, three] {
             let back = D::period_start() - mul * p;
             let forward = D::period_end() + mul * p;
@@ -131,11 +139,12 @@ fn near_bounds<F: Float, D: Domain<F>>() -> Vec<F> {
         }
     }
 
-    for (from, _to) in D::defined_asymptotes() {
+    // Check around asymptotest
+    for (from, _to) in D::defined_asymptotes().take(MAX_ASYMPTOTES) {
         around(from, &mut values);
     }
 
-    for x in D::check_points() {
+    for x in D::check_points().take(MAX_ASYMPTOTES) {
         around(x, &mut values);
     }
 
@@ -145,7 +154,7 @@ fn near_bounds<F: Float, D: Domain<F>>() -> Vec<F> {
     values
 }
 
-/// Push `AROUND` values up and `AROUND` values down from a value.
+/// Push `AROUND` values up and `AROUND` values down from a value exhaustively (increments ULP).
 fn around<F: Float>(x: F, values: &mut Vec<F>) {
     values.push(x);
     values.extend(count_up(x).take(AROUND));