org.apache.commons.math3.optim.nonlinear.scalar

## Class MultivariateFunctionMappingAdapter

- java.lang.Object
- - org.apache.commons.math3.optim.nonlinear.scalar.MultivariateFunctionMappingAdapter

- All Implemented Interfaces:
    MultivariateFunction

      public class MultivariateFunctionMappingAdapter
      extends Object
      implements MultivariateFunction

  Adapter for mapping bounded `MultivariateFunction` to unbounded ones.

  This adapter can be used to wrap functions subject to simple bounds on parameters so they can be used by optimizers that do not directly support simple bounds.

  The principle is that the user function that will be wrapped will see its parameters bounded as required, i.e when its `value` method is called with argument array `point`, the elements array will fulfill requirement `lower[i] <= point[i] <= upper[i]` for all i. Some of the components may be unbounded or bounded only on one side if the corresponding bound is set to an infinite value. The optimizer will not manage the user function by itself, but it will handle this adapter and it is this adapter that will take care the bounds are fulfilled. The adapter `value(double[])` method will be called by the optimizer with unbound parameters, and the adapter will map the unbounded value to the bounded range using appropriate functions like `Sigmoid` for double bounded elements for example.

  As the optimizer sees only unbounded parameters, it should be noted that the start point or simplex expected by the optimizer should be unbounded, so the user is responsible for converting his bounded point to unbounded by calling `boundedToUnbounded(double[])` before providing them to the optimizer. For the same reason, the point returned by the `BaseMultivariateOptimizer.optimize(int, MultivariateFunction, org.apache.commons.math3.optimization.GoalType, double[])` method is unbounded. So to convert this point to bounded, users must call `unboundedToBounded(double[])` by themselves!

  This adapter is only a poor man solution to simple bounds optimization constraints that can be used with simple optimizers like `SimplexOptimizer`. A better solution is to use an optimizer that directly supports simple bounds like `CMAESOptimizer` or `BOBYQAOptimizer`. One caveat of this poor-man's solution is that behavior near the bounds may be numerically unstable as bounds are mapped from infinite values. Another caveat is that convergence values are evaluated by the optimizer with respect to unbounded variables, so there will be scales differences when converted to bounded variables.

  Since:
    3.0
  Version:
    $Id: MultivariateFunctionMappingAdapter.java 1416643 2012-12-03 19:37:14Z tn $
  See Also:
    `MultivariateFunctionPenaltyAdapter`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `private static class` | `MultivariateFunctionMappingAdapter.LowerBoundMapper` Local class for lower bounds mapping.
    `private static class` | `MultivariateFunctionMappingAdapter.LowerUpperBoundMapper` Local class for lower and bounds mapping.
    `private static interface` | `MultivariateFunctionMappingAdapter.Mapper` Mapping interface.
    `private static class` | `MultivariateFunctionMappingAdapter.NoBoundsMapper` Local class for no bounds mapping.
    `private static class` | `MultivariateFunctionMappingAdapter.UpperBoundMapper` Local class for upper bounds mapping.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private MultivariateFunction` | `bounded` Underlying bounded function.
    `private MultivariateFunctionMappingAdapter.Mapper[]` | `mappers` Mapping functions.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MultivariateFunctionMappingAdapter(MultivariateFunction bounded, double[] lower, double[] upper)` Simple constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `double[]` | `boundedToUnbounded(double[] point)` Maps an array from bounded to unbounded.
    `double[]` | `unboundedToBounded(double[] point)` Maps an array from unbounded to bounded.
    `double` | `value(double[] point)` Compute the underlying function value from an unbounded point.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### bounded

          private final MultivariateFunction bounded

      Underlying bounded function.

    - #### mappers

          private final MultivariateFunctionMappingAdapter.Mapper[] mappers

      Mapping functions.

  - ### Constructor Detail

    - #### MultivariateFunctionMappingAdapter

          public MultivariateFunctionMappingAdapter(MultivariateFunction bounded,
                                            double[] lower,
                                            double[] upper)

      Simple constructor.
      Parameters:
        `bounded` - bounded function
        `lower` - lower bounds for each element of the input parameters array (some elements may be set to `Double.NEGATIVE_INFINITY` for unbounded values)
        `upper` - upper bounds for each element of the input parameters array (some elements may be set to `Double.POSITIVE_INFINITY` for unbounded values)
      Throws:
        `DimensionMismatchException` - if lower and upper bounds are not consistent, either according to dimension or to values

  - ### Method Detail

    - #### unboundedToBounded

          public double[] unboundedToBounded(double[] point)

      Maps an array from unbounded to bounded.
      Parameters:
        `point` - Unbounded values.
      Returns:
        the bounded values.

    - #### boundedToUnbounded

          public double[] boundedToUnbounded(double[] point)

      Maps an array from bounded to unbounded.
      Parameters:
        `point` - Bounded values.
      Returns:
        the unbounded values.

    - #### value

          public double value(double[] point)

      Compute the underlying function value from an unbounded point.

      This method simply bounds the unbounded point using the mappings set up at construction and calls the underlying function using the bounded point.

      Specified by:
        `value` in interface `MultivariateFunction`
      Parameters:
        `point` - unbounded value
      Returns:
        underlying function value
      See Also:
        `unboundedToBounded(double[])`

Copyright (c) 2003-2013 Apache Software Foundation