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.FunctionEvaluationException;
021 import org.apache.commons.math.ConvergingAlgorithm;
022 import org.apache.commons.math.analysis.UnivariateRealFunction;
023
024
025 /**
026 * Interface for (univariate real) optimization algorithms.
027 *
028 * @version $Revision: 1073658 $ $Date: 2011-02-23 10:45:42 +0100 (mer. 23 f??vr. 2011) $
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 the 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 the 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 function.
067 * @throws IllegalArgumentException if min > max or the endpoints do not
068 * satisfy the requirements specified by the optimizer.
069 */
070 double optimize(UnivariateRealFunction f, GoalType goalType,
071 double min, double max)
072 throws ConvergenceException, FunctionEvaluationException;
073
074 /**
075 * Find an optimum in the given interval, start at startValue.
076 * <p>
077 * An optimizer may require that the interval brackets a single optimum.
078 * </p>
079 * @param f the function to optimize.
080 * @param goalType type of optimization goal: either {@link GoalType#MAXIMIZE}
081 * or {@link GoalType#MINIMIZE}.
082 * @param min the lower bound for the interval.
083 * @param max the upper bound for the interval.
084 * @param startValue the start value to use.
085 * @return a value where the function is optimum.
086 * @throws ConvergenceException if the maximum iteration count is exceeded
087 * or the optimizer detects convergence problems otherwise.
088 * @throws FunctionEvaluationException if an error occurs evaluating the function.
089 * @throws IllegalArgumentException if min > max or the arguments do not
090 * satisfy the requirements specified by the optimizer.
091 * @throws IllegalStateException if there are no data.
092 */
093 double optimize(UnivariateRealFunction f, GoalType goalType,
094 double min, double max, double startValue)
095 throws ConvergenceException, FunctionEvaluationException;
096
097 /**
098 * Get the result of the last run of the optimizer.
099 *
100 * @return the optimum.
101 * @throws IllegalStateException if there is no result available, either
102 * because no result was yet computed or the last attempt failed.
103 */
104 double getResult();
105
106 /**
107 * Get the result of the last run of the optimizer.
108 *
109 * @return the value of the function at the optimum.
110 * @throws FunctionEvaluationException if an error occurs evaluating the function.
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() throws FunctionEvaluationException;
115
116 }