001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.commons.math.optimization;
018    
019    import org.apache.commons.math.ConvergenceException;
020    import org.apache.commons.math.ConvergingAlgorithm;
021    import org.apache.commons.math.FunctionEvaluationException;
022    import org.apache.commons.math.analysis.UnivariateRealFunction;
023    
024    
025    /**
026     * Interface for (univariate real) optimization algorithms.
027     *  
028     * @version $Revision: 799857 $ $Date: 2009-08-01 09:07:12 -0400 (Sat, 01 Aug 2009) $
029     * @since 2.0
030     */
031    public interface UnivariateRealOptimizer extends ConvergingAlgorithm {
032    
033        /** Set the maximal number of functions evaluations.
034         * @param maxEvaluations maximal number of function evaluations
035         */
036        void setMaxEvaluations(int maxEvaluations);
037    
038        /** Get the maximal number of functions evaluations.
039         * @return maximal number of functions evaluations
040         */
041        int getMaxEvaluations();
042    
043        /** Get the number of evaluations of the objective function.
044         * <p>
045         * The number of evaluations corresponds to the last call to the
046         * {@link #optimize(UnivariateRealFunction, GoalType, double, double) optimize}
047         * method. It is 0 if the method has not been called yet.
048         * </p>
049         * @return number of evaluations of the objective function
050         */
051        int getEvaluations();
052    
053        /**
054         * Find an optimum in the given interval.
055         * <p>
056         * An optimizer may require that the interval brackets a single optimum.
057         * </p>
058         * @param f the function to optimize.
059         * @param goalType type of optimization goal: either {@link GoalType#MAXIMIZE}
060         * or {@link GoalType#MINIMIZE}
061         * @param min the lower bound for the interval.
062         * @param max the upper bound for the interval.
063         * @return a value where the function is optimum
064         * @throws ConvergenceException if the maximum iteration count is exceeded
065         * or the optimizer detects convergence problems otherwise.
066         * @throws FunctionEvaluationException if an error occurs evaluating the
067         * function
068         * @throws IllegalArgumentException if min > max or the endpoints do not
069         * satisfy the requirements specified by the optimizer
070         */
071        double optimize(UnivariateRealFunction f, GoalType goalType,
072                        double min, double max)
073            throws ConvergenceException, FunctionEvaluationException;
074    
075        /**
076         * Find an optimum in the given interval, start at startValue.
077         * <p>
078         * An optimizer may require that the interval brackets a single optimum.
079         * </p>
080         * @param f the function to optimize.
081         * @param goalType type of optimization goal: either {@link GoalType#MAXIMIZE}
082         * or {@link GoalType#MINIMIZE}
083         * @param min the lower bound for the interval.
084         * @param max the upper bound for the interval.
085         * @param startValue the start value to use
086         * @return a value where the function is optimum
087         * @throws ConvergenceException if the maximum iteration count is exceeded
088         * or the optimizer detects convergence problems otherwise.
089         * @throws FunctionEvaluationException if an error occurs evaluating the
090         * function
091         * @throws IllegalArgumentException if min > max or the arguments do not
092         * satisfy the requirements specified by the optimizer
093         */
094        double optimize(UnivariateRealFunction f, GoalType goalType,
095                        double min, double max, double startValue)
096            throws ConvergenceException, FunctionEvaluationException;
097    
098        /**
099         * Get the result of the last run of the optimizer.
100         * 
101         * @return the last result.
102         * @throws IllegalStateException if there is no result available, either
103         * because no result was yet computed or the last attempt failed.
104         */
105        double getResult();
106    
107        /**
108         * Get the result of the last run of the optimizer.
109         * 
110         * @return the value of the function at the last result.
111         * @throws IllegalStateException if there is no result available, either
112         * because no result was yet computed or the last attempt failed.
113         */
114        double getFunctionValue();
115    
116    }