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.DifferentiableMultivariateVectorialFunction;
22  
23  /** 
24   * This interface represents an optimization algorithm for {@link DifferentiableMultivariateVectorialFunction
25   * vectorial 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 DifferentiableMultivariateRealOptimizer
30   * @version $Revision: 799857 $ $Date: 2009-08-01 09:07:12 -0400 (Sat, 01 Aug 2009) $
31   * @since 2.0
32   */
33  public interface DifferentiableMultivariateVectorialOptimizer {
34  
35      /** Set the maximal number of iterations of the algorithm.
36       * @param maxIterations maximal number of function calls
37       * .
38       */
39      void setMaxIterations(int maxIterations);
40  
41      /** Get the maximal number of iterations of the algorithm.
42        * @return maximal number of iterations
43       */
44      int getMaxIterations();
45  
46      /** Get the number of iterations realized by the algorithm.
47       * @return number of iterations
48      */
49     int getIterations();
50  
51     /** Set the maximal number of functions evaluations.
52      * @param maxEvaluations maximal number of function evaluations
53      */
54     void setMaxEvaluations(int maxEvaluations);
55  
56     /** Get the maximal number of functions evaluations.
57      * @return maximal number of functions evaluations
58      */
59     int getMaxEvaluations();
60  
61      /** Get the number of evaluations of the objective function.
62       * <p>
63       * The number of evaluation correspond to the last call to the
64       * {@link #optimize(DifferentiableMultivariateVectorialFunction,
65       * double[], double[], double[]) optimize} method. It is 0 if
66       * the method has not been called yet.
67       * </p>
68       * @return number of evaluations of the objective function
69       */
70      int getEvaluations();
71  
72      /** Get the number of evaluations of the objective function jacobian .
73       * <p>
74       * The number of evaluation correspond to the last call to the
75       * {@link #optimize(DifferentiableMultivariateVectorialFunction,
76       * double[], double[], double[]) optimize} method. It is 0 if
77       * the method has not been called yet.
78       * </p>
79       * @return number of evaluations of the objective function jacobian
80       */
81      int getJacobianEvaluations();
82  
83      /** Set the convergence checker.
84       * @param checker object to use to check for convergence
85       */
86      void setConvergenceChecker(VectorialConvergenceChecker checker);
87  
88      /** Get the convergence checker.
89       * @return object used to check for convergence
90       */
91      VectorialConvergenceChecker getConvergenceChecker();
92  
93      /** Optimizes an objective function.
94       * <p>
95       * Optimization is considered to be a weighted least-squares minimization.
96       * The cost function to be minimized is
97       * &sum;weight<sub>i</sub>(objective<sub>i</sub>-target<sub>i</sub>)<sup>2</sup>
98       * </p>
99       * @param f objective function
100      * @param target target value for the objective functions at optimum
101      * @param weights weight for the least squares cost computation
102      * @param startPoint the start point for optimization
103      * @return the point/value pair giving the optimal value for objective function
104      * @exception FunctionEvaluationException if the objective function throws one during
105      * the search
106      * @exception OptimizationException if the algorithm failed to converge
107      * @exception IllegalArgumentException if the start point dimension is wrong
108      */
109     VectorialPointValuePair optimize(DifferentiableMultivariateVectorialFunction f,
110                                      double[] target, double[] weights,
111                                      double[] startPoint)
112         throws FunctionEvaluationException, OptimizationException, IllegalArgumentException;
113 
114 }