edu.ucla.sspace.matrix

Class SVD

java.lang.Object

edu.ucla.sspace.matrix.SVD

public class SVD
extends Object

A utililty class for invoking different implementations of the Singular Value Decomposition (SVD). The SVD is a way of factoring any matrix A into three matrices U Σ V^T such that Σ is a diagonal matrix containing the singular values of A. The singular values of Σ are ordered according to which causes the most variance in the values of A.

All SVD operations return an array of three Matrix instances that correspond to U Σ and V^T. Regardless of which algorithm is used, the matrices will be returned in this same orientation.

Five different SVD algorithms are possible:

1. SVDLIBC
2. Matlab svds
3. GNU Octave svds - Note that this is an optional package and requires that the ARPACK bindings for Octave is installed.
4. COLT SVD
5. JAMA SVD

Support for these algorithms requires that they are invokable from the path used to start the current JVM, or in the case of JAMA, are available in the classpath. Note that if JAMA is used in conjunction with a .jar executable, it's location needs to be specified with the jama.path system property. This can be set on the command line using -Djama.path=path/to/jama. Similarly, if COLT is to be used in conjunction with a .jar, the location of the colt.jar file should be specified using the colt.path system property.

Users may select which algorithm to use manually using the Algorithm enum. The additional enum value ANY will select the fastest algorithm available. If no algorithm is available, a UnsupporteOperationException is thrown at run-time.

This class will automatically convert a file to the appropriate matrix format for the required algorithm.

Author:

David Jurgens

See Also:

MatrixIO

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SVD.Algorithm Which algorithm to use for computing the Singular Value Decomposition (SVD) of a matrix.

Method Summary

Methods

Modifier and Type	Method and Description
static MatrixFactorization	getFactorization(SVD.Algorithm alg) Returns the MatrixFactorization implementation corresponding to the SVD.Algorithm name.
static MatrixFactorization	getFastestAvailableFactorization() Returns the fastest MatrixFactorization implementation of Singular Value Decomposition available, or null if no implementation is available.
static boolean	isMatlabAvailable() Returns true if Matlab is available
static boolean	isOctaveAvailable() Returns true if Octave is available
static boolean	isSVDLIBCavailable() Returns true if the SVDLIBC library is available
static Matrix[]	svd(File matrix, int dimensions) Deprecated.
static Matrix[]	svd(File matrix, MatrixIO.Format format, int dimensions) Deprecated.
static Matrix[]	svd(File matrix, SVD.Algorithm alg, int dimensions) Deprecated.
static Matrix[]	svd(File matrix, SVD.Algorithm alg, MatrixIO.Format format, int dimensions) Deprecated.
static Matrix[]	svd(Matrix m, int dimensions) Deprecated.
static Matrix[]	svd(Matrix m, SVD.Algorithm algorithm, int dimensions) Deprecated.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getFastestAvailableFactorization

public static MatrixFactorization getFastestAvailableFactorization()

Returns the fastest MatrixFactorization implementation of Singular Value Decomposition available, or null if no implementation is available.

getFactorization

public static MatrixFactorization getFactorization(SVD.Algorithm alg)

Returns the MatrixFactorization implementation corresponding to the SVD.Algorithm name.

svd

@Deprecated
public static Matrix[] svd(Matrix m,
                      int dimensions)

Deprecated.

Returns U, S, V^T matrices for the SVD of the matrix using the fastest available SVD algorithm to generate the specified number of singular values.

Use a MatrixFactorization implementation instead.

Parameters:

m - the matrix on which the SVD should be computed

dimensions - the number of singular values to calculate

Returns:

an array of Matrix objects for the U, S, and V^T matrices in that order

Throws:

UnsupportedOperationException - if no SVD algorithm is available

svd

@Deprecated
public static Matrix[] svd(Matrix m,
                      SVD.Algorithm algorithm,
                      int dimensions)

Deprecated.

Returns U, S, V^T matrices for the SVD of the matrix using the specified SVD algorithm to generate the specified number of singular values.

Use a MatrixFactorization implementation instead.

Parameters:

m - the matrix on which the SVD should be computed

algorithm - the algorithm to use in computing the SVD

dimensions - the number of singular values to calculate

Returns:

an array of Matrix objects for the U, S, and V^T matrices in that order

Throws:

UnsupportedOperationException - if no SVD algorithm is available

svd

@Deprecated
public static Matrix[] svd(File matrix,
                      int dimensions)

Deprecated.

Returns U, S, V^T matrices for the SVD of the matrix file in Matlab sparse format using the specified SVD algorithm to generate the specified number of singular values.

Use a MatrixFactorization implementation instead.

Parameters:

matrix - a file containing a matrix

dimensions - the number of singular values to calculate

Returns:

an array of Matrix objects for the U, S, and V^T matrices in that order

Throws:

UnsupportedOperationException - if no SVD algorithm is available

svd

@Deprecated
public static Matrix[] svd(File matrix,
                      SVD.Algorithm alg,
                      int dimensions)

Deprecated.

Returns U, S, V^T matrices for the SVD of the matrix file in Matlab sparse format using the specified SVD algorithm to generate the specified number of singular values.

Use a MatrixFactorization implementation instead.

Parameters:

matrix - a file containing a matrix

alg - which algorithm to use for computing the SVD

dimensions - the number of singular values to calculate

Returns:

an array of Matrix objects for the U, S, and V^T matrices in that order

Throws:

UnsupportedOperationException - if the provided SVD algorithm is unavailable

svd

@Deprecated
public static Matrix[] svd(File matrix,
                      MatrixIO.Format format,
                      int dimensions)

Deprecated.

Returns U, S, V^T matrices for the SVD of the matrix file in specified format using the the fastst SVD algorithm available to generate the specified number of singular values.

Use a MatrixFactorization implementation instead.

Parameters:

matrix - a file containing a matrix

format - the format of the input matrix file

dimensions - the number of singular values to calculate

Returns:

an array of Matrix objects for the U, S, and V^T matrices in that order

Throws:

UnsupportedOperationException - if no SVD algorithm is available

svd

@Deprecated
public static Matrix[] svd(File matrix,
                      SVD.Algorithm alg,
                      MatrixIO.Format format,
                      int dimensions)

Deprecated.

Returns U, S, V^T matrices for the SVD of the matrix file in specified format using the the specified SVD algorithm available to generate the specified number of singular values.

Use a MatrixFactorization implementation instead.

Parameters:

matrix - a file containing a matrix

alg - which algorithm to use for computing the SVD

format - the format of the input matrix file

dimensions - the number of singular values to calculate

Returns:

an array of Matrix objects for the U, S, and V^T matrices in that order

Throws:

UnsupportedOperationException - if the provided SVD algorithm is unavailable

isSVDLIBCavailable

public static boolean isSVDLIBCavailable()

Returns true if the SVDLIBC library is available

isOctaveAvailable

public static boolean isOctaveAvailable()

Returns true if Octave is available

isMatlabAvailable

public static boolean isMatlabAvailable()

Returns true if Matlab is available