KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > math > analysis > UnivariateRealSolver


1 /*
2  * Copyright 2003-2004 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.apache.commons.math.analysis;
17
18 import org.apache.commons.math.ConvergenceException;
19 import org.apache.commons.math.FunctionEvaluationException;
20
21
22 /**
23  * Interface for (univariate real) rootfinding algorithms.
24  * <p>
25  * Implementations will search for only one zero in the given interval.
26  *
27  * @version $Revision$ $Date: 2005-02-26 05:11:52 -0800 (Sat, 26 Feb 2005) $
28  */
29 public interface UnivariateRealSolver {
30
31     /**
32      * Set the upper limit for the number of iterations.
33      * <p>
34      * Usually a high iteration count indicates convergence problems. However,
35      * the "reasonable value" varies widely for different solvers. Users are
36      * advised to use the default value supplied by the solver.
37      * <p>
38      * A <code>ConvergenceException</code> will be thrown if this number
39      * is exceeded.
40      *
41      * @param count maximum number of iterations
42      */
43     void setMaximalIterationCount(int count);
44
45     /**
46      * Get the upper limit for the number of iterations.
47      *
48      * @return the actual upper limit
49      */
50     int getMaximalIterationCount();
51
52     /**
53      * Reset the upper limit for the number of iterations to the default.
54      * <p>
55      * The default value is supplied by the solver implementation.
56      *
57      * @see #setMaximalIterationCount(int)
58      */
59     void resetMaximalIterationCount();
60
61     /**
62      * Set the absolute accuracy.
63      * <p>
64      * The default is usually choosen so that roots in the interval
65      * -10..-0.1 and +0.1..+10 can be found with a reasonable accuracy. If the
66      * expected absolute value of your roots is of much smaller magnitude, set
67      * this to a smaller value.
68      * <p>
69      * Solvers are advised to do a plausibility check with the relative
70      * accuracy, but clients should not rely on this.
71      *
72      * @param accuracy the accuracy.
73      * @throws IllegalArgumentException if the accuracy can't be achieved by
74      * the solver or is otherwise deemed unreasonable.
75      */
76     void setAbsoluteAccuracy(double accuracy);
77
78     /**
79      * Get the actual absolute accuracy.
80      *
81      * @return the accuracy
82      */
83     double getAbsoluteAccuracy();
84
85     /**
86      * Reset the absolute accuracy to the default.
87      * <p>
88      * The default value is provided by the solver implementation.
89      */
90     void resetAbsoluteAccuracy();
91
92     /**
93      * Set the relative accuracy.
94      * <p>
95      * This is used to stop iterations if the absolute accuracy can't be
96      * achieved due to large values or short mantissa length.
97      * <p>
98      * If this should be the primary criterion for convergence rather then a
99      * safety measure, set the absolute accuracy to a ridiculously small value,
100      * like 1E-1000.
101      *
102      * @param accuracy the relative accuracy.
103      * @throws IllegalArgumentException if the accuracy can't be achieved by
104      * the solver or is otherwise deemed unreasonable.
105      */
106     void setRelativeAccuracy(double accuracy);
107
108     /**
109      * Get the actual relative accuracy.
110      * @return the accuracy
111      */
112     double getRelativeAccuracy();
113
114     /**
115      * Reset the relative accuracy to the default.
116      * The default value is provided by the solver implementation.
117      */
118     void resetRelativeAccuracy();
119
120     /**
121      * Set the function value accuracy.
122      * <p>
123      * This is used to determine whan an evaluated function value or some other
124      * value which is used as divisor is zero.
125      * <p>
126      * This is a safety guard and it shouldn't be necesary to change this in
127      * general.
128      *
129      * @param accuracy the accuracy.
130      * @throws IllegalArgumentException if the accuracy can't be achieved by
131      * the solver or is otherwise deemed unreasonable.
132      */
133     void setFunctionValueAccuracy(double accuracy);
134
135     /**
136      * Get the actual function value accuracy.
137      * @return the accuracy
138      */
139     double getFunctionValueAccuracy();
140
141     /**
142      * Reset the actual function accuracy to the default.
143      * The default value is provided by the solver implementation.
144      */
145     void resetFunctionValueAccuracy();
146
147     /**
148      * Solve for a zero root in the given interval.
149      * A solver may require that the interval brackets a single zero root.
150      *
151      * @param min the lower bound for the interval.
152      * @param max the upper bound for the interval.
153      * @return a value where the function is zero
154      * @throws ConvergenceException if the maximum iteration count is exceeded
155      * or the solver detects convergence problems otherwise.
156      * @throws FunctionEvaluationException if an error occurs evaluating the
157      * function
158      * @throws IllegalArgumentException if min > max or the endpoints do not
159      * satisfy the requirements specified by the solver
160      */
161     double solve(double min, double max) throws ConvergenceException,
162         FunctionEvaluationException;
163
164     /**
165      * Solve for a zero in the given interval, start at startValue.
166      * A solver may require that the interval brackets a single zero root.
167      *
168      * @param min the lower bound for the interval.
169      * @param max the upper bound for the interval.
170      * @param startValue the start value to use
171      * @return a value where the function is zero
172      * @throws ConvergenceException if the maximum iteration count is exceeded
173      * or the solver detects convergence problems otherwise.
174      * @throws FunctionEvaluationException if an error occurs evaluating the
175      * function
176      * @throws IllegalArgumentException if min > max or the arguments do not
177      * satisfy the requirements specified by the solver
178      */
179     double solve(double min, double max, double startValue)
180         throws ConvergenceException, FunctionEvaluationException;
181
182     /**
183      * Get the result of the last run of the solver.
184      *
185      * @return the last result.
186      * @throws IllegalStateException if there is no result available, either
187      * because no result was yet computed or the last attempt failed.
188      */
189     double getResult();
190
191     /**
192      * Get the number of iterations in the last run of the solver.
193      * <p>
194      * This is mainly meant for testing purposes. It may occasionally
195      * help track down performance problems: if the iteration count
196      * is notoriously high, check whether the function is evaluated
197      * properly, and whether another solver is more amenable to the
198      * problem.
199      *
200      * @return the last iteration count.
201      * @throws IllegalStateException if there is no result available, either
202      * because no result was yet computed or the last attempt failed.
203      */
204     int getIterationCount();
205 }
Popular Tags