1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 package org.apache.commons.math4.legacy.analysis.solvers; 19 20 import org.apache.commons.math4.legacy.analysis.UnivariateFunction; 21 22 /** Interface for {@link UnivariateSolver (univariate real) root-finding 23 * algorithms} that maintain a bracketed solution. There are several advantages 24 * to having such root-finding algorithms: 25 * <ul> 26 * <li>The bracketed solution guarantees that the root is kept within the 27 * interval. As such, these algorithms generally also guarantee 28 * convergence.</li> 29 * <li>The bracketed solution means that we have the opportunity to only 30 * return roots that are greater than or equal to the actual root, or 31 * are less than or equal to the actual root. That is, we can control 32 * whether under-approximations and over-approximations are 33 * {@link AllowedSolution allowed solutions}. Other root-finding 34 * algorithms can usually only guarantee that the solution (the root that 35 * was found) is around the actual root.</li> 36 * </ul> 37 * 38 * <p>For backwards compatibility, all root-finding algorithms must have 39 * {@link AllowedSolution#ANY_SIDE ANY_SIDE} as default for the allowed 40 * solutions.</p> 41 * @param <FUNC> Type of function to solve. 42 * 43 * @see AllowedSolution 44 * @since 3.0 45 */ 46 public interface BracketedUnivariateSolver<FUNC extends UnivariateFunction> 47 extends BaseUnivariateSolver<FUNC> { 48 49 /** 50 * Solve for a zero in the given interval. 51 * A solver may require that the interval brackets a single zero root. 52 * Solvers that do require bracketing should be able to handle the case 53 * where one of the endpoints is itself a root. 54 * 55 * @param maxEval Maximum number of evaluations. 56 * @param f Function to solve. 57 * @param min Lower bound for the interval. 58 * @param max Upper bound for the interval. 59 * @param allowedSolution The kind of solutions that the root-finding algorithm may 60 * accept as solutions. 61 * @return A value where the function is zero. 62 * @throws org.apache.commons.math4.legacy.exception.MathIllegalArgumentException 63 * if the arguments do not satisfy the requirements specified by the solver. 64 * @throws org.apache.commons.math4.legacy.exception.TooManyEvaluationsException if 65 * the allowed number of evaluations is exceeded. 66 */ 67 double solve(int maxEval, FUNC f, double min, double max, 68 AllowedSolution allowedSolution); 69 70 /** 71 * Solve for a zero in the given interval, start at {@code startValue}. 72 * A solver may require that the interval brackets a single zero root. 73 * Solvers that do require bracketing should be able to handle the case 74 * where one of the endpoints is itself a root. 75 * 76 * @param maxEval Maximum number of evaluations. 77 * @param f Function to solve. 78 * @param min Lower bound for the interval. 79 * @param max Upper bound for the interval. 80 * @param startValue Start value to use. 81 * @param allowedSolution The kind of solutions that the root-finding algorithm may 82 * accept as solutions. 83 * @return A value where the function is zero. 84 * @throws org.apache.commons.math4.legacy.exception.MathIllegalArgumentException 85 * if the arguments do not satisfy the requirements specified by the solver. 86 * @throws org.apache.commons.math4.legacy.exception.TooManyEvaluationsException if 87 * the allowed number of evaluations is exceeded. 88 */ 89 double solve(int maxEval, FUNC f, double min, double max, double startValue, 90 AllowedSolution allowedSolution); 91 }