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