Ubuntu Manpage: Math::SparseMatrix - Provides basic sparse matrix operations such as creation, reading

Provided by: libmath-sparsematrix-perl_0.03-3_all

NAME

       Math::SparseMatrix - Provides basic sparse matrix operations such as creation, reading
       from file, reading transpose from file and writing to file.

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.

SYNOPSIS

       1. To begin with, Math::SparseMatrix should be included in your Perl program as follows:
               # include this module for use in your program
               use Math::SparseMatrix;

       2. To create an empty sparse matrix object with the required dimensions, use the following
       constructor:
               # create a new sparse matrix with 10 rows and 15 columns
               my $spmatrix = Math::SparseMatrix->new(10, 15);

       3. To update the values in the sparse matrix, use the "set" function as follows:
               # set the value at row 5, column 3 to 10
               $spmatrix->set(5, 3, 10);

       4. To retrieve a stored value, use the "get" function as follows:
               # get the value at row 6, column 5 if present, or zero
               $val = $spmatrix->get(6, 5);

       5. A sparse matrix can be written out to a file in the supported format (explained below)
       as follows:
               # write out the sparse matrix to the file "matrix.txt"
               $spmatrix->writeToFile("matrix.txt");

       6. A new sparse matrix object can be created from a file in the supported  format as
       follows:
               # create a matrix object by reading the file "matrix.txt"
               my $spmatrix = Math::SparseMatrix->createFromFile("matrix.txt");

       7. A new sparse matrix that is the transpose of the matrix stored in the given input file
       can be created as follows:
               # create the transpose of the matrix stored in "matrix.txt"
               my $spmatrix = Math::SparseMatrix->createTransposeFromFile("matrix.txt");

       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.
               # 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");

SPARSE DATA FORMAT

The sparse matrix file format that Math::SparseMatrix expects is described below with an
example.

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.

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.

NOTE: There should be no empty lines except those representing empty rows, neither should
there be any comment lines. Commenting is not supported.

Consider the sparse matrix of 5 rows and 4 columns below:

10 0 0 0
0 0 6 8
0 0 0 0
0 21 0 0
7 0 0 9

The sparse file representation for the same is:

5 4 6
1 10
3 6 4 8

2 21
1 7 4 9

Notice the empty line in between for the third row.

AUTHORS

       Ted Pedersen, University of Minnesota, Duluth.  tpederse at d.umn.edu

       Mahesh Joshi, Carnegie-Mellon University maheshj @ cmu.edu

COPYRIGHT