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 19 import org.apache.commons.math4.legacy.exception.NotStrictlyPositiveException; 20 import org.apache.commons.math4.core.jdkmath.JdkMath; 21 import org.apache.commons.math4.legacy.core.Pair; 22 23 /** 24 * Simple implementation of the {@link ConvergenceChecker} interface using 25 * only point coordinates. 26 * 27 * Convergence is considered to have been reached if either the relative 28 * difference between each point coordinate are smaller than a threshold 29 * or if either the absolute difference between the point coordinates are 30 * smaller than another threshold. 31 * <br> 32 * The {@link #converged(int,Pair,Pair) converged} method will also return 33 * {@code true} if the number of iterations has been set (see 34 * {@link #SimplePointChecker(double,double,int) this constructor}). 35 * 36 * @param <PAIR> Type of the (point, value) pair. 37 * The type of the "value" part of the pair (not used by this class). 38 * 39 * @since 3.0 40 */ 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 /** 57 * Build an instance with specified thresholds. 58 * In order to perform only relative checks, the absolute tolerance 59 * must be set to a negative value. In order to perform only absolute 60 * checks, the relative tolerance must be set to a negative value. 61 * 62 * @param relativeThreshold relative tolerance threshold 63 * @param absoluteThreshold absolute tolerance threshold 64 */ 65 public SimplePointChecker(final double relativeThreshold, 66 final double absoluteThreshold) { 67 super(relativeThreshold, absoluteThreshold); 68 maxIterationCount = ITERATION_CHECK_DISABLED; 69 } 70 71 /** 72 * Builds an instance with specified thresholds. 73 * In order to perform only relative checks, the absolute tolerance 74 * must be set to a negative value. In order to perform only absolute 75 * checks, the relative tolerance must be set to a negative value. 76 * 77 * @param relativeThreshold Relative tolerance threshold. 78 * @param absoluteThreshold Absolute tolerance threshold. 79 * @param maxIter Maximum iteration count. 80 * @throws NotStrictlyPositiveException if {@code maxIter <= 0}. 81 * 82 * @since 3.1 83 */ 84 public SimplePointChecker(final double relativeThreshold, 85 final double absoluteThreshold, 86 final int maxIter) { 87 super(relativeThreshold, absoluteThreshold); 88 89 if (maxIter <= 0) { 90 throw new NotStrictlyPositiveException(maxIter); 91 } 92 maxIterationCount = maxIter; 93 } 94 95 /** 96 * Check if the optimization algorithm has converged considering the 97 * last two points. 98 * This method may be called several times from the same algorithm 99 * iteration with different points. This can be detected by checking the 100 * iteration number at each call if needed. Each time this method is 101 * called, the previous and current point correspond to points with the 102 * same role at each iteration, so they can be compared. As an example, 103 * simplex-based algorithms call this method for all points of the simplex, 104 * not only for the best or worst ones. 105 * 106 * @param iteration Index of current iteration 107 * @param previous Best point in the previous iteration. 108 * @param current Best point in the current iteration. 109 * @return {@code true} if the arguments satisfy the convergence criterion. 110 */ 111 @Override 112 public boolean converged(final int iteration, 113 final PAIR previous, 114 final PAIR current) { 115 if (maxIterationCount != ITERATION_CHECK_DISABLED && iteration >= maxIterationCount) { 116 return true; 117 } 118 119 final double[] p = previous.getKey(); 120 final double[] c = current.getKey(); 121 for (int i = 0; i < p.length; ++i) { 122 final double pi = p[i]; 123 final double ci = c[i]; 124 final double difference = JdkMath.abs(pi - ci); 125 final double size = JdkMath.max(JdkMath.abs(pi), JdkMath.abs(ci)); 126 if (difference > size * getRelativeThreshold() && 127 difference > getAbsoluteThreshold()) { 128 return false; 129 } 130 } 131 return true; 132 } 133 }