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.integration;
18
19 import org.apache.commons.math.ConvergenceException;
20 import org.apache.commons.math.ConvergingAlgorithm;
21 import org.apache.commons.math.FunctionEvaluationException;
22 import org.apache.commons.math.analysis.UnivariateRealFunction;
23
24 /**
25 * Interface for univariate real integration algorithms.
26 *
27 * @version $Revision: 799857 $ $Date: 2009-08-01 09:07:12 -0400 (Sat, 01 Aug 2009) $
28 * @since 1.2
29 */
30 public interface UnivariateRealIntegrator extends ConvergingAlgorithm {
31
32 /**
33 * Set the lower limit for the number of iterations.
34 * <p>
35 * Minimal iteration is needed to avoid false early convergence, e.g.
36 * the sample points happen to be zeroes of the function. Users can
37 * use the default value or choose one that they see as appropriate.</p>
38 * <p>
39 * A <code>ConvergenceException</code> will be thrown if this number
40 * is not met.</p>
41 *
42 * @param count minimum number of iterations
43 */
44 void setMinimalIterationCount(int count);
45
46 /**
47 * Get the lower limit for the number of iterations.
48 *
49 * @return the actual lower limit
50 */
51 int getMinimalIterationCount();
52
53 /**
54 * Reset the lower limit for the number of iterations to the default.
55 * <p>
56 * The default value is supplied by the implementation.</p>
57 *
58 * @see #setMinimalIterationCount(int)
59 */
60 void resetMinimalIterationCount();
61
62 /**
63 * Integrate the function in the given interval.
64 *
65 * @param min the lower bound for the interval
66 * @param max the upper bound for the interval
67 * @return the value of integral
68 * @throws ConvergenceException if the maximum iteration count is exceeded
69 * or the integrator detects convergence problems otherwise
70 * @throws FunctionEvaluationException if an error occurs evaluating the
71 * function
72 * @throws IllegalArgumentException if min > max or the endpoints do not
73 * satisfy the requirements specified by the integrator
74 * @deprecated replaced by {@link #integrate(UnivariateRealFunction, double, double)}
75 * since 2.0
76 */
77 @Deprecated
78 double integrate(double min, double max) throws ConvergenceException,
79 FunctionEvaluationException, IllegalArgumentException;
80
81 /**
82 * Integrate the function in the given interval.
83 *
84 * @param f the integrand function
85 * @param min the lower bound for the interval
86 * @param max the upper bound for the interval
87 * @return the value of integral
88 * @throws ConvergenceException if the maximum iteration count is exceeded
89 * or the integrator detects convergence problems otherwise
90 * @throws FunctionEvaluationException if an error occurs evaluating the
91 * function
92 * @throws IllegalArgumentException if min > max or the endpoints do not
93 * satisfy the requirements specified by the integrator
94 */
95 double integrate(UnivariateRealFunction f, double min, double max) throws ConvergenceException,
96 FunctionEvaluationException, IllegalArgumentException;
97
98 /**
99 * Get the result of the last run of the integrator.
100 *
101 * @return the last result
102 * @throws IllegalStateException if there is no result available, either
103 * because no result was yet computed or the last attempt failed
104 */
105 double getResult() throws IllegalStateException;
106
107 }