    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    }