KickJava   Java API By Example, From Geeks To Geeks.

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


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
17 package org.apache.commons.math.analysis;
18
19 import java.io.Serializable JavaDoc;
20
21 import org.apache.commons.math.FunctionEvaluationException;
22
23 /**
24  * Provide a default implementation for several functions useful to generic
25  * solvers.
26  *
27  * @version $Revision$ $Date: 2005-02-26 05:11:52 -0800 (Sat, 26 Feb 2005) $
28  */
29 public abstract class UnivariateRealSolverImpl implements UnivariateRealSolver,
30     Serializable JavaDoc {
31
32     /** Serializable version identifier */
33     static final long serialVersionUID = 1112491292565386596L;
34     
35     /** Maximum absolute error. */
36     protected double absoluteAccuracy;
37
38     /** Maximum relative error. */
39     protected double relativeAccuracy;
40
41     /** Maximum error of function. */
42     protected double functionValueAccuracy;
43
44     /** Maximum number of iterations. */
45     protected int maximalIterationCount;
46
47     /** Default maximum absolute error. */
48     protected double defaultAbsoluteAccuracy;
49
50     /** Default maximum relative error. */
51     protected double defaultRelativeAccuracy;
52
53     /** Default maximum error of function. */
54     protected double defaultFunctionValueAccuracy;
55
56     /** Default maximum number of iterations. */
57     protected int defaultMaximalIterationCount;
58
59     /** Indicates where a root has been computed. */
60     protected boolean resultComputed = false;
61
62     /** The last computed root. */
63     protected double result;
64
65     // Mainly for test framework.
66 /** The last iteration count. */
67     protected int iterationCount;
68
69     /** The function to solve. */
70     protected UnivariateRealFunction f;
71
72     /**
73      * Construct a solver with given iteration count and accuracy.
74      *
75      * @param f the function to solve.
76      * @param defaultAbsoluteAccuracy maximum absolute error
77      * @param defaultMaximalIterationCount maximum number of iterations
78      * @throws IllegalArgumentException if f is null or the
79      * defaultAbsoluteAccuracy is not valid
80      */
81     protected UnivariateRealSolverImpl(
82         UnivariateRealFunction f,
83         int defaultMaximalIterationCount,
84         double defaultAbsoluteAccuracy) {
85         
86         super();
87         
88         if (f == null) {
89             throw new IllegalArgumentException JavaDoc("function can not be null.");
90         }
91         
92         this.f = f;
93         this.defaultAbsoluteAccuracy = defaultAbsoluteAccuracy;
94         this.defaultRelativeAccuracy = 1E-14;
95         this.defaultFunctionValueAccuracy = 1E-15;
96         this.absoluteAccuracy = defaultAbsoluteAccuracy;
97         this.relativeAccuracy = defaultRelativeAccuracy;
98         this.functionValueAccuracy = defaultFunctionValueAccuracy;
99         this.defaultMaximalIterationCount = defaultMaximalIterationCount;
100         this.maximalIterationCount = defaultMaximalIterationCount;
101     }
102
103     /**
104      * Access the last computed root.
105      *
106      * @return the last computed root
107      * @throws IllegalStateException if no root has been computed
108      */
109     public double getResult() {
110         if (resultComputed) {
111             return result;
112         } else {
113             throw new IllegalStateException JavaDoc("No result available");
114         }
115     }
116
117     /**
118      * Access the last iteration count.
119      *
120      * @return the last iteration count
121      * @throws IllegalStateException if no root has been computed
122      *
123      */
124     public int getIterationCount() {
125         if (resultComputed) {
126             return iterationCount;
127         } else {
128             throw new IllegalStateException JavaDoc("No result available");
129         }
130     }
131
132     /**
133      * Convenience function for implementations.
134      *
135      * @param result the result to set
136      * @param iterationCount the iteration count to set
137      */
138     protected final void setResult(double result, int iterationCount) {
139         this.result = result;
140         this.iterationCount = iterationCount;
141         this.resultComputed = true;
142     }
143
144     /**
145      * Convenience function for implementations.
146      */
147     protected final void clearResult() {
148         this.resultComputed = false;
149     }
150
151     /**
152      * Set the absolute accuracy.
153      *
154      * @param accuracy the accuracy.
155      * @throws IllegalArgumentException if the accuracy can't be achieved by
156      * the solver or is otherwise deemed unreasonable.
157      */
158     public void setAbsoluteAccuracy(double accuracy) {
159         absoluteAccuracy = accuracy;
160     }
161
162     /**
163      * Get the actual absolute accuracy.
164      *
165      * @return the accuracy
166      */
167     public double getAbsoluteAccuracy() {
168         return absoluteAccuracy;
169     }
170
171     /**
172      * Reset the absolute accuracy to the default.
173      */
174     public void resetAbsoluteAccuracy() {
175         absoluteAccuracy = defaultAbsoluteAccuracy;
176     }
177
178     /**
179      * Set the upper limit for the number of iterations.
180      *
181      * @param count maximum number of iterations
182      */
183     public void setMaximalIterationCount(int count) {
184         maximalIterationCount = count;
185     }
186
187     /**
188      * Get the upper limit for the number of iterations.
189      *
190      * @return the actual upper limit
191      */
192     public int getMaximalIterationCount() {
193         return maximalIterationCount;
194     }
195
196     /**
197      * Reset the upper limit for the number of iterations to the default.
198      */
199     public void resetMaximalIterationCount() {
200         maximalIterationCount = defaultMaximalIterationCount;
201     }
202
203     /**
204      * Set the relative accuracy.
205      *
206      * @param accuracy the relative accuracy.
207      * @throws IllegalArgumentException if the accuracy can't be achieved by
208      * the solver or is otherwise deemed unreasonable.
209      */
210     public void setRelativeAccuracy(double accuracy) {
211         relativeAccuracy = accuracy;
212     }
213
214     /**
215      * Get the actual relative accuracy.
216      * @return the accuracy
217      */
218     public double getRelativeAccuracy() {
219         return relativeAccuracy;
220     }
221
222     /**
223      * Reset the relative accuracy to the default.
224      */
225     public void resetRelativeAccuracy() {
226         relativeAccuracy = defaultRelativeAccuracy;
227     }
228
229     /**
230      * Set the function value accuracy.
231      *
232      * @param accuracy the accuracy.
233      * @throws IllegalArgumentException if the accuracy can't be achieved by
234      * the solver or is otherwise deemed unreasonable.
235      */
236     public void setFunctionValueAccuracy(double accuracy) {
237         functionValueAccuracy = accuracy;
238     }
239
240     /**
241      * Get the actual function value accuracy.
242      * @return the accuracy
243      */
244     public double getFunctionValueAccuracy() {
245         return functionValueAccuracy;
246     }
247
248     /**
249      * Reset the actual function accuracy to the default.
250      */
251     public void resetFunctionValueAccuracy() {
252         functionValueAccuracy = defaultFunctionValueAccuracy;
253     }
254     
255     
256     /**
257      * Returns true iff the function takes opposite signs at the endpoints.
258      *
259      * @param lower the lower endpoint
260      * @param upper the upper endpoint
261      * @param f the function
262      * @return true if f(lower) * f(upper) < 0
263      * @throws FunctionEvaluationException if an error occurs evaluating the
264      * function at the endpoints
265      */
266     protected boolean isBracketing(double lower, double upper,
267             UnivariateRealFunction f) throws FunctionEvaluationException {
268         return (f.value(lower) * f.value(upper) < 0);
269     }
270     
271     /**
272      * Returns true if the arguments form a (strictly) increasing sequence
273      *
274      * @param start first number
275      * @param mid second number
276      * @param end third number
277      * @return true if the arguments form an increasing sequence
278      */
279     protected boolean isSequence(double start, double mid, double end) {
280         return (start < mid) && (mid < end);
281     }
282     
283     /**
284      * Verifies that the endpoints specify an interval,
285      * throws IllegalArgumentException if not
286      *
287      * @param lower lower endpoint
288      * @param upper upper endpoint
289      * @throws IllegalArgumentException
290      */
291     protected void verifyInterval(double lower, double upper) {
292         if (lower >= upper) {
293             throw new IllegalArgumentException JavaDoc
294                 ("Endpoints do not specify an interval: [" + lower +
295                         "," + upper + "]");
296         }
297     }
298     
299     /**
300      * Verifies that <code>lower < initial < upper</code>
301      * throws IllegalArgumentException if not
302      *
303      * @param lower lower endpoint
304      * @param initial initial value
305      * @param upper upper endpoint
306      * @throws IllegalArgumentException
307      */
308     protected void verifySequence(double lower, double initial, double upper) {
309         if (!isSequence(lower, initial, upper)) {
310             throw new IllegalArgumentException JavaDoc
311                 ("Invalid interval, initial value parameters: lower=" +
312                    lower + " initial=" + initial + " upper=" + upper);
313         }
314     }
315     
316     /**
317      * Verifies that the endpoints specify an interval and the function takes
318      * opposite signs at the enpoints, throws IllegalArgumentException if not
319      *
320      * @param lower lower endpoint
321      * @param upper upper endpoint
322      * @param f function
323      * @throws IllegalArgumentException
324      * @throws FunctionEvaluationException if an error occurs evaluating the
325      * function at the endpoints
326      */
327     protected void verifyBracketing(double lower, double upper,
328             UnivariateRealFunction f) throws FunctionEvaluationException {
329         
330         verifyInterval(lower, upper);
331         if (!isBracketing(lower, upper, f)) {
332             throw new IllegalArgumentException JavaDoc
333             ("Function values at endpoints do not have different signs." +
334                     " Endpoints: [" + lower + "," + upper + "]" +
335                     " Values: [" + f.value(lower) + "," + f.value(upper) + "]");
336         }
337     }
338 }
339
Popular Tags