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

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

  21. /**
  22.  * Simple implementation of the
  23.  * {@link org.apache.commons.math3.optimization.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.  * @deprecated As of 3.1 (to be removed in 4.0).
  37.  * @since 3.1
  38.  */
  39. @Deprecated
  40. public class SimpleUnivariateValueChecker
  41.     extends AbstractConvergenceChecker<UnivariatePointValuePair> {
  42.     /**
  43.      * If {@link #maxIterationCount} is set to this value, the number of
  44.      * iterations will never cause
  45.      * {@link #converged(int,UnivariatePointValuePair,UnivariatePointValuePair)}
  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,UnivariatePointValuePair,UnivariatePointValuePair)}
  52.      * method will return true (unless the check is disabled).
  53.      */
  54.     private final int maxIterationCount;

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

  63.     /** Build an instance with specified thresholds.
  64.      *
  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 SimpleUnivariateValueChecker(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.      *
  80.      * In order to perform only relative checks, the absolute tolerance
  81.      * must be set to a negative value. In order to perform only absolute
  82.      * checks, the relative tolerance must be set to a negative value.
  83.      *
  84.      * @param relativeThreshold relative tolerance threshold
  85.      * @param absoluteThreshold absolute tolerance threshold
  86.      * @param maxIter Maximum iteration count.
  87.      * @throws NotStrictlyPositiveException if {@code maxIter <= 0}.
  88.      *
  89.      * @since 3.1
  90.      */
  91.     public SimpleUnivariateValueChecker(final double relativeThreshold,
  92.                                         final double absoluteThreshold,
  93.                                         final int maxIter) {
  94.         super(relativeThreshold, absoluteThreshold);

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

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

  123.         final double p = previous.getValue();
  124.         final double c = current.getValue();
  125.         final double difference = FastMath.abs(p - c);
  126.         final double size = FastMath.max(FastMath.abs(p), FastMath.abs(c));
  127.         return difference <= size * getRelativeThreshold() ||
  128.             difference <= getAbsoluteThreshold();
  129.     }
  130. }