1 /* 2 * Copyright 2003-2004 The Apache Software Foundation. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 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 }