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.solvers; 18 19 import org.apache.commons.math.ConvergenceException; 20 import org.apache.commons.math.ConvergingAlgorithm; 21 import org.apache.commons.math.FunctionEvaluationException; 22 import org.apache.commons.math.analysis.UnivariateRealFunction; 23 24 25 /** 26 * Interface for (univariate real) rootfinding algorithms. 27 * <p> 28 * Implementations will search for only one zero in the given interval.</p> 29 * 30 * @version $Revision: 799857 $ $Date: 2009-08-01 09:07:12 -0400 (Sat, 01 Aug 2009) $ 31 */ 32 public interface UnivariateRealSolver extends ConvergingAlgorithm { 33 34 /** 35 * Set the function value accuracy. 36 * <p> 37 * This is used to determine when an evaluated function value or some other 38 * value which is used as divisor is zero.</p> 39 * <p> 40 * This is a safety guard and it shouldn't be necessary to change this in 41 * general.</p> 42 * 43 * @param accuracy the accuracy. 44 * @throws IllegalArgumentException if the accuracy can't be achieved by 45 * the solver or is otherwise deemed unreasonable. 46 */ 47 void setFunctionValueAccuracy(double accuracy); 48 49 /** 50 * Get the actual function value accuracy. 51 * @return the accuracy 52 */ 53 double getFunctionValueAccuracy(); 54 55 /** 56 * Reset the actual function accuracy to the default. 57 * The default value is provided by the solver implementation. 58 */ 59 void resetFunctionValueAccuracy(); 60 61 /** 62 * Solve for a zero root in the given interval. 63 * <p>A solver may require that the interval brackets a single zero root. 64 * Solvers that do require bracketing should be able to handle the case 65 * where one of the endpoints is itself a root.</p> 66 * 67 * @param min the lower bound for the interval. 68 * @param max the upper bound for the interval. 69 * @return a value where the function is zero 70 * @throws ConvergenceException if the maximum iteration count is exceeded 71 * or the solver detects convergence problems otherwise. 72 * @throws FunctionEvaluationException if an error occurs evaluating the 73 * function 74 * @throws IllegalArgumentException if min > max or the endpoints do not 75 * satisfy the requirements specified by the solver 76 * @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double)} 77 * since 2.0 78 */ 79 @Deprecated 80 double solve(double min, double max) throws ConvergenceException, 81 FunctionEvaluationException; 82 83 /** 84 * Solve for a zero root in the given interval. 85 * <p>A solver may require that the interval brackets a single zero root. 86 * Solvers that do require bracketing should be able to handle the case 87 * where one of the endpoints is itself a root.</p> 88 * 89 * @param f the function to solve. 90 * @param min the lower bound for the interval. 91 * @param max the upper bound for the interval. 92 * @return a value where the function is zero 93 * @throws ConvergenceException if the maximum iteration count is exceeded 94 * or the solver detects convergence problems otherwise. 95 * @throws FunctionEvaluationException if an error occurs evaluating the 96 * function 97 * @throws IllegalArgumentException if min > max or the endpoints do not 98 * satisfy the requirements specified by the solver 99 * @since 2.0 100 */ 101 double solve(UnivariateRealFunction f, double min, double max) 102 throws ConvergenceException, 103 FunctionEvaluationException; 104 105 /** 106 * Solve for a zero in the given interval, start at startValue. 107 * <p>A solver may require that the interval brackets a single zero root. 108 * Solvers that do require bracketing should be able to handle the case 109 * where one of the endpoints is itself a root.</p> 110 * 111 * @param min the lower bound for the interval. 112 * @param max the upper bound for the interval. 113 * @param startValue the start value to use 114 * @return a value where the function is zero 115 * @throws ConvergenceException if the maximum iteration count is exceeded 116 * or the solver detects convergence problems otherwise. 117 * @throws FunctionEvaluationException if an error occurs evaluating the 118 * function 119 * @throws IllegalArgumentException if min > max or the arguments do not 120 * satisfy the requirements specified by the solver 121 * @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double, double)} 122 * since 2.0 123 */ 124 @Deprecated 125 double solve(double min, double max, double startValue) 126 throws ConvergenceException, FunctionEvaluationException, IllegalArgumentException; 127 128 /** 129 * Solve for a zero in the given interval, start at startValue. 130 * <p>A solver may require that the interval brackets a single zero root. 131 * Solvers that do require bracketing should be able to handle the case 132 * where one of the endpoints is itself a root.</p> 133 * 134 * @param f the function to solve. 135 * @param min the lower bound for the interval. 136 * @param max the upper bound for the interval. 137 * @param startValue the start value to use 138 * @return a value where the function is zero 139 * @throws ConvergenceException if the maximum iteration count is exceeded 140 * or the solver detects convergence problems otherwise. 141 * @throws FunctionEvaluationException if an error occurs evaluating the 142 * function 143 * @throws IllegalArgumentException if min > max or the arguments do not 144 * satisfy the requirements specified by the solver 145 * @since 2.0 146 */ 147 double solve(UnivariateRealFunction f, double min, double max, double startValue) 148 throws ConvergenceException, FunctionEvaluationException, IllegalArgumentException; 149 150 /** 151 * Get the result of the last run of the solver. 152 * 153 * @return the last result. 154 * @throws IllegalStateException if there is no result available, either 155 * because no result was yet computed or the last attempt failed. 156 */ 157 double getResult(); 158 159 /** 160 * Get the result of the last run of the solver. 161 * 162 * @return the value of the function at the last result. 163 * @throws IllegalStateException if there is no result available, either 164 * because no result was yet computed or the last attempt failed. 165 */ 166 double getFunctionValue(); 167 }