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: 811685 $ $Date: 2009-09-05 13:36:48 -0400 (Sat, 05 Sep 2009) $ 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 073 * function 074 * @throws IllegalArgumentException if min > max or the endpoints do not 075 * satisfy the requirements specified by the solver 076 * @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double)} 077 * since 2.0 078 */ 079 @Deprecated 080 double solve(double min, double max) throws ConvergenceException, 081 FunctionEvaluationException; 082 083 /** 084 * Solve for a zero root in the given interval. 085 * <p>A solver may require that the interval brackets a single zero root. 086 * Solvers that do require bracketing should be able to handle the case 087 * where one of the endpoints is itself a root.</p> 088 * 089 * @param f the function to solve. 090 * @param min the lower bound for the interval. 091 * @param max the upper bound for the interval. 092 * @return a value where the function is zero 093 * @throws ConvergenceException if the maximum iteration count is exceeded 094 * or the solver detects convergence problems otherwise. 095 * @throws FunctionEvaluationException if an error occurs evaluating the 096 * function 097 * @throws IllegalArgumentException if min > max or the endpoints do not 098 * satisfy the requirements specified by the solver 099 * @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 }