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    }