MultivariateFunctionMappingAdapter.java

  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.math4.legacy.optim.nonlinear.scalar;

  19. import org.apache.commons.math4.legacy.analysis.MultivariateFunction;
  20. import org.apache.commons.math4.legacy.analysis.UnivariateFunction;
  21. import org.apache.commons.math4.legacy.analysis.function.Logit;
  22. import org.apache.commons.math4.legacy.analysis.function.Sigmoid;
  23. import org.apache.commons.math4.legacy.exception.NullArgumentException;
  24. import org.apache.commons.math4.legacy.exception.DimensionMismatchException;
  25. import org.apache.commons.math4.legacy.exception.NumberIsTooSmallException;
  26. import org.apache.commons.math4.core.jdkmath.JdkMath;

  28. /**
  29.  * <p>Adapter for mapping bounded {@link MultivariateFunction} to unbounded ones.</p>
  30.  *
  31.  * <p>
  32.  * This adapter can be used to wrap functions subject to simple bounds on
  33.  * parameters so they can be used by optimizers that do <em>not</em> directly
  34.  * support simple bounds.
  35.  * </p>
  36.  * <p>
  37.  * The principle is that the user function that will be wrapped will see its
  38.  * parameters bounded as required, i.e when its {@code value} method is called
  39.  * with argument array {@code point}, the elements array will fulfill requirement
  40.  * {@code lower[i] <= point[i] <= upper[i]} for all i. Some of the components
  41.  * may be unbounded or bounded only on one side if the corresponding bound is
  42.  * set to an infinite value. The optimizer will not manage the user function by
  43.  * itself, but it will handle this adapter and it is this adapter that will take
  44.  * care the bounds are fulfilled. The adapter {@link #value(double[])} method will
  45.  * be called by the optimizer with unbound parameters, and the adapter will map
  46.  * the unbounded value to the bounded range using appropriate functions like
  47.  * {@link Sigmoid} for double bounded elements for example.
  48.  * </p>
  49.  * <p>
  50.  * As the optimizer sees only unbounded parameters, it should be noted that the
  51.  * start point or simplex expected by the optimizer should be unbounded, so the
  52.  * user is responsible for converting his bounded point to unbounded by calling
  53.  * {@link #boundedToUnbounded(double[])} before providing them to the optimizer.
  54.  * For the same reason, the point returned by the {@link
  55.  * org.apache.commons.math4.legacy.optim.BaseMultivariateOptimizer
  56.  * #optimize(org.apache.commons.math4.legacy.optim.OptimizationData...)}
  57.  * method is unbounded. So to convert this point to bounded, users must call
  58.  * {@link #unboundedToBounded(double[])} by themselves!</p>
  59.  * <p>
  60.  * This adapter is only a poor man solution to simple bounds optimization constraints
  61.  * that can be used with simple optimizers like
  62.  * {@link org.apache.commons.math4.legacy.optim.nonlinear.scalar.noderiv.SimplexOptimizer
  63.  * SimplexOptimizer}.
  64.  * A better solution is to use an optimizer that directly supports simple bounds like
  65.  * {@link org.apache.commons.math4.legacy.optim.nonlinear.scalar.noderiv.CMAESOptimizer
  66.  * CMAESOptimizer} or
  67.  * {@link org.apache.commons.math4.legacy.optim.nonlinear.scalar.noderiv.BOBYQAOptimizer
  68.  * BOBYQAOptimizer}.
  69.  * One caveat of this poor-man's solution is that behavior near the bounds may be
  70.  * numerically unstable as bounds are mapped from infinite values.
  71.  * Another caveat is that convergence values are evaluated by the optimizer with
  72.  * respect to unbounded variables, so there will be scales differences when
  73.  * converted to bounded variables.
  74.  * </p>
  75.  *
  76.  * @see MultivariateFunctionPenaltyAdapter
  77.  *
  78.  * @since 3.0
  79.  */
  80. public class MultivariateFunctionMappingAdapter
  81.     implements MultivariateFunction {
  82.     /** Underlying bounded function. */
  83.     private final MultivariateFunction bounded;
  84.     /** Mapping functions. */
  85.     private final Mapper[] mappers;

  87.     /** Simple constructor.
  88.      * @param bounded bounded function
  89.      * @param lower lower bounds for each element of the input parameters array
  90.      * (some elements may be set to {@code Double.NEGATIVE_INFINITY} for
  91.      * unbounded values)
  92.      * @param upper upper bounds for each element of the input parameters array
  93.      * (some elements may be set to {@code Double.POSITIVE_INFINITY} for
  94.      * unbounded values)
  95.      * @exception DimensionMismatchException if lower and upper bounds are not
  96.      * consistent, either according to dimension or to values
  97.      */
  98.     public MultivariateFunctionMappingAdapter(final MultivariateFunction bounded,
  99.                                               final double[] lower, final double[] upper) {
  100.         // safety checks
  101.         NullArgumentException.check(lower);
  102.         NullArgumentException.check(upper);
  103.         if (lower.length != upper.length) {
  104.             throw new DimensionMismatchException(lower.length, upper.length);
  105.         }
  106.         for (int i = 0; i < lower.length; ++i) {
  107.             // note the following test is written in such a way it also fails for NaN
  108.             if (!(upper[i] >= lower[i])) {
  109.                 throw new NumberIsTooSmallException(upper[i], lower[i], true);
  110.             }
  111.         }

  113.         this.bounded = bounded;
  114.         this.mappers = new Mapper[lower.length];
  115.         for (int i = 0; i < mappers.length; ++i) {
  116.             if (Double.isInfinite(lower[i])) {
  117.                 if (Double.isInfinite(upper[i])) {
  118.                     // element is unbounded, no transformation is needed
  119.                     mappers[i] = new NoBoundsMapper();
  120.                 } else {
  121.                     // element is simple-bounded on the upper side
  122.                     mappers[i] = new UpperBoundMapper(upper[i]);
  123.                 }
  124.             } else {
  125.                 if (Double.isInfinite(upper[i])) {
  126.                     // element is simple-bounded on the lower side
  127.                     mappers[i] = new LowerBoundMapper(lower[i]);
  128.                 } else {
  129.                     // element is double-bounded
  130.                     mappers[i] = new LowerUpperBoundMapper(lower[i], upper[i]);
  131.                 }
  132.             }
  133.         }
  134.     }

  136.     /**
  137.      * Maps an array from unbounded to bounded.
  138.      *
  139.      * @param point Unbounded values.
  140.      * @return the bounded values.
  141.      */
  142.     public double[] unboundedToBounded(double[] point) {
  143.         // Map unbounded input point to bounded point.
  144.         final double[] mapped = new double[mappers.length];
  145.         for (int i = 0; i < mappers.length; ++i) {
  146.             mapped[i] = mappers[i].unboundedToBounded(point[i]);
  147.         }

  149.         return mapped;
  150.     }

  152.     /**
  153.      * Maps an array from bounded to unbounded.
  154.      *
  155.      * @param point Bounded values.
  156.      * @return the unbounded values.
  157.      */
  158.     public double[] boundedToUnbounded(double[] point) {
  159.         // Map bounded input point to unbounded point.
  160.         final double[] mapped = new double[mappers.length];
  161.         for (int i = 0; i < mappers.length; ++i) {
  162.             mapped[i] = mappers[i].boundedToUnbounded(point[i]);
  163.         }

  165.         return mapped;
  166.     }

  168.     /**
  169.      * Compute the underlying function value from an unbounded point.
  170.      * <p>
  171.      * This method simply bounds the unbounded point using the mappings
  172.      * set up at construction and calls the underlying function using
  173.      * the bounded point.
  174.      * </p>
  175.      * @param point unbounded value
  176.      * @return underlying function value
  177.      * @see #unboundedToBounded(double[])
  178.      */
  179.     @Override
  180.     public double value(double[] point) {
  181.         return bounded.value(unboundedToBounded(point));
  182.     }

  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);

  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.     }

  203.     /** Local class for no bounds mapping. */
  204.     private static final class NoBoundsMapper implements Mapper {
  205.         /** {@inheritDoc} */
  206.         @Override
  207.         public double unboundedToBounded(final double y) {
  208.             return y;
  209.         }

  211.         /** {@inheritDoc} */
  212.         @Override
  213.         public double boundedToUnbounded(final double x) {
  214.             return x;
  215.         }
  216.     }

  218.     /** Local class for lower bounds mapping. */
  219.     private static final class LowerBoundMapper implements Mapper {
  220.         /** Low bound. */
  221.         private final double lower;

  223.         /**
  224.          * Simple constructor.
  225.          *
  226.          * @param lower lower bound
  227.          */
  228.         LowerBoundMapper(final double lower) {
  229.             this.lower = lower;
  230.         }

  232.         /** {@inheritDoc} */
  233.         @Override
  234.         public double unboundedToBounded(final double y) {
  235.             return lower + JdkMath.exp(y);
  236.         }

  238.         /** {@inheritDoc} */
  239.         @Override
  240.         public double boundedToUnbounded(final double x) {
  241.             return JdkMath.log(x - lower);
  242.         }
  243.     }

  245.     /** Local class for upper bounds mapping. */
  246.     private static final class UpperBoundMapper implements Mapper {

  248.         /** Upper bound. */
  249.         private final double upper;

  251.         /** Simple constructor.
  252.          * @param upper upper bound
  253.          */
  254.         UpperBoundMapper(final double upper) {
  255.             this.upper = upper;
  256.         }

  258.         /** {@inheritDoc} */
  259.         @Override
  260.         public double unboundedToBounded(final double y) {
  261.             return upper - JdkMath.exp(-y);
  262.         }

  264.         /** {@inheritDoc} */
  265.         @Override
  266.         public double boundedToUnbounded(final double x) {
  267.             return -JdkMath.log(upper - x);
  268.         }
  269.     }

  271.     /** Local class for lower and bounds mapping. */
  272.     private static final class LowerUpperBoundMapper implements Mapper {
  273.         /** Function from unbounded to bounded. */
  274.         private final UnivariateFunction boundingFunction;
  275.         /** Function from bounded to unbounded. */
  276.         private final UnivariateFunction unboundingFunction;

  278.         /**
  279.          * Simple constructor.
  280.          *
  281.          * @param lower lower bound
  282.          * @param upper upper bound
  283.          */
  284.         LowerUpperBoundMapper(final double lower, final double upper) {
  285.             boundingFunction   = new Sigmoid(lower, upper);
  286.             unboundingFunction = new Logit(lower, upper);
  287.         }

  289.         /** {@inheritDoc} */
  290.         @Override
  291.         public double unboundedToBounded(final double y) {
  292.             return boundingFunction.value(y);
  293.         }

  295.         /** {@inheritDoc} */
  296.         @Override
  297.         public double boundedToUnbounded(final double x) {
  298.             return unboundingFunction.value(x);
  299.         }
  300.     }
  301. }
Created with JaCoCo 0.8.10.202304240956Code Coverage Report for Apache Commons Math 4.0-SNAPSHOT