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
25  * {@link DifferentiableMultivariateRealFunction scalar differentiable objective
26  * functions}.
27  * Optimization algorithms find the input point set that either {@link GoalType
28  * maximize or minimize} an objective function.
29  *
30  * @see MultivariateRealOptimizer
31  * @see DifferentiableMultivariateVectorialOptimizer
32  * @version $Revision: 1065484 $ $Date: 2011-01-31 06:45:14 +0100 (lun. 31 janv. 2011) $
33  * @since 2.0
34  */
35 public interface DifferentiableMultivariateRealOptimizer {
36 
37     /** Set the maximal number of iterations of the algorithm.
38      * @param maxIterations maximal number of function calls
39      */
setMaxIterations(int maxIterations)40     void setMaxIterations(int maxIterations);
41 
42     /** Get the maximal number of iterations of the algorithm.
43      * @return maximal number of iterations
44      */
getMaxIterations()45     int getMaxIterations();
46 
47     /** Get the number of iterations realized by the algorithm.
48      * <p>
49      * The number of evaluations corresponds to the last call to the
50      * {@code optimize} method. It is 0 if the method has not been called yet.
51      * </p>
52      * @return number of iterations
53      */
getIterations()54     int getIterations();
55 
56     /** Set the maximal number of functions evaluations.
57      * @param maxEvaluations maximal number of function evaluations
58      */
setMaxEvaluations(int maxEvaluations)59     void setMaxEvaluations(int maxEvaluations);
60 
61     /** Get the maximal number of functions evaluations.
62      * @return maximal number of functions evaluations
63      */
getMaxEvaluations()64     int getMaxEvaluations();
65 
66     /** Get the number of evaluations of the objective function.
67      * <p>
68      * The number of evaluations corresponds to the last call to the
69      * {@link #optimize(DifferentiableMultivariateRealFunction, GoalType, double[]) optimize}
70      * method. It is 0 if the method has not been called yet.
71      * </p>
72      * @return number of evaluations of the objective function
73      */
getEvaluations()74     int getEvaluations();
75 
76     /** Get the number of evaluations of the objective function gradient.
77      * <p>
78      * The number of evaluations corresponds to the last call to the
79      * {@link #optimize(DifferentiableMultivariateRealFunction, GoalType, double[]) optimize}
80      * method. It is 0 if the method has not been called yet.
81      * </p>
82      * @return number of evaluations of the objective function gradient
83      */
getGradientEvaluations()84     int getGradientEvaluations();
85 
86     /** Set the convergence checker.
87      * @param checker object to use to check for convergence
88      */
setConvergenceChecker(RealConvergenceChecker checker)89     void setConvergenceChecker(RealConvergenceChecker checker);
90 
91     /** Get the convergence checker.
92      * @return object used to check for convergence
93      */
getConvergenceChecker()94     RealConvergenceChecker getConvergenceChecker();
95 
96     /** Optimizes an objective function.
97      * @param f objective function
98      * @param goalType type of optimization goal: either {@link GoalType#MAXIMIZE}
99      * 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      */
optimize(DifferentiableMultivariateRealFunction f, GoalType goalType, double[] startPoint)107     RealPointValuePair optimize(DifferentiableMultivariateRealFunction f,
108                                   GoalType goalType,
109                                   double[] startPoint)
110         throws FunctionEvaluationException, OptimizationException, IllegalArgumentException;
111 
112 }
113