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 018package org.apache.commons.math3.analysis.solvers; 019 020import 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 */ 047public 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}