001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 package org.apache.commons.math.optimization;
019
020 import org.apache.commons.math.analysis.DifferentiableMultivariateVectorialFunction;
021 import org.apache.commons.math.FunctionEvaluationException;
022
023 /**
024 * This interface represents an optimization algorithm for {@link DifferentiableMultivariateVectorialFunction
025 * vectorial differentiable objective functions}.
026 * <p>Optimization algorithms find the input point set that either {@link GoalType
027 * maximize or minimize} an objective function.</p>
028 * @see MultivariateRealOptimizer
029 * @see DifferentiableMultivariateRealOptimizer
030 * @version $Revision: 1073158 $ $Date: 2011-02-21 22:46:52 +0100 (lun. 21 f??vr. 2011) $
031 * @since 2.0
032 */
033 public interface DifferentiableMultivariateVectorialOptimizer {
034
035 /** Set the maximal number of iterations of the algorithm.
036 * @param maxIterations maximal number of function calls
037 * .
038 */
039 void setMaxIterations(int maxIterations);
040
041 /** Get the maximal number of iterations of the algorithm.
042 * @return maximal number of iterations
043 */
044 int getMaxIterations();
045
046 /** Get the number of iterations realized by the algorithm.
047 * @return number of iterations
048 */
049 int getIterations();
050
051 /** Set the maximal number of functions evaluations.
052 * @param maxEvaluations maximal number of function evaluations
053 */
054 void setMaxEvaluations(int maxEvaluations);
055
056 /** Get the maximal number of functions evaluations.
057 * @return maximal number of functions evaluations
058 */
059 int getMaxEvaluations();
060
061 /** Get the number of evaluations of the objective function.
062 * <p>
063 * The number of evaluation correspond to the last call to the
064 * {@link #optimize(DifferentiableMultivariateVectorialFunction,
065 * double[], double[], double[]) optimize} method. It is 0 if
066 * the method has not been called yet.
067 * </p>
068 * @return number of evaluations of the objective function
069 */
070 int getEvaluations();
071
072 /** Get the number of evaluations of the objective function jacobian .
073 * <p>
074 * The number of evaluation correspond to the last call to the
075 * {@link #optimize(DifferentiableMultivariateVectorialFunction,
076 * double[], double[], double[]) optimize} method. It is 0 if
077 * the method has not been called yet.
078 * </p>
079 * @return number of evaluations of the objective function jacobian
080 */
081 int getJacobianEvaluations();
082
083 /** Set the convergence checker.
084 * @param checker object to use to check for convergence
085 */
086 void setConvergenceChecker(VectorialConvergenceChecker checker);
087
088 /** Get the convergence checker.
089 * @return object used to check for convergence
090 */
091 VectorialConvergenceChecker getConvergenceChecker();
092
093 /** Optimizes an objective function.
094 * <p>
095 * Optimization is considered to be a weighted least-squares minimization.
096 * The cost function to be minimized is
097 * ∑weight<sub>i</sub>(objective<sub>i</sub>-target<sub>i</sub>)<sup>2</sup>
098 * </p>
099 * @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 }