org.apache.commons.math.optimization.general

## Class NonLinearConjugateGradientOptimizer

- java.lang.Object
- - org.apache.commons.math.optimization.general.AbstractScalarDifferentiableOptimizer
  - - org.apache.commons.math.optimization.general.NonLinearConjugateGradientOptimizer

- All Implemented Interfaces:
    DifferentiableMultivariateRealOptimizer

      public class NonLinearConjugateGradientOptimizer
      extends AbstractScalarDifferentiableOptimizer

  Non-linear conjugate gradient optimizer.

  This class supports both the Fletcher-Reeves and the Polak-Ribière update formulas for the conjugate search directions. It also supports optional preconditioning.

  Since:
    2.0
  Version:
    $Revision: 1070725 $ $Date: 2011-02-15 02:31:12 +0100 (mar. 15 févr. 2011) $

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `private static class` | `NonLinearConjugateGradientOptimizer.IdentityPreconditioner` Default identity preconditioner.
    `private class` | `NonLinearConjugateGradientOptimizer.LineSearchFunction` Internal class for line search.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private double` | `initialStep` Initial step used to bracket the optimum in line search.
    `private Preconditioner` | `preconditioner` Preconditioner (may be null).
    `private UnivariateRealSolver` | `solver` solver to use in the line search (may be null).
    `private ConjugateGradientFormula` | `updateFormula` Update formula for the beta parameter.

    - ### Fields inherited from class org.apache.commons.math.optimization.general.AbstractScalarDifferentiableOptimizer

      `checker, DEFAULT_MAX_ITERATIONS, goal, point`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `NonLinearConjugateGradientOptimizer(ConjugateGradientFormula updateFormula)` Simple constructor with default settings.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected RealPointValuePair` | `doOptimize()` Perform the bulk of optimization algorithm.
    `private double` | `findUpperBound(UnivariateRealFunction f, double a, double h)` Find the upper bound b ensuring bracketing of a root between a and b
    `void` | `setInitialStep(double initialStep)` Set the initial step used to bracket the optimum in line search.
    `void` | `setLineSearchSolver(UnivariateRealSolver lineSearchSolver)` Set the solver to use during line search.
    `void` | `setPreconditioner(Preconditioner preconditioner)` Set the preconditioner.

    - ### Methods inherited from class org.apache.commons.math.optimization.general.AbstractScalarDifferentiableOptimizer

      `computeObjectiveGradient, computeObjectiveValue, getConvergenceChecker, getEvaluations, getGradientEvaluations, getIterations, getMaxEvaluations, getMaxIterations, incrementIterationsCounter, optimize, setConvergenceChecker, setMaxEvaluations, setMaxIterations`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### updateFormula

          private final ConjugateGradientFormula updateFormula

      Update formula for the beta parameter.

    - #### preconditioner

          private Preconditioner preconditioner

      Preconditioner (may be null).

    - #### solver

          private UnivariateRealSolver solver

      solver to use in the line search (may be null).

    - #### initialStep

          private double initialStep

      Initial step used to bracket the optimum in line search.

  - ### Constructor Detail

    - #### NonLinearConjugateGradientOptimizer

          public NonLinearConjugateGradientOptimizer(ConjugateGradientFormula updateFormula)

      Simple constructor with default settings.

      The convergence check is set to a `SimpleVectorialValueChecker` and the maximal number of iterations is set to `AbstractScalarDifferentiableOptimizer.DEFAULT_MAX_ITERATIONS`.

      Parameters:
        `updateFormula` - formula to use for updating the β parameter, must be one of `ConjugateGradientFormula.FLETCHER_REEVES` or `ConjugateGradientFormula.POLAK_RIBIERE`

  - ### Method Detail

    - #### setPreconditioner

          public void setPreconditioner(Preconditioner preconditioner)

      Set the preconditioner.
      Parameters:
        `preconditioner` - preconditioner to use for next optimization, may be null to remove an already registered preconditioner

    - #### setLineSearchSolver

          public void setLineSearchSolver(UnivariateRealSolver lineSearchSolver)

      Set the solver to use during line search.
      Parameters:
        `lineSearchSolver` - solver to use during line search, may be null to remove an already registered solver and fall back to the default `Brent solver`.

    - #### setInitialStep

          public void setInitialStep(double initialStep)

      Set the initial step used to bracket the optimum in line search.

      The initial step is a factor with respect to the search direction, which itself is roughly related to the gradient of the function

      Parameters:
        `initialStep` - initial step used to bracket the optimum in line search, if a non-positive value is used, the initial step is reset to its default value of 1.0

    - #### doOptimize

          protected RealPointValuePair doOptimize()
                                           throws FunctionEvaluationException,
                                                  OptimizationException,
                                                  java.lang.IllegalArgumentException

      Perform the bulk of optimization algorithm.
      Specified by:
        `doOptimize` in class `AbstractScalarDifferentiableOptimizer`
      Returns:
        the point/value pair giving the optimal value for objective function
      Throws:
        `FunctionEvaluationException` - if the objective function throws one during the search
        `OptimizationException` - if the algorithm failed to converge
        `java.lang.IllegalArgumentException` - if the start point dimension is wrong

    - #### findUpperBound

          private double findUpperBound(UnivariateRealFunction f,
                              double a,
                              double h)
                                 throws FunctionEvaluationException,
                                        OptimizationException

      Find the upper bound b ensuring bracketing of a root between a and b
      Parameters:
        `f` - function whose root must be bracketed
        `a` - lower bound of the interval
        `h` - initial step to try
      Returns:
        b such that f(a) and f(b) have opposite signs
      Throws:
        `FunctionEvaluationException` - if the function cannot be computed
        `OptimizationException` - if no bracket can be found

Copyright (c) 2003-2013 Apache Software Foundation