========================================== README for Math::SparseVector version 0.03 ========================================== By Amruta Purandare University of Pittsburgh Ted Pedersen University of Minnesota, Duluth Mahesh Joshi University of Minnesota, Duluth 06/18/2006 ============ INTRODUCTION ============ Math:: SparseVector is a CPAN module that implements sparse vector operations using regular Perl hashes. It supports very commonly required methods such as setting a value in a vector, reading a value at a given index, obtaining all indices, addition and dot product of two sparse vectors, and vector normalization. The code is entirely borrowed from the existing Sparse::Vector v0.03 module on CPAN, and re-cast into a new namespace in order to introduce another module Math::SparseMatrix, which makes use of this module. ============ INSTALLATION ============ This module has been developed on Linux and Unix platforms, using Perl programming language. To use this module, you must have Perl (version 5.8 or better recommended) installed on your system. Perl is freely available at - http://www.perl.org. It is very likely that you will already have Perl installed if you are using a Unix/Linux based system. To install this module type the following: perl Makefile.PL make make test make install The exact location of where Math::SparseVector will be installed depends on your system configuration. If you do not have authority to write into system directories, you can install Math::SparseVector in a local directory that you own and have permissions to read and write into as follows: perl Makefile.PL PREFIX=/YOUR/DIR make make test make install This will install the module into /YOUR/DIR/lib/perl5/site_perl/Math/SparseVector.pm If you install Math::SparseVector in a local directory, you will have to explicitly set your PERL5LIB environment variable to include: /YOUR/DIR/lib/perl5/site_perl if this directory was not already included. If you have any troubles during the installation, please contact the authors at tpederse@d.umn.edu or joshi031@d.umn.edu or amruta@cs.pitt.edu =============== GETTING STARTED =============== Step 1. Loading Math::SparseVector Module To use this module, you must insert the following line in your Perl program before using any of the supported methods. use Math::SparseVector; Step 2. Creating a Math::SparseVector Object The following line creates a new object of Math::SparseVector class referred with the name 'spvec'. $spvec=Math::SparseVector->new; The newly created 'spvec' vector will be initially empty. Step 3. Using Methods Now you can use any of the following methods on this 'spvec' Math::SparseVector object. 1. set(i,n) - Sets the value at index i to n Example - $spvec->set(12,5); # equivalent to $spvec{12}=5; 2. get(i) - Returns the value at index i Example - $value = $spvec->get(12); # equivalent to $value=$spvec{12}; 3. keys() - Returns the indices of all non-zero values in the vector Example - @indices = $spvec->keys; # equivalent to @keys=sort {$a <=> $b} keys %spvec; 4. isnull() - Returns 1 if the vector is empty and has no keys Example - if($spvec->isnull) { print "vector is null.\n"; } # similar to # if(scalar(keys %spvec)==0) {print "vector is null.\n";} 5. print() - Prints the sparse vector to stdout Output will show a list of space separated 'index value' pairs for each non-zero 'value' in the vector. Example - $spvec->print; # similar to # foreach $ind (sort {$a<=>$b} keys %spvec) # { print "$ind " . $spvec{$ind} . " "; } 6. stringify() - Returns the vector in a string form. Same as print() method except the vector is written to a string that is returned instead of displaying onto stdout Example - $string=$spvec->stringify; print "$string\n"; # the above will do exactly same as $spvec->print; 7. v1->add(v2) - Adds contents of v2 to vector v1. Similar to v1+=v2 Example - $v1->add($v2); If v1 = (2, , , 5, 8, , , , 1) & v2 = ( , 1, , 3, , , 5, , 9) where blanks show the 0 values that are not stored in Math::SparseVector. After $v1->add($v2); v1 = (2, 1, , 8, 8, , 5, , 10) and v2 remains same 8. v1->binadd(v2) - Binary equivalent of v2 is added into v1. Binary equivalent of a vector is obtained by setting all non-zero values to 1s. Example - If v1 = (1, , , 1, 1, , , , 1) & v2 = ( , 1, , 1, , , 1, , 1) Then, after v1->binadd(v2), v1 will be (1, 1, , 1, 1, , 1, , 1). If v1 = (1, , , 1, 1, , , , 1) & v2 = ( , 1, , 3, , , 5, , 9) v1->binadd(v2); will set v1 to (1, 1, , 1, 1, , 1, , 1). 9. incr(i) - Increments the value at index i Example - $spvec->incr(12); # is similar to $spvec{12}++; 10. div(n) - Divides each vector entry by a given divisor n Example - $spvec->div(4); If spvec = (2, , , 5, 8, , , , 1) Then, $spvec->div(4) will set spvec to (0.5, , , 1.25, 2, , , , 0.25) 11. norm() - Returns the norm of a given vector Example - $spvec_norm = $spvec->norm; If spvec = (2, , , 5, 8, , , , 1) $spvec->norm will return the value = sqrt(2^2 + 5^2 + 8^2 + 1) = sqrt(4 + 25 + 64 + 1) = 9.69536 12. v1->dot(v2) - Returns the dot product of two vectors Example - $dotprod = $v1->dot($v2); If v1 = (2, , , 5, 8, , , , 1) & v2 = ( , 1, , 3, , , 5, , 9) v1->dot(v2) returns 5*3 + 1*9 = 15 + 9 = 24 13. free() - Deallocates all entries and makes the vector empty Example - $spvec->free; will set spvec to null vector () ========= COPYRIGHT ========= Copyright (c) 2006, Amruta Purandare, University of Pittsburgh. amruta@cs.pitt.edu Ted Pedersen, University of Minnesota, Duluth. tpederse@d.umn.edu Mahesh Joshi, University of Minnesota, Duluth. joshi031@d.umn.edu 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. =============================================================================