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