SimplePointChecker.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.math3.optimization;

  18. import org.apache.commons.math3.util.FastMath;
  19. import org.apache.commons.math3.util.Pair;
  20. import org.apache.commons.math3.exception.NotStrictlyPositiveException;

  21. /**
  22.  * Simple implementation of the {@link ConvergenceChecker} interface using
  23.  * only point coordinates.
  24.  *
  25.  * Convergence is considered to have been reached if either the relative
  26.  * difference between each point coordinate are smaller than a threshold
  27.  * or if either the absolute difference between the point coordinates are
  28.  * smaller than another threshold.
  29.  * <br/>
  30.  * The {@link #converged(int,Pair,Pair) converged} method will also return
  31.  * {@code true} if the number of iterations has been set (see
  32.  * {@link #SimplePointChecker(double,double,int) this constructor}).
  33.  *
  34.  * @param <PAIR> Type of the (point, value) pair.
  35.  * The type of the "value" part of the pair (not used by this class).
  36.  *
  37.  * @deprecated As of 3.1 (to be removed in 4.0).
  38.  * @since 3.0
  39.  */
  40. @Deprecated
  41. public class SimplePointChecker<PAIR extends Pair<double[], ? extends Object>>
  42.     extends AbstractConvergenceChecker<PAIR> {
  43.     /**
  44.      * If {@link #maxIterationCount} is set to this value, the number of
  45.      * iterations will never cause {@link #converged(int, Pair, Pair)}
  46.      * to return {@code true}.
  47.      */
  48.     private static final int ITERATION_CHECK_DISABLED = -1;
  49.     /**
  50.      * Number of iterations after which the
  51.      * {@link #converged(int, Pair, Pair)} method
  52.      * will return true (unless the check is disabled).
  53.      */
  54.     private final int maxIterationCount;

  55.     /**
  56.      * Build an instance with default threshold.
  57.      * @deprecated See {@link AbstractConvergenceChecker#AbstractConvergenceChecker()}
  58.      */
  59.     @Deprecated
  60.     public SimplePointChecker() {
  61.         maxIterationCount = ITERATION_CHECK_DISABLED;
  62.     }

  63.     /**
  64.      * Build an instance with specified thresholds.
  65.      * In order to perform only relative checks, the absolute tolerance
  66.      * must be set to a negative value. In order to perform only absolute
  67.      * checks, the relative tolerance must be set to a negative value.
  68.      *
  69.      * @param relativeThreshold relative tolerance threshold
  70.      * @param absoluteThreshold absolute tolerance threshold
  71.      */
  72.     public SimplePointChecker(final double relativeThreshold,
  73.                               final double absoluteThreshold) {
  74.         super(relativeThreshold, absoluteThreshold);
  75.         maxIterationCount = ITERATION_CHECK_DISABLED;
  76.     }

  77.     /**
  78.      * Builds an instance with specified thresholds.
  79.      * In order to perform only relative checks, the absolute tolerance
  80.      * must be set to a negative value. In order to perform only absolute
  81.      * checks, the relative tolerance must be set to a negative value.
  82.      *
  83.      * @param relativeThreshold Relative tolerance threshold.
  84.      * @param absoluteThreshold Absolute tolerance threshold.
  85.      * @param maxIter Maximum iteration count.
  86.      * @throws NotStrictlyPositiveException if {@code maxIter <= 0}.
  87.      *
  88.      * @since 3.1
  89.      */
  90.     public SimplePointChecker(final double relativeThreshold,
  91.                               final double absoluteThreshold,
  92.                               final int maxIter) {
  93.         super(relativeThreshold, absoluteThreshold);

  94.         if (maxIter <= 0) {
  95.             throw new NotStrictlyPositiveException(maxIter);
  96.         }
  97.         maxIterationCount = maxIter;
  98.     }

  99.     /**
  100.      * Check if the optimization algorithm has converged considering the
  101.      * last two points.
  102.      * This method may be called several times from the same algorithm
  103.      * iteration with different points. This can be detected by checking the
  104.      * iteration number at each call if needed. Each time this method is
  105.      * called, the previous and current point correspond to points with the
  106.      * same role at each iteration, so they can be compared. As an example,
  107.      * simplex-based algorithms call this method for all points of the simplex,
  108.      * not only for the best or worst ones.
  109.      *
  110.      * @param iteration Index of current iteration
  111.      * @param previous Best point in the previous iteration.
  112.      * @param current Best point in the current iteration.
  113.      * @return {@code true} if the arguments satify the convergence criterion.
  114.      */
  115.     @Override
  116.     public boolean converged(final int iteration,
  117.                              final PAIR previous,
  118.                              final PAIR current) {
  119.         if (maxIterationCount != ITERATION_CHECK_DISABLED && iteration >= maxIterationCount) {
  120.             return true;
  121.         }

  122.         final double[] p = previous.getKey();
  123.         final double[] c = current.getKey();
  124.         for (int i = 0; i < p.length; ++i) {
  125.             final double pi = p[i];
  126.             final double ci = c[i];
  127.             final double difference = FastMath.abs(pi - ci);
  128.             final double size = FastMath.max(FastMath.abs(pi), FastMath.abs(ci));
  129.             if (difference > size * getRelativeThreshold() &&
  130.                 difference > getAbsoluteThreshold()) {
  131.                 return false;
  132.             }
  133.         }
  134.         return true;
  135.     }
  136. }