Home | History | Annotate | Download | only in optimization 
      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
     25  * {@link DifferentiableMultivariateRealFunction scalar differentiable objective
     26  * functions}.
     27  * Optimization algorithms find the input point set that either {@link GoalType
     28  * maximize or minimize} an objective function.
     29  *
     30  * @see MultivariateRealOptimizer
     31  * @see DifferentiableMultivariateVectorialOptimizer
     32  * @version $Revision: 1065484 $ $Date: 2011-01-31 06:45:14 +0100 (lun. 31 janv. 2011) $
     33  * @since 2.0
     34  */
     35 public interface DifferentiableMultivariateRealOptimizer {
     36 
     37     /** Set the maximal number of iterations of the algorithm.
     38      * @param maxIterations maximal number of function calls
     39      */
     40     void setMaxIterations(int maxIterations);
     41 
     42     /** Get the maximal number of iterations of the algorithm.
     43      * @return maximal number of iterations
     44      */
     45     int getMaxIterations();
     46 
     47     /** Get the number of iterations realized by the algorithm.
     48      * <p>
     49      * The number of evaluations corresponds to the last call to the
     50      * {@code optimize} method. It is 0 if the method has not been called yet.
     51      * </p>
     52      * @return number of iterations
     53      */
     54     int getIterations();
     55 
     56     /** Set the maximal number of functions evaluations.
     57      * @param maxEvaluations maximal number of function evaluations
     58      */
     59     void setMaxEvaluations(int maxEvaluations);
     60 
     61     /** Get the maximal number of functions evaluations.
     62      * @return maximal number of functions evaluations
     63      */
     64     int getMaxEvaluations();
     65 
     66     /** Get the number of evaluations of the objective function.
     67      * <p>
     68      * The number of evaluations corresponds to the last call to the
     69      * {@link #optimize(DifferentiableMultivariateRealFunction, GoalType, double[]) optimize}
     70      * method. It is 0 if the method has not been called yet.
     71      * </p>
     72      * @return number of evaluations of the objective function
     73      */
     74     int getEvaluations();
     75 
     76     /** Get the number of evaluations of the objective function gradient.
     77      * <p>
     78      * The number of evaluations corresponds to the last call to the
     79      * {@link #optimize(DifferentiableMultivariateRealFunction, GoalType, double[]) optimize}
     80      * method. It is 0 if the method has not been called yet.
     81      * </p>
     82      * @return number of evaluations of the objective function gradient
     83      */
     84     int getGradientEvaluations();
     85 
     86     /** Set the convergence checker.
     87      * @param checker object to use to check for convergence
     88      */
     89     void setConvergenceChecker(RealConvergenceChecker checker);
     90 
     91     /** Get the convergence checker.
     92      * @return object used to check for convergence
     93      */
     94     RealConvergenceChecker getConvergenceChecker();
     95 
     96     /** Optimizes an objective function.
     97      * @param f objective function
     98      * @param goalType type of optimization goal: either {@link GoalType#MAXIMIZE}
     99      * or {@link GoalType#MINIMIZE}
    100      * @param startPoint the start point for optimization
    101      * @return the point/value pair giving the optimal value for objective function
    102      * @exception FunctionEvaluationException if the objective function throws one during
    103      * the search
    104      * @exception OptimizationException if the algorithm failed to converge
    105      * @exception IllegalArgumentException if the start point dimension is wrong
    106      */
    107     RealPointValuePair optimize(DifferentiableMultivariateRealFunction f,
    108                                   GoalType goalType,
    109                                   double[] startPoint)
    110         throws FunctionEvaluationException, OptimizationException, IllegalArgumentException;
    111 
    112 }
    113