001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.math.analysis.integration;
018
019 import org.apache.commons.math.ConvergenceException;
020 import org.apache.commons.math.ConvergingAlgorithm;
021 import org.apache.commons.math.FunctionEvaluationException;
022 import org.apache.commons.math.analysis.UnivariateRealFunction;
023
024 /**
025 * Interface for univariate real integration algorithms.
026 *
027 * @version $Revision: 811685 $ $Date: 2009-09-05 13:36:48 -0400 (Sat, 05 Sep 2009) $
028 * @since 1.2
029 */
030 public interface UnivariateRealIntegrator extends ConvergingAlgorithm {
031
032 /**
033 * Set the lower limit for the number of iterations.
034 * <p>
035 * Minimal iteration is needed to avoid false early convergence, e.g.
036 * the sample points happen to be zeroes of the function. Users can
037 * use the default value or choose one that they see as appropriate.</p>
038 * <p>
039 * A <code>ConvergenceException</code> will be thrown if this number
040 * is not met.</p>
041 *
042 * @param count minimum number of iterations
043 */
044 void setMinimalIterationCount(int count);
045
046 /**
047 * Get the lower limit for the number of iterations.
048 *
049 * @return the actual lower limit
050 */
051 int getMinimalIterationCount();
052
053 /**
054 * Reset the lower limit for the number of iterations to the default.
055 * <p>
056 * The default value is supplied by the implementation.</p>
057 *
058 * @see #setMinimalIterationCount(int)
059 */
060 void resetMinimalIterationCount();
061
062 /**
063 * Integrate the function in the given interval.
064 *
065 * @param min the lower bound for the interval
066 * @param max the upper bound for the interval
067 * @return the value of integral
068 * @throws ConvergenceException if the maximum iteration count is exceeded
069 * or the integrator detects convergence problems otherwise
070 * @throws FunctionEvaluationException if an error occurs evaluating the
071 * function
072 * @throws IllegalArgumentException if min > max or the endpoints do not
073 * satisfy the requirements specified by the integrator
074 * @deprecated replaced by {@link #integrate(UnivariateRealFunction, double, double)}
075 * since 2.0
076 */
077 @Deprecated
078 double integrate(double min, double max) throws ConvergenceException,
079 FunctionEvaluationException, IllegalArgumentException;
080
081 /**
082 * Integrate the function in the given interval.
083 *
084 * @param f the integrand function
085 * @param min the lower bound for the interval
086 * @param max the upper bound for the interval
087 * @return the value of integral
088 * @throws ConvergenceException if the maximum iteration count is exceeded
089 * or the integrator detects convergence problems otherwise
090 * @throws FunctionEvaluationException if an error occurs evaluating the
091 * function
092 * @throws IllegalArgumentException if min > max or the endpoints do not
093 * satisfy the requirements specified by the integrator
094 */
095 double integrate(UnivariateRealFunction f, double min, double max) throws ConvergenceException,
096 FunctionEvaluationException, IllegalArgumentException;
097
098 /**
099 * 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 }