1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package org.apache.commons.math.optimization; 18 19 import org.apache.commons.math.ConvergenceException; 20 import org.apache.commons.math.ConvergingAlgorithm; 21 import org.apache.commons.math.FunctionEvaluationException; 22 import org.apache.commons.math.analysis.UnivariateRealFunction; 23 24 25 /** 26 * Interface for (univariate real) optimization algorithms. 27 * 28 * @version $Revision: 799857 $ $Date: 2009-08-01 09:07:12 -0400 (Sat, 01 Aug 2009) $ 29 * @since 2.0 30 */ 31 public interface UnivariateRealOptimizer extends ConvergingAlgorithm { 32 33 /** Set the maximal number of functions evaluations. 34 * @param maxEvaluations maximal number of function evaluations 35 */ 36 void setMaxEvaluations(int maxEvaluations); 37 38 /** Get the maximal number of functions evaluations. 39 * @return maximal number of functions evaluations 40 */ 41 int getMaxEvaluations(); 42 43 /** Get the number of evaluations of the objective function. 44 * <p> 45 * The number of evaluations corresponds to the last call to the 46 * {@link #optimize(UnivariateRealFunction, GoalType, double, double) optimize} 47 * method. It is 0 if the method has not been called yet. 48 * </p> 49 * @return number of evaluations of the objective function 50 */ 51 int getEvaluations(); 52 53 /** 54 * Find an optimum in the given interval. 55 * <p> 56 * An optimizer may require that the interval brackets a single optimum. 57 * </p> 58 * @param f the function to optimize. 59 * @param goalType type of optimization goal: either {@link GoalType#MAXIMIZE} 60 * or {@link GoalType#MINIMIZE} 61 * @param min the lower bound for the interval. 62 * @param max the upper bound for the interval. 63 * @return a value where the function is optimum 64 * @throws ConvergenceException if the maximum iteration count is exceeded 65 * or the optimizer detects convergence problems otherwise. 66 * @throws FunctionEvaluationException if an error occurs evaluating the 67 * function 68 * @throws IllegalArgumentException if min > max or the endpoints do not 69 * satisfy the requirements specified by the optimizer 70 */ 71 double optimize(UnivariateRealFunction f, GoalType goalType, 72 double min, double max) 73 throws ConvergenceException, FunctionEvaluationException; 74 75 /** 76 * Find an optimum in the given interval, start at startValue. 77 * <p> 78 * An optimizer may require that the interval brackets a single optimum. 79 * </p> 80 * @param f the function to optimize. 81 * @param goalType type of optimization goal: either {@link GoalType#MAXIMIZE} 82 * or {@link GoalType#MINIMIZE} 83 * @param min the lower bound for the interval. 84 * @param max the upper bound for the interval. 85 * @param startValue the start value to use 86 * @return a value where the function is optimum 87 * @throws ConvergenceException if the maximum iteration count is exceeded 88 * or the optimizer detects convergence problems otherwise. 89 * @throws FunctionEvaluationException if an error occurs evaluating the 90 * function 91 * @throws IllegalArgumentException if min > max or the arguments do not 92 * satisfy the requirements specified by the optimizer 93 */ 94 double optimize(UnivariateRealFunction f, GoalType goalType, 95 double min, double max, double startValue) 96 throws ConvergenceException, FunctionEvaluationException; 97 98 /** 99 * 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 }