--- name: "Math::Matrix::MaybeGSL" section: "3pm" platform: "linux" package: "libmath-matrix-maybegsl-perl" version: "0.008-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Math::Matrix::MaybeGSL" --- # Math::Matrix::MaybeGSL(3pm) Uniform use of Math::MatrixReal and Math::GSL::Matrix. ## NAME Math::Matrix::MaybeGSL - Uniform use of Math::MatrixReal and Math::GSL::Matrix. ## VERSION version 0.008 ## 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"); ``` ### "row" Returns the selected row in a matrix as a new matrix object. Note that **indexes start at 1** unlike Perl and some other programming languages. ``` my $row = $matrix->row(1); ``` ### "find\_zeros" Given a matrix, returns a nested list of indices corresponding to zero values in the given matrix. Note that **indexes start at 1** unlike Perl and some other programming languages. ``` my @indices = $matrix->find_zeros(); ``` ### "transpose" Returns transposed matrix. ## OVERLOAD For now only matrix multiplication and addition are overloaded, in the usual operators, `"*"` and `"+"`, correspondingly. Take attention that these operations only work if the matrix dimensions are compatible. ``` $m = $a * $b; $n = $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. ## CONTRIBUTORS - • Andrius Merkys \ - • Ivan Baidakou - • Gabor Szabo ## AUTHOR Alberto Simões \ ## COPYRIGHT AND LICENSE This software is copyright (c) 2014-2023 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.