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 018 package org.apache.commons.math.optimization; 019 020 import org.apache.commons.math.FunctionEvaluationException; 021 import org.apache.commons.math.analysis.DifferentiableMultivariateRealFunction; 022 023 /** 024 * This interface represents an optimization algorithm for {@link DifferentiableMultivariateRealFunction 025 * scalar differentiable objective functions}. 026 * <p>Optimization algorithms find the input point set that either {@link GoalType 027 * maximize or minimize} an objective function.</p> 028 * @see MultivariateRealOptimizer 029 * @see DifferentiableMultivariateVectorialOptimizer 030 * @version $Revision: 799857 $ $Date: 2009-08-01 09:07:12 -0400 (Sat, 01 Aug 2009) $ 031 * @since 2.0 032 */ 033 public interface DifferentiableMultivariateRealOptimizer { 034 035 /** Set the maximal number of iterations of the algorithm. 036 * @param maxIterations maximal number of function calls 037 */ 038 void setMaxIterations(int maxIterations); 039 040 /** Get the maximal number of iterations of the algorithm. 041 * @return maximal number of iterations 042 */ 043 int getMaxIterations(); 044 045 /** Get the number of iterations realized by the algorithm. 046 * <p> 047 * The number of evaluations corresponds to the last call to the 048 * {@link #optimize(DifferentiableMultivariateRealFunction, GoalType, double[]) optimize} 049 * method. It is 0 if the method has not been called yet. 050 * </p> 051 * @return number of iterations 052 */ 053 int getIterations(); 054 055 /** Set the maximal number of functions evaluations. 056 * @param maxEvaluations maximal number of function evaluations 057 */ 058 void setMaxEvaluations(int maxEvaluations); 059 060 /** Get the maximal number of functions evaluations. 061 * @return maximal number of functions evaluations 062 */ 063 int getMaxEvaluations(); 064 065 /** Get the number of evaluations of the objective function. 066 * <p> 067 * The number of evaluations corresponds to the last call to the 068 * {@link #optimize(DifferentiableMultivariateRealFunction, GoalType, double[]) optimize} 069 * method. It is 0 if the method has not been called yet. 070 * </p> 071 * @return number of evaluations of the objective function 072 */ 073 int getEvaluations(); 074 075 /** Get the number of evaluations of the objective function gradient. 076 * <p> 077 * The number of evaluations corresponds to the last call to the 078 * {@link #optimize(DifferentiableMultivariateRealFunction, GoalType, double[]) optimize} 079 * method. It is 0 if the method has not been called yet. 080 * </p> 081 * @return number of evaluations of the objective function gradient 082 */ 083 int getGradientEvaluations(); 084 085 /** Set the convergence checker. 086 * @param checker object to use to check for convergence 087 */ 088 void setConvergenceChecker(RealConvergenceChecker checker); 089 090 /** Get the convergence checker. 091 * @return object used to check for convergence 092 */ 093 RealConvergenceChecker getConvergenceChecker(); 094 095 /** Optimizes an objective function. 096 * @param f objective function 097 * @param goalType type of optimization goal: either {@link GoalType#MAXIMIZE} 098 * or {@link GoalType#MINIMIZE} 099 * @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 }