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

## Class AbstractSimplex

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

- All Implemented Interfaces:
    OptimizationData
  Direct Known Subclasses:
    MultiDirectionalSimplex, NelderMeadSimplex

      public abstract class AbstractSimplex
      extends Object
      implements OptimizationData

  This class implements the simplex concept. It is intended to be used in conjunction with `SimplexOptimizer`.
  The initial configuration of the simplex is set by the constructors `AbstractSimplex(double[])` or `AbstractSimplex(double[][])`. The other `constructor` will set all steps to 1, thus building a default configuration from a unit hypercube.
  Users must call the `build` method in order to create the data structure that will be acted on by the other methods of this class.
  Since:
    3.0
  Version:
    $Id: AbstractSimplex.java 1397759 2012-10-13 01:12:58Z erans $
  See Also:
    `SimplexOptimizer`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private int` | `dimension` Simplex dimension (must be equal to `simplex.length - 1`).
    `private PointValuePair[]` | `simplex` Simplex.
    `private double[][]` | `startConfiguration` Start simplex configuration.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AbstractSimplex(double[] steps)` The start configuration for simplex is built from a box parallel to the canonical axes of the space.
    `protected` | `AbstractSimplex(double[][] referenceSimplex)` The real initial simplex will be set up by moving the reference simplex such that its first point is located at the start point of the optimization.
    `protected` | `AbstractSimplex(int n)` Build a unit hypercube simplex.
    `protected` | `AbstractSimplex(int n, double sideLength)` Build a hypercube simplex with the given side length.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `build(double[] startPoint)` Build an initial simplex.
    `private static double[]` | `createHypercubeSteps(int n, double sideLength)` Create steps for a unit hypercube.
    `void` | `evaluate(MultivariateFunction evaluationFunction, Comparator<PointValuePair> comparator)` Evaluate all the non-evaluated points of the simplex.
    `int` | `getDimension()` Get simplex dimension.
    `PointValuePair` | `getPoint(int index)` Get the simplex point stored at the requested `index`.
    `PointValuePair[]` | `getPoints()` Get the points of the simplex.
    `int` | `getSize()` Get simplex size.
    `abstract void` | `iterate(MultivariateFunction evaluationFunction, Comparator<PointValuePair> comparator)` Compute the next simplex of the algorithm.
    `protected void` | `replaceWorstPoint(PointValuePair pointValuePair, Comparator<PointValuePair> comparator)` Replace the worst point of the simplex by a new point.
    `protected void` | `setPoint(int index, PointValuePair point)` Store a new point at location `index`.
    `protected void` | `setPoints(PointValuePair[] points)` Replace all points.

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

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

- - ### Field Detail

    - #### simplex

          private PointValuePair[] simplex

      Simplex.

    - #### startConfiguration

          private double[][] startConfiguration

      Start simplex configuration.

    - #### dimension

          private final int dimension

      Simplex dimension (must be equal to `simplex.length - 1`).

  - ### Constructor Detail

    - #### AbstractSimplex

          protected AbstractSimplex(int n)

      Build a unit hypercube simplex.
      Parameters:
        `n` - Dimension of the simplex.

    - #### AbstractSimplex

          protected AbstractSimplex(int n,
                         double sideLength)

      Build a hypercube simplex with the given side length.
      Parameters:
        `n` - Dimension of the simplex.
        `sideLength` - Length of the sides of the hypercube.

    - #### AbstractSimplex

          protected AbstractSimplex(double[] steps)

      The start configuration for simplex is built from a box parallel to the canonical axes of the space. The simplex is the subset of vertices of a box parallel to the canonical axes. It is built as the path followed while traveling from one vertex of the box to the diagonally opposite vertex moving only along the box edges. The first vertex of the box will be located at the start point of the optimization. As an example, in dimension 3 a simplex has 4 vertices. Setting the steps to (1, 10, 2) and the start point to (1, 1, 1) would imply the start simplex would be: { (1, 1, 1), (2, 1, 1), (2, 11, 1), (2, 11, 3) }. The first vertex would be set to the start point at (1, 1, 1) and the last vertex would be set to the diagonally opposite vertex at (2, 11, 3).
      Parameters:
        `steps` - Steps along the canonical axes representing box edges. They may be negative but not zero.
      Throws:
        `NullArgumentException` - if `steps` is `null`.
        `ZeroException` - if one of the steps is zero.

    - #### AbstractSimplex

          protected AbstractSimplex(double[][] referenceSimplex)

      The real initial simplex will be set up by moving the reference simplex such that its first point is located at the start point of the optimization.
      Parameters:
        `referenceSimplex` - Reference simplex.
      Throws:
        `NotStrictlyPositiveException` - if the reference simplex does not contain at least one point.
        `DimensionMismatchException` - if there is a dimension mismatch in the reference simplex.
        `IllegalArgumentException` - if one of its vertices is duplicated.

  - ### Method Detail

    - #### getDimension

          public int getDimension()

      Get simplex dimension.
      Returns:
        the dimension of the simplex.

    - #### getSize

          public int getSize()

      Get simplex size. After calling the `build` method, this method will will be equivalent to `getDimension() + 1`.
      Returns:
        the size of the simplex.

    - #### iterate

          public abstract void iterate(MultivariateFunction evaluationFunction,
                     Comparator<PointValuePair> comparator)

      Compute the next simplex of the algorithm.
      Parameters:
        `evaluationFunction` - Evaluation function.
        `comparator` - Comparator to use to sort simplex vertices from best to worst.
      Throws:
        `TooManyEvaluationsException` - if the algorithm fails to converge.

    - #### build

          public void build(double[] startPoint)

      Build an initial simplex.
      Parameters:
        `startPoint` - First point of the simplex.
      Throws:
        `DimensionMismatchException` - if the start point does not match simplex dimension.

    - #### evaluate

          public void evaluate(MultivariateFunction evaluationFunction,
                      Comparator<PointValuePair> comparator)

      Evaluate all the non-evaluated points of the simplex.
      Parameters:
        `evaluationFunction` - Evaluation function.
        `comparator` - Comparator to use to sort simplex vertices from best to worst.
      Throws:
        `TooManyEvaluationsException` - if the maximal number of evaluations is exceeded.

    - #### replaceWorstPoint

          protected void replaceWorstPoint(PointValuePair pointValuePair,
                               Comparator<PointValuePair> comparator)

      Replace the worst point of the simplex by a new point.
      Parameters:
        `pointValuePair` - Point to insert.
        `comparator` - Comparator to use for sorting the simplex vertices from best to worst.

    - #### getPoints

          public PointValuePair[] getPoints()

      Get the points of the simplex.
      Returns:
        all the simplex points.

    - #### getPoint

          public PointValuePair getPoint(int index)

      Get the simplex point stored at the requested `index`.
      Parameters:
        `index` - Location.
      Returns:
        the point at location `index`.

    - #### setPoint

          protected void setPoint(int index,
                      PointValuePair point)

      Store a new point at location `index`. Note that no deep-copy of `point` is performed.
      Parameters:
        `index` - Location.
        `point` - New value.

    - #### setPoints

          protected void setPoints(PointValuePair[] points)

      Replace all points. Note that no deep-copy of `points` is performed.
      Parameters:
        `points` - New Points.

    - #### createHypercubeSteps

          private static double[] createHypercubeSteps(int n,
                                      double sideLength)

      Create steps for a unit hypercube.
      Parameters:
        `n` - Dimension of the hypercube.
        `sideLength` - Length of the sides of the hypercube.
      Returns:
        the steps.

Copyright (c) 2003-2013 Apache Software Foundation