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
025 * {@link DifferentiableMultivariateRealFunction scalar differentiable objective
026 * functions}.
027 * Optimization algorithms find the input point set that either {@link GoalType
028 * maximize or minimize} an objective function.
029 *
030 * @see MultivariateRealOptimizer
031 * @see DifferentiableMultivariateVectorialOptimizer
032 * @version $Revision: 1065484 $ $Date: 2011-01-31 06:45:14 +0100 (lun. 31 janv. 2011) $
033 * @since 2.0
034 */
035 public interface DifferentiableMultivariateRealOptimizer {
036
037 /** Set the maximal number of iterations of the algorithm.
038 * @param maxIterations maximal number of function calls
039 */
040 void setMaxIterations(int maxIterations);
041
042 /** Get the maximal number of iterations of the algorithm.
043 * @return maximal number of iterations
044 */
045 int getMaxIterations();
046
047 /** Get the number of iterations realized by the algorithm.
048 * <p>
049 * The number of evaluations corresponds to the last call to the
050 * {@code optimize} method. It is 0 if the method has not been called yet.
051 * </p>
052 * @return number of iterations
053 */
054 int getIterations();
055
056 /** Set the maximal number of functions evaluations.
057 * @param maxEvaluations maximal number of function evaluations
058 */
059 void setMaxEvaluations(int maxEvaluations);
060
061 /** Get the maximal number of functions evaluations.
062 * @return maximal number of functions evaluations
063 */
064 int getMaxEvaluations();
065
066 /** Get the number of evaluations of the objective function.
067 * <p>
068 * The number of evaluations corresponds to the last call to the
069 * {@link #optimize(DifferentiableMultivariateRealFunction, GoalType, double[]) optimize}
070 * method. It is 0 if the method has not been called yet.
071 * </p>
072 * @return number of evaluations of the objective function
073 */
074 int getEvaluations();
075
076 /** Get the number of evaluations of the objective function gradient.
077 * <p>
078 * The number of evaluations corresponds to the last call to the
079 * {@link #optimize(DifferentiableMultivariateRealFunction, GoalType, double[]) optimize}
080 * method. It is 0 if the method has not been called yet.
081 * </p>
082 * @return number of evaluations of the objective function gradient
083 */
084 int getGradientEvaluations();
085
086 /** Set the convergence checker.
087 * @param checker object to use to check for convergence
088 */
089 void setConvergenceChecker(RealConvergenceChecker checker);
090
091 /** Get the convergence checker.
092 * @return object used to check for convergence
093 */
094 RealConvergenceChecker getConvergenceChecker();
095
096 /** Optimizes an objective function.
097 * @param f objective function
098 * @param goalType type of optimization goal: either {@link GoalType#MAXIMIZE}
099 * or {@link GoalType#MINIMIZE}
100 * @param startPoint the start point for optimization
101 * @return the point/value pair giving the optimal value for objective function
102 * @exception FunctionEvaluationException if the objective function throws one during
103 * the search
104 * @exception OptimizationException if the algorithm failed to converge
105 * @exception IllegalArgumentException if the start point dimension is wrong
106 */
107 RealPointValuePair optimize(DifferentiableMultivariateRealFunction f,
108 GoalType goalType,
109 double[] startPoint)
110 throws FunctionEvaluationException, OptimizationException, IllegalArgumentException;
111
112 }