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 */ 046public interface BracketedUnivariateSolver<FUNC extends UnivariateFunction> 047 extends BaseUnivariateSolver<FUNC> { 048 049 /** 050 * Solve for a zero in the given interval. 051 * A solver may require that the interval brackets a single zero root. 052 * Solvers that do require bracketing should be able to handle the case 053 * where one of the endpoints is itself a root. 054 * 055 * @param maxEval Maximum number of evaluations. 056 * @param f Function to solve. 057 * @param min Lower bound for the interval. 058 * @param max Upper bound for the interval. 059 * @param allowedSolution The kind of solutions that the root-finding algorithm may 060 * accept as solutions. 061 * @return A value where the function is zero. 062 * @throws org.apache.commons.math3.exception.MathIllegalArgumentException 063 * if the arguments do not satisfy the requirements specified by the solver. 064 * @throws org.apache.commons.math3.exception.TooManyEvaluationsException if 065 * the allowed number of evaluations is exceeded. 066 */ 067 double solve(int maxEval, FUNC f, double min, double max, 068 AllowedSolution allowedSolution); 069 070 /** 071 * Solve for a zero in the given interval, start at {@code startValue}. 072 * A solver may require that the interval brackets a single zero root. 073 * Solvers that do require bracketing should be able to handle the case 074 * where one of the endpoints is itself a root. 075 * 076 * @param maxEval Maximum number of evaluations. 077 * @param f Function to solve. 078 * @param min Lower bound for the interval. 079 * @param max Upper bound for the interval. 080 * @param startValue Start value to use. 081 * @param allowedSolution The kind of solutions that the root-finding algorithm may 082 * accept as solutions. 083 * @return A value where the function is zero. 084 * @throws org.apache.commons.math3.exception.MathIllegalArgumentException 085 * if the arguments do not satisfy the requirements specified by the solver. 086 * @throws org.apache.commons.math3.exception.TooManyEvaluationsException if 087 * the allowed number of evaluations is exceeded. 088 */ 089 double solve(int maxEval, FUNC f, double min, double max, double startValue, 090 AllowedSolution allowedSolution); 091 092}