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: 1070725 $ $Date: 2011-02-15 02:31:12 +0100 (mar. 15 fvr. 2011) $ 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 function 73 * @throws IllegalArgumentException if min > max or the endpoints do not 74 * satisfy the requirements specified by the solver 75 * @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double)} 76 * since 2.0 77 */ 78 @Deprecated 79 double solve(double min, double max) throws ConvergenceException, FunctionEvaluationException; 80 81 /** 82 * Solve for a zero root in the given interval. 83 * <p>A solver may require that the interval brackets a single zero root. 84 * Solvers that do require bracketing should be able to handle the case 85 * where one of the endpoints is itself a root.</p> 86 * 87 * @param f the function to solve. 88 * @param min the lower bound for the interval. 89 * @param max the upper bound for the interval. 90 * @return a value where the function is zero 91 * @throws ConvergenceException if the maximum iteration count is exceeded 92 * or the solver detects convergence problems otherwise. 93 * @throws FunctionEvaluationException if an error occurs evaluating the function 94 * @throws IllegalArgumentException if min > max or the endpoints do not 95 * satisfy the requirements specified by the solver 96 * @since 2.0 97 * @deprecated in 2.2 (to be removed in 3.0). 98 */ 99 @Deprecated 100 double solve(UnivariateRealFunction f, double min, double max) 101 throws ConvergenceException, FunctionEvaluationException; 102 103 /** 104 * Solve for a zero in the given interval, start at startValue. 105 * <p>A solver may require that the interval brackets a single zero root. 106 * Solvers that do require bracketing should be able to handle the case 107 * where one of the endpoints is itself a root.</p> 108 * 109 * @param min the lower bound for the interval. 110 * @param max the upper bound for the interval. 111 * @param startValue the start value to use 112 * @return a value where the function is zero 113 * @throws ConvergenceException if the maximum iteration count is exceeded 114 * or the solver detects convergence problems otherwise. 115 * @throws FunctionEvaluationException if an error occurs evaluating the function 116 * @throws IllegalArgumentException if min > max or the arguments do not 117 * satisfy the requirements specified by the solver 118 * @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double, double)} 119 * since 2.0 120 */ 121 @Deprecated 122 double solve(double min, double max, double startValue) 123 throws ConvergenceException, FunctionEvaluationException, IllegalArgumentException; 124 125 /** 126 * Solve for a zero in the given interval, start at startValue. 127 * <p>A solver may require that the interval brackets a single zero root. 128 * Solvers that do require bracketing should be able to handle the case 129 * where one of the endpoints is itself a root.</p> 130 * 131 * @param f the function to solve. 132 * @param min the lower bound for the interval. 133 * @param max the upper bound for the interval. 134 * @param startValue the start value to use 135 * @return a value where the function is zero 136 * @throws ConvergenceException if the maximum iteration count is exceeded 137 * or the solver detects convergence problems otherwise. 138 * @throws FunctionEvaluationException if an error occurs evaluating the function 139 * @throws IllegalArgumentException if min > max or the arguments do not 140 * satisfy the requirements specified by the solver 141 * @since 2.0 142 * @deprecated in 2.2 (to be removed in 3.0). 143 */ 144 @Deprecated 145 double solve(UnivariateRealFunction f, double min, double max, double startValue) 146 throws ConvergenceException, FunctionEvaluationException, IllegalArgumentException; 147 148 /** 149 * Get the result of the last run of the solver. 150 * 151 * @return the last result. 152 * @throws IllegalStateException if there is no result available, either 153 * because no result was yet computed or the last attempt failed. 154 */ 155 double getResult(); 156 157 /** 158 * Get the result of the last run of the solver. 159 * 160 * @return the value of the function at the last result. 161 * @throws IllegalStateException if there is no result available, either 162 * because no result was yet computed or the last attempt failed. 163 */ 164 double getFunctionValue(); 165 } 166
