added documentaion

Author: Gaspare99

docs/Documentation.ipynb

@@ -0,0 +1,70 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Documentation \n",
+    "**Disclaimer**: *this document is not meant to be neither a formal nor an exhaustive description of the iterative method to solve the eigenvalue problem. The aim of this text is only to provide the necessary and minimal information needed for the reader to understand the code implementation. We will use these pages to document, explain and justify the choice made from a numerical and scientific computing standpoint*.\n",
+    "\n",
+    "## Problem statement\n",
+    "Given a matrix $\\boldsymbol{A} \\in \\mathbb{C}^{n, n}$, with $n \\in \\mathbb{N}$ the matrix dimension, the eigenvalue problem can be formulated as finding the eigenpair $\\{(\\lambda_i, \\boldsymbol{v}_i)\\}_{i=1} ^ n$, with $\\lambda_i \\in \\mathbb{C}$, $\\boldsymbol{v}_i \\in \\mathbb{C}^{n ,1}$ and $\\boldsymbol{v}_i \\ne \\boldsymbol{0}$ such that \n",
+    "$$\\boldsymbol{A} \\boldsymbol{v}_i = \\lambda_i \\boldsymbol{v}_i, \\quad i=1, 2, ..., n $$\n",
+    "\n",
+    "$\\lambda_i$ are called eigenvalue, while $\\boldsymbol{v}_i$ are the corresponding eigenvectors. Theoretically, finding the matrix's eigenvalue is possible by imposing the following condition:\n",
+    "$$ \\det(A-\\lambda I)=0 $$\n",
+    "which lead to the well known characteristic polynomial of degree $n$. The eigenvalue are the roots of the characteristic polynomial. Although correct, this apporach is not viable, due to the difficulties in both expressing the characteristic polynomial and find its roots, when the Matrix gets very large.\n",
+    "\n",
+    "Numerical methods takle the eigenproblem using a different strategy, most of the time being a iterative methods. Rather than aspire to get the exact solution, they seek after an approximation of the solution, which hopefully, under a set of conditions, converges to the exact solution.\n",
+    "Among all the method devolped to solve the eigenproblem, the power method, along with its variants suct that the inverse power method and power method with shift, and the QR are the widest spread and the most used.\n",
+    "\n",
+    "## Power method\n",
+    "Let $\\boldsymbol{A}$ being a matric and $\\lambda _i$ the eigenvalue already sorted accordingly to their module. If\n",
+    "$$ |\\lambda_1| > |\\lambda _i | \\quad i=2, 3, ..., n$$\n",
+    "then the power method allow to recover the eigenpair $(\\lambda_1, \\boldsymbol{v}_1)$ by applying iteratively, the following steps\n",
+    "\n",
+    "\n",
+    "$$\n",
+    "\\begin{array}{l}\n",
+    "\\textbf{Power Method Algorithm} \\\\\n",
+    "\\textbf{Input:} A \\in \\mathbb{C}^{n \\times n}, \\text{initial vector } x_0, \\text{ tolerance } \\text{tol}, \\text{ max iterations } \\text{max\\_iter} \\\\\n",
+    "\\textbf{Output:} \\lambda \\text{ (dominant eigenvalue approximation), } x \\text{ (eigenvector approximation)} \\\\\n",
+    "\n",
+    "1.\\ \\text{Initialize } x = x_0 \\text{ (random or chosen guess)} \\\\\n",
+    "2.\\ \\text{Normalize } x \\text{: } y^{(1)} = x/ \\| x\\| \\\\\n",
+    "3.\\ \\lambda_{\\text{old}} = 0 \\\\\n",
+    "\n",
+    "4.\\ \\textbf{for } k = 1 \\textbf{ to } \\text{max\\_iter} \\textbf{ do} \\\\\n",
+    "\\quad 5.\\ x^{(k+1)} = A \\cdot y^{(k)} \\\\\n",
+    "\\quad 6.\\  y^{(k+1)} = x^{(k+1)}/ \\| x^{(k+1)}\\|  \\\\\n",
+    "\\quad 7.\\  \\lambda^{(k+1)} =  (y^{(k+1)})^H \\boldsymbol{A} y^{(k+1)} \\\\\n",
+    "\\quad 8.\\ \\textbf{if } |\\lambda^{(k+1)} - \\lambda^{(k)}| < \\text{tol} \\textbf{ then} \\\\\n",
+    "\\quad \\quad \\text{Break (convergence reached)} \\\\\n",
+    "\n",
+    "9.\\ \\textbf{Return } \\lambda, x\n",
+    "\\end{array}\n",
+    "$$\n",
+    "\n",
+    "By exploiting Matrix properties, it is also possible to find the eigenvalue with the smallest norm, and its associated eigenvector, or either the the eigenvalue closest to a given number.\n",
+    "\n",
+    "## QR algorithm\n",
+    "Being the problem we are interested in to solve incolve a symmetric Matrix, we will start introduce the QR alforithm in a general way and specialize it for the case of symmetric matrices as soon as we have the chance.\n",
+    "\n",
+    "The QR algorithm can be divide in to two stages: during the first stage, the matrix is reduced, by means of similar trasformation, into a Hessemberg matrix, or, for Hermetian matrix, into a tridiagonal matrix. Although the QR algorithm can be applied directly to a full matrix, it converges faster if it is applied to Hessemberg Matrix or triagular matrices, with also a smaller computational cost.\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python",
+   "version": "3.12.7"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}