Changed: expand exact-arithmetic re-exports and adversarial benchmarks

Update the `exact` feature to re-export `BigInt` and essential `num-traits`
(FromPrimitive, ToPrimitive, Signed) alongside `BigRational`. This
simplifies downstream usage by removing the need for direct dependencies
on the `num` ecosystem for common operations.

Additionally, formalize adversarial-input benchmarking for near-singular,
large-entry, and Hilbert matrices to better track performance on
ill-conditioned data. CI benchmark comparisons are now more resilient to
newly added benchmarks via `--baseline-lenient`.

Refs: #80

Author: acgetchell

.github/workflows/benchmarks.yml

@@ -114,8 +114,11 @@ jobs:
 
           if [ -d target/criterion/exact_d2/det/main ]; then
             echo "::notice::Baseline found — comparing against main"
+            # --baseline-lenient rather than --baseline: benches added on the
+            # PR branch that don't yet exist in the main baseline get a
+            # "no baseline data" notice instead of aborting the whole run.
             cargo bench --features bench,exact --bench exact \
-              -- --baseline main 2>&1 | tee bench-output.txt
+              -- --baseline-lenient main 2>&1 | tee bench-output.txt
           else
             echo "::notice::No baseline found — running without comparison"
             cargo bench --features bench,exact --bench exact \

AGENTS.md

@@ -221,7 +221,10 @@ When creating or updating issues:
 
 - `exact` — enables exact arithmetic methods via `BigRational`:
   `det_exact()`, `det_exact_f64()`, `det_sign_exact()`, `solve_exact()`, and `solve_exact_f64()`.
-  Also re-exports `BigRational` from the crate root and prelude.
+  Re-exports `BigInt` and `BigRational` from the crate root and prelude, plus
+  `FromPrimitive`, `ToPrimitive`, and `Signed` from `num-traits` in the prelude
+  (so consumers get usable `from_f64` / `to_f64` / `is_positive` etc. without adding
+  `num-bigint` / `num-rational` / `num-traits` as their own deps).
   Gates `src/exact.rs`, additional tests, and the `exact_det_3x3`/`exact_sign_3x3`/`exact_solve_3x3` examples.
   Clippy, doc builds, and test commands have dedicated `--features exact` variants.
 
@@ -245,7 +248,8 @@ When creating or updating issues:
 - The public API re-exports these items from `src/lib.rs`.
 - The `justfile` defines all dev workflows (see `just --list`).
 - Dev-only benchmarks live in `benches/vs_linalg.rs` (Criterion + nalgebra/faer comparison)
-  and `benches/exact.rs` (exact arithmetic across D=2–5).
+  and `benches/exact.rs` (exact arithmetic across D=2–5, plus adversarial-input groups
+  `exact_near_singular_3x3`, `exact_large_entries_3x3`, `exact_hilbert_4x4`, `exact_hilbert_5x5`).
 - Python scripts under `scripts/`:
   - `bench_compare.py`: exact-arithmetic benchmark comparison across releases (generates `docs/PERFORMANCE.md`)
   - `criterion_dim_plot.py`: benchmark plotting (CSV + SVG + README table update)

README.md

@@ -190,8 +190,13 @@ assert!((x[0] - 1.0).abs() <= f64::EPSILON);
 assert!((x[1] - 2.0).abs() <= f64::EPSILON);
 ```
 
-`BigRational` is re-exported from the crate root and prelude when the `exact`
-feature is enabled, so consumers don't need to depend on `num-rational` directly.
+With the `exact` feature enabled, `BigInt` and `BigRational` are re-exported
+from the crate root and prelude, alongside the most commonly needed
+`num-traits` items (`FromPrimitive`, `ToPrimitive`, `Signed`).  This lets
+consumers construct exact values (`BigRational::from_f64`, `from_i64`), query
+sign (`is_positive` / `is_negative`), and convert back to `f64` (`to_f64`)
+with a single `use la_stack::prelude::*;` — no need to add `num-bigint`,
+`num-rational`, or `num-traits` to their own `Cargo.toml`.
 
 For `det_sign_exact()`, D ≤ 4 matrices use a fast f64 filter (error-bounded
 `det_direct()`) that resolves the sign without allocating.  Only near-degenerate

docs/BENCHMARKING.md

@@ -14,6 +14,20 @@ la-stack has two Criterion benchmark suites:
   (`det_exact`, `solve_exact`, `det_sign_exact`, etc.) alongside f64
   baselines (`det`, `det_direct`) across D=2–5. Use this to understand
   the cost of exact arithmetic and track optimization progress.
+  In addition to the per-dimension groups (`exact_d{2..5}`), the suite
+  includes four adversarial-input groups designed to stress specific
+  corners of the pipeline:
+  - `exact_near_singular_3x3` — a 2^-50 perturbation of a singular base
+    matrix; forces the Bareiss fallback in `det_sign_exact` and
+    exercises the largest intermediate `BigInt` values in `solve_exact`.
+  - `exact_large_entries_3x3` — diagonal entries near `f64::MAX / 2`
+    stress `BigInt` growth during Bareiss forward elimination.
+  - `exact_hilbert_4x4` / `exact_hilbert_5x5` — classically
+    ill-conditioned matrices whose non-terminating-in-binary entries
+    stress the `f64_decompose → BigInt` scaling path.
+  Each adversarial group runs the same four benches (`det_sign_exact`,
+  `det_exact`, `solve_exact`, `solve_exact_f64`) so the resulting tables
+  are directly comparable across input classes.
 
 ## Quick reference
 

src/exact.rs

@@ -2091,9 +2091,12 @@ mod tests {
     }
 
     /// Hilbert matrices are symmetric positive-definite, so
-    /// `det_sign_exact` must return `1` for every D.  For D ≥ 5 the fast
-    /// filter is skipped entirely, so this exercises the Bareiss path on
-    /// inputs whose `(mantissa, exponent)` pairs all differ.
+    /// `det_sign_exact` must return `1` for every D.  For D=2..=4 the
+    /// fast f64 filter resolves the positive sign without falling
+    /// through (Hilbert's determinant is tiny but still well above the
+    /// `det_errbound` cushion); for D=5 the filter is skipped entirely
+    /// and the Bareiss path handles inputs whose `(mantissa, exponent)`
+    /// pairs all differ.
     macro_rules! gen_det_sign_exact_hilbert_positive_tests {
         ($d:literal) => {
             paste! {
@@ -2113,6 +2116,7 @@ mod tests {
         };
     }
 
+    gen_det_sign_exact_hilbert_positive_tests!(2);
     gen_det_sign_exact_hilbert_positive_tests!(3);
     gen_det_sign_exact_hilbert_positive_tests!(4);
     gen_det_sign_exact_hilbert_positive_tests!(5);
@@ -2154,6 +2158,7 @@ mod tests {
         };
     }
 
+    gen_solve_exact_hilbert_residual_tests!(2);
     gen_solve_exact_hilbert_residual_tests!(3);
     gen_solve_exact_hilbert_residual_tests!(4);
     gen_solve_exact_hilbert_residual_tests!(5);

src/lib.rs

@@ -387,4 +387,37 @@ mod tests {
         let _ = m.lu(DEFAULT_PIVOT_TOL).unwrap().solve_vec(v).unwrap();
         let _ = m.ldlt(DEFAULT_SINGULAR_TOL).unwrap().solve_vec(v).unwrap();
     }
+
+    /// Exercise every exact-feature re-export via the prelude so a future
+    /// refactor that drops one (e.g. removing `Signed` from the prelude
+    /// list) fails to compile rather than silently breaking downstream.
+    #[cfg(feature = "exact")]
+    #[test]
+    fn prelude_exact_reexports_compile_and_work() {
+        use crate::prelude::*;
+
+        // `BigInt` and `BigRational` constructors.
+        let n = BigInt::from(7);
+        let r = BigRational::from_integer(n.clone());
+        assert_eq!(*r.numer(), n);
+
+        // `FromPrimitive::from_f64` / `from_i64` on `BigRational`.
+        let half = BigRational::from_f64(0.5).unwrap();
+        let two = BigRational::from_i64(2).unwrap();
+        assert_eq!(
+            half.clone() + half.clone(),
+            BigRational::from_integer(BigInt::from(1))
+        );
+
+        // `Signed::is_positive` / `is_negative` / `abs`.
+        assert!(half.is_positive());
+        assert!(!half.is_negative());
+        let neg = -half.clone();
+        assert!(neg.is_negative());
+        assert_eq!(neg.abs(), half);
+
+        // `ToPrimitive::to_f64` / `to_i64`.
+        assert!((half.to_f64().unwrap() - 0.5).abs() <= f64::EPSILON);
+        assert_eq!(two.to_i64().unwrap(), 2);
+    }
 }