Skip to main content

sparse_ir_sve/
fpu_check.rs

1//! FPU state checking and correction for numerical stability
2//!
3//! This module detects dangerous FPU settings (particularly Flush-to-Zero and
4//! Denormals-Are-Zero flags) that can cause incorrect SVD results when called
5//! from Intel Fortran programs compiled with `-O3` without `-fp-model precise`.
6//!
7//! # Background
8//!
9//! Intel Fortran's `-O3` optimization may set the MXCSR register's FZ and DAZ bits
10//! at program startup for performance. However, this causes problems for SVD
11//! computations that rely on proper handling of denormalized (subnormal) numbers.
12//!
13//! # Usage
14//!
15//! The [`FpuGuard`] RAII guard automatically saves, corrects, and restores FPU state:
16//!
17//! ```
18//! use sparse_ir_sve::unstable::fpu_check::FpuGuard;
19//!
20//! let _guard = FpuGuard::new_protect_computation();
21//! // Computation here - FZ/DAZ are disabled
22//! // FPU state is automatically restored when _guard is dropped
23//! ```
24//!
25//! # Performance
26//!
27//! The `stmxcsr`/`ldmxcsr` instructions are very lightweight (a few CPU cycles),
28//! so the overhead of checking and restoring FPU state is negligible compared
29//! to actual matrix computations.
30
31use once_cell::sync::Lazy;
32use std::sync::atomic::{AtomicBool, Ordering};
33
34/// MXCSR bit positions
35const MXCSR_FZ_BIT: u32 = 15; // Flush to Zero
36const MXCSR_DAZ_BIT: u32 = 6; // Denormals Are Zero
37
38/// Flag to track if warning has been shown (only show once per process)
39static WARNING_SHOWN: AtomicBool = AtomicBool::new(false);
40
41/// Lazy initialization to check FPU state at library load time
42static FPU_CHECK_INIT: Lazy<bool> = Lazy::new(|| {
43    let state = get_fpu_state();
44    if state.is_dangerous() {
45        print_fpu_warning(&state);
46        WARNING_SHOWN.store(true, Ordering::SeqCst);
47        true // dangerous state detected
48    } else {
49        false
50    }
51});
52
53/// Result of FPU state check
54#[derive(Debug, Clone, Copy, PartialEq, Eq)]
55pub struct FpuState {
56    /// Raw MXCSR register value
57    pub mxcsr: u32,
58    /// Flush to Zero flag
59    pub flush_to_zero: bool,
60    /// Denormals Are Zero flag
61    pub denormals_are_zero: bool,
62}
63
64impl FpuState {
65    /// Check if FPU state is dangerous for numerical computation
66    pub fn is_dangerous(&self) -> bool {
67        self.flush_to_zero || self.denormals_are_zero
68    }
69}
70
71impl std::fmt::Display for FpuState {
72    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
73        write!(
74            f,
75            "MXCSR=0x{:08X}, FZ={}, DAZ={}",
76            self.mxcsr, self.flush_to_zero as u8, self.denormals_are_zero as u8
77        )
78    }
79}
80
81/// Print FPU warning message (called only once)
82fn print_fpu_warning(state: &FpuState) {
83    eprintln!();
84    eprintln!("================================================================================");
85    eprintln!("sparse-ir WARNING: Dangerous FPU settings detected!");
86    eprintln!("================================================================================");
87    eprintln!();
88    eprintln!("  Current FPU state: {}", state);
89    eprintln!();
90    eprintln!("  Problem: Flush-to-Zero (FZ) or Denormals-Are-Zero (DAZ) is enabled.");
91    eprintln!("           This causes subnormal numbers to be treated as zero, which");
92    eprintln!("           can produce INCORRECT results in SVD/SVE computations.");
93    eprintln!();
94    eprintln!("  Common cause: Intel Fortran compiler (ifort/ifx) with -O3 optimization");
95    eprintln!("                sets FZ/DAZ flags at program startup for performance.");
96    eprintln!();
97    eprintln!("  Solution: Add '-fp-model precise' flag when compiling your Fortran code:");
98    eprintln!();
99    eprintln!("      ifort -O3 -fp-model precise your_program.f90");
100    eprintln!("      ifx   -O3 -fp-model precise your_program.f90");
101    eprintln!();
102    eprintln!("  For Quantum ESPRESSO/EPW, add to make.inc:");
103    eprintln!();
104    eprintln!("      FFLAGS += -fp-model precise");
105    eprintln!();
106    eprintln!("  Action: sparse-ir will temporarily disable FZ/DAZ during each computation");
107    eprintln!("          and restore the original settings afterward.");
108    eprintln!("          Results will be correct, but please fix the compiler flags");
109    eprintln!("          to avoid this warning.");
110    eprintln!();
111    eprintln!("================================================================================");
112    eprintln!();
113}
114
115/// Get current FPU state (x86/x86_64 only)
116#[cfg(any(target_arch = "x86_64", target_arch = "x86"))]
117pub fn get_fpu_state() -> FpuState {
118    let mut mxcsr: u32 = 0;
119    unsafe {
120        std::arch::asm!(
121            "stmxcsr [{}]",
122            in(reg) &mut mxcsr,
123            options(nostack)
124        );
125    }
126
127    FpuState {
128        mxcsr,
129        flush_to_zero: (mxcsr >> MXCSR_FZ_BIT) & 1 != 0,
130        denormals_are_zero: (mxcsr >> MXCSR_DAZ_BIT) & 1 != 0,
131    }
132}
133
134/// Get current FPU state (non-x86 fallback)
135#[cfg(not(any(target_arch = "x86_64", target_arch = "x86")))]
136pub fn get_fpu_state() -> FpuState {
137    // On non-x86 platforms, assume safe defaults
138    FpuState {
139        mxcsr: 0,
140        flush_to_zero: false,
141        denormals_are_zero: false,
142    }
143}
144
145/// Set MXCSR register value (x86/x86_64 only)
146#[cfg(any(target_arch = "x86_64", target_arch = "x86"))]
147fn set_mxcsr(value: u32) {
148    unsafe {
149        std::arch::asm!(
150            "ldmxcsr [{}]",
151            in(reg) &value,
152            options(nostack)
153        );
154    }
155}
156
157/// Set MXCSR register value (non-x86 fallback - no-op)
158#[cfg(not(any(target_arch = "x86_64", target_arch = "x86")))]
159fn set_mxcsr(_value: u32) {
160    // No-op on non-x86 platforms
161}
162
163/// Initialize FPU check (call this early to trigger warning if needed)
164///
165/// This function triggers the lazy initialization which checks FPU state
166/// and prints a warning if dangerous settings are detected.
167/// The warning is only printed once per process.
168pub fn init_fpu_check() {
169    let _ = *FPU_CHECK_INIT;
170}
171
172/// The calling thread's FPU control state (MXCSR on x86), to apply to the
173/// work the library hands to other threads
174///
175/// The FPU state is per thread: a newly spawned thread does not reliably
176/// start from its parent's, and a pool thread keeps whatever state it has.
177/// Running every such piece of work under the state of the thread that hands
178/// it out (with [`FpuContext::run`]) makes the threaded paths compute exactly
179/// what the serial ones would, whether or not the caller holds an
180/// [`FpuGuard`]. A no-op on other architectures. Used only with the
181/// `parallel` feature.
182#[cfg_attr(not(feature = "parallel"), allow(dead_code))]
183#[derive(Debug, Clone, Copy)]
184pub(crate) struct FpuContext {
185    mxcsr: u32,
186}
187
188#[cfg_attr(not(feature = "parallel"), allow(dead_code))]
189impl FpuContext {
190    /// The state of the calling thread
191    pub(crate) fn current() -> Self {
192        Self {
193            mxcsr: get_fpu_state().mxcsr,
194        }
195    }
196
197    /// Run `f` under this state, restoring the thread's own afterwards
198    pub(crate) fn run<R>(self, f: impl FnOnce() -> R) -> R {
199        struct Restore(u32);
200        impl Drop for Restore {
201            fn drop(&mut self) {
202                set_mxcsr(self.0);
203            }
204        }
205        let _restore = Restore(get_fpu_state().mxcsr);
206        set_mxcsr(self.mxcsr);
207        f()
208    }
209}
210
211/// RAII guard that protects a computation from dangerous FPU settings
212///
213/// On creation:
214/// 1. Triggers one-time FPU check and warning (if not already done)
215/// 2. If FZ or DAZ is enabled, disables them temporarily
216///
217/// On drop:
218/// - Restores the original FPU state
219///
220/// # Example
221///
222/// ```
223/// use sparse_ir_sve::unstable::fpu_check::{FpuGuard, get_fpu_state};
224///
225/// let before = get_fpu_state();
226/// {
227///     let _guard = FpuGuard::new_protect_computation();
228///     // Computation here - FZ/DAZ are disabled
229///     assert!(!get_fpu_state().is_dangerous());
230///     let subnormal = std::hint::black_box(f64::MIN_POSITIVE) / 2.0;
231///     assert!(subnormal > 0.0); // not flushed to zero
232/// } // Original FPU state is restored here
233/// let after = get_fpu_state();
234/// assert_eq!(after.flush_to_zero, before.flush_to_zero);
235/// assert_eq!(after.denormals_are_zero, before.denormals_are_zero);
236/// ```
237///
238/// # Performance
239///
240/// The overhead is negligible (a few CPU cycles for stmxcsr/ldmxcsr).
241pub struct FpuGuard {
242    original_mxcsr: u32,
243    needs_restore: bool,
244}
245
246impl FpuGuard {
247    /// Create a new guard that protects computation from FZ/DAZ
248    ///
249    /// - Triggers one-time warning if dangerous FPU settings are detected
250    /// - Temporarily disables FZ/DAZ if they are enabled
251    /// - Restores original state when dropped
252    pub fn new_protect_computation() -> Self {
253        // Trigger one-time FPU check and warning
254        let _ = *FPU_CHECK_INIT;
255
256        let state = get_fpu_state();
257        let original_mxcsr = state.mxcsr;
258
259        if state.is_dangerous() {
260            // Clear FZ and DAZ bits
261            let safe_mxcsr = original_mxcsr & !((1 << MXCSR_FZ_BIT) | (1 << MXCSR_DAZ_BIT));
262            set_mxcsr(safe_mxcsr);
263
264            Self {
265                original_mxcsr,
266                needs_restore: true,
267            }
268        } else {
269            Self {
270                original_mxcsr,
271                needs_restore: false,
272            }
273        }
274    }
275
276    /// Check if the guard needed to modify FPU state
277    pub fn was_modified(&self) -> bool {
278        self.needs_restore
279    }
280}
281
282impl Drop for FpuGuard {
283    fn drop(&mut self) {
284        if self.needs_restore {
285            // Restore original FPU state
286            set_mxcsr(self.original_mxcsr);
287        }
288    }
289}
290
291#[cfg(test)]
292mod tests {
293    use super::*;
294
295    #[test]
296    fn fpu_context_runs_the_closure() {
297        let context = FpuContext::current();
298        let value = std::thread::spawn(move || context.run(|| 6 * 7))
299            .join()
300            .unwrap();
301        assert_eq!(value, 42);
302    }
303
304    /// Work run under a context sees the spawning thread's FZ/DAZ, and the
305    /// worker's own state is restored afterwards.
306    #[cfg(any(target_arch = "x86_64", target_arch = "x86"))]
307    #[test]
308    fn fpu_context_carries_the_state_to_another_thread() {
309        let original = get_fpu_state().mxcsr;
310        let dangerous = original | (1 << MXCSR_FZ_BIT) | (1 << MXCSR_DAZ_BIT);
311        set_mxcsr(dangerous);
312        let context = FpuContext::current();
313        set_mxcsr(original);
314
315        let (inside, after) = std::thread::spawn(move || {
316            let inside = context.run(get_fpu_state);
317            (inside, get_fpu_state())
318        })
319        .join()
320        .unwrap();
321        assert!(inside.flush_to_zero && inside.denormals_are_zero);
322        assert!(!after.flush_to_zero && !after.denormals_are_zero);
323    }
324
325    #[test]
326    fn test_get_fpu_state() {
327        let state = get_fpu_state();
328        // Just verify we can read the state without panicking
329        println!("Current FPU state: {}", state);
330    }
331
332    #[test]
333    fn test_fpu_guard_creation() {
334        let guard = FpuGuard::new_protect_computation();
335        // Guard should be created successfully
336        drop(guard);
337    }
338
339    #[test]
340    fn test_fpu_state_display() {
341        let state = FpuState {
342            mxcsr: 0x1F80,
343            flush_to_zero: false,
344            denormals_are_zero: false,
345        };
346        let display = format!("{}", state);
347        assert!(display.contains("MXCSR=0x00001F80"));
348        assert!(display.contains("FZ=0"));
349        assert!(display.contains("DAZ=0"));
350    }
351
352    #[test]
353    fn test_fpu_state_dangerous() {
354        let safe_state = FpuState {
355            mxcsr: 0x1F80,
356            flush_to_zero: false,
357            denormals_are_zero: false,
358        };
359        assert!(!safe_state.is_dangerous());
360
361        let dangerous_fz = FpuState {
362            mxcsr: 0x9F80,
363            flush_to_zero: true,
364            denormals_are_zero: false,
365        };
366        assert!(dangerous_fz.is_dangerous());
367
368        let dangerous_daz = FpuState {
369            mxcsr: 0x1FC0,
370            flush_to_zero: false,
371            denormals_are_zero: true,
372        };
373        assert!(dangerous_daz.is_dangerous());
374    }
375
376    #[cfg(any(target_arch = "x86_64", target_arch = "x86"))]
377    #[test]
378    fn test_fpu_guard_restores_state() {
379        let original_state = get_fpu_state();
380
381        {
382            let _guard = FpuGuard::new_protect_computation();
383            // State might be modified here
384        }
385
386        let restored_state = get_fpu_state();
387        assert_eq!(original_state.mxcsr, restored_state.mxcsr);
388    }
389}