Math::SparseVector(3pm) 				User Contributed Perl Documentation				   Math::SparseVector(3pm)

NAME

       Math::SparseVector - Supports sparse vector operations 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.

MODULE HISTORY

       This module is the successor to Sparse::Vector, which was re-cast into this new namespace in order to introduce another module
       Math::SparseMatrix, which makes use of this module.

SYNOPSIS

	 use Math::SparseVector;

	 # creating an empty sparse vector object
	 $spvec=Math::SparseVector->new;

	 # sets the value at index 12 to 5
	 $spvec->set(12,5);

	 # returns value at index 12
	 $value = $spvec->get(12);

	 # returns the indices of non-zero values in sorted order
	 @indices = $spvec->keys;

	 # returns 1 if the vector is empty and has no keys
	 if($spvec->isnull) {
	   print "vector is null.
";
	 }
	 else  {
	   print "vector is not null.
";
	 }

	 # print sparse vector to stdout
	 $spvec->print;

	 # returns the string form of sparse vector
	 # same as print except the string is returned
	 # rather than displaying on stdout
	 $spvec->stringify;

	 # adds sparse vectors v1, v2 and stores
	 # result into v1
	 $v1->add($v2);

	 # adds binary equivalent of v2 to v1
	 $v1->binadd($v2);
	 # binary equivalnet treats all non-zero values
	 # as 1s

	 # increments the value at index 12
	 $spvec->incr(12);

	 # divides each vector entry by a given divisor 4
	 $spvec->div(4);

	 # returns norm of the vector
	 $spvec_norm = $spvec->norm;

	 # normalizes a sparse vector
	 $spvec->normalize;

	 # returns dot product of the 2 vectors
	 $dotprod = $v1->dot($v2);

	 # deallocates all entries
	 $spvec->free;

USAGE NOTES

       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;

       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.

       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
			# equivalent to $spvec{12}=5;
			$spvec->set(12,5);

	   2. get(i)	- Returns the value at index i
			# equivalent to $value=$spvec{12};
			$value = $spvec->get(12);

	   3. keys()	- Returns the indices of all non-zero values in the vector
			# equivalent to @keys=sort {$a <=> $b} keys %spvec;
			@indices = $spvec->keys;

	   4. isnull()	- Returns 1 if the vector is empty and has no keys
			# similar to
			# if(scalar(keys %spvec)==0) {print "vector is null.
";}
			if($spvec->isnull) { print "vector is null.
"; }

	   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.
			# similar to
			# foreach $ind (sort {$a<=>$b} keys %spvec)
			    # { print "$ind " . $spvec{$ind} . " "; }
			$spvec->print;

	   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
			# the below will do exactly same as $spvec->print;
			$string=$spvec->stringify;
			print "$string
";

	   7. v1->add(v2) - Adds contents of v2 to vector v1.
			Similar to v1+=v2

			$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.
			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
			# is similar to $spvec{12}++;
			$spvec->incr(12);

	   10. div(n)	- Divides each vector entry by a given divisor n
			$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
			$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
			$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
			$spvec->free;
			will set spvec to null vector ()

AUTHORS

       Amruta Purandare, University of Pittsburgh amruta at cs.pitt.edu

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

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

COPYRIGHT AND LICENSE

       Copyright (c) 2006-2008, Amruta Purandare, Ted Pedersen, 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.

POD ERRORS

       Hey! The above document had some coding errors, which are explained below:

       Around line 464:
	   =back doesn't take any parameters, but you said =back  =back

       Around line 467:
	   You forgot a '=back' before '=head1'

perl v5.10.1							    2008-03-25						   Math::SparseVector(3pm)