Add basic documentation for eigh module

lax/src/eigh.rs

@@ -14,7 +14,7 @@ pub trait Eigh_: Scalar {
         a: &mut [Self],
     ) -> Result<Vec<Self::Real>>;
 
-    /// Wraps `*syegv` for real and `*heegv` for complex
+    /// Wraps `*sygv` for real and `*hegv` for complex
     fn eigh_generalized(
         calc_eigenvec: bool,
         layout: MatrixLayout,

ndarray-linalg/src/eigh.rs

@@ -1,4 +1,37 @@
-//! Eigenvalue decomposition for Hermite matrices
+//! Eigendecomposition for Hermitian matrices.
+//!
+//! For a Hermitian matrix `A`, this solves the eigenvalue problem `A V = V D`
+//! for `D` and `V`, where `D` is the diagonal matrix of eigenvalues in
+//! ascending order and `V` is the orthonormal matrix of corresponding
+//! eigenvectors.
+//!
+//! For a pair of Hermitian matrices `A` and `B` where `B` is also positive
+//! definite, this solves the generalized eigenvalue problem `A V = B V D`,
+//! where `D` is the diagonal matrix of generalized eigenvalues in ascending
+//! order and `V` is the matrix of corresponding generalized eigenvectors. The
+//! matrix `V` is normalized such that `V^H B V = I`.
+//!
+//! # Example
+//!
+//! Find the eigendecomposition of a Hermitian (or real symmetric) matrix.
+//!
+//! ```
+//! use approx::assert_abs_diff_eq;
+//! use ndarray::{array, Array2};
+//! use ndarray_linalg::{Eigh, UPLO};
+//!
+//! let a: Array2<f64> = array![
+//!     [2., 1.],
+//!     [1., 2.],
+//! ];
+//! let (eigvals, eigvecs) = a.eigh(UPLO::Lower)?;
+//! assert_abs_diff_eq!(eigvals, array![1., 3.]);
+//! assert_abs_diff_eq!(
+//!     a.dot(&eigvecs),
+//!     eigvecs.dot(&Array2::from_diag(&eigvals)),
+//! );
+//! # Ok::<(), Box<dyn std::error::Error>>(())
+//! ```
 
 use ndarray::*;