1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package org.apache.commons.math.analysis;
17
18 import org.apache.commons.math.ConvergenceException;
19 import org.apache.commons.math.FunctionEvaluationException;
20
21
22 /**
23 * Interface for (univariate real) rootfinding algorithms.
24 * <p>
25 * Implementations will search for only one zero in the given interval.
26 *
27 * @version $Revision: 155427 $ $Date: 2005-02-26 06:11:52 -0700 (Sat, 26 Feb 2005) $
28 */
29 public interface UnivariateRealSolver {
30
31 /**
32 * Set the upper limit for the number of iterations.
33 * <p>
34 * Usually a high iteration count indicates convergence problems. However,
35 * the "reasonable value" varies widely for different solvers. Users are
36 * advised to use the default value supplied by the solver.
37 * <p>
38 * A <code>ConvergenceException</code> will be thrown if this number
39 * is exceeded.
40 *
41 * @param count maximum number of iterations
42 */
43 void setMaximalIterationCount(int count);
44
45 /**
46 * Get the upper limit for the number of iterations.
47 *
48 * @return the actual upper limit
49 */
50 int getMaximalIterationCount();
51
52 /**
53 * Reset the upper limit for the number of iterations to the default.
54 * <p>
55 * The default value is supplied by the solver implementation.
56 *
57 * @see #setMaximalIterationCount(int)
58 */
59 void resetMaximalIterationCount();
60
61 /**
62 * Set the absolute accuracy.
63 * <p>
64 * The default is usually choosen so that roots in the interval
65 * -10..-0.1 and +0.1..+10 can be found with a reasonable accuracy. If the
66 * expected absolute value of your roots is of much smaller magnitude, set
67 * this to a smaller value.
68 * <p>
69 * Solvers are advised to do a plausibility check with the relative
70 * accuracy, but clients should not rely on this.
71 *
72 * @param accuracy the accuracy.
73 * @throws IllegalArgumentException if the accuracy can't be achieved by
74 * the solver or is otherwise deemed unreasonable.
75 */
76 void setAbsoluteAccuracy(double accuracy);
77
78 /**
79 * Get the actual absolute accuracy.
80 *
81 * @return the accuracy
82 */
83 double getAbsoluteAccuracy();
84
85 /**
86 * Reset the absolute accuracy to the default.
87 * <p>
88 * The default value is provided by the solver implementation.
89 */
90 void resetAbsoluteAccuracy();
91
92 /**
93 * Set the relative accuracy.
94 * <p>
95 * This is used to stop iterations if the absolute accuracy can't be
96 * achieved due to large values or short mantissa length.
97 * <p>
98 * If this should be the primary criterion for convergence rather then a
99 * safety measure, set the absolute accuracy to a ridiculously small value,
100 * like 1E-1000.
101 *
102 * @param accuracy the relative accuracy.
103 * @throws IllegalArgumentException if the accuracy can't be achieved by
104 * the solver or is otherwise deemed unreasonable.
105 */
106 void setRelativeAccuracy(double accuracy);
107
108 /**
109 * Get the actual relative accuracy.
110 * @return the accuracy
111 */
112 double getRelativeAccuracy();
113
114 /**
115 * Reset the relative accuracy to the default.
116 * The default value is provided by the solver implementation.
117 */
118 void resetRelativeAccuracy();
119
120 /**
121 * Set the function value accuracy.
122 * <p>
123 * This is used to determine whan an evaluated function value or some other
124 * value which is used as divisor is zero.
125 * <p>
126 * This is a safety guard and it shouldn't be necesary to change this in
127 * general.
128 *
129 * @param accuracy the accuracy.
130 * @throws IllegalArgumentException if the accuracy can't be achieved by
131 * the solver or is otherwise deemed unreasonable.
132 */
133 void setFunctionValueAccuracy(double accuracy);
134
135 /**
136 * Get the actual function value accuracy.
137 * @return the accuracy
138 */
139 double getFunctionValueAccuracy();
140
141 /**
142 * Reset the actual function accuracy to the default.
143 * The default value is provided by the solver implementation.
144 */
145 void resetFunctionValueAccuracy();
146
147 /**
148 * Solve for a zero root in the given interval.
149 * A solver may require that the interval brackets a single zero root.
150 *
151 * @param min the lower bound for the interval.
152 * @param max the upper bound for the interval.
153 * @return a value where the function is zero
154 * @throws ConvergenceException if the maximum iteration count is exceeded
155 * or the solver detects convergence problems otherwise.
156 * @throws FunctionEvaluationException if an error occurs evaluating the
157 * function
158 * @throws IllegalArgumentException if min > max or the endpoints do not
159 * satisfy the requirements specified by the solver
160 */
161 double solve(double min, double max) throws ConvergenceException,
162 FunctionEvaluationException;
163
164 /**
165 * Solve for a zero in the given interval, start at startValue.
166 * A solver may require that the interval brackets a single zero root.
167 *
168 * @param min the lower bound for the interval.
169 * @param max the upper bound for the interval.
170 * @param startValue the start value to use
171 * @return a value where the function is zero
172 * @throws ConvergenceException if the maximum iteration count is exceeded
173 * or the solver detects convergence problems otherwise.
174 * @throws FunctionEvaluationException if an error occurs evaluating the
175 * function
176 * @throws IllegalArgumentException if min > max or the arguments do not
177 * satisfy the requirements specified by the solver
178 */
179 double solve(double min, double max, double startValue)
180 throws ConvergenceException, FunctionEvaluationException;
181
182 /**
183 * Get the result of the last run of the solver.
184 *
185 * @return the last result.
186 * @throws IllegalStateException if there is no result available, either
187 * because no result was yet computed or the last attempt failed.
188 */
189 double getResult();
190
191 /**
192 * Get the number of iterations in the last run of the solver.
193 * <p>
194 * This is mainly meant for testing purposes. It may occasionally
195 * help track down performance problems: if the iteration count
196 * is notoriously high, check whether the function is evaluated
197 * properly, and whether another solver is more amenable to the
198 * problem.
199 *
200 * @return the last iteration count.
201 * @throws IllegalStateException if there is no result available, either
202 * because no result was yet computed or the last attempt failed.
203 */
204 int getIterationCount();
205 }