Ken Williams > PDL-Sparse > PDL::Sparse

Download:
PDL-Sparse-0.01.tar.gz

Annotate this POD

View/Report Bugs
Source  

NAME ^

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

SYNOPSIS ^

 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);

DESCRIPTION ^

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.

METHODS ^

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.

AUTHOR ^

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: