org.apache.mahout.math.solver
Class ConjugateGradientSolver

java.lang.Object
  extended by org.apache.mahout.math.solver.ConjugateGradientSolver

public class ConjugateGradientSolver
extends Object

Implementation of a conjugate gradient iterative solver for linear systems. Implements both standard conjugate gradient and pre-conditioned conjugate gradient.

Conjugate gradient requires the matrix A in the linear system Ax = b to be symmetric and positive definite. For convenience, this implementation allows the input matrix to be be non-symmetric, in which case the system A'Ax = b is solved. Because this requires only one pass through the matrix A, it is faster than explicitly computing A'A, then passing the results to the solver.

For inputs that may be ill conditioned (often the case for highly sparse input), this solver also accepts a parameter, lambda, which adds a scaled identity to the matrix A, solving the system (A + lambda*I)x = b. This obviously changes the solution, but it will guarantee solvability. The ridge regression approach to linear regression is a common use of this feature.

If only an approximate solution is required, the maximum number of iterations or the error threshold may be specified to end the algorithm early at the expense of accuracy. When the matrix A is ill conditioned, it may sometimes be necessary to increase the maximum number of iterations above the default of A.numCols() due to numerical issues.

By default the solver will run a.numCols() iterations or until the residual falls below 1E-9.

For more information on the conjugate gradient algorithm, see Golub & van Loan, "Matrix Computations", sections 10.2 and 10.3 or the conjugate gradient wikipedia article.


Field Summary
static double DEFAULT_MAX_ERROR
           
 
Constructor Summary
ConjugateGradientSolver()
           
 
Method Summary
 int getIterations()
          Returns the number of iterations run once the solver is complete.
 double getResidualNorm()
          Returns the norm of the residual at the completion of the solver.
 Vector solve(VectorIterable a, Vector b)
          Solves the system Ax = b with default termination criteria.
 Vector solve(VectorIterable a, Vector b, Preconditioner precond)
          Solves the system Ax = b with default termination criteria using the specified preconditioner.
 Vector solve(VectorIterable a, Vector b, Preconditioner preconditioner, int maxIterations, double maxError)
          Solves the system Ax = b, where A is a linear operator and b is a vector.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_MAX_ERROR

public static final double DEFAULT_MAX_ERROR
See Also:
Constant Field Values
Constructor Detail

ConjugateGradientSolver

public ConjugateGradientSolver()
Method Detail

solve

public Vector solve(VectorIterable a,
                    Vector b)
Solves the system Ax = b with default termination criteria. A must be symmetric, square, and positive definite. Only the squareness of a is checked, since testing for symmetry and positive definiteness are too expensive. If an invalid matrix is specified, then the algorithm may not yield a valid result.

Parameters:
a - The linear operator A.
b - The vector b.
Returns:
The result x of solving the system.
Throws:
IllegalArgumentException - if a is not square or if the size of b is not equal to the number of columns of a.

solve

public Vector solve(VectorIterable a,
                    Vector b,
                    Preconditioner precond)
Solves the system Ax = b with default termination criteria using the specified preconditioner. A must be symmetric, square, and positive definite. Only the squareness of a is checked, since testing for symmetry and positive definiteness are too expensive. If an invalid matrix is specified, then the algorithm may not yield a valid result.

Parameters:
a - The linear operator A.
b - The vector b.
precond - A preconditioner to use on A during the solution process.
Returns:
The result x of solving the system.
Throws:
IllegalArgumentException - if a is not square or if the size of b is not equal to the number of columns of a.

solve

public Vector solve(VectorIterable a,
                    Vector b,
                    Preconditioner preconditioner,
                    int maxIterations,
                    double maxError)
Solves the system Ax = b, where A is a linear operator and b is a vector. Uses the specified preconditioner to improve numeric stability and possibly speed convergence. This version of solve() allows control over the termination and iteration parameters.

Parameters:
a - The matrix A.
b - The vector b.
preconditioner - The preconditioner to apply.
maxIterations - The maximum number of iterations to run.
maxError - The maximum amount of residual error to tolerate. The algorithm will run until the residual falls below this value or until maxIterations are completed.
Returns:
The result x of solving the system.
Throws:
IllegalArgumentException - if the matrix is not square, if the size of b is not equal to the number of columns of A, if maxError is less than zero, or if maxIterations is not positive.

getIterations

public int getIterations()
Returns the number of iterations run once the solver is complete.

Returns:
The number of iterations run.

getResidualNorm

public double getResidualNorm()
Returns the norm of the residual at the completion of the solver. Usually this should be close to zero except in the case of a non positive definite matrix A, which results in an unsolvable system, or for ill conditioned A, in which case more iterations than the default may be needed.

Returns:
The norm of the residual in the solution.


Copyright © 2008–2014 The Apache Software Foundation. All rights reserved.