View Javadoc

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 }