Math::GSL::Linalg::SVD(3)

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 /],
               ];

    # Load data.
    $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 } );

load_data

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>

LICENCE AND COPYRIGHT
Copyright (c) 2009, Daniel S. T. Hughes <dsth@cantab.net>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY
Because this software is licensed free of charge, there is no warranty for the software, to the extent permitted by applicable law. Except when otherwise stated in writing the copyright holders and/or other parties provide the software "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of the software is with you. Should the software prove defective, you assume the cost of all necessary servicing, repair, or correction.

In no event unless required by applicable law or agreed to in writing will any copyright holder, or any other party who may modify and/or redistribute the software as permitted by the above licence, be liable to you for damages, including any general, special, incidental, or consequential damages arising out of the use or inability to use the software (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the software to operate with any other software), even if such holder or other party has been advised of the possibility of such damages. Dr Daniel S. T. Hughes, <dsth@>