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

  18. import org.apache.commons.math4.legacy.exception.NotStrictlyPositiveException;
  19. import org.apache.commons.math4.core.jdkmath.JdkMath;
  20. import org.apache.commons.math4.legacy.core.Pair;

  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.  * @since 3.0
  38.  */
  39. public class SimplePointChecker<PAIR extends Pair<double[], ? extends Object>>
  40.     extends AbstractConvergenceChecker<PAIR> {
  41.     /**
  42.      * If {@link #maxIterationCount} is set to this value, the number of
  43.      * iterations will never cause {@link #converged(int, Pair, Pair)}
  44.      * to return {@code true}.
  45.      */
  46.     private static final int ITERATION_CHECK_DISABLED = -1;
  47.     /**
  48.      * Number of iterations after which the
  49.      * {@link #converged(int, Pair, Pair)} method
  50.      * will return true (unless the check is disabled).
  51.      */
  52.     private final int maxIterationCount;

  53.     /**
  54.      * Build an instance with specified thresholds.
  55.      * In order to perform only relative checks, the absolute tolerance
  56.      * must be set to a negative value. In order to perform only absolute
  57.      * checks, the relative tolerance must be set to a negative value.
  58.      *
  59.      * @param relativeThreshold relative tolerance threshold
  60.      * @param absoluteThreshold absolute tolerance threshold
  61.      */
  62.     public SimplePointChecker(final double relativeThreshold,
  63.                               final double absoluteThreshold) {
  64.         super(relativeThreshold, absoluteThreshold);
  65.         maxIterationCount = ITERATION_CHECK_DISABLED;
  66.     }

  67.     /**
  68.      * Builds an instance with specified thresholds.
  69.      * In order to perform only relative checks, the absolute tolerance
  70.      * must be set to a negative value. In order to perform only absolute
  71.      * checks, the relative tolerance must be set to a negative value.
  72.      *
  73.      * @param relativeThreshold Relative tolerance threshold.
  74.      * @param absoluteThreshold Absolute tolerance threshold.
  75.      * @param maxIter Maximum iteration count.
  76.      * @throws NotStrictlyPositiveException if {@code maxIter <= 0}.
  77.      *
  78.      * @since 3.1
  79.      */
  80.     public SimplePointChecker(final double relativeThreshold,
  81.                               final double absoluteThreshold,
  82.                               final int maxIter) {
  83.         super(relativeThreshold, absoluteThreshold);

  84.         if (maxIter <= 0) {
  85.             throw new NotStrictlyPositiveException(maxIter);
  86.         }
  87.         maxIterationCount = maxIter;
  88.     }

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

  112.         final double[] p = previous.getKey();
  113.         final double[] c = current.getKey();
  114.         for (int i = 0; i < p.length; ++i) {
  115.             final double pi = p[i];
  116.             final double ci = c[i];
  117.             final double difference = JdkMath.abs(pi - ci);
  118.             final double size = JdkMath.max(JdkMath.abs(pi), JdkMath.abs(ci));
  119.             if (difference > size * getRelativeThreshold() &&
  120.                 difference > getAbsoluteThreshold()) {
  121.                 return false;
  122.             }
  123.         }
  124.         return true;
  125.     }
  126. }