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 package org.apache.commons.math3.optim.nonlinear.scalar;
018
019 import org.apache.commons.math3.analysis.MultivariateFunction;
020 import org.apache.commons.math3.analysis.UnivariateFunction;
021 import org.apache.commons.math3.analysis.function.Logit;
022 import org.apache.commons.math3.analysis.function.Sigmoid;
023 import org.apache.commons.math3.exception.DimensionMismatchException;
024 import org.apache.commons.math3.exception.NumberIsTooSmallException;
025 import org.apache.commons.math3.util.FastMath;
026 import org.apache.commons.math3.util.MathUtils;
027
028 /**
029 * <p>Adapter for mapping bounded {@link MultivariateFunction} to unbounded ones.</p>
030 *
031 * <p>
032 * This adapter can be used to wrap functions subject to simple bounds on
033 * parameters so they can be used by optimizers that do <em>not</em> directly
034 * support simple bounds.
035 * </p>
036 * <p>
037 * The principle is that the user function that will be wrapped will see its
038 * parameters bounded as required, i.e when its {@code value} method is called
039 * with argument array {@code point}, the elements array will fulfill requirement
040 * {@code lower[i] <= point[i] <= upper[i]} for all i. Some of the components
041 * may be unbounded or bounded only on one side if the corresponding bound is
042 * set to an infinite value. The optimizer will not manage the user function by
043 * itself, but it will handle this adapter and it is this adapter that will take
044 * care the bounds are fulfilled. The adapter {@link #value(double[])} method will
045 * be called by the optimizer with unbound parameters, and the adapter will map
046 * the unbounded value to the bounded range using appropriate functions like
047 * {@link Sigmoid} for double bounded elements for example.
048 * </p>
049 * <p>
050 * As the optimizer sees only unbounded parameters, it should be noted that the
051 * start point or simplex expected by the optimizer should be unbounded, so the
052 * user is responsible for converting his bounded point to unbounded by calling
053 * {@link #boundedToUnbounded(double[])} before providing them to the optimizer.
054 * For the same reason, the point returned by the {@link
055 * org.apache.commons.math3.optimization.BaseMultivariateOptimizer#optimize(int,
056 * MultivariateFunction, org.apache.commons.math3.optimization.GoalType, double[])}
057 * method is unbounded. So to convert this point to bounded, users must call
058 * {@link #unboundedToBounded(double[])} by themselves!</p>
059 * <p>
060 * This adapter is only a poor man solution to simple bounds optimization constraints
061 * that can be used with simple optimizers like
062 * {@link org.apache.commons.math3.optim.nonlinear.scalar.noderiv.SimplexOptimizer
063 * SimplexOptimizer}.
064 * A better solution is to use an optimizer that directly supports simple bounds like
065 * {@link org.apache.commons.math3.optim.nonlinear.scalar.noderiv.CMAESOptimizer
066 * CMAESOptimizer} or
067 * {@link org.apache.commons.math3.optim.nonlinear.scalar.noderiv.BOBYQAOptimizer
068 * BOBYQAOptimizer}.
069 * One caveat of this poor-man's solution is that behavior near the bounds may be
070 * numerically unstable as bounds are mapped from infinite values.
071 * Another caveat is that convergence values are evaluated by the optimizer with
072 * respect to unbounded variables, so there will be scales differences when
073 * converted to bounded variables.
074 * </p>
075 *
076 * @see MultivariateFunctionPenaltyAdapter
077 *
078 * @version $Id: MultivariateFunctionMappingAdapter.java 1416643 2012-12-03 19:37:14Z tn $
079 * @since 3.0
080 */
081 public class MultivariateFunctionMappingAdapter
082 implements MultivariateFunction {
083 /** Underlying bounded function. */
084 private final MultivariateFunction bounded;
085 /** Mapping functions. */
086 private final Mapper[] mappers;
087
088 /** Simple constructor.
089 * @param bounded bounded function
090 * @param lower lower bounds for each element of the input parameters array
091 * (some elements may be set to {@code Double.NEGATIVE_INFINITY} for
092 * unbounded values)
093 * @param upper upper bounds for each element of the input parameters array
094 * (some elements may be set to {@code Double.POSITIVE_INFINITY} for
095 * unbounded values)
096 * @exception DimensionMismatchException if lower and upper bounds are not
097 * consistent, either according to dimension or to values
098 */
099 public MultivariateFunctionMappingAdapter(final MultivariateFunction bounded,
100 final double[] lower, final double[] upper) {
101 // safety checks
102 MathUtils.checkNotNull(lower);
103 MathUtils.checkNotNull(upper);
104 if (lower.length != upper.length) {
105 throw new DimensionMismatchException(lower.length, upper.length);
106 }
107 for (int i = 0; i < lower.length; ++i) {
108 // note the following test is written in such a way it also fails for NaN
109 if (!(upper[i] >= lower[i])) {
110 throw new NumberIsTooSmallException(upper[i], lower[i], true);
111 }
112 }
113
114 this.bounded = bounded;
115 this.mappers = new Mapper[lower.length];
116 for (int i = 0; i < mappers.length; ++i) {
117 if (Double.isInfinite(lower[i])) {
118 if (Double.isInfinite(upper[i])) {
119 // element is unbounded, no transformation is needed
120 mappers[i] = new NoBoundsMapper();
121 } else {
122 // element is simple-bounded on the upper side
123 mappers[i] = new UpperBoundMapper(upper[i]);
124 }
125 } else {
126 if (Double.isInfinite(upper[i])) {
127 // element is simple-bounded on the lower side
128 mappers[i] = new LowerBoundMapper(lower[i]);
129 } else {
130 // element is double-bounded
131 mappers[i] = new LowerUpperBoundMapper(lower[i], upper[i]);
132 }
133 }
134 }
135 }
136
137 /**
138 * Maps an array from unbounded to bounded.
139 *
140 * @param point Unbounded values.
141 * @return the bounded values.
142 */
143 public double[] unboundedToBounded(double[] point) {
144 // Map unbounded input point to bounded point.
145 final double[] mapped = new double[mappers.length];
146 for (int i = 0; i < mappers.length; ++i) {
147 mapped[i] = mappers[i].unboundedToBounded(point[i]);
148 }
149
150 return mapped;
151 }
152
153 /**
154 * Maps an array from bounded to unbounded.
155 *
156 * @param point Bounded values.
157 * @return the unbounded values.
158 */
159 public double[] boundedToUnbounded(double[] point) {
160 // Map bounded input point to unbounded point.
161 final double[] mapped = new double[mappers.length];
162 for (int i = 0; i < mappers.length; ++i) {
163 mapped[i] = mappers[i].boundedToUnbounded(point[i]);
164 }
165
166 return mapped;
167 }
168
169 /**
170 * Compute the underlying function value from an unbounded point.
171 * <p>
172 * This method simply bounds the unbounded point using the mappings
173 * set up at construction and calls the underlying function using
174 * the bounded point.
175 * </p>
176 * @param point unbounded value
177 * @return underlying function value
178 * @see #unboundedToBounded(double[])
179 */
180 public double value(double[] point) {
181 return bounded.value(unboundedToBounded(point));
182 }
183
184 /** Mapping interface. */
185 private interface Mapper {
186 /**
187 * Maps a value from unbounded to bounded.
188 *
189 * @param y Unbounded value.
190 * @return the bounded value.
191 */
192 double unboundedToBounded(double y);
193
194 /**
195 * Maps a value from bounded to unbounded.
196 *
197 * @param x Bounded value.
198 * @return the unbounded value.
199 */
200 double boundedToUnbounded(double x);
201 }
202
203 /** Local class for no bounds mapping. */
204 private static class NoBoundsMapper implements Mapper {
205 /** {@inheritDoc} */
206 public double unboundedToBounded(final double y) {
207 return y;
208 }
209
210 /** {@inheritDoc} */
211 public double boundedToUnbounded(final double x) {
212 return x;
213 }
214 }
215
216 /** Local class for lower bounds mapping. */
217 private static class LowerBoundMapper implements Mapper {
218 /** Low bound. */
219 private final double lower;
220
221 /**
222 * Simple constructor.
223 *
224 * @param lower lower bound
225 */
226 public LowerBoundMapper(final double lower) {
227 this.lower = lower;
228 }
229
230 /** {@inheritDoc} */
231 public double unboundedToBounded(final double y) {
232 return lower + FastMath.exp(y);
233 }
234
235 /** {@inheritDoc} */
236 public double boundedToUnbounded(final double x) {
237 return FastMath.log(x - lower);
238 }
239
240 }
241
242 /** Local class for upper bounds mapping. */
243 private static class UpperBoundMapper implements Mapper {
244
245 /** Upper bound. */
246 private final double upper;
247
248 /** Simple constructor.
249 * @param upper upper bound
250 */
251 public UpperBoundMapper(final double upper) {
252 this.upper = upper;
253 }
254
255 /** {@inheritDoc} */
256 public double unboundedToBounded(final double y) {
257 return upper - FastMath.exp(-y);
258 }
259
260 /** {@inheritDoc} */
261 public double boundedToUnbounded(final double x) {
262 return -FastMath.log(upper - x);
263 }
264
265 }
266
267 /** Local class for lower and bounds mapping. */
268 private static class LowerUpperBoundMapper implements Mapper {
269 /** Function from unbounded to bounded. */
270 private final UnivariateFunction boundingFunction;
271 /** Function from bounded to unbounded. */
272 private final UnivariateFunction unboundingFunction;
273
274 /**
275 * Simple constructor.
276 *
277 * @param lower lower bound
278 * @param upper upper bound
279 */
280 public LowerUpperBoundMapper(final double lower, final double upper) {
281 boundingFunction = new Sigmoid(lower, upper);
282 unboundingFunction = new Logit(lower, upper);
283 }
284
285 /** {@inheritDoc} */
286 public double unboundedToBounded(final double y) {
287 return boundingFunction.value(y);
288 }
289
290 /** {@inheritDoc} */
291 public double boundedToUnbounded(final double x) {
292 return unboundingFunction.value(x);
293 }
294 }
295 }