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.linear;
19  
20  import java.util.Collection;
21  
22  import org.apache.commons.math.optimization.GoalType;
23  import org.apache.commons.math.optimization.OptimizationException;
24  import org.apache.commons.math.optimization.RealPointValuePair;
25  
26  /** 
27   * This interface represents an optimization algorithm for linear problems.
28   * <p>Optimization algorithms find the input point set that either {@link GoalType
29   * maximize or minimize} an objective function. In the linear case the form of
30   * the function is restricted to
31   * <pre>
32   * c<sub>1</sub>x<sub>1</sub> + ... c<sub>n</sub>x<sub>n</sub> = v
33   * </pre>
34   * and there may be linear constraints too, of one of the forms:
35   * <ul>
36   *   <li>c<sub>1</sub>x<sub>1</sub> + ... c<sub>n</sub>x<sub>n</sub> = v</li>
37   *   <li>c<sub>1</sub>x<sub>1</sub> + ... c<sub>n</sub>x<sub>n</sub> &lt;= v</li>
38   *   <li>c<sub>1</sub>x<sub>1</sub> + ... c<sub>n</sub>x<sub>n</sub> >= v</li>
39   *   <li>l<sub>1</sub>x<sub>1</sub> + ... l<sub>n</sub>x<sub>n</sub> + l<sub>cst</sub> =
40   *       r<sub>1</sub>x<sub>1</sub> + ... r<sub>n</sub>x<sub>n</sub> + r<sub>cst</sub></li>
41   *   <li>l<sub>1</sub>x<sub>1</sub> + ... l<sub>n</sub>x<sub>n</sub> + l<sub>cst</sub> &lt;=
42   *       r<sub>1</sub>x<sub>1</sub> + ... r<sub>n</sub>x<sub>n</sub> + r<sub>cst</sub></li>
43   *   <li>l<sub>1</sub>x<sub>1</sub> + ... l<sub>n</sub>x<sub>n</sub> + l<sub>cst</sub> >=
44   *       r<sub>1</sub>x<sub>1</sub> + ... r<sub>n</sub>x<sub>n</sub> + r<sub>cst</sub></li>
45   * </ul>
46   * where the c<sub>i</sub>, l<sub>i</sub> or r<sub>i</sub> are the coefficients of
47   * the constraints, the x<sub>i</sub> are the coordinates of the current point and
48   * v is the value of the constraint.
49   * </p>
50   * @version $Revision: 799857 $ $Date: 2009-08-01 09:07:12 -0400 (Sat, 01 Aug 2009) $
51   * @since 2.0
52   */
53  public interface LinearOptimizer {
54  
55      /** Set the maximal number of iterations of the algorithm.
56       * @param maxIterations maximal number of function calls
57       */
58      void setMaxIterations(int maxIterations);
59  
60      /** Get the maximal number of iterations of the algorithm.
61       * @return maximal number of iterations
62       */
63      int getMaxIterations();
64  
65      /** Get the number of iterations realized by the algorithm.
66       * <p>
67       * The number of evaluations corresponds to the last call to the
68       * {@link #optimize(LinearObjectiveFunction, Collection, GoalType, boolean) optimize}
69       * method. It is 0 if the method has not been called yet.
70       * </p>
71       * @return number of iterations
72       */
73      int getIterations();
74  
75      /** Optimizes an objective function.
76       * @param f linear objective function
77       * @param constraints linear constraints
78       * @param goalType type of optimization goal: either {@link GoalType#MAXIMIZE}
79       * or {@link GoalType#MINIMIZE}
80       * @param restrictToNonNegative whether to restrict the variables to non-negative values
81       * @return point/value pair giving the optimal value for objective function
82       * @exception OptimizationException if no solution fulfilling the constraints
83       * can be found in the allowed number of iterations
84       */
85     RealPointValuePair optimize(LinearObjectiveFunction f, Collection<LinearConstraint> constraints,
86                                 GoalType goalType, boolean restrictToNonNegative)
87          throws OptimizationException;
88  
89  }