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.core.RealFieldElement; 21 import org.apache.commons.math4.legacy.analysis.RealFieldUnivariateFunction; 22 23 /** Interface for {@link UnivariateSolver (univariate real) root-finding 24 * algorithms} that maintain a bracketed solution. There are several advantages 25 * to having such root-finding algorithms: 26 * <ul> 27 * <li>The bracketed solution guarantees that the root is kept within the 28 * interval. As such, these algorithms generally also guarantee 29 * convergence.</li> 30 * <li>The bracketed solution means that we have the opportunity to only 31 * return roots that are greater than or equal to the actual root, or 32 * are less than or equal to the actual root. That is, we can control 33 * whether under-approximations and over-approximations are 34 * {@link AllowedSolution allowed solutions}. Other root-finding 35 * algorithms can usually only guarantee that the solution (the root that 36 * was found) is around the actual root.</li> 37 * </ul> 38 * 39 * <p>For backwards compatibility, all root-finding algorithms must have 40 * {@link AllowedSolution#ANY_SIDE ANY_SIDE} as default for the allowed 41 * solutions.</p> 42 * 43 * @see AllowedSolution 44 * @param <T> the type of the field elements 45 * @since 3.6 46 */ 47 public interface BracketedRealFieldUnivariateSolver<T extends RealFieldElement<T>> { 48 49 /** 50 * Get the maximum number of function evaluations. 51 * 52 * @return the maximum number of function evaluations. 53 */ 54 int getMaxEvaluations(); 55 56 /** 57 * Get the number of evaluations of the objective function. 58 * The number of evaluations corresponds to the last call to the 59 * {@code optimize} method. It is 0 if the method has not been 60 * called yet. 61 * 62 * @return the number of evaluations of the objective function. 63 */ 64 int getEvaluations(); 65 66 /** 67 * Get the absolute accuracy of the solver. Solutions returned by the 68 * solver should be accurate to this tolerance, i.e., if ε is the 69 * absolute accuracy of the solver and {@code v} is a value returned by 70 * one of the {@code solve} methods, then a root of the function should 71 * exist somewhere in the interval ({@code v} - ε, {@code v} + ε). 72 * 73 * @return the absolute accuracy. 74 */ 75 T getAbsoluteAccuracy(); 76 77 /** 78 * Get the relative accuracy of the solver. The contract for relative 79 * accuracy is the same as {@link #getAbsoluteAccuracy()}, but using 80 * relative, rather than absolute error. If ρ is the relative accuracy 81 * configured for a solver and {@code v} is a value returned, then a root 82 * of the function should exist somewhere in the interval 83 * ({@code v} - ρ {@code v}, {@code v} + ρ {@code v}). 84 * 85 * @return the relative accuracy. 86 */ 87 T getRelativeAccuracy(); 88 89 /** 90 * Get the function value accuracy of the solver. If {@code v} is 91 * a value returned by the solver for a function {@code f}, 92 * then by contract, {@code |f(v)|} should be less than or equal to 93 * the function value accuracy configured for the solver. 94 * 95 * @return the function value accuracy. 96 */ 97 T getFunctionValueAccuracy(); 98 99 /** 100 * Solve for a zero in the given interval. 101 * A solver may require that the interval brackets a single zero root. 102 * Solvers that do require bracketing should be able to handle the case 103 * where one of the endpoints is itself a root. 104 * 105 * @param maxEval Maximum number of evaluations. 106 * @param f Function to solve. 107 * @param min Lower bound for the interval. 108 * @param max Upper bound for the interval. 109 * @param allowedSolution The kind of solutions that the root-finding algorithm may 110 * accept as solutions. 111 * @return A value where the function is zero. 112 * @throws org.apache.commons.math4.legacy.exception.MathIllegalArgumentException 113 * if the arguments do not satisfy the requirements specified by the solver. 114 * @throws org.apache.commons.math4.legacy.exception.TooManyEvaluationsException if 115 * the allowed number of evaluations is exceeded. 116 */ 117 T solve(int maxEval, RealFieldUnivariateFunction<T> f, T min, T max, 118 AllowedSolution allowedSolution); 119 120 /** 121 * Solve for a zero in the given interval, start at {@code startValue}. 122 * A solver may require that the interval brackets a single zero root. 123 * Solvers that do require bracketing should be able to handle the case 124 * where one of the endpoints is itself a root. 125 * 126 * @param maxEval Maximum number of evaluations. 127 * @param f Function to solve. 128 * @param min Lower bound for the interval. 129 * @param max Upper bound for the interval. 130 * @param startValue Start value to use. 131 * @param allowedSolution The kind of solutions that the root-finding algorithm may 132 * accept as solutions. 133 * @return A value where the function is zero. 134 * @throws org.apache.commons.math4.legacy.exception.MathIllegalArgumentException 135 * if the arguments do not satisfy the requirements specified by the solver. 136 * @throws org.apache.commons.math4.legacy.exception.TooManyEvaluationsException if 137 * the allowed number of evaluations is exceeded. 138 */ 139 T solve(int maxEval, RealFieldUnivariateFunction<T> f, T min, T max, T startValue, 140 AllowedSolution allowedSolution); 141 }