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.FunctionEvaluationException;
20 import org.apache.commons.math.MaxIterationsExceededException;
21 import org.apache.commons.math.util.MathUtils;
22
23 /**
24 * Implements the <a href="http://mathworld.wolfram.com/MullersMethod.html">
25 * Muller's Method</a> for root finding of real univariate functions. For
26 * reference, see <b>Elementary Numerical Analysis</b>, ISBN 0070124477,
27 * chapter 3.
28 * <p>
29 * Muller's method applies to both real and complex functions, but here we
30 * restrict ourselves to real functions. Methods solve() and solve2() find
31 * real zeros, using different ways to bypass complex arithmetics.</p>
32 *
33 * @version $Revision: 620312 $ $Date: 2008-02-10 12:28:59 -0700 (Sun, 10 Feb 2008) $
34 * @since 1.2
35 */
36 public class MullerSolver extends UnivariateRealSolverImpl {
37
38 /** serializable version identifier */
39 private static final long serialVersionUID = 6552227503458976920L;
40
41 /**
42 * Construct a solver for the given function.
43 *
44 * @param f function to solve
45 */
46 public MullerSolver(UnivariateRealFunction f) {
47 super(f, 100, 1E-6);
48 }
49
50 /**
51 * Find a real root in the given interval with initial value.
52 * <p>
53 * Requires bracketing condition.</p>
54 *
55 * @param min the lower bound for the interval
56 * @param max the upper bound for the interval
57 * @param initial the start value to use
58 * @return the point at which the function value is zero
59 * @throws MaxIterationsExceededException if the maximum iteration count is exceeded
60 * or the solver detects convergence problems otherwise
61 * @throws FunctionEvaluationException if an error occurs evaluating the
62 * function
63 * @throws IllegalArgumentException if any parameters are invalid
64 */
65 public double solve(double min, double max, double initial) throws
66 MaxIterationsExceededException, FunctionEvaluationException {
67
68 // check for zeros before verifying bracketing
69 if (f.value(min) == 0.0) { return min; }
70 if (f.value(max) == 0.0) { return max; }
71 if (f.value(initial) == 0.0) { return initial; }
72
73 verifyBracketing(min, max, f);
74 verifySequence(min, initial, max);
75 if (isBracketing(min, initial, f)) {
76 return solve(min, initial);
77 } else {
78 return solve(initial, max);
79 }
80 }
81
82 /**
83 * Find a real root in the given interval.
84 * <p>
85 * Original Muller's method would have function evaluation at complex point.
86 * Since our f(x) is real, we have to find ways to avoid that. Bracketing
87 * condition is one way to go: by requiring bracketing in every iteration,
88 * the newly computed approximation is guaranteed to be real.</p>
89 * <p>
90 * Normally Muller's method converges quadratically in the vicinity of a
91 * zero, however it may be very slow in regions far away from zeros. For
92 * example, f(x) = exp(x) - 1, min = -50, max = 100. In such case we use
93 * bisection as a safety backup if it performs very poorly.</p>
94 * <p>
95 * The formulas here use divided differences directly.</p>
96 *
97 * @param min the lower bound for the interval
98 * @param max the upper bound for the interval
99 * @return the point at which the function value is zero
100 * @throws MaxIterationsExceededException if the maximum iteration count is exceeded
101 * or the solver detects convergence problems otherwise
102 * @throws FunctionEvaluationException if an error occurs evaluating the
103 * function
104 * @throws IllegalArgumentException if any parameters are invalid
105 */
106 public double solve(double min, double max) throws MaxIterationsExceededException,
107 FunctionEvaluationException {
108
109 // [x0, x2] is the bracketing interval in each iteration
110 // x1 is the last approximation and an interpolation point in (x0, x2)
111 // x is the new root approximation and new x1 for next round
112 // d01, d12, d012 are divided differences
113 double x0, x1, x2, x, oldx, y0, y1, y2, y;
114 double d01, d12, d012, c1, delta, xplus, xminus, tolerance;
115
116 x0 = min; y0 = f.value(x0);
117 x2 = max; y2 = f.value(x2);
118 x1 = 0.5 * (x0 + x2); y1 = f.value(x1);
119
120 // check for zeros before verifying bracketing
121 if (y0 == 0.0) { return min; }
122 if (y2 == 0.0) { return max; }
123 verifyBracketing(min, max, f);
124
125 int i = 1;
126 oldx = Double.POSITIVE_INFINITY;
127 while (i <= maximalIterationCount) {
128 // Muller's method employs quadratic interpolation through
129 // x0, x1, x2 and x is the zero of the interpolating parabola.
130 // Due to bracketing condition, this parabola must have two
131 // real roots and we choose one in [x0, x2] to be x.
132 d01 = (y1 - y0) / (x1 - x0);
133 d12 = (y2 - y1) / (x2 - x1);
134 d012 = (d12 - d01) / (x2 - x0);
135 c1 = d01 + (x1 - x0) * d012;
136 delta = c1 * c1 - 4 * y1 * d012;
137 xplus = x1 + (-2.0 * y1) / (c1 + Math.sqrt(delta));
138 xminus = x1 + (-2.0 * y1) / (c1 - Math.sqrt(delta));
139 // xplus and xminus are two roots of parabola and at least
140 // one of them should lie in (x0, x2)
141 x = isSequence(x0, xplus, x2) ? xplus : xminus;
142 y = f.value(x);
143
144 // check for convergence
145 tolerance = Math.max(relativeAccuracy * Math.abs(x), absoluteAccuracy);
146 if (Math.abs(x - oldx) <= tolerance) {
147 setResult(x, i);
148 return result;
149 }
150 if (Math.abs(y) <= functionValueAccuracy) {
151 setResult(x, i);
152 return result;
153 }
154
155 // Bisect if convergence is too slow. Bisection would waste
156 // our calculation of x, hopefully it won't happen often.
157 // the real number equality test x == x1 is intentional and
158 // completes the proximity tests above it
159 boolean bisect = (x < x1 && (x1 - x0) > 0.95 * (x2 - x0)) ||
160 (x > x1 && (x2 - x1) > 0.95 * (x2 - x0)) ||
161 (x == x1);
162 // prepare the new bracketing interval for next iteration
163 if (!bisect) {
164 x0 = x < x1 ? x0 : x1;
165 y0 = x < x1 ? y0 : y1;
166 x2 = x > x1 ? x2 : x1;
167 y2 = x > x1 ? y2 : y1;
168 x1 = x; y1 = y;
169 oldx = x;
170 } else {
171 double xm = 0.5 * (x0 + x2);
172 double ym = f.value(xm);
173 if (MathUtils.sign(y0) + MathUtils.sign(ym) == 0.0) {
174 x2 = xm; y2 = ym;
175 } else {
176 x0 = xm; y0 = ym;
177 }
178 x1 = 0.5 * (x0 + x2);
179 y1 = f.value(x1);
180 oldx = Double.POSITIVE_INFINITY;
181 }
182 i++;
183 }
184 throw new MaxIterationsExceededException(maximalIterationCount);
185 }
186
187 /**
188 * Find a real root in the given interval.
189 * <p>
190 * solve2() differs from solve() in the way it avoids complex operations.
191 * Except for the initial [min, max], solve2() does not require bracketing
192 * condition, e.g. f(x0), f(x1), f(x2) can have the same sign. If complex
193 * number arises in the computation, we simply use its modulus as real
194 * approximation.</p>
195 * <p>
196 * Because the interval may not be bracketing, bisection alternative is
197 * not applicable here. However in practice our treatment usually works
198 * well, especially near real zeros where the imaginary part of complex
199 * approximation is often negligible.</p>
200 * <p>
201 * The formulas here do not use divided differences directly.</p>
202 *
203 * @param min the lower bound for the interval
204 * @param max the upper bound for the interval
205 * @return the point at which the function value is zero
206 * @throws MaxIterationsExceededException if the maximum iteration count is exceeded
207 * or the solver detects convergence problems otherwise
208 * @throws FunctionEvaluationException if an error occurs evaluating the
209 * function
210 * @throws IllegalArgumentException if any parameters are invalid
211 */
212 public double solve2(double min, double max) throws MaxIterationsExceededException,
213 FunctionEvaluationException {
214
215 // x2 is the last root approximation
216 // x is the new approximation and new x2 for next round
217 // x0 < x1 < x2 does not hold here
218 double x0, x1, x2, x, oldx, y0, y1, y2, y;
219 double q, A, B, C, delta, denominator, tolerance;
220
221 x0 = min; y0 = f.value(x0);
222 x1 = max; y1 = f.value(x1);
223 x2 = 0.5 * (x0 + x1); y2 = f.value(x2);
224
225 // check for zeros before verifying bracketing
226 if (y0 == 0.0) { return min; }
227 if (y1 == 0.0) { return max; }
228 verifyBracketing(min, max, f);
229
230 int i = 1;
231 oldx = Double.POSITIVE_INFINITY;
232 while (i <= maximalIterationCount) {
233 // quadratic interpolation through x0, x1, x2
234 q = (x2 - x1) / (x1 - x0);
235 A = q * (y2 - (1 + q) * y1 + q * y0);
236 B = (2*q + 1) * y2 - (1 + q) * (1 + q) * y1 + q * q * y0;
237 C = (1 + q) * y2;
238 delta = B * B - 4 * A * C;
239 if (delta >= 0.0) {
240 // choose a denominator larger in magnitude
241 double dplus = B + Math.sqrt(delta);
242 double dminus = B - Math.sqrt(delta);
243 denominator = Math.abs(dplus) > Math.abs(dminus) ? dplus : dminus;
244 } else {
245 // take the modulus of (B +/- Math.sqrt(delta))
246 denominator = Math.sqrt(B * B - delta);
247 }
248 if (denominator != 0) {
249 x = x2 - 2.0 * C * (x2 - x1) / denominator;
250 // perturb x if it exactly coincides with x1 or x2
251 // the equality tests here are intentional
252 while (x == x1 || x == x2) {
253 x += absoluteAccuracy;
254 }
255 } else {
256 // extremely rare case, get a random number to skip it
257 x = min + Math.random() * (max - min);
258 oldx = Double.POSITIVE_INFINITY;
259 }
260 y = f.value(x);
261
262 // check for convergence
263 tolerance = Math.max(relativeAccuracy * Math.abs(x), absoluteAccuracy);
264 if (Math.abs(x - oldx) <= tolerance) {
265 setResult(x, i);
266 return result;
267 }
268 if (Math.abs(y) <= functionValueAccuracy) {
269 setResult(x, i);
270 return result;
271 }
272
273 // prepare the next iteration
274 x0 = x1; y0 = y1;
275 x1 = x2; y1 = y2;
276 x2 = x; y2 = y;
277 oldx = x;
278 i++;
279 }
280 throw new MaxIterationsExceededException(maximalIterationCount);
281 }
282 }