org.apache.commons.math.optimization.general

## Class AbstractScalarDifferentiableOptimizer

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

- All Implemented Interfaces:
    DifferentiableMultivariateRealOptimizer
  Direct Known Subclasses:
    NonLinearConjugateGradientOptimizer, PowellOptimizer

      public abstract class AbstractScalarDifferentiableOptimizer
      extends Object
      implements DifferentiableMultivariateRealOptimizer

  Base class for implementing optimizers for multivariate scalar functions.

  This base class handles the boilerplate methods associated to thresholds settings, iterations and evaluations counting.

  Since:
    2.0
  Version:
    $Revision: 1069567 $ $Date: 2011-02-10 22:07:26 +0100 (jeu. 10 févr. 2011) $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected RealConvergenceChecker` | `checker` Deprecated.
    `static int` | `DEFAULT_MAX_ITERATIONS` Default maximal number of iterations allowed.
    `private int` | `evaluations` Number of evaluations already performed.
    `private DifferentiableMultivariateRealFunction` | `function` Objective function.
    `protected GoalType` | `goal` Deprecated.
    `private MultivariateVectorialFunction` | `gradient` Objective function gradient.
    `private int` | `gradientEvaluations` Number of gradient evaluations.
    `private int` | `iterations` Number of iterations already performed.
    `private int` | `maxEvaluations` Maximal number of evaluations allowed.
    `private int` | `maxIterations` Maximal number of iterations allowed.
    `protected double[]` | `point` Deprecated.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AbstractScalarDifferentiableOptimizer()` Simple constructor with default settings.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected double[]` | `computeObjectiveGradient(double[] evaluationPoint)` Compute the gradient vector.
    `protected double` | `computeObjectiveValue(double[] evaluationPoint)` Compute the objective function value.
    `protected abstract RealPointValuePair` | `doOptimize()` Perform the bulk of optimization algorithm.
    `RealConvergenceChecker` | `getConvergenceChecker()` Get the convergence checker.
    `int` | `getEvaluations()` Get the number of evaluations of the objective function.
    `int` | `getGradientEvaluations()` Get the number of evaluations of the objective function gradient.
    `int` | `getIterations()` Get the number of iterations realized by the algorithm.
    `int` | `getMaxEvaluations()` Get the maximal number of functions evaluations.
    `int` | `getMaxIterations()` Get the maximal number of iterations of the algorithm.
    `protected void` | `incrementIterationsCounter()` Increment the iterations counter by 1.
    `RealPointValuePair` | `optimize(DifferentiableMultivariateRealFunction f, GoalType goalType, double[] startPoint)` Optimizes an objective function.
    `void` | `setConvergenceChecker(RealConvergenceChecker convergenceChecker)` Set the convergence checker.
    `void` | `setMaxEvaluations(int maxEvaluations)` Set the maximal number of functions evaluations.
    `void` | `setMaxIterations(int maxIterations)` Set the maximal number of iterations of the algorithm.

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

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

- - ### Field Detail

    - #### DEFAULT_MAX_ITERATIONS

          public static final int DEFAULT_MAX_ITERATIONS

      Default maximal number of iterations allowed.
      See Also:
        Constant Field Values

    - #### checker

          @Deprecated
          protected RealConvergenceChecker checker

      Deprecated.
      Convergence checker.

    - #### goal

          @Deprecated
          protected GoalType goal

      Deprecated.
      Type of optimization.
      Since:
        2.1

    - #### point

          @Deprecated
          protected double[] point

      Deprecated.
      Current point set.

    - #### maxIterations

          private int maxIterations

      Maximal number of iterations allowed.

    - #### iterations

          private int iterations

      Number of iterations already performed.

    - #### maxEvaluations

          private int maxEvaluations

      Maximal number of evaluations allowed.

    - #### evaluations

          private int evaluations

      Number of evaluations already performed.

    - #### gradientEvaluations

          private int gradientEvaluations

      Number of gradient evaluations.

    - #### function

          private DifferentiableMultivariateRealFunction function

      Objective function.

    - #### gradient

          private MultivariateVectorialFunction gradient

      Objective function gradient.

  - ### Constructor Detail

    - #### AbstractScalarDifferentiableOptimizer

          protected AbstractScalarDifferentiableOptimizer()

      Simple constructor with default settings.

      The convergence check is set to a `SimpleScalarValueChecker` and the maximal number of evaluation is set to its default value.

  - ### Method Detail

    - #### setMaxIterations

          public void setMaxIterations(int maxIterations)

      Set the maximal number of iterations of the algorithm.
      Specified by:
        `setMaxIterations` in interface `DifferentiableMultivariateRealOptimizer`
      Parameters:
        `maxIterations` - maximal number of function calls

    - #### getMaxIterations

          public int getMaxIterations()

      Get the maximal number of iterations of the algorithm.
      Specified by:
        `getMaxIterations` in interface `DifferentiableMultivariateRealOptimizer`
      Returns:
        maximal number of iterations

    - #### getIterations

          public int getIterations()

      Get the number of iterations realized by the algorithm.

      The number of evaluations corresponds to the last call to the `optimize` method. It is 0 if the method has not been called yet.

      Specified by:
        `getIterations` in interface `DifferentiableMultivariateRealOptimizer`
      Returns:
        number of iterations

    - #### setMaxEvaluations

          public void setMaxEvaluations(int maxEvaluations)

      Set the maximal number of functions evaluations.
      Specified by:
        `setMaxEvaluations` in interface `DifferentiableMultivariateRealOptimizer`
      Parameters:
        `maxEvaluations` - maximal number of function evaluations

    - #### getMaxEvaluations

          public int getMaxEvaluations()

      Get the maximal number of functions evaluations.
      Specified by:
        `getMaxEvaluations` in interface `DifferentiableMultivariateRealOptimizer`
      Returns:
        maximal number of functions evaluations

    - #### getEvaluations

          public int getEvaluations()

      Get the number of evaluations of the objective function.

      The number of evaluations corresponds to the last call to the `optimize` method. It is 0 if the method has not been called yet.

      Specified by:
        `getEvaluations` in interface `DifferentiableMultivariateRealOptimizer`
      Returns:
        number of evaluations of the objective function

    - #### getGradientEvaluations

          public int getGradientEvaluations()

      Get the number of evaluations of the objective function gradient.

      The number of evaluations corresponds to the last call to the `optimize` method. It is 0 if the method has not been called yet.

      Specified by:
        `getGradientEvaluations` in interface `DifferentiableMultivariateRealOptimizer`
      Returns:
        number of evaluations of the objective function gradient

    - #### setConvergenceChecker

          public void setConvergenceChecker(RealConvergenceChecker convergenceChecker)

      Set the convergence checker.
      Specified by:
        `setConvergenceChecker` in interface `DifferentiableMultivariateRealOptimizer`
      Parameters:
        `convergenceChecker` - object to use to check for convergence

    - #### getConvergenceChecker

          public RealConvergenceChecker getConvergenceChecker()

      Get the convergence checker.
      Specified by:
        `getConvergenceChecker` in interface `DifferentiableMultivariateRealOptimizer`
      Returns:
        object used to check for convergence

    - #### incrementIterationsCounter

          protected void incrementIterationsCounter()
                                             throws OptimizationException

      Increment the iterations counter by 1.
      Throws:
        `OptimizationException` - if the maximal number of iterations is exceeded

    - #### computeObjectiveGradient

          protected double[] computeObjectiveGradient(double[] evaluationPoint)
                                               throws FunctionEvaluationException

      Compute the gradient vector.
      Parameters:
        `evaluationPoint` - point at which the gradient must be evaluated
      Returns:
        gradient at the specified point
      Throws:
        `FunctionEvaluationException` - if the function gradient

    - #### computeObjectiveValue

          protected double computeObjectiveValue(double[] evaluationPoint)
                                          throws FunctionEvaluationException

      Compute the objective function value.
      Parameters:
        `evaluationPoint` - point at which the objective function must be evaluated
      Returns:
        objective function value at specified point
      Throws:
        `FunctionEvaluationException` - if the function cannot be evaluated or its dimension doesn't match problem dimension or the maximal number of iterations is exceeded

    - #### optimize

          public RealPointValuePair optimize(DifferentiableMultivariateRealFunction f,
                                    GoalType goalType,
                                    double[] startPoint)
                                      throws FunctionEvaluationException,
                                             OptimizationException,
                                             IllegalArgumentException

      Optimizes an objective function.
      Specified by:
        `optimize` in interface `DifferentiableMultivariateRealOptimizer`
      Parameters:
        `f` - objective function
        `goalType` - type of optimization goal: either `GoalType.MAXIMIZE` or `GoalType.MINIMIZE`
        `startPoint` - the start point for optimization
      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
        `IllegalArgumentException` - if the start point dimension is wrong

    - #### doOptimize

          protected abstract RealPointValuePair doOptimize()
                                                    throws FunctionEvaluationException,
                                                           OptimizationException,
                                                           IllegalArgumentException

      Perform the bulk of optimization algorithm.
      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
        `IllegalArgumentException` - if the start point dimension is wrong

Copyright (c) 2003-2013 Apache Software Foundation