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 }