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 }