========================================
README for Sparse-0.03
========================================
By
Amruta Purandare and Ted Pedersen,
University of Minnesota, Duluth
06/14/2004
=================
INTRODUCTION
=================
Sparse::Vector is a CPAN module that implements sparse vector operations
using regular Perl hashes. It supports very commonly required methods
like setting a value in a vector, reading a value at a given index,
obtaining all indices, addition and dot product of two sparse vectors,
vector normalization etc...
==================
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 Sparse::Vector will be installed depends
on your system configuration.
If you do not have authority to write into system directories, you can
install Sparse::Vector 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 install
This will install the module into
/YOUR/DIR/bin/
Whether you install Sparse::Vector in a system directory or local directory,
you will have to explicitly set your $PATH to include :
INSTALL_PATH/bin/
where INSTALL_PATH is a path to a system directory like /usr/local, /usr...
OR
the path specified by the user using the PREFIX option with Makefile.PL.
If you have any troubles in installation, please contact the authors at
pura0010@d.umn.edu or tpederse@d.umn.edu
====================
GETTING STARTED
====================
Step 1. Loading Sparse::Vector Module
To use this module, you must insert the following line in your Perl program
before using any of the supported methods.
use Sparse::Vector;
Step 2. Creating a Sparse::Vector Object
The following line creates a new object of Sparse::Vector class referred
with the name 'spvec'.
$spvec=Sparse::Vector->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' Sparse::Vector
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
Sparse::Vector.
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) 2004,
Amruta Purandare, University of Minnesota, Duluth.
pura0010@umn.edu
Ted Pedersen, University of Minnesota, Duluth.
tpederse@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.
=============================================================================