org.apache.mahout.math.decomposer.hebbian

Class HebbianSolver

java.lang.Object

org.apache.mahout.math.decomposer.hebbian.HebbianSolver

public class HebbianSolver
extends Object

The Hebbian solver is an iterative, sparse, singular value decomposition solver, based on the paper Generalized Hebbian Algorithm for Latent Semantic Analysis (2005) by Genevieve Gorrell and Brandyn Webb (a.k.a. Simon Funk). TODO: more description here! For now: read the inline comments, and the comments for the constructors.

Constructor Summary

Constructors

Constructor and Description
HebbianSolver(double convergenceTarget) Creates a new HebbianSolver with the default HebbianUpdater to do the updating work, and the default AsyncEigenVerifier to check for convergence in a (single) background thread, with maxPassesPerEigen set to Integer.MAX_VALUE.
HebbianSolver(double convergenceTarget, int maxPassesPerEigen) This is the recommended constructor to use if you're not sure Creates a new HebbianSolver with the default HebbianUpdater to do the updating work, and the default AsyncEigenVerifier to check for convergence in a (single) background thread.
HebbianSolver(EigenUpdater updater, SingularVectorVerifier verifier, double convergenceTarget) Creates a new HebbianSolver with maxPassesPerEigen = Integer.MAX_VALUE (i.e.
HebbianSolver(EigenUpdater updater, SingularVectorVerifier verifier, double convergenceTarget, int maxPassesPerEigen) Creates a new HebbianSolver
HebbianSolver(int numPassesPerEigen) Creates a new HebbianSolver with the default HebbianUpdater to do the updating work, and the default AsyncEigenVerifier to check for convergence in a (single) background thread, with convergenceTarget set to 0, which means that the solver will not really care about convergence as a loop-exiting criterion (but will be checking for convergence anyways, so it will be logged and singular values will be saved).

Method Summary

Methods

Modifier and Type	Method and Description
protected boolean	hasNotConverged(Vector currentPseudoEigen, Matrix corpus, TrainingState state) Uses the SingularVectorVerifier to check for convergence
static void	main(String[] args)
TrainingState	solve(Matrix corpus, int desiredRank) Primary singular vector solving method.
protected EigenStatus	verify(Matrix corpus, Vector currentPseudoEigen)

Methods inherited from class java.lang.Object

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

Constructor Detail

HebbianSolver

public HebbianSolver(EigenUpdater updater,
             SingularVectorVerifier verifier,
             double convergenceTarget,
             int maxPassesPerEigen)

Creates a new HebbianSolver

Parameters:

updater - EigenUpdater used to do the actual work of iteratively updating the current "best guess" singular vector one data-point presentation at a time.

verifier - SingularVectorVerifier an object which perpetually tries to check how close to convergence the current singular vector is (typically is a AsyncEigenVerifier which does this in the background in another thread, while the main thread continues to converge)

convergenceTarget - a small "epsilon" value which tells the solver how small you want the cosine of the angle between a proposed eigenvector and that same vector after being multiplied by the (square of the) input corpus

maxPassesPerEigen - a cutoff which tells the solver after how many times of checking for convergence (done by the verifier) should the solver stop trying, even if it has not reached the convergenceTarget.

HebbianSolver

public HebbianSolver(EigenUpdater updater,
             SingularVectorVerifier verifier,
             double convergenceTarget)

Creates a new HebbianSolver with maxPassesPerEigen = Integer.MAX_VALUE (i.e. keep on iterating until convergenceTarget is reached). Not recommended unless only looking for the first few (5, maybe 10?) singular vectors, as small errors which compound early on quickly put a minimum error on subsequent vectors.

Parameters:

updater - EigenUpdater used to do the actual work of iteratively updating the current "best guess" singular vector one data-point presentation at a time.

verifier - SingularVectorVerifier an object which perpetually tries to check how close to convergence the current singular vector is (typically is a AsyncEigenVerifier which does this in the background in another thread, while the main thread continues to converge)

convergenceTarget - a small "epsilon" value which tells the solver how small you want the cosine of the angle between a proposed eigenvector and that same vector after being multiplied by the (square of the) input corpus

HebbianSolver

public HebbianSolver(double convergenceTarget,
             int maxPassesPerEigen)

This is the recommended constructor to use if you're not sure Creates a new HebbianSolver with the default HebbianUpdater to do the updating work, and the default AsyncEigenVerifier to check for convergence in a (single) background thread.

Parameters:

convergenceTarget - a small "epsilon" value which tells the solver how small you want the cosine of the angle between a proposed eigenvector and that same vector after being multiplied by the (square of the) input corpus

maxPassesPerEigen - a cutoff which tells the solver after how many times of checking for convergence (done by the verifier) should the solver stop trying, even if it has not reached the convergenceTarget.

HebbianSolver

public HebbianSolver(double convergenceTarget)

Creates a new HebbianSolver with the default HebbianUpdater to do the updating work, and the default AsyncEigenVerifier to check for convergence in a (single) background thread, with maxPassesPerEigen set to Integer.MAX_VALUE. Not recommended unless only looking for the first few (5, maybe 10?) singular vectors, as small errors which compound early on quickly put a minimum error on subsequent vectors.

Parameters:

convergenceTarget - a small "epsilon" value which tells the solver how small you want the cosine of the angle between a proposed eigenvector and that same vector after being multiplied by the (square of the) input corpus

HebbianSolver

public HebbianSolver(int numPassesPerEigen)

Creates a new HebbianSolver with the default HebbianUpdater to do the updating work, and the default AsyncEigenVerifier to check for convergence in a (single) background thread, with convergenceTarget set to 0, which means that the solver will not really care about convergence as a loop-exiting criterion (but will be checking for convergence anyways, so it will be logged and singular values will be saved).

Parameters:

numPassesPerEigen - the exact number of times the verifier will check convergence status in the background before the solver will move on to the next eigen-vector.

Method Detail

solve

public TrainingState solve(Matrix corpus,
                  int desiredRank)

Primary singular vector solving method.

Parameters:

corpus - input matrix to find singular vectors of. Needs not be symmetric, should probably be sparse (in fact the input vectors are not mutated, and accessed only via dot-products and sums, so they should be SequentialAccessSparseVector

desiredRank - the number of singular vectors to find (in roughly decreasing order by singular value)

Returns:

the final TrainingState of the solver, after desiredRank singular vectors (and approximate singular values) have been found.

hasNotConverged

protected boolean hasNotConverged(Vector currentPseudoEigen,
                      Matrix corpus,
                      TrainingState state)

Uses the SingularVectorVerifier to check for convergence

Parameters:

currentPseudoEigen - the purported singular vector whose convergence is being checked

corpus - the corpus to check against

state - contains the previous eigens, various other solving state TrainingState

Returns:

true if either we have converged, or maxPassesPerEigen has been exceeded.

verify

protected EigenStatus verify(Matrix corpus,
                 Vector currentPseudoEigen)

main

public static void main(String[] args)