1dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond/* 2dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * Licensed to the Apache Software Foundation (ASF) under one or more 3dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * contributor license agreements. See the NOTICE file distributed with 4dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * this work for additional information regarding copyright ownership. 5dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * The ASF licenses this file to You under the Apache License, Version 2.0 6dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * (the "License"); you may not use this file except in compliance with 7dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * the License. You may obtain a copy of the License at 8dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * 9dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * http://www.apache.org/licenses/LICENSE-2.0 10dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * 11dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * Unless required by applicable law or agreed to in writing, software 12dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * distributed under the License is distributed on an "AS IS" BASIS, 13dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * See the License for the specific language governing permissions and 15dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * limitations under the License. 16dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond */ 17dee0849a9704d532af0b550146cbafbaa6ee1d19Raymondpackage org.apache.commons.math.analysis.solvers; 18dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond 19dee0849a9704d532af0b550146cbafbaa6ee1d19Raymondimport org.apache.commons.math.ConvergenceException; 20dee0849a9704d532af0b550146cbafbaa6ee1d19Raymondimport org.apache.commons.math.ConvergingAlgorithm; 21dee0849a9704d532af0b550146cbafbaa6ee1d19Raymondimport org.apache.commons.math.FunctionEvaluationException; 22dee0849a9704d532af0b550146cbafbaa6ee1d19Raymondimport org.apache.commons.math.analysis.UnivariateRealFunction; 23dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond 24dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond 25dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond/** 26dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * Interface for (univariate real) rootfinding algorithms. 27dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * <p> 28dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * Implementations will search for only one zero in the given interval.</p> 29dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * 30dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @version $Revision: 1070725 $ $Date: 2011-02-15 02:31:12 +0100 (mar. 15 févr. 2011) $ 31dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond */ 32dee0849a9704d532af0b550146cbafbaa6ee1d19Raymondpublic interface UnivariateRealSolver extends ConvergingAlgorithm { 33dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond 34dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond /** 35dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * Set the function value accuracy. 36dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * <p> 37dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * This is used to determine when an evaluated function value or some other 38dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * value which is used as divisor is zero.</p> 39dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * <p> 40dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * This is a safety guard and it shouldn't be necessary to change this in 41dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * general.</p> 42dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * 43dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @param accuracy the accuracy. 44dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @throws IllegalArgumentException if the accuracy can't be achieved by 45dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * the solver or is otherwise deemed unreasonable. 46dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond */ 47dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond void setFunctionValueAccuracy(double accuracy); 48dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond 49dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond /** 50dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * Get the actual function value accuracy. 51dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @return the accuracy 52dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond */ 53dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond double getFunctionValueAccuracy(); 54dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond 55dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond /** 56dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * Reset the actual function accuracy to the default. 57dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * The default value is provided by the solver implementation. 58dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond */ 59dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond void resetFunctionValueAccuracy(); 60dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond 61dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond /** 62dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * Solve for a zero root in the given interval. 63dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * <p>A solver may require that the interval brackets a single zero root. 64dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * Solvers that do require bracketing should be able to handle the case 65dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * where one of the endpoints is itself a root.</p> 66dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * 67dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @param min the lower bound for the interval. 68dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @param max the upper bound for the interval. 69dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @return a value where the function is zero 70dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @throws ConvergenceException if the maximum iteration count is exceeded 71dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * or the solver detects convergence problems otherwise. 72dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @throws FunctionEvaluationException if an error occurs evaluating the function 73dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @throws IllegalArgumentException if min > max or the endpoints do not 74dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * satisfy the requirements specified by the solver 75dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double)} 76dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * since 2.0 77dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond */ 78dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond @Deprecated 79dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond double solve(double min, double max) throws ConvergenceException, FunctionEvaluationException; 80dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond 81dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond /** 82dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * Solve for a zero root in the given interval. 83dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * <p>A solver may require that the interval brackets a single zero root. 84dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * Solvers that do require bracketing should be able to handle the case 85dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * where one of the endpoints is itself a root.</p> 86dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * 87dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @param f the function to solve. 88dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @param min the lower bound for the interval. 89dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @param max the upper bound for the interval. 90dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @return a value where the function is zero 91dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @throws ConvergenceException if the maximum iteration count is exceeded 92dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * or the solver detects convergence problems otherwise. 93dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @throws FunctionEvaluationException if an error occurs evaluating the function 94dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @throws IllegalArgumentException if min > max or the endpoints do not 95dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * satisfy the requirements specified by the solver 96dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @since 2.0 97dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @deprecated in 2.2 (to be removed in 3.0). 98dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond */ 99dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond @Deprecated 100dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond double solve(UnivariateRealFunction f, double min, double max) 101dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond throws ConvergenceException, FunctionEvaluationException; 102dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond 103dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond /** 104dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * Solve for a zero in the given interval, start at startValue. 105dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * <p>A solver may require that the interval brackets a single zero root. 106dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * Solvers that do require bracketing should be able to handle the case 107dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * where one of the endpoints is itself a root.</p> 108dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * 109dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @param min the lower bound for the interval. 110dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @param max the upper bound for the interval. 111dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @param startValue the start value to use 112dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @return a value where the function is zero 113dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @throws ConvergenceException if the maximum iteration count is exceeded 114dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * or the solver detects convergence problems otherwise. 115dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @throws FunctionEvaluationException if an error occurs evaluating the function 116dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @throws IllegalArgumentException if min > max or the arguments do not 117dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * satisfy the requirements specified by the solver 118dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double, double)} 119dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * since 2.0 120dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond */ 121dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond @Deprecated 122dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond double solve(double min, double max, double startValue) 123dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond throws ConvergenceException, FunctionEvaluationException, IllegalArgumentException; 124dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond 125dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond /** 126dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * Solve for a zero in the given interval, start at startValue. 127dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * <p>A solver may require that the interval brackets a single zero root. 128dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * Solvers that do require bracketing should be able to handle the case 129dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * where one of the endpoints is itself a root.</p> 130dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * 131dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @param f the function to solve. 132dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @param min the lower bound for the interval. 133dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @param max the upper bound for the interval. 134dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @param startValue the start value to use 135dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @return a value where the function is zero 136dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @throws ConvergenceException if the maximum iteration count is exceeded 137dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * or the solver detects convergence problems otherwise. 138dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @throws FunctionEvaluationException if an error occurs evaluating the function 139dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @throws IllegalArgumentException if min > max or the arguments do not 140dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * satisfy the requirements specified by the solver 141dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @since 2.0 142dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @deprecated in 2.2 (to be removed in 3.0). 143dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond */ 144dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond @Deprecated 145dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond double solve(UnivariateRealFunction f, double min, double max, double startValue) 146dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond throws ConvergenceException, FunctionEvaluationException, IllegalArgumentException; 147dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond 148dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond /** 149dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * Get the result of the last run of the solver. 150dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * 151dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @return the last result. 152dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @throws IllegalStateException if there is no result available, either 153dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * because no result was yet computed or the last attempt failed. 154dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond */ 155dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond double getResult(); 156dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond 157dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond /** 158dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * Get the result of the last run of the solver. 159dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * 160dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @return the value of the function at the last result. 161dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * @throws IllegalStateException if there is no result available, either 162dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond * because no result was yet computed or the last attempt failed. 163dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond */ 164dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond double getFunctionValue(); 165dee0849a9704d532af0b550146cbafbaa6ee1d19Raymond} 166