    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
    018    package org.apache.commons.math3.analysis.solvers;
    019
    020    import org.apache.commons.math3.analysis.UnivariateFunction;
    021
    022    /** Interface for {@link UnivariateSolver (univariate real) root-finding
    023     * algorithms} that maintain a bracketed solution. There are several advantages
    024     * to having such root-finding algorithms:
    025     * <ul>
    026     *  <li>The bracketed solution guarantees that the root is kept within the
    027     *      interval. As such, these algorithms generally also guarantee
    028     *      convergence.</li>
    029     *  <li>The bracketed solution means that we have the opportunity to only
    030     *      return roots that are greater than or equal to the actual root, or
    031     *      are less than or equal to the actual root. That is, we can control
    032     *      whether under-approximations and over-approximations are
    033     *      {@link AllowedSolution allowed solutions}. Other root-finding
    034     *      algorithms can usually only guarantee that the solution (the root that
    035     *      was found) is around the actual root.</li>
    036     * </ul>
    037     *
    038     * <p>For backwards compatibility, all root-finding algorithms must have
    039     * {@link AllowedSolution#ANY_SIDE ANY_SIDE} as default for the allowed
    040     * solutions.</p>
    041     * @param <FUNC> Type of function to solve.
    042     *
    043     * @see AllowedSolution
    044     * @since 3.0
    045     * @version $Id: BracketedUnivariateSolver.java 1364387 2012-07-22 18:14:11Z tn $
    046     */
    047    public interface BracketedUnivariateSolver<FUNC extends UnivariateFunction>
    048        extends BaseUnivariateSolver<FUNC> {
    049
    050        /**
    051         * Solve for a zero in the given interval.
    052         * A solver may require that the interval brackets a single zero root.
    053         * Solvers that do require bracketing should be able to handle the case
    054         * where one of the endpoints is itself a root.
    055         *
    056         * @param maxEval Maximum number of evaluations.
    057         * @param f Function to solve.
    058         * @param min Lower bound for the interval.
    059         * @param max Upper bound for the interval.
    060         * @param allowedSolution The kind of solutions that the root-finding algorithm may
    061         * accept as solutions.
    062         * @return A value where the function is zero.
    063         * @throws org.apache.commons.math3.exception.MathIllegalArgumentException
    064         * if the arguments do not satisfy the requirements specified by the solver.
    065         * @throws org.apache.commons.math3.exception.TooManyEvaluationsException if
    066         * the allowed number of evaluations is exceeded.
    067         */
    068        double solve(int maxEval, FUNC f, double min, double max,
    069                     AllowedSolution allowedSolution);
    070
    071        /**
    072         * Solve for a zero in the given interval, start at {@code startValue}.
    073         * A solver may require that the interval brackets a single zero root.
    074         * Solvers that do require bracketing should be able to handle the case
    075         * where one of the endpoints is itself a root.
    076         *
    077         * @param maxEval Maximum number of evaluations.
    078         * @param f Function to solve.
    079         * @param min Lower bound for the interval.
    080         * @param max Upper bound for the interval.
    081         * @param startValue Start value to use.
    082         * @param allowedSolution The kind of solutions that the root-finding algorithm may
    083         * accept as solutions.
    084         * @return A value where the function is zero.
    085         * @throws org.apache.commons.math3.exception.MathIllegalArgumentException
    086         * if the arguments do not satisfy the requirements specified by the solver.
    087         * @throws org.apache.commons.math3.exception.TooManyEvaluationsException if
    088         * the allowed number of evaluations is exceeded.
    089         */
    090        double solve(int maxEval, FUNC f, double min, double max, double startValue,
    091                     AllowedSolution allowedSolution);
    092
    093    }