## org.apache.commons.math.optimization
Class MultiStartUnivariateRealOptimizer

    java.lang.Object
      org.apache.commons.math.optimization.MultiStartUnivariateRealOptimizer

All Implemented Interfaces:
  ConvergingAlgorithm, UnivariateRealOptimizer

    public class MultiStartUnivariateRealOptimizer

extends java.lang.Object
implements UnivariateRealOptimizer

Special implementation of the `UnivariateRealOptimizer` interface adding multi-start features to an existing optimizer.

This class wraps a classical optimizer to use it several times in turn with different starting points in order to avoid being trapped into a local extremum when looking for a global one.

Since:
  2.0
Version:
  $Revision: 811685 $ $Date: 2009-09-05 13:36:48 -0400 (Sat, 05 Sep 2009) $

Field Summary
`private RandomGenerator` `generator` Random generator for multi-start.
`private int` `maxEvaluations` Maximal number of evaluations allowed.
`private int` `maxIterations` Maximal number of iterations allowed.
`private double[]` `optima` Found optima.
`private double[]` `optimaValues` Found function values at optima.
`private UnivariateRealOptimizer` `optimizer` Underlying classical optimizer.
`private static long` `serialVersionUID` Serializable version identifier.
`private int` `starts` Number of starts to go.
`private int` `totalEvaluations` Number of evaluations already performed for all starts.
`private int` `totalIterations` Number of iterations already performed for all starts.

Constructor Summary
`MultiStartUnivariateRealOptimizer(UnivariateRealOptimizer optimizer, int starts, RandomGenerator generator)` Create a multi-start optimizer from a single-start optimizer

Method Summary
`double` `getAbsoluteAccuracy()` Get the actual absolute accuracy.
`int` `getEvaluations()` Get the number of evaluations of the objective function.
`double` `getFunctionValue()` Get the result of the last run of the optimizer.
`int` `getIterationCount()` Get the number of iterations in the last run of the algorithm.
`int` `getMaxEvaluations()` Get the maximal number of functions evaluations.
`int` `getMaximalIterationCount()` Get the upper limit for the number of iterations.
`double[]` `getOptima()` Get all the optima found during the last call to `optimize`.
`double[]` `getOptimaValues()` Get all the function values at optima found during the last call to `optimize`.
`double` `getRelativeAccuracy()` Get the actual relative accuracy.
`double` `getResult()` Get the result of the last run of the optimizer.
`double` `optimize(UnivariateRealFunction f, GoalType goalType, double min, double max)` Find an optimum in the given interval.
`double` `optimize(UnivariateRealFunction f, GoalType goalType, double min, double max, double startValue)` Find an optimum in the given interval, start at startValue.
`void` `resetAbsoluteAccuracy()` Reset the absolute accuracy to the default.
`void` `resetMaximalIterationCount()` Reset the upper limit for the number of iterations to the default.
`void` `resetRelativeAccuracy()` Reset the relative accuracy to the default.
`void` `setAbsoluteAccuracy(double accuracy)` Set the absolute accuracy.
`void` `setMaxEvaluations(int maxEvaluations)` Set the maximal number of functions evaluations.
`void` `setMaximalIterationCount(int count)` Set the upper limit for the number of iterations.
`void` `setRelativeAccuracy(double accuracy)` Set the relative accuracy.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### serialVersionUID

    private static final long serialVersionUID

  Serializable version identifier.

  See Also:
    Constant Field Values

### optimizer

    private final UnivariateRealOptimizer optimizer

  Underlying classical optimizer.

### maxIterations

    private int maxIterations

  Maximal number of iterations allowed.

### maxEvaluations

    private int maxEvaluations

  Maximal number of evaluations allowed.

### totalIterations

    private int totalIterations

  Number of iterations already performed for all starts.

### totalEvaluations

    private int totalEvaluations

  Number of evaluations already performed for all starts.

### starts

    private int starts

  Number of starts to go.

### generator

    private RandomGenerator generator

  Random generator for multi-start.

### optima

    private double[] optima

  Found optima.

### optimaValues

    private double[] optimaValues

  Found function values at optima.

Constructor Detail

### MultiStartUnivariateRealOptimizer

    public MultiStartUnivariateRealOptimizer(UnivariateRealOptimizer optimizer,
                                             int starts,
                                             RandomGenerator generator)

  Create a multi-start optimizer from a single-start optimizer

  Parameters:
    `optimizer` - single-start optimizer to wrap
    `starts` - number of starts to perform (including the first one), multi-start is disabled if value is less than or equal to 1
    `generator` - random generator to use for restarts

Method Detail

### getFunctionValue

    public double getFunctionValue()

  Get the result of the last run of the optimizer.

  Specified by:
    `getFunctionValue` in interface `UnivariateRealOptimizer`
  Returns:
    the value of the function at the last result.

### getResult

    public double getResult()

  Get the result of the last run of the optimizer.

  Specified by:
    `getResult` in interface `UnivariateRealOptimizer`
  Returns:
    the last result.

### getAbsoluteAccuracy

    public double getAbsoluteAccuracy()

  Get the actual absolute accuracy.

  Specified by:
    `getAbsoluteAccuracy` in interface `ConvergingAlgorithm`
  Returns:
    the accuracy

### getIterationCount

    public int getIterationCount()

  Get the number of iterations in the last run of the algorithm.

  This is mainly meant for testing purposes. It may occasionally help track down performance problems: if the iteration count is notoriously high, check whether the problem is evaluated properly, and whether another algorithm is more amenable to the problem.

  Specified by:
    `getIterationCount` in interface `ConvergingAlgorithm`
  Returns:
    the last iteration count.

### getMaximalIterationCount

    public int getMaximalIterationCount()

  Get the upper limit for the number of iterations.

  Specified by:
    `getMaximalIterationCount` in interface `ConvergingAlgorithm`
  Returns:
    the actual upper limit

### getMaxEvaluations

    public int getMaxEvaluations()

  Get the maximal number of functions evaluations.

  Specified by:
    `getMaxEvaluations` in interface `UnivariateRealOptimizer`
  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 `UnivariateRealOptimizer`
  Returns:
    number of evaluations of the objective function

### getRelativeAccuracy

    public double getRelativeAccuracy()

  Get the actual relative accuracy.

  Specified by:
    `getRelativeAccuracy` in interface `ConvergingAlgorithm`
  Returns:
    the accuracy

### resetAbsoluteAccuracy

    public void resetAbsoluteAccuracy()

  Reset the absolute accuracy to the default.

  The default value is provided by the algorithm implementation.

  Specified by:
    `resetAbsoluteAccuracy` in interface `ConvergingAlgorithm`

### resetMaximalIterationCount

    public void resetMaximalIterationCount()

  Reset the upper limit for the number of iterations to the default.

  The default value is supplied by the algorithm implementation.

  Specified by:
    `resetMaximalIterationCount` in interface `ConvergingAlgorithm`
  See Also:
    `ConvergingAlgorithm.setMaximalIterationCount(int)`

### resetRelativeAccuracy

    public void resetRelativeAccuracy()

  Reset the relative accuracy to the default. The default value is provided by the algorithm implementation.

  Specified by:
    `resetRelativeAccuracy` in interface `ConvergingAlgorithm`

### setAbsoluteAccuracy

    public void setAbsoluteAccuracy(double accuracy)

  Set the absolute accuracy.

  The default is usually chosen so that results in the interval -10..-0.1 and +0.1..+10 can be found with a reasonable accuracy. If the expected absolute value of your results is of much smaller magnitude, set this to a smaller value.

  Algorithms are advised to do a plausibility check with the relative accuracy, but clients should not rely on this.

  Specified by:
    `setAbsoluteAccuracy` in interface `ConvergingAlgorithm`
  Parameters:
    `accuracy` - the accuracy.

### setMaximalIterationCount

    public void setMaximalIterationCount(int count)

  Set the upper limit for the number of iterations.

  Usually a high iteration count indicates convergence problems. However, the "reasonable value" varies widely for different algorithms. Users are advised to use the default value supplied by the algorithm.

  A `ConvergenceException` will be thrown if this number is exceeded.

  Specified by:
    `setMaximalIterationCount` in interface `ConvergingAlgorithm`
  Parameters:
    `count` - maximum number of iterations

### setMaxEvaluations

    public void setMaxEvaluations(int maxEvaluations)

  Set the maximal number of functions evaluations.

  Specified by:
    `setMaxEvaluations` in interface `UnivariateRealOptimizer`
  Parameters:
    `maxEvaluations` - maximal number of function evaluations

### setRelativeAccuracy

    public void setRelativeAccuracy(double accuracy)

  Set the relative accuracy.

  This is used to stop iterations if the absolute accuracy can't be achieved due to large values or short mantissa length.

  If this should be the primary criterion for convergence rather then a safety measure, set the absolute accuracy to a ridiculously small value, like `MathUtils.SAFE_MIN`.

  Specified by:
    `setRelativeAccuracy` in interface `ConvergingAlgorithm`
  Parameters:
    `accuracy` - the relative accuracy.

### getOptima

    public double[] getOptima()
                       throws java.lang.IllegalStateException

  Get all the optima found during the last call to `optimize`.

  The optimizer stores all the optima found during a set of restarts. The `optimize` method returns the best point only. This method returns all the points found at the end of each starts, including the best one already returned by the `optimize` method.

  The returned array as one element for each start as specified in the constructor. It is ordered with the results from the runs that did converge first, sorted from best to worst objective value (i.e in ascending order if minimizing and in descending order if maximizing), followed by Double.NaN elements corresponding to the runs that did not converge. This means all elements will be NaN if the `optimize` method did throw a `ConvergenceException`). This also means that if the first element is not NaN, it is the best point found across all starts.

  Returns:
    array containing the optima
  Throws:
    `java.lang.IllegalStateException` - if `optimize` has not been called
  See Also:
    `getOptimaValues()`

### getOptimaValues

    public double[] getOptimaValues()
                             throws java.lang.IllegalStateException

  Get all the function values at optima found during the last call to `optimize`.

  The returned array as one element for each start as specified in the constructor. It is ordered with the results from the runs that did converge first, sorted from best to worst objective value (i.e in ascending order if minimizing and in descending order if maximizing), followed by Double.NaN elements corresponding to the runs that did not converge. This means all elements will be NaN if the `optimize` method did throw a `ConvergenceException`). This also means that if the first element is not NaN, it is the best point found across all starts.

  Returns:
    array containing the optima
  Throws:
    `java.lang.IllegalStateException` - if `optimize` has not been called
  See Also:
    `getOptima()`

### optimize

    public double optimize(UnivariateRealFunction f,
                           GoalType goalType,
                           double min,
                           double max)
                    throws ConvergenceException,
                           FunctionEvaluationException

  Find an optimum in the given interval.

  An optimizer may require that the interval brackets a single optimum.

  Specified by:
    `optimize` in interface `UnivariateRealOptimizer`
  Parameters:
    `f` - the function to optimize.
    `goalType` - type of optimization goal: either `GoalType.MAXIMIZE` or `GoalType.MINIMIZE`
    `min` - the lower bound for the interval.
    `max` - the upper bound for the interval.
  Returns:
    a value where the function is optimum
  Throws:
    `ConvergenceException` - if the maximum iteration count is exceeded or the optimizer detects convergence problems otherwise.
    `FunctionEvaluationException` - if an error occurs evaluating the function

### optimize

    public double optimize(UnivariateRealFunction f,
                           GoalType goalType,
                           double min,
                           double max,
                           double startValue)
                    throws ConvergenceException,
                           FunctionEvaluationException

  Find an optimum in the given interval, start at startValue.

  An optimizer may require that the interval brackets a single optimum.

  Specified by:
    `optimize` in interface `UnivariateRealOptimizer`
  Parameters:
    `f` - the function to optimize.
    `goalType` - type of optimization goal: either `GoalType.MAXIMIZE` or `GoalType.MINIMIZE`
    `min` - the lower bound for the interval.
    `max` - the upper bound for the interval.
    `startValue` - the start value to use
  Returns:
    a value where the function is optimum
  Throws:
    `ConvergenceException` - if the maximum iteration count is exceeded or the optimizer detects convergence problems otherwise.
    `FunctionEvaluationException` - if an error occurs evaluating the function

Copyright (c) 2003-2011 Apache Software Foundation