    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.math3.analysis.solvers;
    018
    019    import org.apache.commons.math3.analysis.UnivariateFunction;
    020
    021
    022    /**
    023     * Interface for (univariate real) rootfinding algorithms.
    024     * Implementations will search for only one zero in the given interval.
    025     *
    026     * This class is not intended for use outside of the Apache Commons Math
    027     * library, regular user should rely on more specific interfaces like
    028     * {@link UnivariateSolver}, {@link PolynomialSolver} or {@link
    029     * DifferentiableUnivariateSolver}.
    030     * @param <FUNC> Type of function to solve.
    031     *
    032     * @since 3.0
    033     * @version $Id: BaseUnivariateSolver.java 1364387 2012-07-22 18:14:11Z tn $
    034     * @see UnivariateSolver
    035     * @see PolynomialSolver
    036     * @see DifferentiableUnivariateSolver
    037     */
    038    public interface BaseUnivariateSolver<FUNC extends UnivariateFunction> {
    039        /**
    040         * Get the maximum number of function evaluations.
    041         *
    042         * @return the maximum number of function evaluations.
    043         */
    044        int getMaxEvaluations();
    045
    046        /**
    047         * Get the number of evaluations of the objective function.
    048         * The number of evaluations corresponds to the last call to the
    049         * {@code optimize} method. It is 0 if the method has not been
    050         * called yet.
    051         *
    052         * @return the number of evaluations of the objective function.
    053         */
    054        int getEvaluations();
    055
    056        /**
    057         * Get the absolute accuracy of the solver.  Solutions returned by the
    058         * solver should be accurate to this tolerance, i.e., if &epsilon; is the
    059         * absolute accuracy of the solver and {@code v} is a value returned by
    060         * one of the {@code solve} methods, then a root of the function should
    061         * exist somewhere in the interval ({@code v} - &epsilon;, {@code v} + &epsilon;).
    062         *
    063         * @return the absolute accuracy.
    064         */
    065        double getAbsoluteAccuracy();
    066
    067        /**
    068         * Get the relative accuracy of the solver.  The contract for relative
    069         * accuracy is the same as {@link #getAbsoluteAccuracy()}, but using
    070         * relative, rather than absolute error.  If &rho; is the relative accuracy
    071         * configured for a solver and {@code v} is a value returned, then a root
    072         * of the function should exist somewhere in the interval
    073         * ({@code v} - &rho; {@code v}, {@code v} + &rho; {@code v}).
    074         *
    075         * @return the relative accuracy.
    076         */
    077        double getRelativeAccuracy();
    078
    079        /**
    080         * Get the function value accuracy of the solver.  If {@code v} is
    081         * a value returned by the solver for a function {@code f},
    082         * then by contract, {@code |f(v)|} should be less than or equal to
    083         * the function value accuracy configured for the solver.
    084         *
    085         * @return the function value accuracy.
    086         */
    087        double getFunctionValueAccuracy();
    088
    089        /**
    090         * Solve for a zero root in the given interval.
    091         * A solver may require that the interval brackets a single zero root.
    092         * Solvers that do require bracketing should be able to handle the case
    093         * where one of the endpoints is itself a root.
    094         *
    095         * @param maxEval Maximum number of evaluations.
    096         * @param f Function to solve.
    097         * @param min Lower bound for the interval.
    098         * @param max Upper bound for the interval.
    099         * @return a value where the function is zero.
    100         * @throws org.apache.commons.math3.exception.MathIllegalArgumentException
    101         * if the arguments do not satisfy the requirements specified by the solver.
    102         * @throws org.apache.commons.math3.exception.TooManyEvaluationsException if
    103         * the allowed number of evaluations is exceeded.
    104         */
    105        double solve(int maxEval, FUNC f, double min, double max);
    106
    107        /**
    108         * Solve for a zero in the given interval, start at {@code startValue}.
    109         * A solver may require that the interval brackets a single zero root.
    110         * Solvers that do require bracketing should be able to handle the case
    111         * where one of the endpoints is itself a root.
    112         *
    113         * @param maxEval Maximum number of evaluations.
    114         * @param f Function to solve.
    115         * @param min Lower bound for the interval.
    116         * @param max Upper bound for the interval.
    117         * @param startValue Start value to use.
    118         * @return a value where the function is zero.
    119         * @throws org.apache.commons.math3.exception.MathIllegalArgumentException
    120         * if the arguments do not satisfy the requirements specified by the solver.
    121         * @throws org.apache.commons.math3.exception.TooManyEvaluationsException if
    122         * the allowed number of evaluations is exceeded.
    123         */
    124        double solve(int maxEval, FUNC f, double min, double max, double startValue);
    125
    126        /**
    127         * Solve for a zero in the vicinity of {@code startValue}.
    128         *
    129         * @param f Function to solve.
    130         * @param startValue Start value to use.
    131         * @return a value where the function is zero.
    132         * @param maxEval Maximum number of evaluations.
    133         * @throws org.apache.commons.math3.exception.MathIllegalArgumentException
    134         * if the arguments do not satisfy the requirements specified by the solver.
    135         * @throws org.apache.commons.math3.exception.TooManyEvaluationsException if
    136         * the allowed number of evaluations is exceeded.
    137         */
    138        double solve(int maxEval, FUNC f, double startValue);
    139    }