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: 811685 $ $Date: 2009-09-05 13:36:48 -0400 (Sat, 05 Sep 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 }