diff options
Diffstat (limited to 'src/main/java/org/apache/commons/math/analysis/solvers/UnivariateRealSolver.java')
| -rw-r--r-- | src/main/java/org/apache/commons/math/analysis/solvers/UnivariateRealSolver.java | 165 |
1 files changed, 165 insertions, 0 deletions
diff --git a/src/main/java/org/apache/commons/math/analysis/solvers/UnivariateRealSolver.java b/src/main/java/org/apache/commons/math/analysis/solvers/UnivariateRealSolver.java new file mode 100644 index 0000000..6540f67 --- /dev/null +++ b/src/main/java/org/apache/commons/math/analysis/solvers/UnivariateRealSolver.java @@ -0,0 +1,165 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.commons.math.analysis.solvers; + +import org.apache.commons.math.ConvergenceException; +import org.apache.commons.math.ConvergingAlgorithm; +import org.apache.commons.math.FunctionEvaluationException; +import org.apache.commons.math.analysis.UnivariateRealFunction; + + +/** + * Interface for (univariate real) rootfinding algorithms. + * <p> + * Implementations will search for only one zero in the given interval.</p> + * + * @version $Revision: 1070725 $ $Date: 2011-02-15 02:31:12 +0100 (mar. 15 févr. 2011) $ + */ +public interface UnivariateRealSolver extends ConvergingAlgorithm { + + /** + * Set the function value accuracy. + * <p> + * This is used to determine when an evaluated function value or some other + * value which is used as divisor is zero.</p> + * <p> + * This is a safety guard and it shouldn't be necessary to change this in + * general.</p> + * + * @param accuracy the accuracy. + * @throws IllegalArgumentException if the accuracy can't be achieved by + * the solver or is otherwise deemed unreasonable. + */ + void setFunctionValueAccuracy(double accuracy); + + /** + * Get the actual function value accuracy. + * @return the accuracy + */ + double getFunctionValueAccuracy(); + + /** + * Reset the actual function accuracy to the default. + * The default value is provided by the solver implementation. + */ + void resetFunctionValueAccuracy(); + + /** + * Solve for a zero root in the given interval. + * <p>A solver may require that the interval brackets a single zero root. + * Solvers that do require bracketing should be able to handle the case + * where one of the endpoints is itself a root.</p> + * + * @param min the lower bound for the interval. + * @param max the upper bound for the interval. + * @return a value where the function is zero + * @throws ConvergenceException if the maximum iteration count is exceeded + * or the solver detects convergence problems otherwise. + * @throws FunctionEvaluationException if an error occurs evaluating the function + * @throws IllegalArgumentException if min > max or the endpoints do not + * satisfy the requirements specified by the solver + * @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double)} + * since 2.0 + */ + @Deprecated + double solve(double min, double max) throws ConvergenceException, FunctionEvaluationException; + + /** + * Solve for a zero root in the given interval. + * <p>A solver may require that the interval brackets a single zero root. + * Solvers that do require bracketing should be able to handle the case + * where one of the endpoints is itself a root.</p> + * + * @param f the function to solve. + * @param min the lower bound for the interval. + * @param max the upper bound for the interval. + * @return a value where the function is zero + * @throws ConvergenceException if the maximum iteration count is exceeded + * or the solver detects convergence problems otherwise. + * @throws FunctionEvaluationException if an error occurs evaluating the function + * @throws IllegalArgumentException if min > max or the endpoints do not + * satisfy the requirements specified by the solver + * @since 2.0 + * @deprecated in 2.2 (to be removed in 3.0). + */ + @Deprecated + double solve(UnivariateRealFunction f, double min, double max) + throws ConvergenceException, FunctionEvaluationException; + + /** + * Solve for a zero in the given interval, start at startValue. + * <p>A solver may require that the interval brackets a single zero root. + * Solvers that do require bracketing should be able to handle the case + * where one of the endpoints is itself a root.</p> + * + * @param min the lower bound for the interval. + * @param max the upper bound for the interval. + * @param startValue the start value to use + * @return a value where the function is zero + * @throws ConvergenceException if the maximum iteration count is exceeded + * or the solver detects convergence problems otherwise. + * @throws FunctionEvaluationException if an error occurs evaluating the function + * @throws IllegalArgumentException if min > max or the arguments do not + * satisfy the requirements specified by the solver + * @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double, double)} + * since 2.0 + */ + @Deprecated + double solve(double min, double max, double startValue) + throws ConvergenceException, FunctionEvaluationException, IllegalArgumentException; + + /** + * Solve for a zero in the given interval, start at startValue. + * <p>A solver may require that the interval brackets a single zero root. + * Solvers that do require bracketing should be able to handle the case + * where one of the endpoints is itself a root.</p> + * + * @param f the function to solve. + * @param min the lower bound for the interval. + * @param max the upper bound for the interval. + * @param startValue the start value to use + * @return a value where the function is zero + * @throws ConvergenceException if the maximum iteration count is exceeded + * or the solver detects convergence problems otherwise. + * @throws FunctionEvaluationException if an error occurs evaluating the function + * @throws IllegalArgumentException if min > max or the arguments do not + * satisfy the requirements specified by the solver + * @since 2.0 + * @deprecated in 2.2 (to be removed in 3.0). + */ + @Deprecated + double solve(UnivariateRealFunction f, double min, double max, double startValue) + throws ConvergenceException, FunctionEvaluationException, IllegalArgumentException; + + /** + * Get the result of the last run of the solver. + * + * @return the last result. + * @throws IllegalStateException if there is no result available, either + * because no result was yet computed or the last attempt failed. + */ + double getResult(); + + /** + * Get the result of the last run of the solver. + * + * @return the value of the function at the last result. + * @throws IllegalStateException if there is no result available, either + * because no result was yet computed or the last attempt failed. + */ + double getFunctionValue(); +} |