Ken Williams >
PDL-Sparse-0.01 >
PDL::Sparse

PDL::Sparse - Compact storage for mostly-zero PDLs

use PDL; use PDL::Sparse; # Create a sparse PDL from a real PDL with mostly zeroes my $mat = zeroes(1000,1000); $mat->slice('500:529,500:529') .= random(30,30); # The sparse matrix $mat->slice('30,52') .= 60; # One more nonzero entry my $sparse1 = PDL::Sparse->new_from_pdl($mat); # Create a sparse PDL from scratch my $sparse2 = new PDL::Sparse(1000, 1000); $sparse2->set(3,4 => 7); # Set a couple entries to nonzero values $sparse2->set(5,6 => 2); $sparse2->bake; my $vec = random(1000); # A normal PDL to multiply with # Find $mat->inner($vec), but much faster my $result1 = $sparse1->inner($vec); # Hand-created sparse pdl works the same way my $result2 = $sparse2->inner($vec);

This package implements a sparse storage class for PDL. By "sparse", we mean any PDL whose entries are "mostly" zeroes. For data like this, it can be much more efficient (for both memory and speed) to keep track of only those entries with nonzero values rather than storing all entries.

At this point only a small subset of PDL's regular methods are implemented for the sparse PDLs. Early versions of this module should be considered as a "proof of concept", and you should regard the interface here as unstable, subject to change whenever people give me better ideas.

`PDL::Sparse->new_from_pdl($pdl)`

This method returns a "packed" PDL::Sparse object that represents the same data as in the argument `$pdl`

.

`PDL::Sparse->new(dim1, dim2, ...)`

Returns a PDL::Sparse object of the given size, with all values initialized to zero. Use the `set()`

and `bake()`

methods to finalize the object data for use in calculations.

`$sparse->set(x1, x2, ..., value)`

Sets an entry in the sparse array to the given value.

`$sparse->cook`

Readies a PDL::Sparse object for computation. Note that you either create a PDL::Sparse object by doing `new()`

, `set()`

, and `cook()`

, or by doing `new_from_pdl()`

- never intermix the two.

`$sparse->inner($vector)`

Just like the standard PDL method `inner()`

in its function. At the moment there are some strong restrictions on the dimensionality of the sparse matrix and the vector - the sparse matrix must be 2-d, and the vector must be 1-d. This restriction may be eased in the future.

Returns the vector result, as a normal PDL object.

`$sparse->matmult($other)`

Multiplies two 2-d matrices and returns the result. The `$other`

matrix can be either a PDL::Sparse object or a regular PDL object. If you need to multiply by a regular PDL object in the reverse order, you can't do `$other->matmult($sparse)`

, because that would call the wrong method. Instead, do `$sparse->matmult($other, 1)`

to reverse the order of the multiplication.

This method is bound to the overloaded `x`

operator, so you can simply write `$sparse x $other`

instead of the more verbose version `$sparse->matmult($other)`

.

In the future the result may be returned as a sparse PDL if both arguments are sparse. This usually makes sense. The only reason I'm not doing it now is that I don't quite know how.

`$sparse->normalize`

Normalizes each row of the 2-d matrix to have Euclidean length 1.

`$sparse->as_pdl`

Returns a new regular PDL object equivalent to the sparse object.

`$sparse->density`

In a list context, returns a list containing the number of nonzero entries and the total number of (perhaps virtual) entries in the sparse PDL. In a scalar context, returns the ratio of these two numbers.

`$sparse->dims`

Returns the list of dimension sizes, just like a regular PDL object.

`$sparse->getdim($i)`

Returns the size of the given dimension, just like a regular PDL object.

`$sparse->getndims`

Returns the number of dimensions, just like a regular PDL object.

Ken Williams, ken@mathforum.org

Based on a concept by Christian Soeller (c.soeller@auckland.ac.nz) posted to perldl@jach.hawaii.edu Sept. 12, 2000

syntax highlighting: