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 }