001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017 package org.apache.commons.math.analysis.solvers; 018 019 import org.apache.commons.math.ConvergenceException; 020 import org.apache.commons.math.ConvergingAlgorithm; 021 import org.apache.commons.math.FunctionEvaluationException; 022 import org.apache.commons.math.analysis.UnivariateRealFunction; 023 024 025 /** 026 * Interface for (univariate real) rootfinding algorithms. 027 * <p> 028 * Implementations will search for only one zero in the given interval.</p> 029 * 030 * @version $Revision: 1070725 $ $Date: 2011-02-15 02:31:12 +0100 (mar. 15 f??vr. 2011) $ 031 */ 032 public interface UnivariateRealSolver extends ConvergingAlgorithm { 033 034 /** 035 * Set the function value accuracy. 036 * <p> 037 * This is used to determine when an evaluated function value or some other 038 * value which is used as divisor is zero.</p> 039 * <p> 040 * This is a safety guard and it shouldn't be necessary to change this in 041 * general.</p> 042 * 043 * @param accuracy the accuracy. 044 * @throws IllegalArgumentException if the accuracy can't be achieved by 045 * the solver or is otherwise deemed unreasonable. 046 */ 047 void setFunctionValueAccuracy(double accuracy); 048 049 /** 050 * Get the actual function value accuracy. 051 * @return the accuracy 052 */ 053 double getFunctionValueAccuracy(); 054 055 /** 056 * Reset the actual function accuracy to the default. 057 * The default value is provided by the solver implementation. 058 */ 059 void resetFunctionValueAccuracy(); 060 061 /** 062 * Solve for a zero root in the given interval. 063 * <p>A solver may require that the interval brackets a single zero root. 064 * Solvers that do require bracketing should be able to handle the case 065 * where one of the endpoints is itself a root.</p> 066 * 067 * @param min the lower bound for the interval. 068 * @param max the upper bound for the interval. 069 * @return a value where the function is zero 070 * @throws ConvergenceException if the maximum iteration count is exceeded 071 * or the solver detects convergence problems otherwise. 072 * @throws FunctionEvaluationException if an error occurs evaluating the function 073 * @throws IllegalArgumentException if min > max or the endpoints do not 074 * satisfy the requirements specified by the solver 075 * @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double)} 076 * since 2.0 077 */ 078 @Deprecated 079 double solve(double min, double max) throws ConvergenceException, FunctionEvaluationException; 080 081 /** 082 * Solve for a zero root in the given interval. 083 * <p>A solver may require that the interval brackets a single zero root. 084 * Solvers that do require bracketing should be able to handle the case 085 * where one of the endpoints is itself a root.</p> 086 * 087 * @param f the function to solve. 088 * @param min the lower bound for the interval. 089 * @param max the upper bound for the interval. 090 * @return a value where the function is zero 091 * @throws ConvergenceException if the maximum iteration count is exceeded 092 * or the solver detects convergence problems otherwise. 093 * @throws FunctionEvaluationException if an error occurs evaluating the function 094 * @throws IllegalArgumentException if min > max or the endpoints do not 095 * satisfy the requirements specified by the solver 096 * @since 2.0 097 * @deprecated in 2.2 (to be removed in 3.0). 098 */ 099 @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 }