Java tutorial
/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.math3.analysis.solvers; import org.apache.commons.math3.analysis.UnivariateFunction; import org.apache.commons.math3.exception.NoBracketingException; import org.apache.commons.math3.exception.NotStrictlyPositiveException; import org.apache.commons.math3.exception.NullArgumentException; import org.apache.commons.math3.exception.NumberIsTooLargeException; import org.apache.commons.math3.exception.util.LocalizedFormats; import org.apache.commons.math3.util.FastMath; /** * Utility routines for {@link UnivariateSolver} objects. * * @version $Id: UnivariateSolverUtils.java 1400850 2012-10-22 11:57:17Z erans $ */ public class UnivariateSolverUtils { /** * Class contains only static methods. */ private UnivariateSolverUtils() { } /** * Convenience method to find a zero of a univariate real function. A default * solver is used. * * @param function Function. * @param x0 Lower bound for the interval. * @param x1 Upper bound for the interval. * @return a value where the function is zero. * @throws NoBracketingException if the function has the same sign at the * endpoints. * @throws NullArgumentException if {@code function} is {@code null}. */ public static double solve(UnivariateFunction function, double x0, double x1) throws NullArgumentException, NoBracketingException { if (function == null) { throw new NullArgumentException(LocalizedFormats.FUNCTION); } final UnivariateSolver solver = new BrentSolver(); return solver.solve(Integer.MAX_VALUE, function, x0, x1); } /** * Convenience method to find a zero of a univariate real function. A default * solver is used. * * @param function Function. * @param x0 Lower bound for the interval. * @param x1 Upper bound for the interval. * @param absoluteAccuracy Accuracy to be used by the solver. * @return a value where the function is zero. * @throws NoBracketingException if the function has the same sign at the * endpoints. * @throws NullArgumentException if {@code function} is {@code null}. */ public static double solve(UnivariateFunction function, double x0, double x1, double absoluteAccuracy) throws NullArgumentException, NoBracketingException { if (function == null) { throw new NullArgumentException(LocalizedFormats.FUNCTION); } final UnivariateSolver solver = new BrentSolver(absoluteAccuracy); return solver.solve(Integer.MAX_VALUE, function, x0, x1); } /** Force a root found by a non-bracketing solver to lie on a specified side, * as if the solver was a bracketing one. * @param maxEval maximal number of new evaluations of the function * (evaluations already done for finding the root should have already been subtracted * from this number) * @param f function to solve * @param bracketing bracketing solver to use for shifting the root * @param baseRoot original root found by a previous non-bracketing solver * @param min minimal bound of the search interval * @param max maximal bound of the search interval * @param allowedSolution the kind of solutions that the root-finding algorithm may * accept as solutions. * @return a root approximation, on the specified side of the exact root * @throws NoBracketingException if the function has the same sign at the * endpoints. */ public static double forceSide(final int maxEval, final UnivariateFunction f, final BracketedUnivariateSolver<UnivariateFunction> bracketing, final double baseRoot, final double min, final double max, final AllowedSolution allowedSolution) throws NoBracketingException { if (allowedSolution == AllowedSolution.ANY_SIDE) { // no further bracketing required return baseRoot; } // find a very small interval bracketing the root final double step = FastMath.max(bracketing.getAbsoluteAccuracy(), FastMath.abs(baseRoot * bracketing.getRelativeAccuracy())); double xLo = FastMath.max(min, baseRoot - step); double fLo = f.value(xLo); double xHi = FastMath.min(max, baseRoot + step); double fHi = f.value(xHi); int remainingEval = maxEval - 2; while (remainingEval > 0) { if ((fLo >= 0 && fHi <= 0) || (fLo <= 0 && fHi >= 0)) { // compute the root on the selected side return bracketing.solve(remainingEval, f, xLo, xHi, baseRoot, allowedSolution); } // try increasing the interval boolean changeLo = false; boolean changeHi = false; if (fLo < fHi) { // increasing function if (fLo >= 0) { changeLo = true; } else { changeHi = true; } } else if (fLo > fHi) { // decreasing function if (fLo <= 0) { changeLo = true; } else { changeHi = true; } } else { // unknown variation changeLo = true; changeHi = true; } // update the lower bound if (changeLo) { xLo = FastMath.max(min, xLo - step); fLo = f.value(xLo); remainingEval--; } // update the higher bound if (changeHi) { xHi = FastMath.min(max, xHi + step); fHi = f.value(xHi); remainingEval--; } } throw new NoBracketingException(LocalizedFormats.FAILED_BRACKETING, xLo, xHi, fLo, fHi, maxEval - remainingEval, maxEval, baseRoot, min, max); } /** * This method attempts to find two values a and b satisfying <ul> * <li> <code> lowerBound <= a < initial < b <= upperBound</code> </li> * <li> <code> f(a) * f(b) < 0 </code></li> * </ul> * If f is continuous on <code>[a,b],</code> this means that <code>a</code> * and <code>b</code> bracket a root of f. * <p> * The algorithm starts by setting * <code>a := initial -1; b := initial +1,</code> examines the value of the * function at <code>a</code> and <code>b</code> and keeps moving * the endpoints out by one unit each time through a loop that terminates * when one of the following happens: <ul> * <li> <code> f(a) * f(b) < 0 </code> -- success!</li> * <li> <code> a = lower </code> and <code> b = upper</code> * -- NoBracketingException </li> * <li> <code> Integer.MAX_VALUE</code> iterations elapse * -- NoBracketingException </li> * </ul></p> * <p> * <strong>Note: </strong> this method can take * <code>Integer.MAX_VALUE</code> iterations to throw a * <code>ConvergenceException.</code> Unless you are confident that there * is a root between <code>lowerBound</code> and <code>upperBound</code> * near <code>initial,</code> it is better to use * {@link #bracket(UnivariateFunction, double, double, double, int)}, * explicitly specifying the maximum number of iterations.</p> * * @param function Function. * @param initial Initial midpoint of interval being expanded to * bracket a root. * @param lowerBound Lower bound (a is never lower than this value) * @param upperBound Upper bound (b never is greater than this * value). * @return a two-element array holding a and b. * @throws NoBracketingException if a root cannot be bracketted. * @throws NotStrictlyPositiveException if {@code maximumIterations <= 0}. * @throws NullArgumentException if {@code function} is {@code null}. */ public static double[] bracket(UnivariateFunction function, double initial, double lowerBound, double upperBound) throws NullArgumentException, NotStrictlyPositiveException, NoBracketingException { return bracket(function, initial, lowerBound, upperBound, Integer.MAX_VALUE); } /** * This method attempts to find two values a and b satisfying <ul> * <li> <code> lowerBound <= a < initial < b <= upperBound</code> </li> * <li> <code> f(a) * f(b) <= 0 </code> </li> * </ul> * If f is continuous on <code>[a,b],</code> this means that <code>a</code> * and <code>b</code> bracket a root of f. * <p> * The algorithm starts by setting * <code>a := initial -1; b := initial +1,</code> examines the value of the * function at <code>a</code> and <code>b</code> and keeps moving * the endpoints out by one unit each time through a loop that terminates * when one of the following happens: <ul> * <li> <code> f(a) * f(b) <= 0 </code> -- success!</li> * <li> <code> a = lower </code> and <code> b = upper</code> * -- NoBracketingException </li> * <li> <code> maximumIterations</code> iterations elapse * -- NoBracketingException </li></ul></p> * * @param function Function. * @param initial Initial midpoint of interval being expanded to * bracket a root. * @param lowerBound Lower bound (a is never lower than this value). * @param upperBound Upper bound (b never is greater than this * value). * @param maximumIterations Maximum number of iterations to perform * @return a two element array holding a and b. * @throws NoBracketingException if the algorithm fails to find a and b * satisfying the desired conditions. * @throws NotStrictlyPositiveException if {@code maximumIterations <= 0}. * @throws NullArgumentException if {@code function} is {@code null}. */ public static double[] bracket(UnivariateFunction function, double initial, double lowerBound, double upperBound, int maximumIterations) throws NullArgumentException, NotStrictlyPositiveException, NoBracketingException { if (function == null) { throw new NullArgumentException(LocalizedFormats.FUNCTION); } if (maximumIterations <= 0) { throw new NotStrictlyPositiveException(LocalizedFormats.INVALID_MAX_ITERATIONS, maximumIterations); } verifySequence(lowerBound, initial, upperBound); double a = initial; double b = initial; double fa; double fb; int numIterations = 0; do { a = FastMath.max(a - 1.0, lowerBound); b = FastMath.min(b + 1.0, upperBound); fa = function.value(a); fb = function.value(b); ++numIterations; } while ((fa * fb > 0.0) && (numIterations < maximumIterations) && ((a > lowerBound) || (b < upperBound))); if (fa * fb > 0.0) { throw new NoBracketingException(LocalizedFormats.FAILED_BRACKETING, a, b, fa, fb, numIterations, maximumIterations, initial, lowerBound, upperBound); } return new double[] { a, b }; } /** * Compute the midpoint of two values. * * @param a first value. * @param b second value. * @return the midpoint. */ public static double midpoint(double a, double b) { return (a + b) * 0.5; } /** * Check whether the interval bounds bracket a root. That is, if the * values at the endpoints are not equal to zero, then the function takes * opposite signs at the endpoints. * * @param function Function. * @param lower Lower endpoint. * @param upper Upper endpoint. * @return {@code true} if the function values have opposite signs at the * given points. * @throws NullArgumentException if {@code function} is {@code null}. */ public static boolean isBracketing(UnivariateFunction function, final double lower, final double upper) throws NullArgumentException { if (function == null) { throw new NullArgumentException(LocalizedFormats.FUNCTION); } final double fLo = function.value(lower); final double fHi = function.value(upper); return (fLo >= 0 && fHi <= 0) || (fLo <= 0 && fHi >= 0); } /** * Check whether the arguments form a (strictly) increasing sequence. * * @param start First number. * @param mid Second number. * @param end Third number. * @return {@code true} if the arguments form an increasing sequence. */ public static boolean isSequence(final double start, final double mid, final double end) { return (start < mid) && (mid < end); } /** * Check that the endpoints specify an interval. * * @param lower Lower endpoint. * @param upper Upper endpoint. * @throws NumberIsTooLargeException if {@code lower >= upper}. */ public static void verifyInterval(final double lower, final double upper) throws NumberIsTooLargeException { if (lower >= upper) { throw new NumberIsTooLargeException(LocalizedFormats.ENDPOINTS_NOT_AN_INTERVAL, lower, upper, false); } } /** * Check that {@code lower < initial < upper}. * * @param lower Lower endpoint. * @param initial Initial value. * @param upper Upper endpoint. * @throws NumberIsTooLargeException if {@code lower >= initial} or * {@code initial >= upper}. */ public static void verifySequence(final double lower, final double initial, final double upper) throws NumberIsTooLargeException { verifyInterval(lower, initial); verifyInterval(initial, upper); } /** * Check that the endpoints specify an interval and the end points * bracket a root. * * @param function Function. * @param lower Lower endpoint. * @param upper Upper endpoint. * @throws NoBracketingException if the function has the same sign at the * endpoints. * @throws NullArgumentException if {@code function} is {@code null}. */ public static void verifyBracketing(UnivariateFunction function, final double lower, final double upper) throws NullArgumentException, NoBracketingException { if (function == null) { throw new NullArgumentException(LocalizedFormats.FUNCTION); } verifyInterval(lower, upper); if (!isBracketing(function, lower, upper)) { throw new NoBracketingException(lower, upper, function.value(lower), function.value(upper)); } } }