From 9e25a4f9478badac014107d37fe18aeba936bb8c Mon Sep 17 00:00:00 2001
From: saudz <saud.zahir@soco-engineers.com>
Date: Sun, 1 Sep 2024 19:19:20 +0500
Subject: [PATCH] Add docs

---
 README.md          | 38 +++++++++++++++++++++++++++-
 docs/docs/index.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/mkdocs.yml    | 18 ++++++++++++++
 3 files changed, 117 insertions(+), 1 deletion(-)
 create mode 100644 docs/docs/index.md
 create mode 100644 docs/mkdocs.yml

diff --git a/README.md b/README.md
index 1579e39..9b924e1 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,38 @@
 # vonMises
-von Mises Iteration
\ No newline at end of file
+
+vonMises is a numerical algorithm for solving eigenvalue problems using the deflation method and power iteration. It is implemented in C++ and wrapped for Python using [scikit-build](https://scikit-build.readthedocs.io/) (skbuild) to provide a high-performance solution for eigenvalue computations in Python environments.
+
+## Features
+
+- Solves eigenvalue problems using **Von Mises iteration** and **Rayleigh Quotient** methods.
+- Supports deflation for computing multiple eigenvalues and eigenvectors.
+- High-performance implementation using **Eigen3** and **OpenMP**.
+- Extensive logging and debugging support via the **fmt** library.
+
+## Installation
+
+You can install vonMises via pip:
+
+```bash
+pip install vonMises
+```
+
+Make sure you have the required dependencies in your environment, especially **Eigen3** and **fmt** libraries.
+
+## Building from Source
+
+To build vonMises from source, ensure you have **CMake**, **Eigen3**, and **fmt** installed. The project uses **scikit-build** to handle the Python build and installation process. You can clone the repository and build the project as follows:
+
+```bash
+git clone https://github.com/your-username/vonMises.git
+cd vonMises
+pip install .
+```
+
+## License
+
+vonMises is licensed under the MIT License. See [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Contributions are welcome! Feel free to submit issues or pull requests.
diff --git a/docs/docs/index.md b/docs/docs/index.md
new file mode 100644
index 0000000..67cfcf3
--- /dev/null
+++ b/docs/docs/index.md
@@ -0,0 +1,62 @@
+# vonMises
+
+The **vonMises** solves the eigenvalue problem using a combination of the Power Iteration 
+method and Rayleigh Quotient to compute both the dominant eigenvalue and its associated eigenvector. 
+The algorithm uses *deflation* to remove previously computed eigenvalues from the matrix.
+
+## Power Iteration Method
+
+The Power Iteration method is used to compute the largest eigenvalue of a matrix \( A \) and its corresponding 
+eigenvector. The steps are as follows:
+
+1. Initialize with a random vector \( x_0 \).
+2. Normalize \( x_0 \) to have a unit norm.
+3. Iteratively compute \( x_{k+1} = A x_k \) and normalize the resulting vector.
+
+The process converges when \( x_k \) stabilizes. The largest eigenvalue \( \lambda \) is computed by:
+
+\[
+\lambda = \frac{x_k^T A x_k}{x_k^T x_k}
+\]
+
+## Rayleigh Quotient
+
+The Rayleigh Quotient is defined as:
+
+\[
+R(x) = \frac{x^T A x}{x^T x}
+\]
+
+This method refines the computed eigenvalue after performing the Power Iteration.
+
+## Complete Algorithm
+
+The vonMises algorithm combines Power Iteration with Rayleigh Quotient and deflation:
+
+```python
+Algorithm vonMises(A):
+    for a in range(n):
+        x = power_iteration(A)
+        λ = rayleigh_quotient(A, x)
+        A = A - λ * (x @ x.T)
+```
+
+The algorithm repeats until all eigenvalues and eigenvectors are computed.
+
+## Deflation
+
+After finding each eigenvalue and eigenvector pair \( (\lambda, x) \), the matrix \( A \) is deflated by subtracting the rank-1 update:
+
+\[
+A = A - \lambda \cdot (x \cdot x^T)
+\]
+
+This ensures that subsequent iterations of the algorithm find the next largest eigenvalue of the matrix.
+
+## Example
+
+Given a matrix \( A \), the vonMises algorithm computes its eigenvalues and eigenvectors as follows:
+
+1. Power Iteration is applied to find the largest eigenvalue \( \lambda_1 \) and its corresponding eigenvector \( x_1 \).
+2. The matrix is deflated: \( A = A - \lambda_1 \cdot (x_1 \cdot x_1^T) \).
+3. The process is repeated for the remaining matrix to compute the next largest eigenvalue and eigenvector.
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
new file mode 100644
index 0000000..67d8df3
--- /dev/null
+++ b/docs/mkdocs.yml
@@ -0,0 +1,18 @@
+site_name: vonMises
+site_url: https://saudzahirr.github.io/vonMises
+theme:
+  name: material
+  features:
+    - navigation.tabs
+    - navigation.sections
+extra_javascript:
+  - https://polyfill.io/v3/polyfill.min.js?features=es6
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
+  - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/MathJax.js?config=TeX-MML-AM_CHTML
+
+markdown_extensions:
+  - admonition
+  - codehilite
+  - toc:
+      permalink: true
+  - pymdownx.arithmatex