Coverage Report - org.apache.commons.math.analysis.UnivariateRealSolver

Classes in this File	Line Coverage	Branch Coverage	Complexity
UnivariateRealSolver	N/A	N/A	1.0;1

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		}