.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Math::Matrix::MaybeGSL 3pm"
.TH Math::Matrix::MaybeGSL 3pm "2023-01-25" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Math::Matrix::MaybeGSL \- Uniform use of Math::MatrixReal and Math::GSL::Matrix.
.SH "VERSION"
.IX Header "VERSION"
version 0.008
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&   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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module interfaces with \f(CW\*(C`Math::GSL::Matrix\*(C'\fR or, if that is not
available, \f(CW\*(C`Math::MatrixReal\*(C'\fR.  The idea behind this module is to
allow the development of tools that use matrices that will work in
pure Perl (using \f(CW\*(C`Math::MatrixReal\*(C'\fR) or with extra efficiency using
\&\f(CW\*(C`Math::GSL::Matrix\*(C'\fR.
.PP
Given the two modules \s-1API\s0 is quite distinct, this module defines its
own \s-1API,\s0 stealing method names from both these modules.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS """Matrix"""
.el .SS "\f(CWMatrix\fP"
.IX Subsection "Matrix"
This is a simple function that returns this package name: \f(CW\*(C`Math::Matrix::MaybeGSL\*(C'\fR.
It allows a simple interface as shown below for the constructors.
.ie n .SS """isGSL"""
.el .SS "\f(CWisGSL\fP"
.IX Subsection "isGSL"
Returns a true value is running over Math::GSL backend.
.PP
.Vb 1
\&    if (Matrix\->isGSL) { ... }
.Ve
.ie n .SS """new"""
.el .SS "\f(CWnew\fP"
.IX Subsection "new"
Construct a new matrix object. Receives as arguments the number of rows and columns of the
matrix being created.
.PP
.Vb 1
\&   my $matrix = Matrix\->new(20, 30);
.Ve
.PP
Yes, although the module name is \f(CW\*(C`Math::Matrix::MaybeGSL\*(C'\fR, the \f(CW\*(C`Matrix\*(C'\fR subroutine will 
make it easier to use (shorter name).
.ie n .SS """new_from_cols"""
.el .SS "\f(CWnew_from_cols\fP"
.IX Subsection "new_from_cols"
Receives a nested list with the matrix elements, one column at a time:
.PP
.Vb 1
\&   my $matrix = Matrix\->new_from_cols( [[1, 2], [3, 4]]);
\&
\&   returns  [ 1 3 ]
\&            [ 2 4 ]
.Ve
.ie n .SS """new_from_rows"""
.el .SS "\f(CWnew_from_rows\fP"
.IX Subsection "new_from_rows"
Receives a nested list with the matrix elements, one row at a time:
.PP
.Vb 1
\&   my $matrix = Matrix\->new_from_rows( [[1, 2], [3, 4]]);
\&
\&   returns  [ 1 2 ]
\&            [ 3 4 ]
.Ve
.ie n .SS """dim"""
.el .SS "\f(CWdim\fP"
.IX Subsection "dim"
Returns a list (a pair) with the number of lines and columns of the matrix.
.PP
.Vb 1
\&   my ($rows, $columns) = $matrix\->dim();
.Ve
.ie n .SS """assign"""
.el .SS "\f(CWassign\fP"
.IX Subsection "assign"
Sets a value in a specific position. Note that \fBindexes start at 1\fR unlike Perl and some 
other programming languages.
.PP
.Vb 2
\&    # sets the first element of the matrix to 10.
\&    $matrix\->assign(1, 1, 10);
.Ve
.ie n .SS """element"""
.el .SS "\f(CWelement\fP"
.IX Subsection "element"
Retrieves a value from a specific position of the matrix. Note that \fBindexes start at 1\fR unlike
Perl and some other programming languages.
.PP
.Vb 2
\&    # retrieves the second element of the first row
\&    my $val = $matrix\->element(1, 2);
.Ve
.ie n .SS """each"""
.el .SS "\f(CWeach\fP"
.IX Subsection "each"
Apply a specific function to every element of the matrix, returning a new one.
.PP
.Vb 2
\&    # square all elements
\&    $squared_matrix = $matrix\->each( { shift ** 2 } );
.Ve
.ie n .SS """hconcat"""
.el .SS "\f(CWhconcat\fP"
.IX Subsection "hconcat"
Concatenates two matrices horizontally. Note they must have the same number of rows.
.PP
.Vb 1
\&   $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 ]
.Ve
.ie n .SS """vconcat"""
.el .SS "\f(CWvconcat\fP"
.IX Subsection "vconcat"
Concatenates two matrices horizontally. Note they must have the same number of rows.
.PP
.Vb 1
\&   $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 ]
.Ve
.ie n .SS """max"""
.el .SS "\f(CWmax\fP"
.IX Subsection "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.
.PP
.Vb 2
\&      $max = $matrix\->max();
\&      ($max, $row, $col) = $matrix\->max();
.Ve
.ie n .SS """min"""
.el .SS "\f(CWmin\fP"
.IX Subsection "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.
.PP
.Vb 2
\&      $min = $matrix\->min();
\&      ($min, $row, $col) = $matrix\->min();
.Ve
.ie n .SS """det"""
.el .SS "\f(CWdet\fP"
.IX Subsection "det"
Returns the determinant of the matrix, without going through the rigamarole of computing
a \s-1LR\s0 decomposition.
.ie n .SS """as_list"""
.el .SS "\f(CWas_list\fP"
.IX Subsection "as_list"
Get the contents of a matrix instance as a Perl list.
.ie n .SS """write"""
.el .SS "\f(CWwrite\fP"
.IX Subsection "write"
Given a matrix and a filename, writes that matrix to the file. Note that if the file
exists it will be overwritten. Also, \fBfiles written by Math::GSL will not be compatible
with files written by Math::MatrixReal\fR nor vice-versa.
.PP
.Vb 1
\&     $matrix\->write("my_matrix.dat");
.Ve
.ie n .SS """read"""
.el .SS "\f(CWread\fP"
.IX Subsection "read"
Reads a matrix written by the \f(CW\*(C`write\*(C'\fR method. Note that it will only read matrices
written by the same back-end that is being used for reading.
.PP
.Vb 1
\&     my $matrix = Matrix\->load("my_matrix.dat");
.Ve
.ie n .SS """row"""
.el .SS "\f(CWrow\fP"
.IX Subsection "row"
Returns the selected row in a matrix as a new matrix object. Note that \fBindexes start at 1\fR
unlike Perl and some other programming languages.
.PP
.Vb 1
\&    my $row = $matrix\->row(1);
.Ve
.ie n .SS """find_zeros"""
.el .SS "\f(CWfind_zeros\fP"
.IX Subsection "find_zeros"
Given a matrix, returns a nested list of indices corresponding to zero values in the
given matrix. Note that \fBindexes start at 1\fR unlike Perl and some other programming languages.
.PP
.Vb 1
\&    my @indices = $matrix\->find_zeros();
.Ve
.ie n .SS """transpose"""
.el .SS "\f(CWtranspose\fP"
.IX Subsection "transpose"
Returns transposed matrix.
.SH "OVERLOAD"
.IX Header "OVERLOAD"
For now only matrix multiplication and addition are overloaded, in the usual operators, \f(CW\*(C`*\*(C'\fR and \f(CW\*(C`+\*(C'\fR, correspondingly.
Take attention that these operations only work if the matrix dimensions are compatible.
.PP
.Vb 2
\&    $m = $a * $b;
\&    $n = $a + $b;
.Ve
.SH "BUGS"
.IX Header "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).
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Check \f(CW\*(C`Math::MatrixReal\*(C'\fR and \f(CW\*(C`Math::GSL::Matrix\*(C'\fR documentation.
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
.IP "\(bu" 4
Andrius Merkys <merkys@cpan.org>
.IP "\(bu" 4
Ivan Baidakou
.IP "\(bu" 4
Gabor Szabo
.SH "AUTHOR"
.IX Header "AUTHOR"
Alberto Simões <ambs@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2014\-2023 by Alberto Simões.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.