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.RealFieldElement; 021import org.apache.commons.math3.analysis.RealFieldUnivariateFunction; 022 023/** Interface for {@link UnivariateSolver (univariate real) root-finding 024 * algorithms} that maintain a bracketed solution. There are several advantages 025 * to having such root-finding algorithms: 026 * <ul> 027 * <li>The bracketed solution guarantees that the root is kept within the 028 * interval. As such, these algorithms generally also guarantee 029 * convergence.</li> 030 * <li>The bracketed solution means that we have the opportunity to only 031 * return roots that are greater than or equal to the actual root, or 032 * are less than or equal to the actual root. That is, we can control 033 * whether under-approximations and over-approximations are 034 * {@link AllowedSolution allowed solutions}. Other root-finding 035 * algorithms can usually only guarantee that the solution (the root that 036 * was found) is around the actual root.</li> 037 * </ul> 038 * 039 * <p>For backwards compatibility, all root-finding algorithms must have 040 * {@link AllowedSolution#ANY_SIDE ANY_SIDE} as default for the allowed 041 * solutions.</p> 042 * 043 * @see AllowedSolution 044 * @param <T> the type of the field elements 045 * @since 3.6 046 */ 047public interface BracketedRealFieldUnivariateSolver<T extends RealFieldElement<T>> { 048 049 /** 050 * Get the maximum number of function evaluations. 051 * 052 * @return the maximum number of function evaluations. 053 */ 054 int getMaxEvaluations(); 055 056 /** 057 * Get the number of evaluations of the objective function. 058 * The number of evaluations corresponds to the last call to the 059 * {@code optimize} method. It is 0 if the method has not been 060 * called yet. 061 * 062 * @return the number of evaluations of the objective function. 063 */ 064 int getEvaluations(); 065 066 /** 067 * Get the absolute accuracy of the solver. Solutions returned by the 068 * solver should be accurate to this tolerance, i.e., if ε is the 069 * absolute accuracy of the solver and {@code v} is a value returned by 070 * one of the {@code solve} methods, then a root of the function should 071 * exist somewhere in the interval ({@code v} - ε, {@code v} + ε). 072 * 073 * @return the absolute accuracy. 074 */ 075 T getAbsoluteAccuracy(); 076 077 /** 078 * Get the relative accuracy of the solver. The contract for relative 079 * accuracy is the same as {@link #getAbsoluteAccuracy()}, but using 080 * relative, rather than absolute error. If ρ is the relative accuracy 081 * configured for a solver and {@code v} is a value returned, then a root 082 * of the function should exist somewhere in the interval 083 * ({@code v} - ρ {@code v}, {@code v} + ρ {@code v}). 084 * 085 * @return the relative accuracy. 086 */ 087 T getRelativeAccuracy(); 088 089 /** 090 * Get the function value accuracy of the solver. If {@code v} is 091 * a value returned by the solver for a function {@code f}, 092 * then by contract, {@code |f(v)|} should be less than or equal to 093 * the function value accuracy configured for the solver. 094 * 095 * @return the function value accuracy. 096 */ 097 T getFunctionValueAccuracy(); 098 099 /** 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.math3.exception.MathIllegalArgumentException 113 * if the arguments do not satisfy the requirements specified by the solver. 114 * @throws org.apache.commons.math3.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.math3.exception.MathIllegalArgumentException 135 * if the arguments do not satisfy the requirements specified by the solver. 136 * @throws org.apache.commons.math3.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 142}