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: 799857 $ $Date: 2009-08-01 09:07:12 -0400 (Sat, 01 Aug 2009) $
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
073         * function
074         * @throws IllegalArgumentException if min > max or the endpoints do not
075         * satisfy the requirements specified by the solver
076         * @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double)}
077         * since 2.0
078         */
079        @Deprecated
080        double solve(double min, double max) throws ConvergenceException, 
081            FunctionEvaluationException;
082    
083        /**
084         * Solve for a zero root in the given interval.
085         * <p>A solver may require that the interval brackets a single zero root.
086         * Solvers that do require bracketing should be able to handle the case
087         * where one of the endpoints is itself a root.</p>
088         * 
089         * @param f the function to solve.
090         * @param min the lower bound for the interval.
091         * @param max the upper bound for the interval.
092         * @return a value where the function is zero
093         * @throws ConvergenceException if the maximum iteration count is exceeded
094         * or the solver detects convergence problems otherwise.
095         * @throws FunctionEvaluationException if an error occurs evaluating the
096         * function
097         * @throws IllegalArgumentException if min > max or the endpoints do not
098         * satisfy the requirements specified by the solver
099         * @since 2.0
100         */
101        double solve(UnivariateRealFunction f, double min, double max)
102            throws ConvergenceException, 
103            FunctionEvaluationException;
104    
105        /**
106         * Solve for a zero in the given interval, start at startValue.
107         * <p>A solver may require that the interval brackets a single zero root.
108         * Solvers that do require bracketing should be able to handle the case
109         * where one of the endpoints is itself a root.</p>
110         * 
111         * @param min the lower bound for the interval.
112         * @param max the upper bound for the interval.
113         * @param startValue the start value to use
114         * @return a value where the function is zero
115         * @throws ConvergenceException if the maximum iteration count is exceeded
116         * or the solver detects convergence problems otherwise.
117         * @throws FunctionEvaluationException if an error occurs evaluating the
118         * function
119         * @throws IllegalArgumentException if min > max or the arguments do not
120         * satisfy the requirements specified by the solver
121         * @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double, double)}
122         * since 2.0
123         */
124        @Deprecated
125        double solve(double min, double max, double startValue)
126            throws ConvergenceException, FunctionEvaluationException, IllegalArgumentException;
127    
128        /**
129         * Solve for a zero in the given interval, start at startValue.
130         * <p>A solver may require that the interval brackets a single zero root.
131         * Solvers that do require bracketing should be able to handle the case
132         * where one of the endpoints is itself a root.</p>
133         * 
134         * @param f the function to solve.
135         * @param min the lower bound for the interval.
136         * @param max the upper bound for the interval.
137         * @param startValue the start value to use
138         * @return a value where the function is zero
139         * @throws ConvergenceException if the maximum iteration count is exceeded
140         * or the solver detects convergence problems otherwise.
141         * @throws FunctionEvaluationException if an error occurs evaluating the
142         * function
143         * @throws IllegalArgumentException if min > max or the arguments do not
144         * satisfy the requirements specified by the solver
145         * @since 2.0
146         */
147        double solve(UnivariateRealFunction f, double min, double max, double startValue)
148            throws ConvergenceException, FunctionEvaluationException, IllegalArgumentException;
149    
150        /**
151         * Get the result of the last run of the solver.
152         * 
153         * @return the last result.
154         * @throws IllegalStateException if there is no result available, either
155         * because no result was yet computed or the last attempt failed.
156         */
157        double getResult();
158    
159        /**
160         * Get the result of the last run of the solver.
161         * 
162         * @return the value of the function at the last result.
163         * @throws IllegalStateException if there is no result available, either
164         * because no result was yet computed or the last attempt failed.
165         */
166        double getFunctionValue();
167    }