Math::...Matrix(3pm)

💖 Math::SparseMatrix 💖

okay bestie, welcome to Math::SparseMatrix — the User Contributed Perl Documentation page for the module that does all the sparse matrix stuff you didn't wanna do by hand. ✨

---

✨ NAME ✨

Math::SparseMatrix — it gives you the basic sparse matrix operations, like:

• creating them
• reading them from a file
• reading the transpose from a file
• writing them out to a file

no cap, that's the whole vibe. 🦋

---

🌸 DESCRIPTION 🌸

Math::SparseMatrix serves up simple sparse matrix functionality, which in practice means:

• creation of sparse matrices
• writing them out to a file
• reading matrices from files
• reading the transpose of a matrix that's stored in a file

that's it, that's the offer, and honestly? it's giving exactly what it needs to give. 💅

---

✨ SYNOPSIS ✨

okay so here's the whole journey, step by step, numbered like the original because we're organized like that:

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 dimensions you need, 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 like this:

# 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 like this:

# 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 (the format is explained below, don't worry 🫶) like this:

# write out the sparse matrix to the file "matrix.txt"
$spmatrix->writeToFile("matrix.txt");

6. A brand new sparse matrix object can be created from a file in the supported format like this:

# 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 like this:

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

periodt. 💖

---

🎀 SPARSE DATA FORMAT 🎀

The sparse matrix file format that Math::SparseMatrix expects is described below, with an example, because examples are the moment. ✨

The first line (aka the header line) of the file should contain 3 numbers separated by a single space:

1. the number of rows in the sparse matrix
2. the number of columns
3. the number of non-zero elements present in the stored matrix

Each subsequent line represents one row of the sparse matrix, so there should be as many lines after the header line as the number of rows mentioned in the header line. fr fr, line count = row count.

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 is the column number of the non-zero element — and heads up, column numbers start with 1
• the row number is implicitly provided by the line number in the file, so you don't write it
• 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. And if a row does not contain any non-zero element? Then an empty line should be present in the file. yes, actually empty. it's not a mistake. 🫶

NOTE: There should be no empty lines except those representing empty rows, and there should be no comment lines either. 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. 👀 that's the empty row doing its thing, main character energy honestly.

---

🦋 SEE ALSO 🦋

• Math::SparseVector

---

👑 AUTHORS 👑

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

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

---

💜 COPYRIGHT 💜

Copyright (c) 2006-2008, Ted Pedersen and Mahesh Joshi

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to

 The Free Software Foundation, Inc.,
 59 Temple Place - Suite 330,
 Boston, MA  02111-1307, USA.

---

and that's the whole page bestie!! 🌈 this one was served up by perl v5.34.0, dated 2022-06-15, under the Math::...Matrix(3pm) title. go read a matrix from a file, you've got this. 💖✨🦋