View Javadoc

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.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: 799857 $ $Date: 2009-08-01 09:07:12 -0400 (Sat, 01 Aug 2009) $
31   * @since 2.0
32   */
33  public 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 }