From 76e00682b2fcc557f24af9db7629d1c868bdf93c Mon Sep 17 00:00:00 2001
From: Elizabeth Hunt <elizabeth.hunt@simponic.xyz>
Date: Mon, 27 Nov 2023 13:32:05 -0700
Subject: [PATCH] add lizfcm api doc entry for least dominant eigenvalue

---
 doc/software_manual.org | 46 +++++++++++++++++++++++++++++++++++++++++
 homeworks/hw-7.org      | 12 +++++++++++
 notes/Nov-27.org        |  2 ++
 3 files changed, 60 insertions(+)

diff --git a/doc/software_manual.org b/doc/software_manual.org
index 134d38d..1520431 100644
--- a/doc/software_manual.org
+++ b/doc/software_manual.org
@@ -1035,6 +1035,52 @@ double dominant_eigenvalue(Matrix_double *m, Array_double *v, double tolerance,
   return lambda;
 }
 #+END_SRC
+*** ~least_dominant_eigenvalue~
++ Author: Elizabeth Hunt
++ Name: ~least_dominant_eigenvalue~
++ Location: ~src/eigen.c~
++ Input: a pointer to an invertible matrix ~m~, an initial eigenvector guess ~v~ (that is non
+  zero or orthogonal to an eigenvector with the dominant eigenvalue), a ~tolerance~ and
+  ~max_iterations~ that act as stop conditions
++ Output: the least dominant eigenvalue with the lowest magnitude, approximated with the Inverse
+  Power Iteration Method
+#+BEGIN_SRC c
+double least_dominant_eigenvalue(Matrix_double *m, Array_double *v,
+                                 double tolerance, size_t max_iterations) {
+  assert(m->rows == m->cols);
+  assert(m->rows == v->size);
+
+  double shift = 0.0;
+  Matrix_double *m_c = copy_matrix(m);
+  for (size_t y = 0; y < m_c->rows; ++y)
+    m_c->data[y]->data[y] = m_c->data[y]->data[y] - shift;
+
+  double error = tolerance;
+  size_t iter = max_iterations;
+  double lambda = shift;
+  Array_double *eigenvector_1 = copy_vector(v);
+
+  while (error >= tolerance && (--iter) > 0) {
+    Array_double *eigenvector_2 = solve_matrix_lu_bsubst(m_c, eigenvector_1);
+    Array_double *normalized_eigenvector_2 =
+        scale_v(eigenvector_2, 1.0 / linf_norm(eigenvector_2));
+    free_vector(eigenvector_2);
+    eigenvector_2 = normalized_eigenvector_2;
+
+    Array_double *mx = m_dot_v(m, eigenvector_2);
+    double new_lambda =
+        v_dot_v(mx, eigenvector_2) / v_dot_v(eigenvector_2, eigenvector_2);
+
+    error = fabs(new_lambda - lambda);
+    lambda = new_lambda;
+    free_vector(eigenvector_1);
+    eigenvector_1 = eigenvector_2;
+  }
+
+  return lambda;
+}
+#+END_SRC
+
 *** ~leslie_matrix~
 + Author: Elizabeth Hunt
 + Name: ~leslie_matrix~
diff --git a/homeworks/hw-7.org b/homeworks/hw-7.org
index 1a5ebb0..dbdf6bb 100644
--- a/homeworks/hw-7.org
+++ b/homeworks/hw-7.org
@@ -12,4 +12,16 @@ See ~UTEST(eigen, leslie_matrix_dominant_eigenvalue)~ in ~test/eigen.t.c~
 and the entry ~Eigen-Adjacent -> leslie_matrix~ in the LIZFCM API
 documentation.
 * Question Three
+See ~UTEST(eigen, least_dominant_eigenvalue)~ in ~test/eigen.t.c~ which
+finds the least dominant eigenvalue on the matrix:
 
+\begin{bmatrix}
+2 & 2 & 4 \\
+1 & 4 & 7 \\
+0 & 2 & 6 
+\end{bmatrix}
+
+which has eigenvalues: $5 + \sqrt{17}, 2, 5 - \sqrt{17}$ and should produce $\sqrt{17}$.
+
+See also the entry ~Eigen-Adjacent -> least_dominant_eigenvalue~ in the LIZFCM API
+documentation.
diff --git a/notes/Nov-27.org b/notes/Nov-27.org
index c4d38b0..ae4ded0 100644
--- a/notes/Nov-27.org
+++ b/notes/Nov-27.org
@@ -14,5 +14,7 @@ x^{k + 1} \rightarrow Ax^k
       }
       x_1[i] = sum / a[i][i];
     }
+
+    err = 0.0;
   }
 #+END_SRC