README

NAME

Math::Libgsl::Eigensystem - An interface to libgsl, the Gnu Scientific Library - Eigensystems

SYNOPSIS

use Math::Libgsl::Matrix;
use Math::Libgsl::Eigensystem;

my Math::Libgsl::Eigensystem::RealSymm $e .= new: 2;

my Math::Libgsl::Matrix $vm .= new: 2, 2;
$vm[0;0] = 2; $vm[0;1] = 1;
$vm[1;0] = 1; $vm[1;1] = 2

my ($eval) = $e.compute($vm);
put $eval[^2];

DESCRIPTION

Math::Libgsl::Eigensystem is an interface to the Eigensystem functions of libgsl, the Gnu Scientific Library.

This module exports six classes:

Math::Libgsl::Eigensystem::RealSymm
Math::Libgsl::Eigensystem::ComplexHerm
Math::Libgsl::Eigensystem::RealNonSymm
Math::Libgsl::Eigensystem::RealGenSymm
Math::Libgsl::Eigensystem::ComplexGenHerm
Math::Libgsl::Eigensystem::RealGenNonSymm

each encapsulates the methods and the buffers needed to create and compute the eigenvalues and the eigenvectors of different kind of matrices.

All these classes share the same constructor schema:

multi method new(Int vectors?)

multi method new(Int :vectors?)

The constructor accepts two simple or named arguments: the size of the system we want to compute and the request to compute the eigenvectors besides the eigenvalues.

All the classes have a compute method; they differ for the number and type of arguments and the return value(s).

Math::Libgsl::Eigensystem::RealSymm

This class acts on a real symmetrix matrix.

method compute(Math::Libgsl::Matrix sort --> List)

This method computes the eigenvalues and the eigenvectors, if selected during the initialization. The optional named argument :$sort specifies the required sort order. The symbolic names for this argument are listed in the Math::Libgsl::Constants module as follows:

GSL_EIGEN_SORT_VAL_ASC: ascending order in numerical value
GSL_EIGEN_SORT_VAL_DESC: descending order in numerical value
GSL_EIGEN_SORT_ABS_ASC: ascending order in magnitude
GSL_EIGEN_SORT_ABS_DESC: descending order in magnitude

This method outputs a List of values: a single Math::Libgsl::Vector, which contains the eigenvalues, and an optional Math::Libgsl::Matrix, which contains the eigenvectors if they were requested.

Math::Libgsl::Eigensystem::ComplexHerm

This class acts on a complex hermitian matrix.

method compute(Math::Libgsl::Matrix::Complex64 sort --> List)

This method computes the eigenvalues and the eigenvectors, if selected during the initialization. The optional named argument :$sort specifies the required sort order.

This method outputs a List of values: a single Math::Libgsl::Vector, which contains the eigenvalues, and an optional Math::Libgsl::Matrix::Complex64, which contains the eigenvectors if they were requested.

Math::Libgsl::Eigensystem::RealNonSymm

This class acts on a complex hermitian matrix.

method compute(Math::Libgsl::Matrix balance = False, gsl_eigen_sort_t :schur-vectors = False, Bool :$schur = False --> List)

This method computes the eigenvalues and the eigenvectors, if selected during the initialization. The optional named argument :schur requires that it computes the full Schur form T. The optional named argument :sort specifies the required sort order.

This method outputs a List of values: a single Math::Libgsl::Vector::Complex64, which contains the eigenvalues, an optional Math::Libgsl::Matrix::Complex64, which contains the eigenvectors if they were requested, and an optional Math::Libgsl::Matrix if the Schur vectors were requested.

Math::Libgsl::Eigensystem::RealGenSymm

method compute(Math::Libgsl::Matrix B where .matrix.size1 == .matrix.size2 && .matrix.size1 == sort --> List)

This method computes the eigenvalues and the eigenvectors, if selected during the initialization. It requires two mandatory Math::Libgsl::Matrix objects (refer to the very good C Library documentation for the meaning of those two matrices and the computation details). The optional named argument :$sort specifies the required sort order.

This method outputs a List of values: a single Math::Libgsl::Vector, which contains the eigenvalues, an optional Math::Libgsl::Matrix, which contains the eigenvectors if they were requested. On exit the first matrix B will contain the Cholesky decomposition of the eigenvector matrix.

Math::Libgsl::Eigensystem::ComplexGenHerm

method compute(Math::Libgsl::Matrix::Complex64 B where .matrix.size1 == .matrix.size2 && .matrix.size1 == sort --> List)

This method computes the eigenvalues and the eigenvectors, if selected during the initialization. It requires two mandatory Math::Libgsl::Matrix::Complex64 objects (refer to the very good C Library documentation for the meaning of those two matrices and the details of the computation). The optional named argument :$sort specifies the required sort order.

This method outputs a List of values: a single Math::Libgsl::Vector, which contains the eigenvalues, an optional Math::Libgsl::Matrix::Complex64, which contains the eigenvectors if they were requested. On exit the first matrix B will contain the Cholesky decomposition of the eigenvector matrix.

Math::Libgsl::Eigensystem::RealGenNonSymm

method compute(Math::Libgsl::Matrix B where .matrix.size1 == .matrix.size2 && .matrix.size1 == schur-S = False, Bool :balance = False, Bool :sort --> List)

This method computes the eigenvalues and the eigenvectors, if selected during the initialization. It requires two mandatory Math::Libgsl::Matrix objects (refer to the amazing C Library documentation for the meaning of those two matrices and the details of the computation). The optional named argument :schur-T requires that it computes the full Schur form T. The optional named argument :schur-vectors requires that it also computes the Schur vectors. The optional named argument :$sort specifies the required sort order.

This method outputs a List of values: one Math::Libgsl::Vector::Complex64 and one Math::Libgsl::Vector object, which contain the eigenvalues (see the C library documentation for the meaning of these two vectors), an optional Math::Libgsl::Matrix::Complex64, which contains the eigenvectors if they were requested. If the Schur vectors were requested the left and right Schur vectors are returned as Math::Libgsl::Matrix objects. On exit, if A will contain the Schur form S; if B will contain the Schur form T.

C Library Documentation

For more details on libgsl see https://www.gnu.org/software/gsl/. The excellent C Library manual is available here https://www.gnu.org/software/gsl/doc/html/index.html, or here https://www.gnu.org/software/gsl/doc/latex/gsl-ref.pdf in PDF format.

Prerequisites

This module requires the libgsl library to be installed. Please follow the instructions below based on your platform:

Debian Linux and Ubuntu 20.04+

sudo apt install libgsl23 libgsl-dev libgslcblas0

That command will install libgslcblas0 as well, since it's used by the GSL.

Ubuntu 18.04

libgsl23 and libgslcblas0 have a missing symbol on Ubuntu 18.04. I solved the issue installing the Debian Buster version of those three libraries:

Installation

To install it using zef (a module management tool):

$ zef install Math::Libgsl::Eigensystem

AUTHOR

Fernando Santagata [email protected]

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.