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 */
17package org.apache.commons.math.optimization;
18
19import org.apache.commons.math.ConvergenceException;
20import org.apache.commons.math.FunctionEvaluationException;
21import org.apache.commons.math.ConvergingAlgorithm;
22import org.apache.commons.math.analysis.UnivariateRealFunction;
23
24
25/**
26 * Interface for (univariate real) optimization algorithms.
27 *
28 * @version $Revision: 1073658 $ $Date: 2011-02-23 10:45:42 +0100 (mer. 23 févr. 2011) $
29 * @since 2.0
30 */
31public interface UnivariateRealOptimizer extends ConvergingAlgorithm {
32
33    /** Set the maximal number of functions evaluations.
34     * @param maxEvaluations maximal number of function evaluations
35     */
36    void setMaxEvaluations(int maxEvaluations);
37
38    /** Get the maximal number of functions evaluations.
39     * @return the maximal number of functions evaluations.
40     */
41    int getMaxEvaluations();
42
43    /** Get the number of evaluations of the objective function.
44     * <p>
45     * The number of evaluations corresponds to the last call to the
46     * {@link #optimize(UnivariateRealFunction, GoalType, double, double) optimize}
47     * method. It is 0 if the method has not been called yet.
48     * </p>
49     * @return the number of evaluations of the objective function.
50     */
51    int getEvaluations();
52
53    /**
54     * Find an optimum in the given interval.
55     * <p>
56     * An optimizer may require that the interval brackets a single optimum.
57     * </p>
58     * @param f the function to optimize.
59     * @param goalType type of optimization goal: either {@link GoalType#MAXIMIZE}
60     * or {@link GoalType#MINIMIZE}.
61     * @param min the lower bound for the interval.
62     * @param max the upper bound for the interval.
63     * @return a value where the function is optimum.
64     * @throws ConvergenceException if the maximum iteration count is exceeded
65     * or the optimizer detects convergence problems otherwise.
66     * @throws FunctionEvaluationException if an error occurs evaluating the function.
67     * @throws IllegalArgumentException if min > max or the endpoints do not
68     * satisfy the requirements specified by the optimizer.
69     */
70    double optimize(UnivariateRealFunction f, GoalType goalType,
71                    double min, double max)
72        throws ConvergenceException, FunctionEvaluationException;
73
74    /**
75     * Find an optimum in the given interval, start at startValue.
76     * <p>
77     * An optimizer may require that the interval brackets a single optimum.
78     * </p>
79     * @param f the function to optimize.
80     * @param goalType type of optimization goal: either {@link GoalType#MAXIMIZE}
81     * or {@link GoalType#MINIMIZE}.
82     * @param min the lower bound for the interval.
83     * @param max the upper bound for the interval.
84     * @param startValue the start value to use.
85     * @return a value where the function is optimum.
86     * @throws ConvergenceException if the maximum iteration count is exceeded
87     * or the optimizer detects convergence problems otherwise.
88     * @throws FunctionEvaluationException if an error occurs evaluating the function.
89     * @throws IllegalArgumentException if min > max or the arguments do not
90     * satisfy the requirements specified by the optimizer.
91     * @throws IllegalStateException if there are no data.
92     */
93    double optimize(UnivariateRealFunction f, GoalType goalType,
94                    double min, double max, double startValue)
95        throws ConvergenceException, FunctionEvaluationException;
96
97    /**
98     * Get the result of the last run of the optimizer.
99     *
100     * @return the optimum.
101     * @throws IllegalStateException if there is no result available, either
102     * because no result was yet computed or the last attempt failed.
103     */
104    double getResult();
105
106    /**
107     * Get the result of the last run of the optimizer.
108     *
109     * @return the value of the function at the optimum.
110     * @throws FunctionEvaluationException if an error occurs evaluating the function.
111     * @throws IllegalStateException if there is no result available, either
112     * because no result was yet computed or the last attempt failed.
113     */
114    double getFunctionValue() throws FunctionEvaluationException;
115
116}
117