SimpleUnivariateValueChecker.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.univariate;

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

  21. /**
  22.  * Simple implementation of the
  23.  * {@link org.apache.commons.math4.legacy.optim.ConvergenceChecker} interface
  24.  * that uses only objective function values.
  25.  *
  26.  * Convergence is considered to have been reached if either the relative
  27.  * difference between the objective function values is smaller than a
  28.  * threshold or if either the absolute difference between the objective
  29.  * function values is smaller than another threshold.
  30.  * <br>
  31.  * The {@link #converged(int,UnivariatePointValuePair,UnivariatePointValuePair)
  32.  * converged} method will also return {@code true} if the number of iterations
  33.  * has been set (see {@link #SimpleUnivariateValueChecker(double,double,int)
  34.  * this constructor}).
  35.  *
  36.  * @since 3.1
  37.  */
  38. public class SimpleUnivariateValueChecker
  39.     extends AbstractConvergenceChecker<UnivariatePointValuePair> {
  40.     /**
  41.      * If {@link #maxIterationCount} is set to this value, the number of
  42.      * iterations will never cause
  43.      * {@link #converged(int,UnivariatePointValuePair,UnivariatePointValuePair)}
  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,UnivariatePointValuePair,UnivariatePointValuePair)}
  50.      * method will return true (unless the check is disabled).
  51.      */
  52.     private final int maxIterationCount;

  53.     /** Build an instance with specified thresholds.
  54.      *
  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 SimpleUnivariateValueChecker(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.      *
  70.      * In order to perform only relative checks, the absolute tolerance
  71.      * must be set to a negative value. In order to perform only absolute
  72.      * checks, the relative tolerance must be set to a negative value.
  73.      *
  74.      * @param relativeThreshold relative tolerance threshold
  75.      * @param absoluteThreshold absolute tolerance threshold
  76.      * @param maxIter Maximum iteration count.
  77.      * @throws NotStrictlyPositiveException if {@code maxIter <= 0}.
  78.      *
  79.      * @since 3.1
  80.      */
  81.     public SimpleUnivariateValueChecker(final double relativeThreshold,
  82.                                         final double absoluteThreshold,
  83.                                         final int maxIter) {
  84.         super(relativeThreshold, absoluteThreshold);

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

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

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