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
18package org.apache.commons.math.optimization;
19
20import org.apache.commons.math.FunctionEvaluationException;
21import org.apache.commons.math.analysis.MultivariateRealFunction;
22
23/**
24 * This interface represents an optimization algorithm for {@link MultivariateRealFunction
25 * scalar 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 DifferentiableMultivariateRealOptimizer
29 * @see DifferentiableMultivariateVectorialOptimizer
30 * @version $Revision: 1065481 $ $Date: 2011-01-31 06:31:41 +0100 (lun. 31 janv. 2011) $
31 * @since 2.0
32 */
33public interface MultivariateRealOptimizer {
34
35    /** Set the maximal number of iterations of the algorithm.
36     * @param maxIterations maximal number of algorithm iterations
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    /** Set the maximal number of functions evaluations.
46     * @param maxEvaluations maximal number of function evaluations
47     */
48    void setMaxEvaluations(int maxEvaluations);
49
50    /** Get the maximal number of functions evaluations.
51     * @return maximal number of functions evaluations
52     */
53    int getMaxEvaluations();
54
55    /** Get the number of iterations realized by the algorithm.
56     * <p>
57     * The number of evaluations corresponds to the last call to the
58     * {@link #optimize(MultivariateRealFunction, GoalType, double[]) optimize}
59     * method. It is 0 if the method has not been called yet.
60     * </p>
61     * @return number of iterations
62     */
63    int getIterations();
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(MultivariateRealFunction, 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    /** Set the convergence checker.
76     * @param checker object to use to check for convergence
77     */
78    void setConvergenceChecker(RealConvergenceChecker checker);
79
80    /** Get the convergence checker.
81     * @return object used to check for convergence
82     */
83    RealConvergenceChecker getConvergenceChecker();
84
85    /** Optimizes an objective function.
86     * @param f objective function
87     * @param goalType type of optimization goal: either {@link GoalType#MAXIMIZE}
88     * or {@link GoalType#MINIMIZE}
89     * @param startPoint the start point for optimization
90     * @return the point/value pair giving the optimal value for objective function
91     * @exception FunctionEvaluationException if the objective function throws one during
92     * the search
93     * @exception OptimizationException if the algorithm failed to converge
94     * @exception IllegalArgumentException if the start point dimension is wrong
95     */
96    RealPointValuePair optimize(MultivariateRealFunction f,
97                                  GoalType goalType,
98                                  double[] startPoint)
99        throws FunctionEvaluationException, OptimizationException, IllegalArgumentException;
100
101}
102