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: 799857 $ $Date: 2009-08-01 09:07:12 -0400 (Sat, 01 Aug 2009) $
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 */
47 void setFunctionValueAccuracy(double accuracy);
48
49 /**
50 * Get the actual function value accuracy.
51 * @return the accuracy
52 */
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 */
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
73 * function
74 * @throws IllegalArgumentException if min > max or the endpoints do not
75 * satisfy the requirements specified by the solver
76 * @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double)}
77 * since 2.0
78 */
79 @Deprecated
80 double solve(double min, double max) throws ConvergenceException,
81 FunctionEvaluationException;
82
83 /**
84 * Solve for a zero root in the given interval.
85 * <p>A solver may require that the interval brackets a single zero root.
86 * Solvers that do require bracketing should be able to handle the case
87 * where one of the endpoints is itself a root.</p>
88 *
89 * @param f the function to solve.
90 * @param min the lower bound for the interval.
91 * @param max the upper bound for the interval.
92 * @return a value where the function is zero
93 * @throws ConvergenceException if the maximum iteration count is exceeded
94 * or the solver detects convergence problems otherwise.
95 * @throws FunctionEvaluationException if an error occurs evaluating the
96 * function
97 * @throws IllegalArgumentException if min > max or the endpoints do not
98 * satisfy the requirements specified by the solver
99 * @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 }