1 /*
2  * Licensed to the Apache Software Foundation (ASF) under one or more
3  * contributor license agreements.  See the NOTICE file distributed with
4  * this work for additional information regarding copyright ownership.
5  * The ASF licenses this file to You under the Apache License, Version 2.0
6  * (the "License"); you may not use this file except in compliance with
7  * the License.  You may obtain a copy of the License at
8  *
9  *      http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 package org.apache.commons.math.analysis.solvers;
18 
19 import org.apache.commons.math.ConvergenceException;
20 import org.apache.commons.math.ConvergingAlgorithm;
21 import org.apache.commons.math.FunctionEvaluationException;
22 import org.apache.commons.math.analysis.UnivariateRealFunction;
23 
24 
25 /**
26  * Interface for (univariate real) rootfinding algorithms.
27  * <p>
28  * Implementations will search for only one zero in the given interval.</p>
29  *
30  * @version $Revision: 1070725 $ $Date: 2011-02-15 02:31:12 +0100 (mar. 15 févr. 2011) $
31  */
32 public interface UnivariateRealSolver extends ConvergingAlgorithm {
33 
34     /**
35      * Set the function value accuracy.
36      * <p>
37      * This is used to determine when an evaluated function value or some other
38      * value which is used as divisor is zero.</p>
39      * <p>
40      * This is a safety guard and it shouldn't be necessary to change this in
41      * general.</p>
42      *
43      * @param accuracy the accuracy.
44      * @throws IllegalArgumentException if the accuracy can't be achieved by
45      * the solver or is otherwise deemed unreasonable.
46      */
setFunctionValueAccuracy(double accuracy)47     void setFunctionValueAccuracy(double accuracy);
48 
49     /**
50      * Get the actual function value accuracy.
51      * @return the accuracy
52      */
getFunctionValueAccuracy()53     double getFunctionValueAccuracy();
54 
55     /**
56      * Reset the actual function accuracy to the default.
57      * The default value is provided by the solver implementation.
58      */
resetFunctionValueAccuracy()59     void resetFunctionValueAccuracy();
60 
61     /**
62      * Solve for a zero root in the given interval.
63      * <p>A solver may require that the interval brackets a single zero root.
64      * Solvers that do require bracketing should be able to handle the case
65      * where one of the endpoints is itself a root.</p>
66      *
67      * @param min the lower bound for the interval.
68      * @param max the upper bound for the interval.
69      * @return a value where the function is zero
70      * @throws ConvergenceException if the maximum iteration count is exceeded
71      * or the solver detects convergence problems otherwise.
72      * @throws FunctionEvaluationException if an error occurs evaluating the function
73      * @throws IllegalArgumentException if min > max or the endpoints do not
74      * satisfy the requirements specified by the solver
75      * @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double)}
76      * since 2.0
77      */
78     @Deprecated
solve(double min, double max)79     double solve(double min, double max) throws ConvergenceException, FunctionEvaluationException;
80 
81     /**
82      * Solve for a zero root in the given interval.
83      * <p>A solver may require that the interval brackets a single zero root.
84      * Solvers that do require bracketing should be able to handle the case
85      * where one of the endpoints is itself a root.</p>
86      *
87      * @param f the function to solve.
88      * @param min the lower bound for the interval.
89      * @param max the upper bound for the interval.
90      * @return a value where the function is zero
91      * @throws ConvergenceException if the maximum iteration count is exceeded
92      * or the solver detects convergence problems otherwise.
93      * @throws FunctionEvaluationException if an error occurs evaluating the function
94      * @throws IllegalArgumentException if min > max or the endpoints do not
95      * satisfy the requirements specified by the solver
96      * @since 2.0
97      * @deprecated in 2.2 (to be removed in 3.0).
98      */
99     @Deprecated
solve(UnivariateRealFunction f, double min, double max)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
solve(double min, double max, double startValue)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
solve(UnivariateRealFunction f, double min, double max, double startValue)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      */
getResult()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      */
getFunctionValue()164     double getFunctionValue();
165 }
166