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 }