## org.apache.mahout.math.solver
Class ConjugateGradientSolver

    java.lang.Object
      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.