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.