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 }