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