View Javadoc

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: 155427 $ $Date: 2005-02-26 06:11:52 -0700 (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 }