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.

