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.solvers;
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    /**
026     * Interface for (univariate real) rootfinding algorithms.
027     * <p>
028     * Implementations will search for only one zero in the given interval.</p>
029     *
030     * @version $Revision: 1070725 $ $Date: 2011-02-15 02:31:12 +0100 (mar. 15 f??vr. 2011) $
031     */
032    public interface UnivariateRealSolver extends ConvergingAlgorithm {
033    
034        /**
035         * Set the function value accuracy.
036         * <p>
037         * This is used to determine when an evaluated function value or some other
038         * value which is used as divisor is zero.</p>
039         * <p>
040         * This is a safety guard and it shouldn't be necessary to change this in
041         * general.</p>
042         *
043         * @param accuracy the accuracy.
044         * @throws IllegalArgumentException if the accuracy can't be achieved by
045         * the solver or is otherwise deemed unreasonable.
046         */
047        void setFunctionValueAccuracy(double accuracy);
048    
049        /**
050         * Get the actual function value accuracy.
051         * @return the accuracy
052         */
053        double getFunctionValueAccuracy();
054    
055        /**
056         * Reset the actual function accuracy to the default.
057         * The default value is provided by the solver implementation.
058         */
059        void resetFunctionValueAccuracy();
060    
061        /**
062         * Solve for a zero root in the given interval.
063         * <p>A solver may require that the interval brackets a single zero root.
064         * Solvers that do require bracketing should be able to handle the case
065         * where one of the endpoints is itself a root.</p>
066         *
067         * @param min the lower bound for the interval.
068         * @param max the upper bound for the interval.
069         * @return a value where the function is zero
070         * @throws ConvergenceException if the maximum iteration count is exceeded
071         * or the solver detects convergence problems otherwise.
072         * @throws FunctionEvaluationException if an error occurs evaluating the function
073         * @throws IllegalArgumentException if min > max or the endpoints do not
074         * satisfy the requirements specified by the solver
075         * @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double)}
076         * since 2.0
077         */
078        @Deprecated
079        double solve(double min, double max) throws ConvergenceException, FunctionEvaluationException;
080    
081        /**
082         * Solve for a zero root in the given interval.
083         * <p>A solver may require that the interval brackets a single zero root.
084         * Solvers that do require bracketing should be able to handle the case
085         * where one of the endpoints is itself a root.</p>
086         *
087         * @param f the function to solve.
088         * @param min the lower bound for the interval.
089         * @param max the upper bound for the interval.
090         * @return a value where the function is zero
091         * @throws ConvergenceException if the maximum iteration count is exceeded
092         * or the solver detects convergence problems otherwise.
093         * @throws FunctionEvaluationException if an error occurs evaluating the function
094         * @throws IllegalArgumentException if min > max or the endpoints do not
095         * satisfy the requirements specified by the solver
096         * @since 2.0
097         * @deprecated in 2.2 (to be removed in 3.0).
098         */
099        @Deprecated
100        double solve(UnivariateRealFunction f, double min, double max)
101            throws ConvergenceException, FunctionEvaluationException;
102    
103        /**
104         * Solve for a zero in the given interval, start at startValue.
105         * <p>A solver may require that the interval brackets a single zero root.
106         * Solvers that do require bracketing should be able to handle the case
107         * where one of the endpoints is itself a root.</p>
108         *
109         * @param min the lower bound for the interval.
110         * @param max the upper bound for the interval.
111         * @param startValue the start value to use
112         * @return a value where the function is zero
113         * @throws ConvergenceException if the maximum iteration count is exceeded
114         * or the solver detects convergence problems otherwise.
115         * @throws FunctionEvaluationException if an error occurs evaluating the function
116         * @throws IllegalArgumentException if min > max or the arguments do not
117         * satisfy the requirements specified by the solver
118         * @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double, double)}
119         * since 2.0
120         */
121        @Deprecated
122        double solve(double min, double max, double startValue)
123            throws ConvergenceException, FunctionEvaluationException, IllegalArgumentException;
124    
125        /**
126         * Solve for a zero in the given interval, start at startValue.
127         * <p>A solver may require that the interval brackets a single zero root.
128         * Solvers that do require bracketing should be able to handle the case
129         * where one of the endpoints is itself a root.</p>
130         *
131         * @param f the function to solve.
132         * @param min the lower bound for the interval.
133         * @param max the upper bound for the interval.
134         * @param startValue the start value to use
135         * @return a value where the function is zero
136         * @throws ConvergenceException if the maximum iteration count is exceeded
137         * or the solver detects convergence problems otherwise.
138         * @throws FunctionEvaluationException if an error occurs evaluating the function
139         * @throws IllegalArgumentException if min > max or the arguments do not
140         * satisfy the requirements specified by the solver
141         * @since 2.0
142         * @deprecated in 2.2 (to be removed in 3.0).
143         */
144        @Deprecated
145        double solve(UnivariateRealFunction f, double min, double max, double startValue)
146            throws ConvergenceException, FunctionEvaluationException, IllegalArgumentException;
147    
148        /**
149         * Get the result of the last run of the solver.
150         *
151         * @return the last result.
152         * @throws IllegalStateException if there is no result available, either
153         * because no result was yet computed or the last attempt failed.
154         */
155        double getResult();
156    
157        /**
158         * Get the result of the last run of the solver.
159         *
160         * @return the value of the function at the last result.
161         * @throws IllegalStateException if there is no result available, either
162         * because no result was yet computed or the last attempt failed.
163         */
164        double getFunctionValue();
165    }