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 */ 17package org.apache.commons.math.optimization; 18 19import org.apache.commons.math.ConvergenceException; 20import org.apache.commons.math.FunctionEvaluationException; 21import org.apache.commons.math.ConvergingAlgorithm; 22import org.apache.commons.math.analysis.UnivariateRealFunction; 23 24 25/** 26 * Interface for (univariate real) optimization algorithms. 27 * 28 * @version $Revision: 1073658 $ $Date: 2011-02-23 10:45:42 +0100 (mer. 23 févr. 2011) $ 29 * @since 2.0 30 */ 31public 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 the 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 the 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 function. 67 * @throws IllegalArgumentException if min > max or the endpoints do not 68 * satisfy the requirements specified by the optimizer. 69 */ 70 double optimize(UnivariateRealFunction f, GoalType goalType, 71 double min, double max) 72 throws ConvergenceException, FunctionEvaluationException; 73 74 /** 75 * Find an optimum in the given interval, start at startValue. 76 * <p> 77 * An optimizer may require that the interval brackets a single optimum. 78 * </p> 79 * @param f the function to optimize. 80 * @param goalType type of optimization goal: either {@link GoalType#MAXIMIZE} 81 * or {@link GoalType#MINIMIZE}. 82 * @param min the lower bound for the interval. 83 * @param max the upper bound for the interval. 84 * @param startValue the start value to use. 85 * @return a value where the function is optimum. 86 * @throws ConvergenceException if the maximum iteration count is exceeded 87 * or the optimizer detects convergence problems otherwise. 88 * @throws FunctionEvaluationException if an error occurs evaluating the function. 89 * @throws IllegalArgumentException if min > max or the arguments do not 90 * satisfy the requirements specified by the optimizer. 91 * @throws IllegalStateException if there are no data. 92 */ 93 double optimize(UnivariateRealFunction f, GoalType goalType, 94 double min, double max, double startValue) 95 throws ConvergenceException, FunctionEvaluationException; 96 97 /** 98 * Get the result of the last run of the optimizer. 99 * 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} 117