SimpleValueChecker.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. /**
  21.  * Simple implementation of the {@link ConvergenceChecker} interface using
  22.  * only objective function values.
  23.  *
  24.  * Convergence is considered to have been reached if either the relative
  25.  * difference between the objective function values is smaller than a
  26.  * threshold or if either the absolute difference between the objective
  27.  * function values is smaller than another threshold.
  28.  * <br>
  29.  * The {@link #converged(int,PointValuePair,PointValuePair) converged}
  30.  * method will also return {@code true} if the number of iterations has been set
  31.  * (see {@link #SimpleValueChecker(double,double,int) this constructor}).
  32.  *
  33.  * @since 3.0
  34.  */
  35. public class SimpleValueChecker
  36.     extends AbstractConvergenceChecker<PointValuePair> {
  37.     /**
  38.      * If {@link #maxIterationCount} is set to this value, the number of
  39.      * iterations will never cause
  40.      * {@link #converged(int,PointValuePair,PointValuePair)}
  41.      * to return {@code true}.
  42.      */
  43.     private static final int ITERATION_CHECK_DISABLED = -1;
  44.     /**
  45.      * Number of iterations after which the
  46.      * {@link #converged(int,PointValuePair,PointValuePair)} method
  47.      * will return true (unless the check is disabled).
  48.      */
  49.     private final int maxIterationCount;

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

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

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

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

  110.         final double p = previous.getValue();
  111.         final double c = current.getValue();
  112.         final double difference = JdkMath.abs(p - c);
  113.         final double size = JdkMath.max(JdkMath.abs(p), JdkMath.abs(c));
  114.         return difference <= size * getRelativeThreshold() ||
  115.             difference <= getAbsoluteThreshold();
  116.     }
  117. }