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: 811685 $ $Date: 2009-09-05 13:36:48 -0400 (Sat, 05 Sep 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 }