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) $

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

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.