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 */ 017package org.apache.commons.math3.analysis.solvers; 018 019import org.apache.commons.math3.analysis.UnivariateFunction; 020import org.apache.commons.math3.exception.MathIllegalArgumentException; 021import org.apache.commons.math3.exception.TooManyEvaluationsException; 022 023 024/** 025 * Interface for (univariate real) rootfinding algorithms. 026 * Implementations will search for only one zero in the given interval. 027 * 028 * This class is not intended for use outside of the Apache Commons Math 029 * library, regular user should rely on more specific interfaces like 030 * {@link UnivariateSolver}, {@link PolynomialSolver} or {@link 031 * DifferentiableUnivariateSolver}. 032 * @param <FUNC> Type of function to solve. 033 * 034 * @since 3.0 035 * @see UnivariateSolver 036 * @see PolynomialSolver 037 * @see DifferentiableUnivariateSolver 038 */ 039public interface BaseUnivariateSolver<FUNC extends UnivariateFunction> { 040 /** 041 * Get the maximum number of function evaluations. 042 * 043 * @return the maximum number of function evaluations. 044 */ 045 int getMaxEvaluations(); 046 047 /** 048 * Get the number of evaluations of the objective function. 049 * The number of evaluations corresponds to the last call to the 050 * {@code optimize} method. It is 0 if the method has not been 051 * called yet. 052 * 053 * @return the number of evaluations of the objective function. 054 */ 055 int getEvaluations(); 056 057 /** 058 * Get the absolute accuracy of the solver. Solutions returned by the 059 * solver should be accurate to this tolerance, i.e., if ε is the 060 * absolute accuracy of the solver and {@code v} is a value returned by 061 * one of the {@code solve} methods, then a root of the function should 062 * exist somewhere in the interval ({@code v} - ε, {@code v} + ε). 063 * 064 * @return the absolute accuracy. 065 */ 066 double getAbsoluteAccuracy(); 067 068 /** 069 * Get the relative accuracy of the solver. The contract for relative 070 * accuracy is the same as {@link #getAbsoluteAccuracy()}, but using 071 * relative, rather than absolute error. If ρ is the relative accuracy 072 * configured for a solver and {@code v} is a value returned, then a root 073 * of the function should exist somewhere in the interval 074 * ({@code v} - ρ {@code v}, {@code v} + ρ {@code v}). 075 * 076 * @return the relative accuracy. 077 */ 078 double getRelativeAccuracy(); 079 080 /** 081 * Get the function value accuracy of the solver. If {@code v} is 082 * a value returned by the solver for a function {@code f}, 083 * then by contract, {@code |f(v)|} should be less than or equal to 084 * the function value accuracy configured for the solver. 085 * 086 * @return the function value accuracy. 087 */ 088 double getFunctionValueAccuracy(); 089 090 /** 091 * Solve for a zero root in the given interval. 092 * A solver may require that the interval brackets a single zero root. 093 * Solvers that do require bracketing should be able to handle the case 094 * where one of the endpoints is itself a root. 095 * 096 * @param maxEval Maximum number of evaluations. 097 * @param f Function to solve. 098 * @param min Lower bound for the interval. 099 * @param max Upper bound for the interval. 100 * @return a value where the function is zero. 101 * @throws MathIllegalArgumentException 102 * if the arguments do not satisfy the requirements specified by the solver. 103 * @throws TooManyEvaluationsException if 104 * the allowed number of evaluations is exceeded. 105 */ 106 double solve(int maxEval, FUNC f, double min, double max) 107 throws MathIllegalArgumentException, TooManyEvaluationsException; 108 109 /** 110 * Solve for a zero in the given interval, start at {@code startValue}. 111 * A solver may require that the interval brackets a single zero root. 112 * Solvers that do require bracketing should be able to handle the case 113 * where one of the endpoints is itself a root. 114 * 115 * @param maxEval Maximum number of evaluations. 116 * @param f Function to solve. 117 * @param min Lower bound for the interval. 118 * @param max Upper bound for the interval. 119 * @param startValue Start value to use. 120 * @return a value where the function is zero. 121 * @throws MathIllegalArgumentException 122 * if the arguments do not satisfy the requirements specified by the solver. 123 * @throws TooManyEvaluationsException if 124 * the allowed number of evaluations is exceeded. 125 */ 126 double solve(int maxEval, FUNC f, double min, double max, double startValue) 127 throws MathIllegalArgumentException, TooManyEvaluationsException; 128 129 /** 130 * Solve for a zero in the vicinity of {@code startValue}. 131 * 132 * @param f Function to solve. 133 * @param startValue Start value to use. 134 * @return a value where the function is zero. 135 * @param maxEval Maximum number of evaluations. 136 * @throws org.apache.commons.math3.exception.MathIllegalArgumentException 137 * if the arguments do not satisfy the requirements specified by the solver. 138 * @throws org.apache.commons.math3.exception.TooManyEvaluationsException if 139 * the allowed number of evaluations is exceeded. 140 */ 141 double solve(int maxEval, FUNC f, double startValue); 142}