001: /*
002: * Copyright 2003-2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.apache.commons.math.analysis;
017:
018: import org.apache.commons.math.ConvergenceException;
019: import org.apache.commons.math.FunctionEvaluationException;
020:
021: /**
022: * Interface for (univariate real) rootfinding algorithms.
023: * <p>
024: * Implementations will search for only one zero in the given interval.
025: *
026: * @version $Revision: 155427 $ $Date: 2005-02-26 06:11:52 -0700 (Sat, 26 Feb 2005) $
027: */
028: public interface UnivariateRealSolver {
029:
030: /**
031: * Set the upper limit for the number of iterations.
032: * <p>
033: * Usually a high iteration count indicates convergence problems. However,
034: * the "reasonable value" varies widely for different solvers. Users are
035: * advised to use the default value supplied by the solver.
036: * <p>
037: * A <code>ConvergenceException</code> will be thrown if this number
038: * is exceeded.
039: *
040: * @param count maximum number of iterations
041: */
042: void setMaximalIterationCount(int count);
043:
044: /**
045: * Get the upper limit for the number of iterations.
046: *
047: * @return the actual upper limit
048: */
049: int getMaximalIterationCount();
050:
051: /**
052: * Reset the upper limit for the number of iterations to the default.
053: * <p>
054: * The default value is supplied by the solver implementation.
055: *
056: * @see #setMaximalIterationCount(int)
057: */
058: void resetMaximalIterationCount();
059:
060: /**
061: * Set the absolute accuracy.
062: * <p>
063: * The default is usually choosen so that roots in the interval
064: * -10..-0.1 and +0.1..+10 can be found with a reasonable accuracy. If the
065: * expected absolute value of your roots is of much smaller magnitude, set
066: * this to a smaller value.
067: * <p>
068: * Solvers are advised to do a plausibility check with the relative
069: * accuracy, but clients should not rely on this.
070: *
071: * @param accuracy the accuracy.
072: * @throws IllegalArgumentException if the accuracy can't be achieved by
073: * the solver or is otherwise deemed unreasonable.
074: */
075: void setAbsoluteAccuracy(double accuracy);
076:
077: /**
078: * Get the actual absolute accuracy.
079: *
080: * @return the accuracy
081: */
082: double getAbsoluteAccuracy();
083:
084: /**
085: * Reset the absolute accuracy to the default.
086: * <p>
087: * The default value is provided by the solver implementation.
088: */
089: void resetAbsoluteAccuracy();
090:
091: /**
092: * Set the relative accuracy.
093: * <p>
094: * This is used to stop iterations if the absolute accuracy can't be
095: * achieved due to large values or short mantissa length.
096: * <p>
097: * If this should be the primary criterion for convergence rather then a
098: * safety measure, set the absolute accuracy to a ridiculously small value,
099: * like 1E-1000.
100: *
101: * @param accuracy the relative accuracy.
102: * @throws IllegalArgumentException if the accuracy can't be achieved by
103: * the solver or is otherwise deemed unreasonable.
104: */
105: void setRelativeAccuracy(double accuracy);
106:
107: /**
108: * Get the actual relative accuracy.
109: * @return the accuracy
110: */
111: double getRelativeAccuracy();
112:
113: /**
114: * Reset the relative accuracy to the default.
115: * The default value is provided by the solver implementation.
116: */
117: void resetRelativeAccuracy();
118:
119: /**
120: * Set the function value accuracy.
121: * <p>
122: * This is used to determine whan an evaluated function value or some other
123: * value which is used as divisor is zero.
124: * <p>
125: * This is a safety guard and it shouldn't be necesary to change this in
126: * general.
127: *
128: * @param accuracy the accuracy.
129: * @throws IllegalArgumentException if the accuracy can't be achieved by
130: * the solver or is otherwise deemed unreasonable.
131: */
132: void setFunctionValueAccuracy(double accuracy);
133:
134: /**
135: * Get the actual function value accuracy.
136: * @return the accuracy
137: */
138: double getFunctionValueAccuracy();
139:
140: /**
141: * Reset the actual function accuracy to the default.
142: * The default value is provided by the solver implementation.
143: */
144: void resetFunctionValueAccuracy();
145:
146: /**
147: * Solve for a zero root in the given interval.
148: * A solver may require that the interval brackets a single zero root.
149: *
150: * @param min the lower bound for the interval.
151: * @param max the upper bound for the interval.
152: * @return a value where the function is zero
153: * @throws ConvergenceException if the maximum iteration count is exceeded
154: * or the solver detects convergence problems otherwise.
155: * @throws FunctionEvaluationException if an error occurs evaluating the
156: * function
157: * @throws IllegalArgumentException if min > max or the endpoints do not
158: * satisfy the requirements specified by the solver
159: */
160: double solve(double min, double max) throws ConvergenceException,
161: FunctionEvaluationException;
162:
163: /**
164: * Solve for a zero in the given interval, start at startValue.
165: * A solver may require that the interval brackets a single zero root.
166: *
167: * @param min the lower bound for the interval.
168: * @param max the upper bound for the interval.
169: * @param startValue the start value to use
170: * @return a value where the function is zero
171: * @throws ConvergenceException if the maximum iteration count is exceeded
172: * or the solver detects convergence problems otherwise.
173: * @throws FunctionEvaluationException if an error occurs evaluating the
174: * function
175: * @throws IllegalArgumentException if min > max or the arguments do not
176: * satisfy the requirements specified by the solver
177: */
178: double solve(double min, double max, double startValue)
179: throws ConvergenceException, FunctionEvaluationException;
180:
181: /**
182: * Get the result of the last run of the solver.
183: *
184: * @return the last result.
185: * @throws IllegalStateException if there is no result available, either
186: * because no result was yet computed or the last attempt failed.
187: */
188: double getResult();
189:
190: /**
191: * Get the number of iterations in the last run of the solver.
192: * <p>
193: * This is mainly meant for testing purposes. It may occasionally
194: * help track down performance problems: if the iteration count
195: * is notoriously high, check whether the function is evaluated
196: * properly, and whether another solver is more amenable to the
197: * problem.
198: *
199: * @return the last iteration count.
200: * @throws IllegalStateException if there is no result available, either
201: * because no result was yet computed or the last attempt failed.
202: */
203: int getIterationCount();
204: }
|