Debian Codegraph @

README

raw
1 NAME
2 Math::SparseVector - Supports sparse vector operations such as setting a
3 value in a vector, reading a value at a given index, obtaining all
4 indices, addition and dot product of two sparse vectors, and vector
5 normalization.
6
7 MODULE HISTORY
8 This module is the successor to Sparse::Vector, which was re-cast into
9 this new namespace in order to introduce another module
10 Math::SparseMatrix, which makes use of this module.
11
12 SYNOPSIS
13 use Math::SparseVector;
14
15 # creating an empty sparse vector object
16 $spvec=Math::SparseVector->new;
17
18 # sets the value at index 12 to 5
19 $spvec->set(12,5);
20
21 # returns value at index 12
22 $value = $spvec->get(12);
23
24 # returns the indices of non-zero values in sorted order
25 @indices = $spvec->keys;
26
27 # returns 1 if the vector is empty and has no keys
28 if($spvec->isnull) {
29 print "vector is null.\n";
30 }
31 else {
32 print "vector is not null.\n";
33 }
34
35 # print sparse vector to stdout
36 $spvec->print;
37
38 # returns the string form of sparse vector
39 # same as print except the string is returned
40 # rather than displaying on stdout
41 $spvec->stringify;
42
43 # adds sparse vectors v1, v2 and stores
44 # result into v1
45 $v1->add($v2);
46
47 # adds binary equivalent of v2 to v1
48 $v1->binadd($v2);
49 # binary equivalnet treats all non-zero values
50 # as 1s
51
52 # increments the value at index 12
53 $spvec->incr(12);
54
55 # divides each vector entry by a given divisor 4
56 $spvec->div(4);
57
58 # returns norm of the vector
59 $spvec_norm = $spvec->norm;
60
61 # normalizes a sparse vector
62 $spvec->normalize;
63
64 # returns dot product of the 2 vectors
65 $dotprod = $v1->dot($v2);
66
67 # deallocates all entries
68 $spvec->free;
69
70 USAGE NOTES
71 1. Loading Math::SparseVector Module
72 To use this module, you must insert the following line in your Perl
73 program before using any of the supported methods.
74
75 use Math::SparseVector;
76
77 2. Creating a Math::SparseVector Object
78 The following line creates a new object of Math::SparseVector class
79 referred with the name 'spvec'.
80
81 $spvec=Math::SparseVector->new;
82
83 The newly created 'spvec' vector will be initially empty.
84
85 3. Using Methods
86 Now you can use any of the following methods on this 'spvec'
87 Math::SparseVector object.
88
89 1. set(i,n) - Sets the value at index i to n
90 # equivalent to $spvec{12}=5;
91 $spvec->set(12,5);
92
93 2. get(i) - Returns the value at index i
94 # equivalent to $value=$spvec{12};
95 $value = $spvec->get(12);
96
97 3. keys() - Returns the indices of all non-zero values in the vector
98 # equivalent to @keys=sort {$a <=> $b} keys %spvec;
99 @indices = $spvec->keys;
100
101 4. isnull() - Returns 1 if the vector is empty and has no keys
102 # similar to
103 # if(scalar(keys %spvec)==0) {print "vector is null.\n";}
104 if($spvec->isnull) { print "vector is null.\n"; }
105
106 5. print() - Prints the sparse vector to stdout - Output will show a
107 list of space separated 'index value' pairs for each non-zero
108 'value' in the vector.
109 # similar to
110 # foreach $ind (sort {$a<=>$b} keys %spvec)
111 # { print "$ind " . $spvec{$ind} . " "; }
112 $spvec->print;
113
114 6. stringify() - Returns the vector in a string form. Same as
115 print() method except the vector is written to a string that is
116 returned instead of displaying onto stdout
117 # the below will do exactly same as $spvec->print;
118 $string=$spvec->stringify;
119 print "$string\n";
120
121 7. v1->add(v2) - Adds contents of v2 to vector v1.
122 Similar to v1+=v2
123
124 $v1->add($v2);
125 If v1 = (2, , , 5, 8, , , , 1)
126 & v2 = ( , 1, , 3, , , 5, , 9)
127 where blanks show the 0 values that are not stored in
128 Math::SparseVector.
129
130 After $v1->add($v2);
131 v1 = (2, 1, , 8, 8, , 5, , 10) and v2 remains same
132
133 8. v1->binadd(v2) - Binary equivalent of v2 is added into v1. Binary
134 equivalent of a vector is obtained by setting all non-zero values to
135 1s.
136 If v1 = (1, , , 1, 1, , , , 1)
137 & v2 = ( , 1, , 1, , , 1, , 1)
138 Then, after v1->binadd(v2),
139 v1 will be (1, 1, , 1, 1, , 1, , 1).
140
141 If v1 = (1, , , 1, 1, , , , 1)
142 & v2 = ( , 1, , 3, , , 5, , 9)
143 v1->binadd(v2);
144 will set v1 to (1, 1, , 1, 1, , 1, , 1).
145
146 9. incr(i) - Increments the value at index i
147 # is similar to $spvec{12}++;
148 $spvec->incr(12);
149
150 10. div(n) - Divides each vector entry by a given divisor n
151 $spvec->div(4);
152 If spvec = (2, , , 5, 8, , , , 1)
153 Then, $spvec->div(4)
154 will set spvec to (0.5, , , 1.25, 2, , , , 0.25)
155
156 11. norm() - Returns the norm of a given vector
157 $spvec_norm = $spvec->norm;
158 If spvec = (2, , , 5, 8, , , , 1)
159 $spvec->norm will return the value
160 = sqrt(2^2 + 5^2 + 8^2 + 1)
161 = sqrt(4 + 25 + 64 + 1)
162 = 9.69536
163
164 12. v1->dot(v2) - Returns the dot product of two vectors
165 $dotprod = $v1->dot($v2);
166 If v1 = (2, , , 5, 8, , , , 1)
167 & v2 = ( , 1, , 3, , , 5, , 9)
168 v1->dot(v2) returns
169 5*3 + 1*9 = 15 + 9 = 24
170
171 13. free() - Deallocates all entries and makes the vector empty
172 $spvec->free;
173 will set spvec to null vector ()
174
175 AUTHORS
176 Amruta Purandare, University of Pittsburgh amruta at cs.pitt.edu
177
178 Ted Pedersen, University of Minnesota, Duluth tpederse at d.umn.edu
179
180 Mahesh Joshi, Carnegie-Mellon University maheshj at cmu.edu
181
182 COPYRIGHT AND LICENSE
183 Copyright (c) 2006-2008, Amruta Purandare, Ted Pedersen, Mahesh
184 Joshi
185
186 This program is free software; you can redistribute it and/or modify
187 it under the terms of the GNU General Public License as published by
188 the Free Software Foundation; either version 2 of the License, or
189 (at your option) any later version.
190
191 This program is distributed in the hope that it will be useful, but
192 WITHOUT ANY WARRANTY; without even the implied warranty of
193 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
194 General Public License for more details.
195
196 You should have received a copy of the GNU General Public License
197 along with this program; if not, write to
198
199 The Free Software Foundation, Inc.,
200 59 Temple Place - Suite 330,
201 Boston, MA 02111-1307, USA.
202