src/main/java/org/apache/commons/math/optimization/univariate/AbstractUnivariateRealOptimizer.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.commons.math.optimization.univariate;

import org.apache.commons.math.ConvergingAlgorithmImpl;
import org.apache.commons.math.FunctionEvaluationException;
import org.apache.commons.math.MaxEvaluationsExceededException;
import org.apache.commons.math.MaxIterationsExceededException;
import org.apache.commons.math.analysis.UnivariateRealFunction;
import org.apache.commons.math.exception.MathUnsupportedOperationException;
import org.apache.commons.math.exception.NoDataException;
import org.apache.commons.math.exception.util.LocalizedFormats;
import org.apache.commons.math.optimization.GoalType;
import org.apache.commons.math.optimization.UnivariateRealOptimizer;

/**
 * Provide a default implementation for several functions useful to generic
 * optimizers.
 *
 * @version $Revision: 1070725 $ $Date: 2011-02-15 02:31:12 +0100 (mar. 15 févr. 2011) $
 * @since 2.0
 */
public abstract class AbstractUnivariateRealOptimizer
    extends ConvergingAlgorithmImpl implements UnivariateRealOptimizer {
    /** Indicates where a root has been computed. */
    protected boolean resultComputed;
    /** The last computed root. */
    protected double result;
    /** Value of the function at the last computed result. */
    protected double functionValue;
    /** Maximal number of evaluations allowed. */
    private int maxEvaluations;
    /** Number of evaluations already performed. */
    private int evaluations;
    /** Optimization type */
    private GoalType optimizationGoal;
    /** Lower end of search interval. */
    private double searchMin;
    /** Higher end of search interval. */
    private double searchMax;
    /** Initial guess . */
    private double searchStart;
    /** Function to optimize. */
    private UnivariateRealFunction function;

    /**
     * Construct a solver with given iteration count and accuracy.
     * @param defaultAbsoluteAccuracy maximum absolute error
     * @param defaultMaximalIterationCount maximum number of iterations
     * @throws IllegalArgumentException if f is null or the
     * defaultAbsoluteAccuracy is not valid
     * @deprecated in 2.2. Please use the "setter" methods to assign meaningful
     * values to the maximum numbers of iterations and evaluations, and to the
     * absolute and relative accuracy thresholds.
     */
    @Deprecated
    protected AbstractUnivariateRealOptimizer(final int defaultMaximalIterationCount,
                                              final double defaultAbsoluteAccuracy) {
        super(defaultMaximalIterationCount, defaultAbsoluteAccuracy);
        resultComputed = false;
        setMaxEvaluations(Integer.MAX_VALUE);
    }

    /**
     * Default constructor.
     * To be removed once the single non-default one has been removed.
     */
    protected AbstractUnivariateRealOptimizer() {}

    /**
     * Check whether a result has been computed.
     * @throws NoDataException if no result has been computed
     * @deprecated in 2.2 (no alternative).
     */
    @Deprecated
    protected void checkResultComputed() {
        if (!resultComputed) {
            throw new NoDataException();
        }
    }

    /** {@inheritDoc} */
    public double getResult() {
        if (!resultComputed) {
            throw new NoDataException();
        }
        return result;
    }

    /** {@inheritDoc} */
    public double getFunctionValue() throws FunctionEvaluationException {
        if (Double.isNaN(functionValue)) {
            final double opt = getResult();
            functionValue = function.value(opt);
        }
        return functionValue;
    }

    /**
     * Convenience function for implementations.
     *
     * @param x the result to set
     * @param fx the result to set
     * @param iterationCount the iteration count to set
     * @deprecated in 2.2 (no alternative).
     */
    @Deprecated
    protected final void setResult(final double x, final double fx,
                                   final int iterationCount) {
        this.result         = x;
        this.functionValue  = fx;
        this.iterationCount = iterationCount;
        this.resultComputed = true;
    }

    /**
     * Convenience function for implementations.
     * @deprecated in 2.2 (no alternative).
     */
    @Deprecated
    protected final void clearResult() {
        this.resultComputed = false;
    }

    /** {@inheritDoc} */
    public void setMaxEvaluations(int maxEvaluations) {
        this.maxEvaluations = maxEvaluations;
    }

    /** {@inheritDoc} */
    public int getMaxEvaluations() {
        return maxEvaluations;
    }

    /** {@inheritDoc} */
    public int getEvaluations() {
        return evaluations;
    }

    /**
     * @return the optimization type.
     */
    public GoalType getGoalType() {
        return optimizationGoal;
    }
    /**
     * @return the lower of the search interval.
     */
    public double getMin() {
        return searchMin;
    }
    /**
     * @return the higher of the search interval.
     */
    public double getMax() {
        return searchMax;
    }
    /**
     * @return the initial guess.
     */
    public double getStartValue() {
        return searchStart;
    }

    /**
     * Compute the objective function value.
     * @param f objective function
     * @param point point at which the objective function must be evaluated
     * @return objective function value at specified point
     * @exception FunctionEvaluationException if the function cannot be evaluated
     * or the maximal number of iterations is exceeded
     * @deprecated in 2.2. Use this {@link #computeObjectiveValue(double)
     * replacement} instead.
     */
    @Deprecated
    protected double computeObjectiveValue(final UnivariateRealFunction f,
                                           final double point)
        throws FunctionEvaluationException {
        if (++evaluations > maxEvaluations) {
            throw new FunctionEvaluationException(new MaxEvaluationsExceededException(maxEvaluations), point);
        }
        return f.value(point);
    }

    /**
     * Compute the objective function value.
     *
     * @param point Point at which the objective function must be evaluated.
     * @return the objective function value at specified point.
     * @exception FunctionEvaluationException if the function cannot be evaluated
     * or the maximal number of iterations is exceeded.
     */
    protected double computeObjectiveValue(double point)
        throws FunctionEvaluationException {
        if (++evaluations > maxEvaluations) {
            resultComputed = false;
            throw new FunctionEvaluationException(new MaxEvaluationsExceededException(maxEvaluations), point);
        }
        return function.value(point);
    }

    /** {@inheritDoc} */
    public double optimize(UnivariateRealFunction f, GoalType goal,
                           double min, double max, double startValue)
        throws MaxIterationsExceededException, FunctionEvaluationException {
        // Initialize.
        this.searchMin = min;
        this.searchMax = max;
        this.searchStart = startValue;
        this.optimizationGoal = goal;
        this.function = f;

        // Reset.
        functionValue = Double.NaN;
        evaluations = 0;
        resetIterationsCounter();

        // Perform computation.
        result = doOptimize();
        resultComputed = true;

        return result;
    }

    /**
     * Set the value at the optimum.
     *
     * @param functionValue Value of the objective function at the optimum.
     */
    protected void setFunctionValue(double functionValue) {
        this.functionValue = functionValue;
    }

    /** {@inheritDoc} */
    public double optimize(UnivariateRealFunction f, GoalType goal,
                           double min, double max)
        throws MaxIterationsExceededException, FunctionEvaluationException {
        return optimize(f, goal, min, max, min + 0.5 * (max - min));
    }

    /**
     * Method for implementing actual optimization algorithms in derived
     * classes.
     *
     * From version 3.0 onwards, this method will be abstract - i.e.
     * concrete implementations will have to implement it.  If this method
     * is not implemented, subclasses must override
     * {@link #optimize(UnivariateRealFunction, GoalType, double, double)}.
     *
     * @return the optimum.
     * @throws MaxIterationsExceededException if the maximum iteration count
     * is exceeded.
     * @throws FunctionEvaluationException if an error occurs evaluating
     * the function.
     */
    protected double doOptimize()
        throws MaxIterationsExceededException, FunctionEvaluationException {
        throw new MathUnsupportedOperationException(LocalizedFormats.NOT_OVERRIDEN);
    }
}