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 * ∑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 }