Provided by: libmath-sparsevector-perl_0.04-2_all bug

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.\n";
         }
         else  {
           print "vector is not null.\n";
         }

         # 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.\n";}
                        if($spvec->isnull) { 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.
                        # 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\n";

           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.