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 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: 1070725 $ $Date: 2011-02-15 02:31:12 +0100 (mar. 15 févr. 2011) $

### Field Summary

Fields
`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

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

### Method Summary

Methods
`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 optimum.

#### getResult

    public double getResult()

Get the result of the last run of the optimizer.

Specified by:
  `getResult` in interface `UnivariateRealOptimizer`
Returns:
  the optimum.

#### 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:
  the 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:
  the 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 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:
  `IllegalStateException` - if `optimize` has not been called
See Also:
  `getOptimaValues()`

#### getOptimaValues

    public double[] getOptimaValues()
                             throws 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:
  `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.