001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    
018    package org.apache.commons.math.optimization;
019    
020    import org.apache.commons.math.util.FastMath;
021    
022    /**
023     * Simple implementation of the {@link ConvergenceChecker} interface using
024     * only objective function values.
025     *
026     * Convergence is considered to have been reached if either the relative
027     * difference between the objective function values is smaller than a
028     * threshold or if either the absolute difference between the objective
029     * function values is smaller than another threshold.
030     *
031     * @version $Id: SimpleScalarValueChecker.java 1131229 2011-06-03 20:49:25Z luc $
032     * @since 3.0
033     */
034    public class SimpleScalarValueChecker
035        extends AbstractConvergenceChecker<RealPointValuePair> {
036        /**
037         * Build an instance with default thresholds.
038         */
039        public SimpleScalarValueChecker() {}
040    
041        /** Build an instance with specified thresholds.
042         *
043         * In order to perform only relative checks, the absolute tolerance
044         * must be set to a negative value. In order to perform only absolute
045         * checks, the relative tolerance must be set to a negative value.
046         *
047         * @param relativeThreshold relative tolerance threshold
048         * @param absoluteThreshold absolute tolerance threshold
049         */
050        public SimpleScalarValueChecker(final double relativeThreshold,
051                                        final double absoluteThreshold) {
052            super(relativeThreshold, absoluteThreshold);
053        }
054    
055        /**
056         * Check if the optimization algorithm has converged considering the
057         * last two points.
058         * This method may be called several time from the same algorithm
059         * iteration with different points. This can be detected by checking the
060         * iteration number at each call if needed. Each time this method is
061         * called, the previous and current point correspond to points with the
062         * same role at each iteration, so they can be compared. As an example,
063         * simplex-based algorithms call this method for all points of the simplex,
064         * not only for the best or worst ones.
065         *
066         * @param iteration Index of current iteration
067         * @param previous Best point in the previous iteration.
068         * @param current Best point in the current iteration.
069         * @return {@code true} if the algorithm has converged.
070         */
071        @Override
072        public boolean converged(final int iteration,
073                                 final RealPointValuePair previous,
074                                 final RealPointValuePair current) {
075            final double p = previous.getValue();
076            final double c = current.getValue();
077            final double difference = FastMath.abs(p - c);
078            final double size = FastMath.max(FastMath.abs(p), FastMath.abs(c));
079            return difference <= size * getRelativeThreshold() ||
080                difference <= getAbsoluteThreshold();
081        }
082    }