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 18 package org.apache.commons.math.optimization; 19 20 import org.apache.commons.math.FunctionEvaluationException; 21 import org.apache.commons.math.analysis.DifferentiableMultivariateRealFunction; 22 23 /** 24 * This interface represents an optimization algorithm for {@link DifferentiableMultivariateRealFunction 25 * scalar differentiable objective functions}. 26 * <p>Optimization algorithms find the input point set that either {@link GoalType 27 * maximize or minimize} an objective function.</p> 28 * @see MultivariateRealOptimizer 29 * @see DifferentiableMultivariateVectorialOptimizer 30 * @version $Revision: 799857 $ $Date: 2009-08-01 09:07:12 -0400 (Sat, 01 Aug 2009) $ 31 * @since 2.0 32 */ 33 public interface DifferentiableMultivariateRealOptimizer { 34 35 /** Set the maximal number of iterations of the algorithm. 36 * @param maxIterations maximal number of function calls 37 */ 38 void setMaxIterations(int maxIterations); 39 40 /** Get the maximal number of iterations of the algorithm. 41 * @return maximal number of iterations 42 */ 43 int getMaxIterations(); 44 45 /** Get the number of iterations realized by the algorithm. 46 * <p> 47 * The number of evaluations corresponds to the last call to the 48 * {@link #optimize(DifferentiableMultivariateRealFunction, GoalType, double[]) optimize} 49 * method. It is 0 if the method has not been called yet. 50 * </p> 51 * @return number of iterations 52 */ 53 int getIterations(); 54 55 /** Set the maximal number of functions evaluations. 56 * @param maxEvaluations maximal number of function evaluations 57 */ 58 void setMaxEvaluations(int maxEvaluations); 59 60 /** Get the maximal number of functions evaluations. 61 * @return maximal number of functions evaluations 62 */ 63 int getMaxEvaluations(); 64 65 /** Get the number of evaluations of the objective function. 66 * <p> 67 * The number of evaluations corresponds to the last call to the 68 * {@link #optimize(DifferentiableMultivariateRealFunction, GoalType, double[]) optimize} 69 * method. It is 0 if the method has not been called yet. 70 * </p> 71 * @return number of evaluations of the objective function 72 */ 73 int getEvaluations(); 74 75 /** Get the number of evaluations of the objective function gradient. 76 * <p> 77 * The number of evaluations corresponds to the last call to the 78 * {@link #optimize(DifferentiableMultivariateRealFunction, GoalType, double[]) optimize} 79 * method. It is 0 if the method has not been called yet. 80 * </p> 81 * @return number of evaluations of the objective function gradient 82 */ 83 int getGradientEvaluations(); 84 85 /** Set the convergence checker. 86 * @param checker object to use to check for convergence 87 */ 88 void setConvergenceChecker(RealConvergenceChecker checker); 89 90 /** Get the convergence checker. 91 * @return object used to check for convergence 92 */ 93 RealConvergenceChecker getConvergenceChecker(); 94 95 /** Optimizes an objective function. 96 * @param f objective function 97 * @param goalType type of optimization goal: either {@link GoalType#MAXIMIZE} 98 * or {@link GoalType#MINIMIZE} 99 * @param startPoint the start point for optimization 100 * @return the point/value pair giving the optimal value for objective function 101 * @exception FunctionEvaluationException if the objective function throws one during 102 * the search 103 * @exception OptimizationException if the algorithm failed to converge 104 * @exception IllegalArgumentException if the start point dimension is wrong 105 */ 106 RealPointValuePair optimize(DifferentiableMultivariateRealFunction f, 107 GoalType goalType, 108 double[] startPoint) 109 throws FunctionEvaluationException, OptimizationException, IllegalArgumentException; 110 111 }