    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    package org.apache.commons.math;
    018
    019
    020    /**
    021     * Interface for algorithms handling convergence settings.
    022     * <p>
    023     * This interface only deals with convergence parameters setting, not
    024     * execution of the algorithms per se.
    025     * </p>
    026     * @see ConvergenceException
    027     * @version $Revision: 1042336 $ $Date: 2010-12-05 13:40:48 +0100 (dim. 05 d??c. 2010) $
    028     * @since 2.0
    029     * @deprecated in 2.2 (to be removed in 3.0). The concept of "iteration" will
    030     * be moved to a new {@code IterativeAlgorithm}. The concept of "accuracy" is
    031     * currently is also contained in {@link org.apache.commons.math.optimization.SimpleRealPointChecker}
    032     * and similar classes.
    033     */
    034    @Deprecated
    035    public interface ConvergingAlgorithm {
    036
    037        /**
    038         * Set the upper limit for the number of iterations.
    039         * <p>
    040         * Usually a high iteration count indicates convergence problems. However,
    041         * the "reasonable value" varies widely for different algorithms. Users are
    042         * advised to use the default value supplied by the algorithm.</p>
    043         * <p>
    044         * A {@link ConvergenceException} will be thrown if this number
    045         * is exceeded.</p>
    046         *
    047         * @param count maximum number of iterations
    048         */
    049        void setMaximalIterationCount(int count);
    050
    051        /**
    052         * Get the upper limit for the number of iterations.
    053         *
    054         * @return the actual upper limit
    055         */
    056        int getMaximalIterationCount();
    057
    058        /**
    059         * Reset the upper limit for the number of iterations to the default.
    060         * <p>
    061         * The default value is supplied by the algorithm implementation.</p>
    062         *
    063         * @see #setMaximalIterationCount(int)
    064         */
    065        void resetMaximalIterationCount();
    066
    067        /**
    068         * Set the absolute accuracy.
    069         * <p>
    070         * The default is usually chosen so that results in the interval
    071         * -10..-0.1 and +0.1..+10 can be found with a reasonable accuracy. If the
    072         * expected absolute value of your results is of much smaller magnitude, set
    073         * this to a smaller value.</p>
    074         * <p>
    075         * Algorithms are advised to do a plausibility check with the relative
    076         * accuracy, but clients should not rely on this.</p>
    077         *
    078         * @param accuracy the accuracy.
    079         * @throws IllegalArgumentException if the accuracy can't be achieved by
    080         * the solver or is otherwise deemed unreasonable.
    081         */
    082        void setAbsoluteAccuracy(double accuracy);
    083
    084        /**
    085         * Get the actual absolute accuracy.
    086         *
    087         * @return the accuracy
    088         */
    089        double getAbsoluteAccuracy();
    090
    091        /**
    092         * Reset the absolute accuracy to the default.
    093         * <p>
    094         * The default value is provided by the algorithm implementation.</p>
    095         */
    096        void resetAbsoluteAccuracy();
    097
    098        /**
    099         * Set the relative accuracy.
    100         * <p>
    101         * This is used to stop iterations if the absolute accuracy can't be
    102         * achieved due to large values or short mantissa length.</p>
    103         * <p>
    104         * If this should be the primary criterion for convergence rather then a
    105         * safety measure, set the absolute accuracy to a ridiculously small value,
    106         * like {@link org.apache.commons.math.util.MathUtils#SAFE_MIN MathUtils.SAFE_MIN}.</p>
    107         *
    108         * @param accuracy the relative accuracy.
    109         * @throws IllegalArgumentException if the accuracy can't be achieved by
    110         *  the algorithm or is otherwise deemed unreasonable.
    111         */
    112        void setRelativeAccuracy(double accuracy);
    113
    114        /**
    115         * Get the actual relative accuracy.
    116         * @return the accuracy
    117         */
    118        double getRelativeAccuracy();
    119
    120        /**
    121         * Reset the relative accuracy to the default.
    122         * The default value is provided by the algorithm implementation.
    123         */
    124        void resetRelativeAccuracy();
    125
    126        /**
    127         * Get the number of iterations in the last run of the algorithm.
    128         * <p>
    129         * This is mainly meant for testing purposes. It may occasionally
    130         * help track down performance problems: if the iteration count
    131         * is notoriously high, check whether the problem is evaluated
    132         * properly, and whether another algorithm is more amenable to the
    133         * problem.</p>
    134         *
    135         * @return the last iteration count.
    136         * @throws IllegalStateException if there is no result available, either
    137         * because no result was yet computed or the last attempt failed.
    138         */
    139        int getIterationCount();
    140
    141    }