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  package org.apache.commons.math3.optim;
18  
19  import org.apache.commons.math3.exception.DimensionMismatchException;
20  import org.apache.commons.math3.exception.NumberIsTooSmallException;
21  import org.apache.commons.math3.exception.NumberIsTooLargeException;
22  
23  /**
24   * Base class for implementing optimizers for multivariate functions.
25   * It contains the boiler-plate code for initial guess and bounds
26   * specifications.
27   * <em>It is not a "user" class.</em>
28   *
29   * @param <PAIR> Type of the point/value pair returned by the optimization
30   * algorithm.
31   *
32   * @version $Id: BaseMultivariateOptimizer.java 1443444 2013-02-07 12:41:36Z erans $
33   * @since 3.1
34   */
35  public abstract class BaseMultivariateOptimizer<PAIR>
36      extends BaseOptimizer<PAIR> {
37      /** Initial guess. */
38      private double[] start;
39      /** Lower bounds. */
40      private double[] lowerBound;
41      /** Upper bounds. */
42      private double[] upperBound;
43  
44      /**
45       * @param checker Convergence checker.
46       */
47      protected BaseMultivariateOptimizer(ConvergenceChecker<PAIR> checker) {
48          super(checker);
49      }
50  
51      /**
52       * {@inheritDoc}
53       *
54       * @param optData Optimization data. In addition to those documented in
55       * {@link BaseOptimizer#parseOptimizationData(OptimizationData[]) BaseOptimizer},
56       * this method will register the following data:
57       * <ul>
58       *  <li>{@link InitialGuess}</li>
59       *  <li>{@link SimpleBounds}</li>
60       * </ul>
61       * @return {@inheritDoc}
62       */
63      @Override
64      public PAIR optimize(OptimizationData... optData) {
65          // Perform optimization.
66          return super.optimize(optData);
67      }
68  
69      /**
70       * Scans the list of (required and optional) optimization data that
71       * characterize the problem.
72       *
73       * @param optData Optimization data. The following data will be looked for:
74       * <ul>
75       *  <li>{@link InitialGuess}</li>
76       *  <li>{@link SimpleBounds}</li>
77       * </ul>
78       */
79      @Override
80      protected void parseOptimizationData(OptimizationData... optData) {
81          // Allow base class to register its own data.
82          super.parseOptimizationData(optData);
83  
84          // The existing values (as set by the previous call) are reused if
85          // not provided in the argument list.
86          for (OptimizationData data : optData) {
87              if (data instanceof InitialGuess) {
88                  start = ((InitialGuess) data).getInitialGuess();
89                  continue;
90              }
91              if (data instanceof SimpleBounds) {
92                  final SimpleBounds bounds = (SimpleBounds) data;
93                  lowerBound = bounds.getLower();
94                  upperBound = bounds.getUpper();
95                  continue;
96              }
97          }
98  
99          // Check input consistency.
100         checkParameters();
101     }
102 
103     /**
104      * Gets the initial guess.
105      *
106      * @return the initial guess, or {@code null} if not set.
107      */
108     public double[] getStartPoint() {
109         return start == null ? null : start.clone();
110     }
111     /**
112      * @return the lower bounds, or {@code null} if not set.
113      */
114     public double[] getLowerBound() {
115         return lowerBound == null ? null : lowerBound.clone();
116     }
117     /**
118      * @return the upper bounds, or {@code null} if not set.
119      */
120     public double[] getUpperBound() {
121         return upperBound == null ? null : upperBound.clone();
122     }
123 
124     /**
125      * Check parameters consistency.
126      */
127     private void checkParameters() {
128         if (start != null) {
129             final int dim = start.length;
130             if (lowerBound != null) {
131                 if (lowerBound.length != dim) {
132                     throw new DimensionMismatchException(lowerBound.length, dim);
133                 }
134                 for (int i = 0; i < dim; i++) {
135                     final double v = start[i];
136                     final double lo = lowerBound[i];
137                     if (v < lo) {
138                         throw new NumberIsTooSmallException(v, lo, true);
139                     }
140                 }
141             }
142             if (upperBound != null) {
143                 if (upperBound.length != dim) {
144                     throw new DimensionMismatchException(upperBound.length, dim);
145                 }
146                 for (int i = 0; i < dim; i++) {
147                     final double v = start[i];
148                     final double hi = upperBound[i];
149                     if (v > hi) {
150                         throw new NumberIsTooLargeException(v, hi, true);
151                     }
152                 }
153             }
154         }
155     }
156 }