diff --git a/docs/make.jl b/docs/make.jl index 422b3487..c617fe54 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -23,6 +23,7 @@ makedocs( ], "Eigenproblems" => [ "Power method" => "eigenproblems/power_method.md", + "LOBPCG" => "eigenproblems/lobpcg.md" ], "SVDL" => "svd/svdl.md", "The iterator approach" => "iterators.md", @@ -37,7 +38,7 @@ deploydocs( repo = "github.com/JuliaMath/IterativeSolvers.jl.git", target = "build", osname = "linux", - julia = "0.6", + julia = "0.7", deps = nothing, make = nothing, ) diff --git a/docs/src/eigenproblems/lobpcg.md b/docs/src/eigenproblems/lobpcg.md new file mode 100644 index 00000000..609ca0fd --- /dev/null +++ b/docs/src/eigenproblems/lobpcg.md @@ -0,0 +1,22 @@ +# [Locally optimal block preconditioned conjugate gradient (LOBPCG)](@id LOBPCG) + +Solves the generalized eigenproblem $Ax = λBx$ approximately where $A$ and $B$ are Hermitian linear maps, and $B$ is positive definite. $B$ is taken to be the identity by default. It can find the smallest (or largest) `k` eigenvalues and their corresponding eigenvectors which are B-orthonormal. It also admits a preconditioner and a "constraints" matrix `C`, such that the algorithm returns the smallest (or largest) eigenvalues associated with the eigenvectors in the nullspace of `C'B`. + +## Usage + +```@docs +lobpcg +lobpcg! +``` + +## Implementation Details + +A `LOBPCGIterator` is created to pre-allocate all the memory required by the method using the constructor `LOBPCGIterator(A, B, largest, X, P, C)` where `A` and `B` are the matrices from the generalized eigenvalue problem, `largest` indicates if the problem is a maximum or minimum eigenvalue problem, `X` is the initial eigenbasis, randomly sampled if not input, where `size(X, 2)` is the block size `bs`. `P` is the preconditioner, `nothing` by default, and `C` is the constraints matrix. The desired `k` eigenvalues are found `bs` at a time. + + +## References +Implementation is based on [^Knyazev1993] and [^Scipy]. + +[^Knyazev1993]: Andrew V. Knyazev. "Toward the Optimal Preconditioned Eigensolver: Locally Optimal Block Preconditioned Conjugate Gradient Method" SIAM Journal on Scientific Computing, 23(2):517–541 2001. + +[^Scipy]: See [Scipy LOBPCG implementation](https://github.com/scipy/scipy/blob/v1.1.0/scipy/sparse/linalg/eigen/lobpcg/lobpcg.py#L109-L568)