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.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 */
35public interface DifferentiableMultivariateRealOptimizer {
36
37    /** Set the maximal number of iterations of the algorithm.
38     * @param maxIterations maximal number of function calls
39     */
40    void setMaxIterations(int maxIterations);
41
42    /** Get the maximal number of iterations of the algorithm.
43     * @return maximal number of iterations
44     */
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     */
54    int getIterations();
55
56    /** Set the maximal number of functions evaluations.
57     * @param maxEvaluations maximal number of function evaluations
58     */
59    void setMaxEvaluations(int maxEvaluations);
60
61    /** Get the maximal number of functions evaluations.
62     * @return maximal number of functions evaluations
63     */
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     */
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     */
84    int getGradientEvaluations();
85
86    /** Set the convergence checker.
87     * @param checker object to use to check for convergence
88     */
89    void setConvergenceChecker(RealConvergenceChecker checker);
90
91    /** Get the convergence checker.
92     * @return object used to check for convergence
93     */
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     */
107    RealPointValuePair optimize(DifferentiableMultivariateRealFunction f,
108                                  GoalType goalType,
109                                  double[] startPoint)
110        throws FunctionEvaluationException, OptimizationException, IllegalArgumentException;
111
112}
113