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 */
17package org.apache.commons.math;
18
19
20/**
21 * Interface for algorithms handling convergence settings.
22 * <p>
23 * This interface only deals with convergence parameters setting, not
24 * execution of the algorithms per se.
25 * </p>
26 * @see ConvergenceException
27 * @version $Revision: 1042336 $ $Date: 2010-12-05 13:40:48 +0100 (dim. 05 déc. 2010) $
28 * @since 2.0
29 * @deprecated in 2.2 (to be removed in 3.0). The concept of "iteration" will
30 * be moved to a new {@code IterativeAlgorithm}. The concept of "accuracy" is
31 * currently is also contained in {@link org.apache.commons.math.optimization.SimpleRealPointChecker}
32 * and similar classes.
33 */
34@Deprecated
35public interface ConvergingAlgorithm {
36
37    /**
38     * Set the upper limit for the number of iterations.
39     * <p>
40     * Usually a high iteration count indicates convergence problems. However,
41     * the "reasonable value" varies widely for different algorithms. Users are
42     * advised to use the default value supplied by the algorithm.</p>
43     * <p>
44     * A {@link ConvergenceException} will be thrown if this number
45     * is exceeded.</p>
46     *
47     * @param count maximum number of iterations
48     */
49    void setMaximalIterationCount(int count);
50
51    /**
52     * Get the upper limit for the number of iterations.
53     *
54     * @return the actual upper limit
55     */
56    int getMaximalIterationCount();
57
58    /**
59     * Reset the upper limit for the number of iterations to the default.
60     * <p>
61     * The default value is supplied by the algorithm implementation.</p>
62     *
63     * @see #setMaximalIterationCount(int)
64     */
65    void resetMaximalIterationCount();
66
67    /**
68     * Set the absolute accuracy.
69     * <p>
70     * The default is usually chosen so that results in the interval
71     * -10..-0.1 and +0.1..+10 can be found with a reasonable accuracy. If the
72     * expected absolute value of your results is of much smaller magnitude, set
73     * this to a smaller value.</p>
74     * <p>
75     * Algorithms are advised to do a plausibility check with the relative
76     * accuracy, but clients should not rely on this.</p>
77     *
78     * @param accuracy the accuracy.
79     * @throws IllegalArgumentException if the accuracy can't be achieved by
80     * the solver or is otherwise deemed unreasonable.
81     */
82    void setAbsoluteAccuracy(double accuracy);
83
84    /**
85     * Get the actual absolute accuracy.
86     *
87     * @return the accuracy
88     */
89    double getAbsoluteAccuracy();
90
91    /**
92     * Reset the absolute accuracy to the default.
93     * <p>
94     * The default value is provided by the algorithm implementation.</p>
95     */
96    void resetAbsoluteAccuracy();
97
98    /**
99     * 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}
142