1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.math.analysis;
18
19 import org.apache.commons.math.ConvergenceException;
20 import org.apache.commons.math.FunctionEvaluationException;
21
22 /**
23 * Interface for univariate real integration algorithms.
24 *
25 * @version $Revision: 620312 $ $Date: 2008-02-10 12:28:59 -0700 (Sun, 10 Feb 2008) $
26 * @since 1.2
27 */
28 public interface UnivariateRealIntegrator {
29
30 /**
31 * Set the upper limit for the number of iterations.
32 * <p>
33 * Usually a high iteration count indicates convergence problem. However,
34 * the "reasonable value" varies widely for different cases. Users are
35 * advised to use the default value.</p>
36 * <p>
37 * A <code>ConvergenceException</code> will be thrown if this number
38 * is exceeded.</p>
39 *
40 * @param count maximum number of iterations
41 */
42 void setMaximalIterationCount(int count);
43
44 /**
45 * Get the upper limit for the number of iterations.
46 *
47 * @return the actual upper limit
48 */
49 int getMaximalIterationCount();
50
51 /**
52 * Reset the upper limit for the number of iterations to the default.
53 * <p>
54 * The default value is supplied by the implementation.</p>
55 *
56 * @see #setMaximalIterationCount(int)
57 */
58 void resetMaximalIterationCount();
59
60 /**
61 * Set the lower limit for the number of iterations.
62 * <p>
63 * Minimal iteration is needed to avoid false early convergence, e.g.
64 * the sample points happen to be zeroes of the function. Users can
65 * use the default value or choose one that they see as appropriate.</p>
66 * <p>
67 * A <code>ConvergenceException</code> will be thrown if this number
68 * is not met.</p>
69 *
70 * @param count minimum number of iterations
71 */
72 void setMinimalIterationCount(int count);
73
74 /**
75 * Get the lower limit for the number of iterations.
76 *
77 * @return the actual lower limit
78 */
79 int getMinimalIterationCount();
80
81 /**
82 * Reset the lower limit for the number of iterations to the default.
83 * <p>
84 * The default value is supplied by the implementation.</p>
85 *
86 * @see #setMinimalIterationCount(int)
87 */
88 void resetMinimalIterationCount();
89
90 /**
91 * Set the relative accuracy.
92 * <p>
93 * This is used to stop iterations.</p>
94 *
95 * @param accuracy the relative accuracy
96 * @throws IllegalArgumentException if the accuracy can't be achieved
97 * or is otherwise deemed unreasonable
98 */
99 void setRelativeAccuracy(double accuracy);
100
101 /**
102 * Get the actual relative accuracy.
103 *
104 * @return the accuracy
105 */
106 double getRelativeAccuracy();
107
108 /**
109 * Reset the relative accuracy to the default.
110 * <p>
111 * The default value is provided by the implementation.</p>
112 *
113 * @see #setRelativeAccuracy(double)
114 */
115 void resetRelativeAccuracy();
116
117 /**
118 * Integrate the function in the given interval.
119 *
120 * @param min the lower bound for the interval
121 * @param max the upper bound for the interval
122 * @return the value of integral
123 * @throws ConvergenceException if the maximum iteration count is exceeded
124 * or the integrator detects convergence problems otherwise
125 * @throws FunctionEvaluationException if an error occurs evaluating the
126 * function
127 * @throws IllegalArgumentException if min > max or the endpoints do not
128 * satisfy the requirements specified by the integrator
129 */
130 double integrate(double min, double max) throws ConvergenceException,
131 FunctionEvaluationException, IllegalArgumentException;
132
133 /**
134 * Get the result of the last run of the integrator.
135 *
136 * @return the last result
137 * @throws IllegalStateException if there is no result available, either
138 * because no result was yet computed or the last attempt failed
139 */
140 double getResult() throws IllegalStateException;
141
142 /**
143 * Get the number of iterations in the last run of the integrator.
144 * <p>
145 * This is mainly meant for testing purposes. It may occasionally
146 * help track down performance problems: if the iteration count
147 * is notoriously high, check whether the function is evaluated
148 * properly, and whether another integrator is more amenable to the
149 * problem.</p>
150 *
151 * @return the last iteration count
152 * @throws IllegalStateException if there is no result available, either
153 * because no result was yet computed or the last attempt failed
154 */
155 int getIterationCount() throws IllegalStateException;
156 }