NAME

Math::Matrix::MaybeGSL - Uniform use of Math::MatrixReal and Math::GSL::Matrix.

VERSION

version 0.007

SYNOPSIS

   use Math::Matrix::MaybeGSL;

   my $matrix = Matrix->new(3, 4);

   # puts first position of matrix with value 10
   $matrix->assign(1, 1, 10);

   # gets last position of matrix (should hold 0)
   my $l = $matrix->element(3, 4);

DESCRIPTION

This module interfaces with Math::GSL::Matrix or, if that is not available, Math::MatrixReal. The idea behind this module is to allow the development of tools that use matrices that will work in pure Perl (using Math::MatrixReal) or with extra efficiency using Math::GSL::Matrix.

Given the two modules API is quite distinct, this module defines its own API, stealing method names from both these modules.

METHODS

Matrix

This is a simple function that returns this package name: Math::Matrix::MaybeGSL. It allows a simple interface as shown below for the constructors.

isGSL

Returns a true value is running over Math::GSL backend.

    if (Matrix->isGSL) { ... }

new

Construct a new matrix object. Receives as arguments the number of rows and columns of the matrix being created.

   my $matrix = Matrix->new(20, 30);

Yes, although the module name is Math::Matrix::MaybeGSL, the Matrix subroutine will make it easier to use (shorter name).

new_from_cols

Receives a nested list with the matrix elements, one column at a time:

   my $matrix = Matrix->new_from_cols( [[1, 2], [3, 4]]);

   returns  [ 1 3 ]
            [ 2 4 ]

new_from_rows

Receives a nested list with the matrix elements, one row at a time:

   my $matrix = Matrix->new_from_rows( [[1, 2], [3, 4]]);

   returns  [ 1 2 ]
            [ 3 4 ]

dim

Returns a list (a pair) with the number of lines and columns of the matrix.

   my ($rows, $columns) = $matrix->dim();

assign

Sets a value in a specific position. Note that indexes start at 1 unlike Perl and some other programming languages.

    # sets the first element of the matrix to 10.
    $matrix->assign(1, 1, 10);

element

Retrieves a value from a specific position of the matrix. Note that indexes start at 1 unlike Perl and some other programming languages.

    # retrieves the second element of the first row
    my $val = $matrix->element(1, 2);

each

Apply a specific function to every element of the matrix, returning a new one.

    # square all elements
    $squared_matrix = $matrix->each( { shift ** 2 } );

hconcat

Concatenates two matrices horizontally. Note they must have the same number of rows.

   $C = $a->hconcat($b);

   if A = [ 1 2 ]  and B = [ 5 6 ]  then C = [ 1 2 5 6 ]
          [ 3 4 ]          [ 7 8 ]           [ 3 4 7 8 ]

vconcat

Concatenates two matrices horizontally. Note they must have the same number of rows.

   $C = $a->vconcat($b);

   if A = [ 1 2 ]  and B = [ 5 6 ]  then C = [ 1 2 ]
          [ 3 4 ]          [ 7 8 ]           [ 3 4 ]
                                             [ 5 6 ]
                                             [ 7 8 ]

max

Returns the maximum value of the matrix. In scalar context the position is also returned. For vectors (matrices whose number of rows or columns is 1) only a position value is returned.

      $max = $matrix->max();
      ($max, $row, $col) = $matrix->max();

min

Returns the minimum value of the matrix. In scalar context the position is also returned. For vectors (matrices whose number of rows or columns is 1) only a position value is returned.

      $min = $matrix->min();
      ($min, $row, $col) = $matrix->min();

det

Returns the determinant of the matrix, without going through the rigamarole of computing a LR decomposition.

as_list

Get the contents of a matrix instance as a Perl list.

write

Given a matrix and a filename, writes that matrix to the file. Note that if the file exists it will be overwritten. Also, files written by Math::GSL will not be compatible with files written by Math::MatrixReal nor vice-versa.

     $matrix->write("my_matrix.dat");

read

Reads a matrix written by the write method. Note that it will only read matrices written by the same back-end that is being used for reading.

     my $matrix = Matrix->load("my_matrix.dat");

OVERLOAD

For now only the matrix multiplication is overloaded, in the usual operator, *. Take attention that matrix multiplication only works if the matrix dimensions are compatible.

    $m = $a * $b;

BUGS

At this initial stage of this module, only the methods that I am really needing for my depending applications are implemented. Therefore, it might not include the method that you were looking for. Nevertheless, send me an e-mail (or open an issue on GitHub) and I'll be happy to include it (given the two modules support it).

SEE ALSO

Check Math::MatrixReal and Math::GSL::Matrix documentation.

AUTHOR

Alberto Simões <ambs@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Alberto Simões.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.