.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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::SparseMatrix 3pm"
.TH Math::SparseMatrix 3pm "2022-06-15" "perl v5.34.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::SparseMatrix \- Provides basic sparse matrix operations such as creation, reading from file, reading transpose from file and writing to file.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Math::SparseMatrix provides simple sparse matrix functionality such as 
creation of sparse matrices, writing them out to a file, reading matrices from 
files and reading transpose of a matrix stored in a file.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.IP "1. To begin with, Math::SparseMatrix should be included in your Perl program as follows:" 4
.IX Item "1. To begin with, Math::SparseMatrix should be included in your Perl program as follows:"
.Vb 2
\&    # include this module for use in your program
\&    use Math::SparseMatrix;
.Ve
.IP "2. To create an empty sparse matrix object with the required dimensions, use the following constructor:" 4
.IX Item "2. To create an empty sparse matrix object with the required dimensions, use the following constructor:"
.Vb 2
\&    # create a new sparse matrix with 10 rows and 15 columns
\&    my $spmatrix = Math::SparseMatrix\->new(10, 15);
.Ve
.ie n .IP "3. To update the values in the sparse matrix, use the ""set"" function as follows:" 4
.el .IP "3. To update the values in the sparse matrix, use the ``set'' function as follows:" 4
.IX Item "3. To update the values in the sparse matrix, use the set function as follows:"
.Vb 2
\&    # set the value at row 5, column 3 to 10
\&    $spmatrix\->set(5, 3, 10);
.Ve
.ie n .IP "4. To retrieve a stored value, use the ""get"" function as follows:" 4
.el .IP "4. To retrieve a stored value, use the ``get'' function as follows:" 4
.IX Item "4. To retrieve a stored value, use the get function as follows:"
.Vb 2
\&    # get the value at row 6, column 5 if present, or zero
\&    $val = $spmatrix\->get(6, 5);
.Ve
.IP "5. A sparse matrix can be written out to a file in the supported format (explained below) as follows:" 4
.IX Item "5. A sparse matrix can be written out to a file in the supported format (explained below) as follows:"
.Vb 2
\&    # write out the sparse matrix to the file "matrix.txt"
\&    $spmatrix\->writeToFile("matrix.txt");
.Ve
.IP "6. A new sparse matrix object can be created from a file in the supported  format as follows:" 4
.IX Item "6. A new sparse matrix object can be created from a file in the supported format as follows:"
.Vb 2
\&    # create a matrix object by reading the file "matrix.txt"
\&    my $spmatrix = Math::SparseMatrix\->createFromFile("matrix.txt");
.Ve
.IP "7. A new sparse matrix that is the transpose of the matrix stored in the given input file can be created as follows:" 4
.IX Item "7. A new sparse matrix that is the transpose of the matrix stored in the given input file can be created as follows:"
.Vb 2
\&    # create the transpose of the matrix stored in "matrix.txt"
\&    my $spmatrix = Math::SparseMatrix\->createTransposeFromFile("matrix.txt");
.Ve
.IP "8. Finally, to generate the transpose of a matrix stored in a file, read the transpose as in #7 above and write out the read transpose to a new file as in #5 above." 4
.IX Item "8. Finally, to generate the transpose of a matrix stored in a file, read the transpose as in #7 above and write out the read transpose to a new file as in #5 above."
.Vb 2
\&    # create the transpose of the matrix stored in "matrix.txt"
\&    my $spmatrix = Math::SparseMatrix\->createTransposeFromFile("matrix.txt");
\&    
\&    # write out the created transpose to another file "transpose.txt"
\&    $spmatrix\->writeToFile("transpose.txt");
.Ve
.SH "SPARSE DATA FORMAT"
.IX Header "SPARSE DATA FORMAT"
The sparse matrix file format that Math::SparseMatrix expects is described
below with an example.
.PP
The first line (or the header line) of the file should contain 3 number 
separated by a single space.
The first number is the number of rows in the sparse matrix, the second
number is the number of columns and the third number is the number of non-zero
elements present in the stored matrix.
.PP
Each subsequent line represents one row of the sparse matrix, therefore there
should be as many number of lines after the header line as the number of rows
mentioned in the header line. In every line representing a row, there should
be as many pairs of numbers as the number of non-zero elements in that row.
The first number in the pair represents the column number of the non-zero
element (column numbers start with 1). The row number is implicitly provided
by the line
number in the file. The second number in the pair is the actual non-zero
matrix element. Numbers in a pair and multiple pairs should all be separated
by single spaces. If a row does not contain any non-zero element, then an
empty line should be present in the file.
.PP
\&\s-1NOTE:\s0 There should be no empty lines except those representing empty rows,
neither should there be any comment lines. Commenting is not supported.
.PP
Consider the sparse matrix of 5 rows and 4 columns below:
.PP
.Vb 5
\&  10    0    0    0
\&   0    0    6    8
\&   0    0    0    0
\&   0   21    0    0
\&   7    0    0    9
.Ve
.PP
The sparse file representation for the same is:
.PP
.Vb 3
\&  5 4 6
\&  1 10
\&  3 6 4 8
\&
\&  2 21
\&  1 7 4 9
.Ve
.PP
Notice the empty line in between for the third row.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Math::SparseVector
.SH "AUTHORS"
.IX Header "AUTHORS"
Ted Pedersen, University of Minnesota, Duluth.
tpederse at d.umn.edu
.PP
Mahesh Joshi, Carnegie-Mellon University
maheshj @ cmu.edu
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2006\-2008, Ted Pedersen and Mahesh Joshi
.PP
This program is free software; you can redistribute it and/or modify it under
the terms of the \s-1GNU\s0 General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.
.PP
This program is distributed in the hope that it will be useful, but \s-1WITHOUT
ANY WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS
FOR A PARTICULAR PURPOSE.\s0 See the \s-1GNU\s0 General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License along with
this program; if not, write to
.PP
.Vb 3
\& The Free Software Foundation, Inc.,
\& 59 Temple Place \- Suite 330,
\& Boston, MA  02111\-1307, USA.
.Ve