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.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 }