From 440d4a4681f52216ee0398356c46ed366f46ab4e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Crozet?= <sebcrozet@dimforge.com>
Date: Thu, 28 Mar 2024 15:07:05 +0100
Subject: [PATCH] chore: add comment providing details on the householder fix.

---
 src/linalg/householder.rs | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/src/linalg/householder.rs b/src/linalg/householder.rs
index 13385035..ef94e929 100644
--- a/src/linalg/householder.rs
+++ b/src/linalg/householder.rs
@@ -34,7 +34,17 @@ pub fn reflection_axis_mut<T: ComplexField, D: Dim, S: StorageMut<T, D>>(
 
     if !factor.is_zero() {
         column.unscale_mut(factor.sqrt());
+
+        // Normalize again, making sure the vector is unit-sized.
+        // If `factor` had a very small value, the first normalization
+        // (dividing by `factor.sqrt()`) might end up with a slightly
+        // non-unit vector (especially when using 32-bits float).
+        // Decompositions strongly rely on that unit-vector property,
+        // so we run a second normalization (that is much more numerically
+        // stable since the norm is close to 1) to ensure it has a unit
+        // size.
         let _ = column.normalize_mut();
+
         (-signed_norm, true)
     } else {
         // TODO: not sure why we don't have a - sign here.