#
# = Eigensystems
# === Contentes
# 1. {Modules and classes}[link:eigen_rdoc.html#label-Modules+and+classes]
# 1. {Real Symmetric Matrices}[link:eigen_rdoc.html#label-Real+Symmetric+Matrices]
# 1. {Complex Hermitian Matrices}[link:eigen_rdoc.html#label-Complex+Hermitian+Matrices]
# 1. {Real Nonsymmetric Matrices}[link:eigen_rdoc.html#label-Real+Nonsymmetric+Matrices+%28%3E%3D+GSL-1.9%29] (>= GSL-1.9)
# 1. {Real Generalized Symmetric-Definite Eigensystems}[link:eigen_rdoc.html#label-Real+Generalized+Symmetric-Definite+Eigensystems+%28GSL-1.10%29] (>= GSL-1.10)
# 1. {Complex Generalized Hermitian-Definite Eigensystems}[link:eigen_rdoc.html#label-Complex+Generalized+Hermitian-Definite+Eigensystems+%28%3E%3D+GSL-1.10%29] (>= GSL-1.10)
# 1. {Real Generalized Nonsymmetric Eigensystems}[link:eigen_rdoc.html#label-Real+Generalized+Nonsymmetric+Eigensystems+%28%3E%3D+GSL-1.10%29] (>= GSL-1.10)
# 1. {Sorting Eigenvalues and Eigenvectors }[link:eigen_rdoc.html#label-Sorting+Eigenvalues+and+Eigenvectors]
#
# == Modules and classes
#
# * GSL
#   * Eigen
#     * EigenValues < Vector
#     * EigenVectors < Matrix
#     * Symm (Module)
#       * Workspace (Class)
#     * Symmv (Module)
#       * Workspace (Class)
#     * Nonsymm (Module, >= GSL-1.9)
#       * Workspace (Class)
#     * Nonsymmv (Module, >= GSL-1.9)
#       * Workspace (Class)
#     * Gensymm (Module, >= GSL-1.10)
#       * Workspace (Class)
#     * Gensymmv (Module, >= GSL-1.10)
#       * Workspace (Class)
#     * Herm (Module)
#       * Workspace (Class)
#     * Hermv (Module)
#       * Workspace (Class)
#       * Vectors < Matrix::Complex
#     * Genherm (Module, >= GSL-1.10)
#       * Workspace (Class)
#     * Genhermv (Module, >= GSL-1.10)
#       * Workspace (Class)
#     * Gen (Module, >= GSL-1.10)
#       * Workspace (Class)
#     * Genv (Module, >= GSL-1.10)
#       * Workspace (Class)
#
# == Real Symmetric Matrices
# === Workspace classes
# ---
# * GSL::Eigen::Symm::Workspace.alloc(n)
# * GSL::Eigen::Symmv::Workspace.alloc(n)
# * GSL::Eigen::Herm::Workspace.alloc(n)
# * GSL::Eigen::Hermv::Workspace.alloc(n)
#
#
# === Methods to solve eigensystems
# ---
# * GSL::Eigen::symm(A)
# * GSL::Eigen::symm(A, workspace)
# * GSL::Matrix#eigen_symm
# * GSL::Matrix#eigen_symm(workspace)
#
#   These methods compute the eigenvalues of the real symmetric matrix.
#   The workspace object <tt>workspace</tt> can be omitted.
#
# ---
# * GSL::Eigen::symmv(A)
# * GSL::Matrix#eigen_symmv
#
#   These methods compute the eigenvalues and eigenvectors of the real symmetric
#   matrix, and return an array of two elements:
#   The first is a <tt>GSL::Vector</tt> object which stores all the eigenvalues.
#   The second is a <tt>GSL::Matrix object</tt>, whose columns contain
#   eigenvectors.
#
# 1. Singleton method of the <tt>GSL::Eigen</tt> module, <tt>GSL::Eigen::symm</tt>
#
#         m = GSL::Matrix.alloc([1.0, 1/2.0, 1/3.0, 1/4.0], [1/2.0, 1/3.0, 1/4.0, 1/5.0],
#                            [1/3.0, 1/4.0, 1/5.0, 1/6.0], [1/4.0, 1/5.0, 1/6.0, 1/7.0])
#         eigval, eigvec = Eigen::symmv(m)
#
# 1. Instance method of <tt>GSL::Matrix</tt> class
#
#         eigval, eigvec = m.eigen_symmv
#
# == Complex Hermitian Matrices
# ---
# * GSL::Eigen::herm(A)
# * GSL::Eigen::herm(A, workspace)
# * GSL::Matrix::Complex#eigen_herm
# * GSL::Matrix::Complex#eigen_herm(workspace)
#
#   These methods compute the eigenvalues of the complex hermitian matrix.
#
# ---
# * GSL::Eigen::hermv(A)
# * GSL::Eigen::hermv(A, workspace)
# * GSL::Matrix::Complex#eigen_hermv
# * GSL::Matrix::Complex#eigen_hermv(workspace
#
#
# == Real Nonsymmetric Matrices (>= GSL-1.9)
#
# ---
# * GSL::Eigen::Nonsymm.alloc(n)
#
#   This allocates a workspace for computing eigenvalues of n-by-n real
#   nonsymmetric matrices. The size of the workspace is O(2n).
#
# ---
# * GSL::Eigen::Nonsymm::params(compute_t, balance, wspace)
# * GSL::Eigen::Nonsymm::Workspace#params(compute_t, balance)
#
#   This method sets some parameters which determine how the eigenvalue
#   problem is solved in subsequent calls to <tt>GSL::Eigen::nonsymm</tt>.
#   If <tt>compute_t</tt> is set to 1, the full Schur form <tt>T</tt> will be
#   computed by gsl_eigen_nonsymm. If it is set to 0, <tt>T</tt> will not be
#   computed (this is the default setting).
#   Computing the full Schur form <tt>T</tt> requires approximately 1.5-2 times
#   the number of flops.
#
#   If <tt>balance</tt> is set to 1, a balancing transformation is applied to
#   the matrix prior to computing eigenvalues. This transformation is designed
#   to make the rows and columns of the matrix have comparable norms, and can
#   result in more accurate eigenvalues for matrices whose entries vary widely
#   in magnitude. See section Balancing for more information. Note that the
#   balancing transformation does not preserve the orthogonality of the Schur
#   vectors, so if you wish to compute the Schur vectors with
#   <tt>GSL::Eigen::nonsymm_Z</tt> you will obtain the Schur vectors of the
#   balanced matrix instead of the original matrix. The relationship will be
#   where Q is the matrix of Schur vectors for the balanced matrix, and <tt>D</tt>
#   is the balancing transformation. Then <tt>GSL::Eigen::nonsymm_Z</tt> will
#   compute a matrix <tt>Z</tt> which satisfies with <tt>Z = D Q</tt>.
#   Note that <tt>Z</tt> will not be orthogonal. For this reason, balancing is
#   not performed by default.
#
# ---
# * GSL::Eigen::nonsymm(m, eval, wspace)
# * GSL::Eigen::nonsymm(m)
# * GSL::Matrix#eigen_nonsymm()
# * GSL::Matrix#eigen_nonsymm(wspace)
# * GSL::Matrix#eigen_nonsymm(eval, wspace)
#
#   These methods compute the eigenvalues of the real nonsymmetric matrix <tt>m</tt>
#   and return them, or store in the vector <tt>eval</tt> if it given.
#   If <tt>T</tt> is desired, it is stored in <tt>m</tt> on output, however the lower
#   triangular portion will not be zeroed out. Otherwise, on output, the diagonal
#   of <tt>m</tt> will contain the 1-by-1 real eigenvalues and 2-by-2 complex
#   conjugate eigenvalue systems, and the rest of <tt>m</tt> is destroyed.
#
# ---
# * GSL::Eigen::nonsymm_Z(m, eval, Z, wspace)
# * GSL::Eigen::nonsymm_Z(m)
# * GSL::Matrix#eigen_nonsymm_Z()
# * GSL::Matrix#eigen_nonsymm(eval, Z, wspace)
#
#   These methods are identical to <tt>GSL::Eigen::nonsymm</tt> except they also
#   compute the Schur vectors and return them (or store into <tt>Z</tt>).
#
# ---
# * GSL::Eigen::Nonsymmv.alloc(n)
#
#   Allocates a workspace for computing eigenvalues and eigenvectors
#   of n-by-n real nonsymmetric matrices. The size of the workspace is O(5n).
# ---
# * GSL::Eigen::nonsymm(m)
# * GSL::Eigen::nonsymm(m, wspace)
# * GSL::Eigen::nonsymm(m, eval, evec)
# * GSL::Eigen::nonsymm(m, eval, evec, wspace)
# * GSL::Matrix#eigen_nonsymmv()
# * GSL::Matrix#eigen_nonsymmv(wspace)
# * GSL::Matrix#eigen_nonsymmv(eval, evec)
# * GSL::Matrix#eigen_nonsymmv(eval, evec, wspace)
#
#   Compute eigenvalues and right eigenvectors of the n-by-n real nonsymmetric
#   matrix. The computed eigenvectors are normalized to have Euclidean norm 1.
#   On output, the upper portion of <tt>m</tt> contains the Schur form <tt>T</tt>.
#
# == Real Generalized Symmetric-Definite Eigensystems (GSL-1.10)
# The real generalized symmetric-definite eigenvalue problem is to
# find eigenvalues <tt>lambda</tt> and eigenvectors <tt>x</tt> such that
# where <tt>A</tt> and <tt>B</tt> are symmetric matrices, and <tt>B</tt>
# is positive-definite. This problem reduces to the standard symmetric eigenvalue
# problem by applying the Cholesky decomposition to <tt>B</tt>:
# Therefore, the problem becomes <tt>C y = lambda y</tt>
# where <tt>C = L^{-1} A L^{-t}</tt> is symmetric, and <tt>y = L^t x</tt>.
# The standard symmetric eigensolver can be applied to the matrix <tt>C</tt>.
# The resulting eigenvectors are backtransformed to find the vectors of the
# original problem. The eigenvalues and eigenvectors of the generalized
# symmetric-definite eigenproblem are always real.
#
# ---
# * GSL::Eigen::Gensymm.alloc(n)
# * GSL::Eigen::Gensymm::Workspace.alloc(n)
#
#   Allocates a workspace for computing eigenvalues of n-by-n real
#   generalized symmetric-definite eigensystems.
#   The size of the workspace is O(2n).
# ---
# * GSL::Eigen::gensymm(A, B, w)
#
#   Computes the eigenvalues of the real generalized symmetric-definite matrix
#   pair <tt>A, B</tt>, and returns them as a <tt>GSL::Vector</tt>,
#   using the method outlined above. On output, B contains its Cholesky
#   decomposition.
# ---
# * GSL::Eigen::gensymmv(A, B, w)
#
#   Computes the eigenvalues and eigenvectors of the real generalized
#   symmetric-definite matrix pair <tt>A, B</tt>, and returns
#   them as a <tt>GSL::Vector</tt> and a <tt>GSL::Matrix</tt>.
#   The computed eigenvectors are normalized to have unit magnitude.
#   On output, <tt>B</tt> contains its Cholesky decomposition.
#
# == Complex Generalized Hermitian-Definite Eigensystems (>= GSL-1.10)
# The complex generalized hermitian-definite eigenvalue problem is to
# find eigenvalues <tt>lambda</tt> and eigenvectors <tt>x</tt> such that
# where <tt>A</tt> and <tt>B</tt> are hermitian matrices, and <tt>B</tt>
# is positive-definite. Similarly to the real case, this can be reduced to
# <tt>C y = lambda y</tt> where <tt>C = L^{-1} A L^{-H}</tt> is hermitian,
# and <tt>y = L^H x</tt>. The standard hermitian eigensolver can be applied to
# the matrix <tt>C</tt>. The resulting eigenvectors are backtransformed
# to find the vectors of the original problem.
# The eigenvalues of the generalized hermitian-definite eigenproblem are always
# real.
#
# ---
# * GSL::Eigen::Genherm.alloc(n)
#
#   Allocates a workspace for computing eigenvalues of n-by-n complex
#   generalized hermitian-definite eigensystems.
#   The size of the workspace is O(3n).
# ---
# * GSL::Eigen::genherm(A, B, w)
#
#   Computes the eigenvalues of the complex generalized hermitian-definite
#   matrix pair <tt>A, B</tt>, and returns them as a <tt>GSL::Vector</tt>,
#   using the method outlined above.
#   On output, <tt>B</tt> contains its Cholesky decomposition.
# ---
# * GSL::Eigen::genherm(A, B, w)
#
#   Computes the eigenvalues and eigenvectors of the complex generalized
#   hermitian-definite matrix pair <tt>A, B</tt>,
#   and returns them as a <tt>GSL::Vector</tt> and a <tt>GSL::Matrix::Complex</tt>.
#   The computed eigenvectors are normalized to have unit magnitude.
#   On output, <tt>B</tt> contains its Cholesky decomposition.
#
# == Real Generalized Nonsymmetric Eigensystems (>= GSL-1.10)
#
# ---
# * GSL::Eigen::Gen.alloc(n)
# * GSL::Eigen::Gen::Workspace.alloc(n)
#
#   Allocates a workspace for computing eigenvalues of n-by-n real generalized
#   nonsymmetric eigensystems. The size of the workspace is O(n).
#
# ---
# * GSL::Eigen::Gen::params(compute_s, compute_t, balance, w)
# * GSL::Eigen::gen_params(compute_s, compute_t, balance, w)
#
#   Set some parameters which determine how the eigenvalue problem is solved
#   in subsequent calls to <tt>GSL::Eigen::gen</tt>.
#
#   If <tt>compute_s</tt> is set to 1, the full Schur form <tt>S</tt> will be
#   computed by <tt>GSL::Eigen::gen</tt>. If it is set to 0, <tt>S</tt> will
#   not be computed (this is the default setting). <tt>S</tt> is a quasi upper
#   triangular matrix with 1-by-1 and 2-by-2 blocks on its diagonal.
#   1-by-1 blocks correspond to real eigenvalues, and 2-by-2 blocks
#   correspond to complex eigenvalues.
#
#   If <tt>compute_t</tt> is set to 1, the full Schur form <tt>T</tt> will
#   be computed by <tt>GSL::Eigen::gen</tt>. If it is set to 0, <tt>T</tt>
#   will not be computed (this is the default setting). <tt>T</tt>
#   is an upper triangular matrix with non-negative elements on its diagonal.
#   Any 2-by-2 blocks in <tt>S</tt> will correspond to a 2-by-2 diagonal block
#   in <tt>T</tt>.
#
#   The <tt>balance</tt> parameter is currently ignored, since generalized
#   balancing is not yet implemented.
#
# ---
# * GSL::Eigen::gen(A, B, w)
#
#   Computes the eigenvalues of the real generalized nonsymmetric matrix pair
#   <tt>A, B</tt>, and returns them as pairs in (alpha, beta),
#   where alpha is <tt>GSL::Vector::Complex</tt> and beta is <tt>GSL::Vector</tt>.
#   If beta_i is non-zero, then lambda = alpha_i / beta_i is an eigenvalue.
#   Likewise, if alpha_i is non-zero, then mu = beta_i / alpha_i is an
#   eigenvalue of the alternate problem mu A y = B y.
#   The elements of <tt>beta</tt> are normalized to be non-negative.
#
#   If <tt>S</tt> is desired, it is stored in <tt>A</tt> on output.
#   If <tt>T</tt> is desired, it is stored in <tt>B</tt> on output.
#   The ordering of eigenvalues in <tt>alpha, beta</tt>
#   follows the ordering of the diagonal blocks in the Schur forms <tt>S</tt>
#   and <tt>T</tt>.
#
# ---
# * GSL::Eigen::gen_QZ(A, B, w)
#
#   This method is identical to <tt>GSL::Eigen::gen</tt> except it also computes
#   the left and right Schur vectors and returns them.
#
# ---
# * GSL::Eigen::Genv.alloc(n)
# * GSL::Eigen::Genv::Workspace.alloc(n)
#
#   Allocatesa workspace for computing eigenvalues and eigenvectors of
#   n-by-n real generalized nonsymmetric eigensystems.
#   The size of the workspace is O(7n).
#
# ---
# * GSL::Eigen::genv(A, B, w)
#
#   Computes eigenvalues and right eigenvectors of the n-by-n real generalized
#   nonsymmetric matrix pair <tt>A, B</tt>. The eigenvalues and eigenvectors
#   are returned in <tt>alpha, beta, evec</tt>.
#   On output, <tt>A, B</tt> contains the generalized Schur form <tt>S, T</tt>.
#
# ---
# * GSL::Eigen::genv_QZ(A, B, w)
#
#   This method is identical to <tt>GSL::Eigen::genv</tt> except it also computes
#   the left and right Schur vectors and returns them.
#
# == Sorting Eigenvalues and Eigenvectors
# ---
# * GSL::Eigen::symmv_sort(eval, evec, type = GSL::Eigen::SORT_VAL_ASC)
# * GSL::Eigen::Symmv::sort(eval, evec, type = GSL::Eigen::SORT_VAL_ASC)
#
#   These methods simultaneously sort the eigenvalues stored in the vector
#   <tt>eval</tt> and the corresponding real eigenvectors stored in the
#   columns of the matrix <tt>evec</tt> into ascending or descending order
#   according to the value of the parameter <tt>type</tt>,
#
#   * <tt>GSL::Eigen::SORT_VAL_ASC</tt>
#     ascending order in numerical value
#   * <tt>GSL::Eigen::SORT_VAL_DESC</tt>
#     escending order in numerical value
#   * <tt>GSL::Eigen::SORT_ABS_ASC</tt>
#     scending order in magnitude
#   * <tt>GSL::Eigen::SORT_ABS_DESC</tt>
#     descending order in magnitude
#
#   The sorting is carried out in-place!
#
# ---
# * GSL::Eigen::hermv_sort(eval, evec, type = GSL::Eigen::SORT_VAL_ASC)
# * GSL::Eigen::Hermv::sort(eval, evec, type = GSL::Eigen::SORT_VAL_ASC)
#
#   These methods simultaneously sort the eigenvalues stored in the vector
#   <tt>eval</tt> and the corresponding complex eigenvectors stored in the columns
#   of the matrix <tt>evec</tt> into ascending or descending order according
#   to the value of the parameter <tt>type</tt> as shown above.
#
# ---
# * GSL::Eigen::nonsymmv_sort(eval, evec, type = GSL::Eigen::SORT_VAL_ASC)
# * GSL::Eigen::Nonsymmv::sort(eval, evec, type = GSL::Eigen::SORT_VAL_ASC)
#
#   Sorts the eigenvalues stored in the vector <tt>eval</tt> and the corresponding
#   complex eigenvectors stored in the columns of the matrix <tt>evec</tt>
#   into ascending or descending order according to the value of the
#   parameter <tt>type</tt> as shown above.
#   Only <tt>GSL::EIGEN_SORT_ABS_ASC</tt> and <tt>GSL::EIGEN_SORT_ABS_DESC</tt>
#   are supported due to the eigenvalues being complex.
#
# ---
# * GSL::Eigen::gensymmv_sort(eval, evec, type = GSL::Eigen::SORT_VAL_ASC)
# * GSL::Eigen::Gensymmv::sort(eval, evec, type = GSL::Eigen::SORT_VAL_ASC)
#
#   Sorts the eigenvalues stored in the vector <tt>eval</tt> and the
#   corresponding real eigenvectors stored in the columns of the matrix
#   <tt>evec</tt> into ascending or descending order according to the value of
#   the parameter <tt>type</tt> as shown above.
#
# ---
# * GSL::Eigen::gensymmv_sort(eval, evec, type = GSL::Eigen::SORT_VAL_ASC)
# * GSL::Eigen::Gensymmv::sort(eval, evec, type = GSL::Eigen::SORT_VAL_ASC)
#
#   Sorts the eigenvalues stored in the vector <tt>eval</tt> and the
#   corresponding complex eigenvectors stored in the columns of the matrix
#   <tt>evec</tt> into ascending or descending order according to the value of
#   the parameter <tt>type</tt> as shown above.
#
# ---
# * GSL::Eigen::genv_sort(alpha, beta, evec, type = GSL::Eigen::SORT_VAL_ASC)
# * GSL::Eigen::Genv::sort(alpha, beta, evec, type = GSL::Eigen::SORT_VAL_ASC)
#
#   Sorts the eigenvalues stored in the vectors <tt>alpha, beta</tt> and the
#   corresponding complex eigenvectors stored in the columns of the matrix
#   <tt>evec</tt> into ascending or descending order according to the value of
#   the parameter <tt>type</tt> as shown above. Only <tt>GSL::EIGEN_SORT_ABS_ASC</tt>
#   and <tt>GSL::EIGEN_SORT_ABS_DESC</tt> are supported due to the eigenvalues
#   being complex.
#
# {prev}[link:linalg_rdoc.html]
# {next}[link:fft_rdoc.html]
#
# {Reference index}[link:ref_rdoc.html]
# {top}[link:index.html]
#
#