org.apache.commons.math3.optim.nonlinear.scalar.gradient

## Class NonLinearConjugateGradientOptimizer

- java.lang.Object
- - org.apache.commons.math3.optim.BaseOptimizer<PAIR>
  - - org.apache.commons.math3.optim.BaseMultivariateOptimizer<PointValuePair>
    - - org.apache.commons.math3.optim.nonlinear.scalar.MultivariateOptimizer
      - - org.apache.commons.math3.optim.nonlinear.scalar.GradientMultivariateOptimizer
        - - org.apache.commons.math3.optim.nonlinear.scalar.gradient.NonLinearConjugateGradientOptimizer

-     public class NonLinearConjugateGradientOptimizer
      extends GradientMultivariateOptimizer

  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:
    $Id: NonLinearConjugateGradientOptimizer.java 1416643 2012-12-03 19:37:14Z tn $

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `NonLinearConjugateGradientOptimizer.BracketingStep` The initial step is a factor with respect to the search direction (which itself is roughly related to the gradient of the function).
    `static class` | `NonLinearConjugateGradientOptimizer.Formula` Available choices of update formulas for the updating the parameter that is used to compute the successive conjugate search directions.
    `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 UnivariateSolver` | `solver` solver to use in the line search (may be null).
    `private NonLinearConjugateGradientOptimizer.Formula` | `updateFormula` Update formula for the beta parameter.

    - ### Fields inherited from class org.apache.commons.math3.optim.BaseOptimizer

      `evaluations, iterations`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `NonLinearConjugateGradientOptimizer(NonLinearConjugateGradientOptimizer.Formula updateFormula, ConvergenceChecker<PointValuePair> checker)` Constructor with default `line search solver` and `preconditioner`.
    `NonLinearConjugateGradientOptimizer(NonLinearConjugateGradientOptimizer.Formula updateFormula, ConvergenceChecker<PointValuePair> checker, UnivariateSolver lineSearchSolver)` Constructor with default `preconditioner`.
    `NonLinearConjugateGradientOptimizer(NonLinearConjugateGradientOptimizer.Formula updateFormula, ConvergenceChecker<PointValuePair> checker, UnivariateSolver lineSearchSolver, Preconditioner preconditioner)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected PointValuePair` | `doOptimize()` Performs the bulk of the optimization algorithm.
    `private double` | `findUpperBound(UnivariateFunction f, double a, double h)` Finds the upper bound b ensuring bracketing of a root between a and b.
    `PointValuePair` | `optimize(OptimizationData... optData)` Stores data and performs the optimization.
    `private void` | `parseOptimizationData(OptimizationData... optData)` Scans the list of (required and optional) optimization data that characterize the problem.

    - ### Methods inherited from class org.apache.commons.math3.optim.nonlinear.scalar.GradientMultivariateOptimizer

      `computeObjectiveGradient`

    - ### Methods inherited from class org.apache.commons.math3.optim.nonlinear.scalar.MultivariateOptimizer

      `computeObjectiveValue, getGoalType`

    - ### Methods inherited from class org.apache.commons.math3.optim.BaseMultivariateOptimizer

      `getLowerBound, getStartPoint, getUpperBound`

    - ### Methods inherited from class org.apache.commons.math3.optim.BaseOptimizer

      `getConvergenceChecker, getEvaluations, getIterations, getMaxEvaluations, getMaxIterations, incrementEvaluationCount, incrementIterationCount`

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

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

- - ### Field Detail

    - #### updateFormula

          private final NonLinearConjugateGradientOptimizer.Formula updateFormula

      Update formula for the beta parameter.

    - #### preconditioner

          private final Preconditioner preconditioner

      Preconditioner (may be null).

    - #### solver

          private final UnivariateSolver 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(NonLinearConjugateGradientOptimizer.Formula updateFormula,
                                             ConvergenceChecker<PointValuePair> checker)

      Constructor with default `line search solver` and `preconditioner`.
      Parameters:
        `updateFormula` - formula to use for updating the β parameter, must be one of `NonLinearConjugateGradientOptimizer.Formula.FLETCHER_REEVES` or `NonLinearConjugateGradientOptimizer.Formula.POLAK_RIBIERE`.
        `checker` - Convergence checker.

    - #### NonLinearConjugateGradientOptimizer

          public NonLinearConjugateGradientOptimizer(NonLinearConjugateGradientOptimizer.Formula updateFormula,
                                             ConvergenceChecker<PointValuePair> checker,
                                             UnivariateSolver lineSearchSolver)

      Constructor with default `preconditioner`.
      Parameters:
        `updateFormula` - formula to use for updating the β parameter, must be one of `NonLinearConjugateGradientOptimizer.Formula.FLETCHER_REEVES` or `NonLinearConjugateGradientOptimizer.Formula.POLAK_RIBIERE`.
        `checker` - Convergence checker.
        `lineSearchSolver` - Solver to use during line search.

    - #### NonLinearConjugateGradientOptimizer

          public NonLinearConjugateGradientOptimizer(NonLinearConjugateGradientOptimizer.Formula updateFormula,
                                             ConvergenceChecker<PointValuePair> checker,
                                             UnivariateSolver lineSearchSolver,
                                             Preconditioner preconditioner)

      Parameters:
        `updateFormula` - formula to use for updating the β parameter, must be one of `NonLinearConjugateGradientOptimizer.Formula.FLETCHER_REEVES` or `NonLinearConjugateGradientOptimizer.Formula.POLAK_RIBIERE`.
        `checker` - Convergence checker.
        `lineSearchSolver` - Solver to use during line search.
        `preconditioner` - Preconditioner.

  - ### Method Detail

    - #### optimize

          public PointValuePair optimize(OptimizationData... optData)
                                  throws TooManyEvaluationsException

      Stores data and performs the optimization.
      Overrides:
        `optimize` in class `GradientMultivariateOptimizer`
      Parameters:
        `optData` - Optimization data. The following data will be looked for:
        - `MaxEval`
        - `InitialGuess`
        - `SimpleBounds`
        - `GoalType`
        - `ObjectiveFunction`
        - `ObjectiveFunctionGradient`
        - `NonLinearConjugateGradientOptimizer.BracketingStep`
      Returns:
        a point/value pair that satifies the convergence criteria.
      Throws:
        `TooManyEvaluationsException` - if the maximal number of evaluations (of the objective function) is exceeded.

    - #### doOptimize

          protected PointValuePair doOptimize()

      Performs the bulk of the optimization algorithm.
      Specified by:
        `doOptimize` in class `BaseOptimizer<PointValuePair>`
      Returns:
        the point/value pair giving the optimal value of the objective function.

    - #### parseOptimizationData

          private void parseOptimizationData(OptimizationData... optData)

      Scans the list of (required and optional) optimization data that characterize the problem.
      Parameters:
        `optData` - Optimization data. The following data will be looked for:
        - `InitialStep`

    - #### findUpperBound

          private double findUpperBound(UnivariateFunction f,
                              double a,
                              double h)

      Finds 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:
        `MathIllegalStateException` - if no bracket can be found.

Copyright (c) 2003-2013 Apache Software Foundation