# NAME

Math::GSL::Linalg::SVD - Perl extension with convenience methods for performing SVD and eigenvector decomp with the gsl C libraries.

# SYNOPSIS

``````    use Math::GSL::Linalg::SVD;

# Create object.
my \$svd = Math::GSL::Linalg::SVD->new( { verbose => 1 } );

my \$data = [
[qw/  9.515970281313E-01  1.230695618728E-01 -1.652767938310E-01 /],
[qw/ -1.788010086499E-01  3.654739881179E-01  8.526964090247E-02 /],
[qw/  4.156708817272E-02  5.298288357316E-02  7.130047145031E-01 /],
];

\$svd->load_data( { data => \$data } );

# Perform singular value decomposition using the Golub-Reinsch algorithm (this is the default - see METHODS).
# To perform eigen decomposition pass 'eign' as algorithm argument - see METHODS.
\$svd->decompose( { algorithm => q{gd} } );

# Pass results - see METHODS for more details.
my (\$S_vec_ref, \$U_mat_ref, \$V_mat_ref, \$original_data_ref) = \$svd->results;

# Print elements of vector S.
print qq{\nPrint diagonal elements in vector S\n};
for my \$s (@{\$S_vec_ref}) { print qq{\$s, }; }

# Print elements of matrix U.
print qq{\nPrint matrix U\n};
for my \$r (0..\$#{\$U_mat_ref}) {
for my \$c (0..\$#{\$U_mat_ref->[\$r]}) { print qq{\$U_mat_ref->[\$r][\$c], } }; print qq{\n}; }

# Print elements of matrix V.
print qq{\nPrint matrix V\n};
for my \$r (0..\$#{\$V_mat_ref}) {
for my \$c (0..\$#{\$V_mat_ref->[\$r]}) { print qq{\$V_mat_ref->[\$r][\$c], } }; print qq{\n}; }
``````

# DESCRIPTION

The singular value decomposition (SVD) is an important factorization of a rectangular real matrix - see http://en.wikipedia.org/wiki/Singular_value_decomposition. Eigendecomposition is the factorization of a matrix into a canonical form, whereby the matrix is represented in terms of its eigenvalues and eigenvectors - see http://en.wikipedia.org/wiki/Eigendecomposition_of_a_matrix. This module implements the SVD and Eigen decomposition routines of the The C GNU Scientific Library (GSL). It provides simple convinience methods in the upper-level Math::GSL::Linalg::SVD namespace to perform these operations. Alternatively, it also provides direct access to the C routines in the Math::GSL::Linalg::SVD::Matrix, Math::GSL::Linalg::SVD::Vector and Math::GSL::Linalg::SVD::Eigen namespaces - see METHODS.

# METHODS

This is a C-Wrapper for the gsl SVD and Eigen decomp routines. Its provides two means of accessing them. First, a basic OO-interface of convenience methods to allow simple use of the various sdv and eigen routines within the Math::GSL::Linalg::SVD namespaces. Second, it allows you to use the various routines directly using an object interface for the various C structure types. These exist within specific lower-level namespaces for convenience - see below.

## Math::GSL::Linalg::SVD

### new

Create a new Math:GSL::Linalg::SVD object.

``````    my \$svd = Math::GSL::Linalg::SVD->new();
# Pass verbose to turn on minimal messages.
my \$svd = Math::GSL::Linalg::SVD->new( { verbose => 1 } );``````

Used for loading data into object. Data is fed as a reference to a LoL within an anonymous hash using the named argument 'data'.

``````    \$svd->load_data( { data => [
[qw/  9.515970281313E-01 1.230695618728E-01 /],
[qw/ -1.788010086499E-01 3.654739881179E-01 /],
[qw/  4.156708817272E-02  5.298288357316E-02 /],
] } );``````

### decompose

Performs one of several different singular value decomposition algorithms on the loaded matrix (or computes eigenvalues and eigenvectors) depending on argument passed with with 'algorithm' argument. To use the Golub-Reinsch algorithm implemented by `gsl_linalg_SV_decomp` pass 'gd'. To use the modified Golub-Reinsch algorithm implemented by `gsl_linalg_SV_decomp_mod` pass 'mod'. To use the one-sided Jacobi orthogonalization algorithm implemented by `gsl_linalg_SV_decomp_jacobi` pass 'jacobi'. To perform the eigenvalue and eigenvector calculations implemented by `gsl_eigen_symmv` pass 'eigen'. See http://www.gnu.org/software/gsl/manual/html_node/Singular-Value-Decomposition.html for further details.

``````    # Perform svd using the Golub-Reinsch algorithm pass 'gd' or nothing.
\$svd->decompose();
\$svd->decompose( { algorithm => q{mod} } );
\$svd->decompose( { algorithm => q{jacobi} } );
\$eigen->decompose( { algorithm => q{eigen} } );``````

### results

Used to access the results of the analysis. Called in LIST context. For svd an ordered LIST of the LoLs is returned (corresponding to Vector S, Matrix U, Matrix V and Matrix A (see http://www.gnu.org/software/gsl/manual/html_node/Singular-Value-Decomposition.html). See SYNOPSIS.

``    my (\$S_vec_ref, \$U_mat_ref, \$V_mat_ref, \$original_data_ref) = \$svd->results;``

For eigen computation an ordered list of LoLs is returned corresponding to unordered eigenvalues, the eigenvectors (in the same order as the eigenvalues) and the original data matrix. See http://www.gnu.org/software/gsl/manual/html_node/Real-Symmetric-Matrices.html.

``````    my (\$e_val_ref, \$e_vec_ref, \$original_data_ref) = \$eigen->results;

# Print eigenvalues along with corresponding eigenvectors.
for my \$i (0..\$#{\$e_val_ref}) {
print qq{\nEigenvalue: \$e_val_ref->[\$i], };
print qq{\nEigenvector: };
for my \$vec_component (@{\$e_vec_ref->[\$i]}) { print qq{\$vec_component, }; }; print qq{\n}; }``````

## Math::GSL::Linalg::SVD::Matrix

This namespace functions as an interface to the `gsl_matrix` C-structure typedef.

### new

``````    Name:           new
Implements:     gsl_matrix_alloc
Usage:          \$gsl_matrix_pointer_as_perl_object = Math::GSL::Linalg::SVD::Matrix->new;
Returns:        pointer to a gsl_matrix type as Perl object``````

### set_matrix

``````    Name:           set_matrix
Implements:     gsl_matrix_set
Usage:          \$gsl_matrix_pointer_as_perl_object->set_matrix(\$row, \$col, \$double_number);
Returns:  ``````

### get_matrix

``````    Name:           matrix_get
Implements:     gsl_matrix_get
Usage:          \$gsl_matrix_pointer_as_perl_object->set_matrix(\$row, \$col);
Returns:        scalar value``````

### SV_decomp

``````    Name:           SV_decomp
Implements:     gsl_linalg_SV_decomp
Usage:          \$gsl_matrix_pointer_as_perl_object->SV_decomp (...);
Returns:  ``````

### SV_decomp_mod

``````    Name:           SV_decomp_mod
Implements:     gsl_linalg_SV_decomp_mod
Usage:          \$gsl_matrix_pointer_as_perl_object->SV_decomp_mod (...);
Returns:  ``````

### SV_decomp_jacobi

``````    Name:           SV_decomp_jacobi
Implements:     gsl_linalg_SV_decomp_jacobi
Usage:          \$gsl_matrix_pointer_as_perl_object->SV_decomp_mod (...);
Returns:  ``````

### Eigen_decomp

``````    Name:           Eigen_decomp
Implements:     gsl_eigen_symmv
Usage:          \$gsl_matrix_pointer_as_perl_object->Eigen_decomp (...);
Returns:  ``````

## Math::GSL::Linalg::SVD::Vector

This namespace functions as an interface to the `gsl_vector` C-structure typedef.

### new

``````    Name:           new
Implements:     gsl_vector_alloc
Usage:          \$gsl_vector_pointer_as_perl_object = Math::GSL::Linalg::SVD::Vector->new;
Returns:        pointer to gsl_vector as perl object``````

### set_vector

``````    Name:           vector_set
Implements:     gsl_vector_set
Usage:          \$gsl_vector_pointer_as_perl_object->set_vector(\$row, \$col, \$double_number);
Returns:  ``````

### get_vector

``````    Name:           vector_get
Implements:     gsl_vector_get
Usage:          \$gsl_vector_pointer_as_perl_object->set_vector(\$row, \$col)
Returns:        scalar value``````

## Math::GSL::Linalg::SVD::Eigen

This namespace functions as an interface to the `gsl_eigen_symmv_workspace` C-structure typedef used as workspace for the eigen decomposition routines of the gsl library.

### new

``````    Name:           new
Implements:     gsl_eigen_symmv_alloc
Usage:          \$gsl_vector_pointer_as_perl_object = Math::GSL::Linalg::SVD::vector->new;
Returns:        pointer to gsl_eigen_symmv type as perl object``````

# AUTHOR

Daniel S. T. Hughes <dsth@cpan.org>