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

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

  5 4 6
  1 10
  3 6 4 8

  2 21
  1 7 4 9

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

package Math::SparseMatrix;

use 5.006;
use strict;
use warnings;

require Exporter;
require Math::SparseVector;

use Math::SparseVector;


our @ISA = qw(Exporter);

# Items to export into callers namespace by default. Note: do not export
# names by default without a very good reason. Use EXPORT_OK instead.
# Do not simply export all your public functions/methods/constants.

# This allows declaration	use Math::SparseMatrix ':all';
# If you do not need this, moving things directly into @EXPORT or @EXPORT_OK
# will save memory.
our %EXPORT_TAGS = ( 'all' => [ qw(
	
) ] );

our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );

our @EXPORT = qw(
	
);

our $VERSION = '0.03';

sub new {
    my $class = shift;
    my $rows = shift;
    my $cols = shift;

    if (!defined $rows || !defined $cols) {
        die "Math::SparseMatrix->new error.\n" .
            "USAGE: my \$spmatrix = Math::SparseMatrix->new(\$num_rows, \$num_cols);\n";
    }

    my $self = {
        _rows => $rows,
        _cols => $cols,
        _nnz => 0,
        _data => {}
    };

    bless $self, $class;
    return $self;
}

sub set {
    my $self = shift;
    my ($row, $col, $val) = @_;

    if (!defined $row || !defined $col || !defined $val) {
        die "Math::SparseMatrix->set error.\n" .
            "USAGE: \$spmatrix->set(\$row, \$col, \$val);\n";
    }

    if ($row < 1 || $row > $self->{_rows}) {
        die "Math::SparseMatrix->set error.\n" .
            "Row index out of bounds, must be between 1 and " .
            $self->{_rows} . " inclusive.\n";
    }
    
    if ($col < 1 || $col > $self->{_cols}) {
        die "Math::SparseMatrix->set error.\n" .
            "Column index out of bounds, must be between 1 and " .
            $self->{_cols} . " inclusive.\n";
    }

    if ($val == 0) {
        die "Math::SparseMatrix->set error.\n" .
            "Cannot store zero value in a sparse matrix.\n";
    }

    if (exists $self->{_data}->{$row}) {
        # update the number of non-zero elements in the matrix
        $self->{_nnz} -= scalar($self->{_data}->{$row}->keys);
        $self->{_data}{$row}->set($col,$val);
        $self->{_nnz} += scalar($self->{_data}->{$row}->keys);
    } else {
        $self->{_data}->{$row} = new Math::SparseVector();
        $self->{_data}->{$row}->set($col,$val);
        $self->{_nnz}++;
    }
}

sub get {
    my $self = shift;
    my ($row, $col) = @_;

    if (!defined $row || !defined $col) {
        die "Math::SparseMatrix->get error.\n" .
            "USAGE: \$val = \$spmatrix->get(\$row, \$col);\n";
    }

    if ($row < 1 || $row > $self->{_rows}) {
        die "Math::SparseMatrix->get error.\n" .
            "Row index out of bounds, must be between 1 and " .
            $self->{_rows} . " inclusive.\n";
    }
    
    if ($col < 1 || $col > $self->{_cols}) {
        die "Math::SparseMatrix->get error.\n" .
            "Column index out of bounds, must be between 1 and " .
            $self->{_cols} . " inclusive.\n";
    }

    if (exists $self->{_data}->{$row}) {
        return $self->{_data}->{$row}->get($col);
    } else {
        return 0;
    }
}

sub createFromFile {

    my $class = shift;
    my $infile = shift;

    if (!defined $infile) {
        die "Math::SparseMatrix->createFromFile error.\n" .
            "USAGE: my \$spmatrix = Math::SparseMatrix->createFromFile(\$input_file);\n";
    }

    if (!-f $infile) {
        die "Math::SparseMatrix->createFromFile error.\n" .
            "Cannot find file $infile.\n";
    }

    my $self = {
        _rows => 0,
        _cols => 0,
        _nnz => 0,
        _data => {}
    };

    open(INPUT, "< $infile") or
        die "Math::SparseMatrix->createFromFile error.\n" .
            "Failed to open sparse matrix input file $infile.\n";

    # read the number of rows, columns and the non-zero elements in the
    # file
    my $line = <INPUT>;
    chomp $line;
    my ($rows, $cols, $nnz) = split / +/, $line;
    $self->{_rows} = $rows;
    $self->{_cols} = $cols;
    # DO NOT SET THE NUMBER OF NON-ZEROS, THAT IS MANAGED BY THE set(...)
    # function, which is called below

    # create a Math::SparseMatrix object
    bless $self, $class;

    # also do error checks on file integrity
    my $lineNum = 0;
    my $nnzFound = 0;
    while ($line = <INPUT>) {
        chomp $line;
        $lineNum++;
        if ($lineNum > $rows) {
            die "Math::SparseMatrix->createFromFile error.\n". 
            "Number of rows in $infile is greater than that " .
            "mentioned in the file header ($rows).";
        }

        my @tokens = split / +/, $line;
        my $index;
        # process the <column, value> pairs in each line
        for ($index = 0; $index < @tokens; $index += 2) {
            # the column number of the current pair is the column 
            # number, and the current line number is the row number
            $self->set($lineNum, $tokens[$index], $tokens[$index + 1]);
            $nnzFound++;
        }
    }

    if ($nnzFound < $nnz) {
        die "Math::SparseMatrix->createFromFile error.\n". 
            "Number of non-zero elements found in $infile is less than that " .
            "mentioned in the file header -- $nnzFound < $nnz.\n";
    }

    if ($nnzFound > $nnz) {
        die "Math::SparseMatrix->createFromFile error.\n". 
            "Number of non-zero elements found in $infile is greater than that " .
            "mentioned in the file header -- $nnzFound > $nnz.\n";
    }

    # now the transposed matrix is loaded and ready to be returned
    return $self;
}

sub createTransposeFromFile {

    my $class = shift;
    my $infile = shift;

    if (!defined $infile) {
        die "Math::SparseMatrix->createTransposeFromFile error.\n" .
            "USAGE: \$my \$spmatrix = Math::SparseMatrix->createTransposeFromFile(\$input_file)\n";
    }

    if (!-f $infile) {
        die "Math::SparseMatrix->createTransposeFromFile error.\n" .
            "Cannot find file $infile.\n";
    }

    my $self = {
        _rows => 0,
        _cols => 0,
        _nnz => 0,
        _data => {}
    };

    open(INPUT, "< $infile") or
        die "Math::SparseMatrix->createTransposeFromFile error.\n" .
            "Failed to open sparse matrix input file $infile.\n";

    # read the number of rows, columns and the non-zero elements in the
    # file
    my $line = <INPUT>;
    chomp $line;
    my ($rows, $cols, $nnz) = split / +/, $line;
    # swap number of rows and columns
    $self->{_rows} = $cols;
    $self->{_cols} = $rows;
    # DO NOT SET THE NUMBER OF NON-ZEROS, THAT IS MANAGED BY THE set(...)
    # function, which is called below

    # create a Math::SparseMatrix object
    bless $self, $class;

    # also do error checks on file integrity
    my $lineNum = 0;
    my $nnzFound = 0;
    while ($line = <INPUT>) {
        chomp $line;
        $lineNum++;
        if ($lineNum > $rows) {
            die "Math::SparseMatrix->createTransposeFromFile error.\n". 
            "Number of columns in $infile is greater than that " .
            "mentioned in the file header ($rows).";
        }

        my @tokens = split / +/, $line;
        my $index;
        # process the <column, value> pairs in each line
        for ($index = 0; $index < @tokens; $index += 2) {
            # the column number of the current pair is the row
            # number in the transpose, the current line number is
            # the column number in the transpose
            $self->set($tokens[$index], $lineNum, $tokens[$index + 1]);
            $nnzFound++;
        }
    }

    if ($nnzFound < $nnz) {
        die "Math::SparseMatrix->createTransposeFromFile error.\n". 
            "Number of non-zero elements found in $infile is less than that " .
            "mentioned in the file header -- $nnzFound < $nnz.\n";
    }

    if ($nnzFound > $nnz) {
        die "Math::SparseMatrix->createTransposeFromFile error.\n". 
            "Number of non-zero elements found in $infile is greater than that " .
            "mentioned in the file header -- $nnzFound > $nnz.\n";
    }


    # now the transposed matrix is loaded and ready to be returned
    return $self;
}

sub writeToFile {

    my $self = shift;
    my $outfile = shift;

    if (!defined $outfile) {
        die "Math::SparseMatrix->writeToFile error.\n" .
            "USAGE: \$spmatrix->writeToFile (\$output_file);\n";
    }

    # write it to the output file
    open(OUTPUT, "> $outfile") or
        die "Math::SparseMatrix->writeToFile error.\n" .
            "Failed to create output file $outfile.\n";
    print OUTPUT $self->{_rows} . " " . $self->{_cols} . " " . 
        $self->{_nnz} . "\n";
    my $row;
    my $linecount = 1;
    foreach $row (sort {$a <=> $b} keys %{$self->{_data}}) {
        if ($row > $linecount) {
            # add empty lines for empty rows
            my $i = 0;
            my $limit = $row - $linecount;
            for ($i = 0; $i < $limit; $i++) {
                print OUTPUT "\n";
                $linecount++;
            }
        }
        my $vec = $self->{_data}->{$row};
        my $line = $vec->stringify();
        print OUTPUT $line . "\n";
        $linecount++;
    }
    close OUTPUT;
}

sub printDims {
    my $self = shift;
    print "Rows: " . $self->{_rows} . ". Cols: " . $self->{_cols} . ".\n";
}

1;
__END__